Metadata-Version: 2.4
Name: jyapyforex
Version: 0.1.1
Summary: A Python library to get historical forex rates from various providers.
Author-email: Krishna Kuruvadi <krishnakuruvadi@gmail.com>
Project-URL: Homepage, https://github.com/JustYetAnother/jyapyforex
Project-URL: Bug Tracker, https://github.com/JustYetAnother/jyapyforex/issues
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Office/Business :: Financial
Classifier: Intended Audience :: Developers
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28.1
Dynamic: license-file

# Just Yet Another library for forex conversions

A Python library for fetching historical foreign exchange (forex) rates from various popular providers. This library aims to simplify currency conversion for a given date by abstracting away the complexities of different API integrations.

## Features

* **Unified Interface:** Get conversion rates using a single, consistent API.
* **Multiple Provider Support:** Designed to support multiple forex API providers (currently includes Fixer.io, ExchangeRateHost, OpenExchangeRates).
* **Historical Data:** Fetch rates for specific past dates.
* **Single and Multiple Currency Conversions:** Convert to one or multiple currencies in a single operation.
* **Secure API Key Handling:** Utilizes environment variables for API key management.

## Installation

You can install `jyapyforex` using pip:

```bash
pip install jyapyforex
```

## API Keys

This library requires API keys from the forex rate providers you wish to use. For security, it's highly recommended to store your API keys as environment variables.

**Example for Fixer.io:**

