Metadata-Version: 2.5
Name: my-mimic
Version: 0.6.0
Summary: Cache/Memoization package
Project-URL: homepage, https://github.com/CenturyBoys/my-mimic
Project-URL: repository, https://github.com/CenturyBoys/my-mimic
Project-URL: documentation, https://github.com/CenturyBoys/my-mimic
Author-email: Marco Sievers de Almeida Ximit Gaia <im.ximit@gmail.com>
License-Expression: Apache-2.0
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: meeseeks-singleton>=0.4.2
Provides-Extra: redis-edition
Requires-Dist: redis>=5.0.8; extra == 'redis-edition'
Provides-Extra: temp-edition
Requires-Dist: aiofile>=3.8.8; extra == 'temp-edition'
Description-Content-Type: text/markdown

# My Mimic
```
⠀⠀⠀⠀⠀⠀⠀⠀⠀⣀⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⣴⣶⣶⣦⣄⣀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⢠⢊⢽⣝⡆⣫⣷⣌⣦⣤⡐⠾⣿⣷⣄⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣠⣾⣿⣿⣾⣯⣿⣯⣷⣦⣄⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⡠⢤⣜⠺⢟⡩⡇⢹⣉⡟⣰⠻⣯⢇⣿⣿⣿⣦⣄⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⣠⣾⣿⣿⣿⣿⣿⣿⣿⠿⠿⠿⠿⠷⠄⠀⠀⠀⠀⠀⠀⠀
⢸⢰⣻⡟⣄⢈⣖⠹⢺⠰⠷⣏⢱⣾⣿⣿⣿⣿⣾⣿⣷⣶⣶⣤⣤⠠⠐⠂⠀⠀⠐⠒⠠⣄⣤⣤⣶⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠁⠋⠳⣄⠫⡐⣉⠆⡓⢌⢂⢿⢹⣿⡛⢿⣿⣿⣿⣿⣿⣿⠟⠁⠀⠀⠀⠀⠀⢀⠀⢸⣿⣿⣿⣿⣿⣿⣿⣿⣿⡟⠛⠻⠿⠃⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠈⡔⣡⠒⣸⠞⡌⢂⢎⣥⣷⣿⢨⣿⣿⣿⣿⡟⠁⡀⠀⠠⠀⡐⠀⠡⠀⠀⠀⢿⣿⣿⣿⣿⣿⣿⣿⣿⠃⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠸⣦⣳⡆⣞⣴⡿⠃⠀⠘⠛⠛⣿⣿⣿⡿⢀⡞⢣⡇⠀⡀⠰⡴⠟⡄⠆⢃⠘⣿⣿⣿⣿⣿⣿⣿⣿⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⢠⢛⢻⠏⠉⠀⠀⠀⠀⠀⠀⠙⠛⡫⢁⠸⡀⠸⠅⢀⠡⢸⡇⠘⡿⠀⠈⠘⡌⠛⠿⢿⡟⠉⠉⠉⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⡜⠀⢸⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⣟⡆⢠⠈⠁⢀⠂⠀⡀⠉⢒⠇⠠⢀⣭⣔⡩⢐⠂⡇⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⢇⢀⡦⠀⠀⠀⠀⠀⠀⠀⢀⣀⠀⣯⡇⢀⡘⢷⣶⢶⠶⣶⣚⡟⡄⣴⠻⣭⣟⣷⡈⢒⣃⣀⣀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⢸⡈⠐⠣⠄⣀⡀⠀⣠⡾⣩⢏⡼⣹⢏⣧⡂⠌⡌⠻⣉⠎⡑⢎⢧⡐⢯⣷⢳⡾⡝⣠⠿⣏⡟⣿⣟⣦⡄⠀⠀⣀⣀⡀⠤⣄⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠙⠦⠄⣐⡀⢀⠠⠉⠉⠘⡷⣎⢷⡹⣎⢷⡻⣖⢨⣑⣨⠘⢩⠘⠌⣃⠢⢉⣋⣵⠾⣍⢳⣬⣛⢶⣻⡮⡑⠆⠀⢀⣀⣠⠀⠈⡆⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠉⢱⣧⣥⣾⢿⡜⣯⢳⣝⢮⣳⡇⠁⠒⠤⢋⢏⢩⡙⢭⢉⠧⡈⣿⡝⣮⢳⢮⡝⣮⢷⣻⢾⡏⠉⠀⠀⠘⡦⠀⢹⡀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢿⡽⣯⠿⣽⣞⡷⣞⡷⣯⠛⠀⠀⣠⣤⠾⡶⣞⣤⣅⠂⠀⢻⣽⣎⣟⣮⡽⣯⢿⣹⡿⠀⠀⠀⠀⠀⠸⢄⣈⡇⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠈⠻⣽⣻⠷⣾⡽⣯⠟⠃⠀⢠⣾⢻⣬⢛⡵⢫⡞⣭⢻⡄⠀⠙⠾⣽⢾⣽⣳⡯⠛⠀⠀⠀⠀⠀⡠⠊⠉⠀⠈⠑⠢⡀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠈⠙⣩⠁⠀⠀⠀⠀⣼⣇⡳⣌⠳⣜⢣⡞⣵⣫⢽⠀⠀⢀⠤⡉⠽⠀⠀⠀⠀⡠⠖⠂⠒⠁⠀⡀⠀⡀⠀⠀⣠⠭⡁⠉⡀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢻⡅⡄⠀⠀⠀⢿⡲⣝⡬⣓⢮⡳⣝⢮⣳⢻⠀⡌⢃⢚⢰⠃⠀⠀⠀⠀⢧⢀⡰⠊⠙⣼⠁⡬⡄⢰⠦⢄⡁⠘⢫⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣠⡾⣻⢟⣿⣴⠠⢌⠻⣧⣻⣝⣮⣳⣏⡷⡽⣣⡵⣞⠿⣯⢿⣄⠀⠀⠀⠀⠀⠀⠀⠀⡠⠃⠀⡇⢸⠀⠑⢤⠐⠴⠞⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢰⣿⣱⣟⣾⣳⣟⣷⡨⠒⣌⠱⡛⢚⠓⣛⢙⣰⣿⡹⣞⡽⣎⢷⣻⡄⠀⠀⠀⠀⠀⠀⠐⢧⣀⣠⠇⠘⠶⠀⠞⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⠽⢷⣻⣞⣧⣟⡾⣽⠧⠣⢄⠣⡘⠤⡉⢤⠃⣼⣷⣻⢾⣵⣻⠞⠉⠓⠤⣀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣀⡄⠊⠁⠀⢀⣿⣞⣷⣫⣽⡞⠐⢣⣬⣆⣁⣢⣑⣢⣵⡞⣷⣯⣟⣾⣽⠂⣤⣀⠀⠀⢉⡔⠒⣤⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⣴⠞⠉⠀⢠⣴⠞⠋⠉⠙⠛⠛⠉⠀⠀⠀⠀⠈⠉⠉⠉⠁⠀⠀⠈⠘⠛⠉⠁⠀⠀⠉⠛⠶⡏⠀⠀⠀⣷⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⣎⠈⠐⠒⡖⣾⡉⢷⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠑⣫⢭⠶⣋⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠈⠳⠶⠹⢜⡱⡸⢌⡳⢄⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠰⣈⢦⠓⡼⡄⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⢀⣴⣶⣄⡀⠈⠑⣇⡝⣌⣿⣷⡄⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠈⣣⡛⡔⡻⣄⠀⠀⠀⠀⠀⣀⡀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⢠⣿⣿⠛⢻⣷⣤⣾⣿⣿⣿⣿⣿⡿⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢰⣿⣷⣌⣱⣿⣷⣄⡀⣠⣾⣿⢿⣧⡀⠀
⠀⠀⠀⠀⠀⠀⠀⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⡿⠟⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠺⣿⣿⣿⣿⣿⣿⣿⣿⣿⣷⣾⣿⣻⣷⡀
⠀⠀⠀⠀⠀⠀⠀⠙⠿⣿⣿⣿⣿⣿⣿⡿⠟⠉⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠈⠉⠛⢿⣿⣿⣿⣟⣿⣻⣽⣳⣯⣿⠇
⠀⡀⠀⠀⠀⠀⠀⠀⠀⠀⠉⠉⠉⠉⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠉⠛⠛⠛⠻⠷⠿⠷⠟⠋⠀
                                                                            By CenturyBoys
```

