{"id":19547323,"url":"https://github.com/emilamaj/cachedisk","last_synced_at":"2025-02-26T06:20:37.981Z","repository":{"id":227245176,"uuid":"770855567","full_name":"emilamaj/CacheDisk","owner":"emilamaj","description":"Simple Python library to cache sync/async function results, with disk persistence and I/O tuning options","archived":false,"fork":false,"pushed_at":"2024-03-12T11:17:14.000Z","size":7,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-04-14T05:02:04.596Z","etag":null,"topics":["asynchronous","cache","disk","key-value-database","memory","optimization","python"],"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/emilamaj.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":"2024-03-12T09:30:20.000Z","updated_at":"2024-04-09T16:46:31.000Z","dependencies_parsed_at":null,"dependency_job_id":"267062d5-4ab0-4d3f-8540-7c16f4860550","html_url":"https://github.com/emilamaj/CacheDisk","commit_stats":null,"previous_names":["emilamaj/cachedisk"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emilamaj%2FCacheDisk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emilamaj%2FCacheDisk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emilamaj%2FCacheDisk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emilamaj%2FCacheDisk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/emilamaj","download_url":"https://codeload.github.com/emilamaj/CacheDisk/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240802190,"owners_count":19859933,"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":["asynchronous","cache","disk","key-value-database","memory","optimization","python"],"created_at":"2024-11-11T03:49:19.119Z","updated_at":"2025-02-26T06:20:37.953Z","avatar_url":"https://github.com/emilamaj.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CacheDisk\r\n\r\nCacheDisk is a lightweight, in-memory caching library designed for Python, offering seamless disk persistence.\r\nIt provides a drop-in optimization for your frequently used sync/async functions, allowing you to cache their results and retrieve them from memory on subsequent calls.\r\n\r\n## Features\r\n\r\n- Easy-to-use decorators to cache the results of functions, both synchronously and asynchronously.\r\n- Disk persistence allows your cache to survive across application restarts, enhancing data retrieval times for repeated operations.\r\n- Flexible storage options with support for JSON and Pickle, choose according to your compatibility or performance needs.\r\n- Culling functionality to remove infrequently used cache entries, ensuring that your cache does not grow unbounded.\r\n- Configurable caching parameters allowing fine-tuned performance to match the needs of your application, by avoiding slow-downs caused by disk writes.\r\n\r\n## Installation\r\n\r\nCacheDisk is available on PyPi and can be installed using pip:\r\n\r\n```bash\r\npip install cachedisk\r\n```\r\n\r\n## Quick Start\r\n\r\n### Basic Caching Example\r\n\r\nHere's a quick example to get you started with CacheDisk:\r\n\r\n```python\r\nfrom cachedisk import CacheDisk, CacheDiskConfig\r\n\r\n# Optional: Configure CacheDisk to use JSON for serialization\r\nCacheDiskConfig.use_json = True\r\n\r\n@CacheDisk.sync_disk_cache()\r\ndef expensive_function(param1):\r\n    # Simulate an expensive or time-consuming operation\r\n    return some_expensive_computation(param1)\r\n\r\n# First call will compute and cache the result\r\nresult = expensive_function('some_input') # Takes 10 seconds to return\r\n\r\n# Subsequent calls with the same input will fetch the result from the cache\r\ncached_result = expensive_function('some_input') # Returns in 0ms\r\n```\r\n\r\nFor asynchronous functions, simply use the `@CacheDisk.async_disk_cache()` decorator in a similar fashion:\r\n\r\n```python\r\n@CacheDisk.async_disk_cache()\r\nasync def expensive_function(param1):\r\n    return some_expensive_computation(param1)\r\n```\r\n\r\n### Advanced Usage\r\n\r\nYou can customize the behavior of the cache by passing additional parameters to the decorators:\r\n\r\n- `factor`: The factor which determines when should the save to disk operation be force-triggered. A factor of 0.33  (default value) means that the cache will be saved to disk every 33% of the cache size changes.\r\n- `delay`: The delay in seconds after which the save to disk operation will be force-triggered if there are no save operations due to cache size changes.\r\n- `cache_none`: Whether to cache the result of the function when it returns None. This can be useful if you want to recompute the result of the function when it returns None (possibly due to exceptions).\r\n\r\nHere's an example:\r\n```python\r\n@CacheDisk.async_disk_cache(factor=0.50, delay=120, cache_none=False)\r\nasync def expensive_function(param1):\r\n    return some_expensive_computation(param1)\r\n```\r\n\r\n### Configuring the Cache Directory\r\n\r\nBy default, CacheDisk uses a directory named `cache_data` in your current working directory. You can customize the cache directory as follows:\r\n\r\n```python\r\nCacheDiskConfig.cache_dir = '/path/to/your/custom/cache/directory'\r\n```\r\n\r\n### Caveat:Committing Cache Changes\r\n\r\nSome pending cache changes may not be saved to disk if the program is terminated abruptly right after the cache is updated but before the changes are written to disk.\r\nTo manually trigger saving all pending cache changes to disk:\r\n\r\n```python\r\nCacheDisk.commit()\r\n```\r\n\r\nThis can be particularly useful before application shutdown or after a batch of operations.\r\nThis delayed commit behavior is put in place to avoid degrading the SSD/HDD longevity with frequent writes.\r\nIt can however be completely disabled by passing the parameter\r\n\r\n## Contributing\r\n\r\nContributions are welcome! Please feel free to submit a pull request or open an issue if you have feedback, ideas, or code improvements.\r\n\r\n## License\r\n\r\nCacheDisk is licensed under the MIT License. See [LICENSE](LICENSE) file for more details.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Femilamaj%2Fcachedisk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Femilamaj%2Fcachedisk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Femilamaj%2Fcachedisk/lists"}