pico-caching 0.1.0__tar.gz

pico_caching-0.1.0/.coveragerc

@@ -0,0 +1,18 @@
+[run]
+branch = True
+source =
+    pico_caching
+omit =
+    */_version.py
+
+[paths]
+pico_caching =
+    src/pico_caching
+    .tox/*/lib/*/site-packages/pico_caching
+    .tox/*/site-packages/pico_caching
+    */site-packages/pico_caching
+
+[report]
+show_missing = True
+omit =
+    */_version.py

pico_caching-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,24 @@
+name: Bug Report
+description: Report a bug
+labels: [bug]
+body:
+  - type: textarea
+    id: description
+    attributes: { label: Description }
+    validations: { required: true }
+  - type: textarea
+    id: steps
+    attributes: { label: Steps to Reproduce, render: python }
+    validations: { required: true }
+  - type: textarea
+    id: expected
+    attributes: { label: Expected Behavior }
+    validations: { required: true }
+  - type: input
+    id: version
+    attributes: { label: Package Version }
+    validations: { required: true }
+  - type: input
+    id: python
+    attributes: { label: Python Version }
+    validations: { required: true }

pico_caching-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,15 @@
+name: Feature Request
+description: Suggest an improvement
+labels: [enhancement]
+body:
+  - type: textarea
+    id: problem
+    attributes: { label: Problem }
+    validations: { required: true }
+  - type: textarea
+    id: solution
+    attributes: { label: Proposed Solution }
+    validations: { required: true }
+  - type: textarea
+    id: alternatives
+    attributes: { label: Alternatives Considered }

pico_caching-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,13 @@
+## Summary
+
+## Changes
+
+-
+
+## Checklist
+
+- [ ] Tests pass (`pytest tests/ -v`)
+- [ ] Linting passes (`ruff check src/ tests/`)
+- [ ] CHANGELOG.md updated (if user-facing)
+- [ ] No new runtime dependencies
+- [ ] Single-line commit messages

pico_caching-0.1.0/.github/dependabot.yml

@@ -0,0 +1,10 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"

pico_caching-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,69 @@
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - run: pip install ruff
+      - run: ruff check src/ tests/
+      - run: ruff format --check src/ tests/
+
+  tests:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install tox
+      - name: Run tests with coverage
+        env:
+          SETUPTOOLS_SCM_PRETEND_VERSION: "0.1.0"
+        run: |
+          tox -e cov
+          mv .coverage .coverage.${{ matrix.python-version }}
+      - uses: actions/upload-artifact@v4
+        with:
+          name: coverage-${{ matrix.python-version }}
+          path: .coverage.${{ matrix.python-version }}
+          include-hidden-files: true
+          if-no-files-found: error
+
+  coverage:
+    needs: tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - uses: actions/download-artifact@v4
+        with:
+          path: coverage-reports
+      - name: Combine and upload
+        run: |
+          pip install coverage
+          files=$(find coverage-reports -type f -name ".coverage.*")
+          if [ -z "$files" ]; then echo "No coverage files"; exit 1; fi
+          coverage combine $files
+          coverage xml
+      - uses: codecov/codecov-action@v4
+        continue-on-error: true
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: coverage.xml
+          fail_ci_if_error: false

pico_caching-0.1.0/.github/workflows/codeql.yml

@@ -0,0 +1,21 @@
+name: CodeQL
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  schedule:
+    - cron: "0 6 * * 1"
+
+permissions:
+  security-events: write
+  contents: read
+
+jobs:
+  analyze:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: github/codeql-action/init@v3
+        with: { languages: python }
+      - uses: github/codeql-action/analyze@v3

