ttl-cache-decorator 0.1.2__tar.gz

ttl_cache_decorator-0.1.2/.gitattributes

@@ -0,0 +1,2 @@
+* text=auto
+*.sh text eol=lf

ttl_cache_decorator-0.1.2/.github/workflows/docs.yml

@@ -0,0 +1,38 @@
+name: Documentation
+on:
+  push:
+    branches:
+      - main
+    tags:
+      - "v*"
+permissions:
+  contents: write
+concurrency:
+  group: docs-publish
+  cancel-in-progress: false
+jobs:
+  publish-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+      - name: Install dependencies
+        run: |
+          uv sync --group docs --no-install-project
+          uv pip install git+https://github.com/squidfunk/mike.git
+      - name: Configure git
+        run: |
+          git config user.name "${{ github.actor }}"
+          git config user.email "${{ github.actor_id }}+${{ github.actor }}@users.noreply.github.com"
+      - name: Publish dev docs
+        if: github.ref == 'refs/heads/main'
+        run: uv run mike deploy --push dev
+      - name: Publish release docs
+        if: startsWith(github.ref, 'refs/tags/v')
+        run: |
+          VERSION="${GITHUB_REF_NAME#v}"
+          uv run mike deploy --push --update-aliases "$VERSION" latest

ttl_cache_decorator-0.1.2/.github/workflows/publish.yml

@@ -0,0 +1,33 @@
+name: Publish
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_run:
+    workflows:
+      - Release
+    types:
+      - completed
+permissions:
+  id-token: write
+jobs:
+  publish:
+    if: >-
+      github.event_name == 'push' ||
+      github.event.workflow_run.conclusion == 'success'
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/ttl-cache-decorator
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          ref: ${{ github.event_name == 'workflow_run' && github.event.workflow_run.head_sha || github.ref }}
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+      - name: Build distributions
+        run: uv build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

ttl_cache_decorator-0.1.2/.github/workflows/release.yml

@@ -0,0 +1,43 @@
+name: Release
+on:
+  workflow_dispatch:
+    inputs:
+      bump:
+        description: Version bump
+        type: choice
+        options:
+          - patch
+          - minor
+          - major
+        default: patch
+permissions:
+  contents: write
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      # A personal access token is required so the pushed tag triggers the
+      # test/docs/publish workflows — pushes made with the default
+      # GITHUB_TOKEN never start new workflow runs.
+      - uses: actions/checkout@v7
+        with:
+          token: ${{ secrets.RELEASE_PAT || github.token }}
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v6
+      - uses: taiki-e/install-action@v2
+        with:
+          tool: git-cliff
+      - name: Bump version
+        run: uv version --bump ${{ inputs.bump }}
+      - name: Generate changelog
+        run: git-cliff --config cliff.toml --tag "v$(uv version --short)" --output CHANGELOG.md
+      - name: Commit, tag and push
+        run: |
+          VERSION=$(uv version --short)
+          git config user.name "${{ github.actor }}"
+          git config user.email "${{ github.actor_id }}+${{ github.actor }}@users.noreply.github.com"
+          git add pyproject.toml uv.lock CHANGELOG.md
+          git commit -m "chore: release v$VERSION"
+          git tag -a "v$VERSION" -m "Release v$VERSION"
+          git push origin main
+          git push origin "v$VERSION"

ttl_cache_decorator-0.1.2/.github/workflows/test.yml

@@ -0,0 +1,44 @@
+name: Tests
+on:
+  push:
+    branches:
+      - main
+    tags:
+      - "v*"
+  pull_request:
+  workflow_run:
+    workflows:
+      - Release
+    types:
+      - completed
+permissions:
+  contents: read
+concurrency:
+  group: tests-${{ github.ref }}
+  cancel-in-progress: true
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os:
+          - ubuntu-latest
+          - windows-latest
+          - macos-latest
+        python-version:
+          - "3.12"
+          - "3.13"
+          - "3.14"
+          - "3.15"
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: uv sync --group test --python ${{ matrix.python-version }}
+      - name: Run tests
+        run: uv run pytest

ttl_cache_decorator-0.1.2/.gitignore

