ecb-rate 0.5.2__py3-none-any.whl

ecb_rate/cli.py

@@ -0,0 +1,133 @@
+"""
+CLI entry point for ecb_rate.
+
+Examples:
+    ecb_rate TRY
+    ecb_rate try
+    ecb_rate TRY --specific-date 2025-06-06
+    ecb_rate TRY --pretty
+"""
+
+import argparse
+import asyncio
+import sys
+from datetime import date
+
+from pydantic import ValidationError
+from importlib.metadata import metadata
+
+from ecb_rate.client import ECBJsonClient
+from ecb_rate.models import CliInputError, EcbRateError, QueryParams, RatePoint
+from ecb_rate.service import EcbJsonParser, ExchangeRateService
+
+
+class CliApplication:
+    """
+    Application entry point coordinating argparse and the service layer.
+    """
+
+    def __init__(self) -> None:
+        client = ECBJsonClient(timeout_seconds=10)
+        parser = EcbJsonParser()
+        self._service = ExchangeRateService(
+            client=client,
+            parser=parser,
+        )
+
+    def run(self, argv: list[str] | None = None) -> int:
+        try:
+            args = self._parse_args(argv)
+            query = self._build_query(args)
+            result = asyncio.run(self._service.get_rate(query))
+            self._print_result(result, pretty=args.pretty)
+            return 0
+        except (CliInputError, EcbRateError) as exc:
+            print(f"Error: {exc}", file=sys.stderr)
+            return 1
+
+    @staticmethod
+    def _parse_args(argv: list[str] | None) -> argparse.Namespace:
+        package_metadata = metadata("ecb-rate")
+
+        project_name = package_metadata["Name"].replace("-", "_")
+        project_version = package_metadata["Version"]
+        project_description = package_metadata["Summary"]
+
+        parser = argparse.ArgumentParser(
+            prog=project_name,
+            description=project_description,
+        )
+
+        parser.add_argument(
+            "--version",
+            action="version",
+            version=f"%(prog)s {project_version}",
+            help="Show the installed CLI version and exit.",
+        )
+        parser.add_argument(
+            "target_currency",
+            nargs="?",
+            help="Target currency code, for example TRY or USD.",
+        )
+        parser.add_argument(
+            "--specific-date",
+            dest="specific_date",
+            default=None,
+            help="Specific date in YYYY-MM-DD format. Defaults to today.",
+        )
+        parser.add_argument(
+            "--pretty",
+            action="store_true",
+            help="Print formatted output with base currency, target currency, and rate date.",
+        )
+
+        args = parser.parse_args(argv)
+
+        if args.target_currency is None:
+            parser.error("the following arguments are required: target_currency")
+
+        return args
+
+    @staticmethod
+    def _build_query(args: argparse.Namespace) -> QueryParams:
+        if args.specific_date is None:
+            specific_date = date.today()
+        else:
+            try:
+                specific_date = date.fromisoformat(args.specific_date)
+            except ValueError as exc:
+                raise CliInputError(
+                    f"Invalid --specific-date: {args.specific_date}. Expected YYYY-MM-DD."
+                ) from exc
+
+        try:
+            return QueryParams(
+                target_currency=args.target_currency,
+                specific_date=specific_date,
+            )
+        except (ValidationError, ValueError) as exc:
+            raise CliInputError(str(exc)) from exc
+
+    @staticmethod
+    def _print_result(rate_point: RatePoint, pretty: bool = False) -> None:
+        if not pretty:
+            print(f"{rate_point.rate:.4f}")
+            return
+
+        print(f"Base currency:   {rate_point.base_currency.code}")
+        print(f"Target currency: {rate_point.target_currency.code}")
+        print()
+
+        print(
+            f"{rate_point.date.isoformat()}: "
+            f"1 {rate_point.base_currency.code} = {rate_point.rate:.4f} {rate_point.target_currency.code}"
+        )
+
+
+def main() -> int:
+    app = CliApplication()
+    return app.run()
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

