fastapi-memory 0.1.0__tar.gz

fastapi_memory-0.1.0/LICENSE

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

fastapi_memory-0.1.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include README.md
+include LICENSE
+include fastapi_memory/py.typed

fastapi_memory-0.1.0/PKG-INFO

@@ -0,0 +1,233 @@
+Metadata-Version: 2.4
+Name: fastapi-memory
+Version: 0.1.0
+Summary: Caching, retry and resilient-HTTP helpers for FastAPI services.
+Author-email: Alexander Stankovic <alexdarka@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/alexdarka/fastapi-memory
+Project-URL: Repository, https://github.com/alexdarka/fastapi-memory
+Keywords: fastapi,cache,caching,retry,tenacity,httpx,resilience,redis
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Framework :: FastAPI
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: fastapi-cache2>=0.2.2
+Requires-Dist: tenacity>=8.3.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: jinja2>=3.1.0
+Provides-Extra: redis
+Requires-Dist: redis>=5.0.0; extra == "redis"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocs; extra == "docs"
+Requires-Dist: mkdocs-material; extra == "docs"
+Requires-Dist: mkdocstrings[python]; extra == "docs"
+Dynamic: license-file
+
+# fastapi-memory
+
+Caching, retry, and resilient-HTTP helpers for FastAPI services.
+
+A single package that provides response caching, retry policies, a resilient
+async HTTP client, and cached config singletons — tailored for FastAPI
+projects that talk to upstream APIs.
+
+```python
+from fastapi_memory import (
+    FmCacheManager, FmMemoryBackend, memorize,
+    retry, stop_after_retries, exponential_backoff, retry_on_error,
+    fm_lru,
+)
+```
+
+## Why
+
+Most FastAPI services that proxy slower or less-reliable upstream APIs end up
+re-writing the same patterns:
+
+1. A **cache** for endpoints or data that don't change often.
+2. A **retry policy** for upstream calls — retry network errors and 5xx, but not 4xx.
+3. A **cached singleton** config object (build once, reuse everywhere).
+4. A **resilient HTTP client** with connection pooling and retries baked in.
+
+`fastapi-memory` consolidates all of these into one import, with ready-made
+helpers so you don't have to re-derive common patterns every time.
+
+## Installation
+
+```bash
+# Editable install (local development)
+pip install -e /path/to/fastapi-memory
+
+# From PyPI (once published)
+pip install fastapi-memory
+
+# With optional Redis cache backend support
+pip install "fastapi-memory[redis]"
+```
+
+## What's inside
+
+| Module       | Provides                                                          | Adds                                                      |
+|--------------|-------------------------------------------------------------------|-----------------------------------------------------------|
+| `caching`    | `FmCacheManager`, `FmMemoryBackend`, `memorize`, `FmRedisBackend` | `init_cache()`, `clear_cache()`                           |
+| `resilience` | `retry`, `stop_after_retries`, `exponential_backoff`, `retry_on_error` | `default_retry()`, `is_retryable_httpx_error()`           |
+| `config`     | `fm_lru`                                                          | `cached_singleton`                                        |
+| `http`       | —                                                                 | `FmResilientClient`                                       |
+
+Everything above is re-exported from the top-level `fastapi_memory` package,
+so `from fastapi_memory import <anything in the table>` works.
+
+---
+
+## Quick start
+
+### Caching — response caching with a single call
+
+```python
+from contextlib import asynccontextmanager
+from fastapi import FastAPI
+from fastapi_memory import init_cache, clear_cache, memorize
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    init_cache(prefix="app-cache")  # in-memory (default)
+    yield
+
+app = FastAPI(lifespan=lifespan)
+
+@app.get("/api/data")
+@memorize(expire=60)
+async def get_data():
+    return {"data": "computed result"}
+
+@app.post("/api/cache/invalidate")
+async def invalidate_cache():
+    await clear_cache()
+    return {"ok": True}
+```
+
+### Switching to Redis later
+
+```python
+init_cache(backend="redis", prefix="app-cache", redis_url="redis://localhost:6379")
+```
+
+### Retry — exponential backoff with sensible defaults
+
+```python
+from fastapi_memory import default_retry
+
+@default_retry()
+async def call_upstream():
+    resp = await client.get(url)
+    resp.raise_for_status()
+    return resp.json()
+```
+
+`default_retry()` retries up to 3 times with exponential backoff (2s–10s),
+skip 4xx, reraise on final failure. Override any piece:
+
+```python
+@default_retry(attempts=5, wait_max=30)
+async def flaky_call():
+    ...
+```
+
+### Config — cached singleton
+
+```python
+from fastapi_memory import cached_singleton
+
+class Settings:
+    BASE_URL: str = "http://api.example.com:8080"
+    CACHE_TTL: int = 300
+
+@cached_singleton
+def get_settings() -> Settings:
+    return Settings()
+
+config = get_settings()
+```
+
+### Resilient HTTP client
+
+```python
+from contextlib import asynccontextmanager
+from fastapi import FastAPI
+from fastapi_memory import FmResilientClient, init_cache
+
+upstream = FmResilientClient(
+    base_url="http://api.example.com:8080",
+    timeout=30.0,
+)
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    await upstream.start()
+    init_cache(prefix="app-cache")
+    yield
+    await upstream.aclose()
+
+app = FastAPI(lifespan=lifespan)
+
+@app.get("/api/data")
+async def get_data():
+    return await upstream.get_json("data")
+```
+
+`upstream.get_raw(path, params)` is also available if you want the raw
+exceptions instead of `HTTPException`.
+
+---
+
+## Project layout
+
+```
+fastapi-memory/
+├── pyproject.toml
+├── setup.py
+├── README.md
+├── LICENSE
+├── fastapi_memory/
+│   ├── __init__.py          # re-exports everything
+│   ├── caching.py            # FmCacheManager, FmMemoryBackend, memorize, init_cache, clear_cache
+│   ├── resilience.py         # retry + default_retry, is_retryable_httpx_error
+│   ├── config.py             # fm_lru + cached_singleton
+│   └── http.py               # FmResilientClient
+└── tests/
+    └── test_imports.py
+```
+
+## Updating `requirements.txt`
+
+Replace:
+
+```
+tenacity>=8.3.0
+fastapi-cache2>=0.2.2
+redis>=5.0.0
+```
+
+with:
+
+```
+fastapi-memory @ file:///path/to/fastapi-memory
+```
+
+(or once published: `fastapi-memory>=0.1.0`, optionally `fastapi-memory[redis]`.)

