django-cfg 1.2.23__py3-none-any.whl → 1.2.25__py3-none-any.whl

django_cfg/modules/django_currency/README.md

@@ -1,334 +1,169 @@
 # Django Currency Module
 
-🚀 **Auto-configuring currency conversion service for django-cfg**
+🚀 **Universal currency converter with decomposed provider logic**
 
-A comprehensive currency conversion module that integrates seamlessly with DjangoConfig, featuring multiple data sources, intelligent caching, and beautiful YAML export functionality.
+A simple, KISS-principle currency conversion module that provides seamless bidirectional conversion between fiat and cryptocurrency rates.
 
 ## ✨ Features
 
-- **🔄 Multi-Source Conversion**: CBR API, ECB API, and fallback currency converter
-- **📁 YAML Caching**: Beautiful, human-readable cache files with comments
-- **⚡ TTL Memory Cache**: Fast in-memory caching with automatic expiration
-- **🌍 170+ Currencies**: Support for major world currencies
-- **🔧 Auto-Configuration**: Seamless integration with DjangoConfig
-- **📊 Batch Operations**: Convert multiple currencies in one call
-- **🎨 Pretty Export**: Export rates to formatted YAML with descriptions
-- **🔔 Telegram Integration**: Send currency alerts via Telegram
+- **🔄 Universal Conversion**: Fiat ⇄ Fiat, Crypto ⇄ Fiat, Crypto ⇄ Crypto
+- **📡 Dynamic Loading**: All currencies loaded dynamically from APIs (no hardcoded lists)
+- **🎯 Provider Separation**: YFinance for fiat, CoinGecko for crypto
+- **⚡ TTL Caching**: Fast in-memory caching with configurable TTL
+- **🔧 Pydantic Models**: All data structures typed with Pydantic v2
+- **🚫 No API Keys**: Uses only public APIs
+- **🔀 Smart Routing**: Automatic provider selection and indirect conversions
 
-## 🚀 Quick Start
-
-### Basic Usage
-
-```python
-from django_cfg.modules.django_currency import DjangoCurrency
+## 🏗️ Architecture
 
-# Initialize service (auto-configured)
-currency = DjangoCurrency()
-
-# Convert currencies
-result = currency.convert(100, 'USD', 'RUB')
-print(f"100 USD = {result:.2f} RUB")
-
-# Get exchange rate
-rate = currency.get_rate('EUR', 'USD')
-print(f"1 EUR = {rate:.4f} USD")
 ```
+django_currency/
+├── models.py           # Pydantic v2 data models
+├── exceptions.py       # Custom exceptions
+├── cache.py           # TTL cache manager  
+├── converter.py       # Main conversion logic
+├── clients/
+│   ├── yfinance_client.py    # Fiat currencies only
+│   └── coingecko_client.py   # Cryptocurrencies only
+└── __init__.py        # Public API
+```
+
+## 🚀 Quick Start
 
-### Convenience Functions
+### Simple API
 
 ```python
 from django_cfg.modules.django_currency import convert_currency, get_exchange_rate
 
-# Quick conversion
-amount_rub = convert_currency(100, 'USD', 'RUB')
+# Convert currencies
+eur_amount = convert_currency(100, "USD", "EUR")
+btc_price = convert_currency(50000, "USD", "BTC")
 
-# Quick rate lookup
-eur_usd_rate = get_exchange_rate('EUR', 'USD')
+# Get exchange rates
+usd_eur_rate = get_exchange_rate("USD", "EUR")
+btc_usd_rate = get_exchange_rate("BTC", "USD")
 ```
 
-### Batch Conversions
+### Advanced Usage
 
 ```python
-currency = DjangoCurrency()
+from django_cfg.modules.django_currency import CurrencyConverter
 
-amounts = [100, 500, 1000]
-from_currencies = ['USD', 'EUR', 'GBP']  
-to_currencies = ['RUB', 'RUB', 'RUB']
+converter = CurrencyConverter()
 