ecb_rate/client.py

@@ -0,0 +1,93 @@
+"""
+ECB-specific async JSON API client.
+"""
+
+from datetime import date
+from typing import Any
+
+import aiohttp
+
+from ecb_rate.custom_types import CurrencyType
+from ecb_rate.models import EcbApiError
+
+
+class ECBJsonClient:
+    """
+    Async HTTP client for the ECB Data Portal API.
+
+    This client is responsible for:
+    - building ECB-specific URLs
+    - executing HTTP requests
+    - returning parsed JSON responses
+    """
+
+    BASE_URL = "https://data-api.ecb.europa.eu/service/data/EXR"
+
+    def __init__(self, timeout_seconds: int = 10) -> None:
+        self._timeout = aiohttp.ClientTimeout(total=timeout_seconds)
+
+    async def fetch(
+        self,
+        currency: CurrencyType,
+        specific_date: date,
+    ) -> dict[str, Any]:
+        """
+        Fetch ECB time series data in jsondata format for a specific date.
+
+        Uses:
+            D.<CURRENCY>.EUR.SP00.A
+            format=jsondata
+            lastNObservations=1
+            endPeriod=<date>
+            details=dataonly
+
+        This returns the latest available observation up to the given date.
+        """
+        series_key = f"D.{currency.code}.EUR.SP00.A"
+
+        iso_formatted_date = specific_date.isoformat()
+        params = {
+            "format": "jsondata",
+            "lastNObservations": 1,
+            "endPeriod": iso_formatted_date,
+            "details": "dataonly",
+        }
+
+        headers = {
+            "Accept": "application/json",
+            "User-Agent": "ecb_rate/0.1.0",
+        }
+
+        url = f"{self.BASE_URL}/{series_key}"
+
+        try:
+            async with aiohttp.ClientSession(
+                timeout=self._timeout,
+                headers=headers,
+            ) as session:
+                async with session.get(url, params=params) as response:
+                    if response.status >= 400:
+                        text = await response.text()
+                        raise EcbApiError(
+                            f"HTTP error: {response.status} {response.reason}. "
+                            f"Response: {text}"
+                        )
+
+                    try:
+                        data = await response.json()
+
+                    except aiohttp.ContentTypeError as exc:
+                        text = await response.text()
+                        raise EcbApiError(
+                            f"Expected JSON but got different content: {text}"
+                        ) from exc
+
+                    if not isinstance(data, dict):
+                        raise EcbApiError("Expected JSON object as top-level response.")
+
+                    return data
+
+        except aiohttp.ClientError as exc:
+            raise EcbApiError(f"Network error: {exc}") from exc
+        except TimeoutError as exc:
+            raise EcbApiError("Request timeout.") from exc

ecb_rate/custom_types.py

