logged-cache 0.0.0__tar.gz

logged_cache-0.0.0/.gitignore

@@ -0,0 +1,218 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$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
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.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/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+.vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml

logged_cache-0.0.0/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+<!-- version list -->
+
+## v0.0.0 (2026-05-23)
+
+- Initial Release
+
+## 0.1.0
+
+- Initial package structure.
+- Added `LoggedCache`, `LRUCacheManager`, `TTLCacheManager`, stats, hooks, and
+  decorator helpers.
+- Added tests, documentation, and GitHub Actions workflows.

logged_cache-0.0.0/CONTRIBUTING.md

@@ -0,0 +1,39 @@
+# Contributing
+
+## Setup
+
+```bash
+uv sync --extra dev --extra docs
+```
+
+Without `uv`:
+
+```bash
+python -m venv .venv
+. .venv/bin/activate
+python -m pip install -e ".[dev,docs]"
+```
+
+## Checks
+
+```bash
+ruff check .
+mypy
+pytest
+python -m build
+twine check dist/*
+```
+
+## Releases
+
+Releases are automated with Python Semantic Release and Conventional Commits.
+Pushes to `main` are analyzed and a release is created only when commits require
+one:
+
+- `fix: ...` creates a patch release.
+- `feat: ...` creates a minor release.
+- `feat!: ...` or a `BREAKING CHANGE:` footer creates a major release.
+
+Release commits are generated as `chore(release): <version> [skip ci]`.
+
+Please keep changes focused and include tests for behavior changes.

logged_cache-0.0.0/LICENSE

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

logged_cache-0.0.0/PKG-INFO

