Skip to content

ca_registry module

Global registry for cacheables.

Caching in vectorbt is achieved through a combination of decorators and the registry. Cacheable decorators such as cacheable() take a function and wrap it with another function that behaves like the wrapped function but also takes care of all caching modalities.

But unlike other implementations such as that of functools.lru_cache, the actual caching procedure doesn't happen nor are the results stored inside the decorators themselves: decorators just register a so-called "setup" for the wrapped function at the registry (see CARunSetup).

Runnable setups

The actual magic happens within a runnable setup: it takes the function that should be called and the arguments that should be passed to this function, looks whether the result should be cached, runs the function, stores the result in the cache, updates the metrics, etc. It then returns the resulting object to the wrapping function, which in turn returns it to the user. Each setup is stateful - it stores the cache, the number of hits and misses, and other metadata. Thus, there can be only one registered setup per each cacheable function globally at a time. To avoid creating new setups for the same function over and over again, each setup can be uniquely identified by its function through hashing:

>>> from vectorbtpro import *

>>> my_func = lambda: np.random.uniform(size=1000000)

>>> # Decorator returns a wrapper
>>> my_ca_func = vbt.cached(my_func)

>>> # Wrapper registers a new setup
>>> my_ca_func.get_ca_setup()
CARunSetup(registry=<vectorbtpro.registries.ca_registry.CacheableRegistry object at 0x7fe14c27df60>, use_cache=True, whitelist=False, cacheable=<function <lambda> at 0x7fe14e94cae8>, instance=None, max_size=None, ignore_args=None, cache={})

>>> # Another call won't register a new setup but return the existing one
>>> my_ca_func.get_ca_setup()
CARunSetup(registry=<vectorbtpro.registries.ca_registry.CacheableRegistry object at 0x7fe14c27df60>, use_cache=True, whitelist=False, cacheable=<function <lambda> at 0x7fe14e94cae8>, instance=None, max_size=None, ignore_args=None, cache={})

>>> # Only one CARunSetup object per wrapper and optionally the instance the wrapper is bound to
>>> hash(my_ca_func.get_ca_setup()) == hash((my_ca_func, None))
True

When we call my_ca_func, it takes the setup from the registry and calls CARunSetup.run(). The caching happens by the setup itself and isn't in any way visible to my_ca_func. To access the cache or any metric of interest, we can ask the setup:

>>> my_setup = my_ca_func.get_ca_setup()

>>> # Cache is empty
>>> my_setup.get_stats()
{
    'hash': 4792160544297109364,
    'string': '<bound func __main__.<lambda>>',
    'use_cache': True,
    'whitelist': False,
    'caching_enabled': True,
    'hits': 0,
    'misses': 0,
    'total_size': '0 Bytes',
    'total_elapsed': None,
    'total_saved': None,
    'first_run_time': None,
    'last_run_time': None,
    'first_hit_time': None,
    'last_hit_time': None,
    'creation_time': 'now',
    'last_update_time': None
}

>>> # The result is cached
>>> my_ca_func()
>>> my_setup.get_stats()
{
    'hash': 4792160544297109364,
    'string': '<bound func __main__.<lambda>>',
    'use_cache': True,
    'whitelist': False,
    'caching_enabled': True,
    'hits': 0,
    'misses': 1,
    'total_size': '8.0 MB',
    'total_elapsed': '11.33 milliseconds',
    'total_saved': '0 milliseconds',
    'first_run_time': 'now',
    'last_run_time': 'now',
    'first_hit_time': None,
    'last_hit_time': None,
    'creation_time': 'now',
    'last_update_time': None
}

>>> # The cached result is retrieved
>>> my_ca_func()
>>> my_setup.get_stats()
{
    'hash': 4792160544297109364,
    'string': '<bound func __main__.<lambda>>',
    'use_cache': True,
    'whitelist': False,
    'caching_enabled': True,
    'hits': 1,
    'misses': 1,
    'total_size': '8.0 MB',
    'total_elapsed': '11.33 milliseconds',
    'total_saved': '11.33 milliseconds',
    'first_run_time': 'now',
    'last_run_time': 'now',
    'first_hit_time': 'now',
    'last_hit_time': 'now',
    'creation_time': 'now',
    'last_update_time': None
}

Enabling/disabling caching

To enable or disable caching, we can invoke CABaseSetup.enable_caching() and CABaseSetup.disable_caching() respectively. This will set CARunSetup.use_cache flag to True or False. Even though we expressed our disire to change caching rules, the final decision also depends on the global settings and whether the setup is whitelisted in case caching is disabled globally. This decision is available via CARunSetup.caching_enabled:

>>> my_setup.disable_caching()
>>> my_setup.caching_enabled
False

>>> my_setup.enable_caching()
>>> my_setup.caching_enabled
True

>>> vbt.settings.caching['disable'] = True
>>> my_setup.caching_enabled
False

>>> my_setup.enable_caching()
UserWarning: This operation has no effect: caching is disabled globally and this setup is not whitelisted

>>> my_setup.enable_caching(force=True)
>>> my_setup.caching_enabled
True

>>> vbt.settings.caching['disable_whitelist'] = True
>>> my_setup.caching_enabled
False

