diff --git a/README.md b/README.md new file mode 100644 index 0000000..298726b --- /dev/null +++ b/README.md @@ -0,0 +1,108 @@ +# forex-python + +[![travis-ci](https://travis-ci.org/MicroPyramid/forex-python.svg?branch=master)](https://travis-ci.org/MicroPyramid/forex-python) +[![coveralls](https://coveralls.io/repos/github/MicroPyramid/forex-python/badge.svg?branch=master)](https://coveralls.io/github/MicroPyramid/forex-python?branch=master) +[![Code Health](https://landscape.io/github/MicroPyramid/forex-python/master/landscape.svg?style=flat)](https://landscape.io/github/MicroPyramid/forex-python/master) +[![pypi](https://img.shields.io/badge/python-3.6%2B-blue.svg)](https://pypi.python.org/pypi/forex-python) + +**Forex Python** is a free library for foreign exchange rates and currency conversion, supporting Python 3.6 and above. + +> **Note:** Install the latest version (`forex-python>=1.6`) to avoid `RatesNotAvailableError`. + +## Features + +- List all currency rates +- Bitcoin price for all currencies +- Convert amounts to and from Bitcoin +- Get historical rates (since 1999) +- Currency conversion (e.g., USD to INR) +- Currency symbols and names + +## Currency Source + +[theratesapi.com](https://theratesapi.com) provides current and historical foreign exchange rates published by the European Central Bank. Rates are updated daily at 3PM CET. + +## Bitcoin Price Source + +Bitcoin prices are updated every minute. For more information, visit [CoinDesk](http://www.coindesk.com). + +## Installation + +Install via pip: +```bash +pip install forex-python +``` +Or clone the repository and install manually: +```bash +git clone https://github.com/MicroPyramid/forex-python.git +cd forex-python +python3 setup.py install +``` + +## Usage Examples + +**Initialize the class:** +```python +from forex_python.converter import CurrencyRates +c = CurrencyRates() +``` + +**List all latest currency rates for "USD":** +```python +c.get_rates('USD') +# Example output: {'INR': 83.12, 'EUR': 0.92, ...} +``` + +**Get conversion rate from USD to INR:** +```python +c.get_rate('USD', 'INR') +# Example output: 83.12 +``` + +**Convert amount from USD to INR:** +```python +c.convert('USD', 'INR', 10) +# Example output: 831.2 +``` + +**Force use of Decimal:** +```python +from decimal import Decimal +c = CurrencyRates(force_decimal=True) +c.convert('USD', 'INR', Decimal('10.45')) +# Example output: 868.75 +``` + +**Get latest Bitcoin price:** +```python +from forex_python.bitcoin import BtcConverter +b = BtcConverter() +b.get_latest_price('USD') +# Example output: 67000.0 +``` + +**Convert amount to Bitcoins:** +```python +b.convert_to_btc(400, 'USD') +# Example output: 0.00597 +``` + +**Get currency symbol using currency code:** +```python +from forex_python.converter import CurrencyCodes +codes = CurrencyCodes() +codes.get_symbol('GBP') +# Example output: '£' +``` + +For complete documentation, see the [forex-python docs](http://forex-python.readthedocs.org/en/latest/?badge=latest). + +--- + +## Support & Feedback + +- Found a bug? Please [open a GitHub issue](https://github.com/MicroPyramid/forex-python/issues). +- Need a new feature or custom development? [Contact us here](https://micropyramid.com/contact-us/). +- Visit our [Python Development Services](https://micropyramid.com/python-development-services/) page for more information. + +--- \ No newline at end of file diff --git a/README.rst b/README.rst deleted file mode 100644 index 6bc71d2..0000000 --- a/README.rst +++ /dev/null @@ -1,157 +0,0 @@ -forex-python -============ - -.. image:: https://travis-ci.org/MicroPyramid/forex-python.svg?branch=master - :target: https://travis-ci.org/MicroPyramid/forex-python - :alt: travis-ci - -.. image:: https://coveralls.io/repos/github/MicroPyramid/forex-python/badge.svg?branch=master - :target: https://coveralls.io/github/MicroPyramid/forex-python?branch=master - :alt: coveralls - -.. image:: https://landscape.io/github/MicroPyramid/forex-python/master/landscape.svg?style=flat - :target: https://landscape.io/github/MicroPyramid/forex-python/master - :alt: Code Health - -.. image:: https://img.shields.io/badge/python-2.7%2C%203.3%2C%203.4%2C%203.5-blue.svg - :target: https://pypi.python.org/pypi/forex-python - :alt: pypi - -Forex Python is a Free Foreign exchange rates and currency conversion. - -**Note: Install latest forex-python==1.6 to avoid RatesNotAvailableError** - -Features of Forex Python: ---------- -- List all currency rates. -- BitCoin price for all currencies. -- Converting amount to BitCoins. -- Get historical rates for any day since 1999. -- Conversion rate for one currency(ex; USD to INR). -- Convert amount from one currency to other.('USD 10$' to INR). -- Currency symbols. -- Currency names. - -Currency Source: ------------------ - -https://theforexapi.com is a free API for current and historical foreign exchange rates published by European Central Bank. -The rates are updated daily 3PM CET. - -BitCoin Price Source: ---------------------- -Bitcoin prices calculated every minute. For more information visit [CoinDesk API](http://www.coindesk.com/api/). - -Installation --------------- - -- Install using python package - - .. code-block:: python - - pip install forex-python - - Or directly cloning the repo: - - python setup.py install - -Usage Examples: ------------------- - -- Initialize class - - .. code-block:: python - - python - >>> from forex_python.converter import CurrencyRates - >>> c = CurrencyRates() - -- list all latest currency rates for "USD" - - .. code-block:: python - - python - >>> c.get_rates('USD') - {u'IDR': 13625.0, u'BGN': 1.7433, u'ILS': 3.8794, u'GBP': 0.68641, u'DKK': 6.6289, u'CAD': 1.3106, u'JPY': 110.36, u'HUF': 282.36, u'RON': 4.0162, u'MYR': 4.081, u'SEK': 8.3419, u'SGD': 1.3815, u'HKD': 7.7673, u'AUD': 1.3833, u'CHF': 0.99144, u'KRW': 1187.3, u'CNY': 6.5475, u'TRY': 2.9839, u'HRK': 6.6731, u'NZD': 1.4777, u'THB': 35.73, u'EUR': 0.89135, u'NOK': 8.3212, u'RUB': 66.774, u'INR': 67.473, u'MXN': 18.41, u'CZK': 24.089, u'BRL': 3.5473, u'PLN': 3.94, u'PHP': 46.775, u'ZAR': 15.747} - -- Get conversion rate from USD to INR - - .. code-block:: python - - python - >>> c.get_rate('USD', 'INR') - 67.473 - -- Convert amount from USD to INR - - .. code-block:: python - - python - >>> c.convert('USD', 'INR', 10) - 674.73 - -- Force use of Decimal - - .. code-block:: python - - python - >>> from forex_python.converter import CurrencyRates - >>> c = CurrencyRates(force_decimal=True) - >>> c.convert('USD', 'INR', Decimal('10.45')) - 705.09 - >>> c.convert('USD', 'INR', 10) - DecimalFloatMismatchError: convert requires amount parameter is of type Decimal when use_decimal=True - -- Detect use of Decimal - - .. code-block:: python - - python - >>> from forex_python.converter import CurrencyRates - >>> c = CurrencyRates() - >>> c.convert('USD', 'INR', Decimal('10.45')) - 705.09 - >>> c.convert('USD', 'INR', 10) - 674.73 - -- Get latest Bitcoin price. - - .. code-block:: python - - python - >>> from forex_python.bitcoin import BtcConverter - >>> b = BtcConverter() # force_decimal=True to get Decimal rates - >>> b.get_latest_price('USD') - 533.913 - - -- Convert Amount to Bitcoins based on latest exchange price. - - .. code-block:: python - - python - >>> b.convert_to_btc(400, 'USD') - 0.7492699301118473 - - -- Get currency symbol using currency code - - .. code-block:: python - - python - >>> from forex_python.converter import CurrencyCodes - >>> c = CurrencyCodes() - >>> print c.get_symbol('GBP') - £ - - -You can view the complete `Documentation Here`_ - -Visit our Python Development page `Here`_ - -We welcome your feedback and support, raise `github ticket`_ if you want to report a bug. Need new features? `Contact us here`_ - -.. _contact us here: https://micropyramid.com/contact-us/ -.. _github ticket: https://github.com/MicroPyramid/forex-python/issues -.. _Documentation Here: http://forex-python.readthedocs.org/en/latest/?badge=latest -.. _Here: https://micropyramid.com/python-development-services/ diff --git a/docs/source/conf.py b/docs/source/conf.py index 4e7c981..bc49dd2 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -59,9 +59,9 @@ # built documents. # # The short X.Y version. -version = u'1.6' +version = u'1.9.2' # The full version, including alpha/beta/rc tags. -release = u'1.6' +release = u'1.9.2' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. diff --git a/docs/source/currencysource.rst b/docs/source/currencysource.rst index 170281a..1c6dbf9 100644 --- a/docs/source/currencysource.rst +++ b/docs/source/currencysource.rst @@ -1,9 +1,9 @@ currency source =============== -https://theforexapi.com +https://theratesapi.com -------- -https://theforexapi.com is a free API for current and historical foreign exchange rates published by European Central Bank. The rates are updated daily 3PM CET. +https://theratesapi.com is a free API for current and historical foreign exchange rates published by European Central Bank. The rates are updated daily 3PM CET. List of Supported Currency codes. --------------------------------- diff --git a/docs/source/index.rst b/docs/source/index.rst index c009d5f..6d42f63 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,17 +1,17 @@ forex-python ============ -Free Foreign exchange rates, bitcoin prices and currency conversion. +Free foreign exchange rates, Bitcoin prices and currency conversion. Features: --------- - List all currency rates. -- BitCoin price for all currencies. -- Converting amount to BitCoins. +- Bitcoin price for all currencies. +- Converting amount to BitCoin. - Get historical rates for any day since 1999. -- Conversion rate for one currency(ex; USD to INR). -- Convert amount from one currency to other.('USD 10$' to INR) -- Currency Symbols +- Conversion rate for one currency (e.g. USD to INR). +- Convert amount from one currency to another (e.g. 'USD $10' to INR) +- Currency symbols - Currency names Contents: diff --git a/docs/source/usage.rst b/docs/source/usage.rst index 779e478..d62607f 100644 --- a/docs/source/usage.rst +++ b/docs/source/usage.rst @@ -66,21 +66,21 @@ Bitcoin Prices: >>> b.get_previous_price('USD', date_obj) # get_previous_price('USD', date_obj) 453.378 -3. Convert Amout to bitcoins:: +3. Convert Amount to Bitcoin:: >>> b.convert_to_btc(5000, 'USD') # convert_to_btc(5000, 'USD') 9.36345369116708 -4. Convert Amount to bitcoins based on previous date prices:: +4. Convert Amount to Bitcoin based on previous date prices:: >>> date_obj datetime.datetime(2016, 5, 18, 19, 39, 36, 815417) >>> b.convert_to_btc_on(5000, 'USD', date_obj) # convert_to_btc_on(5000, 'USD', date_obj) 11.028325150316071 -5. Convert Bitcoins to valid currency amount based on lates price:: +5. Convert Bitcoin to valid currency amount based on latest price:: >>> b.convert_btc_to_cur(1.25, 'USD') # convert_btc_to_cur(1.25, 'USD') 668.1012499999999 -6. Convert Bitcoins to valid currency amount based on previous date price:: +6. Convert Bitcoin to valid currency amount based on previous date price:: >>> date_obj datetime.datetime(2016, 5, 18, 19, 39, 36, 815417) >>> b.convert_btc_to_cur_on(1.25, 'EUR', date_obj) @@ -106,7 +106,7 @@ Bitcoin Prices: Currency Symbols & Codes ------------------------- -1. Get Currency symbol Using currency code:: +1. Get currency symbol using currency code:: >>> from forex_python.converter import CurrencyCodes >>> c = CurrencyCodes() >>> c.get_symbol('GBP') @@ -116,8 +116,8 @@ Currency Symbols & Codes >>> print c.get_symbol('EUR') € -2. Get Currency Name using currency code:: +2. Get currency name using currency code:: >>> c.get_currency_name('EUR') u'European Euro' >>> c.get_currency_name('INR') - u'Indian rupee' + u'Indian Rupee' diff --git a/forex_python/bitcoin.py b/forex_python/bitcoin.py index 6ccd226..b699a4d 100644 --- a/forex_python/bitcoin.py +++ b/forex_python/bitcoin.py @@ -6,7 +6,7 @@ class BtcConverter(object): """ - Get bit coin rates and convertion + Get Bitcoin rates and conversion """ def __init__(self, force_decimal=False): self._force_decimal = force_decimal @@ -20,7 +20,7 @@ def _decode_rates(self, response, use_decimal=False): def get_latest_price(self, currency): """ - Get Lates price of one bitcoin to valid Currency 1BTC => X USD + Get latest price of one Bitcoin to valid currency 1BTC => X USD """ url = 'https://api.coindesk.com/v1/bpi/currentprice/{}.json'.format(currency) response = requests.get(url) @@ -34,7 +34,7 @@ def get_latest_price(self, currency): def get_previous_price(self, currency, date_obj): """ - Get Price for one bit coin on given date + Get price for one Bitcoin on given date """ start = date_obj.strftime('%Y-%m-%d') end = date_obj.strftime('%Y-%m-%d') @@ -55,7 +55,7 @@ def get_previous_price(self, currency, date_obj): def get_previous_price_list(self, currency, start_date, end_date): """ - Get List of prices between two dates + Get list of Bitcoin prices between two dates """ start = start_date.strftime('%Y-%m-%d') end = end_date.strftime('%Y-%m-%d') @@ -74,7 +74,7 @@ def get_previous_price_list(self, currency, start_date, end_date): def convert_to_btc(self, amount, currency): """ - Convert X amount to Bit Coins + Convert X amount to Bitcoin """ if isinstance(amount, Decimal): use_decimal = True @@ -98,7 +98,7 @@ def convert_to_btc(self, amount, currency): def convert_btc_to_cur(self, coins, currency): """ - Convert X bit coins to valid currency amount + Convert X Bitcoin to valid currency amount """ if isinstance(coins, Decimal): use_decimal = True @@ -122,7 +122,7 @@ def convert_btc_to_cur(self, coins, currency): def convert_to_btc_on(self, amount, currency, date_obj): """ - Convert X amount to BTC based on given date rate + Convert X amount to Bitcoin based on a given date's rate """ if isinstance(amount, Decimal): use_decimal = True @@ -149,11 +149,11 @@ def convert_to_btc_on(self, amount, currency, date_obj): return converted_btc except TypeError: raise DecimalFloatMismatchError("convert_to_btc_on requires amount parameter is of type Decimal when force_decimal=True") - raise RatesNotAvailableError("BitCoin Rates Source Not Ready For Given Date") + raise RatesNotAvailableError("Bitcoin rates source not ready for given date") def convert_btc_to_cur_on(self, coins, currency, date_obj): """ - Convert X BTC to valid currency amount based on given date + Convert X Bitcoin to valid currency amount based on given's date rate """ if isinstance(coins, Decimal): use_decimal = True @@ -180,11 +180,11 @@ def convert_btc_to_cur_on(self, coins, currency, date_obj): return converted_btc except TypeError: raise DecimalFloatMismatchError("convert_btc_to_cur_on requires amount parameter is of type Decimal when force_decimal=True") - raise RatesNotAvailableError("BitCoin Rates Source Not Ready For Given Date") + raise RatesNotAvailableError("Bitcoin rates source not ready for given date") def get_symbol(self): """ - Here is Unicode symbol for bitcoin + Here is the Unicode symbol for Bitcoin: """ return "\u0E3F" diff --git a/forex_python/converter.py b/forex_python/converter.py index 390a11a..d0c4f7a 100644 --- a/forex_python/converter.py +++ b/forex_python/converter.py @@ -7,7 +7,7 @@ class RatesNotAvailableError(Exception): """ - Custome Exception when https://theforexapi.com is Down and not available for currency rates + Custom exception when https://theratesapi.com is down and not available for currency rates """ pass @@ -25,7 +25,7 @@ def __init__(self, force_decimal=False): self._force_decimal = force_decimal def _source_url(self): - return "https://theforexapi.com/api/" + return "https://theratesapi.com/api/" def _get_date_string(self, date_obj): if date_obj is None: @@ -99,6 +99,9 @@ def convert(self, base_cur, dest_cur, amount, date_obj=None): if not rate: raise RatesNotAvailableError("Currency {0} => {1} rate not available for Date {2}.".format( source_url, dest_cur, date_str)) + # Ensure rate is numeric + if isinstance(rate, str): + rate = Decimal(rate) if use_decimal else float(rate) try: converted_amount = rate * amount return converted_amount @@ -124,7 +127,7 @@ def __init__(self): def _currency_data(self): if self.__currency_data is None: file_path = os.path.dirname(os.path.abspath(__file__)) - with open(file_path + '/raw_data/currencies.json') as f: + with open(file_path + '/raw_data/currencies.json', encoding="utf-8") as f: self.__currency_data = json.loads(f.read()) return self.__currency_data diff --git a/setup.py b/setup.py index de66932..34dc559 100644 --- a/setup.py +++ b/setup.py @@ -2,47 +2,51 @@ import os from setuptools import setup, find_packages -VERSION = '1.6' -long_description_text = """Forex Python is a Free Foreign exchange rates and currency conversion. -Features: -List all currency rates. -BitCoin price for all curuncies. -Converting amount to BitCoins. -Get historical rates for any day since 1999. -Conversion rate for one currency(ex; USD to INR). -Convert amount from one currency to other.('USD 10$' to INR). -Currency symbols. -Currency names. +# 1) Bump this version each release: +VERSION = '1.9.2' -Documentation: http://forex-python.readthedocs.io/en/latest/usage.html -GitHub: https://github.com/MicroPyramid/forex-python - -""" +# 2) Pull your README.md in as long_description: +here = os.path.abspath(os.path.dirname(__file__)) +with io.open(os.path.join(here, 'README.md'), encoding='utf-8') as f: + long_description = f.read() setup( name='forex-python', version=VERSION, author='Micro Pyramid Informatic Pvt. Ltd.', author_email='hello@micropyramid.com', + description='Free foreign exchange rates and currency conversion.', + long_description=long_description, + long_description_content_type='text/markdown', # so PyPI renders your README properly url='https://github.com/MicroPyramid/forex-python', - description='Foreign exchange rates and currency conversion.', - long_description=long_description_text, - packages=find_packages(exclude=['tests', 'tests.*']), + packages=find_packages(exclude=['tests*']), include_package_data=True, install_requires=[ - 'requests', - 'simplejson', + 'requests>=2.0', + 'simplejson>=3.0', ], + python_requires='>=2.7, !=3.0.*, !=3.1.*, !=3.2.*, <4', classifiers=[ + # audience 'Intended Audience :: Developers', - 'Operating System :: OS Independent', + 'Topic :: Software Development :: Internationalization', + # license 'License :: OSI Approved :: MIT License', + # OS + 'Operating System :: OS Independent', + # languages 'Programming Language :: Python', 'Programming Language :: Python :: 2.7', 'Programming Language :: Python :: 3', - 'Programming Language :: Python :: 3.3', - 'Programming Language :: Python :: 3.4', - 'Programming Language :: Python :: 3.5', - 'Topic :: Software Development :: Internationalization', + 'Programming Language :: Python :: 3.6', + 'Programming Language :: Python :: 3.7', + 'Programming Language :: Python :: 3.8', + 'Programming Language :: Python :: 3.9', + 'Programming Language :: Python :: 3.10', ], + project_urls={ # these show up as “Project Links” on PyPI + 'Documentation': 'https://forex-python.readthedocs.io/', + 'Source': 'https://github.com/MicroPyramid/forex-python', + 'Tracker': 'https://github.com/MicroPyramid/forex-python/issues', + }, ) diff --git a/tests/test_bitcoin.py b/tests/test_bitcoin.py index a747c8c..f2eccfd 100644 --- a/tests/test_bitcoin.py +++ b/tests/test_bitcoin.py @@ -55,7 +55,7 @@ def test_previous_price_list_with_invalid_currency(self): class TestConvertBtc(TestCase): """ - Test Converting amount to Bit coins + Test converting amount to Bitcoin """ def test_convet_to_btc_with_valid_currency(self): coins = convert_to_btc(250, 'USD') @@ -67,7 +67,7 @@ def test_convet_to_btc_with_invalid_currency(self): class TestConvertBtcToCur(TestCase): """ - Convert Bit Coins to Valid Currency amount + Convert Bitcoin to valid currency amount """ def test_convert_btc_to_cur_valid_currency(self): amount = convert_btc_to_cur(2, 'USD') @@ -79,7 +79,7 @@ def test_convert_btc_to_cur_invalid_currency(self): class TestConvertToBtcOn(TestCase): """ - Convert To bit coin based on previous dates + Convert to Bitcoin based on previous date """ def test_convert_to_btc_on_with_valid_currency(self): date_obj = datetime.datetime.today() - datetime.timedelta(days=15) @@ -93,7 +93,7 @@ def test_convert_to_btc_on_with_invalid_currency(self): class TestConvertBtcToCurOn(TestCase): """ - Convert BitCoins to valid Currency + Convert Bitcoin to valid currency """ def test_convert_to_btc_on_with_valid_currency(self): date_obj = datetime.datetime.today() - datetime.timedelta(days=15) @@ -107,7 +107,7 @@ def test_convert_to_btc_on_with_invalid_currency(self): class TestBitCoinSymbol(TestCase): """ - Bit Coin symbol + Bitcoin symbol """ def test_bitcoin_symbol(self): self.assertEqual(get_btc_symbol(), "\u0E3F") @@ -218,11 +218,11 @@ def test_previous_price_list_with_invalid_currency(self): self.assertFalse(price_list) self.assertEqual(type(price_list), dict) - def test_convet_to_btc_with_valid_currency(self): + def test_convert_to_btc_with_valid_currency(self): coins = self.b.convert_to_btc(Decimal('250'), 'USD') self.assertEqual(type(coins), Decimal) - def test_convet_to_btc_with_invalid_currency(self): + def test_convert_to_btc_with_invalid_currency(self): self.assertRaises(RatesNotAvailableError, self.b.convert_to_btc, Decimal('250'), 'XYZ') def test_convert_btc_to_cur_valid_currency(self):