@@ -0,0 +1,111 @@
+"""
+Custom shared types for ecb_rate.
+"""
+
+from enum import StrEnum
+
+
+class CurrencyType(StrEnum):
+    """
+    Supported currencies for the CLI.
+
+    Values are stored in lowercase. Use ``code`` for the ECB-compatible
+    uppercase representation.
+    """
+
+    AUD = "aud"
+    # Australian dollar (Australia)
+
+    BRL = "brl"
+    # Brazilian real (Brazil)
+
+    CAD = "cad"
+    # Canadian dollar (Canada)
+
+    CHF = "chf"
+    # Swiss franc (Switzerland)
+
+    CNY = "cny"
+    # Chinese yuan (China)
+
+    CZK = "czk"
+    # Czech koruna (Czech Republic)
+
+    DKK = "dkk"
+    # Danish krone (Denmark)
+
+    EUR = "eur"
+    # Euro (Eurozone)
+
+    GBP = "gbp"
+    # Pound sterling (United Kingdom)
+
+    HKD = "hkd"
+    # Hong Kong dollar (Hong Kong)
+
+    HUF = "huf"
+    # Hungarian forint (Hungary)
+
+    IDR = "idr"
+    # Indonesian rupiah (Indonesia)
+
+    ILS = "ils"
+    # Israeli shekel (Israel)
+
+    INR = "inr"
+    # Indian rupee (India)
+
+    ISK = "isk"
+    # Icelandic krona (Iceland)
+
+    JPY = "jpy"
+    # Japanese yen (Japan)
+
+    KRW = "krw"
+    # South Korean won (South Korea)
+
+    MXN = "mxn"
+    # Mexican peso (Mexico)
+
+    MYR = "myr"
+    # Malaysian ringgit (Malaysia)
+
+    NOK = "nok"
+    # Norwegian krone (Norway)
+
+    NZD = "nzd"
+    # New Zealand dollar (New Zealand)
+
+    PHP = "php"
+    # Philippine peso (Philippines)
+
+    PLN = "pln"
+    # Polish zloty (Poland)
+
+    RON = "ron"
+    # Romanian leu (Romania)
+
+    SEK = "sek"
+    # Swedish krona (Sweden)
+
+    SGD = "sgd"
+    # Singapore dollar (Singapore)
+
+    THB = "thb"
+    # Thai baht (Thailand)
+
+    TRY = "try"
+    # Turkish lira (Turkey)
+
+    USD = "usd"
+    # US dollar (United States)
+
+    ZAR = "zar"
+    # South African rand (South Africa)
+
+    @property
+    def code(self) -> str:
+        """
+        Return the ECB-compatible uppercase currency code.
+        """
+        return self.value.upper()

ecb_rate/models.py

@@ -0,0 +1,55 @@
+"""
+Shared models and exceptions for ecb_rate.
+"""
+
+from datetime import date
+from decimal import Decimal
+
+from pydantic import BaseModel, field_validator
+
+from ecb_rate.custom_types import CurrencyType
+
+
+class EcbRateError(Exception):
+    """Base exception for the application."""
+
+
+class CliInputError(EcbRateError):
+    """Raised when CLI input is invalid."""
+
+
+class EcbApiError(EcbRateError):
+    """Raised when the ECB API request or response is invalid."""
+
+
+class QueryParams(BaseModel):
+    """
+    Query parameters for the currency conversion request.
+
+    EUR is always the base currency.
+    """
+
+    target_currency: CurrencyType
+    specific_date: date
+
+    @field_validator("target_currency", mode="before")
+    @classmethod
+    def normalize_currency(cls, value: object) -> object:
+        """
+        Normalize currency input to lowercase before enum validation.
+        """
+        if isinstance(value, str) and not isinstance(value, CurrencyType):
+            return value.lower()
+
+        return value
+
+
+class RatePoint(BaseModel):
+    """
+    A single exchange-rate result for a specific date.
+    """
+
+    date: date
+    rate: Decimal
+    target_currency: CurrencyType
+    base_currency: CurrencyType = CurrencyType.EUR

ecb_rate/service.py