-results = currency.convert_multiple(amounts, from_currencies, to_currencies)
-# Results: [8074.98, 4268.14, 9514.20]
-```
+# Get conversion result with details
+result = converter.convert(100, "USD", "EUR")
+print(f"Amount: {result.result}")
+print(f"Rate: {result.rate.rate}")
+print(f"Source: {result.rate.source}")
 
-## 📁 YAML Caching
-
-The module uses beautiful YAML files for caching with automatic comments:
-
-```yaml
-# Currency Exchange Rates - Django CFG
-# Source: CBR API
-# Generated: 2024-01-15 14:30:25 UTC
-# Total currencies: 43
-# Cache TTL: 24 hours
-
-source: cbr
-timestamp: 2024-01-15T14:30:25.123456
-
-metadata:
-  count: 43
-  cache_version: '1.0'
-  format: 'YAML'
-  description: 'Currency rates from CBR API'
-  updated_at: '2024-01-15 14:30:25 UTC'
-  ttl_hours: 24
-  next_update: '2024-01-16 14:30:25 UTC'
-
-# Currency Rates
-rates:
-  USD: 80.749800    # US Dollar
-  EUR: 93.627400    # Euro
-  GBP: 108.422800   # British Pound
-  JPY: 0.551940     # Japanese Yen
-  CNY: 11.200000    # Chinese Yuan
-  KRW: 0.063500     # South Korean Won
-  RUB: 1.000000     # Russian Ruble
-  # ... more currencies
+# Get all supported currencies  
+currencies = converter.get_supported_currencies()
+print(f"Fiat currencies: {len(currencies.yfinance.fiat)}")
+print(f"Cryptocurrencies: {len(currencies.coingecko.crypto)}")
 ```
 
-## 🔧 Configuration
+## 🎯 Provider Logic
 
-### DjangoConfig Integration
+### YFinance Client
+- **Purpose**: Fiat currency pairs only
+- **Symbols**: `EURUSD=X`, `GBPJPY=X`, etc.
+- **Dynamic Loading**: Uses `yf.Lookup().get_currency()` to get all available pairs
+- **Coverage**: All major and minor fiat currencies
 
-```python
-from django_cfg import DjangoConfig
-
-class MyConfig(DjangoConfig):
-    project_name: str = "My Project"
-    
-    # Optional: Custom cache directory (default: src/django_cfg/cache/currency/)
-    currency_cache_dir: str = "/path/to/cache"
-    
-    # Telegram integration (optional)
-    telegram: TelegramConfig = TelegramConfig(
-        bot_token="your_bot_token",
-        chat_id="your_chat_id"
-    )
-
-config = MyConfig()
-```
+### CoinGecko Client  
+- **Purpose**: Cryptocurrency pairs only
+- **API**: CoinGecko Public API v3
+- **Dynamic Loading**: Uses `get_coins_list()` and `get_supported_vs_currencies()`
+- **Coverage**: 17,000+ cryptocurrencies
 
-### Cache Configuration
+## 🔄 Conversion Routes
 
 ```python
-from django_cfg.modules.django_currency import CurrencyCache
-
-# Custom cache settings
-cache = CurrencyCache(
-    cache_dir=Path("/custom/cache/dir"),
-    ttl=3600,  # 1 hour TTL
-    max_size=500  # Max 500 items in memory
-)
-```
-
-## 📊 Data Sources
-
-### 1. Central Bank of Russia (CBR)
-- **Best for**: RUB-based conversions
-- **URL**: `https://www.cbr-xml-daily.ru/daily_json.js`
-- **Currencies**: 40+ major currencies
-- **Update**: Daily
-
-### 2. European Central Bank (ECB)
-- **Best for**: EUR-based conversions  
-- **URL**: `https://api.exchangerate-api.com/v4/latest/EUR`
-- **Currencies**: 170+ currencies
-- **Update**: Daily
-
-### 3. Fallback Converter
-- **Library**: `currency_converter`
-- **Best for**: Historical rates and exotic pairs
-- **Offline**: Works without internet (cached data)
-
-## 🎨 Advanced Features
-
-### Export to YAML
+# Direct routes
+USD → EUR    # YFinance
+BTC → USD    # CoinGecko  
 