@@ -0,0 +1,389 @@
+Metadata-Version: 2.4
+Name: logged-cache
+Version: 0.0.0
+Summary: Small logged cachetools wrappers with cache managers, stats, and decorators.
+Project-URL: Homepage, https://github.com/51n91n51nk1n/logged_cache
+Project-URL: Documentation, https://github.com/51n91n51nk1n/logged_cache#readme
+Project-URL: Issues, https://github.com/51n91n51nk1n/logged_cache/issues
+Project-URL: Source, https://github.com/51n91n51nk1n/logged_cache
+Author: 51n91n51nk1n
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cache,cachetools,logging,lru,ttl
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: cachetools<7,>=5.3
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: packaging>=25; extra == 'dev'
+Requires-Dist: pkginfo>=1.12; extra == 'dev'
+Requires-Dist: pre-commit>=4.0; extra == 'dev'
+Requires-Dist: pylint>=3.3; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: python-semantic-release>=10.5; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Requires-Dist: twine>=5.0; extra == 'dev'
+Requires-Dist: types-cachetools>=6.2; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs>=1.6; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# logged-cache
+
+`logged-cache` is a small Python package around
+[`cachetools`](https://cachetools.readthedocs.io/) for applications that want
+cache hit/miss logs without rewriting their caching code.
+
+It provides:
+
+- `LoggedCache`, a mutable mapping wrapper that logs cache activity.
+- `LRUCacheManager` and `TTLCacheManager`, with a shared lock for
+  `cachetools.cached`.
+- `CacheStats`, lightweight counters for hits, misses, writes, deletes, and
+  clears.
+- `cached` and `cachedmethod`, convenience decorators for functions and methods.
+- Synchronous and asynchronous function caching with the same decorator.
+- Hooks and key formatters for metrics, redaction, and structured logging.
+
+## Installation
+
+```bash
+pip install logged-cache
+```
+
+For local development with `uv`:
+
+```bash
+uv sync --extra dev --extra docs
+uv run pytest
+```
+
+If you do not use `uv`, the project is still standard PEP 621 Python packaging:
+
+```bash
+python -m venv .venv
+. .venv/bin/activate
+python -m pip install -e ".[dev,docs]"
+pytest
+```
+
+## Quick Start
+
+```python
+import logging
+
+from logged_cache import (
+    LRUCacheManager,
+    TTLCacheManager,
+    cached,
+    cachedmethod,
+)
+
+logger = logging.getLogger("myapp.cache")
+
+# Use LRU when you want a bounded cache.
+users = LRUCacheManager(maxsize=256, logger=logger, name="users")
+
+
+@cached(users)
+def load_user(user_id: int) -> dict[str, int | str]:
+    return {"id": user_id, "name": "Ada"}
+
+
+# Use TTL when values should expire.
+tokens = TTLCacheManager(maxsize=1000, ttl=300, logger=logger, name="tokens")
+
+
+@cached(tokens)
+def fetch_token(account_id: str) -> str:
+    return f"token-for-{account_id}"
+
+
+# Use cachedmethod for instance or class methods.
+class ProfileService:
+    cache = LRUCacheManager(maxsize=256, logger=logger, name="profiles")
+
+    @cachedmethod(cache)
+    def load_profile(self, user_id: int) -> dict[str, int | str]:
+        return {"id": user_id, "name": "Ada"}
+
+
+# The same decorators work with async functions and methods.
+@cached(users)
+async def load_user_async(user_id: int) -> dict[str, int | str]:
+    return {"id": user_id, "name": "Ada"}
+
+
+load_user(1)  # miss, then set.
+load_user(1)  # hit.
+fetch_token("main")  # TTL miss, then set.
+ProfileService().load_profile(1)  # method cache.
+
+print(users.stats.hits, users.stats.misses, users.stats.hit_rate)
+```
+
+With a standard logging formatter, cache events look like this:
+
+```text
+DEBUG:myapp.cache:[users] Cache miss: function=load_user key=(1,)
+DEBUG:myapp.cache:[users] Cache set: function=load_user key=(1,)
+DEBUG:myapp.cache:[users] Cache hit: function=load_user key=(1,)
+```
+
+If `logger` is not provided, `logging.getLogger()` is used. Each log record also
+contains `cache_name`, `cache_function`, `cache_event`, and `cache_key`
+attributes for structured logging. When a cache is used through `cached`,
+`cachedmethod`, `async_cached`, or `async_cachedmethod`, log messages also show
+the function or method name.
+
+If `name` is omitted, decorators set a readable fallback name from the decorated
+callable, such as `myapp.services.UserService.load_user`.
+
+Keys are formatted defensively before they are written to logs. Very large keys
+are truncated, and plain object instances are shown as readable class names
+instead of memory-address-heavy default representations:
+
+```text
+DEBUG:myapp.cache:[users] Cache miss: key=<myapp.queries.UserQuery>
+DEBUG:myapp.cache:[users] Cache miss: key=('xxxxxxxxxxxxxxxxxxxx...<truncated>)
+```
+
+## LRU Cache
+
+Use `LRUCacheManager` when you want a fixed-size cache where the least recently
+used entries are evicted first.
+
+```python
+import logging
+
+from logged_cache import LRUCacheManager, cached
+
+logger = logging.getLogger("myapp.cache")
+users = LRUCacheManager(maxsize=256, logger=logger, name="users")
+
+
+@cached(users)
+def load_user(user_id: int) -> dict[str, int | str]:
+    return {"id": user_id, "name": "Ada"}
+
+
+load_user(1)
+load_user(1)
+
+print(users.stats.hits, users.stats.misses, users.stats.hit_rate)
+```
+
+## TTL Cache
+
+```python
+from logged_cache import TTLCacheManager, cached
+
+tokens = TTLCacheManager(maxsize=1000, ttl=300)
+
+
+@cached(tokens)
+def fetch_token(account_id: str) -> str:
+    return f"token-for-{account_id}"
+```
+
+## Async Functions
+
+Use the same `cached` decorator for `async def`. The awaited result is cached,
+not the coroutine object.
+
+```python
+from logged_cache import LRUCacheManager, cached
+
+profiles = LRUCacheManager(maxsize=256)
+
+
+@cached(profiles)
+async def fetch_profile(user_id: int) -> dict[str, int | str]:
+    return {"id": user_id, "name": "Ada"}
+
+
+profile = await fetch_profile(1)
+```
+
+For async-only applications, use `AsyncLRUCacheManager` or
+`AsyncTTLCacheManager` with `async_cached` to protect cache operations with
+`asyncio.Lock`.
+
+```python
+from logged_cache import AsyncLRUCacheManager, async_cached
+
+profiles = AsyncLRUCacheManager(maxsize=256, name="profiles")
+
+
+@async_cached(profiles)
+async def fetch_profile(user_id: int) -> dict[str, int | str]:
+    return {"id": user_id, "name": "Ada"}
+```
+
+## Methods
+
+Use `cachedmethod` for instance methods and class methods. By default, it uses
+`cachetools.keys.methodkey`, so the first method argument (`self` or `cls`) is
+not included in the cache key.
+
+```python
+from logged_cache import LRUCacheManager, cachedmethod
+
+
+class ProfileService:
+    cache = LRUCacheManager(maxsize=256)
+
+    @cachedmethod(cache)
+    def load_profile(self, user_id: int) -> dict[str, int | str]:
+        return {"id": user_id, "name": "Ada"}
+```
+
+Async methods work the same way:
+
+```python
+from logged_cache import AsyncLRUCacheManager, async_cachedmethod
+
+
+class AsyncProfileService:
+    cache = AsyncLRUCacheManager(maxsize=256)
+
+    @async_cachedmethod(cache)
+    async def load_profile(self, user_id: int) -> dict[str, int | str]:
+        return {"id": user_id, "name": "Ada"}
+```
+
+## Direct Mapping Usage
+
+```python
+from cachetools import LRUCache
+from logged_cache import LoggedCache
+
+cache = LoggedCache(LRUCache(maxsize=2))
+cache["a"] = 1
+
+if "a" in cache:
+    print(cache["a"])
+```
+
+Direct mapping operations emit the same event names:
+
+```text
+DEBUG:myapp.cache:[logged-cache] Cache set: key='a'
+DEBUG:myapp.cache:[logged-cache] Cache hit: key='a'
+DEBUG:myapp.cache:[logged-cache] Cache delete: key='a'
+DEBUG:myapp.cache:[logged-cache] Cache cleared
+```
+
+## Redacting Sensitive Keys
+
+By default, keys are logged with a safe formatter that truncates large values
+and describes plain object instances by class. For user IDs, tokens, emails, or
+other sensitive values, pass a formatter:
+
+```python
+from logged_cache import LRUCacheManager
+
+
+def redact_key(key: object) -> str:
+    return "<redacted>"
+
+
+cache = LRUCacheManager(maxsize=128, key_formatter=redact_key)
+```
+
+To keep the default behavior but change the maximum key length, use
+`format_cache_key`:
+
+```python
+from functools import partial
+from logged_cache import LRUCacheManager, format_cache_key
+
+cache = LRUCacheManager(
+    maxsize=128,
+    key_formatter=partial(format_cache_key, max_length=80),
+)
+```
+
+## Naming Caches
+
+Pass `name` when the same logger receives events from several caches.
+
+```python
+users = LRUCacheManager(maxsize=256, name="users")
+tokens = TTLCacheManager(maxsize=1000, ttl=300, name="tokens")
+```
+
+If `name` is omitted and the manager is used with `cached` or `cachedmethod`,
+the package sets a fallback from the decorated callable's module and qualified
+name. Explicit names are never replaced by decorators.
+
+## Exporting Metrics
+
+Use `on_event` to bridge cache events into your metrics stack.
+
+```python
+from logged_cache import CacheEvent, LRUCacheManager
+
+
+def record_metric(event: CacheEvent, key: object) -> None:
+    print(f"cache.{event}")
+
+
+cache = LRUCacheManager(maxsize=128, on_event=record_metric)
+```
+
+## API Overview
+
+`LoggedCache(inner, logger=None, log_level=logging.DEBUG, stats=None,
+key_formatter=repr, on_event=None, name=None)` wraps any mutable mapping, including
+`cachetools` caches. If `logger` is `None`, the root logger from
+`logging.getLogger()` is used.
+
+`LRUCacheManager(maxsize, ...)` creates an `LRUCache`, a `LoggedCache`, an
+`RLock`, and a shared `CacheStats` object.
+
+`TTLCacheManager(maxsize, ttl, ...)` does the same for `TTLCache`.
+
+`AsyncLRUCacheManager(maxsize, ...)` and `AsyncTTLCacheManager(maxsize, ttl, ...)`
+use `asyncio.Lock` for async-only applications.
+
+`cached(manager, key=cachetools.keys.hashkey, info=False)` returns a decorator
+compatible with regular and async functions.
+
+`cachedmethod(manager, key=cachetools.keys.methodkey, info=False)` returns a
+decorator compatible with regular and async methods.
+
+`async_cached(...)` and `async_cachedmethod(...)` are async-only variants for
+async cache managers.
+
+## Development
+
+```bash
+uv sync --extra dev --extra docs
+uv run ruff check .
+uv run pylint src/logged_cache tests
+uv run mypy
+uv run pytest
+uv run python -m build
+uv run twine check dist/*
+```
+
+Install pre-commit hooks with:
+
+```bash
+uv run pre-commit install
+```
+
+## License
+
+MIT