>>> my_setup.enable_caching(force=True)
UserWarning: This operation has no effect: caching and whitelisting are disabled globally

To disable registration of new setups completely, use disable_machinery:

>>> vbt.settings.caching['disable_machinery'] = True

Setup hierarchy

But what if we wanted to change caching rules for an entire instance or class at once? Even if we changed the setup of every cacheable function declared in the class, how do we make sure that each future subclass or instance inherits the changes that we applied? To account for this, vectorbt provides us with a set of setups that both are stateful and can delegate various operations to their child setups, all the way down to CARunSetup. The setup hierarchy follows the inheritance hierarchy in OOP:

For example, calling B.get_ca_setup().disable_caching() would disable caching for each current and future subclass and instance of B, but it won't disable caching for A or any other superclass of B. In turn, each instance of B would then disable caching for each cacheable property and method in that instance. As we see, the propagation of this operation is happening from top to bottom.

The reason why unbound setups are stretching outside of their classes in the diagram is because there is no easy way to derive the class when calling a cacheable decorator, thus their functions are considered to be living on their own. When calling B.f.get_ca_setup().disable_caching(), we are disabling caching for the function B.f for each current and future subclass and instance of B, while all other functions remain untouched.

But what happens when we enable caching for the class B and disable caching for the unbound function B.f? Would the future method b2.f be cached or not? Quite easy: it would then inherit the state from the setup that has been updated more recently.

Here is another illustration of how operations are propagated from parents to children:

The diagram above depicts the following setup hierarchy:

>>> # Populate setups at init
>>> vbt.settings.caching.reset()
>>> vbt.settings.caching['register_lazily'] = False

>>> class A(vbt.Cacheable):
...     @vbt.cached_property
...     def f1(self): pass

>>> class B(A):
...     def f2(self): pass

>>> class C(A):
...     @vbt.cached_method
...     def f2(self): pass

>>> b1 = B()
>>> c1 = C()
>>> c2 = C()

>>> print(vbt.prettify(A.get_ca_setup().get_setup_hierarchy()))
[
    {
        "parent": "<class __main__.B>",
        "children": [
            {
                "parent": "<instance of __main__.B>",
                "children": [
                    "<instance property __main__.B.f1>"
                ]
            }
        ]
    },
    {
        "parent": "<class __main__.C>",
        "children": [
            {
                "parent": "<instance of __main__.C>",
                "children": [
                    "<instance method __main__.C.f2>",
                    "<instance property __main__.C.f1>"
                ]
            },
            {
                "parent": "<instance of __main__.C>",
                "children": [
                    "<instance method __main__.C.f2>",
                    "<instance property __main__.C.f1>"
                ]
            }
        ]
    }
]

>>> print(vbt.prettify(A.f1.get_ca_setup().get_setup_hierarchy()))
[
    "<instance property __main__.C.f1>",
    "<instance property __main__.C.f1>",
    "<instance property __main__.B.f1>"
]

>>> print(vbt.prettify(C.f2.get_ca_setup().get_setup_hierarchy()))
[
    "<instance method __main__.C.f2>",
    "<instance method __main__.C.f2>"
]

Let's disable caching for the entire A class:

>>> A.get_ca_setup().disable_caching()
>>> A.get_ca_setup().use_cache
False
>>> B.get_ca_setup().use_cache
False
>>> C.get_ca_setup().use_cache
False

This disabled caching for A, subclasses B and C, their instances, and any instance function. But it didn't touch unbound functions such as C.f1 and C.f2:

>>> C.f1.get_ca_setup().use_cache
True
>>> C.f2.get_ca_setup().use_cache
True

This is because unbound functions are not children of the classes they are declared in! Still, any future instance method of C won't be cached because it looks which parent has been updated more recently: the class or the unbound function. In our case, the class had a more recent update.

>>> c3 = C()
>>> C.f2.get_ca_setup(c3).use_cache
False

In fact, if we want to disable an entire class but leave one function untouched, we need to perform two operations in a particular order: 1) disable caching on the class and 2) enable caching on the unbound function.

>>> A.get_ca_setup().disable_caching()
>>> C.f2.get_ca_setup().enable_caching()

>>> c4 = C()
>>> C.f2.get_ca_setup(c4).use_cache
True

Getting statistics

The main advantage of having a central registry of setups is that we can easily find any setup registered in any part of vectorbt that matches some condition using CacheableRegistry.match_setups().

Note

By default, all setups are registered lazily - no setup is registered until it's run or explicitly called. To change this behavior, set register_lazily in the global settings to False.

For example, let's look which setups have been registered so far:

