fmp-data 2.2.0__tar.gz → 2.2.1__tar.gz

{fmp_data-2.2.0 → fmp_data-2.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fmp-data
-Version: 2.2.0
+Version: 2.2.1
 Summary: Python client for the Financial Modeling Prep API
 Project-URL: Homepage, https://github.com/MehdiZare/fmp-data
 Project-URL: Repository, https://github.com/MehdiZare/fmp-data
@@ -30,6 +30,8 @@ Requires-Python: <3.15,>=3.10
 Requires-Dist: httpx>=0.28.1
 Requires-Dist: pydantic>=2.12.5
 Requires-Dist: tenacity>=9.1.2
+Provides-Extra: cache-redis
+Requires-Dist: redis>=5.0.0; extra == 'cache-redis'
 Provides-Extra: dev
 Requires-Dist: bandit[toml]>=1.9.3; extra == 'dev'
 Requires-Dist: coverage>=7.13.1; extra == 'dev'
@@ -95,6 +97,7 @@ This project uses UV as the primary package management tool for several key bene
 - Built-in rate limiting
 - Comprehensive logging
 - Async support
+- Opt-in response caching with memory, file, and Redis backends
 - Type hints and validation with Pydantic
 - Automatic retries with exponential backoff
 - 85%+ test coverage with comprehensive test suite
@@ -121,6 +124,9 @@ To use this library, you'll need an API key from Financial Modeling Prep (FMP).
 # Basic installation
 uv pip install fmp-data
 
+# With Redis cache backend support
+uv pip install "fmp-data[cache-redis]"
+
 # With Langchain integration
 uv pip install "fmp-data[langchain]"
 
@@ -139,12 +145,52 @@ LangChain integration requires LangChain v1 (`langchain-core`, `langchain-openai
 # Basic installation
 pip install fmp-data
 
+# With Redis cache backend support
+pip install "fmp-data[cache-redis]"
+
 # With extras
 pip install fmp-data[langchain]
 pip install fmp-data[mcp]
 pip install fmp-data[langchain,mcp]
 ```
 
+## Response Caching
+
+Response caching is optional and works for both sync and async clients.
+
+```python
+from fmp_data import CacheConfig, ClientConfig, FMPDataClient
+
+config = ClientConfig(
+    api_key="YOUR_FMP_API_KEY",  # pragma: allowlist secret
+    cache=CacheConfig(
+        backend="memory",
+        default_ttl=300,
+        ttl_overrides={"get_quote": 30},
+    ),
+)
+
+with FMPDataClient(config=config) as client:
+    quote = client.company.get_quote("AAPL")
+    fresh_quote = client.company.get_quote("AAPL", force_refresh=True)
+```
+
+You can also configure caching from the environment:
+
+```bash
+export FMP_CACHE_ENABLED=true
+export FMP_CACHE_BACKEND=file
+export FMP_CACHE_TTL=300
+export FMP_CACHE_DIR=.cache/fmp-data
+```
+
+For Redis-backed caching, install the optional extra and set:
+
+```bash
+export FMP_CACHE_BACKEND=redis
+export FMP_CACHE_REDIS_URL=redis://localhost:6379/0
+```
+
 ## MCP Server (Claude Desktop Integration)
 
 Model Context Protocol (MCP) server provides financial data access through a standardized protocol, enabling Claude Desktop to query FMP data seamlessly.

{fmp_data-2.2.0 → fmp_data-2.2.1}/README.md

@@ -27,6 +27,7 @@ This project uses UV as the primary package management tool for several key bene
 - Built-in rate limiting
 - Comprehensive logging
 - Async support
+- Opt-in response caching with memory, file, and Redis backends
 - Type hints and validation with Pydantic
 - Automatic retries with exponential backoff
 - 85%+ test coverage with comprehensive test suite
@@ -53,6 +54,9 @@ To use this library, you'll need an API key from Financial Modeling Prep (FMP).
 # Basic installation
 uv pip install fmp-data
 
+# With Redis cache backend support
+uv pip install "fmp-data[cache-redis]"
+
 # With Langchain integration
 uv pip install "fmp-data[langchain]"
 
@@ -71,12 +75,52 @@ LangChain integration requires LangChain v1 (`langchain-core`, `langchain-openai
 # Basic installation
 pip install fmp-data
 
+# With Redis cache backend support
+pip install "fmp-data[cache-redis]"
+
 # With extras
 pip install fmp-data[langchain]
 pip install fmp-data[mcp]
 pip install fmp-data[langchain,mcp]
 ```
 
+## Response Caching
+
+Response caching is optional and works for both sync and async clients.
+
+```python
+from fmp_data import CacheConfig, ClientConfig, FMPDataClient
+
+config = ClientConfig(
+    api_key="YOUR_FMP_API_KEY",  # pragma: allowlist secret
+    cache=CacheConfig(
+        backend="memory",
+        default_ttl=300,
+        ttl_overrides={"get_quote": 30},
+    ),
+)
+
+with FMPDataClient(config=config) as client:
+    quote = client.company.get_quote("AAPL")
+    fresh_quote = client.company.get_quote("AAPL", force_refresh=True)
+```
+
+You can also configure caching from the environment:
+
+```bash
+export FMP_CACHE_ENABLED=true
+export FMP_CACHE_BACKEND=file
+export FMP_CACHE_TTL=300
+export FMP_CACHE_DIR=.cache/fmp-data
+```
+
+For Redis-backed caching, install the optional extra and set:
+
+```bash
+export FMP_CACHE_BACKEND=redis
+export FMP_CACHE_REDIS_URL=redis://localhost:6379/0
+```
+
 ## MCP Server (Claude Desktop Integration)
 
 Model Context Protocol (MCP) server provides financial data access through a standardized protocol, enabling Claude Desktop to query FMP data seamlessly.

{fmp_data-2.2.0 → fmp_data-2.2.1}/fmp_data/__init__.py

@@ -19,6 +19,7 @@ import types as _types
 from typing import Any
 
 from fmp_data.async_client import AsyncFMPDataClient
+from fmp_data.cache.config import CacheConfig
 from fmp_data.client import FMPDataClient
 from fmp_data.config import (
     ClientConfig,
@@ -48,6 +49,7 @@ except ImportError:
 __all__ = [
     "AsyncFMPDataClient",
     "AuthenticationError",
+    "CacheConfig",
     "ClientConfig",
     "ConfigError",
     "FMPDataClient",

{fmp_data-2.2.0 → fmp_data-2.2.1}/fmp_data/base.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 
 import asyncio
 from contextvars import ContextVar
+import copy
 import json
 import logging
 import time
@@ -22,6 +23,7 @@ from tenacity import (
     wait_exponential,
 )
 
+from fmp_data.cache.base import CacheBackend
 from fmp_data.config import ClientConfig
 from fmp_data.exceptions import (
     AuthenticationError,
@@ -83,6 +85,22 @@ class BaseClient:
         # Async client (lazily initialized)
         self._async_client: httpx.AsyncClient | None = None
 
+        # Response cache (optional)
+        self._cache: CacheBackend | None = None
+        cache_cfg = getattr(config, "cache", None)
+        if cache_cfg is not None and getattr(cache_cfg, "enabled", False) is True:
+            from fmp_data.cache import create_backend
+            from fmp_data.cache.config import CacheConfig
+
+            if isinstance(cache_cfg, CacheConfig):
+                self._cache = create_backend(cache_cfg)
+                self._cache_ttl_overrides = cache_cfg.ttl_overrides
+                self._cache_default_ttl = cache_cfg.default_ttl
+                self.logger.info(
+                    "Response caching enabled (backend=%s)",
+                    cache_cfg.backend,
+                )
+
     def _setup_http_client(self) -> None:
         """
         Setup HTTP client with default configuration.
@@ -137,6 +155,85 @@ class BaseClient:
         # Also close sync client
         self.close()
 
+    @staticmethod
+    def _build_cache_key(endpoint_name: str, params: dict[str, Any]) -> str:
+        """Build a deterministic cache key from endpoint name and params.
+
+        Excludes 'apikey' to avoid leaking secrets in keys.
+        Uses urllib.parse.urlencode to properly escape special characters
+        and prevent key collisions from values containing '&' or '='.
+        """
+        import hashlib
+        import urllib.parse
+
+        filtered = {k: v for k, v in sorted(params.items()) if k != "apikey"}
+        params_str = urllib.parse.urlencode(filtered, doseq=True)
+
+        # codeql[py/weak-sensitive-data-hashing]
+        # This hash is only used to shorten cache keys, not for credential storage.
+        params_hash = hashlib.sha256(
+            params_str.encode(), usedforsecurity=False
+        ).hexdigest()[:16]
+        return f"{endpoint_name}:{params_hash}"
+
+    def _get_cache_ttl(self, endpoint_name: str) -> int:
+        """Get TTL for a given endpoint, checking overrides first."""
+        if not hasattr(self, "_cache_ttl_overrides"):
+            return 300
+        return self._cache_ttl_overrides.get(endpoint_name, self._cache_default_ttl)
+
+    def _cache_get(
+        self, endpoint_name: str, cache_key: str
+    ) -> dict[str, Any] | list[Any] | None:
+        """Read from cache, returning None on any failure."""
+        assert self._cache is not None
+        try:
+            cached = self._cache.get(cache_key)
+            return None if cached is None else copy.deepcopy(cached)
+        except Exception:
+            self.logger.warning(
+                "Cache read failed for %s", endpoint_name, exc_info=True
+            )
+            return None
+
+    async def _cache_aget(
+        self, endpoint_name: str, cache_key: str
+    ) -> dict[str, Any] | list[Any] | None:
+        """Async read from cache, returning None on any failure."""
+        assert self._cache is not None
+        try:
+            cached = await self._cache.aget(cache_key)
+            return None if cached is None else copy.deepcopy(cached)
+        except Exception:
+            self.logger.warning(
+                "Cache read failed for %s", endpoint_name, exc_info=True
+            )
+            return None
+
+    def _cache_set(
+        self, endpoint_name: str, cache_key: str, data: Any, ttl: int
+    ) -> None:
+        """Write to cache, logging on failure."""
+        assert self._cache is not None
+        try:
+            self._cache.set(cache_key, copy.deepcopy(data), ttl)
+        except Exception:
+            self.logger.warning(
+                "Cache write failed for %s", endpoint_name, exc_info=True
+            )
+
+    async def _cache_aset(
+        self, endpoint_name: str, cache_key: str, data: Any, ttl: int
+    ) -> None:
+        """Async write to cache, logging on failure."""
+        assert self._cache is not None
+        try:
+            await self._cache.aset(cache_key, copy.deepcopy(data), ttl)
+        except Exception:
+            self.logger.warning(
+                "Cache write failed for %s", endpoint_name, exc_info=True
+            )
+
     def _handle_rate_limit(self, wait_time: float) -> None:
         """
         Handle rate limiting by waiting or raising an exception based on retry count.
@@ -225,18 +322,12 @@ class BaseClient:
         Returns:
             Either a single Pydantic model of type T or a list of T.
         """
-        # Check rate limit before making request
-        if not self._rate_limiter.should_allow_request():
-            wait_time = self._rate_limiter.get_wait_time()
-            self._handle_rate_limit(wait_time)
-
         request_start = time.perf_counter()
         status_code = 0
         success = False
+        force_refresh = kwargs.pop("force_refresh", False)
 
         try:
-            self._rate_limiter.record_request()
-
             # Validate and process parameters
             validated_params = endpoint.validate_params(
                 kwargs,
@@ -250,6 +341,35 @@ class BaseClient:
             query_params = endpoint.get_query_params(validated_params)
             query_params["apikey"] = self.config.api_key
 
+            # Check cache before rate limiting — cache hits are free
+            cache_key: str | None = None
+            if (
+                self._cache is not None
+                and not force_refresh
+                and endpoint.response_model is not bytes
+            ):
+                cache_key = self._build_cache_key(endpoint.name, query_params)
+                cached = self._cache_get(endpoint.name, cache_key)
+                if cached is not None:
+                    self.logger.debug(
+                        "Cache hit for %s",
+                        endpoint.name,
+                        extra={"endpoint": endpoint.name, "cache_key": cache_key},
+                    )
+                    success = True
+                    return self._process_response(
+                        endpoint,
+                        cached,
+                        validation_mode=self.config.validation_mode,
+                    )
+
+            # Check rate limit only when making an actual HTTP request
+            if not self._rate_limiter.should_allow_request():
+                wait_time = self._rate_limiter.get_wait_time()
+                self._handle_rate_limit(wait_time)
+
+            self._rate_limiter.record_request()
+
             self.logger.debug(
                 f"Making request to {endpoint.name}",
                 extra={
@@ -277,6 +397,12 @@ class BaseClient:
                     validation_mode=self.config.validation_mode,
                 )
                 success = True
+
+                # Store in cache
+                if self._cache is not None and cache_key is not None:
+                    ttl = self._get_cache_ttl(endpoint.name)
+                    self._cache_set(endpoint.name, cache_key, data, ttl)
+
                 return result
             finally:
                 response.close()
@@ -697,32 +823,9 @@ class BaseClient:
         Returns:
             Either a single Pydantic model of type T or a list of T.
         """
-        # Check rate limit using async rate limiter (concurrency-safe)
-        if not await self._async_rate_limiter.should_allow_request():
-            wait_time = self._async_rate_limiter.get_wait_time()
-            current_count = _rate_limit_retry_count.get() + 1
-            _rate_limit_retry_count.set(current_count)
-
-            if current_count > self.max_rate_limit_retries:
-                _rate_limit_retry_count.set(0)
-                raise RateLimitError(
-                    f"Rate limit exceeded after "
-                    f"{self.max_rate_limit_retries} retries. "
-                    f"Please wait {wait_time:.1f} seconds",
-                    retry_after=wait_time,
-                )
-
-            self.logger.warning(
-                f"Rate limit reached "
-                f"(attempt {current_count}/"
-                f"{self.max_rate_limit_retries}), "
-                f"waiting {wait_time:.1f} seconds before retrying"
-            )
-            await asyncio.sleep(wait_time)
+        force_refresh = kwargs.pop("force_refresh", False)
 
         try:
-            await self._async_rate_limiter.record_request()
-
             # Validate and process parameters
             validated_params = endpoint.validate_params(
                 kwargs,
@@ -736,6 +839,52 @@ class BaseClient:
             query_params = endpoint.get_query_params(validated_params)
             query_params["apikey"] = self.config.api_key
 
+            # Check cache before rate limiting — cache hits are free
+            cache_key: str | None = None
+            if (
+                self._cache is not None
+                and not force_refresh
+                and endpoint.response_model is not bytes
+            ):
+                cache_key = self._build_cache_key(endpoint.name, query_params)
+                cached = await self._cache_aget(endpoint.name, cache_key)
+                if cached is not None:
+                    self.logger.debug(
+                        "Cache hit for %s",
+                        endpoint.name,
+                        extra={"endpoint": endpoint.name, "cache_key": cache_key},
+                    )
+                    return self._process_response(
+                        endpoint,
+                        cached,
+                        validation_mode=self.config.validation_mode,
+                    )
+
+            # Check rate limit only when making an actual HTTP request
+            if not await self._async_rate_limiter.should_allow_request():
+                wait_time = self._async_rate_limiter.get_wait_time()
+                current_count = _rate_limit_retry_count.get() + 1
+                _rate_limit_retry_count.set(current_count)
+
+                if current_count > self.max_rate_limit_retries:
+                    _rate_limit_retry_count.set(0)
+                    raise RateLimitError(
+                        f"Rate limit exceeded after "
+                        f"{self.max_rate_limit_retries} retries. "
+                        f"Please wait {wait_time:.1f} seconds",
+                        retry_after=wait_time,
+                    )
+
+                self.logger.warning(
+                    f"Rate limit reached "
+                    f"(attempt {current_count}/"
+                    f"{self.max_rate_limit_retries}), "
+                    f"waiting {wait_time:.1f} seconds before retrying"
+                )
+                await asyncio.sleep(wait_time)
+
+            await self._async_rate_limiter.record_request()
+
             self.logger.debug(
                 f"Making async request to {endpoint.name}",
                 extra={
@@ -757,11 +906,18 @@ class BaseClient:
                     data = response.content
                 else:
                     data = self.handle_response(endpoint, response)
-                return self._process_response(
+                result = self._process_response(
                     endpoint,
                     data,
                     validation_mode=self.config.validation_mode,
                 )
+
+                # Store in cache
+                if self._cache is not None and cache_key is not None:
+                    ttl = self._get_cache_ttl(endpoint.name)
+                    await self._cache_aset(endpoint.name, cache_key, data, ttl)
+
+                return result
             finally:
                 await response.aclose()
 

fmp_data-2.2.1/fmp_data/cache/__init__.py

@@ -0,0 +1,48 @@
+"""Response caching for FMP Data API client.
+
+Provides pluggable cache backends (memory, file, redis) to reduce
+redundant API calls and improve latency for repeated queries.
+"""
+
+from __future__ import annotations
+
+from fmp_data.cache.base import CacheBackend
+from fmp_data.cache.config import CacheConfig
+from fmp_data.cache.file import FileCache
+from fmp_data.cache.memory import MemoryCache
+
+__all__ = [
+    "CacheBackend",
+    "CacheConfig",
+    "FileCache",
+    "MemoryCache",
+    "create_backend",
+]
+
+
+def create_backend(config: CacheConfig) -> CacheBackend:
+    """Instantiate a cache backend from configuration.
+
+    Args:
+        config: Cache configuration
+
+    Returns:
+        A ready-to-use CacheBackend instance
+
+    Raises:
+        ValueError: If the backend type is unknown
+        ImportError: If redis backend is requested but redis is not installed
+    """
+    if config.backend == "memory":
+        return MemoryCache(default_ttl=config.default_ttl)
+    if config.backend == "file":
+        from pathlib import Path
+
+        cache_dir = config.cache_dir or Path.home() / ".cache" / "fmp-data"
+        return FileCache(cache_dir=cache_dir, default_ttl=config.default_ttl)
+    if config.backend == "redis":
+        from fmp_data.cache.redis_backend import RedisCache
+
+        redis_url = config.redis_url or "redis://localhost:6379/0"
+        return RedisCache(redis_url=redis_url, default_ttl=config.default_ttl)
+    raise ValueError(f"Unknown cache backend: {config.backend!r}")

fmp_data-2.2.1/fmp_data/cache/base.py

@@ -0,0 +1,56 @@
+"""Abstract cache backend interface."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+import asyncio
+from typing import Any
+
+
+class CacheBackend(ABC):
+    """Abstract base class for cache backends."""
+
+    @abstractmethod
+    def get(self, key: str) -> Any | None:
+        """Retrieve a value from the cache.
+
+        Args:
+            key: Cache key
+
+        Returns:
+            Cached value or None if not found / expired
+        """
+
+    @abstractmethod
+    def set(self, key: str, value: Any, ttl: int | None = None) -> None:
+        """Store a value in the cache.
+
+        Args:
+            key: Cache key
+            value: Value to cache
+            ttl: Time-to-live in seconds (None = use backend default)
+        """
+
+    @abstractmethod
+    def delete(self, key: str) -> None:
+        """Remove a key from the cache."""
+
+    @abstractmethod
+    def clear(self) -> None:
+        """Remove all entries from the cache."""
+
+    async def aget(self, key: str) -> Any | None:
+        """Async variant of get. Offloads to a thread by default."""
+        return await asyncio.to_thread(self.get, key)
+
+    async def aset(self, key: str, value: Any, ttl: int | None = None) -> None:
+        """Async variant of set. Offloads to a thread by default."""
+        await asyncio.to_thread(self.set, key, value, ttl)
+
+    async def adelete(self, key: str) -> None:
+        """Async variant of delete. Offloads to a thread by default."""
+        await asyncio.to_thread(self.delete, key)
+
+    async def aclear(self) -> None:
+        """Async variant of clear. Offloads to a thread by default."""
+        await asyncio.to_thread(self.clear)

fmp_data-2.2.1/fmp_data/cache/config.py

@@ -0,0 +1,58 @@
+"""Cache configuration models."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+
+class CacheConfig(BaseModel):
+    """Configuration for the response cache."""
+
+    enabled: bool = Field(default=True, description="Whether caching is enabled")
+    backend: Literal["memory", "file", "redis"] = Field(
+        default="memory", description="Cache backend type"
+    )
+    default_ttl: int = Field(default=300, gt=0, description="Default TTL in seconds")
+    ttl_overrides: dict[str, int] = Field(
+        default_factory=dict,
+        description="Per-endpoint TTL overrides (endpoint_name -> seconds)",
+    )
+    cache_dir: Path | None = Field(
+        default=None, description="Directory for file-based cache"
+    )
+    redis_url: str | None = Field(default=None, description="Redis connection URL")
+
+    @classmethod
+    def from_env(cls) -> CacheConfig | None:
+        """Create cache config from environment variables.
+
+        Returns None if FMP_CACHE_ENABLED is not set or is 'false'.
+        """
+        enabled_str = os.getenv("FMP_CACHE_ENABLED", "").lower()
+        if enabled_str not in ("true", "1", "yes"):
+            return None
+
+        cache_dir_str = os.getenv("FMP_CACHE_DIR")
+        cache_dir = Path(cache_dir_str) if cache_dir_str else None
+
+        try:
+            ttl = int(os.getenv("FMP_CACHE_TTL", "300"))
+            ttl = max(1, ttl)
+        except (ValueError, TypeError):
+            ttl = 300
+
+        backend_str = os.getenv("FMP_CACHE_BACKEND", "memory")
+        if backend_str not in ("memory", "file", "redis"):
+            backend_str = "memory"
+
+        return cls(
+            enabled=True,
+            backend=backend_str,
+            default_ttl=ttl,
+            cache_dir=cache_dir,
+            redis_url=os.getenv("FMP_CACHE_REDIS_URL"),
+        )