pico_caching-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,48 @@
+name: Docs
+on:
+  push:
+    branches: [main]
+    paths: [docs/**, mkdocs.yml]
+  pull_request:
+    branches: [main]
+    paths: [docs/**, mkdocs.yml]
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  validate:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with: { fetch-depth: 0 }
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      - run: pip install -r docs/requirements.txt
+      - run: mkdocs build --strict
+
+  deploy:
+    if: github.event_name != 'pull_request'
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/checkout@v4
+        with: { fetch-depth: 0 }
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      - run: pip install -r docs/requirements.txt
+      - run: mkdocs build --strict --verbose
+      - uses: actions/upload-pages-artifact@v3
+        with: { path: site }
+      - id: deployment
+        uses: actions/deploy-pages@v4

pico_caching-0.1.0/.github/workflows/publish-to-pypi.yml

@@ -0,0 +1,24 @@
+name: Publish to PyPI
+on:
+  release:
+    types: [published]
+
+permissions:
+  id-token: write
+  contents: read
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with: { fetch-depth: 0 }
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.x" }
+      - run: pip install build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: true
+          verify-metadata: true
+          attestations: true

pico_caching-0.1.0/AGENTS.md

@@ -0,0 +1,36 @@
+# pico-caching
+
+Declarative caching (@cacheable) for pico-ioc components with pluggable backends.
+
+## Commands
+
+```bash
+pip install -e ".[dev]"
+pytest tests/ -v
+pytest --cov=pico_caching --cov-report=term-missing tests/
+mkdocs serve -f mkdocs.yml
+```
+
+## Project Structure
+
+```
+src/pico_caching/
+  __init__.py     # Public API
+  decorators.py   # @cacheable (policy on fn + intercepted_by)
+  interceptor.py  # CacheInterceptor (get-or-compute)
+  backend.py      # CacheBackend protocol + InMemoryCacheBackend (LRU + TTL)
+  config.py       # CacheSettings (prefix "cache")
+```
+
+## Key Concepts
+
+- Default key: module.Class.method(args;kwargs) repr; override with `key=callable`.
+- TTL: per-decorator `ttl_seconds` overrides `cache.default_ttl_seconds`.
+- Backend selection: first non-builtin `CacheBackend` component wins, else built-in LRU.
+- Async caches the awaited result; `time.monotonic` for expiry; one lock, OrderedDict LRU.
+- `cache.enabled: false` -> pass-through.
+
+## Boundaries
+
+- Do not modify `_version.py`
+- Keep `backend.py` free of asyncio (backends are sync by contract)

pico_caching-0.1.0/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-07-03
+
+### Added
+
+- `@cacheable` decorator (sync + async; the awaited result is cached).
+- `CacheBackend` protocol; user backends replace the built-in automatically.
+- `InMemoryCacheBackend`: thread-safe LRU with per-entry TTL.
+- `CacheSettings` (prefix `cache`): `enabled`, `default_ttl_seconds`, `max_entries`.
+- Auto-discovery through the `pico_boot.modules` entry point; zero-config.
+
+[Unreleased]: https://github.com/dperezcabrera/pico-caching/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/dperezcabrera/pico-caching/releases/tag/v0.1.0

pico_caching-0.1.0/CLAUDE.md

@@ -0,0 +1,14 @@
+Read and follow ./AGENTS.md for project conventions.
+
+## Pico Ecosystem Context
+
+pico-caching provides `@cacheable` via pico-ioc `MethodInterceptor` with a pluggable `CacheBackend` protocol (built-in thread-safe in-memory LRU + TTL). Same decorator idiom as pico-pydantic. Auto-discovered via `pico_boot.modules` entry point. Config prefix `cache` (zero-config).
+
+## Key Reminders
+
+- pico-ioc dependency: `>= 2.2.0`
+- **NEVER change `version_scheme`** in pyproject.toml. It MUST remain `"post-release"`.
+- requires-python >= 3.11
+- Commit messages: one line only
+- Async methods cache the awaited result, never the coroutine
+- A user `CacheBackend` @component replaces the built-in (selection in `CacheInterceptor.__init__`)

pico_caching-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,35 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+
+Examples of unacceptable behavior:
+
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information without explicit permission
+* Other conduct which could reasonably be considered inappropriate
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the project maintainer at **dperezcabrera@gmail.com**.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1.

pico_caching-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,37 @@
+# Contributing to pico-caching
+
+## Development setup
+
+```bash
+git clone https://github.com/dperezcabrera/pico-caching.git
+cd pico-caching
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+## Running tests
+
+```bash
+pytest tests/ -v
+pytest --cov=pico_caching --cov-report=term-missing tests/
+tox
+```
+
+## Linting
+
+```bash
+ruff check src/ tests/
+ruff format src/ tests/
+```
+
+## Code style
+
+- Python 3.11+
+- See AGENTS.md for conventions
+- Single-line commit messages
+
+## What NOT to do
+
+- Don't modify `_version.py` (auto-generated)
+- Don't change `version_scheme` in pyproject.toml
+- Don't add runtime dependencies without discussion

pico_caching-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 David Pérez Cabrera
+
+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.

pico_caching-0.1.0/MANIFEST.in

@@ -0,0 +1,5 @@
+include README.md LICENSE CHANGELOG.md
+recursive-include src *.py py.typed
+recursive-include tests *.py
+exclude .gitignore Dockerfile* docker-compose*.yml Makefile
+prune build dist .tox .pytest_cache __pycache__

pico_caching-0.1.0/PKG-INFO

@@ -0,0 +1,110 @@
+Metadata-Version: 2.4
+Name: pico-caching
+Version: 0.1.0
+Summary: Declarative caching for the Pico ecosystem: @cacheable AOP with pluggable backends.
+Author-email: David Perez Cabrera <dperezcabrera@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2025 David Pérez Cabrera
+        
+        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.
+        
+Project-URL: Homepage, https://github.com/dperezcabrera/pico-caching
+Project-URL: Documentation, https://dperezcabrera.github.io/pico-caching/
+Project-URL: Repository, https://github.com/dperezcabrera/pico-caching
+Project-URL: Changelog, https://github.com/dperezcabrera/pico-caching/blob/main/CHANGELOG.md
+Project-URL: Issue Tracker, https://github.com/dperezcabrera/pico-caching/issues
+Keywords: cache,cacheable,lru,ttl,aop,ioc,spring boot
+Classifier: Development Status :: 4 - Beta
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pico-ioc>=2.2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: pytest-cov>=5; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Dynamic: license-file
+
+# 📦 pico-caching
+
+[![PyPI](https://img.shields.io/pypi/v/pico-caching.svg)](https://pypi.org/project/pico-caching/)
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/dperezcabrera/pico-caching)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+![CI (tox matrix)](https://github.com/dperezcabrera/pico-caching/actions/workflows/ci.yml/badge.svg)
+[![codecov](https://codecov.io/gh/dperezcabrera/pico-caching/branch/main/graph/badge.svg)](https://codecov.io/gh/dperezcabrera/pico-caching)
+[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=dperezcabrera_pico-caching&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=dperezcabrera_pico-caching)
+[![Duplicated Lines (%)](https://sonarcloud.io/api/project_badges/measure?project=dperezcabrera_pico-caching&metric=duplicated_lines_density)](https://sonarcloud.io/summary/new_code?id=dperezcabrera_pico-caching)
+[![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=dperezcabrera_pico-caching&metric=sqale_rating)](https://sonarcloud.io/summary/new_code?id=dperezcabrera_pico-caching)
+[![PyPI Downloads](https://img.shields.io/pypi/dm/pico-caching)](https://pypi.org/project/pico-caching/)
+[![Docs](https://img.shields.io/badge/Docs-pico--caching-blue?style=flat&logo=readthedocs&logoColor=white)](https://dperezcabrera.github.io/pico-caching/)
+[![Interactive Lab](https://img.shields.io/badge/Learn-online-green?style=flat&logo=python&logoColor=white)](https://dperezcabrera.github.io/pico-learn/)
+
+Declarative **method caching** for the [Pico](https://github.com/dperezcabrera/pico-ioc) ecosystem: `@cacheable` over pico-ioc method interception, pluggable backends, auto-discovered by [pico-boot](https://github.com/dperezcabrera/pico-boot). Zero-config.
+
+## Install
+
+```bash
+pip install pico-caching
+```
+
+## Use
+
+```python
+from pico_ioc import component
+from pico_caching import cacheable
+
+@component
+class UserRepo:
+    @cacheable(ttl_seconds=60)
+    async def find(self, user_id: int): ...
+
+    @cacheable(key=lambda q: f"search:{q}")
+    def search(self, q: str): ...
+```
+
+Sync and async (the awaited **result** is cached, never the coroutine). Default backend: thread-safe in-memory LRU with per-entry TTL (`cache.max_entries`, `cache.default_ttl_seconds`). Bring your own backend by implementing the `CacheBackend` protocol as a `@component` — it replaces the built-in automatically.
+
+```yaml
+# application.yaml (optional)
+cache:
+  default_ttl_seconds: 300
+  max_entries: 1024
+```
+
+Skipped for now: `@cache_evict` and a Redis backend — planned once real usage asks for them.
+
+## Documentation
+
+Full docs at **[dperezcabrera.github.io/pico-caching](https://dperezcabrera.github.io/pico-caching/)**.
+
+## License
+
+MIT

pico_caching-0.1.0/README.md

@@ -0,0 +1,55 @@
+# 📦 pico-caching
+
+[![PyPI](https://img.shields.io/pypi/v/pico-caching.svg)](https://pypi.org/project/pico-caching/)
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/dperezcabrera/pico-caching)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+![CI (tox matrix)](https://github.com/dperezcabrera/pico-caching/actions/workflows/ci.yml/badge.svg)
+[![codecov](https://codecov.io/gh/dperezcabrera/pico-caching/branch/main/graph/badge.svg)](https://codecov.io/gh/dperezcabrera/pico-caching)
+[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=dperezcabrera_pico-caching&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=dperezcabrera_pico-caching)
+[![Duplicated Lines (%)](https://sonarcloud.io/api/project_badges/measure?project=dperezcabrera_pico-caching&metric=duplicated_lines_density)](https://sonarcloud.io/summary/new_code?id=dperezcabrera_pico-caching)
+[![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=dperezcabrera_pico-caching&metric=sqale_rating)](https://sonarcloud.io/summary/new_code?id=dperezcabrera_pico-caching)
+[![PyPI Downloads](https://img.shields.io/pypi/dm/pico-caching)](https://pypi.org/project/pico-caching/)
+[![Docs](https://img.shields.io/badge/Docs-pico--caching-blue?style=flat&logo=readthedocs&logoColor=white)](https://dperezcabrera.github.io/pico-caching/)
+[![Interactive Lab](https://img.shields.io/badge/Learn-online-green?style=flat&logo=python&logoColor=white)](https://dperezcabrera.github.io/pico-learn/)
+
+Declarative **method caching** for the [Pico](https://github.com/dperezcabrera/pico-ioc) ecosystem: `@cacheable` over pico-ioc method interception, pluggable backends, auto-discovered by [pico-boot](https://github.com/dperezcabrera/pico-boot). Zero-config.
+
+## Install
+
+```bash
+pip install pico-caching
+```
+
+## Use
+
+```python
+from pico_ioc import component
+from pico_caching import cacheable
+
+@component
+class UserRepo:
+    @cacheable(ttl_seconds=60)
+    async def find(self, user_id: int): ...
+
+    @cacheable(key=lambda q: f"search:{q}")
+    def search(self, q: str): ...
+```
+
+Sync and async (the awaited **result** is cached, never the coroutine). Default backend: thread-safe in-memory LRU with per-entry TTL (`cache.max_entries`, `cache.default_ttl_seconds`). Bring your own backend by implementing the `CacheBackend` protocol as a `@component` — it replaces the built-in automatically.
+
+```yaml
+# application.yaml (optional)
+cache:
+  default_ttl_seconds: 300
+  max_entries: 1024
+```
+
+Skipped for now: `@cache_evict` and a Redis backend — planned once real usage asks for them.
+
+## Documentation
+
+Full docs at **[dperezcabrera.github.io/pico-caching](https://dperezcabrera.github.io/pico-caching/)**.
+
+## License
+
+MIT

pico_caching-0.1.0/SECURITY.md

@@ -0,0 +1,11 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported |
+|---------|-----------|
+| 0.1.x   | Yes       |
+
+## Reporting a Vulnerability
+
+Email dperezcabrera@gmail.com with details. You will receive acknowledgment within 48 hours.

pico_caching-0.1.0/docs/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-07-03
+
+### Added
+
+- `@cacheable` decorator (sync + async; the awaited result is cached).
+- `CacheBackend` protocol; user backends replace the built-in automatically.
+- `InMemoryCacheBackend`: thread-safe LRU with per-entry TTL.
+- `CacheSettings` (prefix `cache`): `enabled`, `default_ttl_seconds`, `max_entries`.
+- Auto-discovery through the `pico_boot.modules` entry point; zero-config.
+
+[Unreleased]: https://github.com/dperezcabrera/pico-caching/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/dperezcabrera/pico-caching/releases/tag/v0.1.0

pico_caching-0.1.0/docs/LEARN.md

@@ -0,0 +1,14 @@
+# Learning Roadmap
+
+1. **Install** — `pip install pico-caching`
+   ([Getting Started](getting-started.md)).
+2. **First hit** — `@cacheable` on an expensive lookup; verify with a call
+   counter that the second call is free.
+3. **Tune TTL** — per-method `ttl_seconds` vs `cache.default_ttl_seconds`.
+4. **Custom keys** — `key=lambda user_id: f"user:{user_id}"` when reprs are
+   noisy.
+5. **Your backend** — implement `CacheBackend` as a `@component` (Redis,
+   memcached); it replaces the built-in automatically
+   ([Architecture](architecture.md)).
+6. **Invalidate** — inject the backend; `delete`/`clear` until
+   `@cache_evict` exists.