>>> vbt.ca_reg.match_setups(kind=None)
{
    CAClassSetup(registry=<vectorbtpro.registries.ca_registry.CacheableRegistry object at 0x7fe14c27df60>, use_cache=None, whitelist=None, cls=<class '__main__.B'>),
    CAClassSetup(registry=<vectorbtpro.registries.ca_registry.CacheableRegistry object at 0x7fe14c27df60>, use_cache=None, whitelist=None, cls=<class '__main__.C'>),
    CAInstanceSetup(registry=<vectorbtpro.registries.ca_registry.CacheableRegistry object at 0x7fe14c27df60>, use_cache=None, whitelist=None, instance=<weakref at 0x7fe14e9d83b8; to 'B' at 0x7fe14e944978>),
    CAInstanceSetup(registry=<vectorbtpro.registries.ca_registry.CacheableRegistry object at 0x7fe14c27df60>, use_cache=None, whitelist=None, instance=<weakref at 0x7fe14e9d84f8; to 'C' at 0x7fe14e9448d0>),
    CAInstanceSetup(registry=<vectorbtpro.registries.ca_registry.CacheableRegistry object at 0x7fe14c27df60>, use_cache=None, whitelist=None, instance=<weakref at 0x7fe14e9d8688; to 'C' at 0x7fe1495111d0>),
    CARunSetup(registry=<vectorbtpro.registries.ca_registry.CacheableRegistry object at 0x7fe14c27df60>, use_cache=True, whitelist=False, cacheable=<function <lambda> at 0x7fe14e94cae8>, instance=None, max_size=None, ignore_args=None, cache={}),
    CARunSetup(registry=<vectorbtpro.registries.ca_registry.CacheableRegistry object at 0x7fe14c27df60>, use_cache=True, whitelist=False, cacheable=<function C.f2 at 0x7fe13959ee18>, instance=<weakref at 0x7fe14e9d85e8; to 'C' at 0x7fe14e9448d0>, max_size=None, ignore_args=None, cache={}),
    CARunSetup(registry=<vectorbtpro.registries.ca_registry.CacheableRegistry object at 0x7fe14c27df60>, use_cache=True, whitelist=False, cacheable=<function C.f2 at 0x7fe13959ee18>, instance=<weakref at 0x7fe14e9d8728; to 'C' at 0x7fe1495111d0>, max_size=None, ignore_args=None, cache={}),
    CARunSetup(registry=<vectorbtpro.registries.ca_registry.CacheableRegistry object at 0x7fe14c27df60>, use_cache=True, whitelist=False, cacheable=<vectorbtpro.utils.decorators.cached_property object at 0x7fe118045408>, instance=<weakref at 0x7fe14e9d8458; to 'B' at 0x7fe14e944978>, max_size=None, ignore_args=None, cache={}),
    CARunSetup(registry=<vectorbtpro.registries.ca_registry.CacheableRegistry object at 0x7fe14c27df60>, use_cache=True, whitelist=False, cacheable=<vectorbtpro.utils.decorators.cached_property object at 0x7fe118045408>, instance=<weakref at 0x7fe14e9d8598; to 'C' at 0x7fe14e9448d0>, max_size=None, ignore_args=None, cache={}),
    CARunSetup(registry=<vectorbtpro.registries.ca_registry.CacheableRegistry object at 0x7fe14c27df60>, use_cache=True, whitelist=False, cacheable=<vectorbtpro.utils.decorators.cached_property object at 0x7fe118045408>, instance=<weakref at 0x7fe14e9d86d8; to 'C' at 0x7fe1495111d0>, max_size=None, ignore_args=None, cache={}),
    CAUnboundSetup(registry=<vectorbtpro.registries.ca_registry.CacheableRegistry object at 0x7fe14c27df60>, use_cache=True, whitelist=False, cacheable=<function C.f2 at 0x7fe13959ee18>),
    CAUnboundSetup(registry=<vectorbtpro.registries.ca_registry.CacheableRegistry object at 0x7fe14c27df60>, use_cache=True, whitelist=False, cacheable=<vectorbtpro.utils.decorators.cached_property object at 0x7fe118045408>)
}

Let's get the runnable setup of any property and method called f2:

>>> vbt.ca_reg.match_setups('f2', kind='runnable')
{
    CARunSetup(registry=<vectorbtpro.registries.ca_registry.CacheableRegistry object at 0x7fe14c27df60>, use_cache=True, whitelist=False, cacheable=<function C.f2 at 0x7fe13959ee18>, instance=<weakref at 0x7fe14e9d85e8; to 'C' at 0x7fe14e9448d0>, max_size=None, ignore_args=None, cache={}),
    CARunSetup(registry=<vectorbtpro.registries.ca_registry.CacheableRegistry object at 0x7fe14c27df60>, use_cache=True, whitelist=False, cacheable=<function C.f2 at 0x7fe13959ee18>, instance=<weakref at 0x7fe14e9d8728; to 'C' at 0x7fe1495111d0>, max_size=None, ignore_args=None, cache={})
}

But there is a better way to get the stats: CASetupDelegatorMixin.get_stats(). It returns a DataFrame with setup stats as rows:

>>> vbt.CAQueryDelegator('f2', kind='runnable').get_stats()
                                               string  use_cache  whitelist  \
hash
 3506416602224216137  <instance method __main__.C.f2>       True      False
-4747092115268118855  <instance method __main__.C.f2>       True      False
-4748466030718995055  <instance method __main__.C.f2>       True      False

                      caching_enabled  hits  misses total_size total_elapsed  \
hash
 3506416602224216137             True     0       0    0 Bytes          None
-4747092115268118855             True     0       0    0 Bytes          None
-4748466030718995055             True     0       0    0 Bytes          None

                     total_saved first_run_time last_run_time first_hit_time  \
