{"id":23159097,"url":"https://github.com/aekasitt/cachette","last_synced_at":"2025-08-18T01:31:11.250Z","repository":{"id":56899561,"uuid":"477969663","full_name":"aekasitt/cachette","owner":"aekasitt","description":"Cache extension for ASGI frameworks","archived":false,"fork":false,"pushed_at":"2024-04-11T13:30:04.000Z","size":1025,"stargazers_count":7,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"master","last_synced_at":"2024-04-23T02:57:52.067Z","etag":null,"topics":["aiobotocore","aiomcache","aioredis","asgi","asynchronous","blacksheep","botocore","cache","dynamodb","fastapi","litestar","memcached","mongo","mongodb","motor","pickle","pymongo","redis","starlette","valkey"],"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/aekasitt.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}},"created_at":"2022-04-05T04:07:36.000Z","updated_at":"2024-04-10T16:19:20.000Z","dependencies_parsed_at":"2023-12-03T12:24:50.008Z","dependency_job_id":"207c1660-c17d-404a-95bb-a94308fad139","html_url":"https://github.com/aekasitt/cachette","commit_stats":{"total_commits":76,"total_committers":1,"mean_commits":76.0,"dds":0.0,"last_synced_commit":"71062a3b4414c92c6ee861ce3b2269d7ae4c7a9d"},"previous_names":["aekasitt/cachette","aekasitt/fastapi-cachette"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aekasitt%2Fcachette","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aekasitt%2Fcachette/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aekasitt%2Fcachette/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aekasitt%2Fcachette/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aekasitt","download_url":"https://codeload.github.com/aekasitt/cachette/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230190224,"owners_count":18187462,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["aiobotocore","aiomcache","aioredis","asgi","asynchronous","blacksheep","botocore","cache","dynamodb","fastapi","litestar","memcached","mongo","mongodb","motor","pickle","pymongo","redis","starlette","valkey"],"created_at":"2024-12-17T22:29:01.768Z","updated_at":"2024-12-17T22:29:02.347Z","avatar_url":"https://github.com/aekasitt.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Cachette\n\n[![Package vesion](https://img.shields.io/pypi/v/cachette)](https://pypi.org/project/cachette)\n[![Format](https://img.shields.io/pypi/format/cachette)](https://pypi.org/project/cachette)\n[![Python version](https://img.shields.io/pypi/pyversions/cachette)](https://pypi.org/project/cachette)\n[![License](https://img.shields.io/pypi/l/cachette)](https://pypi.org/project/cachette)\n[![Top](https://img.shields.io/github/languages/top/aekasitt/cachette)](.)\n[![Languages](https://img.shields.io/github/languages/count/aekasitt/cachette)](.)\n[![Size](https://img.shields.io/github/repo-size/aekasitt/cachette)](.)\n[![Last commit](https://img.shields.io/github/last-commit/aekasitt/cachette/master)](.)\n\n![Cachette banner](static/cachette-banner.svg)\n\n## Features\n\nThis is an extension aiming at making cache access on the server\nBy configuration at startup of the FastAPI App instance, you can set the backend and other \nconfiguration options and have it remain a class constant when using FastAPI's\nintuitive [Dependency Injection](https://fastapi.tiangolo.com/tutorial/dependencies/) system.\n\nThe design has built-in limitations like fixed codec and backend once the app has been launched and \nencourage developers to design their applications with this in mind.\n\nMost of the Backend implementation is directly lifted from \n[fastapi-cache](https://github.com/long2ice/fastapi-cache) by \n[@long2ice](https://github.com/long2ice) excluding the MongoDB backend option.\n\n## Configuration Options\n\nThe following are the current available configuration keys that can be set on this FastAPI extension\non startup either by using a method which returns a list of tuples or a Pydantic BaseSettings object\n(See examples below or in `examples/` folder)\n\n    backend -- optional; must be one of [\"inmemory\", \"memcached\", \"mongodb\", \"pickle\", \"redis\"];\n      defaults to using inmemory option which required no extra package dependencies. To use\n      other listed options; See installation guide on the README.md at\n      [Repository Page](https://github.com/aekasitt/cachette).\n    codec -- optional; serialization and de-serialization format to have cache values stored in\n      the cache backend of choice as a string of selected encoding. once fetched, will have their\n      decoded values returned of the same format. must be one of [\"feather\", \"msgpack\", \"parquet\",\n      \"pickle\"]; if none is defined, will vanilla codec of basic string conversion will be used.\n    database_name -- required when backend set to \"mongodb\"; the database name to be automatically\n      created if not exists on the MongoDB instance and store the cache table; defaults to\n      \"cachette-db\"\n    memcached_host -- required when backend set to \"memcached\"; the host endpoint to the memcached\n      distributed memory caching system.\n    mongodb_url -- required when backend set to \"mongodb\"; the url set to MongoDB database\n      instance with or without provided authentication in such formats\n      \"mongodb://user:password@host:port\" and \"mongodb://host:port\" respectively.\n    pickle_path -- required when backend set to \"pickle\"; the file-system path to create local\n      store using python pickling on local directory\n    redis_url -- required when backend set to \"redis\"; the url set to redis-server instance with\n      or without provided authentication in such formats \"redis://user:password@host:port\" and\n      \"redis://host:port\" respectively.\n    table_name -- required when backend set to \"mongodb\"; name of the cache collection in case of\n      \"mongodb\" backend to have key-value pairs stored; defaults to \"cachette\". \n    ttl -- optional; the time-to-live or amount before this cache item expires within the cache;\n      defaults to 60 (seconds) and must be between 1 second to 1 hour (3600 seconds).\n    valkey_url -- required when backend set to \"valkey\"; the url set to valkey-server instance\n      with or without provided authentication in such formats \"valkey://user:password@host:port\"\n      and \"valkey://host:port\" respectively.\n\n## Examples\n\nThe following shows and example of setting up FastAPI Cachette in its default configuration, which\nis an In-Memory cache implementation.\n\n```py\nfrom cachette import Cachette\nfrom fastapi import FastAPI, Depends\nfrom fastapi.responses import PlainTextResponse\nfrom pydantic import BaseModel\n\napp = FastAPI()\n\n### Routing ###\nclass Payload(BaseModel):\n  key: str\n  value: str\n\n@app.post('/', response_class=PlainTextResponse)\nasync def setter(payload: Payload, cachette: Cachette = Depends()):\n  await cachette.put(payload.key, payload.value)\n  return 'OK'\n\n@app.get('/{key}', response_class=PlainTextResponse, status_code=200)\nasync def getter(key: str, cachette: Cachette = Depends()):\n  value: str = await cachette.fetch(key)\n  return value\n```\n\nAnd then this is how you set up a FastAPI Cachette with Redis support enabled.\n\n```py\nfrom cachette import Cachette\nfrom fastapi import FastAPI, Depends\nfrom fastapi.responses import PlainTextResponse\nfrom pydantic import BaseModel\n\napp = FastAPI()\n\n@Cachette.load_config\ndef get_cachette_config():\n  return [('backend', 'redis'), ('redis_url', 'redis://localhost:6379')]\n\nclass Payload(BaseModel):\n  key: str\n  value: str\n\n@app.post('/', response_class=PlainTextResponse)\nasync def setter(payload: Payload, cachette: Cachette = Depends()):\n  await cachette.put(payload.key, payload.value)\n  return 'OK'\n\n@app.get('/{key}', response_class=PlainTextResponse, status_code=200)\nasync def getter(key: str, cachette: Cachette = Depends()):\n  value: str = await cachette.fetch(key)\n  return value\n```\n\n## Roadmap\n\n1. Implement `flush` and `flush_expired` methods on individual backends \n(Not needed for Redis \u0026 Memcached backends)\n\n2. Memcached Authentication ([No SASL Support](https://github.com/aio-libs/aiomcache/issues/12))\nChange library?\n\n3. Add behaviors responding to \"Cache-Control\" request header\n\n4. More character validations for URLs and Database/Table/Collection names in configuration options\n\n## Installation\n\nThe easiest way to start working with this extension with pip\n\n```bash\npip install cachette\n# or\nuv add cachette\n```\n\nWhen you familiarize with the basic structure of how to Dependency Inject Cachette within your\nendpoints, please experiment more of using external backends with `extras` installations like\n\n```bash\n# Install FastAPI Cachette's extra requirements to Redis support\npip install cachette --install-option \"--extras-require=redis\"\n# or Install FastAPI Cachette's support to Memcached\nuv add cachette[memcached]\n# or Special JSON Codec written on Rust at lightning speed\nuv add cachette[orjson]\n# or Include PyArrow package making DataFrame serialization much easier\npip install cachette --install-option \"--extras-require=dataframe\"\n```\n\n## Getting Started\n\nThis FastAPI extension utilizes \"Dependency Injection\" (To be continued)\n\nConfiguration of this FastAPI extension must be done at startup using \"@Cachette.load_config\" \ndecorator (To be continued)\n\nThese are all available options with explanations and validation requirements (To be continued)\n\n## Examples\n\nThe following examples show you how to integrate this extension to a FastAPI App (To be continued)\n\nSee \"examples/\" folders\n\nTo run examples, first you must install extra dependencies\n\nDo all in one go with this command...\n\n```bash\npip install aiomcache motor uvicorn redis\n# or\nuv sync --extra examples\n# or\nuv sync --all-extras\n```\n\nDo individual example with this command...\n\n```bash\npip install redis\n# or\nuv sync --extra redis\n```\n\n## Contributions\n\n### Prerequisites\n\n- [python](https://www.python.org) version 3.9 or above\n- [uv](https://docs.astral.sh/uv)\n\n### Set up local environment\n\nThe following guide walks through setting up your local working environment using `pyenv`\nas Python version manager and `uv` as Python package manager. If you do not have `pyenv`\ninstalled, run the following command.\n\n\u003cdetails\u003e\n  \u003csummary\u003e Install using Homebrew (Darwin) \u003c/summary\u003e\n  \n  ```sh\n  brew install pyenv --head\n  ```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003e Install using standalone installer (Darwin and Linux) \u003c/summary\u003e\n  \n  ```sh\n  curl https://pyenv.run | bash\n  ```\n\u003c/details\u003e\n\nIf you do not have `uv` installed, run the following command.\n\n\u003cdetails\u003e\n  \u003csummary\u003e Install using Homebrew (Darwin) \u003c/summary\u003e\n\n  ```sh\n  brew install uv\n  ```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003e Install using standalone installer (Darwin and Linux) \u003c/summary\u003e\n\n  ```sh\n  curl -LsSf https://astral.sh/uv/install.sh | sh\n  ```\n\u003c/details\u003e\n\n\nOnce you have `pyenv` Python version manager installed, you can\ninstall any version of Python above version 3.9 for this project.\nThe following commands help you set up and activate a Python virtual\nenvironment where `uv` can download project dependencies from the `PyPI`\nopen-sourced registry defined under `pyproject.toml` file.\n\n\u003cdetails\u003e\n  \u003csummary\u003e Set up environment and synchronize project dependencies \u003c/summary\u003e\n\n  ```sh\n  pyenv install 3.9.19\n  pyenv shell 3.9.19\n  uv venv  --python-preference system\n  source .venv/bin/activate\n  uv sync --dev\n  ```\n\u003c/details\u003e\n\n## Test Environment Setup\n\nThis project utilizes multiple external backend services namely AWS DynamoDB, Memcached, MongoDB and\nRedis as backend service options as well as a possible internal option called InMemoryBackend. In\norder to test viability, we must have specific instances of these set up in the background of our\ntesting environment. Utilize orchestration file attached to reposity and `docker-compose` command \nto set up testing instances of backend services using the following command...\n\n```bash\ndocker-compose up --detach\n```\n\nWhen you are finished, you can stop and remove background running backend instances with the\nfollowing command...\n\n```bash\ndocker-compose down\n```\n\nNow that you have background running backend instances, you can proceed with the tests by using\n`pytest` command as such...\n\n```bash\npytest\n```\n\nOr you can configure the command to run specific tests as such...\n\n```bash\npytest -k test_load_invalid_configs\n# or\npytest -k test_set_then_clear\n```\n\nAll test suites must be placed under `tests/` folder or its subfolders.\n\n## License\n\nThis project is licensed under the terms of the MIT license.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faekasitt%2Fcachette","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faekasitt%2Fcachette","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faekasitt%2Fcachette/lists"}