musif.cache package

This package implements utilities to cache and speed-up the extraction of features.

Submodules

musif.cache.cache module

class musif.cache.cache.CallableArguments(*args, **kwargs)

Bases: object

This class represents a set of ordered arguments. The hash is the concatenation of the argument hashes. If the arguments are SmartModuleCache objects, this object uses their cache (which persists to disk), otherwise it uses deepdiff.DeepHash to compute a hash based on the content value (which should persists across pickling).

Note that DeepHash may be much slower than the builtin hash() function, so for large and complex objects like music21.Score, just use a SmartModuleCache wrapper.

class musif.cache.cache.MethodCache(reference: ObjectReference, attr_name: str, target_addresses: List[str] = ['music21'], special_method: bool = False, check_reference_changes: bool = False)

Bases: object

A simple wrapper that checks if the arguments are in the cache, otherwise runs the method and caches the arguments

cache

check_reference_changes

name

reference

special_method

target_addresses

class musif.cache.cache.ObjectReference(reference: Any, resurrect_reference: Tuple | None, parent=None, name: str = '', args: Tuple | None = None)

Bases: object

This handles the calls to the reference object so that both MethodCache and SmartModuleCache reference the same object and when one resurrects it, the other sees it.

args

name

parent

reference

resurrect_reference

class musif.cache.cache.SmartModuleCache(reference: Any | None = None, resurrect_reference: Tuple | None = None, parent: ObjectReference | None = None, name: Tuple[str] = ('',), args: Tuple[Tuple | None] = (None,), target_addresses: List[str] = ['music21'], check_reference_changes: bool = False)

Bases: object

This class wraps any object so that its function calls can be cached in a dict, very similarly to how functools.lru_cache works.

The object keeps a dictionary and a reference to the wrapped object. Each time a method, a field, or a property is called, it stores the result value in the dictionary. When the same call is performed a second time, the result value is taken from the dictionary.

If the object is changed, the change is not cached. As such, only read operations can be executed on a SmartModuleCache.

After unpickling, the referenced object is no longer available. If resurrect_reference is not None, it will be loaded using its value. In such a case, resurrect_reference should be a tuple with a function in the first position and the arguments later; the function returned value must be the reference object.

If the method/property/field returns an object defined in a one of the target_addresses, this class will return a wrapped version of that object. In musif, this is used to wrap all the music21 objects and to cache (most of) music21 operations.

When a method is called, it is matched with all the arguments, similarly to functools.lru_cache, thus using the hash value of the objects.

When pickled, this object only pickles the cache dictionary. The matching of the arguments in a method works on a custom hash value that is guaranteed to be the same when the object is pickled/unpickled. As consequence, as long as the method arguments are SmartModuleCache objects, they will re-use the cache after pickling/unpickling.

Sometimes, the methods of the referenced object expect a non-cached module, for instance when a type checking or a hash comparison is done. For those situations, SmartModuleCache provides special methods that start with SmartModuleCache.SPECIAL_METHODS_NAME (which defaults to “smartcache__”). It is possible call any method with smartcache__methodname, e.g. score.smartcache__remove. When a special method is called, the first call is performed with the non-cached arguments, as it would happen without SmartModuleCache.

NotImplemented: When smart_pickling is True, it pickles the dictionary alone, without the reference, otherwise, it pickles the reference as well.

Note: this class implements __repr__ in a custom way, while proxies the __str__ method to the referenced object.

Note: In future, deepdiff.Delta could be used to allow in-place operations, but it needs that:

1. the object modified are pickable

2. the reference are deep-copiable (for some reason, music21 objects)

   sometimes exceed the maximum number of recursion while deep-copying

SPECIAL_METHODS_NAME = 'smartcache__'

cache

ischanged()

Returns if the reference object is changed using value comparison of its attributes recursively.

smartforcecache(name, *args, **kwargs)

This method can be used to forcedly cache some attribute of the reference object without using it. name is the name of the attribute. If it is a method, *args and **kwargs.

Return (True, None) if object is cached, (False, Exception) otherwise

musif.cache.utils module

class musif.cache.utils.FileCacheIntoRAM(capacity: int)

Bases: object

This class simply stores a dictionary of key-value. In musif, it is used to cache the objects (values) coming from the parsing of files (whose names are the keys). It is never written to disk and only kept into RAM.

musif.cache.utils.hasattr(obj1, attr)

Check if obj1 has attr. This function grants that SmartModuleCache objects are checked against their cache or reference objects.

musif.cache.utils.iscache(obj1)

Check if obj1 is a SmartModuleCache or a MethodCache object

musif.cache.utils.isinstance(obj1, cls)

Check if obj1 is instance of cls. This function grants that SmartModuleCache objects are checked against their reference objects.

musif.cache.utils.load_score_df(fname)

Loads a score object saved with store_score_df from a string or Path pointing to the file or from a file-like object. Return a dictionary of dataframes

musif.cache.utils.store_score_df(score, fname)

Stores score into fname (a file-like object, a string or a Path object) using dataframes and returns the object saved.

The returned object is a dictionary with keys the name of the parts and values dataframes with the following columns:

• “Type”: A string identifying the type of object. Possible values: "Note",

  "Rest", "Measure", "Time Signature"

• “Name”: A string with the name of the note in Common Western Notation or with

  the time signature string for time signatures; for measures and rests, the value "-" is used.

• “Value”: The midi pitch for notes, -1 for others

• “Measure Onset”: The beat position of the object in reference to the beginning

  of the measure, -1 for measures

• “Part Onset”: The onset position of the object in reference to the beginning

  of the part

• “Duration”: The duration of the object, -1 for time signatures

• “Tie”: If a tie is applied to the note, its type is there (one of "start",

  "continue", "stop"), otherwise "-" is used

musif.cache.utils.wrap_module_objects(obj: Any, target_addresses: List[str] = ['music21'], resurrect_reference: Tuple | None = None, parent: ObjectReference | None = None, name: Tuple[str] = ('',), args: Tuple[Tuple | None] = (None,))

Returns the object wrapped with SmartModuleCache class if it was defined in one of the target_addresses

If obj is a list or a tuple, e new list/tuple this function works recursively on their objects.

If the object is an instance of weakref.ReferenceType this function converts the object to a regular reference and then applies the wrapping.