onefinance 0.1.0__py3-none-any.whl

onefinance/__init__.py

@@ -0,0 +1,74 @@
+"""OneFinance — unified financial data API across multiple providers."""
+
+from onefinance.core.client import OneFinanceClient
+from onefinance.core.errors import (
+    AllProvidersFailedError,
+    FinanceError,
+    NotSupportedError,
+    ProviderError,
+    RateLimitError,
+)
+from onefinance.indicators import TechnicalIndicators, compute_indicators
+from onefinance.core.models import (
+    AnalystData,
+    BalanceSheet,
+    CashFlow,
+    CompanyInfo,
+    CorporateAction,
+    Currency,
+    DCFValuation,
+    EarningsRecord,
+    FinancialRatios,
+    FinanceModel,
+    ForwardEstimates,
+    IncomeStatement,
+    InsiderTrade,
+    InstitutionalHolder,
+    NewsArticle,
+    OptionChain,
+    OptionContract,
+    PriceBar,
+    Quote,
+    ScreenerResult,
+    SectorInfo,
+    Symbol,
+)
+
+__all__ = [
+    # Client
+    "OneFinanceClient",
+    # Models
+    "AnalystData",
+    "FinanceModel",
+    "PriceBar",
+    "Quote",
+    "IncomeStatement",
+    "BalanceSheet",
+    "CashFlow",
+    "CompanyInfo",
+    "CorporateAction",
+    "DCFValuation",
+    "EarningsRecord",
+    "FinancialRatios",
+    "ForwardEstimates",
+    "InsiderTrade",
+    "InstitutionalHolder",
+    "NewsArticle",
+    "OptionChain",
+    "OptionContract",
+    "ScreenerResult",
+    "SectorInfo",
+    "Symbol",
+    "Currency",
+    # Errors
+    "FinanceError",
+    "ProviderError",
+    "NotSupportedError",
+    "RateLimitError",
+    "AllProvidersFailedError",
+    # Indicators
+    "TechnicalIndicators",
+    "compute_indicators",
+]
+
+__version__ = "0.1.0"

onefinance/audit/__init__.py

@@ -0,0 +1,23 @@
+"""Audit log — structured tracing for every API invocation.
+
+Records provider calls, cache hits, tier-walking decisions, and
+errors so you can answer "which provider served this?" and
+"how many FMP calls did I burn today?"
+
+Usage::
+
+    from onefinance.audit import AuditLog, AuditEntry, AuditStats
+
+    log = AuditLog()
+    entries = log.query(provider="fmp", limit=10)
+    stats = log.stats()
+"""
+
+from onefinance.audit.models import AuditEntry, AuditStats
+from onefinance.audit.log import AuditLog
+
+__all__ = [
+    "AuditEntry",
+    "AuditLog",
+    "AuditStats",
+]

onefinance/audit/log.py

