django-stash 0.1.0__tar.gz

django_stash-0.1.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Andy Babic
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

django_stash-0.1.0/PKG-INFO

@@ -0,0 +1,110 @@
+Metadata-Version: 2.5
+Name: django-stash
+Version: 0.1.0
+Summary: Scoped ambient memoization for Django — stash values for the duration of a request or task, available anywhere in the stack.
+Keywords: Django,cache,memoize,request,asgiref,performance
+Author-email: Andy Babic <andyjbabic@gmail.com>
+Maintainer-email: Andy Babic <andyjbabic@gmail.com>
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 4.2
+Classifier: Framework :: Django :: 5.0
+Classifier: Framework :: Django :: 5.1
+Classifier: Framework :: Django :: 5.2
+License-File: LICENSE
+Requires-Dist: Django>=4.2
+Requires-Dist: asgiref>=3.7
+Requires-Dist: ruff>=0.1.1,<1.0 ; extra == "development"
+Requires-Dist: coverage>=7.0,<8.0 ; extra == "testing"
+Project-URL: Changelog, https://github.com/ababic/django-stash/blob/main/CHANGELOG.md
+Project-URL: Source, https://github.com/ababic/django-stash
+Provides-Extra: development
+Provides-Extra: testing
+Import-Name: stash
+
+# django-stash
+
+[![License: BSD-3-Clause](https://img.shields.io/badge/License-BSD--3--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+
+Scoped ambient memoization for Django.
+
+Stash values for the duration of a **request** (or any other explicit scope), and read them again from anywhere in the call stack — without threading a `request` through every helper.
+
+This is **not** a cache backend. It does not replace Redis/Memcached/database cache. It is an L1 memo pad that only exists while a scope is open.
+
+## Install
+
+```bash
+pip install django-stash
+```
+
+```python
+MIDDLEWARE = [
+    "stash.middleware.StashMiddleware",
+    # ...
+]
+```
+
+No `INSTALLED_APPS` entry required.
+
+## Usage
+
+```python
+import stash
+
+def expensive_site_paths():
+    return stash.get_or_set(
+        "wagtail.site_root_paths",
+        loader=compute_site_root_paths,
+    )
+
+@stash.memoize(key="taxonomy.colours")
+def get_colour_choices():
+    return list(Colour.objects.values_list("id", "name"))
+```
+
+Outside a scope (management commands, Celery, shell), `get_or_set` / `memoize` just call the loader every time. Nothing sticks on the worker.
+
+### Manual scopes
+
+```python
+with stash.stash_scope():
+    ...
+```
+
+Useful for tests, management commands, or task bodies that want the same behaviour.
+
+### Clearing
+
+```python
+stash.clear("wagtail.site_root_paths")  # one key
+stash.clear()                           # everything in this scope
+```
+
+## Rules of thumb
+
+1. **Scope owns lifetime** — middleware / `stash_scope()` enable at enter and disable in `finally`.
+2. **No scope ⇒ no stash** — avoids sticky process caches on Gunicorn sync workers.
+3. **Prefer immutable-ish values** — stash stores/returns shallow copies; don't stash live model graphs you plan to mutate in place.
+4. **Shared cache is separate** — if you need cross-process invalidation, keep Django's cache as L2 and use stash as L1 in front of it.
+
+## Development
+
+```bash
+cd django-stash
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[testing,development]"
+python testmanage.py test
+```
+

django_stash-0.1.0/README.md

@@ -0,0 +1,75 @@
+# django-stash
+
+[![License: BSD-3-Clause](https://img.shields.io/badge/License-BSD--3--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+
+Scoped ambient memoization for Django.
+
+Stash values for the duration of a **request** (or any other explicit scope), and read them again from anywhere in the call stack — without threading a `request` through every helper.
+
+This is **not** a cache backend. It does not replace Redis/Memcached/database cache. It is an L1 memo pad that only exists while a scope is open.
+
+## Install
+
+```bash
+pip install django-stash
+```
+
+```python
+MIDDLEWARE = [
+    "stash.middleware.StashMiddleware",
+    # ...
+]
+```
+
+No `INSTALLED_APPS` entry required.
+
+## Usage
+
+```python
+import stash
+
+def expensive_site_paths():
+    return stash.get_or_set(
+        "wagtail.site_root_paths",
+        loader=compute_site_root_paths,
+    )
+
+@stash.memoize(key="taxonomy.colours")
+def get_colour_choices():
+    return list(Colour.objects.values_list("id", "name"))
+```
+
+Outside a scope (management commands, Celery, shell), `get_or_set` / `memoize` just call the loader every time. Nothing sticks on the worker.
+
+### Manual scopes
+
+```python
+with stash.stash_scope():
+    ...
+```
+
+Useful for tests, management commands, or task bodies that want the same behaviour.
+
+### Clearing
+
+```python
+stash.clear("wagtail.site_root_paths")  # one key
+stash.clear()                           # everything in this scope
+```
+
+## Rules of thumb
+
+1. **Scope owns lifetime** — middleware / `stash_scope()` enable at enter and disable in `finally`.
+2. **No scope ⇒ no stash** — avoids sticky process caches on Gunicorn sync workers.
+3. **Prefer immutable-ish values** — stash stores/returns shallow copies; don't stash live model graphs you plan to mutate in place.
+4. **Shared cache is separate** — if you need cross-process invalidation, keep Django's cache as L2 and use stash as L1 in front of it.
+
+## Development
+
+```bash
+cd django-stash
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[testing,development]"
+python testmanage.py test
+```

django_stash-0.1.0/pyproject.toml

@@ -0,0 +1,67 @@
+[project]
+name = "django-stash"
+description = "Scoped ambient memoization for Django — stash values for the duration of a request or task, available anywhere in the stack."
+authors = [{name = "Andy Babic", email = "andyjbabic@gmail.com"}]
+maintainers = [
+    {name = "Andy Babic", email = "andyjbabic@gmail.com"},
+]
+readme = "README.md"
+license = {file = "LICENSE"}
+keywords = ["Django", "cache", "memoize", "request", "asgiref", "performance"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: BSD License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Framework :: Django",
+    "Framework :: Django :: 4.2",
+    "Framework :: Django :: 5.0",
+    "Framework :: Django :: 5.1",
+    "Framework :: Django :: 5.2",
+]
+
+dynamic = ["version"]
+requires-python = ">=3.11"
+dependencies = [
+    "Django>=4.2",
+    "asgiref>=3.7",
+]
+
+[project.optional-dependencies]
+testing = [
+    "coverage>=7.0,<8.0",
+]
+development = [
+    "ruff>=0.1.1,<1.0",
+]
+
+[project.urls]
+Source = "https://github.com/ababic/django-stash"
+Changelog = "https://github.com/ababic/django-stash/blob/main/CHANGELOG.md"
+
+[build-system]
+requires = ["flit_core >=3.2,<4"]
+build-backend = "flit_core.buildapi"
+
+[tool.flit.module]
+name = "stash"
+
+[tool.flit.sdist]
+exclude = [
+    ".*",
+    "*.db",
+    "*.json",
+    "*.ini",
+    "*.sqlite3",
+    "*.yaml",
+    "tests",
+    "CHANGELOG.md",
+    "ruff.toml",
+    "manage.py",
+    "testmanage.py",
+]

django_stash-0.1.0/src/stash/__init__.py

@@ -0,0 +1,28 @@
+from stash.__version__ import __version__
+from stash.api import (
+    clear,
+    disable,
+    enable,
+    enabled,
+    get,
+    get_or_set,
+    memoize,
+    set,
+    stash_scope,
+)
+from stash.middleware import StashMiddleware
+
+
+__all__ = [
+    "StashMiddleware",
+    "__version__",
+    "clear",
+    "disable",
+    "enable",
+    "enabled",
+    "get",
+    "get_or_set",
+    "memoize",
+    "set",
+    "stash_scope",
+]

django_stash-0.1.0/src/stash/__version__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

django_stash-0.1.0/src/stash/api.py

@@ -0,0 +1,157 @@
+from __future__ import annotations
+
+import copy
+
+from collections.abc import Callable, Iterator
+from contextlib import contextmanager
+from functools import wraps
+from typing import Any, TypeVar, overload
+
+from asgiref.local import Local
+
+
+T = TypeVar("T")
+
+_local = Local()
+_MISSING = object()
+
+
+def enabled() -> bool:
+    """Return whether a stash scope is active for this execution context."""
+    return bool(getattr(_local, "enabled", False))
+
+
+def enable() -> None:
+    """
+    Open a stash scope for this execution context.
+
+    Prefer ``StashMiddleware`` or ``stash_scope()`` so lifetime is bounded.
+    """
+    _local.enabled = True
+    _local.values = {}
+
+
+def disable() -> None:
+    """Close the stash scope and drop all stored values for this context."""
+    _local.values = {}
+    _local.enabled = False
+
+
+def _values() -> dict[str, Any]:
+    values = getattr(_local, "values", None)
+    if values is None:
+        values = {}
+        _local.values = values
+    return values
+
+
+def _store(value: Any) -> Any:
+    return copy.copy(value)
+
+
+def _retrieve(value: Any) -> Any:
+    return copy.copy(value)
+
+
+def get(key: str, default: Any = None) -> Any:
+    """Return a stashed value, or ``default`` on miss / when no scope is active."""
+    if not enabled():
+        return default
+    value = _values().get(key, _MISSING)
+    if value is _MISSING:
+        return default
+    return _retrieve(value)
+
+
+def set(key: str, value: Any) -> None:
+    """
+    Store ``value`` under ``key`` when a scope is active.
+
+    No-op when no scope is active (avoids sticky process-level state).
+    """
+    if not enabled():
+        return
+    _values()[key] = _store(value)
+
+
+def clear(key: str | None = None) -> None:
+    """Clear one key, or the entire stash when ``key`` is omitted."""
+    if not enabled():
+        return
+    if key is None:
+        _local.values = {}
+        return
+    _values().pop(key, None)
+
+
+def get_or_set(key: str, loader: Callable[[], T]) -> T:
+    """
+    Return a stashed value, or call ``loader``, stash the result, and return it.
+
+    When no scope is active, always calls ``loader()`` and does not store.
+    """
+    if not enabled():
+        return loader()
+
+    values = _values()
+    value = values.get(key, _MISSING)
+    if value is not _MISSING:
+        return _retrieve(value)
+
+    loaded = loader()
+    values[key] = _store(loaded)
+    return _retrieve(loaded)
+
+
+def _memo_key(func: Callable[..., Any], args: tuple[Any, ...], kwargs: dict[str, Any]) -> str:
+    qualname = f"{func.__module__}.{func.__qualname__}"
+    if not args and not kwargs:
+        return qualname
+    return f"{qualname}:{args!r}:{sorted(kwargs.items())!r}"
+
+
+@overload
+def memoize(func: Callable[..., T]) -> Callable[..., T]: ...
+
+
+@overload
+def memoize(
+    *,
+    key: str | None = None,
+) -> Callable[[Callable[..., T]], Callable[..., T]]: ...
+
+
+def memoize(
+    func: Callable[..., T] | None = None,
+    *,
+    key: str | None = None,
+) -> Callable[..., T] | Callable[[Callable[..., T]], Callable[..., T]]:
+    """
+    Memoize a function into the active stash scope.
+
+    ``@memoize`` derives a key from the function and call arguments.
+    ``@memoize(key="...")`` uses a fixed key (argument values ignored).
+    Outside a scope, the function always runs normally.
+    """
+
+    def decorator(fn: Callable[..., T]) -> Callable[..., T]:
+        @wraps(fn)
+        def wrapper(*args: Any, **kwargs: Any) -> T:
+            cache_key = key if key is not None else _memo_key(fn, args, kwargs)
+            return get_or_set(cache_key, lambda: fn(*args, **kwargs))
+
+        return wrapper
+
+    if func is not None:
+        return decorator(func)
+    return decorator
+
+
+@contextmanager
+def stash_scope() -> Iterator[None]:
+    """Context manager that opens a stash scope for a block of work."""
+    enable()
+    try:
+        yield
+    finally:
+        disable()

django_stash-0.1.0/src/stash/middleware.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from django.http import HttpRequest, HttpResponse
+
+from stash.api import disable, enable
+
+
+class StashMiddleware:
+    """
+    Open a stash scope for the duration of one HTTP request.
+
+    Outside this middleware (management commands, Celery tasks, etc.) stash
+    reads miss and writes no-op, so values cannot leak across units of work on
+    a reused worker thread.
+    """
+
+    def __init__(self, get_response: Callable[[HttpRequest], HttpResponse]) -> None:
+        self.get_response = get_response
+
+    def __call__(self, request: HttpRequest) -> HttpResponse:
+        enable()
+        try:
+            return self.get_response(request)
+        finally:
+            disable()