# Django Currency Converter
A Django application for converting currencies using real-time exchange rates from ExchangeRate-API.
## Features
- Real-time currency conversion using ExchangeRate-API
- Built-in caching for improved performance
- Custom Django management commands
- Comprehensive error handling
- Support for 24+ major currencies
- Production-ready with proper logging
- Type hints and documentation
## Installation
1. Install the package:
```bash
pip install django-currency-converter-erapi
```
2. For .env file support (recommended), also install:
```bash
pip install django-currency-converter-erapi[dotenv]
```
3. Add `currency_converter` to your Django project's `INSTALLED_APPS` in `settings.py`:
```python
INSTALLED_APPS = [
# ... other apps
'currency_converter_erapi',
]
```
## Configuration
### API Key Configuration (Multiple Options)
The currency converter supports multiple ways to configure your API key for premium access:
#### Option 1: .env File (Recommended)
Create a `.env` file in your Django project root:
```bash
# .env file
CURRENCY_API_KEY=your_exchangerate_api_key_here
# or alternatively:
EXCHANGERATE_API_KEY=your_exchangerate_api_key_here
```
#### Option 2: Django Settings
Add to your Django `settings.py`:
```python
CURRENCY_API_KEY = 'your_api_key_here'
```
#### Option 3: Environment Variables
Set environment variables directly:
```bash
export CURRENCY_API_KEY=your_api_key_here
# or
export EXCHANGERATE_API_KEY=your_api_key_here
```
### Priority Order
The package checks for API keys in this order:
1. Django settings (`CURRENCY_API_KEY`)
2. Environment variable `CURRENCY_API_KEY`
3. Environment variable `EXCHANGERATE_API_KEY`
4. No API key (uses free tier)
### Additional Settings
Add these optional settings to your Django `settings.py`:
```python
# Currency Converter Settings (Optional)
CURRENCY_CACHE_TIMEOUT = 3600 # Cache exchange rates for 1 hour (default: 3600)
# Ensure you have caching configured
CACHES = {
'default': {
'BACKEND': 'django.core.cache.backends.locmem.LocMemCache',
'LOCATION': 'unique-snowflake',
}
}
```
## Usage
### Using the Management Command
Convert currency using the management command:
```bash
# Basic conversion
python manage.py convert_currency 100 USD EUR
# Show only exchange rate
python manage.py convert_currency 100 USD EUR --rate-only
# List all supported currencies
python manage.py convert_currency 0 USD EUR --list-currencies
```
### Using the Converter Class in Your Code
```python
from currency_converter_erapi.converter import CurrencyConverter
from currency_converter_erapi.exceptions import InvalidCurrencyError, APIError
try:
converter = CurrencyConverter()
# Convert 100 USD to EUR
result = converter.convert(100, 'USD', 'EUR')
print(f"100 USD = {result} EUR")
# Get exchange rate only
rate = converter.get_exchange_rate('USD', 'EUR')
print(f"1 USD = {rate} EUR")
# Get supported currencies
currencies = converter.get_supported_currencies()
print(f"Supported currencies: {currencies}")
except InvalidCurrencyError as e:
print(f"Invalid currency: {e}")
except APIError as e:
print(f"API error: {e}")
```
### Supported Currencies
The application supports 24 major currencies:
- USD, EUR, GBP, JPY, AUD, CAD, CHF, CNY
- SEK, NZD, MXN, SGD, HKD, NOK, TRY, RUB
- INR, BRL, ZAR, KRW, DKK, PLN, TWD, THB
## Error Handling
The package includes comprehensive error handling:
- `InvalidCurrencyError`: Raised for unsupported currency codes
- `APIError`: Raised when the exchange rate API fails
- `RateLimitError`: Raised when API rate limits are exceeded
- `NetworkError`: Raised for network connectivity issues
- `CacheError`: Raised for caching-related errors
## API Rate Limits
The free ExchangeRate-API has the following limits:
- 1,500 requests per month
- Cached responses help minimize API calls
For higher limits, consider upgrading to a paid plan and setting `CURRENCY_API_KEY`.
## Requirements
- Python 3.8+
- Django 3.2+
- requests 2.25.0+
## Development
### Running Tests
```bash
python -m pytest
```
### Code Quality
The project follows PEP 8 standards and includes:
- Type hints
- Comprehensive docstrings
- Error handling
- Logging support
## Troubleshooting
### Common Issues
1. **API Rate Limit Exceeded**
- Solution: Wait for rate limit reset or upgrade to paid plan
2. **Network Timeout**
- Solution: Check internet connection and firewall settings
3. **Cache Issues**
- Solution: Ensure Django caching is properly configured
4. **Invalid Currency Code**
- Solution: Use 3-letter ISO currency codes (e.g., USD, EUR)
### Logging
Enable logging to see detailed error information:
```python
LOGGING = {
'version': 1,
'disable_existing_loggers': False,
'handlers': {
'console': {
'class': 'logging.StreamHandler',
},
},
'loggers': {
'currency_converter_erapi': {
'handlers': ['console'],
'level': 'INFO',
},
},
}
```
## Contributing
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Support
For issues and questions:
- Create an issue on GitHub
- Check the troubleshooting section above
## Changelog
### Version 1.0.0
- Initial release
- Support for 24 major currencies
- Caching support
- Management commands
- Comprehensive error handling
Raw data
{
"_id": null,
"home_page": "https://github.com/mislamdev/django-currency-converter-erapi",
"name": "django-currency-converter-erapi",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "django currency converter exchange rates api finance",
"author": "MD. MAZHARUL ISLAM",
"author_email": "mislam@m4a.dev",
"download_url": "https://files.pythonhosted.org/packages/95/15/7619c38e5d3c939d279ecf2790f0e4604294b3dfed667c72334e9db39862/django_currency_converter_erapi-1.2.0.tar.gz",
"platform": null,
"description": "# Django Currency Converter\n\nA Django application for converting currencies using real-time exchange rates from ExchangeRate-API.\n\n## Features\n\n- Real-time currency conversion using ExchangeRate-API\n- Built-in caching for improved performance\n- Custom Django management commands\n- Comprehensive error handling\n- Support for 24+ major currencies\n- Production-ready with proper logging\n- Type hints and documentation\n\n## Installation\n\n1. Install the package:\n```bash\npip install django-currency-converter-erapi\n```\n\n2. For .env file support (recommended), also install:\n```bash\npip install django-currency-converter-erapi[dotenv]\n```\n\n3. Add `currency_converter` to your Django project's `INSTALLED_APPS` in `settings.py`:\n```python\nINSTALLED_APPS = [\n # ... other apps\n 'currency_converter_erapi',\n]\n```\n\n## Configuration\n\n### API Key Configuration (Multiple Options)\n\nThe currency converter supports multiple ways to configure your API key for premium access:\n\n#### Option 1: .env File (Recommended)\nCreate a `.env` file in your Django project root:\n```bash\n# .env file\nCURRENCY_API_KEY=your_exchangerate_api_key_here\n# or alternatively:\nEXCHANGERATE_API_KEY=your_exchangerate_api_key_here\n```\n\n#### Option 2: Django Settings\nAdd to your Django `settings.py`:\n```python\nCURRENCY_API_KEY = 'your_api_key_here'\n```\n\n#### Option 3: Environment Variables\nSet environment variables directly:\n```bash\nexport CURRENCY_API_KEY=your_api_key_here\n# or\nexport EXCHANGERATE_API_KEY=your_api_key_here\n```\n\n### Priority Order\nThe package checks for API keys in this order:\n1. Django settings (`CURRENCY_API_KEY`)\n2. Environment variable `CURRENCY_API_KEY`\n3. Environment variable `EXCHANGERATE_API_KEY`\n4. No API key (uses free tier)\n\n### Additional Settings\n\nAdd these optional settings to your Django `settings.py`:\n\n```python\n# Currency Converter Settings (Optional)\nCURRENCY_CACHE_TIMEOUT = 3600 # Cache exchange rates for 1 hour (default: 3600)\n\n# Ensure you have caching configured\nCACHES = {\n 'default': {\n 'BACKEND': 'django.core.cache.backends.locmem.LocMemCache',\n 'LOCATION': 'unique-snowflake',\n }\n}\n```\n\n## Usage\n\n### Using the Management Command\n\nConvert currency using the management command:\n\n```bash\n# Basic conversion\npython manage.py convert_currency 100 USD EUR\n\n# Show only exchange rate\npython manage.py convert_currency 100 USD EUR --rate-only\n\n# List all supported currencies\npython manage.py convert_currency 0 USD EUR --list-currencies\n```\n\n### Using the Converter Class in Your Code\n\n```python\nfrom currency_converter_erapi.converter import CurrencyConverter\nfrom currency_converter_erapi.exceptions import InvalidCurrencyError, APIError\n\ntry:\n converter = CurrencyConverter()\n\n # Convert 100 USD to EUR\n result = converter.convert(100, 'USD', 'EUR')\n print(f\"100 USD = {result} EUR\")\n\n # Get exchange rate only\n rate = converter.get_exchange_rate('USD', 'EUR')\n print(f\"1 USD = {rate} EUR\")\n\n # Get supported currencies\n currencies = converter.get_supported_currencies()\n print(f\"Supported currencies: {currencies}\")\n\nexcept InvalidCurrencyError as e:\n print(f\"Invalid currency: {e}\")\nexcept APIError as e:\n print(f\"API error: {e}\")\n```\n\n### Supported Currencies\n\nThe application supports 24 major currencies:\n- USD, EUR, GBP, JPY, AUD, CAD, CHF, CNY\n- SEK, NZD, MXN, SGD, HKD, NOK, TRY, RUB\n- INR, BRL, ZAR, KRW, DKK, PLN, TWD, THB\n\n## Error Handling\n\nThe package includes comprehensive error handling:\n\n- `InvalidCurrencyError`: Raised for unsupported currency codes\n- `APIError`: Raised when the exchange rate API fails\n- `RateLimitError`: Raised when API rate limits are exceeded\n- `NetworkError`: Raised for network connectivity issues\n- `CacheError`: Raised for caching-related errors\n\n## API Rate Limits\n\nThe free ExchangeRate-API has the following limits:\n- 1,500 requests per month\n- Cached responses help minimize API calls\n\nFor higher limits, consider upgrading to a paid plan and setting `CURRENCY_API_KEY`.\n\n## Requirements\n\n- Python 3.8+\n- Django 3.2+\n- requests 2.25.0+\n\n## Development\n\n### Running Tests\n\n```bash\npython -m pytest\n```\n\n### Code Quality\n\nThe project follows PEP 8 standards and includes:\n- Type hints\n- Comprehensive docstrings\n- Error handling\n- Logging support\n\n## Troubleshooting\n\n### Common Issues\n\n1. **API Rate Limit Exceeded**\n - Solution: Wait for rate limit reset or upgrade to paid plan\n\n2. **Network Timeout**\n - Solution: Check internet connection and firewall settings\n\n3. **Cache Issues**\n - Solution: Ensure Django caching is properly configured\n\n4. **Invalid Currency Code**\n - Solution: Use 3-letter ISO currency codes (e.g., USD, EUR)\n\n### Logging\n\nEnable logging to see detailed error information:\n\n```python\nLOGGING = {\n 'version': 1,\n 'disable_existing_loggers': False,\n 'handlers': {\n 'console': {\n 'class': 'logging.StreamHandler',\n },\n },\n 'loggers': {\n 'currency_converter_erapi': {\n 'handlers': ['console'],\n 'level': 'INFO',\n },\n },\n}\n```\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Support\n\nFor issues and questions:\n- Create an issue on GitHub\n- Check the troubleshooting section above\n\n## Changelog\n\n### Version 1.0.0\n- Initial release\n- Support for 24 major currencies\n- Caching support\n- Management commands\n- Comprehensive error handling\n",
"bugtrack_url": null,
"license": null,
"summary": "A Django application for currency conversion using real-time exchange rates",
"version": "1.2.0",
"project_urls": {
"Bug Reports": "https://github.com/mislamdev/django-currency-converter-erapi/issues",
"Documentation": "https://github.com/mislamdev/django-currency-converter-erapi#readme",
"Homepage": "https://github.com/mislamdev/django-currency-converter-erapi",
"Source": "https://github.com/mislamdev/django-currency-converter-erapi"
},
"split_keywords": [
"django",
"currency",
"converter",
"exchange",
"rates",
"api",
"finance"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "4b45cb7b60eb19e73b518a85fe207f04855321a46197b662357f44784594aa6b",
"md5": "6d93f79325cb3b083245fda751d60abc",
"sha256": "6684813cdf674a78d93a29dff9b1af3b3e23e4be9bd51dd23eff7086cdb213c4"
},
"downloads": -1,
"filename": "django_currency_converter_erapi-1.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6d93f79325cb3b083245fda751d60abc",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 14758,
"upload_time": "2025-09-09T06:38:14",
"upload_time_iso_8601": "2025-09-09T06:38:14.690443Z",
"url": "https://files.pythonhosted.org/packages/4b/45/cb7b60eb19e73b518a85fe207f04855321a46197b662357f44784594aa6b/django_currency_converter_erapi-1.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "95157619c38e5d3c939d279ecf2790f0e4604294b3dfed667c72334e9db39862",
"md5": "1e7b850d2cabcc6e7bb20711f731e4c3",
"sha256": "d85900bc683499c067e54bb0c6605765b9c1533e46051074968fc01cc61d3809"
},
"downloads": -1,
"filename": "django_currency_converter_erapi-1.2.0.tar.gz",
"has_sig": false,
"md5_digest": "1e7b850d2cabcc6e7bb20711f731e4c3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 14794,
"upload_time": "2025-09-09T06:38:15",
"upload_time_iso_8601": "2025-09-09T06:38:15.613203Z",
"url": "https://files.pythonhosted.org/packages/95/15/7619c38e5d3c939d279ecf2790f0e4604294b3dfed667c72334e9db39862/django_currency_converter_erapi-1.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-09 06:38:15",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mislamdev",
"github_project": "django-currency-converter-erapi",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "Django",
"specs": [
[
">=",
"3.2"
],
[
"<",
"5.3"
]
]
},
{
"name": "requests",
"specs": [
[
"<",
"3.0"
],
[
">=",
"2.25.0"
]
]
},
{
"name": "pytest",
"specs": [
[
">=",
"6.0"
]
]
},
{
"name": "pytest-django",
"specs": [
[
">=",
"4.0"
]
]
},
{
"name": "pytest-cov",
"specs": [
[
">=",
"2.10.0"
]
]
},
{
"name": "coverage",
"specs": [
[
">=",
"5.0"
]
]
},
{
"name": "black",
"specs": [
[
">=",
"21.0"
]
]
},
{
"name": "flake8",
"specs": [
[
">=",
"3.8"
]
]
},
{
"name": "mypy",
"specs": [
[
">=",
"0.800"
]
]
},
{
"name": "isort",
"specs": [
[
">=",
"5.0"
]
]
},
{
"name": "sphinx",
"specs": [
[
">=",
"4.0"
]
]
},
{
"name": "sphinx-rtd-theme",
"specs": [
[
">=",
"1.0"
]
]
}
],
"lcname": "django-currency-converter-erapi"
}
JSON