hash
 3506416602224216137        None           None          None           None
-4747092115268118855        None           None          None           None
-4748466030718995055        None           None          None           None

                     last_hit_time  creation_time last_update_time
hash
 3506416602224216137          None  9 minutes ago    9 minutes ago
-4747092115268118855          None  9 minutes ago    9 minutes ago
-4748466030718995055          None  9 minutes ago    9 minutes ago

Clearing up

Instance and runnable setups hold only weak references to their instances such that deleting those instances won't keep them in memory and will automatically remove the setups.

To clear all caches:

>>> vbt.CAQueryDelegator().clear_cache()

Resetting

To reset global caching flags:

>>> vbt.settings.caching.reset()

To remove all setups:

>>> vbt.CAQueryDelegator(kind=None).deregister()

ca_reg CacheableRegistry

Default registry of type CacheableRegistry.

clear_cache function

clear_cache(
    *args,
    **kwargs
)

Clear cache globally or of an object.

collect_garbage function

collect_garbage()

Collect garbage.

disable_caching function

disable_caching(
    clear_cache=True
)

Disable caching globally.

enable_caching function

enable_caching()

Enable caching globally.

flush function

flush()

Clear cache and collect garbage.

get_cache_stats function

get_cache_stats(
    *args,
    **kwargs
)

Get cache stats globally or of an object.

get_obj_id function

get_obj_id(
    instance
)

Get id of an instance.

is_bindable_cacheable function

is_bindable_cacheable(
    cacheable
)

Check if cacheable is a cacheable that can be bound to an instance.

is_cacheable function

is_cacheable(
    cacheable
)

Check if cacheable is a cacheable.

is_cacheable_function function

is_cacheable_function(
    cacheable
)

Check if cacheable is a cacheable function.

is_cacheable_method function

is_cacheable_method(
    cacheable
)

Check if cacheable is a cacheable method.

is_cacheable_property function

is_cacheable_property(
    cacheable
)

Check if cacheable is a cacheable property.

print_cache_stats function

print_cache_stats(
    *args,
    **kwargs
)

Print cache stats globally or of an object.

with_caching_disabled function

with_caching_disabled(
    *args,
    **caching_disabled_kwargs
)

Decorator to run a function with CachingDisabled.

with_caching_enabled function

with_caching_enabled(
    *args,
    **caching_enabled_kwargs
)

Decorator to run a function with CachingEnabled.

CABaseDelegatorSetup class

CABaseDelegatorSetup(
    *args,
    **kwargs
)

Base class acting as a stateful setup that delegates cache management to child setups.

First delegates the work and only then changes its own state.

Superclasses

Inherited members

Subclasses

child_setups property

Get child setups that match CABaseDelegatorSetup.query.

CABaseSetup class

CABaseSetup(
    *args,
    **kwargs
)

Base class that exposes properties and methods for cache management.

Superclasses

Inherited members

Subclasses

activate method

CABaseSetup.activate()

Activate.

active class variable

Whether to register and/or return setup when requested.

caching_enabled property

Whether caching is enabled in this setup.

Caching is disabled when any of the following apply:

Returns None if CABaseSetup.use_cache or CABaseSetup.whitelist is None.

clear_cache method

CABaseSetup.clear_cache()

Clear the cache.

creation_time property

Time when this setup was created.

deactivate method

CABaseSetup.deactivate()

Deactivate.

deregister method

CABaseSetup.deregister()

Register setup using CacheableRegistry.deregister_setup().

disable_caching method

CABaseSetup.disable_caching(
    clear_cache=True
)

Disable caching.

Set clear_cache() to True to also clear the cache.

disable_whitelist method

CABaseSetup.disable_whitelist()

Disable whitelisting.

enable_caching method

CABaseSetup.enable_caching(
    force=False,
    silence_warnings=None
)

Enable caching.

Set force to True to whitelist this setup.

enable_whitelist method

CABaseSetup.enable_whitelist()

Enable whitelisting.

enforce_rules method

CABaseSetup.enforce_rules()

Enforce registry rules.

get_stats method

CABaseSetup.get_stats(
    readable=True,
    short_str=False
)

Get stats of the setup as a dict with metrics.

last_update_time property

Last time any of CABaseSetup.use_cache and CABaseSetup.whitelist were updated.

position_among_similar property

Get position among all similar setups.

Ordered by creation time.

query property

Query to match this setup.

readable_name property

Get a readable name of the object the setup is bound to.

readable_str property

Convert this setup into a readable string.

register method

CABaseSetup.register()

Register setup using CacheableRegistry.register_setup().

registered property

Return whether setup is registered.

registry class variable

Registry of type CacheableRegistry.

same_type_setups property

short_str property

Convert this setup into a short string.

use_cache class variable

Whether caching is enabled.

use_cache_lut property

Last time CABaseSetup.use_cache was updated.

whitelist class variable

Whether to cache even if caching was disabled globally.

whitelist_lut property

Last time CABaseSetup.whitelist was updated.

CAClassSetup class

CAClassSetup(
    *args,
    **kwargs
)

Class that represents a setup of a cacheable class.