-```python
-currency = DjangoCurrency()
-
-# Export current rates to formatted YAML
-yaml_content = currency.cache.export_rates_yaml('cbr')
-print(yaml_content)
-
-# Save to file
-from pathlib import Path
-output_file = Path('currency_rates.yaml')
-currency.cache.export_rates_yaml('cbr', output_file)
+# Indirect routes (via USD bridge)
+EUR → BTC    # EUR → USD → BTC
+ETH → BTC    # ETH → USD → BTC
 ```
 
-### Cache Management
+## 📊 Data Models
 
-```python
-currency = DjangoCurrency()
+All responses use Pydantic v2 models:
 
-# Get cache information
-cache_info = currency.get_config_info()
-print(f"Cache directory: {cache_info['cache_directory']}")
-print(f"Memory cache size: {cache_info['cache_info']['memory_cache']['size']}")
-
-# Force refresh rates
-success = currency.refresh_rates()
-print(f"Refresh {'successful' if success else 'failed'}")
+```python
+class Rate(BaseModel):
+    source: str           # "yfinance" or "coingecko"
+    base_currency: str    # "USD"
+    quote_currency: str   # "EUR" 
+    rate: float          # 0.85
+    timestamp: datetime   # Auto-generated
 
-# Clear cache
-currency.cache.clear_cache('cbr')  # Clear specific source
-currency.cache.clear_cache()       # Clear all
+class ConversionResult(BaseModel):
+    request: ConversionRequest
+    result: float
+    rate: Rate
+    path: Optional[str]   # "EUR→USD→BTC" for indirect
 ```
 
-### Telegram Alerts
-
-```python
-from django_cfg.modules.django_currency import DjangoCurrency
+## ⚡ Caching
 
-# Send currency alert
-DjangoCurrency.send_currency_alert(
-    "USD/RUB rate exceeded 85.00!",
-    rates={"USD/RUB": 85.25, "EUR/RUB": 92.15}
-)
-```
+- **TTL Cache**: Configurable time-to-live (default: 5 minutes)
+- **Per-Source**: Separate cache for each provider
+- **Statistics**: Cache hit/miss monitoring
+- **Memory Efficient**: Uses `cachetools.TTLCache`
 
 ## 🧪 Testing
 
-Run the included test script:
-
 ```bash
-cd /path/to/django_currency/
+cd django_cfg/modules/django_currency/
 python test_currency.py
 ```
 
-Example output:
+## 🎨 Example Output
+
 ```
 🧪 Testing Django Currency Module...
 ==================================================
 
-💱 Basic Currency Conversion:
-✅ 100 USD = 8074.98 RUB
+💱 Test 1: Fiat Currency Conversion
+✅ 100 USD = 85.23 EUR
 
-🔄 Using Convenience Function:
-✅ 100 USD = 93.15 EUR
+📊 Test 2: Exchange Rate  
+✅ 1 USD = 0.8523 EUR
 
-📊 Exchange Rates:
-✅ 1 USD = 80.7498 RUB
+🪙 Test 3: Crypto Conversion
+✅ 1 BTC = 45,230.50 USD
 
-📋 Available Currencies:
-✅ Total currencies: 43
-✅ Major currencies available: USD, EUR, GBP, JPY, CNY, KRW, RUB
+📋 Test 4: Supported Currencies
+✅ YFinance fiat currencies: 168
+✅ CoinGecko cryptocurrencies: 17,247  
+✅ CoinGecko vs_currencies: 61
 
 🎉 All tests completed successfully!
 ```
 
-## 📦 Dependencies
+## 🚫 No Fallbacks Policy
 
-- `pyyaml` - YAML parsing and generation
-- `requests` - HTTP requests for API calls
-- `cachetools` - TTL memory caching
-- `currency_converter` - Fallback converter (optional)
+- **Strict Mode**: If API fails, module fails (no backup hardcoded lists)
+- **Dynamic Only**: All currencies loaded from live APIs
+- **Fail Fast**: Clear error messages when providers unavailable
 
-## 🔍 Error Handling
+## 📝 Error Handling
 
 ```python