[![CI](https://github.com/CenturyBoys/my-mimic/actions/workflows/ci.yml/badge.svg)](https://github.com/CenturyBoys/my-mimic/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/CenturyBoys/my-mimic/branch/main/graph/badge.svg)](https://codecov.io/gh/CenturyBoys/my-mimic)
[![PyPI](https://badge.fury.io/py/my-mimic.svg)](https://pypi.org/project/my-mimic/)
[![Python](https://img.shields.io/pypi/pyversions/my-mimic.svg)](https://pypi.org/project/my-mimic/)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)

My Mimic is a function decorator for cache/memoization. They use the args and kwargs to create a hash to storage the function call result after the first call all function invoke will use already storage result.

## Installation

```shell
uv add my-mimic
OR
poetry add my-mimic
OR
pip install my-mimic
```

### Configuration

Using `mr.Mime` from Mimic allowed you to use the default config or create a self one. By default, an in-memory state are used you can implement your own state resolver using the interface IState.

Below you can see the interface contract
```python
from abc import ABC, abstractmethod


class IState(ABC):
    """
    State interface
    """

    @abstractmethod
    def sync_get(self, key: str):
        """
        Sync get implementation
        :param key: str
        :return:
        """

    @abstractmethod
    def sync_set(self, key: str, value: any, ttl: int = None):
        """
        Sync set implementation
        :param key: str
        :param value: Any
        :param ttl: int. Seconds that the cache will have to live. Set None to never die
        :return:
        """

    @abstractmethod
    async def async_get(self, key: str):
        """
        Async get implementation
        :param key: str
        :return:
        """

    @abstractmethod
    async def async_set(self, key: str, value: any, ttl: int = None):
        """
        Async set implementation
        :param key: str
        :param value: Any
        :param ttl: int. Seconds that the cache will have to live. Set None to never die
        :return:
        """
```

To configure a new state you need to use `mr.Mime.set_config` function passing a config instance. The config accepts a `kwargs: dict` parameter, this parameter will be sent to the state instance.

```python
import mr


class MyState(mr.IState):
    def sync_get(self, key: str):
        pass

    def sync_set(self, key: str, value: any, ttl: int = None):
        pass

    async def async_get(self, key: str):
        pass

    async def async_set(self, key: str, value: any, ttl: int = None):
        pass


mr.Mime.set_config(config=mr.Config(state=MyState, state_kwargs={"KEY": "value"}))
```

### Extras

For default a memory-state is allways set. But we also have extras states see below the list:

#### Redis

This extra add the redis [package](https://pypi.org/project/redis/) in version `^4.6.0`. All result will be `serialized` to be stored and `unserialized` to be returned using the [pickle lib](https://docs.python.org/3/library/pickle.html).

How to install extra packages?

```shell
uv add 'my-mimic[redis_edition]'
OR
poetry add my-mimic -E redis_edition
OR
pip install 'my-mimic[redis_edition]'
```

You need pass the `REDIS_URL` parameter on configuration

```python
import mr

mr.Mime.set_config(
    config=mr.Config(state=mr.states.RedisState, state_kwargs={"REDIS_URL": "redis://"})
)
```

#### Redis

This extra add the aiofile [package](https://pypi.org/project/aiofile/) in version `^3.8.8`. All result will be `serialized` to be stored and `unserialized` to be returned using the [pickle lib](https://docs.python.org/3/library/pickle.html).

How to install extra packages?

```shell
uv add 'my-mimic[temp_edition]'
OR
poetry add my-mimic -E temp_edition
OR
pip install 'my-mimic[temp_edition]'
```

You can pass the `BASE_PATH` parameter on configuration. Where all cached files will be storage, if not set will use the OS default temp folder.
You can pass the `STATIC` parameter on configuration. When `True` disable the temporary cleanup, if used without set a `BASE_PATH` will use the OS default temp folder.


```python
import mr

mr.Mime.set_config(
    config=mr.Config(
        state=mr.states.TempFileState,
        kwargs={"BASE_PATH": "/home/my_user", "STATIC": True},
    )
)
```

### How to use

For that we use `mr.Mime` as decorator that receive a ttl as argument. That means the ttl is the seconds that the cache will have to live. Set None to never die.

Mime works fine with sync and async functions too.

```python
import time
import mr


@mr.Mime(ttl=1)
def cached_callback(param_a: int, param_b: int):
    print("Function was called")
    return param_a + param_b


result = cached_callback(1, 2)
print(result)
result = cached_callback(1, 2)
print(result)
time.sleep(2)
print("Await 2 seconds")
result = cached_callback(1, 2)
print(result)
```
The output will be

```bash
Function was called
3
3
Await 2 seconds
Function was called
3
```

### Invalidation

Every decorated function exposes an `invalidate` method that drops the cached entry
for a specific set of arguments (the cache key is `sha256(func_name + args + kwargs)`).
Call it with the same arguments you used to call the function.

```python
import mr


@mr.Mime(ttl=60)
def cached_callback(param_a: int, param_b: int):
    return param_a + param_b


cached_callback(1, 2)  # computed and cached
cached_callback.invalidate(1, 2)  # drop the cached entry for (1, 2)
cached_callback(1, 2)  # computed again
```

For async functions `invalidate` is awaitable:

```python
@mr.Mime(ttl=60)
async def cached_callback(param_a: int, param_b: int):
    return param_a + param_b


await cached_callback.invalidate(1, 2)
```