Metadata-Version: 2.1
Name: sag-py-cache-decorator
Version: 0.3.0
Summary: A decorator to cache method call results with similar parameters
Home-page: https://github.com/SamhammerAG/sag_py_cache_decorator
Author: Samhammer AG
Author-email: support@samhammer.de
License: MIT
Project-URL: Documentation, https://github.com/SamhammerAG/sag_py_cache_decorator
Project-URL: Bug Reports, https://github.com/SamhammerAG/sag_py_cache_decorator/issues
Project-URL: Source, https://github.com/SamhammerAG/sag_py_cache_decorator
Keywords: cache,decorator
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Provides-Extra: dev
Requires-Dist: flake8; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-asyncio; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: toml; extra == "dev"
Requires-Dist: coverage; extra == "dev"
Requires-Dist: coverage-lcov; extra == "dev"
Requires-Dist: mock; extra == "dev"
Requires-Dist: types-mock; extra == "dev"
Requires-Dist: zipp>=3.19.1; extra == "dev"

# sag_py_cache_decorator
[![Maintainability][codeclimate-image]][codeclimate-url]
[![Coverage Status][coveralls-image]][coveralls-url]
[![Known Vulnerabilities][snyk-image]][snyk-url]

A cache annotation that can be used to cache calls to a method

## What it does
- Caches calls to methods if the same parameters are used
- Removes the least recently used cache item if a optional maximum is reached
- Supports sync and async functions
- Possibility to skip the cache by parameter
- Possibility to clear the cache entirely or for one set of parameters

### Installation
pip install sag-py-cache-decorator

## How to use
```python
from sag_py_cache_decorator.lru_cache import lru_cache

@lru_cache(maxsize=3)
def my_function(str: str, str2: str) -> str:
    return f"{str}-{str2}"
```

This is the regular use case of the cache.

Available decorator arguments:

| Argument | Description                                                                                                                | Default |
|----------|----------------------------------------------------------------------------------------------------------------------------|---------|
| maxsize  | If this size is reached, the least recently used cache item will be removed. Can be set to None to have a unlimited cache. | 128     |

```python
from sag_py_cache_decorator.lru_cache import lru_cache

@lru_cache(maxsize=3)
def my_function(
    str: str,
    lru_clear_cache: bool = False,
) -> str:
    return f"{str}-{str2}"

my_function("one")
my_function("two")
# Before executing the next function the cache is cleared and then
# rebuilt with the results of three and four because of lru_clear_cache = True
my_function("three", lru_clear_cache = True)
my_function("four")
```
Available function arguments:
| Argument            | Description                                                                                                                           | Default |
|---------------------|---------------------------------------------------------------------------------------------------------------------------------------|---------|
| lru_use_cache       | If set to false, the function call skips the cache. Existing cached items are ignored and new ones are not written for that call.     | True    |
| lru_clear_cache     | If set to true, the cache is cleared entirely before executing the method. The result of the call is then cached again.               | False   |
| lru_clear_arg_cache | If set to true, the result for this set of parameters is removed from cache(if present). The result of the call is then cached again. | False   |

## How to start developing

### With vscode

Just install vscode with dev containers extension. All required extensions and configurations are prepared automatically.

### With pycharm

* Install latest pycharm
* Install pycharm plugin BlackConnect
* Install pycharm plugin Mypy
* Configure the python interpreter/venv
* pip install requirements-dev.txt
* pip install black[d]
* Ctl+Alt+S => Check Tools => BlackConnect => Trigger when saving changed files
* Ctl+Alt+S => Check Tools => BlackConnect => Trigger on code reformat
* Ctl+Alt+S => Click Tools => BlackConnect => "Load from pyproject.yaml" (ensure line length is 120)
* Ctl+Alt+S => Click Tools => BlackConnect => Configure path to the blackd.exe at the "local instance" config (e.g. C:\Python310\Scripts\blackd.exe)
* Ctl+Alt+S => Click Tools => Actions on save => Reformat code
* Restart pycharm

## How to publish
* Update the version in setup.py and commit your change
* Create a tag with the same version number
* Let github do the rest

## How to test

To avoid publishing to pypi unnecessarily you can do as follows

* Tag your branch however you like
* Use the chosen tag in the requirements.txt-file of the project you want to test this library in, eg. `sag_py_cache_decorator==<your tag>`
* Rebuild/redeploy your project

[codeclimate-image]:https://api.codeclimate.com/v1/badges/e29dcd8f76877962c93b/maintainability
[codeclimate-url]:https://codeclimate.com/github/SamhammerAG/sag_py_cache_decorator/maintainability
[coveralls-image]:https://coveralls.io/repos/github/SamhammerAG/sag_py_cache_decorator/badge.svg?branch=master
[coveralls-url]:https://coveralls.io/github/SamhammerAG/sag_py_cache_decorator?branch=master
[snyk-image]:https://snyk.io/test/github/SamhammerAG/sag_py_cache_decorator/badge.svg
[snyk-url]:https://snyk.io/test/github/SamhammerAG/sag_py_cache_decorator
