{"id":37075649,"url":"https://github.com/bnlucas/cacheio","last_synced_at":"2026-01-14T08:54:09.798Z","repository":{"id":308773272,"uuid":"1034050775","full_name":"bnlucas/cacheio","owner":"bnlucas","description":"A flexible and user-friendly Python caching interface that provides a unified API for both synchronous and asynchronous caching, by wrapping and integrating two well-established caching libraries.","archived":false,"fork":false,"pushed_at":"2025-08-08T17:31:28.000Z","size":70,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-04T09:19:11.168Z","etag":null,"topics":["aiocache","cachelib","caching","interface","python","standardization"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bnlucas.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-07T19:01:06.000Z","updated_at":"2025-08-08T03:36:00.000Z","dependencies_parsed_at":"2025-08-07T21:17:02.606Z","dependency_job_id":"4b505c51-4a3b-4404-a038-6f16c6bb6294","html_url":"https://github.com/bnlucas/cacheio","commit_stats":null,"previous_names":["bnlucas/cacheio"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/bnlucas/cacheio","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bnlucas%2Fcacheio","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bnlucas%2Fcacheio/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bnlucas%2Fcacheio/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bnlucas%2Fcacheio/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bnlucas","download_url":"https://codeload.github.com/bnlucas/cacheio/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bnlucas%2Fcacheio/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28414713,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T08:38:59.149Z","status":"ssl_error","status_checked_at":"2026-01-14T08:38:43.588Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aiocache","cachelib","caching","interface","python","standardization"],"created_at":"2026-01-14T08:54:09.078Z","updated_at":"2026-01-14T08:54:09.782Z","avatar_url":"https://github.com/bnlucas.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# cacheio\n![Python Version](https://img.shields.io/badge/python-3.10%2B-blue) ![License](https://img.shields.io/github/license/bnlucas/cacheio) ![PyPI - Version](https://img.shields.io/pypi/v/cacheio)\n\nA flexible and user-friendly Python caching utility that provides a **unified interface** for both synchronous and asynchronous caching, **wrapping and integrating** two well-established caching libraries: [`cachelib`](https://github.com/pallets/cachelib) for synchronous caching, and [`aiocache`](https://github.com/aio-libs/aiocache) for asynchronous caching.\n\n`cacheio` simplifies caching in Python applications by providing a consistent API for both sync and async use cases — no need to learn two different interfaces or manage separate dependencies manually. It intelligently loads only the backend dependencies you need.\n\n---\n\n## Overview 🚀\n\n`cacheio` offers a unified caching interface for Python developers, abstracting away the differences between synchronous and asynchronous caching libraries. By wrapping [`cachelib`](https://github.com/pallets/cachelib) for sync caching and [`aiocache`](https://github.com/aio-libs/aiocache) for async caching, it lets you write caching logic that is clean, consistent, and easy to maintain.\n\n---\n\n## Installation\n\nYou can install `cacheio` via pip. It supports optional dependency groups for backend support.\n\n### Basic Installation\n\nInstall core library without caching backends:\n\n```bash\npip install cacheio\n```\n\n### Installing with Backends\n\n- **Synchronous caching (cachelib-based):**\n\n```bash\npip install \"cacheio[sync]\"\n```\n\n- **Asynchronous caching (aiocache-based):**\n\n```bash\npip install \"cacheio[async]\"\n```\n\n- **Full installation (both sync and async):**\n\n```bash\npip install \"cacheio[full]\"\n```\n\n---\n\n## Quick Start\n\n### Synchronous Caching\n\nUse `CacheFactory.memory_cache()` to get a sync cache adapter backed by `cachelib`.\n\n```python\nfrom cacheio import CacheFactory\n\ncache = CacheFactory.memory_cache()\n\ncache.set(\"my_key\", \"my_value\", ttl=300)\nprint(cache.get(\"my_key\"))\n```\n\n### Asynchronous Caching\n\nUse `CacheFactory.async_memory_cache()` to get an async cache adapter backed by `aiocache`.\n\n```python\nimport asyncio\nfrom cacheio import CacheFactory\n\nasync def main():\n    async_cache = CacheFactory.async_memory_cache()\n    await async_cache.set(\"my_async_key\", \"my_async_value\", ttl=300)\n    val = await async_cache.get(\"my_async_key\")\n    print(val)\n\nasyncio.run(main())\n```\n\n---\n\n## Using Decorators for Method Result Caching\n\n`cacheio` provides four decorators to easily cache method results with minimal boilerplate:\n\n- `@cached`: Sync decorator with automatic cache key generation.\n- `@memoized`: Sync decorator with user-defined key function.\n- `@async_cached`: Async decorator with automatic cache key generation.\n- `@async_memoized`: Async decorator with user-defined async key function.\n\n### 1. Synchronous `@cached`\n\nAutomatically caches method results using method arguments as the cache key.\n\n```python\nfrom cacheio import cached\nfrom cacheio.mixins import Cacheable\n\nclass UserService(Cacheable):\n    @cached(ttl=60)\n    def fetch_user(self, user_id: int) -\u003e dict:\n        print(f\"Fetching user {user_id} from DB...\")\n        return {\"id\": user_id, \"name\": f\"User_{user_id}\"}\n\nservice = UserService()\nprint(service.fetch_user(1))  # Runs and caches\nprint(service.fetch_user(1))  # Returns cached result\n```\n\n### 2. Synchronous `@memoized`\n\nAllows a custom cache key function for more control.\n\n```python\nfrom cacheio import memoized\nfrom cacheio.mixins import Cacheable\n\nclass UserService(Cacheable):\n    @memoized(key_fn=lambda self, user_id, **kwargs: f\"user:{user_id}\", ttl=60)\n    def fetch_user(self, user_id: int, request_id: str) -\u003e dict:\n        print(f\"Fetching user {user_id} with request {request_id}\")\n        return {\"id\": user_id, \"request\": request_id}\n\nservice = UserService()\nprint(service.fetch_user(1, request_id=\"abc\"))  # Cached by user_id only\nprint(service.fetch_user(1, request_id=\"xyz\"))  # Returns cached result (same key)\n```\n\n### 3. Asynchronous `@async_cached`\n\nAsync version of `@cached`, for async methods.\n\n```python\nimport asyncio\nfrom cacheio import async_cached\nfrom cacheio.mixins import AsyncCacheable\n\nclass AsyncUserService(AsyncCacheable):\n    @async_cached(ttl=60)\n    async def fetch_user(self, user_id: int) -\u003e dict:\n        print(f\"Fetching user {user_id} asynchronously...\")\n        await asyncio.sleep(2)\n        return {\"id\": user_id, \"name\": f\"User_{user_id}\"}\n\nasync def main():\n    service = AsyncUserService()\n    print(await service.fetch_user(1))  # Runs and caches\n    print(await service.fetch_user(1))  # Returns cached result\n\nasyncio.run(main())\n```\n\n### 4. Asynchronous `@async_memoized`\n\nAsync decorator with a custom async key function.\n\n```python\nimport asyncio\nfrom cacheio import async_memoized\nfrom cacheio.mixins import AsyncCacheable\n\nclass AsyncUserService(AsyncCacheable):\n    @async_memoized(key_fn=lambda self, user_id, **kwargs: f\"user:{user_id}\", ttl=60)\n    async def fetch_user(self, user_id: int, request_id: str) -\u003e dict:\n        print(f\"Fetching user {user_id} with request {request_id} asynchronously...\")\n        await asyncio.sleep(2)\n        return {\"id\": user_id, \"request\": request_id}\n\nasync def main():\n    service = AsyncUserService()\n    print(await service.fetch_user(1, request_id=\"abc\"))  # Cached\n    print(await service.fetch_user(1, request_id=\"xyz\"))  # Returns cached result\n\nasyncio.run(main())\n```\n\n---\n\n## Configuration\n\nYou can customize global caching behavior via the `config` object and the `configure()` function.\n\nExample:\n\n```python\nfrom cacheio import config, configure\n\ndef update_settings(cfg):\n    cfg.default_ttl = 600\n    cfg.default_threshold = 1000\n\nconfigure(update_settings)\n```\n\nThis allows centralized control of defaults like TTL and cache size threshold.\n\n---\n\n## Contributing\n\nContributions are welcome! Feel free to open issues or submit pull requests on our [GitHub repository](https://github.com/bnlucas/cacheio).\n\n---\n\n## License\n\n`cacheio` is distributed under the MIT license. See the [LICENSE](https://github.com/bnlucas/cacheio/blob/main/LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbnlucas%2Fcacheio","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbnlucas%2Fcacheio","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbnlucas%2Fcacheio/lists"}