generated from jCloud/repository-template
153 lines
2.4 KiB
Markdown
153 lines
2.4 KiB
Markdown
# jcloud-cachelib
|
|
|
|
A simple library for caching data.
|
|
|
|
## Installation
|
|
You can install the library using `pip`:
|
|
|
|
```bash
|
|
pip install jcloud-cachelib --index-url https://repo.jcloud-services.ddns.net/simple/
|
|
```
|
|
|
|
## Full documentation
|
|
|
|
### `CacheItem`
|
|
A cache item.
|
|
|
|
#### Params
|
|
- `value` (type: `Any`): The value of the item
|
|
- `creation_time` (type: `Union[int, float]`): The time the item was created
|
|
|
|
#### Exceptions
|
|
|
|
No exceptions.
|
|
|
|
#### Methods
|
|
|
|
No methods.
|
|
|
|
### `Cache`
|
|
A thread-safe cache.
|
|
|
|
#### Parameters
|
|
- `generate_value_func` (type: `Optional[FunctionType]`, default: `None`): The function to generate a new value. It has to take one positional argument.
|
|
- `max_size` (type: `int`, default: `256`): The maximum size of the cache.
|
|
- `ttl` (type: `int`, default: `120`): The TTL (time to live) in seconds.
|
|
|
|
#### Exceptions
|
|
|
|
No exceptions.
|
|
|
|
#### Methods
|
|
|
|
##### `set`
|
|
|
|
Sets or updates an item (thread-safe).
|
|
|
|
###### Parameters
|
|
|
|
- `key` (type: `str`): The key.
|
|
- `value` (type: `Any`): The value.
|
|
|
|
###### Exceptions
|
|
|
|
No exceptions.
|
|
|
|
###### Returns
|
|
|
|
`None`
|
|
|
|
##### `delete`
|
|
Deletes an item (thread-safe).
|
|
|
|
###### Parameters
|
|
|
|
- `key` (type: `str`): The key.
|
|
|
|
###### Exceptions
|
|
|
|
- `KeyError`: If the item does not exist.
|
|
|
|
###### Returns
|
|
|
|
`None`
|
|
|
|
##### `get`
|
|
|
|
Returns an item (thread-safe).
|
|
If the item does not exist, it uses ``self.generate_value_func`` to
|
|
get the value. If no ``generate_value_func`` was specified in the
|
|
constructor of the ``Cache`` object, the value will be set to ``None``.
|
|
|
|
###### Parameters
|
|
|
|
- `key` (type: `str`): The key.
|
|
|
|
###### Exceptions
|
|
|
|
No exceptions.
|
|
|
|
###### Returns
|
|
|
|
The value.
|
|
Type: `Any`
|
|
|
|
##### `clean_item`
|
|
|
|
Removes an item if it is expired (thread-safe).
|
|
|
|
###### Parameters
|
|
|
|
- `key` (type: `key`): The key
|
|
|
|
###### Exceptions
|
|
|
|
No exceptions.
|
|
|
|
###### Returns
|
|
|
|
`None`
|
|
|
|
##### `clear_expired`
|
|
|
|
Removes all expired items (thread-safe).
|
|
|
|
###### Parameters
|
|
|
|
No parameters.
|
|
|
|
###### Exceptions
|
|
|
|
No Exceptions.
|
|
|
|
###### Returns
|
|
|
|
`None`
|
|
|
|
##### `clear`
|
|
|
|
Removes all items (thread-safe).
|
|
|
|
###### Parameters
|
|
|
|
No parameters.
|
|
|
|
###### Exceptions
|
|
|
|
No Exceptions.
|
|
|
|
###### Returns
|
|
|
|
`None`
|
|
|
|
## Changelog
|
|
|
|
### Version 0.1.0
|
|
- initial release
|
|
- thread safety
|
|
- set, update, delete and get items
|
|
- TTL
|
|
- support for specifying a function to generate new values
|
|
- deletion of expired items when getting them
|
|
- deletion of the least used item when a new item is set and the maximum size is reached
|
|
- support for clearing the cache |