Metadata-Version: 2.4
Name: reactive_caching
Version: 0.1.0
Summary: Provides caching for class properties.
Author-email: rgzz666 <tt1224@hotmail.com>
License-Expression: Apache-2.0
Project-URL: Repository, https://github.com/totowang-hhh/properties_caching.git
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
>
> v0.1.0

```bash
pip3 install reactive_caching
```

**Reactive Caching is a Python module providing the ability to cache properties of a class, and automatically invalidate them on specified rules of changes in attributes.** This can avoid calculating the property everytime when calling it and keeping the data up to date.

## 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
```

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):
    ...
```

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 MyClass(CachedClass):
    ...
    @MyClass.cached_property(watched_attrs = "-all-")
    def a_property_that_is_calced_with_all_attributes(self) -> int:
        ...
        return 1
```

### 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.

### `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.

## 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.