fastapi_memory-0.1.0/README.md

@@ -0,0 +1,192 @@
+# fastapi-memory
+
+Caching, retry, and resilient-HTTP helpers for FastAPI services.
+
+A single package that provides response caching, retry policies, a resilient
+async HTTP client, and cached config singletons — tailored for FastAPI
+projects that talk to upstream APIs.
+
+```python
+from fastapi_memory import (
+    FmCacheManager, FmMemoryBackend, memorize,
+    retry, stop_after_retries, exponential_backoff, retry_on_error,
+    fm_lru,
+)
+```
+
+## Why
+
+Most FastAPI services that proxy slower or less-reliable upstream APIs end up
+re-writing the same patterns:
+
+1. A **cache** for endpoints or data that don't change often.
+2. A **retry policy** for upstream calls — retry network errors and 5xx, but not 4xx.
+3. A **cached singleton** config object (build once, reuse everywhere).
+4. A **resilient HTTP client** with connection pooling and retries baked in.
+
+`fastapi-memory` consolidates all of these into one import, with ready-made
+helpers so you don't have to re-derive common patterns every time.
+
+## Installation
+
+```bash
+# Editable install (local development)
+pip install -e /path/to/fastapi-memory
+
+# From PyPI (once published)
+pip install fastapi-memory
+
+# With optional Redis cache backend support
+pip install "fastapi-memory[redis]"
+```
+
+## What's inside
+
+| Module       | Provides                                                          | Adds                                                      |
+|--------------|-------------------------------------------------------------------|-----------------------------------------------------------|
+| `caching`    | `FmCacheManager`, `FmMemoryBackend`, `memorize`, `FmRedisBackend` | `init_cache()`, `clear_cache()`                           |
+| `resilience` | `retry`, `stop_after_retries`, `exponential_backoff`, `retry_on_error` | `default_retry()`, `is_retryable_httpx_error()`           |
+| `config`     | `fm_lru`                                                          | `cached_singleton`                                        |
+| `http`       | —                                                                 | `FmResilientClient`                                       |
+
+Everything above is re-exported from the top-level `fastapi_memory` package,
+so `from fastapi_memory import <anything in the table>` works.
+
+---
+
+## Quick start
+
+### Caching — response caching with a single call
+
+```python
+from contextlib import asynccontextmanager
+from fastapi import FastAPI
+from fastapi_memory import init_cache, clear_cache, memorize
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    init_cache(prefix="app-cache")  # in-memory (default)
+    yield
+
+app = FastAPI(lifespan=lifespan)
+
+@app.get("/api/data")
+@memorize(expire=60)
+async def get_data():
+    return {"data": "computed result"}
+
+@app.post("/api/cache/invalidate")
+async def invalidate_cache():
+    await clear_cache()
+    return {"ok": True}
+```
+
+### Switching to Redis later
+
+```python
+init_cache(backend="redis", prefix="app-cache", redis_url="redis://localhost:6379")
+```
+
+### Retry — exponential backoff with sensible defaults
+
+```python
+from fastapi_memory import default_retry
+
+@default_retry()
+async def call_upstream():
+    resp = await client.get(url)
+    resp.raise_for_status()
+    return resp.json()
+```
+
+`default_retry()` retries up to 3 times with exponential backoff (2s–10s),
+skip 4xx, reraise on final failure. Override any piece:
+
+```python
+@default_retry(attempts=5, wait_max=30)
+async def flaky_call():
+    ...
+```
+
+### Config — cached singleton
+
+```python
+from fastapi_memory import cached_singleton
+
+class Settings:
+    BASE_URL: str = "http://api.example.com:8080"
+    CACHE_TTL: int = 300
+
+@cached_singleton
+def get_settings() -> Settings:
+    return Settings()
+
+config = get_settings()
+```
+
+### Resilient HTTP client
+
+```python
+from contextlib import asynccontextmanager
+from fastapi import FastAPI
+from fastapi_memory import FmResilientClient, init_cache
+
+upstream = FmResilientClient(
+    base_url="http://api.example.com:8080",
+    timeout=30.0,
+)
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    await upstream.start()
+    init_cache(prefix="app-cache")
+    yield
+    await upstream.aclose()
+
+app = FastAPI(lifespan=lifespan)
+
+@app.get("/api/data")
+async def get_data():
+    return await upstream.get_json("data")
+```
+
+`upstream.get_raw(path, params)` is also available if you want the raw
+exceptions instead of `HTTPException`.
+
+---
+
+## Project layout
+
+```
+fastapi-memory/
+├── pyproject.toml
+├── setup.py
+├── README.md
+├── LICENSE
+├── fastapi_memory/
+│   ├── __init__.py          # re-exports everything
+│   ├── caching.py            # FmCacheManager, FmMemoryBackend, memorize, init_cache, clear_cache
+│   ├── resilience.py         # retry + default_retry, is_retryable_httpx_error
+│   ├── config.py             # fm_lru + cached_singleton
+│   └── http.py               # FmResilientClient
+└── tests/
+    └── test_imports.py
+```
+
+## Updating `requirements.txt`
+
+Replace:
+
+```
+tenacity>=8.3.0
+fastapi-cache2>=0.2.2
+redis>=5.0.0
+```
+
+with:
+
+```
+fastapi-memory @ file:///path/to/fastapi-memory
+```
+
+(or once published: `fastapi-memory>=0.1.0`, optionally `fastapi-memory[redis]`.)