@@ -0,0 +1,325 @@
+"""JSONL file-backed audit log for provider API calls.
+
+Stores one JSON object per line (append-only).  Designed for low
+overhead (single line write per API call), human-readability
+(``cat audit.jsonl | jq``), and programmatic querying via the
+``query()`` and ``stats()`` helpers.
+
+Default location: ``~/.one_finance_data/audit/audit.jsonl``.
+Default retention: 30 days (pruned on startup).
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+from collections import defaultdict
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from typing import Any
+
+from onefinance.audit.models import AuditEntry, AuditStats
+
+logger = logging.getLogger(__name__)
+
+_DEFAULT_LOG_DIR = "~/.one_finance_data/audit"
+_DEFAULT_RETENTION_DAYS = 30
+
+
+class AuditLog:
+    """JSONL file-backed audit log for provider API calls.
+
+    Parameters
+    ----------
+    log_path:
+        Path to the JSONL log file.  If a directory is given,
+        ``audit.jsonl`` is appended.  Defaults to
+        ``~/.one_finance_data/audit/audit.jsonl``.
+    retention_days:
+        Entries older than this are pruned on startup.
+        Set to ``0`` to disable pruning.
+    enabled:
+        If ``False``, ``record()`` is a no-op.  Useful for tests
+        or when audit overhead is unwanted.
+    """
+
+    def __init__(
+        self,
+        log_path: str | Path | None = None,
+        retention_days: int = _DEFAULT_RETENTION_DAYS,
+        enabled: bool = True,
+    ) -> None:
+        self._enabled = enabled
+        self._retention_days = retention_days
+        self._path: Path | None = None
+
+        if not enabled:
+            return
+
+        resolved = Path(log_path or _DEFAULT_LOG_DIR).expanduser()
+        if resolved.is_dir() or not resolved.suffix:
+            resolved = resolved / "audit.jsonl"
+        resolved.parent.mkdir(parents=True, exist_ok=True)
+        self._path = resolved
+
+        # Auto-prune old entries
+        if retention_days > 0 and self._path.exists():
+            pruned = self._prune()
+            if pruned > 0:
+                logger.debug(
+                    "Pruned %d audit entries older than %d days",
+                    pruned, retention_days,
+                )
+
+    # -------------------------------------------------------------------
+    # Write
+    # -------------------------------------------------------------------
+
+    def record(self, entry: AuditEntry) -> None:
+        """Append an audit entry as a single JSON line.
+
+        No-op if the log is disabled.
+        """
+        if not self._enabled or self._path is None:
+            return
+
+        try:
+            line = json.dumps(entry.to_dict(), separators=(",", ":"))
+            with open(self._path, "a") as f:
+                f.write(line + "\n")
+        except Exception:
+            logger.debug("Failed to write audit entry", exc_info=True)
+
+    # -------------------------------------------------------------------
+    # Query
+    # -------------------------------------------------------------------
+
+    def query(
+        self,
+        *,
+        provider: str | None = None,
+        endpoint: str | None = None,
+        status: str | None = None,
+        symbol: str | None = None,
+        request_id: str | None = None,
+        since: datetime | None = None,
+        limit: int = 100,
+    ) -> list[AuditEntry]:
+        """Query audit entries with optional filters.
+
+        Returns newest-first, up to ``limit`` entries.
+        """
+        if not self._enabled or self._path is None or not self._path.exists():
+            return []
+
+        entries: list[AuditEntry] = []
+        for raw in self._read_lines():
+            try:
+                obj = json.loads(raw)
+            except json.JSONDecodeError:
+                continue
+
+            # Apply filters
+            if provider is not None and obj.get("provider") != provider:
+                continue
+            if endpoint is not None and obj.get("endpoint") != endpoint:
+                continue
+            if status is not None and obj.get("status") != status:
+                continue
+            if symbol is not None and (obj.get("symbol") or "").upper() != symbol.upper():
+                continue
+            if request_id is not None and obj.get("request_id") != request_id:
+                continue
+            if since is not None:
+                ts = _parse_ts(obj.get("timestamp", ""))
+                if ts is not None and ts < since:
+                    continue
+
+            entries.append(_dict_to_entry(obj))
+
+        # Newest-first, limited
+        entries.reverse()
+        return entries[:limit]
+
+    # -------------------------------------------------------------------
+    # Aggregate stats
+    # -------------------------------------------------------------------
+
+    def stats(
+        self,
+        *,
+        since: datetime | None = None,
+    ) -> AuditStats:
+        """Compute aggregate stats over a time range.
+
+        Parameters
+        ----------
+        since:
+            Start of the stats period.  Defaults to 24 hours ago.
+        """
+        if not self._enabled or self._path is None or not self._path.exists():
+            return AuditStats()
+
+        if since is None:
+            since = datetime.now(timezone.utc) - timedelta(days=1)
+
+        now = datetime.now(timezone.utc)
+
+        total_calls = 0
+        cache_hits = 0
+        calls_by: dict[str, int] = defaultdict(int)
+        errors_by: dict[str, int] = defaultdict(int)
+        rate_limits_by: dict[str, int] = defaultdict(int)
+        latencies_by: dict[str, list[float]] = defaultdict(list)
+
+        for raw in self._read_lines():
+            try:
+                obj = json.loads(raw)
+            except json.JSONDecodeError:
+                continue
+
+            ts = _parse_ts(obj.get("timestamp", ""))
+            if ts is not None and ts < since:
+                continue
+
+            prov = obj.get("provider", "unknown")
+            status = obj.get("status", "")
+
+            if status == "cache_hit":
+                cache_hits += 1
+                continue
+
+            # Skip not_supported and skipped — they aren't real calls
+            if status in ("not_supported", "skipped"):
+                continue
+
+            total_calls += 1
+            calls_by[prov] += 1
+            latencies_by[prov].append(obj.get("latency_ms", 0))
+
+            if status == "error":
+                errors_by[prov] += 1
+            elif status == "rate_limited":
+                rate_limits_by[prov] += 1
+                errors_by[prov] += 1
+
+        total_requests = total_calls + cache_hits
+        cache_hit_rate = cache_hits / total_requests if total_requests > 0 else 0.0
+
+        avg_latency = {
+            prov: round(sum(lats) / len(lats), 1)
+            for prov, lats in latencies_by.items()
+            if lats
+        }
+
+        return AuditStats(
+            total_calls=total_calls,
+            cache_hits=cache_hits,
+            cache_hit_rate=round(cache_hit_rate, 3),
+            calls_by_provider=dict(calls_by),
+            errors_by_provider=dict(errors_by),
+            avg_latency_ms_by_provider=avg_latency,
+            rate_limits_by_provider=dict(rate_limits_by),
+            period_start=since,
+            period_end=now,
+        )
+
+    # -------------------------------------------------------------------
+    # Maintenance
+    # -------------------------------------------------------------------
+
+    def _prune(self) -> int:
+        """Remove entries older than ``retention_days``.
+
+        Rewrites the file in-place, keeping only recent entries.
+        Returns the number of entries removed.
+        """
+        if self._path is None or not self._path.exists():
+            return 0
+
+        cutoff = datetime.now(timezone.utc) - timedelta(days=self._retention_days)
+        kept: list[str] = []
+        pruned = 0
+
+        for raw in self._read_lines():
+            try:
+                obj = json.loads(raw)
+                ts = _parse_ts(obj.get("timestamp", ""))
+                if ts is not None and ts < cutoff:
+                    pruned += 1
+                    continue
+            except json.JSONDecodeError:
+                pruned += 1
+                continue
+            kept.append(raw)
+
+        if pruned > 0:
+            with open(self._path, "w") as f:
+                for line in kept:
+                    f.write(line if line.endswith("\n") else line + "\n")
+
+        return pruned
+
+    def clear(self) -> None:
+        """Remove all entries from the audit log."""
+        if self._path is not None and self._path.exists():
+            self._path.write_text("")
+
+    def close(self) -> None:
+        """No-op for file-based log (no persistent connections)."""
+        pass
+
+    @property
+    def enabled(self) -> bool:
+        """Whether this audit log is active."""
+        return self._enabled
+
+    @property
+    def path(self) -> Path | None:
+        """Path to the log file, or None if disabled."""
+        return self._path
+
+    # -------------------------------------------------------------------
+    # Internal
+    # -------------------------------------------------------------------
+
+    def _read_lines(self) -> list[str]:
+        """Read all lines from the log file."""
+        if self._path is None or not self._path.exists():
+            return []
+        with open(self._path) as f:
+            return [line.strip() for line in f if line.strip()]
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _parse_ts(value: str) -> datetime | None:
+    """Parse an ISO timestamp string to datetime."""
+    if not value:
+        return None
+    try:
+        return datetime.fromisoformat(value)
+    except (ValueError, TypeError):
+        return None
+
+
+def _dict_to_entry(obj: dict[str, Any]) -> AuditEntry:
+    """Convert a JSON dict to an AuditEntry."""
+    return AuditEntry(
+        timestamp=_parse_ts(obj.get("timestamp", "")) or datetime.now(timezone.utc),
+        request_id=obj.get("request_id", ""),
+        endpoint=obj.get("endpoint", ""),
+        provider=obj.get("provider", ""),
+        symbol=obj.get("symbol"),
+        status=obj.get("status", ""),
+        latency_ms=obj.get("latency_ms", 0),
+        error_code=obj.get("error_code"),
+        error_message=obj.get("error_message"),
+        tier_position=obj.get("tier_position", 0),
+        tier_total=obj.get("tier_total", 1),
+        http_status=obj.get("http_status"),
+        cache_key=obj.get("cache_key"),
+    )

onefinance/audit/models.py

@@ -0,0 +1,116 @@
+"""Data models for the audit log.
+
+``AuditEntry`` is a single log row; ``AuditStats`` is aggregated
+statistics over a time range.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+
+
+@dataclass(frozen=True)
+class AuditEntry:
+    """Single audit log entry for one provider call attempt.
+
+    Attributes
+    ----------
+    timestamp:
+        UTC time when the call started.
+    request_id:
+        Short hex ID grouping all tier-walk attempts for one
+        ``dispatch()`` call.
+    endpoint:
+        Logical endpoint name (``"price_history"``, ``"quote"``, etc.).
+    provider:
+        Provider that handled this attempt (``"fmp"``, ``"cache"``, etc.).
+    symbol:
+        Ticker symbol, if extractable from the call context.
+    status:
+        Outcome — ``"success"``, ``"error"``, ``"rate_limited"``,
+        ``"skipped"``, ``"cache_hit"``, ``"not_supported"``.
+    latency_ms:
+        Wall-clock time for this attempt in milliseconds.
+    error_code:
+        Stable error code (e.g. ``"NETWORK_ERROR"``), or ``None``.
+    error_message:
+        Human-readable error detail, or ``None``.
+    tier_position:
+        0-indexed position of this provider in the tier list.
+    tier_total:
+        Total number of providers in the tier list.
+    http_status:
+        Raw HTTP status code, if available.
+    cache_key:
+        Cache key for ``cache_hit`` entries, ``None`` otherwise.
+    """
+
+    timestamp: datetime
+    request_id: str
+    endpoint: str
+    provider: str
+    symbol: str | None = None
+    status: str = "success"
+    latency_ms: float = 0.0
+    error_code: str | None = None
+    error_message: str | None = None
+    tier_position: int = 0
+    tier_total: int = 1
+    http_status: int | None = None
+    cache_key: str | None = None
+
+    def to_dict(self) -> dict:
+        """Serialise to a plain dictionary."""
+        return {
+            "timestamp": self.timestamp.isoformat(),
+            "request_id": self.request_id,
+            "endpoint": self.endpoint,
+            "provider": self.provider,
+            "symbol": self.symbol,
+            "status": self.status,
+            "latency_ms": round(self.latency_ms, 1),
+            "error_code": self.error_code,
+            "error_message": self.error_message,
+            "tier_position": self.tier_position,
+            "tier_total": self.tier_total,
+            "http_status": self.http_status,
+            "cache_key": self.cache_key,
+        }
+
+
+@dataclass
+class AuditStats:
+    """Aggregated statistics from audit entries.
+
+    Attributes
+    ----------
+    total_calls:
+        Total API call attempts (excludes cache hits).
+    cache_hits:
+        Number of requests served from cache.
+    cache_hit_rate:
+        Fraction of total requests served from cache (0.0–1.0).
+    calls_by_provider:
+        Number of API calls per provider.
+    errors_by_provider:
+        Number of errors per provider.
+    avg_latency_ms_by_provider:
+        Mean latency in ms per provider.
+    rate_limits_by_provider:
+        Number of rate-limit hits per provider.
+    period_start:
+        Start of the stats period.
+    period_end:
+        End of the stats period.
+    """
+
+    total_calls: int = 0
+    cache_hits: int = 0
+    cache_hit_rate: float = 0.0
+    calls_by_provider: dict[str, int] = field(default_factory=dict)
+    errors_by_provider: dict[str, int] = field(default_factory=dict)
+    avg_latency_ms_by_provider: dict[str, float] = field(default_factory=dict)
+    rate_limits_by_provider: dict[str, int] = field(default_factory=dict)
+    period_start: datetime | None = None
+    period_end: datetime | None = None