@@ -0,0 +1,89 @@
+"""
+Business logic for building EUR exchange rates from ECB JSON series.
+"""
+
+from datetime import date
+from decimal import Decimal
+from typing import Any
+
+from ecb_rate.client import ECBJsonClient
+from ecb_rate.custom_types import CurrencyType
+from ecb_rate.models import EcbApiError, QueryParams, RatePoint
+
+
+class EcbJsonParser:
+    """
+    Parser for ECB JSON responses.
+    """
+
+    def extract_ecb_rate(
+        self,
+        payload: dict[str, Any],
+    ) -> Decimal:
+        """
+        Extract the currency rate from ECB JSON payload.
+        """
+
+        try:
+            result = list(payload["dataSets"][0]["series"].values())[0]["observations"][
+                "0"
+            ][0]
+
+            if result is None:
+                raise EcbApiError("No exchange rate found.")
+        except (KeyError, IndexError, TypeError) as exc:
+            raise EcbApiError("Unexpected ECB JSON structure.") from exc
+
+        return Decimal(str(result))
+
+
+class ExchangeRateService:
+    """
+    High-level service that fetches ECB series and computes:
+
+        1 EUR = X target_currency
+    """
+
+    def __init__(
+        self,
+        client: ECBJsonClient,
+        parser: EcbJsonParser,
+    ) -> None:
+        self._client = client
+        self._parser = parser
+
+    async def get_rate(self, query: QueryParams) -> RatePoint:
+        """
+        Return the EUR -> target currency rate for the requested date.
+        """
+
+        if query.target_currency == CurrencyType.EUR:
+            return RatePoint(
+                target_currency=query.target_currency,
+                date=query.specific_date,
+                rate=Decimal("1"),
+            )
+
+        rate = await self._fetch_eur_to_currency(
+            currency=query.target_currency,
+            specific_date=query.specific_date,
+        )
+
+        return RatePoint(
+            target_currency=query.target_currency,
+            date=query.specific_date,
+            rate=rate,
+        )
+
+    async def _fetch_eur_to_currency(
+        self,
+        currency: CurrencyType,
+        specific_date: date,
+    ) -> Decimal:
+        payload = await self._client.fetch(
+            currency=currency,
+            specific_date=specific_date,
+        )
+        return self._parser.extract_ecb_rate(
+            payload=payload,
+        )

ecb_rate-0.5.2.dist-info/METADATA

@@ -0,0 +1,175 @@
+Metadata-Version: 2.4
+Name: ecb-rate
+Version: 0.5.2
+Summary: CLI for ECB JSON exchange rates.
+Author: PythBuster
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/PythBuster/ecb-rate
+Project-URL: Repository, https://github.com/PythBuster/ecb-rate
+Project-URL: Issues, https://github.com/PythBuster/ecb-rate/issues
+Keywords: ecb,exchange-rates,currency,cli,forex
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: <3.15,>=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp>=3.13.5
+Requires-Dist: pydantic>=2.12.5
+Dynamic: license-file
+
+# ecb-rate
+
+Simple CLI tool to fetch EUR-based exchange rates from the European Central Bank (ECB) API.
+
+Note: ECB euro foreign exchange reference rates are published for information purposes only.
+Using these rates for transaction purposes is strongly discouraged by the ECB.
+
+Official ECB reference:
+https://www.ecb.europa.eu/stats/policy_and_exchange_rates/euro_reference_exchange_rates/html/index.en.html
+
+---
+
+## Installation
+
+Using `uv` (recommended):
+
+    uv sync
+
+Or with pip:
+
+    pip install .
+
+---
+
+## Usage
+
+### Basic
+
+    ecb_rate TRY
+
+Output:
+
+    51.2795
+
+---
+
+### With specific date
+
+    ecb_rate TRY --specific-date 2025-06-06
+
+---
+
+### Pretty output
+
+    ecb_rate TRY --pretty
+
+Output:
+
+    Base currency:   EUR
+    Target currency: TRY
+
+    2025-06-06: 1 EUR = 43.1234 TRY
+
+---
+
+### Version
+
+    ecb_rate --version
+
+Output:
+
+    ecb_rate 0.4.1
+
+Use this option to print the installed CLI version and exit immediately.
+
+---
+
+## Supported currencies
+
+The CLI supports all currencies defined by the ECB reference exchange rate dataset (EXR).
+
+Currently implemented currencies:
+
+- AUD – Australian dollar (Australia)
+- BRL – Brazilian real (Brazil)
+- CAD – Canadian dollar (Canada)
+- CHF – Swiss franc (Switzerland)
+- CNY – Chinese yuan (China)
+- CZK – Czech koruna (Czech Republic)
+- DKK – Danish krone (Denmark)
+- EUR – Euro (Eurozone)
+- GBP – Pound sterling (United Kingdom)
+- HKD – Hong Kong dollar (Hong Kong)
+- HUF – Hungarian forint (Hungary)
+- IDR – Indonesian rupiah (Indonesia)
+- ILS – Israeli shekel (Israel)
+- INR – Indian rupee (India)
+- ISK – Icelandic krona (Iceland)
+- JPY – Japanese yen (Japan)
+- KRW – South Korean won (South Korea)
+- MXN – Mexican peso (Mexico)
+- MYR – Malaysian ringgit (Malaysia)
+- NOK – Norwegian krone (Norway)
+- NZD – New Zealand dollar (New Zealand)
+- PHP – Philippine peso (Philippines)
+- PLN – Polish zloty (Poland)
+- RON – Romanian leu (Romania)
+- SEK – Swedish krona (Sweden)
+- SGD – Singapore dollar (Singapore)
+- THB – Thai baht (Thailand)
+- TRY – Turkish lira (Turkey)
+- USD – US dollar (United States)
+- ZAR – South African rand (South Africa)
+
+Source:
+https://data-api.ecb.europa.eu/service/data/EXR
+
+Currency support in this tool is defined via the `CurrencyType` enum.
+
+---
+
+## API
+
+Uses the official ECB Data Portal:
+
+    https://data-api.ecb.europa.eu/service/data/EXR
+
+Format:
+
+- jsondata (SDMX JSON)
+
+Reference rates are intended for informational use and should not be treated as executable market prices.
+
+---
+
+## Project structure
+
+    ecb_rate/
+    ├─ cli.py
+    ├─ client.py
+    ├─ custom_types.py
+    ├─ models.py
+    ├─ service.py
+    └─ utils.py
+
+---
+
+## Development
+
+Install dev dependencies:
+
+    uv sync --dev
+
+Run tests:
+
+    pytest