@@ -0,0 +1,40 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+.env
+*.env.*
+!.env.example
+
+# Streamlit secrets
+**/.streamlit/secrets.toml
+
+# Database
+.sqlite/*.db
+
+# Big json files
+full_describe.json
+
+# Gitkeep
+
+# MkDocs
+site/
+.cache/
+
+.vscode/**
+!.vscode/extensions.json
+!.vscode/settings.json
+!.vscode/launch.json
+!project.code-snippets
+.coverage
+
+tests/temp/**
+*.db
+
+!.gitkeep

ttl_cache_decorator-0.1.2/.python-version

@@ -0,0 +1 @@
+3.12

ttl_cache_decorator-0.1.2/.vscode/extensions.json

@@ -0,0 +1,15 @@
+{
+  "recommendations": [
+    "streetsidesoftware.code-spell-checker",
+    "streetsidesoftware.code-spell-checker-british-english",
+    "esbenp.prettier-vscode",
+    "dbaeumer.vscode-eslint",
+    "charliermarsh.ruff",
+    "ms-python.python",
+    "ms-python.vscode-pylance",
+    "ms-python.debugpy",
+    "njpwerner.autodocstring",
+    "usernamehw.errorlens"
+  ],
+  "unwantedRecommendations": ["ms-python.flake8"]
+}

ttl_cache_decorator-0.1.2/.vscode/launch.json

@@ -0,0 +1,14 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Python: Debug Tests",
+      "type": "debugpy",
+      "request": "launch",
+      "program": "${file}",
+      "purpose": ["debug-test"],
+      "console": "integratedTerminal",
+      "justMyCode": true
+    }
+  ]
+}

ttl_cache_decorator-0.1.2/.vscode/settings.json

@@ -0,0 +1,49 @@
+{
+  // Git settings
+  "git.autofetch": true,
+  // Ruff settings - config lives in pyproject.toml
+  "ruff.configuration": "${workspaceFolder}/pyproject.toml",
+  // Mypy settings - auto-discovers mypy.ini in workspace root
+  "python.analysis.typeCheckingMode": "standard",
+  // Python testing settings
+  "python.testing.pytestEnabled": true,
+  "python.testing.unittestEnabled": false,
+  "python.testing.pytestArgs": [
+    "tests",
+    "--cov",
+    "--cov-config=pyproject.toml"
+  ],
+  "[python]": {
+    "editor.defaultFormatter": "charliermarsh.ruff",
+    "editor.formatOnSave": true,
+    "editor.codeActionsOnSave": {
+      "source.organizeImports.ruff": "explicit",
+      "source.fixAll.ruff": "explicit"
+    }
+  },
+  // Code formatting
+  "editor.formatOnSave": true,
+  // Editor settings
+  "editor.rulers": [120],
+  "files.insertFinalNewline": true,
+  "files.trimTrailingWhitespace": true,
+  "files.eol": "\n",
+  // Codespell settings - explicit workspace paths
+  "cSpell.enabled": true,
+  "cSpell.language": "en-GB",
+  "cSpell.customDictionaries": {
+    "project-words": {
+      "name": "project-words",
+      "path": "${workspaceFolder}/.project-words.txt",
+      "addWords": true,
+      "scope": "workspace"
+    }
+  },
+  // Error Lens settings
+  "errorLens.enabled": true,
+  "errorLens.enabledDiagnosticLevels": ["error", "warning", "info", "hint"],
+  "errorLens.onSave": true,
+  "errorLens.onSaveTimeout": 1000,
+  "errorLens.delay": 500,
+  "errorLens.followCursor": "allLines"
+}

ttl_cache_decorator-0.1.2/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+### Miscellaneous
+
+- Initial commit ([c96fc0e](https://github.com/Johandielangman/ttl-cache-decorator/commit/c96fc0efa65c289c731b6b8d04358cbd9943eeeb))
+- Add the wheel ([20e5b76](https://github.com/Johandielangman/ttl-cache-decorator/commit/20e5b761ea79e1553682a770e2cbfc51ace33ca0))
+- Add docs dependencies ([23eacf4](https://github.com/Johandielangman/ttl-cache-decorator/commit/23eacf4ebc5f9bcd78e7aac6a727ba54f041bda3))
+- Use a cliff uses ([3e1c78a](https://github.com/Johandielangman/ttl-cache-decorator/commit/3e1c78a6dd6a14053e3f0b0285cc1383fc253806))
+- Release v0.1.1 ([91408a2](https://github.com/Johandielangman/ttl-cache-decorator/commit/91408a2770190351a4996c1f996a415e42d3f463))
+- Better tagging ([4b45da8](https://github.com/Johandielangman/ttl-cache-decorator/commit/4b45da8adeb4545a7a3bd04f600f615198a4f7d9))
+<!-- generated by git-cliff -->

ttl_cache_decorator-0.1.2/LICENSE.txt

@@ -0,0 +1,18 @@
+MIT License
+
+Copyright (c) 2026-present Johandielangman <jghanekom2@gmail.com>
+
+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.

ttl_cache_decorator-0.1.2/PKG-INFO

@@ -0,0 +1,58 @@
+Metadata-Version: 2.5
+Name: ttl-cache-decorator
+Version: 0.1.2
+Summary: LRU Cache Decorator with a Time to Live
+Project-URL: Changelog, https://github.com/Johandielangman/ttl-cache-decorator/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://johandielangman.github.io/ttl-cache-decorator/
+Project-URL: Issues, https://github.com/Johandielangman/ttl-cache-decorator/issues
+Project-URL: Source, https://github.com/Johandielangman/ttl-cache-decorator
+Author-email: Johandielangman <johan@datatreehouse.org>
+License-Expression: MIT
+License-File: LICENSE.txt
+Classifier: Development Status :: 4 - Beta
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# TTL Cache
+
+[![PyPI - Version](https://img.shields.io/pypi/v/ttl-cache-decorator.svg)](https://pypi.org/project/ttl-cache-decorator)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/ttl-cache-decorator.svg)](https://pypi.org/project/ttl-cache-decorator)
+
+An LRU cache decorator with a time to live — like `functools.lru_cache`, but entries expire after a configurable number of seconds.
+
+## Installation
+
+```console
+pip install ttl-cache-decorator
+```
+
+## Usage
+
+```python
+from ttl_cache import ttl_lru_cache
+
+
+@ttl_lru_cache(ttl=30)
+def fetch_user(user_id: int) -> dict:
+    return {"id": user_id, "name": "Ada"}
+
+
+fetch_user(1)  # Calls the function
+fetch_user(1)  # Cache hit
+# ... 30 seconds later ...
+fetch_user(1)  # Expired — calls the function again
+```
+
+## License
+
+`ttl-cache-decorator` is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.

ttl_cache_decorator-0.1.2/README.md

@@ -0,0 +1,33 @@
+# TTL Cache
+
+[![PyPI - Version](https://img.shields.io/pypi/v/ttl-cache-decorator.svg)](https://pypi.org/project/ttl-cache-decorator)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/ttl-cache-decorator.svg)](https://pypi.org/project/ttl-cache-decorator)
+
+An LRU cache decorator with a time to live — like `functools.lru_cache`, but entries expire after a configurable number of seconds.
+
+## Installation
+
+```console
+pip install ttl-cache-decorator
+```
+
+## Usage
+
+```python
+from ttl_cache import ttl_lru_cache
+
+
+@ttl_lru_cache(ttl=30)
+def fetch_user(user_id: int) -> dict:
+    return {"id": user_id, "name": "Ada"}
+
+
+fetch_user(1)  # Calls the function
+fetch_user(1)  # Cache hit
+# ... 30 seconds later ...
+fetch_user(1)  # Expired — calls the function again
+```
+
+## License
+
+`ttl-cache-decorator` is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.

ttl_cache_decorator-0.1.2/cliff.toml

@@ -0,0 +1,37 @@
+# git-cliff ~ changelog configuration
+# https://git-cliff.org/docs/configuration
+
+[changelog]
+header = """
+# Changelog
+
+All notable changes to this project are documented in this file.
+"""
+body = """
+{% for group, commits in commits | group_by(attribute="group") %}
+    ### {{ group | upper_first }}
+    {% for commit in commits %}
+        - {{ commit.message | upper_first }} ([{{ commit.id | truncate(length=7, end="") }}](https://github.com/Johandielangman/ttl-cache-decorator/commit/{{ commit.id }}))\
+    {% endfor %}
+{% endfor %}
+"""
+footer = """
+<!-- generated by git-cliff -->
+"""
+trim = true
+
+[git]
+conventional_commits = true
+filter_unconventional = true
+commit_parsers = [
+    { message = "^feat", group = "Features" },
+    { message = "^fix", group = "Bug Fixes" },
+    { message = "^perf", group = "Performance" },
+    { message = "^refactor", group = "Refactoring" },
+    { message = "^docs", group = "Documentation" },
+    { message = "^test", group = "Testing" },
+    { message = "^chore\\(release\\)", skip = true },
+    { message = "^chore", group = "Miscellaneous" },
+]
+filter_commits = false
+tag_pattern = "^v[0-9]+\\.[0-9]+\\.[0-9]+$"

ttl_cache_decorator-0.1.2/docs/index.md

@@ -0,0 +1,138 @@
+---
+icon: lucide/timer
+---
+
+# TTL Cache
+
+An LRU cache decorator with a ==time to live==. `ttl_lru_cache` works exactly
+like [`functools.lru_cache`][lru_cache], except entries automatically expire
+after a configurable number of seconds.
+
+  [lru_cache]: https://docs.python.org/3/library/functools.html#functools.lru_cache
+
+## Installation
+
+=== "pip"
+
+    ``` console
+    pip install ttl-cache-decorator
+    ```
+
+=== "uv"
+
+    ``` console
+    uv add ttl-cache-decorator
+    ```
+
+Requires **Python 3.12+**.
+
+## Quickstart
+
+``` python title="Basic usage" hl_lines="1 4"
+from ttl_cache import ttl_lru_cache
+
+
+@ttl_lru_cache(ttl=30)  # (1)!
+def fetch_user(user_id: int) -> dict:
+    print("Fetching from the network...")
+    return {"id": user_id, "name": "Ada"}
+
+
+fetch_user(1)  # Prints "Fetching from the network..."
+fetch_user(1)  # Cache hit, nothing printed
+# ... 30 seconds later ...
+fetch_user(1)  # Expired — fetches again
+```
+
+1.  Cache results for 30 seconds. While the TTL window is open, repeat calls
+    with the same arguments are served from the cache.
+
+## How it works
+
+Under the hood it still uses `lru_cache`, but the cached call receives an extra
+positional-only *time bucket* argument derived from a monotonic clock:
+
+``` python title="The time bucket"
+time_bucket = int((time.monotonic() + offset) // ttl)
+```
+
+An entry stays "alive" while the bucket value is unchanged and expires when the
+bucket rolls over:
+
+``` mermaid
+graph LR
+  A[Call] --> B{Bucket changed?}
+  B -->|No| C[Serve cached value]
+  B -->|Yes| D[Recompute and cache]
+  C --> E[Return]
+  D --> E
+```
+
+!!! note
+
+    The bucket boundary is shared per TTL window, so an entry lives for *at
+    most* `ttl` seconds and *at least* the remainder of the current bucket.
+
+## API reference
+
+### `ttl_lru_cache`
+
+``` python
+ttl_lru_cache(
+    ttl: float = 60,
+    jitter: float = 0,
+    maxsize: int | None = 128,
+    typed: bool = False,
+)
+```
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `ttl` | `float` | `60` | Time to live in seconds. Must be positive. |
+| `jitter` | `float` | `0` | Max random offset (seconds) applied to bucket boundaries. Must be non-negative. |
+| `maxsize` | `int \| None` | `128` | Max size of the cache, or `None` for unbounded. |
+| `typed` | `bool` | `False` | Whether argument types are part of the cache key. |
+
+Returns a decorator whose wrapped function keeps its signature and exposes the
+usual `lru_cache` helpers: `cache_info()` and `cache_clear()`.
+
+!!! warning "Validation"
+
+    A `ValueError` is raised at decoration time if `ttl` is not positive or
+    `jitter` is negative.
+
+### Jitter
+
+`jitter` draws a random offset once per decorated function from
+`random.uniform(0, jitter)`, so different functions (or processes) expire at
+different moments instead of all at once. Use it to avoid a *thundering herd*
+when many cached values would otherwise expire simultaneously:
+
+``` python title="Adding jitter" hl_lines="1"
+@ttl_lru_cache(ttl=60, jitter=10)
+def fetch_metrics(service: str) -> dict:
+    ...
+```
+
+### Cache helpers
+
+``` python title="Inspecting and clearing the cache"
+fetch_user.cache_info()   # CacheInfo(hits=..., misses=..., maxsize=128, currsize=...)
+fetch_user.cache_clear()  # Drop all cached entries
+```
+
+??? info "Typing"
+
+    The decorator is fully generic via `ParamSpec` and returns a
+    `TTLCachedFunction` protocol, so type checkers preserve the wrapped
+    function's signature — including keyword arguments.
+
+    ``` python
+    from ttl_cache import TTLCachedFunction
+
+    cached_fetch: TTLCachedFunction[[str], dict] = ttl_lru_cache(ttl=5)(fetch_user)
+    ```
+
+## License
+
+`ttl-cache-decorator` is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.