ecbfx 0.2.0__py3-none-any.whl

ecbfx/__init__.py

@@ -0,0 +1,31 @@
+"""
+ecbfx — ECB foreign exchange rate lookup tool.
+"""
+
+from .api import (
+    ECBError,
+    validate_currency,
+    fetch_rates,
+    fetch_rates_for_pairs,
+    fetch_latest,
+    fetch_ecb_raw,
+    parse_ecb_csv,
+    resolve_rate,
+)
+
+try:
+    from importlib.metadata import version as _v
+    __version__ = _v("ecbfx")
+except Exception:
+    __version__ = "unknown"
+
+__all__ = [
+    "ECBError",
+    "validate_currency",
+    "fetch_rates",
+    "fetch_rates_for_pairs",
+    "fetch_latest",
+    "fetch_ecb_raw",
+    "parse_ecb_csv",
+    "resolve_rate",
+]

ecbfx/api.py

@@ -0,0 +1,473 @@
+"""
+ecbfx.api
+==========
+Low-level ECB SDMX data fetcher and parser.
+Public functions have no side effects beyond outbound HTTP requests.
+"""
+
+from __future__ import annotations
+
+import csv
+import logging
+import random
+import re
+import time
+from collections import defaultdict
+from datetime import date, timedelta
+from io import StringIO
+from typing import Dict, List, Optional, Tuple
+
+import requests
+
+logger = logging.getLogger(__name__)
+
+__all__ = [
+    "ECBError",
+    "validate_currency",
+    "fetch_ecb_raw",
+    "parse_ecb_csv",
+    "resolve_rate",
+    "fetch_rates",
+    "fetch_rates_for_pairs",
+    "fetch_latest",
+]
+
+MAX_GAP_DAYS             = 5
+RETRIES                  = 3
+BASE_URL                 = "https://data-api.ecb.europa.eu/service/data"
+# Log a warning when fetch_rates_for_pairs spans more than this many days —
+# the full range is still fetched in one call, but users should be aware
+# of the payload size for very sparse historical data.
+SPARSE_WARNING_THRESHOLD = 365
+
+
+class ECBError(RuntimeError):
+    """Raised for any ECB API or data error."""
+
+
+# ── Validation ─────────────────────────────────────────────────────────────────
+
+_CCY_RE = re.compile(r"[A-Z]{2,4}")
+
+def validate_currency(currency: str) -> str:
+    """
+    Normalise and validate a currency code.
+    Accepts 2–4 ASCII letters (covers all ISO 4217 codes).
+    Raises ECBError for anything that would corrupt the ECB URL.
+
+    Uses re.fullmatch (not re.match) so a trailing newline such as
+    "USD\\n" is correctly rejected — re.match with a $ anchor silently
+    accepts strings ending with a newline due to Python's $ semantics.
+    """
+    # Strip only horizontal whitespace (spaces). Do NOT strip newlines —
+    # "USD\n" must be rejected, and .strip() would remove \n before fullmatch.
+    ccy = currency.strip(" ").upper()
+    if not _CCY_RE.fullmatch(ccy):
+        raise ECBError(
+            f"Invalid currency code {currency!r}. "
+            "Expected 2–4 ASCII letters, e.g. USD, GBP, CHF."
+        )
+    return ccy
+
+# Keep the private alias so any external code that used _validate_currency
+# still works — will be removed in 0.3.0.
+_validate_currency = validate_currency
+
+
+# ── HTTP ───────────────────────────────────────────────────────────────────────
+
+def fetch_ecb_raw(
+    currency: str,
+    start: date,
+    end: date,
+    timeout: int = 30,
+    session: Optional[requests.Session] = None,
+) -> str:
+    """
+    Fetch raw CSV text from the ECB SDMX API.
+
+    Parameters
+    ----------
+    currency : ISO 4217 currency code
+    start    : start of date range
+    end      : end of date range
+    timeout  : HTTP request timeout in seconds (default 30)
+    session  : optional requests.Session for connection reuse.
+               If None, a one-off request is made.
+    """
+    currency = validate_currency(currency)
+    url = (
+        f"{BASE_URL}/EXR/D.{currency}.EUR.SP00.A"
+        f"?startPeriod={start.isoformat()}&endPeriod={end.isoformat()}&format=csvdata"
+    )
+    get = (session.get if session is not None else requests.get)
+    last_err: Exception | None = None
+
+    for attempt in range(1, RETRIES + 1):
+        try:
+            logger.debug("Fetching %s attempt %d/%d: %s", currency, attempt, RETRIES, url)
+            resp = get(url, timeout=timeout, headers={"Accept": "text/csv"})
+            resp.raise_for_status()
+            # Guard against the ECB returning an HTML error page instead of CSV.
+            # Primary check: Content-Type header. Secondary check: response body
+            # starts with HTML tags — catches misconfigured servers that send
+            # text/html content with a non-HTML Content-Type header.
+            content_type = resp.headers.get("Content-Type", "")
+            body_start   = resp.text.lstrip()[:15].lower()
+            if "html" in content_type.lower() or body_start.startswith(("<html", "<!doctype")):
+                raise ECBError(
+                    f"ECB returned an HTML response instead of CSV for {currency}. "
+                    "The API may be temporarily unavailable."
+                )
+            logger.debug("Fetched %s: %d bytes", currency, len(resp.text))
+            return resp.text
+        except requests.exceptions.HTTPError as exc:
+            # Do not retry client errors (4xx) — they won't recover on retry.
+            if exc.response is not None and exc.response.status_code < 500:
+                raise ECBError(
+                    f"ECB returned {exc.response.status_code} for {currency}. "
+                    "Check the currency code is valid (e.g. USD, GBP, CHF)."
+                ) from exc
+            last_err = exc
+        except requests.RequestException as exc:
+            # Network errors, timeouts, 5xx — all worth retrying
+            last_err = exc
+
+        if attempt < RETRIES:
+            # Exponential backoff with jitter — avoids thundering herd on retry storms
+            wait = min(2 ** attempt + random.uniform(0, 1), 30)
+            logger.warning(
+                "ECB fetch for %s failed (attempt %d/%d): %s — retrying in %.1fs",
+                currency, attempt, RETRIES, last_err.__class__.__name__, wait,
+            )
+            time.sleep(wait)
+
+    raise ECBError(
+        f"ECB fetch failed for {currency} after {RETRIES} attempts: {last_err}\n"
+        "Check your internet connection or verify the currency code."
+    )
+
+
+# ── Parsing ────────────────────────────────────────────────────────────────────
+
+def parse_ecb_csv(text: str, currency: str) -> Dict[date, float]:
+    """
+    Parse ECB SDMX CSV response.
+    Returns {date: indirect_rate} where indirect_rate = foreign units per 1 EUR
+    (ECB native format — no inversion applied here).
+    """
+    try:
+        reader = csv.DictReader(StringIO(text))
+        rows   = list(reader)
+    except Exception as exc:
+        raise ECBError(f"Failed to parse ECB response for {currency}: {exc}") from exc
+
+    # Normalise header names — ECB occasionally adds whitespace;
+    # guard against None values that csv.DictReader can produce for missing fields.
+    rows = [{k.strip(): (v.strip() if v is not None else "") for k, v in row.items()} for row in rows]
+
+    if not rows or "TIME_PERIOD" not in rows[0] or "OBS_VALUE" not in rows[0]:
+        raise ECBError(
+            f"Unexpected ECB response structure for {currency}. "
+            f"Got columns: {list(rows[0].keys()) if rows else '(empty)'}"
+        )
+
+    result: Dict[date, float] = {}
+    for row in rows:
+        try:
+            d    = date.fromisoformat(row["TIME_PERIOD"])
+            rate = float(row["OBS_VALUE"])
+            if rate > 0:
+                result[d] = rate  # keep full float precision; rounding done at output
+        except (ValueError, KeyError) as exc:
+            logger.warning("Skipped malformed ECB row (currency=%s): %s", currency, exc)
+            continue  # skip malformed rows
+
+    if not result:
+        raise ECBError(
+            f"No valid rate data returned for {currency}. "
+            "The currency may not be available from ECB, or the date range "
+            "may fall entirely on non-trading days."
+        )
+
+    return result
+
+
+# ── Gap filling ────────────────────────────────────────────────────────────────
+
+def resolve_rate(daily: Dict[date, float], target: date,
+                 currency: str, gap_fill: bool = True) -> float:
+    """
+    Return the rate for target date.
+
+    gap_fill=True  (default): falls back to the nearest available date within
+                              MAX_GAP_DAYS — handles weekends and public holidays.
+                              When two dates are equidistant (e.g. a mid-week
+                              holiday), the earlier date is preferred for
+                              consistency with standard financial convention.
+    gap_fill=False (strict):  raises ECBError if target date has no exact match.
+    """
+    if not daily:
+        raise ECBError(
+            f"No rate data available for {currency}. "
+            "The date range may fall entirely outside ECB published data."
+        )
+
+    if target in daily:
+        return daily[target]
+
+    if not gap_fill:
+        nearby = ", ".join(
+            str(d) for d in sorted(daily) if abs((d - target).days) <= 3
+        )
+        raise ECBError(
+            f"No ECB rate for {target} ({currency}) and --no-gap-fill is set. "
+            f"This date may be a weekend or public holiday. "
+            f"Available dates nearby: {nearby or 'none'}"
+        )
+
+    # Last Observation Carried Forward (LOCF) — standard financial convention.
+    # For any missing date (weekend, holiday), use the most recent prior
+    # trading day. Never use a future rate — doing so would introduce
+    # look-ahead bias (e.g. a Monday holiday should use Friday, not Tuesday).
+    prior = [d for d in daily if d < target]
+    if prior:
+        closest = max(prior)          # most recent trading day before target
+    else:
+        # No prior data — target is before the earliest available date.
+        # Falling forward would introduce look-ahead bias, so raise explicitly.
+        raise ECBError(
+            f"No ECB rate available for {currency} on or before {target}. "
+            f"Earliest data available: {min(daily.keys())}. "
+            "Consider widening the date range."
+        )
+
+    gap = abs((closest - target).days)
+
+    if gap > MAX_GAP_DAYS:
+        raise ECBError(
+            f"No ECB rate within {MAX_GAP_DAYS} days of {target} for {currency}. "
+            f"Closest available: {closest} ({gap} days away)."
+        )
+
+    logger.debug("Gap-filled %s %s → %s (%d day(s))", currency, target, closest, gap)
+    return daily[closest]
+
+
+# ── High-level ─────────────────────────────────────────────────────────────────
+
+def fetch_rates(
+    currencies: List[str],
+    start: date,
+    end: date,
+    direct: bool = False,
+    decimals: int = 4,
+    gap_fill: bool = True,
+    session: Optional[requests.Session] = None,
+) -> List[Dict]:
+    """
+    Fetch rates for all currencies over [start, end].
+
+    Parameters
+    ----------
+    currencies : list of ISO 4217 codes, e.g. ["USD", "GBP"]
+    start, end : inclusive date range
+    direct     : if True, return EUR per 1 foreign unit (inverted);
+                 if False (default), return foreign units per 1 EUR (ECB native)
+    decimals   : decimal places to round the output rate to (default 4)
+    gap_fill   : if False, raise ECBError on weekends/holidays instead of
+                 substituting the nearest available rate
+
+    Returns
+    -------
+    List of dicts: {date, currency, rate, convention}
+    convention is "EUR/CCY" (direct) or "CCY/EUR" (indirect).
+    """
+    results = []
+
+    for currency in currencies:
+        currency = validate_currency(currency)
+
+        if currency == "EUR":
+            d = start
+            while d <= end:
+                results.append({
+                    "date":       str(d),
+                    "currency":   "EUR",
+                    "rate":       round(1.0, decimals),
+                    "convention": "EUR/EUR",
+                })
+                d += timedelta(days=1)
+            continue
+
+        # Fetch slightly before `start` so that LOCF always has a prior
+        # trading day available for the first date in the requested range.
+        # Without this, a range starting on a public holiday (e.g. Jan 1)
+        # would raise because there is no prior data within the window.
+        # The extra days are used only for gap-filling — output still covers
+        # exactly start → end.
+        ecb_start = start - timedelta(days=MAX_GAP_DAYS)
+        raw_text  = fetch_ecb_raw(currency, ecb_start, end, session=session)
+        daily     = parse_ecb_csv(raw_text, currency)
+        col_label = f"EUR/{currency}" if direct else f"{currency}/EUR"
+
+        # Iterate every calendar day in the requested range and resolve each
+        # date individually — this fills weekends and public holidays with the
+        # nearest available trading-day rate (via resolve_rate), unless
+        # gap_fill=False in which case an error is raised for missing dates.
+        d = start
+        while d <= end:
+            indirect_rate = resolve_rate(daily, d, currency, gap_fill=gap_fill)
+            rate = round(1 / indirect_rate, decimals) if direct \
+                   else round(indirect_rate, decimals)
+            results.append({
+                "date":       str(d),
+                "currency":   currency,
+                "rate":       rate,
+                "convention": col_label,
+            })
+            d += timedelta(days=1)
+
+    # Sort by date then currency for consistent, predictable output
+    return sorted(results, key=lambda r: (r["date"], r["currency"]))
+
+
+def fetch_latest(
+    currencies: List[str],
+    direct: bool = False,
+    decimals: int = 4,
+    lookback_days: int = 14,
+    session: Optional[requests.Session] = None,
+    _today: Optional[date] = None,
+) -> List[Dict]:
+    """
+    Return the most recent available ECB rate for each currency.
+
+    Fetches the past `lookback_days` calendar days and returns only the row
+    with the latest date. Default of 14 days safely covers extended holiday
+    periods (e.g. Christmas/New Year break) that can run up to 10 calendar
+    days with no trading days.
+
+    _today is an optional override for the current date, used in tests to
+    avoid depending on the real system clock.
+    """
+    today = _today if _today is not None else date.today()
+    start = today - timedelta(days=lookback_days)
+    rows  = fetch_rates(currencies, start, today,
+                        direct=direct, decimals=decimals, gap_fill=True,
+                        session=session)
+
+    # For each currency, keep only the row with the maximum date
+    latest: Dict[str, Dict] = {}
+    for row in rows:
+        ccy = row["currency"]
+        if ccy not in latest or row["date"] > latest[ccy]["date"]:
+            latest[ccy] = row
+
+    # Return in the same order as the input currencies list.
+    # Raise if any requested currency wasn't found — silent omission would
+    # give callers incomplete data without any indication something went wrong.
+    results = []
+    for c in currencies:
+        key = c.upper()
+        if key not in latest:
+            raise ECBError(
+                f"No rate data returned for {c!r} within the last {lookback_days} days. "
+                "The currency may not be supported by ECB, or all days in the "
+                "lookback window may be non-trading days."
+            )
+        results.append(latest[key])
+    return results
+
+
+def fetch_rates_for_pairs(
+    pairs: List[Tuple[date, str]],
+    direct: bool = False,
+    decimals: int = 4,
+    gap_fill: bool = True,
+    session: Optional[requests.Session] = None,
+) -> List[Dict]:
+    """
+    Fetch rates for an arbitrary list of (date, currency) pairs.
+
+    Unlike fetch_rates() which requires a contiguous date range, this function
+    accepts sparse dates — ideal for transaction-level data where trades are
+    scattered across a calendar (e.g. a broker activity statement).
+
+    Internally batches by currency: one HTTP call per unique currency regardless
+    of how many pairs share that currency. Duplicate (date, currency) pairs are
+    deduplicated before fetching and restored in the output.
+
+    Parameters
+    ----------
+    pairs    : list of (date, currency) tuples,
+               e.g. [(date(2025,1,15), "USD"), (date(2025,1,20), "GBP")]
+    direct   : if True, return EUR per 1 foreign unit (inverted);
+               if False (default), return foreign units per 1 EUR (ECB native)
+    decimals : decimal places to round the output rate to (default 4)
+    gap_fill : if False, raise ECBError on weekends/holidays instead of
+               substituting the nearest available rate
+
+    Returns
+    -------
+    List of dicts: {date, currency, rate, convention}
+    Ordered to match the input pairs list.
+    """
+    if not pairs:
+        return []
+
+    # ── Group unique dates by currency ────────────────────────────────────────
+    by_currency: Dict[str, List[date]] = defaultdict(list)
+    for d, ccy in pairs:
+        by_currency[validate_currency(ccy)].append(d)
+
+    # Deduplicate dates per currency (preserve all for output reconstruction)
+    unique_by_currency: Dict[str, List[date]] = {
+        ccy: sorted(set(dates))
+        for ccy, dates in by_currency.items()
+    }
+
+    # ── One HTTP call per currency, covering its full date span ───────────────
+    # rate_cache[(currency, date_str)] = rate
+    rate_cache: Dict[Tuple[str, str], float] = {}
+
+    for currency, dates in unique_by_currency.items():
+        col_label = f"EUR/{currency}" if direct else f"{currency}/EUR"
+
+        if currency == "EUR":
+            for d in dates:
+                rate_cache[("EUR", str(d))] = round(1.0, decimals)
+            continue
+
+        span = (max(dates) - min(dates)).days
+        if span > SPARSE_WARNING_THRESHOLD:
+            logger.warning(
+                "%s: date span is %d days (%s to %s, %d unique dates). "
+                "Fetching full range in one request.",
+                currency, span, min(dates), max(dates), len(dates),
+            )
+        # Extend the fetch window backward by MAX_GAP_DAYS so LOCF has a
+        # prior trading day available even if the earliest requested date
+        # falls on a public holiday.
+        ecb_start = min(dates) - timedelta(days=MAX_GAP_DAYS)
+        raw_text  = fetch_ecb_raw(currency, ecb_start, max(dates), session=session)
+        daily     = parse_ecb_csv(raw_text, currency)
+
+        for d in dates:
+            indirect      = resolve_rate(daily, d, currency, gap_fill=gap_fill)
+            rate          = round(1 / indirect if direct else indirect, decimals)
+            rate_cache[(currency, str(d))] = rate
+
+    # ── Reconstruct output in input order ─────────────────────────────────────
+    results = []
+    for d, ccy in pairs:
+        ccy       = validate_currency(ccy)
+        col_label = f"EUR/{ccy}" if direct else f"{ccy}/EUR"
+        results.append({
+            "date":       str(d),
+            "currency":   ccy,
+            "rate":       rate_cache[(ccy, str(d))],
+            "convention": col_label,
+        })
+
+    return results

