Metadata-Version: 2.3
Name: bcc-rates
Version: 1.0.1
Summary: Currency exchange rates and converter using live data from Banque Centrale du Congo (BCC)
Author: Edimedia Mutoke
Author-email: Edimedia Mutoke <eddycondor07@gmail.com>
Requires-Dist: aiohttp>=3.13.1
Requires-Dist: beautifulsoup4>=4.14.2
Requires-Dist: dinero>=0.4.0
Requires-Dist: requests>=2.32.5
Requires-Python: >=3.12
Description-Content-Type: text/markdown

# 🏦 BCC Rates

[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**BCC Rates** is a Python library and command-line tool for fetching real-time currency exchange rates from the **Banque Centrale du Congo (BCC)**. It provides both synchronous and asynchronous APIs for seamless integration into your applications.

## 🌟 Features

- 📊 **Real-time exchange rates** from BCC official website
- 🔄 **Synchronous and asynchronous** API support
- 💱 **Currency conversion** with precise calculations
- 🖥️ **Command-line interface** for quick conversions
- 🎯 **Interactive mode** for multiple conversions
- 🔧 **Type hints** for better development experience

## 🚀 Installation

### From PyPI (recommended)
```bash
pip install bcc-rates
```

### From GitHub
```bash
pip install git+https://github.com/oxiliere/bcc_rates.git
```

### From source (development)
```bash
git clone https://github.com/oxiliere/bcc_rates.git
cd bcc_rates
pip install -e .
```

### Using uv (recommended for development)
```bash
git clone https://github.com/oxiliere/bcc_rates.git
cd bcc_rates
uv sync
```

## 📖 Quick Start

### Command Line Usage

After installation, use the `bcc_exchange` command:

```bash
# Show all available exchange rates
bcc_exchange --list

# Convert currencies
bcc_exchange 100 USD EUR

# Interactive mode
bcc_exchange --interactive

# Quiet mode (result only)
bcc_exchange --quiet 1000 EUR CDF
```

### Python API

#### Synchronous Usage

```python
from bcc_rates import BCCBankSource
from dinero import Dinero, currencies

# Initialize the BCC source
bcc = BCCBankSource()

# Get all exchange rates
rates = bcc.sync()
print(f"Found {len(rates)} exchange rates")

# Get specific currency rate
usd_rate = bcc.get_value("USD")
print(f"1 USD = {usd_rate.amount} CDF")

# Currency conversion
amount = Dinero(100, currencies.USD)
converted = bcc.to(amount, "EUR")
print(f"100 USD = {converted.amount} EUR")
```

#### Asynchronous Usage

```python
import asyncio
from bcc_rates import AsyncBCCBankSource
from dinero import Dinero, currencies

async def main():
    # Initialize async BCC source
    bcc = AsyncBCCBankSource()
    
    # Get all exchange rates
    rates = await bcc.sync()
    print(f"Found {len(rates)} exchange rates")
    
    # Get specific currency rate
    eur_rate = await bcc.get_value("EUR")
    print(f"1 EUR = {eur_rate.amount} CDF")
    
    # Currency conversion
    amount = Dinero(50, currencies.GBP)
    converted = await bcc.to(amount, "USD")
    print(f"50 GBP = {converted.amount} USD")

# Run async function
asyncio.run(main())
```

## 🛠️ Command Line Interface

The `bcc_exchange` command provides a powerful CLI for currency operations:

### Basic Commands

```bash
# Show help
bcc_exchange --help

# List all available currencies and rates
bcc_exchange --list

# Convert 100 USD to EUR
bcc_exchange 100 USD EUR

# Convert 1000 EUR to CDF (Congolese Franc)
bcc_exchange 1000 EUR CDF

# Use async mode for better performance
bcc_exchange --async-mode 50 GBP USD
```

### Interactive Mode

```bash
bcc_exchange --interactive
```

This starts an interactive session where you can perform multiple conversions:

```
🔄 Interactive Currency Converter
Enter 'quit' to exit
------------------------------
Available currencies: AOA, AUD, BIF, CAD, CDF, CHF, CNY, EUR, GBP, JPY, RWF, TZS, UGX, USD, XAF, XDR, ZAR, ZMW

Enter amount (or 'quit'): 100
From currency: USD
To currency: EUR
✅ 100.00 USD = 86.15 EUR

Enter amount (or 'quit'): quit
```

### Quiet Mode

For scripting and automation:

```bash
# Returns only the conversion result
bcc_exchange --quiet 100 USD EUR
# Output: 86.1487
```

## 📚 API Reference

### Classes

#### `BCCBankSource` (Synchronous)

```python
class BCCBankSource:
    def __init__(self, url: str = "https://www.bcc.cd/"):
        """Initialize BCC source with optional custom URL."""
    
    def sync(self, cache: bool = False) -> List[SourceValue]:
        """Fetch all exchange rates from BCC."""
    
    def get_value(self, currency: str) -> SourceValue:
        """Get exchange rate for specific currency."""
    
    def get_values(self, currencies: List[str] = None, cache: bool = False) -> List[SourceValue]:
        """Get exchange rates for multiple currencies."""
    
    def to(self, base: Dinero, target: str | Currency) -> Dinero:
        """Convert currency amount to target currency."""
```

#### `AsyncBCCBankSource` (Asynchronous)

```python
class AsyncBCCBankSource:
    def __init__(self, url: str = "https://www.bcc.cd/"):
        """Initialize async BCC source with optional custom URL."""
    
    async def sync(self, cache: bool = False) -> List[SourceValue]:
        """Fetch all exchange rates from BCC."""
    
    async def get_value(self, currency: str) -> SourceValue:
        """Get exchange rate for specific currency."""
    
    async def get_values(self, currencies: List[str] = None, cache: bool = False) -> List[SourceValue]:
        """Get exchange rates for multiple currencies."""
    
    async def to(self, base: Dinero, target: str | Currency) -> Dinero:
        """Convert currency amount to target currency."""
```

#### `SourceValue`

```python
@dataclass
class SourceValue:
    currency: str  # Currency code (e.g., "USD", "EUR")
    amount: Decimal  # Exchange rate in CDF
```

### Supported Currencies

The library supports all currencies available on the BCC website, including:

- **USD** - US Dollar
- **EUR** - Euro
- **GBP** - British Pound
- **CAD** - Canadian Dollar
- **CHF** - Swiss Franc
- **JPY** - Japanese Yen
- **CNY** - Chinese Yuan
- **AUD** - Australian Dollar
- **ZAR** - South African Rand
- **CDF** - Congolese Franc (base currency)
- And many more...

## 🧪 Development

### Setting up Development Environment

```bash
# Clone the repository
git clone https://github.com/oxiliere/bcc_rates.git
cd bcc_rates

# Install with uv (recommended)
uv sync

# Or with pip
pip install -e ".[dev]"
```

### Running Tests

```bash
# Run all tests
uv run python -m pytest

# Run with coverage
uv run python -m pytest --cov=bcc_rates

# Run specific test file
uv run python src/tests.py
```

### Running CLI in Development

```bash
# Using uv (recommended)
uv run python -m bcc_rates --help
uv run python -m bcc_rates 100 USD EUR

# Direct execution
uv run python src/bcc_rates/cli.py --help
```

### Code Quality

```bash
# Format code
uv run black src/

# Type checking
uv run mypy src/

# Linting
uv run flake8 src/
```

## 📋 Examples

### Basic Currency Conversion

```python
from bcc_rates import BCCBankSource
from dinero import currencies, Dinero

bcc = BCCBankSource()

# Convert 100 USD to EUR
usd_amount = Dinero(100, currencies.USD)
eur_amount = bcc.to(usd_amount, "EUR")
print(f"100 USD = {eur_amount.amount:.2f} EUR")

# Convert 1000 EUR to CDF
eur_amount = Dinero(1000, currencies.EUR)
cdf_amount = bcc.to(eur_amount, "CDF")
print(f"1000 EUR = {cdf_amount.amount:,.2f} CDF")
```

### Batch Processing

```python
from bcc_rates import BCCBankSource

bcc = BCCBankSource()

# Get rates for specific currencies
currencies_of_interest = ["USD", "EUR", "GBP", "CAD"]
rates = bcc.get_values(currencies_of_interest)

for rate in rates:
    print(f"1 {rate.currency} = {rate.amount:,.4f} CDF")
```

### Async Batch Processing

```python
import asyncio
from bcc_rates import AsyncBCCBankSource

async def get_multiple_rates():
    bcc = AsyncBCCBankSource()
    
    # Fetch all rates
    rates = await bcc.sync(cache=True)
    
    # Process rates
    major_currencies = ["USD", "EUR", "GBP", "JPY"]
    for currency in major_currencies:
        try:
            rate = await bcc.get_value(currency)
            print(f"1 {currency} = {rate.amount:,.4f} CDF")
        except ValueError:
            print(f"{currency} not available")

asyncio.run(get_multiple_rates())
```

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

### Development Guidelines

1. **Fork** the repository
2. **Create** a feature branch (`git checkout -b feature/amazing-feature`)
3. **Write tests** for your changes
4. **Ensure** all tests pass
5. **Commit** your changes (`git commit -m 'Add amazing feature'`)
6. **Push** to the branch (`git push origin feature/amazing-feature`)
7. **Open** a Pull Request

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- **Banque Centrale du Congo (BCC)** for providing the exchange rate data
- **Dinero** library for currency handling
- **BeautifulSoup** for HTML parsing
- **aiohttp** for async HTTP requests

## 📞 Support

If you encounter any issues or have questions:

1. Check the [Issues](https://github.com/oxiliere/bcc_rates/issues) page
2. Create a new issue if your problem isn't already reported
3. Provide detailed information about your environment and the issue

## 🔗 Links

- **PyPI Package**: [https://pypi.org/project/bcc-rates/](https://pypi.org/project/bcc-rates/)
- **Source Code**: [https://github.com/oxiliere/bcc_rates](https://github.com/oxiliere/bcc_rates)
- **BCC Official Website**: [https://www.bcc.cd/](https://www.bcc.cd/)

---

Made with ❤️ for the Congolese developer community
