music21.common.decorators

Functions

music21.common.decorators.cacheMethod(method)

A decorator for music21Objects or other objects that assumes that there is a ._cache Dictionary in the instance and returns or sets that value if it exists, otherwise calls the method and stores the value.

To be used ONLY with zero-arg calls. Like properties. Well, can be used by others but will not store per-value caches.

Not a generic memorize, because by storing in one ._cache place, a .clearCache() method can eliminate them.

Uses the name of the function as the cache key.

New in v.6 – helps to make all the caches easier to work with.

music21.common.decorators.deprecated(method, startDate=None, removeDate=None, message=None)

Decorator that marks a function as deprecated and should not be called.

Because we’re all developers, it does not use DeprecationWarning, which no one would ever see, but UserWarning.

Warns once per session and never again.

Use without arguments for a simple case:

For demonstrating I need to screw with stderr…

>>> import sys
>>> saveStdErr = sys.stderr
>>> sys.stderr = sys.stdout

>>> @common.deprecated
... def hi(msg):
...     print(msg)

(I’m printing “/” at the beginning because message begins with the filename and that is different on each system, but you can’t use ellipses at the beginning of a doctest)

>>> print('/'); hi('myke')
/...Music21DeprecationWarning: hi was deprecated
        and will disappear soon. Find alternative methods.
...
 myke

A second call raises no warning:

>>> hi('myke')
myke

Now a new function demonstrating the argument form.

>>> @common.deprecated('February 1972', 'September 2099', 'You should be okay...')
... def bye(msg):
...     print(msg)

>>> print('/'); bye('world')
/...Music21DeprecationWarning: bye was deprecated on February 1972
        and will disappear at or after September 2099. You should be okay...
...
world

Restore stderr at the end.

>>> sys.stderr = saveStdErr

music21.common.decorators.optional_arg_decorator(fn)

a decorator for decorators. Allows them to either have or not have arguments.