Reactive Caching

2026 by rgzz666

Latest: v0.2.2 (Beta)

GitHub | PyPI

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.

pip3 install reactive_caching

Usage

Import the module

To use the module, you must import it with:

import reactive_caching

or if you prefer to directly use the contents:

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 .

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:

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.

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.

For Any Undocumented Details

I apologize for the incompleteness of the document. Please consider the following solutions:

1. Check later versions of the document, some details might be added to the document in later versions.
2. Create an issue and ask me. This can remind me to add the details you asked to this document, and help completing the document.

That's all, Good luck!

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