fastapi_memory-0.1.0/fastapi_memory/__init__.py

@@ -0,0 +1,74 @@
+"""
+fastapi-memory
+==============
+
+Caching, retry, and resilient-HTTP helpers for FastAPI services.
+
+This package provides response caching, retry policies, a resilient async
+HTTP client, and cached config singletons — all in one import, designed for
+FastAPI services that talk to slower upstream APIs.
+
+Import from this package instead of juggling multiple dependencies directly::
+
+    from fastapi_memory import (
+        FmCacheManager, FmMemoryBackend, memorize,
+        retry, stop_after_retries, exponential_backoff, retry_on_error,
+        fm_lru,
+    )
+
+Higher-level helpers
+---------------------
+On top of the re-exports, fastapi-memory adds a few small conveniences:
+
+- ``init_cache()``              -> one-line ``FmCacheManager`` setup (memory or Redis)
+- ``clear_cache()``              -> ``await FmCacheManager.clear()``
+- ``default_retry()``            -> the "3 attempts, exponential backoff, skip 4xx" policy
+- ``is_retryable_httpx_error``   -> the retry predicate behind ``default_retry``
+- ``cached_singleton``           -> ``@fm_lru(maxsize=1)`` for settings-style singletons
+- ``FmResilientClient``           -> persistent ``httpx.AsyncClient`` + retries + JSON helpers
+
+See the README for full usage examples and a migration guide.
+"""
+
+from .caching import (
+    FmCacheManager,
+    FmMemoryBackend,
+    FmRedisBackend,
+    memorize,
+    clear_cache,
+    init_cache,
+)
+from .config import cached_singleton, fm_lru
+from .http import FmResilientClient
+from .resilience import (
+    default_retry,
+    is_retryable_httpx_error,
+    retry,
+    retry_on_error,
+    stop_after_retries,
+    exponential_backoff,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # caching
+    "FmCacheManager",
+    "FmMemoryBackend",
+    "FmRedisBackend",
+    "memorize",
+    "init_cache",
+    "clear_cache",
+    # resilience
+    "retry",
+    "stop_after_retries",
+    "exponential_backoff",
+    "retry_on_error",
+    "default_retry",
+    "is_retryable_httpx_error",
+    # config
+    "fm_lru",
+    "cached_singleton",
+    # http
+    "FmResilientClient",
+]