The provided class must subclass Cacheable.

Delegates cache management to its child subclass setups of type CAClassSetup and child instance setups of type CAInstanceSetup.

If use_cash or whitelist are None, inherits a non-empty value from its superclass setups using the method resolution order (MRO).

Note

Unbound setups are not children of class setups. See notes on CAUnboundSetup.

Superclasses

Inherited members

any_use_cache_lut property

Last time CABaseSetup.use_cache was updated in this class or any of its superclasses.

any_whitelist_lut property

Last time CABaseSetup.whitelist was updated in this class or any of its superclasses.

cls class variable

Cacheable class.

get class method

CAClassSetup.get(
    cls_,
    registry=<vectorbtpro.registries.ca_registry.CacheableRegistry object>,
    **kwargs
)

Get setup from CacheableRegistry or register a new one.

**kwargs are passed to CAClassSetup.

get_cacheable_subclasses static method

CAClassSetup.get_cacheable_subclasses(
    cls
)

Get an ordered list of the cacheable subclasses of a class.

get_cacheable_superclasses static method

CAClassSetup.get_cacheable_superclasses(
    cls
)

Get an ordered list of the cacheable superclasses of a class.

get_subclass_setups static method

CAClassSetup.get_subclass_setups(
    registry,
    cls
)

Setups of type CAClassSetup of each in CAClassSetup.get_cacheable_subclasses().

get_superclass_setups static method

CAClassSetup.get_superclass_setups(
    registry,
    cls
)

Setups of type CAClassSetup of each in CAClassSetup.get_cacheable_superclasses().

get_unbound_cacheables static method

CAClassSetup.get_unbound_cacheables(
    cls
)

Get a set of the unbound cacheables of a class.

get_unbound_setups static method

CAClassSetup.get_unbound_setups(
    registry,
    cls
)

Setups of type CAUnboundSetup of each in CAClassSetup.get_unbound_cacheables().

instance_setups property

Setups of type CAInstanceSetup of instances of the class.

same_type_setups property

subclass_setups property

See CAClassSetup.get_subclass_setups().

superclass_setups property

See CAClassSetup.get_superclass_setups().

unbound_setups property

See CAClassSetup.get_unbound_setups().

CAInstanceSetup class

CAInstanceSetup(
    *args,
    **kwargs
)

Class that represents a setup of an instance that has cacheables bound to it.

The provided instance must be of Cacheable.

Delegates cache management to its child setups of type CARunSetup.

If use_cash or whitelist are None, inherits a non-empty value from its parent class setup.

Superclasses

Inherited members

class_setup property

Setup of type CAClassSetup of the cacheable class of the instance.

contains_garbage property

Whether instance was destroyed.

get class method

CAInstanceSetup.get(
    instance,
    registry=<vectorbtpro.registries.ca_registry.CacheableRegistry object>,
    **kwargs
)

Get setup from CacheableRegistry or register a new one.

**kwargs are passed to CAInstanceSetup.

instance class variable

Cacheable instance.

instance_obj property

Instance object.

run_setups property

Setups of type CARunSetup of cacheables bound to the instance.

same_type_setups property

unbound_setups property

Setups of type CAUnboundSetup of unbound cacheables declared in the class of the instance.

CAMetrics class

CAMetrics()

Abstract class that exposes various metrics related to caching.

Subclasses

first_hit_time property

Time of the first hit.

first_run_time property

Time of the first run.

hits property

Number of hits.

last_hit_time property

Time of the last hit.

last_run_time property

Time of the last run.

metrics property

Dict with all metrics.

misses property

Number of misses.

total_elapsed property

Total number of seconds elapsed during running the function.

total_saved property

Total number of seconds saved by using the cache.

total_size property

Total size of cached objects.

CAQuery class

CAQuery(
    *args,
    **kwargs
)

Data class that represents a query for matching and ranking setups.

Superclasses

Inherited members

base_cls class variable

Base class of the instance or its name (case-sensitive) CAQuery.cacheable is bound to.

cacheable class variable

Cacheable object or its name (case-sensitive).

cls class variable

Class of the instance or its name (case-sensitive) CAQuery.cacheable is bound to.

instance class variable

Weak reference to the instance CAQuery.cacheable is bound to.

instance_obj property

Instance object.

matches_setup method

CAQuery.matches_setup(
    setup
)

Return whether the setup matches this query.

Usage

Let's evaluate various queries:

>>> class A(vbt.Cacheable):
...     @vbt.cached_method(my_option=True)
...     def f(self):
...         return None

>>> class B(A):
...     pass

>>> @vbt.cached(my_option=False)
... def f():
...     return None

>>> a = A()
>>> b = B()

>>> def match_query(query):
...     matched = []
...     if query.matches_setup(A.f.get_ca_setup()):  # unbound method
...         matched.append('A.f')
...     if query.matches_setup(A.get_ca_setup()):  # class
...         matched.append('A')
...     if query.matches_setup(a.get_ca_setup()):  # instance
...         matched.append('a')
...     if query.matches_setup(A.f.get_ca_setup(a)):  # instance method
...         matched.append('a.f')
...     if query.matches_setup(B.f.get_ca_setup()):  # unbound method
...         matched.append('B.f')
...     if query.matches_setup(B.get_ca_setup()):  # class
...         matched.append('B')
...     if query.matches_setup(b.get_ca_setup()):  # instance
...         matched.append('b')
...     if query.matches_setup(B.f.get_ca_setup(b)):  # instance method
...         matched.append('b.f')
...     if query.matches_setup(f.get_ca_setup()):  # function
...         matched.append('f')
...     return matched