1.  Sign up for an API key at [Fixer.io](https://fixer.io/).
2.  Set your API key as an environment variable:

    * **Linux/macOS:**
        ```bash
        export FIXER_IO_API_KEY="your_fixer_io_api_key_here"
        ```
        (Add this line to your `~/.bashrc`, `~/.zshrc`, or equivalent for persistence)

    * **Windows (Command Prompt):**
        ```cmd
        set FIXER_IO_API_KEY="your_fixer_io_api_key_here"
        ```
        (For persistence, you'll need to set it via System Properties -> Environment Variables)

    * **Windows (PowerShell):**
        ```powershell
        $env:FIXER_IO_API_KEY="your_fixer_io_api_key_here"
        ```
        (For persistence, you'll need to set it in your PowerShell profile)

Alternatively, you can pass the API keys directly to the `ForexConverter` constructor as a dictionary.

Following are the expected environment variables for supported providers:
|     Provider         |            Key              |
| -------------------- | --------------------------- |
| Fixer.io             | FIXER_IO_API_KEY            |
| Open Exchange Rates  | OPEN_EXCHANGE_RATES_API_KEY |
| Exchange Rate Host   | EXCHANGE_RATE_HOST_API_KEY  |

## Usage

Here's how to use the `ForexConverter` to get historical exchange rates:

```python
from jyapyforex import ForexConverter

# Initialize the converter. It will automatically look for API keys
# in environment variables or you can pass them explicitly.
try:
    converter = ForexConverter()

    # Example 1: Get the conversion rate from USD to EUR on a specific date
    date = "2023-01-15"
    from_currency = "USD"
    to_currency = "EUR"

    rate = converter.get_conversion_rate(from_currency, to_currency, date)
    print(f"1 {from_currency} = {rate:.4f} {to_currency} on {date}")

    # Example 2: Convert an amount
    amount = 100.0
    converted_amount = converter.convert_amount(amount, from_currency, to_currency, date)
    print(f"{amount} {from_currency} = {converted_amount:.2f} {to_currency} on {date}")

    # Example 3: Convert an amount to multiple currencies at once
    to_currencies = ["EUR", "GBP", "JPY", "CAD"]
    multi_conversions = converter.convert_amount_to_multiple_currencies(
        amount=100.0,
        from_currency="USD",
        to_currencies=to_currencies,
        date="2023-01-15"
    )
    print(f"100 USD on 2023-01-15 converts to:")
    for currency, converted_amount in multi_conversions.items():
        print(f"  {converted_amount:.2f} {currency}")

    # Example 4: If you want to pass API keys directly (less secure for production)
    # api_keys = {
    #     "FIXER_IO_API_KEY": "your_api_key_here_if_not_using_env_vars"
    # }
    # converter_with_keys = ForexConverter(api_keys=api_keys)
    # rate_direct = converter_with_keys.get_conversion_rate("GBP", "JPY", "2024-05-20")
    # print(f"1 GBP = {rate_direct:.4f} JPY on 2024-05-20 (using direct keys)")

except ValueError as e:
    print(f"Configuration Error: {e}")
except Exception as e:
    print(f"An error occurred: {e}")

```
### Command-Line Interface (CLI)

After installation, you can use the `jyapyforex` command directly from your terminal:

* **Get a conversion rate:**
    ```bash
    jyapyforex rate USD EUR 2023-01-15
    ```
* **Convert an amount:**
    ```bash
    jyapyforex convert 100 USD EUR 2023-01-15
    ```
* **Get help:**
    ```bash
    jyapyforex --help
    jyapyforex rate --help
    ```
* **Enable debug logging:**
    ```bash
    jyapyforex --debug rate USD EUR 2023-01-15
    ```

## Testing

The library includes comprehensive unit tests covering all functionality. To run the tests:

```bash
# Install pytest if not already installed
pip install pytest

# Run all tests
pytest test/test_converters.py -v

# Run specific test class
pytest test/test_converters.py::TestConvertAmountToMultipleCurrencies -v
```

The test suite includes:
* **Initialization tests:** Validation of API key loading from environment and configuration
* **Conversion rate tests:** Fetching rates for single currency pairs
* **Single currency conversion tests:** Converting amounts between two currencies
* **Multiple currency conversion tests:** Converting amounts to multiple target currencies at once
* **Error handling tests:** Proper exception handling for invalid inputs and API failures
* **Edge case tests:** Zero amounts, float precision, and partial failures

## API Methods

### `get_conversion_rate(from_currency, to_currency, date) -> float`

Gets the exchange rate between two currencies for a specific date.

**Parameters:**
- `from_currency` (str): Three-letter currency code (e.g., "USD")
- `to_currency` (str): Three-letter currency code (e.g., "EUR")
- `date` (str): Date in "YYYY-MM-DD" format

**Returns:** Float representing the exchange rate

### `convert_amount(amount, from_currency, to_currency, date) -> float`

Converts a single amount from one currency to another for a specific date.

**Parameters:**
- `amount` (float): The amount to convert
- `from_currency` (str): Three-letter currency code
- `to_currency` (str): Three-letter currency code
- `date` (str): Date in "YYYY-MM-DD" format

**Returns:** Float representing the converted amount

### `convert_amount_to_multiple_currencies(amount, from_currency, to_currencies, date) -> Dict[str, float]`

Converts a single amount from one currency to multiple target currencies for a specific date.

**Parameters:**
- `amount` (float): The amount to convert
- `from_currency` (str): Three-letter currency code
- `to_currencies` (List[str]): List of three-letter currency codes (e.g., ["EUR", "GBP", "JPY"])
- `date` (str): Date in "YYYY-MM-DD" format

**Returns:** Dictionary mapping currency codes to converted amounts

**Example:**
```python
result = converter.convert_amount_to_multiple_currencies(
    amount=100,
    from_currency="USD",
    to_currencies=["EUR", "GBP", "JPY"],
    date="2023-01-15"
)
# Returns: {"EUR": 92.50, "GBP": 79.30, "JPY": 12450.00}
```

**Note:** If conversion to some currencies fails, the method continues with other currencies and returns a partial result. It only raises an exception if all conversions fail.

## Supported Currencies

The supported currencies depend on the integrated API providers. Generally, popular currencies like USD, EUR, GBP, JPY, CAD, AUD, CHF, etc., are widely supported. Refer to the documentation of each specific API provider (e.g., Fixer.io) for a complete list.

## Adding More API Providers

To add support for a new API provider:

1.  Create a new Python file in `src/jyapyforex/api_clients/` (e.g., `open_exchange_rates.py`).
2.  Implement a class for the new API client (e.g., `OpenExchangeRatesClient`) with a `get_historical_rate` method that matches the signature of `FixerIOClient`.
3.  Import and instantiate your new client in `src/jyapyforex/converters.py` within the `_load_api_clients` method, checking for its corresponding environment variable or passed API key.

## Contributing

Contributions are welcome! Please feel free to open issues or submit pull requests on the [GitHub repository](https://github.com/JustYetAnother/jyapyforex).

## License

This project is licensed under the MIT License - see the `LICENSE` file for details.