fastapi_memory-0.1.0/fastapi_memory/caching.py

@@ -0,0 +1,117 @@
+"""
+Thin convenience layer around fastapi-cache2.
+
+Re-exports the pieces you already use directly (``FmCacheManager``,
+``FmMemoryBackend``, ``memorize``) and adds two small helpers:
+
+- :func:`init_cache` - one-line setup for an in-memory or Redis-backed cache
+- :func:`clear_cache` - ``await FmCacheManager.clear()``
+
+The Redis backend is optional. Install it with::
+
+    pip install "fastapi-memory[redis]"
+
+If ``redis`` isn't installed, ``FmRedisBackend`` is simply ``None`` and
+``init_cache(backend="redis", ...)`` raises a clear ``RuntimeError``
+explaining how to fix it. The default ``backend="memory"`` works with no
+extra dependencies, exactly like the original::
+
+    FmCacheManager.init(FmMemoryBackend(), prefix="app-cache")
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from fastapi_cache import FastAPICache
+from fastapi_cache.backends.inmemory import InMemoryBackend
+from fastapi_cache.decorator import cache
+
+# Aliases under fastapi-memory namespace
+FmCacheManager = FastAPICache
+FmMemoryBackend = InMemoryBackend
+memorize = cache
+
+try:  # pragma: no cover - exercised only when the `redis` extra is installed
+    from fastapi_cache.backends.redis import RedisBackend
+    from redis.asyncio import from_url as _redis_from_url
+
+    FmRedisBackend = RedisBackend
+    _REDIS_AVAILABLE = True
+except ImportError:  # pragma: no cover - redis extra not installed
+    FmRedisBackend = None  # type: ignore[assignment, misc]
+    _redis_from_url = None
+    _REDIS_AVAILABLE = False
+
+
+def init_cache(
+    backend: str = "memory",
+    *,
+    prefix: str = "fastapi-cache",
+    redis_url: Optional[str] = None,
+) -> None:
+    """
+    Initialise :class:`FmCacheManager` with either an in-memory backend
+    (default) or a Redis backend.
+
+    Call this once during application startup, typically inside a
+    ``lifespan`` handler::
+
+        from contextlib import asynccontextmanager
+        from fastapi import FastAPI
+        from fastapi_memory import init_cache
+
+        @asynccontextmanager
+        async def lifespan(app: FastAPI):
+            init_cache(prefix="app-cache")  # in-memory (default)
+            yield
+
+        app = FastAPI(lifespan=lifespan)
+
+    For Redis, pass ``backend="redis"`` and a connection URL::
+
+        init_cache(backend="redis", prefix="app-cache", redis_url="redis://localhost:6379")
+
+    Parameters
+    ----------
+    backend:
+        ``"memory"`` (default) or ``"redis"``.
+    prefix:
+        Cache-key prefix, passed straight through to ``FmCacheManager.init``.
+    redis_url:
+        Connection string for Redis, e.g. ``redis://localhost:6379``.
+        Required when ``backend="redis"``.
+    """
+    if backend == "memory":
+        FmCacheManager.init(FmMemoryBackend(), prefix=prefix)
+        return
+
+    if backend == "redis":
+        if not _REDIS_AVAILABLE:
+            raise RuntimeError(
+                "Redis backend requested but the 'redis' package is not "
+                "installed. Install it with: pip install fastapi-memory[redis]"
+            )
+        if not redis_url:
+            raise ValueError("redis_url is required when backend='redis'")
+
+        client = _redis_from_url(redis_url, encoding="utf8", decode_responses=False)
+        FmCacheManager.init(FmRedisBackend(client), prefix=prefix)
+        return
+
+    raise ValueError(f"Unknown backend {backend!r}, expected 'memory' or 'redis'")
+
+
+async def clear_cache() -> None:
+    """Clear the entire cache - thin wrapper around ``await FmCacheManager.clear()``."""
+    await FmCacheManager.clear()
+
+
+__all__ = [
+    "FmCacheManager",
+    "FmMemoryBackend",
+    "FmRedisBackend",
+    "memorize",
+    "init_cache",
+    "clear_cache",
+]

fastapi_memory-0.1.0/fastapi_memory/config.py

@@ -0,0 +1,34 @@
+"""
+Tiny helper built on top of ``functools.lru_cache`` for the
+"build-it-once-and-reuse-it" settings/config pattern.
+
+Re-exports ``lru_cache`` as ``fm_lru``, plus :func:`cached_singleton`, a
+small shorthand for the common::
+
+    @fm_lru(maxsize=1)
+    def get_settings() -> Settings:
+        return Settings()
+
+pattern.
+"""
+
+from __future__ import annotations
+
+from functools import lru_cache
+from typing import Callable, TypeVar
+
+T = TypeVar("T")
+
+# Alias under fastapi-memory namespace
+fm_lru = lru_cache
+
+
+def cached_singleton(func: Callable[[], T]) -> Callable[[], T]:
+    """
+    Shorthand for ``@fm_lru(maxsize=1)`` - turns a zero-argument factory
+    function into a cached singleton getter.
+    """
+    return fm_lru(maxsize=1)(func)
+
+
+__all__ = ["fm_lru", "cached_singleton"]