>>> match_query(vbt.CAQuery())
['A.f', 'A', 'a', 'a.f', 'B.f', 'B', 'b', 'b.f', 'f']
>>> match_query(vbt.CAQuery(cacheable=A.f))
['A.f', 'a.f', 'B.f', 'b.f']
>>> match_query(vbt.CAQuery(cacheable=B.f))
['A.f', 'a.f', 'B.f', 'b.f']
>>> match_query(vbt.CAQuery(cls=A))
['A', 'a', 'a.f']
>>> match_query(vbt.CAQuery(cls=B))
['B', 'b', 'b.f']
>>> match_query(vbt.CAQuery(cls=vbt.Regex('[A-B]')))
['A', 'a', 'a.f', 'B', 'b', 'b.f']
>>> match_query(vbt.CAQuery(base_cls=A))
['A', 'a', 'a.f', 'B', 'b', 'b.f']
>>> match_query(vbt.CAQuery(base_cls=B))
['B', 'b', 'b.f']
>>> match_query(vbt.CAQuery(instance=a))
['a', 'a.f']
>>> match_query(vbt.CAQuery(instance=b))
['b', 'b.f']
>>> match_query(vbt.CAQuery(instance=a, cacheable='f'))
['a.f']
>>> match_query(vbt.CAQuery(instance=b, cacheable='f'))
['b.f']
>>> match_query(vbt.CAQuery(options=dict(my_option=True)))
['A.f', 'a.f', 'B.f', 'b.f']
>>> match_query(vbt.CAQuery(options=dict(my_option=False)))
['f']

options class variable

Options to match.

parse class method

CAQuery.parse(
    query_like,
    use_base_cls=True
)

Parse a query-like object.

Note

Not all attribute combinations can be safely parsed by this function. For example, you cannot combine cacheable together with options.

Usage

>>> vbt.CAQuery.parse(lambda x: x)
CAQuery(cacheable=<function <lambda> at 0x7fd4766c7730>, instance=None, cls=None, base_cls=None, options=None)

>>> vbt.CAQuery.parse("a")
CAQuery(cacheable='a', instance=None, cls=None, base_cls=None, options=None)

>>> vbt.CAQuery.parse("A.a")
CAQuery(cacheable='a', instance=None, cls=None, base_cls='A', options=None)

>>> vbt.CAQuery.parse("A")
CAQuery(cacheable=None, instance=None, cls=None, base_cls='A', options=None)

>>> vbt.CAQuery.parse("A", use_base_cls=False)
CAQuery(cacheable=None, instance=None, cls='A', base_cls=None, options=None)

>>> vbt.CAQuery.parse(vbt.Regex("[A-B]"))
CAQuery(cacheable=None, instance=None, cls=None, base_cls=Regex(pattern='[A-B]', flags=0), options=None)

>>> vbt.CAQuery.parse(dict(my_option=100))
CAQuery(cacheable=None, instance=None, cls=None, base_cls=None, options={'my_option': 100})

CAQueryDelegator class

CAQueryDelegator(
    *args,
    registry=<vectorbtpro.registries.ca_registry.CacheableRegistry object>,
    collapse=True,
    **kwargs
)

Class that delegates any setups that match a query.

*args, collapse, and **kwargs are passed to CacheableRegistry.match_setups().

Superclasses

Inherited members

args property

Arguments.

child_setups property

Get child setups by matching them using CacheableRegistry.match_setups().

kwargs property

Keyword arguments.

registry property

Registry of type CacheableRegistry.

CARule class

CARule(
    *args,
    **kwargs
)

Data class that represents a rule that should be enforced on setups that match a query.

Superclasses

Inherited members

enforce method

CARule.enforce(
    setup
)

Run CARule.enforce_func on the setup if it has been matched.

enforce_func class variable

Function to run on the setup if it has been matched.

exclude class variable

One or multiple setups to exclude.

filter_func class variable

Function to filter out a setup.

kind class variable

Kind of a setup to match.

matches_setup method

CARule.matches_setup(
    setup
)

Return whether the setup matches the rule.

query class variable

CAQuery used in matching.

CARunResult class

CARunResult(
    *args,
    **kwargs
)

Class that represents a cached result of a run.

Note

Hashed solely by the hash of the arguments args_hash.

Superclasses

Inherited members

args_hash class variable

Hash of the arguments.

first_hit_time property

Time of the first hit.

hit method

CARunResult.hit()

Hit the result.

hits property

last_hit_time property

Time of the last hit.

result class variable

Result of the run.

result_size property

Get size of the result in memory.

run_time property

Time of the run.

timer class variable

Timer used to measure the execution time.

CARunSetup class

CARunSetup(
    *args,
    **kwargs
)

