Metadata-Version: 2.4
Name: reactive_caching
Version: 0.2.1
Summary: Caching module for class properties, with automatic invalidation based on attribute changes.
Author-email: rgzz666 <tt1224@hotmail.com>
License-Expression: Apache-2.0
Project-URL: Repository, https://github.com/totowang-hhh/reactive_caching/
Project-URL: Author's Site, https://rgzz666.top
Keywords: caching,cache,reactive,property,attribute,attr,performance,something new,something interesting
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# Reactive Caching

> 2026 by rgzz666
>
> Latest: v0.2.1 (Beta)
>
> [GitHub](https://github.com/TotoWang-hhh/reactive_caching) | [PyPI](https://pypi.org/project/reactive-caching/)

**Reactive Caching is a Python module that implements cached properties with automatic invalidation according to configurable rules of changes in attributes.** This can avoid calculating the property everytime when calling it, while also keeps the data up to date.

```bash
pip3 install reactive_caching
```

## Usage

### Import the module

To use the module, you must import it with:

```python
import reactive_caching
```

or if you prefer to directly use the contents:

```python
from reactive_caching import CachedClass, cached_property
```

Note that the latter will be used as the example in the folowing guide.

### Subclassing

The class containing any cached properties must have the ability to handle them. In this project, the class get those abilities by subclassing `CachedClass` .

```python
class MyClass(CachedClass):
    def __init__(self, ...):
        CachedClass.__init__(self)
        # ...(normal initialization routine)...

    ...
```

This will redefine its `__setattr__()` , so if your class requires a customized `__setattr__()` routine, you must run `CachedClass.__setattr(name, value)` inside your routine.

### `cached_property` Decorator Factory

Each cached property should be decorated by a decorator which generated by `cached_property` factory. Usage shown as below:

```python
class Rectangle(CachedClass):

    def __init__(self):
        self.width: int = 10
        self.height: int = 10
    ...

    @cached_property(watched_attrs = ["width", "height:])
    def area(self) -> int:
        ...
        return self.width * self.height
```

In the example, the `area` property is calculated from, hence depends on attributes `width` and `height`. With the shown configuration, value of property area will be cached, but the cache will be discarded and re-calculated when value of `width` or `height` is changed.

### Caching Rules

This is a parameter of `cached_property` decorator factory, used to specify rules of the cache.

Caching rules can be set to either a list of property names, or one of the keywords. Effect of each configuration will be introduced below:

- **List of property names:** All attributes with name included in that list will be watched. When any of their values is changed, the cache will be flagged dirty.
- **Keyword `-all-`:** All attributes will be watched and if any of them is changed, the cache will be flagged dirty.
- **Keyword `-exposed-`:** All exposed attributes (those with name that does not starts with \`\_\`) will be watched. When any of their values is changed, the cache will be flagged dirty.

With one of these rules set, the cache will be automatically flagged dirty when value of any of the dependencies is changed, and will be discarded and re-calculated the next time getting that property.

### `on_cache_dirty` Bind

If you decide to carry out a specific routine when a cache turned dirty, override `_on_cache_dirty()` function with your own when inheriting `CachedClass`. Your function should receive a parameter in type string, containing the name of the property which has its cache turned dirty, and returns `None`.

```python
class A(CachedClass):
    ...
    def _on_cache_dirty(prop_name: str) -> None:
        print(f"Cached property {prop_name} got its cache dirty.")
```

### Destroying Cache

If a cached object is no longer needed, you may use `destroy_cache()` to free up memory space by removing all cache-relating stuff of such object.

After destroying a cached object, it is not suggested to access this object anymore, although its cached (and normal) properties will still be accessible, but all caching policies will be bypassed.

## Copyright

```
   Copyright 2026 rgzz666

   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
```

## Questions?

For code contribution, create a pull request.

For bugs and feature requests, create an issue.

For questions in usage or other discussions, use GitHub Discussions.

---

**That's all, Good luck!**

(C) 2026 rgzz666, licensed under Apache License 2.0, see [Copyright](#Copyright) section for more.
