inhouse-cache 0.1.1__tar.gz

inhouse_cache-0.1.1/.gitignore

@@ -0,0 +1,177 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Local development notes
+.working_sessions/*

inhouse_cache-0.1.1/LICENSE

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

inhouse_cache-0.1.1/PKG-INFO

@@ -0,0 +1,325 @@
+Metadata-Version: 2.4
+Name: inhouse-cache
+Version: 0.1.1
+Summary: Zero-dependency, in-process TTL cache for Python. Optional FastAPI decorators, stampede-safe, LRU-bounded.
+Project-URL: Homepage, https://github.com/kineticquant/inhouse
+Project-URL: Repository, https://github.com/kineticquant/inhouse
+Project-URL: Issues, https://github.com/kineticquant/inhouse/issues
+Author-email: Michael Mooney <inhouse@rancero.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: async,cache,fastapi,lru,ttl
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: fastapi>=0.100; extra == 'dev'
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.100; extra == 'fastapi'
+Description-Content-Type: text/markdown
+
+# inhouse
+
+**Zero-dependency, in-process TTL cache for Python.** One decorator, stampede-safe, LRU-bounded. For when Redis is a meeting you don't want to have, or when you need to avoid yet another deployment. Designed to be simple and effective without bloat or complexity for developers.
+
+Designed for easy use with FastAPI applications. Although FastAPI integration is absolutely optional.
+
+## Install
+
+The package is published on PyPI as **`inhouse-cache`**. Imports use `inhouse` (e.g. `from inhouse import MemoryStore`).
+
+Core:
+```bash
+pip install inhouse-cache
+```
+
+With FastAPI helpers (`fastapi_cache`, lifespan sweeper):
+```bash
+pip install inhouse-cache[fastapi]
+```
+
+## Quick start Usage
+
+### Core (any Python project)
+
+```python
+from inhouse import MemoryStore, inhouse_cache
+
+store = MemoryStore(max_size=1024, default_ttl=60)
+
+
+@inhouse_cache(store=store)
+async def load_user(user_id: int) -> dict[str, int]:
+    return {"user_id": user_id}
+```
+
+Works with both `async def` and `def` callables.
+
+### FastAPI Use Case
+
+```python
+import asyncio
+
+from fastapi import FastAPI
+
+from inhouse import MemoryStore
+from inhouse.fastapi import create_lifespan, fastapi_cache
+
+store = MemoryStore(max_size=1024, default_ttl=60)
+app = FastAPI(lifespan=create_lifespan(store))
+
+
+@app.get("/items/{item_id}")
+@fastapi_cache(store=store)
+async def get_item(item_id: int) -> dict[str, int]:
+    await asyncio.sleep(0.1)  # expensive work
+    return {"item_id": item_id}
+```
+
+Requires `pip install inhouse-cache[fastapi]`.
+
+## Features
+
+**Core (zero dependencies)**
+
+- TTL cache with lazy expiry on read
+- LRU eviction when `max_size` is exceeded
+- Per-key singleflight stampede guard - concurrent misses on the same key coalesce to one computation. Errors and cancellations propagate to all waiters (no hung followers on shutdown)
+- Deterministic cache keys - canonical JSON serialization. Keyword argument order and Request subclasses don't cause spurious cache misses
+- Thread-safe store for sync and async callables
+- Fixed, store-default, or callable TTL on each cache write
+
+**Optional FastAPI extra** (`pip install inhouse-cache[fastapi]`)
+
+- `@fastapi_cache` with Request/Response-aware cache keys
+- Background expiry sweeper via FastAPI lifespan helpers
+- Clean lifespan shutdown - background sweeper cancels without noisy tracebacks
+
+## Configuration reference
+
+### `MemoryStore`
+
+```python
+from inhouse import MemoryStore
+
+store = MemoryStore(max_size=1024, default_ttl=60)
+```
+
+| Parameter / attribute | Type | Default | Description |
+|---|---|---|---|
+| `max_size` | `int` | `1024` | Maximum number of entries before LRU eviction |
+| `default_ttl` | `float \| None` | `None` | Default TTL in seconds for `store.set()` and decorators that omit `ttl_seconds` |
+| `default_ttl` (property) | `float \| None` | — | Mutable at runtime; affects **future** writes only |
+| `size` | `int` (read-only) | — | Current number of cached entries |
+
+Store methods:
+
+| Method | Description |
+|---|---|
+| `get(key, *, default=MISS)` | Return a cached value, or `default` on miss/expiry |
+| `set(key, value, ttl_seconds=None)` | Write a value; uses `default_ttl` when `ttl_seconds` is omitted |
+| `delete(key)` | Remove one entry |
+| `clear()` | Remove all entries |
+| `purge_expired()` | Proactively delete expired entries |
+| `keys()` | List current cache keys |
+
+### `@inhouse_cache` / `cache()`
+
+Core decorator. Works with both `async def` and `def` callables.
+
+```python
+from inhouse import MemoryStore, inhouse_cache, make_cache_key
+
+store = MemoryStore(default_ttl=60)
+
+@inhouse_cache(
+    ttl_seconds=60,          # optional — see Dynamic TTL below
+    store=store,             # optional — defaults to a module-level store
+    key_builder=make_cache_key,  # optional — custom cache key strategy
+    exclude_types=(object,),     # optional — types omitted from key material
+)
+async def load_user(user_id: int) -> dict[str, int]:
+    return {"user_id": user_id}
+```
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `ttl_seconds` | `float \| Callable[[], float] \| None` | `None` | TTL in seconds for each cache write. See [Dynamic TTL](#dynamic-ttl). |
+| `store` | `MemoryStore \| None` | module default | Cache instance to read/write |
+| `key_builder` | `Callable[..., str]` | `make_cache_key` | Builds the cache key from function identity + arguments |
+| `exclude_types` | `tuple[type, ...]` | `()` | Argument types excluded from key material (e.g. request objects) |
+
+`inhouse_cache` is an alias for `cache`.
+
+Global default store helpers:
+
+```python
+from inhouse import configure_default_store, get_default_store
+
+store = MemoryStore(default_ttl=120)
+configure_default_store(store)
+
+@inhouse_cache()  # uses the configured default store + its default_ttl
+async def load_config() -> dict[str, str]:
+    ...
+```
+
+### `@fastapi_cache` *(optional — requires `inhouse-cache[fastapi]`)*
+
+FastAPI-friendly wrapper around `inhouse_cache`. Automatically excludes Starlette `Request` and `Response` objects from cache keys.
+
+```python
+from inhouse.fastapi import create_lifespan, fastapi_cache
+
+store = MemoryStore(max_size=512, default_ttl=60)
+app = FastAPI(lifespan=create_lifespan(store, sweep_interval=30.0))
+
+@app.get("/items/{item_id}")
+@fastapi_cache(store=store)
+async def get_item(item_id: int) -> dict[str, int]:
+    ...
+```
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `ttl_seconds` | `float \| Callable[[], float] \| None` | `None` | Same semantics as `@inhouse_cache` |
+| `store` | `MemoryStore \| None` | module default | Cache instance to read/write |
+
+`fastapi_cache` does not expose `key_builder` or `exclude_types`; it always uses the FastAPI-aware key builder.
+
+### Lifespan / background cleanup *(optional — requires `inhouse-cache[fastapi]`)*
+
+```python
+from inhouse.fastapi import create_lifespan, inhouse_lifespan
+
+# Option A: pass directly to FastAPI
+app = FastAPI(lifespan=create_lifespan(store, sweep_interval=30.0))
+
+# Option B: use inside your own lifespan
+async with inhouse_lifespan(store, sweep_interval=30.0):
+    ...
+```
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `store` | `MemoryStore` | required | Store to sweep for expired entries |
+| `sweep_interval` | `float` | `30.0` | Seconds between background purge runs |
+
+## Dynamic TTL
+
+TTL is resolved when a value is **written** to the cache (on a miss), not on every read. Changing TTL settings does not retroactively extend entries already stored.
+
+Three ways to configure expiration:
+
+### 1. Fixed TTL (per route)
+
+```python
+@inhouse_cache(60, store=store)
+async def load_user(user_id: int) -> dict[str, int]:
+    ...
+```
+
+Always expires 60 seconds after the value is cached.
+
+### 2. Store default (mutable at runtime)
+
+```python
+store = MemoryStore(default_ttl=60)
+
+@inhouse_cache(store=store)
+async def load_config() -> dict[str, str]:
+    ...
+
+# Later - affects future cache writes only
+store.default_ttl = 300
+```
+
+Omitting `ttl_seconds` on the decorator uses `store.default_ttl`. If both are missing, inhouse raises `ValueError`.
+
+`store.default_ttl` is safe to change at runtime from other threads; new writes pick up the updated value atomically.
+
+### 3. Callable TTL (evaluated on each write)
+
+```python
+settings = {"cache_ttl": 60}
+
+@inhouse_cache(lambda: settings["cache_ttl"], store=store)
+async def load_dashboard() -> dict[str, str]:
+    ...
+
+settings["cache_ttl"] = 300  # next cache miss uses 300 seconds
+```
+
+Useful for feature flags, config files, or environment-driven TTL without redeploying.
+
+### Priority order
+
+When a cache miss is written, TTL is resolved as:
+
+1. Callable `ttl_seconds()` result, if a callable was passed
+2. Fixed `ttl_seconds` float, if provided
+3. `store.default_ttl`, if set
+4. Otherwise → `ValueError`
+
+## When to use inhouse
+
+| Scenario | inhouse | Redis | fastapi-cache2 |
+|---|---|---|---|
+| Single-node FastAPI prototype | Great | Overkill | Great |
+| Zero external infrastructure | Yes | No | Depends on backend |
+| Distributed multi-instance cache | No | Yes | Yes (with Redis) |
+| Decorator-first developer UX | Yes | No | Yes |
+
+## Important limitations
+
+inhouse is **per-process** memory. If you run `uvicorn main:app --workers 4`, each worker maintains its own independent cache. That keeps the design simple and avoids shared infrastructure. It is not a distributed cache.
+
+## Architecture
+
+```mermaid
+flowchart TB
+    subgraph fastapi_layer [Optional FastAPI Layer]
+        Decorator["@fastapi_cache"]
+        Lifespan["lifespan: start/stop sweeper"]
+    end
+
+    subgraph core [Zero-Dependency Core]
+        KeyBuilder["make_cache_key()"]
+        Store["MemoryStore"]
+        Singleflight["PerKeySingleflight"]
+        Sweeper["ExpirySweeper"]
+    end
+
+    Decorator --> KeyBuilder
+    Decorator --> Store
+    Decorator --> Singleflight
+    Lifespan --> Sweeper
+    Sweeper --> Store
+    Store -->|"OrderedDict + TTL entries"| Memory[(In-Process Memory)]
+```
+
+## Core API
+
+The core package has no runtime dependencies. Import from `inhouse` directly:
+
+```python
+from inhouse import MemoryStore, configure_default_store, inhouse_cache, make_cache_key
+```
+
+See [Configuration reference](#configuration-reference) for full decorator and store options.
+
+## License
+
+MIT

inhouse_cache-0.1.1/README.md

@@ -0,0 +1,293 @@
+# inhouse
+
+**Zero-dependency, in-process TTL cache for Python.** One decorator, stampede-safe, LRU-bounded. For when Redis is a meeting you don't want to have, or when you need to avoid yet another deployment. Designed to be simple and effective without bloat or complexity for developers.
+
+Designed for easy use with FastAPI applications. Although FastAPI integration is absolutely optional.
+
+## Install
+
+The package is published on PyPI as **`inhouse-cache`**. Imports use `inhouse` (e.g. `from inhouse import MemoryStore`).
+
+Core:
+```bash
+pip install inhouse-cache
+```
+
+With FastAPI helpers (`fastapi_cache`, lifespan sweeper):
+```bash
+pip install inhouse-cache[fastapi]
+```
+
+## Quick start Usage
+
+### Core (any Python project)
+
+```python
+from inhouse import MemoryStore, inhouse_cache
+
+store = MemoryStore(max_size=1024, default_ttl=60)
+
+
+@inhouse_cache(store=store)
+async def load_user(user_id: int) -> dict[str, int]:
+    return {"user_id": user_id}
+```
+
+Works with both `async def` and `def` callables.
+
+### FastAPI Use Case
+
+```python
+import asyncio
+
+from fastapi import FastAPI
+
+from inhouse import MemoryStore
+from inhouse.fastapi import create_lifespan, fastapi_cache
+
+store = MemoryStore(max_size=1024, default_ttl=60)
+app = FastAPI(lifespan=create_lifespan(store))
+
+
+@app.get("/items/{item_id}")
+@fastapi_cache(store=store)
+async def get_item(item_id: int) -> dict[str, int]:
+    await asyncio.sleep(0.1)  # expensive work
+    return {"item_id": item_id}
+```
+
+Requires `pip install inhouse-cache[fastapi]`.
+
+## Features
+
+**Core (zero dependencies)**
+
+- TTL cache with lazy expiry on read
+- LRU eviction when `max_size` is exceeded
+- Per-key singleflight stampede guard - concurrent misses on the same key coalesce to one computation. Errors and cancellations propagate to all waiters (no hung followers on shutdown)
+- Deterministic cache keys - canonical JSON serialization. Keyword argument order and Request subclasses don't cause spurious cache misses
+- Thread-safe store for sync and async callables
+- Fixed, store-default, or callable TTL on each cache write
+
+**Optional FastAPI extra** (`pip install inhouse-cache[fastapi]`)
+
+- `@fastapi_cache` with Request/Response-aware cache keys
+- Background expiry sweeper via FastAPI lifespan helpers
+- Clean lifespan shutdown - background sweeper cancels without noisy tracebacks
+
+## Configuration reference
+
+### `MemoryStore`
+
+```python
+from inhouse import MemoryStore
+
+store = MemoryStore(max_size=1024, default_ttl=60)
+```
+
+| Parameter / attribute | Type | Default | Description |
+|---|---|---|---|
+| `max_size` | `int` | `1024` | Maximum number of entries before LRU eviction |
+| `default_ttl` | `float \| None` | `None` | Default TTL in seconds for `store.set()` and decorators that omit `ttl_seconds` |
+| `default_ttl` (property) | `float \| None` | — | Mutable at runtime; affects **future** writes only |
+| `size` | `int` (read-only) | — | Current number of cached entries |
+
+Store methods:
+
+| Method | Description |
+|---|---|
+| `get(key, *, default=MISS)` | Return a cached value, or `default` on miss/expiry |
+| `set(key, value, ttl_seconds=None)` | Write a value; uses `default_ttl` when `ttl_seconds` is omitted |
+| `delete(key)` | Remove one entry |
+| `clear()` | Remove all entries |
+| `purge_expired()` | Proactively delete expired entries |
+| `keys()` | List current cache keys |
+
+### `@inhouse_cache` / `cache()`
+
+Core decorator. Works with both `async def` and `def` callables.
+
+```python
+from inhouse import MemoryStore, inhouse_cache, make_cache_key
+
+store = MemoryStore(default_ttl=60)
+
+@inhouse_cache(
+    ttl_seconds=60,          # optional — see Dynamic TTL below
+    store=store,             # optional — defaults to a module-level store
+    key_builder=make_cache_key,  # optional — custom cache key strategy
+    exclude_types=(object,),     # optional — types omitted from key material
+)
+async def load_user(user_id: int) -> dict[str, int]:
+    return {"user_id": user_id}
+```
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `ttl_seconds` | `float \| Callable[[], float] \| None` | `None` | TTL in seconds for each cache write. See [Dynamic TTL](#dynamic-ttl). |
+| `store` | `MemoryStore \| None` | module default | Cache instance to read/write |
+| `key_builder` | `Callable[..., str]` | `make_cache_key` | Builds the cache key from function identity + arguments |
+| `exclude_types` | `tuple[type, ...]` | `()` | Argument types excluded from key material (e.g. request objects) |
+
+`inhouse_cache` is an alias for `cache`.
+
+Global default store helpers:
+
+```python
+from inhouse import configure_default_store, get_default_store
+
+store = MemoryStore(default_ttl=120)
+configure_default_store(store)
+
+@inhouse_cache()  # uses the configured default store + its default_ttl
+async def load_config() -> dict[str, str]:
+    ...
+```
+
+### `@fastapi_cache` *(optional — requires `inhouse-cache[fastapi]`)*
+
+FastAPI-friendly wrapper around `inhouse_cache`. Automatically excludes Starlette `Request` and `Response` objects from cache keys.
+
+```python
+from inhouse.fastapi import create_lifespan, fastapi_cache
+
+store = MemoryStore(max_size=512, default_ttl=60)
+app = FastAPI(lifespan=create_lifespan(store, sweep_interval=30.0))
+
+@app.get("/items/{item_id}")
+@fastapi_cache(store=store)
+async def get_item(item_id: int) -> dict[str, int]:
+    ...
+```
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `ttl_seconds` | `float \| Callable[[], float] \| None` | `None` | Same semantics as `@inhouse_cache` |
+| `store` | `MemoryStore \| None` | module default | Cache instance to read/write |
+
+`fastapi_cache` does not expose `key_builder` or `exclude_types`; it always uses the FastAPI-aware key builder.
+
+### Lifespan / background cleanup *(optional — requires `inhouse-cache[fastapi]`)*
+
+```python
+from inhouse.fastapi import create_lifespan, inhouse_lifespan
+
+# Option A: pass directly to FastAPI
+app = FastAPI(lifespan=create_lifespan(store, sweep_interval=30.0))
+
+# Option B: use inside your own lifespan
+async with inhouse_lifespan(store, sweep_interval=30.0):
+    ...
+```
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `store` | `MemoryStore` | required | Store to sweep for expired entries |
+| `sweep_interval` | `float` | `30.0` | Seconds between background purge runs |
+
+## Dynamic TTL
+
+TTL is resolved when a value is **written** to the cache (on a miss), not on every read. Changing TTL settings does not retroactively extend entries already stored.
+
+Three ways to configure expiration:
+
+### 1. Fixed TTL (per route)
+
+```python
+@inhouse_cache(60, store=store)
+async def load_user(user_id: int) -> dict[str, int]:
+    ...
+```
+
+Always expires 60 seconds after the value is cached.
+
+### 2. Store default (mutable at runtime)
+
+```python
+store = MemoryStore(default_ttl=60)
+
+@inhouse_cache(store=store)
+async def load_config() -> dict[str, str]:
+    ...
+
+# Later - affects future cache writes only
+store.default_ttl = 300
+```
+
+Omitting `ttl_seconds` on the decorator uses `store.default_ttl`. If both are missing, inhouse raises `ValueError`.
+
+`store.default_ttl` is safe to change at runtime from other threads; new writes pick up the updated value atomically.
+
+### 3. Callable TTL (evaluated on each write)
+
+```python
+settings = {"cache_ttl": 60}
+
+@inhouse_cache(lambda: settings["cache_ttl"], store=store)
+async def load_dashboard() -> dict[str, str]:
+    ...
+
+settings["cache_ttl"] = 300  # next cache miss uses 300 seconds
+```
+
+Useful for feature flags, config files, or environment-driven TTL without redeploying.
+
+### Priority order
+
+When a cache miss is written, TTL is resolved as:
+
+1. Callable `ttl_seconds()` result, if a callable was passed
+2. Fixed `ttl_seconds` float, if provided
+3. `store.default_ttl`, if set
+4. Otherwise → `ValueError`
+
+## When to use inhouse
+
+| Scenario | inhouse | Redis | fastapi-cache2 |
+|---|---|---|---|
+| Single-node FastAPI prototype | Great | Overkill | Great |
+| Zero external infrastructure | Yes | No | Depends on backend |
+| Distributed multi-instance cache | No | Yes | Yes (with Redis) |
+| Decorator-first developer UX | Yes | No | Yes |
+
+## Important limitations
+
+inhouse is **per-process** memory. If you run `uvicorn main:app --workers 4`, each worker maintains its own independent cache. That keeps the design simple and avoids shared infrastructure. It is not a distributed cache.
+
+## Architecture
+
+```mermaid
+flowchart TB
+    subgraph fastapi_layer [Optional FastAPI Layer]
+        Decorator["@fastapi_cache"]
+        Lifespan["lifespan: start/stop sweeper"]
+    end
+
+    subgraph core [Zero-Dependency Core]
+        KeyBuilder["make_cache_key()"]
+        Store["MemoryStore"]
+        Singleflight["PerKeySingleflight"]
+        Sweeper["ExpirySweeper"]
+    end
+
+    Decorator --> KeyBuilder
+    Decorator --> Store
+    Decorator --> Singleflight
+    Lifespan --> Sweeper
+    Sweeper --> Store
+    Store -->|"OrderedDict + TTL entries"| Memory[(In-Process Memory)]
+```
+
+## Core API
+
+The core package has no runtime dependencies. Import from `inhouse` directly:
+
+```python
+from inhouse import MemoryStore, configure_default_store, inhouse_cache, make_cache_key
+```
+
+See [Configuration reference](#configuration-reference) for full decorator and store options.
+
+## License
+
+MIT

inhouse_cache-0.1.1/pyproject.toml

@@ -0,0 +1,71 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "inhouse-cache"
+version = "0.1.1"
+description = "Zero-dependency, in-process TTL cache for Python. Optional FastAPI decorators, stampede-safe, LRU-bounded."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "Michael Mooney", email = "inhouse@rancero.com" }]
+keywords = ["cache", "fastapi", "ttl", "lru", "async"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Framework :: FastAPI",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = []
+
+[project.optional-dependencies]
+fastapi = ["fastapi>=0.100"]
+dev = [
+    "fastapi>=0.100",
+    "httpx>=0.27",
+    "mypy>=1.10",
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "ruff>=0.4",
+]
+
+[project.urls]
+Homepage = "https://github.com/kineticquant/inhouse"
+Repository = "https://github.com/kineticquant/inhouse"
+Issues = "https://github.com/kineticquant/inhouse/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/inhouse"]
+
+[tool.hatch.build.targets.wheel.sources]
+"src/inhouse" = "inhouse"
+
+[tool.hatch.build.targets.sdist]
+include = ["src/inhouse", "README.md", "LICENSE"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+warn_return_any = true
+warn_unused_configs = true
+
+[[tool.mypy.overrides]]
+module = "tests.*"
+disallow_untyped_defs = false

inhouse_cache-0.1.1/src/inhouse/__init__.py

@@ -0,0 +1,19 @@
+"""inhouse — zero-dependency, in-process TTL cache with LRU eviction."""
+
+from inhouse.decorator import cache, configure_default_store, get_default_store, inhouse_cache
+from inhouse.entry import CacheEntry
+from inhouse.keys import make_cache_key
+from inhouse.store import MemoryStore
+from inhouse.sweeper import ExpirySweeper
+
+__all__ = [
+    "CacheEntry",
+    "ExpirySweeper",
+    "MemoryStore",
+    "cache",
+    "configure_default_store",
+    "get_default_store",
+    "inhouse_cache",
+    "make_cache_key",
+]
+__version__ = "0.1.1"

inhouse_cache-0.1.1/src/inhouse/decorator.py

@@ -0,0 +1,112 @@
+from __future__ import annotations
+
+import inspect
+from collections.abc import Callable
+from functools import wraps
+from typing import Any, TypeVar
+
+from inhouse.keys import make_cache_key
+from inhouse.singleflight import AsyncSingleflight, SyncSingleflight
+from inhouse.store import MISS, MemoryStore
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+TtlSource = float | Callable[[], float] | None
+
+_DEFAULT_STORE = MemoryStore()
+_ASYNC_SINGLEFLIGHT = AsyncSingleflight()
+_SYNC_SINGLEFLIGHT = SyncSingleflight()
+
+
+def get_default_store() -> MemoryStore:
+    return _DEFAULT_STORE
+
+
+def configure_default_store(store: MemoryStore) -> None:
+    global _DEFAULT_STORE
+    _DEFAULT_STORE = store
+
+
+def _resolve_ttl(target_store: MemoryStore, ttl_seconds: TtlSource) -> float:
+    if callable(ttl_seconds):
+        resolved = ttl_seconds()
+    elif ttl_seconds is not None:
+        resolved = ttl_seconds
+    elif target_store.default_ttl is not None:
+        resolved = target_store.default_ttl
+    else:
+        raise ValueError("ttl_seconds is required when the store has no default_ttl")
+
+    if resolved <= 0:
+        raise ValueError("ttl_seconds must be positive")
+    return resolved
+
+
+def cache(
+    ttl_seconds: TtlSource = None,
+    *,
+    store: MemoryStore | None = None,
+    key_builder: Callable[..., str] = make_cache_key,
+    exclude_types: tuple[type[Any], ...] = (),
+) -> Callable[[F], F]:
+    """Cache decorator for sync and async callables."""
+
+    def decorator(func: F) -> F:
+        if inspect.iscoroutinefunction(func):
+
+            @wraps(func)
+            async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
+                target_store = store or _DEFAULT_STORE
+                cache_key = key_builder(
+                    func,
+                    args,
+                    kwargs,
+                    exclude_types=exclude_types,
+                )
+
+                cached = target_store.get(cache_key)
+                if cached is not MISS:
+                    return cached
+
+                async def compute() -> Any:
+                    recheck = target_store.get(cache_key)
+                    if recheck is not MISS:
+                        return recheck
+                    result = await func(*args, **kwargs)
+                    target_store.set(cache_key, result, _resolve_ttl(target_store, ttl_seconds))
+                    return result
+
+                return await _ASYNC_SINGLEFLIGHT.do(cache_key, compute)
+
+            return async_wrapper  # type: ignore[return-value]
+
+        @wraps(func)
+        def sync_wrapper(*args: Any, **kwargs: Any) -> Any:
+            target_store = store or _DEFAULT_STORE
+            cache_key = key_builder(
+                func,
+                args,
+                kwargs,
+                exclude_types=exclude_types,
+            )
+
+            cached = target_store.get(cache_key)
+            if cached is not MISS:
+                return cached
+
+            def compute() -> Any:
+                recheck = target_store.get(cache_key)
+                if recheck is not MISS:
+                    return recheck
+                result = func(*args, **kwargs)
+                target_store.set(cache_key, result, _resolve_ttl(target_store, ttl_seconds))
+                return result
+
+            return _SYNC_SINGLEFLIGHT.do(cache_key, compute)
+
+        return sync_wrapper  # type: ignore[return-value]
+
+    return decorator
+
+
+inhouse_cache = cache

inhouse_cache-0.1.1/src/inhouse/entry.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(slots=True)
+class CacheEntry:
+    expires_at: float
+    value: Any

inhouse_cache-0.1.1/src/inhouse/fastapi.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Callable
+from contextlib import AbstractAsyncContextManager, asynccontextmanager
+from typing import Any
+
+from inhouse.decorator import cache, inhouse_cache
+from inhouse.keys import make_cache_key
+from inhouse.store import MemoryStore
+from inhouse.sweeper import ExpirySweeper
+
+# MUST have fastapi which uses starlette to work with RR tuple
+try:
+    from starlette.requests import Request
+    from starlette.responses import Response
+
+    _FASTAPI_EXCLUDE_TYPES: tuple[type[Any], ...] = (Request, Response)
+except ImportError:  # pragma: no cover - optional dependency, technically
+    _FASTAPI_EXCLUDE_TYPES = ()
+
+
+def make_fastapi_cache_key(
+    func: Any,
+    args: Any,
+    kwargs: Any,
+    *,
+    exclude_types: tuple[type[Any], ...] = (),
+) -> str:
+    merged_exclude = _FASTAPI_EXCLUDE_TYPES + exclude_types
+    return make_cache_key(func, args, kwargs, exclude_types=merged_exclude)
+
+
+def fastapi_cache(
+    ttl_seconds: float | Callable[[], float] | None = None,
+    *,
+    store: MemoryStore | None = None,
+) -> Callable[[Any], Any]:
+    """Cache decorator that excludes Starlette Request/Response objects from keys."""
+    return inhouse_cache(
+        ttl_seconds,
+        store=store,
+        key_builder=make_fastapi_cache_key,
+    )
+
+
+@asynccontextmanager
+async def inhouse_lifespan(
+    store: MemoryStore,
+    *,
+    sweep_interval: float = 30.0,
+) -> AsyncIterator[None]:
+    """FastAPI lifespan helper that starts and stops the expiry sweeper."""
+    sweeper = ExpirySweeper(store, interval_seconds=sweep_interval)
+    task = sweeper.start()
+    try:
+        yield
+    finally:
+        await sweeper.stop(task)
+
+
+def create_lifespan(
+    store: MemoryStore,
+    *,
+    sweep_interval: float = 30.0,
+) -> Callable[[Any], AbstractAsyncContextManager[None]]:
+    """Return a FastAPI-compatible lifespan callable bound to a cache store."""
+
+    @asynccontextmanager
+    async def lifespan(_app: Any) -> AsyncIterator[None]:
+        async with inhouse_lifespan(store, sweep_interval=sweep_interval):
+            yield
+
+    return lifespan
+
+
+__all__ = [
+    "cache",
+    "create_lifespan",
+    "fastapi_cache",
+    "inhouse_cache",
+    "inhouse_lifespan",
+    "make_fastapi_cache_key",
+]

inhouse_cache-0.1.1/src/inhouse/keys.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+import hashlib
+import json
+from collections.abc import Callable, Mapping, Sequence
+from typing import Any
+
+
+def _normalize_value(value: Any) -> Any:
+    if isinstance(value, Mapping):
+        return {
+            str(k): _normalize_value(v)
+            for k, v in sorted(value.items(), key=lambda item: str(item[0]))
+        }
+    if isinstance(value, list | tuple):
+        return [_normalize_value(item) for item in value]
+    if isinstance(value, str | int | float | bool) or value is None:
+        return value
+    return str(value)
+
+
+def _collect_key_material(
+    args: Sequence[Any],
+    kwargs: Mapping[str, Any],
+    exclude_types: tuple[type[Any], ...],
+) -> dict[str, Any]:
+    filtered_args = [arg for arg in args if not isinstance(arg, exclude_types)]
+    filtered_kwargs = {
+        key: value for key, value in sorted(kwargs.items()) if not isinstance(value, exclude_types)
+    }
+    return {
+        "args": [_normalize_value(arg) for arg in filtered_args],
+        "kwargs": {key: _normalize_value(value) for key, value in filtered_kwargs.items()},
+    }
+
+
+def make_cache_key(
+    func: Callable[..., Any],
+    args: Sequence[Any],
+    kwargs: Mapping[str, Any],
+    *,
+    exclude_types: tuple[type[Any], ...] = (),
+) -> str:
+    """Build a deterministic cache key from function identity and call arguments."""
+    material = _collect_key_material(args, kwargs, exclude_types)
+    payload = json.dumps(material, sort_keys=True, separators=(",", ":"))
+    digest = hashlib.sha256(payload.encode("utf-8")).hexdigest()
+    return f"{func.__module__}.{func.__qualname__}:{digest}"

inhouse_cache-0.1.1/src/inhouse/singleflight.py

@@ -0,0 +1,93 @@
+from __future__ import annotations
+
+import asyncio
+import threading
+from collections.abc import Awaitable, Callable
+from concurrent.futures import Future
+from typing import Any, TypeVar
+
+T = TypeVar("T")
+
+
+def _release_async_waiters(future: asyncio.Future[Any], exc: BaseException) -> None:
+    if future.done():
+        return
+    if isinstance(exc, asyncio.CancelledError):
+        future.cancel()
+    else:
+        future.set_exception(exc)
+
+
+def _release_sync_waiters(future: Future[Any], exc: BaseException) -> None:
+    if not future.done():
+        future.set_exception(exc)
+
+
+class AsyncSingleflight:
+    """Coalesce concurrent async computations for the same cache key."""
+
+    def __init__(self) -> None:
+        self._inflight: dict[str, asyncio.Future[Any]] = {}
+        self._guard = asyncio.Lock()
+
+    async def do(self, key: str, compute: Callable[[], Awaitable[T]]) -> T:
+        async with self._guard:
+            future = self._inflight.get(key)
+            if future is None:
+                loop = asyncio.get_running_loop()
+                future = loop.create_future()
+                self._inflight[key] = future
+                leader = True
+            else:
+                leader = False
+
+        if not leader:
+            result: T = await future
+            return result
+
+        try:
+            result = await compute()
+        except BaseException as exc:
+            _release_async_waiters(future, exc)
+            raise
+        else:
+            if not future.done():
+                future.set_result(result)
+            return result
+        finally:
+            async with self._guard:
+                self._inflight.pop(key, None)
+
+
+class SyncSingleflight:
+    """Coalesce concurrent sync computations for the same cache key."""
+
+    def __init__(self) -> None:
+        self._inflight: dict[str, Future[Any]] = {}
+        self._guard = threading.Lock()
+
+    def do(self, key: str, compute: Callable[[], T]) -> T:
+        with self._guard:
+            future = self._inflight.get(key)
+            if future is None:
+                future = Future()
+                self._inflight[key] = future
+                leader = True
+            else:
+                leader = False
+
+        if not leader:
+            result: T = future.result()
+            return result
+
+        try:
+            result = compute()
+        except BaseException as exc:
+            _release_sync_waiters(future, exc)
+            raise
+        else:
+            future.set_result(result)
+            return result
+        finally:
+            with self._guard:
+                self._inflight.pop(key, None)

inhouse_cache-0.1.1/src/inhouse/store.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+import threading
+import time
+from collections import OrderedDict
+from typing import Any
+
+from inhouse.entry import CacheEntry
+
+
+class _CacheMiss:
+    """Sentinel returned when a key is absent or expired."""
+
+
+MISS = _CacheMiss()
+
+
+class MemoryStore:
+    """Thread-safe in-memory cache with TTL expiry and LRU eviction."""
+
+    def __init__(self, max_size: int = 1024, *, default_ttl: float | None = None) -> None:
+        if max_size < 1:
+            raise ValueError("max_size must be at least 1")
+        self._max_size = max_size
+        self._default_ttl = default_ttl
+        self._entries: OrderedDict[str, CacheEntry] = OrderedDict()
+        self._lock = threading.RLock()
+        if default_ttl is not None and default_ttl <= 0:
+            raise ValueError("default_ttl must be positive")
+
+    @property
+    def max_size(self) -> int:
+        return self._max_size
+
+    @property
+    def default_ttl(self) -> float | None:
+        with self._lock:
+            return self._default_ttl
+
+    @default_ttl.setter
+    def default_ttl(self, value: float | None) -> None:
+        if value is not None and value <= 0:
+            raise ValueError("default_ttl must be positive")
+        with self._lock:
+            self._default_ttl = value
+
+    @property
+    def size(self) -> int:
+        with self._lock:
+            return len(self._entries)
+
+    def get(self, key: str, *, default: Any = MISS) -> Any:
+        with self._lock:
+            entry = self._entries.get(key)
+            if entry is None:
+                return default
+            if time.monotonic() >= entry.expires_at:
+                del self._entries[key]
+                return default
+            self._entries.move_to_end(key)
+            return entry.value
+
+    def set(self, key: str, value: Any, ttl_seconds: float | None = None) -> None:
+        with self._lock:
+            ttl = ttl_seconds if ttl_seconds is not None else self._default_ttl
+            if ttl is None or ttl <= 0:
+                raise ValueError("ttl_seconds must be positive")
+            expires_at = time.monotonic() + ttl
+            self._entries[key] = CacheEntry(expires_at=expires_at, value=value)
+            self._entries.move_to_end(key)
+            while len(self._entries) > self._max_size:
+                self._entries.popitem(last=False)
+
+    def delete(self, key: str) -> bool:
+        with self._lock:
+            if key in self._entries:
+                del self._entries[key]
+                return True
+            return False
+
+    def clear(self) -> None:
+        with self._lock:
+            self._entries.clear()
+
+    def purge_expired(self) -> int:
+        """Remove all expired entries. Returns count of removed keys."""
+        now = time.monotonic()
+        removed = 0
+        with self._lock:
+            expired_keys = [
+                key for key, entry in self._entries.items() if now >= entry.expires_at
+            ]
+            for key in expired_keys:
+                del self._entries[key]
+                removed += 1
+        return removed
+
+    def keys(self) -> list[str]:
+        with self._lock:
+            return list(self._entries.keys())

inhouse_cache-0.1.1/src/inhouse/sweeper.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+import asyncio
+
+from inhouse.store import MemoryStore
+
+
+class ExpirySweeper:
+    """Background task that periodically purges expired cache entries."""
+
+    def __init__(self, store: MemoryStore, *, interval_seconds: float = 30.0) -> None:
+        if interval_seconds <= 0:
+            raise ValueError("interval_seconds must be positive")
+        self._store = store
+        self._interval_seconds = interval_seconds
+        self._task: asyncio.Task[None] | None = None
+
+    async def run(self) -> None:
+        while True:
+            await asyncio.sleep(self._interval_seconds)
+            self._store.purge_expired()
+
+    def start(self) -> asyncio.Task[None]:
+        self._task = asyncio.create_task(self.run(), name="inhouse-expiry-sweeper")
+        return self._task
+
+    async def stop(self, task: asyncio.Task[None] | None = None) -> None:
+        target = task or self._task
+        if target is None:
+            return
+        target.cancel()
+        try:
+            await target
+        except asyncio.CancelledError:
+            pass
+        if task is None:
+            self._task = None