ecbfx/cli.py

@@ -0,0 +1,490 @@
+"""
+ecbfx.cli
+==========
+Command-line interface for ECB FX rate lookup.
+
+Usage examples
+--------------
+  ecbfx USD
+  ecbfx USD 2025-01-15
+  ecbfx USD GBP CHF 2025-01-15
+  ecbfx USD GBP --from 2025-01-01 --to 2025-03-31
+  ecbfx USD --from 2025-01-01 --to 2025-01-31 --direct
+  ecbfx USD --from 2025-01-01 --to 2025-01-31 --csv > rates.csv
+  ecbfx USD --latest
+  ecbfx USD --latest --quiet
+  ecbfx USD --decimal 6
+  ecbfx USD 2025-01-13 --no-gap-fill
+  ecbfx --pairs transactions.csv --direct --csv
+  ecbfx --pairs - --direct --csv < transactions.csv
+  cat transactions.csv | ecbfx --pairs - --quiet
+"""
+
+from __future__ import annotations
+
+import argparse
+import contextlib
+import csv
+import sys
+from datetime import date
+from typing import List, Optional, Tuple
+
+def _get_version() -> str:
+    try:
+        from importlib.metadata import version
+        return version("ecbfx")
+    except Exception:
+        return "unknown"
+
+import requests
+from .api import ECBError, fetch_rates, fetch_rates_for_pairs, fetch_latest, validate_currency
+
+# ── Formatting ─────────────────────────────────────────────────────────────────
+
+# ANSI colours (suppressed when stdout is not a tty)
+def _ansi(code: str, text: str) -> str:
+    if not sys.stdout.isatty():
+        return text
+    return f"\033[{code}m{text}\033[0m"
+
+DIM    = lambda t: _ansi("2",  t)
+BOLD   = lambda t: _ansi("1",  t)
+CYAN   = lambda t: _ansi("36", t)
+GREEN  = lambda t: _ansi("32", t)
+RED    = lambda t: _ansi("31", t)
+
+
+def _print_table(rows: List[dict]) -> None:
+    """Pretty-print rows as an aligned table to stdout."""
+    if not rows:
+        print(DIM("  (no data)"))
+        return
+
+    w_date = max(len(r["date"])       for r in rows)
+    w_ccy  = max(len(r["currency"])   for r in rows)
+    w_conv = max(len(r["convention"]) for r in rows)
+    w_rate = max(len(str(r["rate"]))  for r in rows)
+
+    header = (
+        f"  {BOLD('Date'): <{w_date + 10}}"
+        f"{BOLD('CCY'): <{w_ccy + 10}}"
+        f"{BOLD('Convention'): <{w_conv + 10}}"
+        f"{BOLD('Rate'):>{w_rate}}"
+    )
+    sep = "  " + DIM("─" * (w_date + w_ccy + w_conv + w_rate + 6))
+    print(header)
+    print(sep)
+
+    for r in rows:
+        print(
+            f"  {CYAN(r['date']): <{w_date + 10}}"
+            f"{r['currency']: <{w_ccy + 10}}"
+            f"{DIM(r['convention']): <{w_conv + 10}}"
+            f"{GREEN(str(r['rate'])):>{w_rate + 9}}"
+        )
+    print()
+
+
+def _print_csv(rows: List[dict]) -> None:
+    """Write rows as CSV to stdout."""
+    if not rows:
+        return
+    writer = csv.DictWriter(
+        sys.stdout,
+        fieldnames=["date", "currency", "convention", "rate"],
+        lineterminator="\n")
+    writer.writeheader()
+    writer.writerows(rows)
+
+
+def _print_quiet(rows: List[dict]) -> None:
+    """Print only the rate value(s), one per line. Ideal for scripting."""
+    for r in rows:
+        print(r["rate"])
+
+
+def _output(rows: List[dict], args: argparse.Namespace) -> None:
+    """Route to the correct output formatter."""
+    if args.quiet:
+        _print_quiet(rows)
+    elif args.csv:
+        _print_csv(rows)
+    else:
+        _print_table(rows)
+
+
+# ── Pairs input ────────────────────────────────────────────────────────────────
+
+def _read_pairs(
+    source: str,
+    date_from: Optional[date] = None,
+    date_to:   Optional[date] = None,
+) -> List[Tuple[date, str]]:
+    """
+    Read (date, currency) pairs from a file or stdin.
+
+    source   : path to a CSV/TSV file, or "-" to read from stdin
+    date_from: optional lower bound filter (inclusive)
+    date_to  : optional upper bound filter (inclusive)
+
+    Input format — one pair per line, date first, then currency code.
+    The separator can be a comma, tab, or single space.
+    A header row is detected and skipped automatically.
+    Lines starting with '#' are treated as comments and skipped.
+
+    Valid input examples
+    --------------------
+    2025-01-15,USD
+    2025-01-20,GBP
+    2025-02-03,USD
+
+    Or with a header:
+    date,currency
+    2025-01-15,USD
+    ...
+    """
+    pairs: List[Tuple[date, str]] = []
+    seen_header = False
+
+    ctx = contextlib.ExitStack()
+    if source == "-":
+        fh = sys.stdin
+    else:
+        fh = ctx.enter_context(open(source, encoding="utf-8-sig"))
+
+    with ctx:
+        for lineno, raw in enumerate(fh, 1):
+            line = raw.strip()
+            if not line or line.startswith("#"):
+                continue
+
+            # Detect separator: comma, tab, or space
+            if "\t" in line:
+                parts = line.split("\t", 1)
+            elif "," in line:
+                parts = line.split(",", 1)
+            else:
+                parts = line.split(None, 1)
+
+            if len(parts) < 2:
+                raise ValueError(
+                    f"Line {lineno}: expected 'date,currency', got: {line!r}"
+                )
+
+            raw_date, raw_ccy = parts[0].strip(), parts[1].strip()
+
+            # Skip a header row only if the first field is purely alphabetic
+            # (e.g. "date", "Date", "DATE"). This correctly accepts:
+            #   "date,currency"    → skip as header ✓
+            # And correctly rejects as malformed (not silently skipped):
+            #   "not-a-date,USD"   → '-' makes isalpha() False → error ✓
+            #   "2025-02-29,USD"   → digits make isalpha() False → error ✓
+            if not seen_header:
+                seen_header = True
+                if raw_date.isalpha():
+                    continue  # purely alphabetic label → header row, skip
+
+            try:
+                d = date.fromisoformat(raw_date)
+            except ValueError:
+                raise ValueError(
+                    f"Line {lineno}: {raw_date!r} is not a valid YYYY-MM-DD date."
+                )
+
+            try:
+                raw_ccy = validate_currency(raw_ccy)
+            except ECBError as exc:
+                raise ValueError(f"Line {lineno}: {exc}") from exc
+
+            # Apply optional date filters
+            if date_from and d < date_from:
+                continue
+            if date_to and d > date_to:
+                continue
+
+            pairs.append((d, raw_ccy))
+
+    if not pairs:
+        raise ValueError(
+            "No valid pairs found in input"
+            + (f" after applying date filters ({date_from} → {date_to})"
+               if date_from or date_to else "") + "."
+        )
+
+    return pairs
+
+
+# ── Argument parsing ───────────────────────────────────────────────────────────
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="ecbfx",
+        description=(
+            "Fetch EUR foreign exchange rates from the ECB SDMX API.\n\n"
+            "CONVENTION\n"
+            "  Indirect (default) : foreign units per 1 EUR  e.g. 1 EUR = 1.0830 USD\n"
+            "  Direct (--direct)  : EUR per 1 foreign unit   e.g. 1 USD = 0.9234 EUR\n"
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=(
+            "examples:\n"
+            "  ecbfx USD\n"
+            "  ecbfx USD 2025-01-15\n"
+            "  ecbfx USD GBP CHF 2025-01-15\n"
+            "  ecbfx USD GBP --from 2025-01-01 --to 2025-03-31\n"
+            "  ecbfx USD --from 2025-01-01 --to 2025-01-31 --direct\n"
+            "  ecbfx USD --from 2025-01-01 --to 2025-01-31 --csv > rates.csv\n"
+            "  ecbfx USD --latest\n"
+            "  ecbfx USD --latest --quiet\n"
+            "  ecbfx USD --decimal 6\n"
+            "  ecbfx USD 2025-01-13 --no-gap-fill\n"
+            "  ecbfx --pairs transactions.csv --direct --csv\n"
+            "  ecbfx --pairs - --direct --csv < transactions.csv\n"
+            "  cat transactions.csv | ecbfx --pairs - --quiet\n"
+        ),
+    )
+
+    # ── Mode selection (mutually exclusive) ──────────────────────────────────
+    # --pairs and positional CCY codes are mutually exclusive.
+    # --latest is a separate flag that works alongside CCY positional args.
+    mode = parser.add_mutually_exclusive_group()
+    mode.add_argument(
+        "currencies",
+        nargs="*",
+        metavar="CCY",
+        help="ISO 4217 currency code(s), e.g. USD GBP CHF",
+    )
+    mode.add_argument(
+        "--pairs", dest="pairs_source", default=None, metavar="FILE|-",
+        help=(
+            "Read (date, currency) pairs from FILE or stdin (-). "
+            "One pair per line: '2025-01-15,USD'. "
+            "Comma, tab, or space separators are all accepted. "
+            "An optional header row (first line starting with a non-date) "
+            "and comment lines starting with '#' are skipped automatically."
+        ),
+    )
+
+    parser.add_argument(
+        "--latest", action="store_true", default=False,
+        help="Return the most recent available rate, regardless of today's date.",
+    )
+
+    parser.add_argument(
+        "date",
+        nargs="?",
+        metavar="DATE",
+        default=None,
+        help="Single date YYYY-MM-DD (shorthand for --from DATE --to DATE)",
+    )
+    parser.add_argument(
+        "--from", dest="date_from", default=None, metavar="YYYY-MM-DD",
+        help="Start of date range (inclusive). Also filters --pairs input.",
+    )
+    parser.add_argument(
+        "--to", dest="date_to", default=None, metavar="YYYY-MM-DD",
+        help=(
+            "End of date range (inclusive). Also filters --pairs input. "
+            "Requires --from when used in range mode."
+        ),
+    )
+    parser.add_argument(
+        "--direct", action="store_true", default=False,
+        help="Return EUR per 1 foreign unit (inverted). Default: foreign units per 1 EUR.",
+    )
+    parser.add_argument(
+        "--no-gap-fill", dest="no_gap_fill", action="store_true", default=False,
+        help=(
+            "Strict mode: raise an error if a requested date has no ECB rate "
+            "(e.g. weekend or public holiday) instead of substituting the "
+            "nearest available rate."
+        ),
+    )
+    parser.add_argument(
+        "--decimal", dest="decimals", type=int, default=4, metavar="N",
+        help="Number of decimal places in the output rate (default: 4).",
+    )
+    parser.add_argument(
+        "--quiet", "-q", action="store_true", default=False,
+        help=(
+            "Print only the rate value(s), one per line. "
+            "Useful for shell scripting: $(ecbfx USD --quiet)"
+        ),
+    )
+    parser.add_argument(
+        "--csv", action="store_true", default=False,
+        help="Output as CSV instead of a formatted table.",
+    )
+    parser.add_argument(
+        "--version", action="version", version=f"%(prog)s {_get_version()}",
+    )
+
+    return parser
+
+
+def _resolve_dates(args: argparse.Namespace):
+    """
+    Resolve the final (start, end) date pair for range mode.
+
+    Precedence:
+      1. --latest flag                   → handled separately in main()
+      2. --pairs flag                    → handled separately in main()
+      3. Positional DATE argument        → single date
+      4. --from / --to flags             → explicit range
+      5. No date arguments               → today (single date)
+    """
+    today = date.today()
+
+    # Detect if the last "currency" token is actually a date
+    # (handles: ecbfx USD GBP 2025-01-15)
+    currencies = list(args.currencies)
+    positional_date = None
+
+    if args.date:
+        positional_date = args.date
+    elif currencies:
+        last = currencies[-1]
+        try:
+            date.fromisoformat(last)
+            positional_date = last
+            currencies = currencies[:-1]
+        except ValueError:
+            pass
+
+    if not currencies:
+        raise ValueError("At least one currency code is required.")
+
+    if positional_date:
+        if args.date_from or args.date_to:
+            raise ValueError(
+                "Positional DATE and --from/--to cannot be used together."
+            )
+        d = date.fromisoformat(positional_date)
+        return currencies, d, d
+
+    start = date.fromisoformat(args.date_from) if args.date_from else today
+    end   = date.fromisoformat(args.date_to)   if args.date_to   else (
+        start if args.date_from else today
+    )
+
+    if args.date_to and not args.date_from:
+        raise ValueError(
+            "--to requires --from. "
+            "Please provide a start date, e.g. --from 2025-01-01 --to 2025-03-31"
+        )
+
+    if end < start:
+        raise ValueError("--to date must not be earlier than --from date.")
+
+    return currencies, start, end
+
+
+# ── Entry point ────────────────────────────────────────────────────────────────
+
+def main(argv: List[str] | None = None) -> int:
+    parser = _build_parser()
+    try:
+        args = parser.parse_args(argv)
+    except SystemExit as exc:
+        # argparse calls sys.exit() on usage errors; convert to return code
+        # so callers (and tests) always get an integer back.
+        return int(exc.code) if exc.code is not None else 0
+
+    # ── Validate decimals ──────────────────────────────────────────────────────
+    if args.decimals < 0 or args.decimals > 10:
+        print(RED("Error: --decimal must be between 0 and 10."), file=sys.stderr)
+        return 2
+
+    # Shared session reuses TCP connections across all fetch calls
+    session = requests.Session()
+
+    # ── --pairs mode ───────────────────────────────────────────────────────────
+    if args.pairs_source is not None:
+        if args.latest:
+            print(RED("Error: --pairs cannot be combined with --latest."),
+                  file=sys.stderr)
+            return 2
+        date_from = date.fromisoformat(args.date_from) if args.date_from else None
+        date_to   = date.fromisoformat(args.date_to)   if args.date_to   else None
+
+        try:
+            pairs = _read_pairs(args.pairs_source, date_from, date_to)
+        except (ValueError, OSError) as exc:
+            print(RED(f"Error reading pairs: {exc}"), file=sys.stderr)
+            return 2
+
+        if not args.quiet and not args.csv and sys.stdout.isatty():
+            conv   = "direct (EUR/CCY)" if args.direct else "indirect (CCY/EUR)"
+            strict = "  ·  strict (no gap fill)" if args.no_gap_fill else ""
+            print(DIM(f"\n  ECB rates  {len(pairs)} pairs  ·  {conv}{strict}\n"))
+
+        try:
+            rows = fetch_rates_for_pairs(
+                pairs,
+                direct=args.direct,
+                decimals=args.decimals,
+                gap_fill=not args.no_gap_fill,
+                session=session,
+            )
+        except ECBError as exc:
+            print(RED(f"Error: {exc}"), file=sys.stderr)
+            return 1
+
+        _output(rows, args)
+        return 0
+
+    # ── --latest mode ──────────────────────────────────────────────────────────
+    if args.latest:
+        currencies = list(args.currencies) if args.currencies else []
+        if not currencies:
+            print(RED("Error: at least one currency code is required with --latest."),
+                  file=sys.stderr)
+            return 2
+        if args.date_from or args.date_to or args.date:
+            print(RED("Error: --latest cannot be combined with date arguments."),
+                  file=sys.stderr)
+            return 2
+        if args.no_gap_fill:
+            print(RED("Error: --latest and --no-gap-fill cannot be combined."),
+                  file=sys.stderr)
+            return 2
+        try:
+            rows = fetch_latest(currencies, direct=args.direct,
+                                decimals=args.decimals, session=session)
+        except ECBError as exc:
+            print(RED(f"Error: {exc}"), file=sys.stderr)
+            return 1
+        _output(rows, args)
+        return 0
+
+    # ── Normal date-range mode ─────────────────────────────────────────────────
+    try:
+        currencies, start, end = _resolve_dates(args)
+    except ValueError as exc:
+        print(RED(f"Error: {exc}"), file=sys.stderr)
+        return 2
+
+    if not args.quiet and not args.csv and sys.stdout.isatty():
+        label  = str(start) if start == end else f"{start} → {end}"
+        conv   = "direct (EUR/CCY)" if args.direct else "indirect (CCY/EUR)"
+        strict = "  ·  strict (no gap fill)" if args.no_gap_fill else ""
+        print(DIM(f"\n  ECB rates  {label}  ·  {conv}{strict}\n"))
+
+    try:
+        rows = fetch_rates(
+            currencies, start, end,
+            direct=args.direct,
+            decimals=args.decimals,
+            gap_fill=not args.no_gap_fill,
+            session=session,
+        )
+    except ECBError as exc:
+        print(RED(f"Error: {exc}"), file=sys.stderr)
+        return 1
+
+    _output(rows, args)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