-currency = DjangoCurrency()
-
-# Graceful error handling
 try:
-    result = currency.convert(100, 'USD', 'INVALID')
-except CurrencyConversionError as e:
-    print(f"Conversion failed: {e}")
-
-# Silent failures
-result = currency.convert(100, 'USD', 'INVALID', fail_silently=True)
-# Returns 0.0 on failure
+    result = convert_currency(100, "INVALID", "USD")
+except CurrencyNotFoundError:
+    print("Currency not supported")
+except RateFetchError:
+    print("API temporarily unavailable")
+except ConversionError:
+    print("Conversion failed")
 ```
 
-## 🎯 Use Cases
-
-### E-commerce
-```python
-# Convert product prices
-product_price_usd = 99.99
-price_rub = convert_currency(product_price_usd, 'USD', 'RUB')
-```
-
-### Financial Applications
-```python
-# Portfolio conversion
-currency = DjangoCurrency()
-portfolio_values = [1000, 2000, 1500]  # USD, EUR, GBP
-currencies = ['USD', 'EUR', 'GBP']
-target_currency = 'RUB'
-
-rub_values = currency.convert_multiple(
-    portfolio_values, 
-    currencies, 
-    [target_currency] * len(currencies)
-)
-total_rub = sum(rub_values)
-```
-
-### Tax Calculations
-```python
-# For CarAPIS tax calculator
-def calculate_vehicle_tax(vehicle_price_krw: float, target_country: str):
-    currency = DjangoCurrency()
-    
-    # Convert KRW to local currency
-    if target_country == 'RU':
-        price_rub = currency.convert(vehicle_price_krw, 'KRW', 'RUB')
-        return calculate_russian_tax(price_rub)
-    elif target_country == 'US':
-        price_usd = currency.convert(vehicle_price_krw, 'KRW', 'USD')
-        return calculate_us_tax(price_usd)
-```
-
-## 🔗 Integration with Django CFG
-
-The module automatically integrates with other django-cfg services:
-
-- **📧 Email Service**: Send rate alerts via email
-- **📱 Telegram Service**: Send notifications to Telegram
-- **📊 Logger Service**: Structured logging with configuration
-- **⚙️ Configuration**: Auto-discovery of DjangoConfig settings
-
-## 📈 Performance
-
-- **Memory Cache**: Sub-millisecond lookups for cached rates
-- **File Cache**: ~10ms for file-based cache hits  
-- **API Calls**: ~200-500ms for fresh data from APIs
-- **Batch Operations**: Optimized for multiple conversions
-- **YAML Export**: ~50ms for 100+ currencies with formatting
-
-## 🛠️ Development
-
-### Project Structure
-```
-django_currency/
-├── __init__.py          # Public API exports
-├── service.py           # Main DjangoCurrency service
-├── converter.py         # Currency conversion logic
-├── cache.py             # YAML caching system
-├── test_currency.py     # Test suite
-└── README.md           # This file
-```
-
-### Contributing
-
-1. Follow django-cfg module patterns
-2. Use YAML for configuration files
-3. Include comprehensive error handling
-4. Add tests for new features
-5. Update documentation
-
 ---
 
-**Made with ❤️ for the Django CFG ecosystem**
-
-*Beautiful currency conversion with intelligent caching and seamless Django integration.*
+**Built with ❤️ following KISS principles and decomposed architecture**

django_cfg/modules/django_currency/__init__.py

@@ -1,47 +1,105 @@
 """
-Django Currency Service for django_cfg.
+Django Currency Module - Simple universal currency converter.
 
-Auto-configuring currency conversion service that integrates with DjangoConfig.
+Provides seamless bidirectional conversion between fiat and cryptocurrency rates.
+Uses YFinance for fiat/major crypto pairs and CoinGecko for broad crypto coverage.
 """
 
-from .service import DjangoCurrency, CurrencyError, CurrencyConfigError
-from .converter import CurrencyConverter
-from .cache import CurrencyCache
-
-# Convenience functions
-def convert_currency(
-    amount: float, 
-    from_currency: str, 
-    to_currency: str,
-    fail_silently: bool = False
-) -> float:
-    """Convert currency using auto-configured service."""
-    currency = DjangoCurrency()
-    return currency.convert(
-        amount=amount,
-        from_currency=from_currency,
-        to_currency=to_currency,
-        fail_silently=fail_silently
-    )
-
-def get_exchange_rate(from_currency: str, to_currency: str) -> float:
-    """Get exchange rate using auto-configured service."""
-    currency = DjangoCurrency()
-    return currency.get_rate(from_currency, to_currency)
-
-def get_available_currencies() -> set:
-    """Get available currencies."""
-    currency = DjangoCurrency()
-    return currency.get_available_currencies()
-
-# Export public API
+# Core functionality
+from .core import (
+    CurrencyConverter,
+    Rate,
+    ConversionRequest,
+    ConversionResult,
+    SupportedCurrencies,
+    YFinanceCurrencies,
+    CoinGeckoCurrencies,
+    CurrencyError,
+    CurrencyNotFoundError,
+    RateFetchError,
+    ConversionError,
+    CacheError
+)
+
+# Utilities
+from .utils import CacheManager
+
+# Clients
+from .clients import YFinanceClient, CoinGeckoClient
+
+# Database tools
+from .database import (
+    CurrencyDatabaseLoader,
+    DatabaseLoaderConfig,
+    create_database_loader,
+    load_currencies_to_database_format
+)
+
+# Simple public API
+def convert_currency(amount: float, from_currency: str, to_currency: str) -> float:
+    """
+    Convert currency amount.
+    
+    Args:
+        amount: Amount to convert
+        from_currency: Source currency code
+        to_currency: Target currency code
+        
+    Returns:
+        Converted amount
+    """
+    converter = CurrencyConverter()
+    result = converter.convert(amount, from_currency, to_currency)
+    return result.result
+
+
+def get_exchange_rate(base: str, quote: str) -> float:
+    """
+    Get exchange rate between currencies.
+    
+    Args:
+        base: Base currency code
+        quote: Quote currency code
+        
+    Returns:
+        Exchange rate
+    """
+    converter = CurrencyConverter()
+    result = converter.convert(1.0, base, quote)
+    return result.rate.rate
+
+
 __all__ = [
-    'DjangoCurrency',
-    'CurrencyConverter', 
-    'CurrencyCache',
-    'CurrencyError',
-    'CurrencyConfigError',
-    'convert_currency',
-    'get_exchange_rate',
-    'get_available_currencies'
+    # Core converter and models
+    "CurrencyConverter",
+    "Rate", 
+    "ConversionRequest",
+    "ConversionResult",
+    "SupportedCurrencies",
+    "YFinanceCurrencies", 
+    "CoinGeckoCurrencies",
+    
+    # Exceptions
+    "CurrencyError",
+    "CurrencyNotFoundError",
+    "RateFetchError", 
+    "ConversionError",
+    "CacheError",
+    
+    # Utilities
+    "CacheManager",
+    
+    # Clients
+    "YFinanceClient",
+    "CoinGeckoClient",
+    
+    # Database tools
+    "CurrencyDatabaseLoader",
+    "DatabaseLoaderConfig",
+    "create_database_loader",
+    "load_currencies_to_database_format",
+    
+    # Public API
+    "convert_currency",
+    "get_exchange_rate"
 ]

django_cfg/modules/django_currency/clients/__init__.py

@@ -0,0 +1,11 @@
+"""
+Currency data clients for fetching rates from external APIs.
+"""
+
+from .yfinance_client import YFinanceClient
+from .coingecko_client import CoinGeckoClient
+
+__all__ = [
+    'YFinanceClient', 
+    'CoinGeckoClient'
+]