Class that represents a runnable cacheable setup.

Takes care of running functions and caching the results using CARunSetup.run().

Accepts as cacheable either cacheable_property, cacheable_method(), or cacheable().

Hashed by the callable and optionally the id of the instance its bound to. This way, it can be uniquely identified among all setups.

Note

Cacheable properties and methods must provide an instance.

Only one instance per each unique combination of cacheable and instance can exist at a time.

If use_cash or whitelist are None, inherits a non-empty value either from its parent instance setup or its parent unbound setup. If both setups have non-empty values, takes the one that has been updated more recently.

Note

Use CARunSetup.get() class method instead of CARunSetup to create a setup. The class method first checks whether a setup with the same hash has already been registered, and if so, returns it. Otherwise, creates and registers a new one. Using CARunSetup will throw an error if there is a setup with the same hash.

Superclasses

Inherited members

cache class variable

Dict of cached CARunResult instances by their hash.

cacheable class variable

Cacheable object.

contains_garbage property

Whether instance was destroyed.

get class method

CARunSetup.get(
    cacheable,
    instance=None,
    registry=<vectorbtpro.registries.ca_registry.CacheableRegistry object>,
    **kwargs
)

Get setup from CacheableRegistry or register a new one.

**kwargs are passed to CARunSetup.

get_args_hash method

CARunSetup.get_args_hash(
    *args,
    **kwargs
)

Get the hash of the passed arguments.

CARunSetup.ignore_args gets extended with ignore_args under caching.

If no arguments were passed, hashes None.

ignore_args class variable

Arguments to ignore when hashing.

instance class variable

Cacheable instance.

instance_obj property

Instance object.

instance_setup property

Setup of type CAInstanceSetup of the instance this cacheable is bound to.

max_size class variable

Maximum number of entries in CARunSetup.cache.

run method

CARunSetup.run(
    *args,
    **kwargs
)

Run the setup and cache it depending on a range of conditions.

Runs CARunSetup.run_func() if caching is disabled or arguments are not hashable, and CARunSetup.run_func_and_cache() otherwise.

run_func method

CARunSetup.run_func(
    *args,
    **kwargs
)

Run the setup's function without caching.

run_func_and_cache method

CARunSetup.run_func_and_cache(
    *args,
    **kwargs
)

Run the setup's function and cache the result.

Hashes the arguments using CARunSetup.get_args_hash(), runs the function using CARunSetup.run_func(), wraps the result using CARunResult, and uses the hash as a key to store the instance of CARunResult into CARunSetup.cache for later retrieval.

same_type_setups property

unbound_setup property

Setup of type CAUnboundSetup of the unbound cacheable.

CASetupDelegatorMixin class

CASetupDelegatorMixin()

Mixin class that delegates cache management to child setups.

Superclasses

Inherited members

Subclasses

child_setups property

Child setups.

clear_cache method

CASetupDelegatorMixin.clear_cache(
    **kwargs
)

Calls CABaseSetup.clear_cache() on each child setup.

delegate method

CASetupDelegatorMixin.delegate(
    func,
    exclude=None,
    **kwargs
)

Delegate a function to all child setups.

func must take the setup and return nothing. If the setup is an instance of CASetupDelegatorMixin, it must additionally accept exclude.

deregister method

CASetupDelegatorMixin.deregister(
    **kwargs
)

Calls CABaseSetup.deregister() on each child setup.

disable_caching method

CASetupDelegatorMixin.disable_caching(
    **kwargs
)

Calls CABaseSetup.disable_caching() on each child setup.

disable_whitelist method

CASetupDelegatorMixin.disable_whitelist(
    **kwargs
)

Calls CABaseSetup.disable_whitelist() on each child setup.

enable_caching method

CASetupDelegatorMixin.enable_caching(
    **kwargs
)

Calls CABaseSetup.enable_caching() on each child setup.

enable_whitelist method

CASetupDelegatorMixin.enable_whitelist(
    **kwargs
)

Calls CABaseSetup.enable_whitelist() on each child setup.

get_setup_hierarchy method

CASetupDelegatorMixin.get_setup_hierarchy(
    readable=True,
    short_str=False
)

Get the setup hierarchy by recursively traversing the child setups.

get_stats method

CASetupDelegatorMixin.get_stats(
    readable=True,
    short_str=False,
    index_by_hash=False,
    filter_func=None,
    include=None,
    exclude=None
)

Get a DataFrame out of stats dicts of child setups.

CAUnboundSetup class

CAUnboundSetup(
    *args,
    **kwargs
)

Class that represents a setup of an unbound cacheable property or method.

An unbound callable is a callable that was declared in a class but is not bound to any instance (just yet).

Note

Unbound callables are just regular functions - they have no parent setups. Even though they are formally declared in a class, there is no easy way to get a reference to the class from the decorator itself. Thus, searching for child setups of a specific class won't return unbound setups.

Delegates cache management to its child setups of type CARunSetup. One unbound cacheable property or method can be bound to multiple instances, thus there is one-to-many relationship between CAUnboundSetup and CARunSetup instances.

Hint

Use class attributes instead of instance attributes to access unbound callables.

Superclasses

Inherited members

cacheable class variable