ecb_rate-0.5.2.dist-info/RECORD

@@ -0,0 +1,12 @@
+ecb_rate/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ecb_rate/cli.py,sha256=1Ot79OjscUWuC-_u9Uu3ZYZe0oHQ68HkSPNbdhOJEsg,4148
+ecb_rate/client.py,sha256=HZxy-OZjnLKfADKeNlOsOW21sQieErZNk2zfxWMZl1g,2888
+ecb_rate/custom_types.py,sha256=Jrj73KOhaqDMUUPF6Q1O78pjtZiqwNPdYcz59bsHdGo,1991
+ecb_rate/models.py,sha256=1p4cH3G3NNBqQfcPYviww0WWJy6WkUvVy_cuGjeJU9Y,1297
+ecb_rate/service.py,sha256=Rg98iz3v6RpuNlAcyavSmjuthmtyDyQWoBvtFL0lLII,2390
+ecb_rate-0.5.2.dist-info/licenses/LICENSE,sha256=ZYPOZtJBYetn0L8ZRA4enYpb1TPQfe1b8nJcqhAPU5I,1086
+ecb_rate-0.5.2.dist-info/METADATA,sha256=hXQJL4OvelGlyIMb7MGAOQCgMFD6tenQ27QAzHxkntQ,4117
+ecb_rate-0.5.2.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+ecb_rate-0.5.2.dist-info/entry_points.txt,sha256=gcVdhCrILbpRPW-mLQHaLBUQ_uV3e5p-Z4ZF5ki444Y,47
+ecb_rate-0.5.2.dist-info/top_level.txt,sha256=VcYA2ySxOquKBOdsla5uzQNYZ9HIRQGhoYbRJw2zPF0,9
+ecb_rate-0.5.2.dist-info/RECORD,,

ecb_rate-0.5.2.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

ecb_rate-0.5.2.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ecb_rate = ecb_rate.cli:main

ecb_rate-0.5.2.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PythBuster
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ecb_rate-0.5.2.dist-info/top_level.txt

@@ -0,0 +1 @@
+ecb_rate