ecbfx-0.2.0.dist-info/METADATA

@@ -0,0 +1,226 @@
+Metadata-Version: 2.4
+Name: ecbfx
+Version: 0.2.0
+Summary: ECB foreign exchange rate lookup — CLI and Python API with gap-fill, strict mode, and scripting support
+Project-URL: Homepage, https://github.com/edvinassvedas-dev/ecbfx
+Project-URL: Repository, https://github.com/edvinassvedas-dev/ecbfx
+Project-URL: Issues, https://github.com/edvinassvedas-dev/ecbfx/issues
+Author: Edvinas Švedas
+License: MIT
+License-File: LICENSE
+Keywords: cli,currency,ecb,exchange-rate,finance,forex,fx
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Requires-Dist: requests>=2.28
+Provides-Extra: dev
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: responses; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# ecbfx
+
+[![PyPI version](https://img.shields.io/pypi/v/ecbfx.svg)](https://pypi.org/project/ecbfx/)
+[![Python](https://img.shields.io/pypi/pyversions/ecbfx.svg)](https://pypi.org/project/ecbfx/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/edvinassvedas-dev/ecbfx/blob/main/LICENSE)
+
+A minimal command-line tool and Python library for fetching EUR foreign exchange
+rates directly from the [ECB SDMX API](https://data-api.ecb.europa.eu).
+
+---
+
+## Install
+
+```bash
+pip install ecbfx
+```
+
+**For development** (includes test dependencies):
+
+```bash
+git clone https://github.com/edvinassvedas-dev/ecbfx.git
+cd ecbfx
+pip install -e ".[dev]"
+pytest
+```
+
+## CLI usage
+
+```bash
+# Today's rate for USD (indirect: USD per 1 EUR — ECB native)
+# Note: ECB publishes rates ~16:00 CET on trading days.
+# If today's rate isn't available yet, use --latest instead.
+ecbfx USD
+
+# Specific date
+ecbfx USD 2025-01-15
+
+# Multiple currencies, specific date
+ecbfx USD GBP CHF 2025-01-15
+
+# Date range
+ecbfx USD GBP --from 2025-01-01 --to 2025-03-31
+
+# Direct convention: EUR per 1 foreign unit (inverted)
+ecbfx USD 2025-01-15 --direct
+
+# Most recent available rate (ignores today being a weekend/holiday)
+ecbfx USD --latest
+
+# Single value only — ideal for shell scripting
+ecbfx USD --latest --quiet
+RATE=$(ecbfx USD --quiet)
+
+# Control decimal precision (default: 4)
+ecbfx USD 2025-01-15 --decimal 6
+
+# Strict mode — error instead of gap-filling on weekends/holidays
+ecbfx USD 2025-01-15 --no-gap-fill
+
+# CSV output (pipe-friendly)
+ecbfx USD --from 2025-01-01 --to 2025-01-31 --csv
+ecbfx USD --from 2025-01-01 --to 2025-01-31 --csv > rates.csv
+
+# Read pairs from a file — one HTTP call per currency
+ecbfx --pairs transactions.csv --direct --csv
+
+# Read pairs from stdin
+cat transactions.csv | ecbfx --pairs - --direct --csv
+
+# Combine with date filter
+ecbfx --pairs transactions.csv --from 2025-01-01 --to 2025-03-31 --csv
+```
+
+### Convention
+
+| Flag | Formula | Example |
+|---|---|---|
+| *(default)* | foreign units per 1 EUR | `1 EUR = 1.0830 USD` |
+| `--direct` | EUR per 1 foreign unit | `1 USD = 0.9234 EUR` |
+
+ECB publishes indirect natively. `--direct` inverts the rate.
+The `convention` column in CSV output (`USD/EUR` or `EUR/USD`) makes the
+direction explicit for downstream pipelines.
+
+### Flags reference
+
+| Flag | Default | Description |
+|---|---|---|
+| `--direct` | off | EUR per 1 foreign unit instead of ECB native |
+| `--latest` | off | Most recent available rate, regardless of date |
+| `--quiet` / `-q` | off | Print rate value(s) only — ideal for scripting |
+| `--decimal N` | 4 | Decimal places in output rate |
+| `--no-gap-fill` | off | Raise an error on weekends/holidays instead of substituting the nearest rate |
+| `--csv` | off | CSV output instead of formatted table |
+| `--pairs FILE\|-` | — | Read `date,currency` pairs from a file or stdin |
+
+### Weekend and holiday gap-filling
+
+ECB only publishes rates on trading days. By default, `ecbfx` automatically
+uses the most recent prior trading day's rate (Last Observation Carried Forward)
+when a requested date falls on a weekend or public holiday — including the first
+date in a range that starts on a holiday such as January 1st.
+
+Use `--no-gap-fill` to disable this and receive an explicit error instead —
+useful in audit workflows where a substituted rate is not acceptable.
+
+---
+
+
+### Exit codes
+
+| Code | Meaning |
+|---|---|
+| `0` | Success |
+| `1` | Runtime error (ECB API failure, network issue, no data returned) |
+| `2` | Usage error (invalid arguments, bad date format, missing required flag) |
+
+Useful for scripting:
+```bash
+ecbfx USD --quiet || echo "fetch failed, exit $?"
+```
+
+## Python API
+
+```python
+from datetime import date
+from ecbfx import fetch_rates, fetch_rates_for_pairs, fetch_latest
+
+# Indirect (default) — foreign units per 1 EUR, contiguous range
+rows = fetch_rates(["USD", "GBP"], date(2025, 1, 1), date(2025, 1, 31))
+
+# Direct — EUR per 1 foreign unit
+rows = fetch_rates(["USD"], date(2025, 1, 15), date(2025, 1, 15), direct=True)
+
+# Most recent available rate
+rows = fetch_latest(["USD", "CHF"])
+
+# Sparse transaction dates — one HTTP call per currency regardless of pair count
+pairs = [
+    (date(2025, 1, 15), "USD"),
+    (date(2025, 1, 20), "GBP"),
+    (date(2025, 2,  3), "USD"),
+    (date(2025, 2,  3), "CHF"),
+]
+rows = fetch_rates_for_pairs(pairs, direct=True)
+
+# Custom decimal precision
+rows = fetch_rates(["USD"], date(2025, 1, 15), date(2025, 1, 15), decimals=6)
+
+# Strict mode — raises ECBError on weekends/holidays
+rows = fetch_rates(["USD"], date(2025, 1, 13), date(2025, 1, 13), gap_fill=False)
+rows = fetch_rates_for_pairs([(date(2025, 1, 13), "USD")], gap_fill=False)
+
+for r in rows:
+    print(r["date"], r["currency"], r["convention"], r["rate"])
+```
+
+Each row is a dict: `{date, currency, rate, convention}`.
+
+### Input validation
+
+```python
+from ecbfx import validate_currency, ECBError
+
+# Normalises and validates a currency code — raises ECBError if invalid
+print(validate_currency("usd"))   # → "USD"
+print(validate_currency("  GBP ")) # → "GBP"
+
+try:
+    validate_currency("US$")
+except ECBError as e:
+    print(e)  # Invalid currency code 'US$'. Expected 2–4 ASCII letters.
+```
+
+Use `ECBError` in `try/except` blocks when calling any `ecbfx` function
+to handle API failures, network errors, or invalid inputs cleanly.
+
+### fetch_rates vs fetch_rates_for_pairs
+
+| | `fetch_rates` | `fetch_rates_for_pairs` |
+|---|---|---|
+| Input | currency list + date range | list of `(date, currency)` tuples |
+| Returns | every calendar day in range | exactly the requested dates |
+| Best for | daily pipelines, backfill | transaction enrichment, broker CSVs |
+| HTTP calls | one per currency | one per currency (full span, regardless of gaps) |
+
+> **Note:** `fetch_rates_for_pairs` always fetches the full date span from the earliest to the latest date per currency in a single HTTP call. For very sparse data (e.g. two transactions 10 years apart), this fetches the entire intervening range. A warning is logged when the span exceeds one year.
+
+
+---
+
+## License
+
+MIT

ecbfx-0.2.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+ecbfx/__init__.py,sha256=kUtX49xLQ5M6dzKU1w_rKSwoHoPH9tLPY1lV1LCWvuI,551
+ecbfx/api.py,sha256=x9lyfMxNZWG9tQbpVNMpqjex7sy24ihvLhrByVclcAA,19132
+ecbfx/cli.py,sha256=5u9VH-BtUFoPglKzS5mFIfEk1CQTwKl3tQdSZ_vL5mc,17653
+ecbfx-0.2.0.dist-info/METADATA,sha256=Q9n-ptFHPUWdz5cDHFLw0SLMmx53lI1bobarzYQWfsc,7491
+ecbfx-0.2.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+ecbfx-0.2.0.dist-info/entry_points.txt,sha256=PqALcYDZ0uQ3m1YF756SCjUTOIHsDlb75759yYhyYkg,41
+ecbfx-0.2.0.dist-info/licenses/LICENSE,sha256=ykjvlRCsC-Sg-BU9M68Gvp2PQQxo2fh4RC2EaUCHcKM,1074
+ecbfx-0.2.0.dist-info/RECORD,,

ecbfx-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

ecbfx-0.2.0.dist-info/entry_points.txt

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

ecbfx-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 edvinassvedas-dev
+
+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.