Cacheable object.

get class method

CAUnboundSetup.get(
    cacheable,
    registry=<vectorbtpro.registries.ca_registry.CacheableRegistry object>,
    **kwargs
)

Get setup from CacheableRegistry or register a new one.

**kwargs are passed to CAUnboundSetup.

run_setups property

Setups of type CARunSetup of bound cacheables.

same_type_setups property

CacheableRegistry class

CacheableRegistry()

Class for registering setups of cacheables.

class_setups property

Dict of registered CAClassSetup instances by their hash.

deregister_rule method

CacheableRegistry.deregister_rule(
    rule
)

Deregister a rule of type CARule.

deregister_setup method

CacheableRegistry.deregister_setup(
    setup
)

Deregister a new setup of type CABaseSetup.

Removes the setup from its respective collection.

To also deregister its children, call the CASetupDelegatorMixin.deregister() method.

get_class_setup method

CacheableRegistry.get_class_setup(
    cls
)

Get a setup of type CAInstanceSetup with this class or return None.

get_instance_setup method

CacheableRegistry.get_instance_setup(
    instance
)

Get a setup of type CAInstanceSetup with this instance or return None.

get_run_setup method

CacheableRegistry.get_run_setup(
    cacheable,
    instance=None
)

Get a setup of type CARunSetup with this cacheable and instance, or return None.

get_setup_by_hash method

CacheableRegistry.get_setup_by_hash(
    hash_
)

Get the setup by its hash.

get_unbound_setup method

CacheableRegistry.get_unbound_setup(
    cacheable
)

Get a setup of type CAUnboundSetup with this cacheable or return None.

instance_setups property

Dict of registered CAInstanceSetup instances by their hash.

match_setups method

CacheableRegistry.match_setups(
    query_like=None,
    collapse=False,
    kind=None,
    exclude=None,
    exclude_children=True,
    filter_func=None
)

Match all setups registered in this registry against query_like.

query_like can be one or more query-like objects that will be parsed using CAQuery.parse().

Set collapse to True to remove child setups that belong to any matched parent setup.

kind can be one or multiple of the following:

  • 'class' to only return class setups (instances of CAClassSetup)
  • 'instance' to only return instance setups (instances of CAInstanceSetup)
  • 'unbound' to only return unbound setups (instances of CAUnboundSetup)
  • 'runnable' to only return runnable setups (instances of CARunSetup)

Set exclude to one or multiple setups to exclude. To not exclude their children, set exclude_children to False.

Note

exclude_children is applied only when collapse is True.

filter_func can be used to filter out setups. For example, lambda setup: setup.caching_enabled includes only those setups that have caching enabled. It must take a setup and return a boolean of whether to include this setup in the final results.

register_rule method

CacheableRegistry.register_rule(
    rule
)

Register a new rule of type CARule.

register_setup method

CacheableRegistry.register_setup(
    setup
)

Register a new setup of type CABaseSetup.

rules property

List of registered CARule instances.

run_setups property

Dict of registered CARunSetup instances by their hash.

setup_registered method

CacheableRegistry.setup_registered(
    setup
)

Return whether the setup is registered.

setups property

Dict of registered CABaseSetup instances by their hash.

unbound_setups property

Dict of registered CAUnboundSetup instances by their hash.

CachingDisabled class

CachingDisabled(
    query_like=None,
    use_base_cls=True,
    kind=None,
    exclude=None,
    filter_func=None,
    registry=<vectorbtpro.registries.ca_registry.CacheableRegistry object>,
    disable_whitelist=True,
    disable_machinery=True,
    clear_cache=True,
    silence_warnings=False
)

Context manager to disable caching.

clear_cache property

Whether to clear global cache when entering or local cache when disabling caching.

disable_machinery property

Whether to disable machinery.

disable_whitelist property

Whether to disable whitelist.

exclude property

See CARule.exclude.

filter_func property

See CARule.filter_func.

init_settings property

Initial caching settings.

init_setup_settings property

Initial setup settings.

kind property

See CARule.kind.

query_like property

See CAQuery.parse().

registry property

Registry of type CacheableRegistry.

rule property

Rule.

silence_warnings property

Whether to silence warnings.

use_base_cls property

See CAQuery.parse().

CachingEnabled class

CachingEnabled(
    query_like=None,
    use_base_cls=True,
    kind=None,
    exclude=None,
    filter_func=None,
    registry=<vectorbtpro.registries.ca_registry.CacheableRegistry object>,
    enable_whitelist=True,
    enable_machinery=True,
    clear_cache=True,
    silence_warnings=False
)

Context manager to enable caching.

clear_cache property

Whether to clear global cache when exiting or local cache when disabling caching.

enable_machinery property

Whether to enable machinery.

enable_whitelist property

Whether to enable whitelist.

exclude property

See CARule.exclude.

filter_func property

See CARule.filter_func.

init_settings property

Initial caching settings.

init_setup_settings property

Initial setup settings.

kind property

See CARule.kind.

query_like property

See CAQuery.parse().

registry property

Registry of type CacheableRegistry.

rule property

Rule.

silence_warnings property

Whether to silence warnings.

use_base_cls property

See CAQuery.parse().