Metadata-Version: 2.1
Name: cachian
Version: 0.3
Summary: Python lru_cache but with TTL
Home-page: https://github.com/ianteohsc/cachian
Download-URL: https://github.com/ianteohsc/cachian/archive/refs/tags/v0.2.tar.gz
Author: Ian Teoh
Author-email: ian.teoh@gmail.com
License: MIT
Keywords: LRU,cache,ttl
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Description-Content-Type: text/markdown
License-File: LICENSE

# Basic Usage

This module provides memoization with LRU, TTL and various clearing utility functions.

```
from cachian import Cachian

class PatientDB:

    @Cachian() #LRU caching defaulting to 10,000 items
    def get_by_id(self, id):
        pass

    @Cachian(maxsize=100) #LRU caching with 100 items
    def get_by_id2(self, id):
        pass        

    @Cachian(ttl=60) #TTL caching with TTL at 60 secs
    def get_latest_10_patient(self):
        pass
    
    #Split cache clearing by first args ie. id
    @Cachian(partition_attr=1)
    def get_by_id3(self, id):
        pass

    #TTL, LRU & partition caching, whichever miss first
    @Cachian(maxsize=100,ttl=60,partition_attr=1)
    def get_by_id4(self,id):
        pass


#Can be used with standalone functions
@Cachian()
def count_patient_name_len(patient_name):
    return len(patient_name)
```

## Backends

By default, memory backend is used. Any class that subclasses MutableMapping can be used as a backend store. Refer to the default MemoryStore for a skeletal example.

Using Redis as a backend can be achieved using:

```
import os
os.environ["CACHIAN_REDIS_HOST"] = "prod.redis.com"
os.environ["CACHIAN_REDIS_PORT"] = "6380"
os.environ["CACHIAN_REDIS_DB"] = "8"
os.environ["CACHIAN_REDIS_SSL"] = "true"
os.environ["CACHIAN_REDIS_PASSWORD"] = "abc123"

from cachian.redis_store import RedisStore

class PatientDB:

    @Cachian(cache_class=RedisStore) #LRU caching defaulting to 10,000 items with Redis storage backend
    def get_by_id(self, id):
        pass
```



# Utilities


## Get stats
Utilities to obtain statistics on cached methods/functions. Code continues from the **Basic Usage** example.

```
from cachian import global_cache_info
from pprint import pprint

#Print stats of all cached function/methods
pprint(global_cache_info())

#Print stats of a single cached function/method
pprint(count_patient_name_len.cache_info())
```

## Clearing cache
A few clearing utilities to allow selecting clearing of cached items. Code continues from the **Basic Usage** example.

```
from cachian import function_cache_reset_by_class, function_cache_reset, global_cache_reset

#Clear all cached items of all methods in the class
function_cache_reset_by_class(PatientDB)

#Clear cache of a function
function_cache_reset('count_patient_name_len')

#Clear all cached items
global_cache_reset()
```


# Installation

Basic installation
```
pip install Cachian
```

Clone the repository to run unittests.

Installing the **cachetools** package will allow unittest to run benchmarks against cachetools.

```
pip install cachetools
python -m unittest discover -s . -p "*_test.py"
```

# License

Copyright (c) 2023-2025 Ian Teoh

Licensed under the [MIT](https://raw.github.com/tkem/cachetools/master/LICENSE) license