onefinance/cache/__init__.py

@@ -0,0 +1,11 @@
+"""Cache subpackage — diskcache-backed caching layer."""
+
+from onefinance.cache.keys import make_key
+from onefinance.cache.manager import CacheManager, default_ttl, ttl_for_price_history
+
+__all__ = [
+    "CacheManager",
+    "make_key",
+    "default_ttl",
+    "ttl_for_price_history",
+]

onefinance/cache/keys.py

@@ -0,0 +1,62 @@
+"""Cache key generation and parameter hashing.
+
+Keys are provider-agnostic: the same ``(symbol, date range)`` from
+FMP and yfinance share one cache key.  The ``source`` field on the
+returned model tells the caller which provider answered.
+
+Key format::
+
+    "{data_type}:{sha256(sorted_params)[:16]}"
+    # example: "price_history:a3f9c2e8b1d4f6a0"
+
+See design doc §10 for the full specification.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import Any
+
+
+def make_key(data_type: str, **params: Any) -> str:
+    """Build a cache key from a data type and arbitrary parameters.
+
+    Parameters are JSON-serialised with ``sort_keys=True`` before hashing
+    so argument order never causes misses.
+
+    Parameters
+    ----------
+    data_type:
+        Endpoint identifier, e.g. ``"price_history"``, ``"quote"``.
+    **params:
+        The call parameters (symbol, start, end, period, etc.).
+        Values are coerced to strings via ``_normalise_value`` so that
+        ``date(2024,1,1)`` and ``"2024-01-01"`` produce the same key.
+
+    Returns
+    -------
+    str
+        A deterministic cache key like ``"price_history:a3f9c2e8b1d4f6a0"``.
+    """
+    normalised = {k: _normalise_value(v) for k, v in params.items() if v is not None}
+    param_json = json.dumps(normalised, sort_keys=True, separators=(",", ":"))
+    param_hash = hashlib.sha256(param_json.encode()).hexdigest()[:16]
+    return f"{data_type}:{param_hash}"
+
+
+def _normalise_value(value: Any) -> str | int | float | bool | list | None:
+    """Coerce a parameter value to a JSON-friendly primitive.
+
+    Ensures that ``date(2024,1,1)`` and ``"2024-01-01"`` hash identically.
+    """
+    if value is None:
+        return None
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, (int, float)):
+        return value
+    # date / datetime → ISO string
+    if hasattr(value, "isoformat"):
+        return value.isoformat()
+    return str(value)