{
    "info": {
        "author": "Piotr Kuszaj",
        "author_email": "peterkuszaj@gmail.com",
        "bugtrack_url": null,
        "classifiers": [
            "Development Status :: 3 - Alpha",
            "Environment :: Other Environment",
            "Environment :: Web Environment",
            "Intended Audience :: Developers",
            "Intended Audience :: Financial and Insurance Industry",
            "License :: OSI Approved :: MIT License",
            "Operating System :: OS Independent",
            "Programming Language :: Python :: 3",
            "Programming Language :: Python :: 3.3",
            "Programming Language :: Python :: 3.4",
            "Programming Language :: Python :: 3.5",
            "Programming Language :: Python :: 3.6",
            "Topic :: Office/Business :: Financial :: Accounting",
            "Topic :: Software Development :: Libraries :: Python Modules",
            "Topic :: Utilities"
        ],
        "description": "NPBy\n====\n\n.. image:: https://travis-ci.org/kuszaj/nbpy.svg?branch=master\n    :target: https://travis-ci.org/kuszaj/nbpy\n\nA utility package for calling `NBP (Polish National Bank) Web API <http://api.nbp.pl/en.html>`_ and converting various currencies to Polish zloty using its exchange rates.\n\nNBPy requires Python 3.3 or newer\n\nInstallation\n------------\n\nFrom PyPI:\n\n.. code:: shell\n\n    $ pip3 install nbpy\n\nFrom source code:\n\n.. code:: shell\n\n    $ git clone https://github.com/kuszaj/nbpy\n    $ cd nbpy\n    $ python3 setup.py install\n\nUsage\n-----\n\nNBPy provides a ``NBPClient`` class for generating API callers, given available currency code:\n\n.. code:: python\n\n    >>> import nbpy\n    >>> #: Available currencies\n    >>> nbpy.currencies\n    {'EUR': NBPCurrency(Euro, code=EUR, tables={'A', 'C'}), 'USD': NBPCurrency(United States dollar, code=USD, tables={'A', 'C'}), ...}\n    >>> nbp = nbpy.NBPClient('eur')\n    >>> nbp\n    NBPClient(USD, as_float=False, suppress_errors=False, cache_size=128)\n    >>> nbp.currency_code = 'EUR'\n    >>> nbp\n    NBPClient(EUR, as_float=False, suppress_errors=False, cache_size=128)\n\n``currency_code`` has to be one of the available codes from ``nbpy.currencies`` otherwise ``NBPClient`` raises ``UnknownCurrencyCode``.\n\n.. code:: python\n\n    >>> from nbpy.errors import UnknownCurrencyCode\n    >>> 'XYZ' in nbpy.currencies\n    False\n    >>> try:\n    ...     nbp.currency_code = 'XYZ'\n    ... except UnknownCurrencyCode:\n    ...     print('XYZ is unknown')\n    ...\n    XYZ is unknown\n\nAPI calls\n~~~~~~~~~\n\nAll API calls defined in ``NBPClient`` returns either a ``NBPExchangeRate`` object or a list its instances.\n\n``.current()`` returns current exchange rate for currency. Note that it doesn't necessarily mean current day: for weekends, holidays and before official announcements by Polish National Bank method returns last available value.\n\n.. code:: python\n\n    >>> nbp.current()\n    NBPExchangeRate(EUR->PLN, 2017-10-31, mid=4.2498)\n    >>> #: Calling NBPClient object is synonymous with current()\n    >>> nbp()\n    NBPExchangeRate(EUR->PLN, 2017-10-31, mid=4.2498)\n\n``.today()`` returns exchange rate for current day, if available.\nOtherwise, raises ``APIError``.\n\n.. code:: python\n\n    >>> nbp.today()\n    NBPExchangeRate(EUR->PLN, 2017-10-31, mid=4.2498)\n    ...\n    >>> #: A day later, during national holiday\n    >>> from nbpy.errors import APIError\n    >>> try:\n    ...     nbp.today()\n    ... except APIError:\n    ...     print(\"No data available\")\n    ...\n    No data available\n\n``.date(date)`` returns exchange rate for given day, if available. Otherwise, raises ``APIError``. Argument ``date`` has to be either ``datetime.datetime`` or a properly formatted date string (``YYYY-MM-DD``), otherwise method raises ``DateFormattingError``.\n\n.. code:: python\n\n    >>> from nbpy.errors import APIError, DateFormattingError\n    >>> nbp.date('2017-10-02')\n    NBPExchangeRate(EUR->PLN, 2017-10-02, mid=4.3137)\n    >>> try:\n    ...     nbp.date('2017-10-01')\n    ... except APIError:\n    ...     print(\"No data available for date\")\n    ...\n    No data available for date\n    >>> try:\n    ...     nbp.date('01/10/17')\n    ... except DateFormattingError:\n    ...     print(\"Improperly formatted date string\")\n    ...\n    Improperly formatted date string\n\n``.last(n)`` returns last ``n`` available exchange rates, ordered by date in ascending order.\n\n.. code:: python\n\n    >>> nbp.last(3)\n    [NBPExchangeRate(EUR->PLN, 2017-10-27, mid=4.2520),\n     NBPExchangeRate(EUR->PLN, 2017-10-30, mid=4.2403),\n     NBPExchangeRate(EUR->PLN, 2017-10-31, mid=4.2498)]\n\n``.date_range(start_date, end_date)`` returns exchange rates for given date range ``[start_date, end_date]``, ordered by date in ascending order. Both arguments are restricted in the same way as ``date`` for ``date()`` method.\n\nIf range covers more than 93 days, method raises ``APIError``.\n\n.. code:: python\n\n    >>> from nbp.errors import APIError\n    >>> nbp.date_range('2017-10-01', '2017-10-14')\n    [NBPExchangeRate(EUR->PLN, 2017-10-02, mid=4.3137),\n     NBPExchangeRate(EUR->PLN, 2017-10-03, mid=4.3105),\n     NBPExchangeRate(EUR->PLN, 2017-10-04, mid=4.3025), ...]\n    >>> try:\n    ...     nbp.date_range('2017-01-01', '2017-06-01')\n    ... except APIError:\n    ...     print('Invalid date range')\n    ...\n    Invalid date range\n\nBid/ask rates\n^^^^^^^^^^^^^\n\nBy default all API call methods return average exchange rate (``mid``). However, by passing ``bid_ask=True`` you can additionally get bid/ask values. Not that not every currency has them available: for such case ``bid_ask`` is ignored.\n\n.. code:: python\n\n    >>> nbp()\n    NBPExchangeRate(EUR->PLN, 2017-10-31, mid=4.2498)\n    >>> nbp(bid_ask=True)\n    NBPExchangeRate(EUR->PLN, 2017-11-02, bid=4.2036, ask=4.2886)\n    >>> #: No bid/ask values for CUP\n    >>> nbp.currency_code = 'CUP'\n    >>> nbp()\n    NBPExchangeRate(CUP->PLN, 2017-10-31, mid=3.6529)\n    >>> from nbpy.errors import BidAskUnavailable\n    >>> try:\n    ...     nbp(bid_ask=True)\n    ... except BidAskUnavailable:\n    ...     print('Bid/ask unavailable')\n    ...\n    Bid/ask unavailable\n\nSuppressing errors\n~~~~~~~~~~~~~~~~~~\n\nIf you want API calls to always return something, despite possible issues with API, you can pass ``suppress_errors=True`` to ``NBPClient``. With this flag turned on API calls instead of raising ``BidAskUnavailable`` and ``APIError`` exceptions will return ``None``.\n\n.. code:: python\n\n    >>> from nbp.errors import APIError\n    >>> try:\n    ...     nbp.date_range('2017-01-01', '2017-06-01')\n    ... except APIError:\n    ...     print('Invalid date range')\n    ...\n    Invalid date range\n    >>> nbp.suppress_errors = True\n    >>> print(nbp.date_range('2017-01-01', '2017-06-01'))\n    None\n\nCache size\n~~~~~~~~~~\n\nFor efficiency, ``NBPClient`` utilizes LRU cache for by saving last 128 calls. You can change this value by passing ``cache_size`` to ``NBPClient``. This value can be set only during object initialization.\n\n.. code:: python\n\n    >>> nbp = NBPClient('eur', cache_size=64)\n    >>> nbp\n    NBPClient(EUR, as_float=False, suppress_errors=False, cache_size=64)\n    >>> try:\n    ...     nbp.cache_size = 128\n    ... except AttributeError:\n    ...     print(\"Can't overwrite cache_size\")\n    ...\n    Can't overwrite cache_size\n\nRates as floats\n~~~~~~~~~~~~~~~\n\nBy default all exchange rates are parsed as ``decimal.Decimal`` objects. You can change this behaviour by passing ``as_float=True``, which will force all exchange rates to be parsed as ``float``.\n\n.. code:: python\n\n    >>> nbp = NBPClient('eur')\n    >>> type(nbp().mid)\n    <class 'decimal.Decimal'>\n    >>> nbp = NBPClient('eur', as_float=True)\n    >>> type(nbp().mid)\n    <class 'float'>\n\nExchange rates\n--------------\n\n``NBPClient`` calls returns an ``NBPExchangeRate`` object (their list), which can be used as a converter for calculating given amount in foreign currency to Polish zlotys.\n\n.. code:: python\n\n    >>> exchange_rate = nbp()\n    >>> exchange_rate\n    NBPExchangeRate(EUR->PLN, 2017-10-31, mid=4.2498)\n    >>> amount = 1000\n    >>> exchange_rate(amount)\n    {'mid': Decimal('4249.8000')}\n    >>> exchange_rate * amount\n    {'mid': Decimal('4249.8000')}\n    >>> amount * exchange_rate\n    {'mid': Decimal('4249.8000')}\n    >>>\n    >>> exchange_rate = nbp(all_values=True)\n    >>> exchange_rate\n    NBPExchangeRate(EUR->PLN, 2017-11-02, bid=4.2036, ask=4.2886)\n    >>> exchange_rate(amount)\n    {'bid': Decimal('4204.3000'), 'ask': Decimal('4289.3000')}\n\nExample\n-------\n\nBelow script prints and summarises a list of invoices in foreign currencies.\n\n.. code:: python\n\n    from datetime import datetime, timedelta\n    from decimal import Decimal\n    from nbpy import NBPClient\n    from nbpy.errors import APIError\n\n\n    class Invoice(object):\n        \"\"\"Invoice class with builtin currency converter.\"\"\"\n\n        def __init__(self, currency_code, date, amount):\n            self.currency_code = currency_code\n            self.date = date\n            self.amount = Decimal(\"{:.2f}\".format(amount))\n\n            self._nbp = NBPClient(currency_code)\n\n        @property\n        def amount_in_pln(self):\n            exchange_rate = None\n            date = datetime.strptime(self.date, '%Y-%m-%d')\n            while exchange_rate is None:\n                # Get exchange rates until valid is found\n                try:\n                    exchange_rate = self._nbp.date(date.strftime('%Y-%m-%d'))\n                    break\n                except APIError:\n                    date -= timedelta(days=1)\n\n            amount = (exchange_rate * self.amount)['mid']\n            return round(amount, 2)\n\n\n    # List of invoices in foreign currencies\n    invoices = [\n        Invoice('EUR', '2017-10-03', 650.0),\n        Invoice('EUR', '2017-10-06', 890.0),\n        Invoice('USD', '2017-10-11', 1230.0),\n    ]\n\n    # Print all amounts in their currencies and PLN\n    template = \"{currency}    {amount:7.2f}  {amount_in_pln:7.2f}\"\n    for invoice in invoices:\n        print(template.format(\n            currency=invoice.currency_code,\n            amount=invoice.amount,\n            amount_in_pln=invoice.amount_in_pln,\n        ))\n\n    # Sum all values in PLN\n    # Since amount_in_pln were already called, script will use cached values\n    # instead of calling NBP Web API\n    sum_amount_in_pln = sum([invoice.amount_in_pln for invoice in invoices])\n\n    print(\"-\" * 23)\n    print(\"        total: {sum:8.2f}\".format(sum=sum_amount_in_pln))\n\n    # EUR     650.00  2801.82\n    # EUR     890.00  3830.74\n    # USD    1230.00  4454.94\n    # -----------------------\n    #         total: 11087.50\n\nLicense\n-------\n\n`MIT <LICENSE>`_\n\n",
        "description_content_type": null,
        "docs_url": null,
        "download_url": "",
        "downloads": {
            "last_day": -1,
            "last_month": -1,
            "last_week": -1
        },
        "home_page": "",
        "keywords": "",
        "license": "MIT",
        "maintainer": "",
        "maintainer_email": "",
        "name": "NBPy",
        "package_url": "https://pypi.org/project/NBPy/",
        "platform": "",
        "project_url": "https://pypi.org/project/NBPy/",
        "project_urls": null,
        "release_url": "https://pypi.org/project/NBPy/0.1.1/",
        "requires_dist": [
            "requests (>=2.18)"
        ],
        "requires_python": ">=3.3",
        "summary": "A utility package for calling NBP (Polish National Bank) Web API.",
        "version": "0.1.1"
    },
    "last_serial": 3314001,
    "releases": {
        "0.1.0": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "b04c9e8509e41165181849f499e140a0",
                    "sha256": "016ff028aa3afe1f8b884e4f2f60f1ade0135e5690b83290757780e6a96f73f1"
                },
                "downloads": -1,
                "filename": "NBPy-0.1.0-py3-none-any.whl",
                "has_sig": false,
                "md5_digest": "b04c9e8509e41165181849f499e140a0",
                "packagetype": "bdist_wheel",
                "python_version": "py3",
                "requires_python": ">=3.3",
                "size": 15406,
                "upload_time": "2017-11-07T21:57:53",
                "url": "https://files.pythonhosted.org/packages/ed/b6/d6b2a7a865fc67f8f338cc2d1ad04b7f12a2899f86698888faf4db158c36/NBPy-0.1.0-py3-none-any.whl"
            },
            {
                "comment_text": "",
                "digests": {
                    "md5": "9cc5b00091e992405da5c3bbaccd9730",
                    "sha256": "8ad5d578de9cbb10658bed85c9df0e83a83aef7b5b1905272a5ac287825fd223"
                },
                "downloads": -1,
                "filename": "NBPy-0.1.0.tar.gz",
                "has_sig": false,
                "md5_digest": "9cc5b00091e992405da5c3bbaccd9730",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": ">=3.3",
                "size": 13567,
                "upload_time": "2017-11-07T21:57:55",
                "url": "https://files.pythonhosted.org/packages/a0/80/607ade15025274cbda43af3d959d0a478fb1582cb8295784948f856f6693/NBPy-0.1.0.tar.gz"
            }
        ],
        "0.1.1": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "fc17696d5f35183e079b159cc823631f",
                    "sha256": "43166515b09f96ead854baf1915a737d2bd6122330d3a3568668f4c0da8bd10c"
                },
                "downloads": -1,
                "filename": "NBPy-0.1.1-py3-none-any.whl",
                "has_sig": false,
                "md5_digest": "fc17696d5f35183e079b159cc823631f",
                "packagetype": "bdist_wheel",
                "python_version": "py3",
                "requires_python": ">=3.3",
                "size": 15407,
                "upload_time": "2017-11-07T22:02:27",
                "url": "https://files.pythonhosted.org/packages/a2/4d/30022d111139aec35de977dc758f6bb1dca8325418e258a756050f67f9e9/NBPy-0.1.1-py3-none-any.whl"
            },
            {
                "comment_text": "",
                "digests": {
                    "md5": "d72126378fa80e405e54976b4ce10003",
                    "sha256": "6004d076c64406aef4ce06c01e8b0c760e71bf909c4df92872aa1b22a96ab5b2"
                },
                "downloads": -1,
                "filename": "NBPy-0.1.1.tar.gz",
                "has_sig": false,
                "md5_digest": "d72126378fa80e405e54976b4ce10003",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": ">=3.3",
                "size": 13565,
                "upload_time": "2017-11-07T22:02:29",
                "url": "https://files.pythonhosted.org/packages/cd/35/e914bdd37160437a82145f95581a444021d8afe6b99f76d88b0acd31ad60/NBPy-0.1.1.tar.gz"
            }
        ]
    },
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "fc17696d5f35183e079b159cc823631f",
                "sha256": "43166515b09f96ead854baf1915a737d2bd6122330d3a3568668f4c0da8bd10c"
            },
            "downloads": -1,
            "filename": "NBPy-0.1.1-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "fc17696d5f35183e079b159cc823631f",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.3",
            "size": 15407,
            "upload_time": "2017-11-07T22:02:27",
            "url": "https://files.pythonhosted.org/packages/a2/4d/30022d111139aec35de977dc758f6bb1dca8325418e258a756050f67f9e9/NBPy-0.1.1-py3-none-any.whl"
        },
        {
            "comment_text": "",
            "digests": {
                "md5": "d72126378fa80e405e54976b4ce10003",
                "sha256": "6004d076c64406aef4ce06c01e8b0c760e71bf909c4df92872aa1b22a96ab5b2"
            },
            "downloads": -1,
            "filename": "NBPy-0.1.1.tar.gz",
            "has_sig": false,
            "md5_digest": "d72126378fa80e405e54976b4ce10003",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.3",
            "size": 13565,
            "upload_time": "2017-11-07T22:02:29",
            "url": "https://files.pythonhosted.org/packages/cd/35/e914bdd37160437a82145f95581a444021d8afe6b99f76d88b0acd31ad60/NBPy-0.1.1.tar.gz"
        }
    ]
}