Python decorators transform how functions work.

@this_is_a_decorator
def some_function():
    return something

"""
>>> some_function()
Something else!
"""

Between the core language and the standard library, there are several decorators that come with Python. Also, many popular frameworks provide decorators to help eliminate boilerplate and make building applications faster and easier.

Decorators are easier to use than to understand.

This article will try to help you understand how decorators work and how to write them. To do that, we'll write a basic implementation of a dispatch function, which will conditionally call function implementations based on the value of an argument.

A Problem in Need of Decorators¶

How often have you written code that looks something like this?

def if_chain_function(status):
    if status == "red":
        # large block of code
    elif status == "orange":
        # large block of code
    elif status == "yellow":
        # large block of code
    else:
        # some default large block of code

Most of us have written some version of that more than we'd like to admit. Some languages even have a special mechanism (usually called switch) for doing it.

But it has problems.

As the number of cases increases, it becomes hard to read.
The code blocks in each case will likely evolve independently, some getting refactored into clean functions, some not, and some being a mix of inline code and custom function calls.
New cases have to be added explicitly in this function. This precludes pluggable cases from external modules, and also just adds mental load.
If the cases are anything other than simple comparisons, the whole thing quickly becomes difficult to reason about.

To solve these problems, making the code more readable and easier to extend, we're going to look at function dispatching.

A little bit about function dispatching¶

Conventionally, function dispatching is related to the type of the argument. That is, function dispatching is a mechanism for doing different things, depending on whether you pass in an int or a str or a list or whatever.

Python is dynamically typed, so you don't have to specify that a function only accepts some specific type as an argument. But if those different types have to be handled differently, you might end up with code that looks eerily similar to the code above.

def depends_on_type(x):
    if type(x) == str:
        # large block of code
    else if type(x) == int:
        # large block of code
    else if type(x) == list:
        # large block of code
    else:
        # some default large block of code

This has all the same problems mentioned above. But, unlike the first example, Python has a solution to this already:
@functools.singledispatch.

This is a decorator which transforms a function into a single-dispatch generic function. You then register other functions against it, specifying a type of object (that is, a class name). When the function is called, it:

looks up the type of the first argument
checks its registry for that type
executes the function registered for that type
if the type wasn't registered, the original function is executed

If this sounds complicated, don't worry. Using singledispatch is simpler than explaining it.

import functools

@functools.singledispatch
def dispatch_on_type(x):
    # some default logic
    print("I am the default implementation.")
    
@dispatch_on_type.register(str)
def _(x):
    # some stringy logic
    print(f"'{x}' is a string.")
    
@dispatch_on_type.register(int)
def _(x):
    # some integer logic
    print(f"{x} is an integer.")
    
@dispatch_on_type.register(list)
def _(x):
    # some list logic
    print(f"{x} is a list.")

dispatch_on_type(set())

I am the default implementation.

dispatch_on_type("STRING")

'STRING' is a string.

dispatch_on_type(1337)

1337 is an integer.

dispatch_on_type([1,3,3,7])

[1, 3, 3, 7] is a list.

You can do all sorts of cool things with functools.singledispatch, but it doesn't solve the problem in the code at the top of the page. For that, we're going to create a decorator similar to singledispatch that dispatches based on the value of the first argument instead of the type.

Along the way we'll learn more about how decorators work.

Writing Decorators¶

The @ decorator syntax is syntactic sugar that covers passing a function to another function and then returning a function.

What?

Again, this is easier to show than to explain.

def a_decorator(func):
    return func


# The sweet decorator way...
@a_decorator
def some_function():
    print("Some function.")

# Which has exactly the same effect as...
def some_other_function():
    print("Some other function.")
    
some_other_function = a_decorator(some_other_function)

A decorator is just a function that returns a function.

When used with the @ syntax,

the decorator function is called, with the decorated function passed as an argument;
the return value of the decorator function is assigned to the same name as the decorated function.
When you call the decorated function, you are actually calling the function that was returned by the decorator (which may or may not call the original function's code).

But the above example returned the original function without altering it. The point of decorators is to return something other than the original function, in order to transform the function in some way.

To do this, we usually define another function inside the decorator, and then return that.

def never_two(func):
    def wrapper(*args, **kw):
        x = func(*args, **kw)
        return x if x != 2 else 3
    return wrapper
    
@never_two
def add(x,y):
    return x + y

add(1,1)

3

The wrapper function is defined inside never_two, but it is not executed when never_two is executed (which happens at the line where @never_two appears). Notice — it isn't called anywhere. (That is, you don't see anything like wrapper(1,1).)

Instead, the wrapper function is returned by @never_two, and assigned to the name add. Meanwhile, the code in the original add definition is inside wrapper, where it is called func.

When add(1,1) is called:

The code defined in wrapper is executed, because it was assigned to add.
The arguments passed into add (the two 1s) are passed on to func when it is called at x = func(*args, **kw).
The code originally defined at add (return x + y) is executed, because that code was assigned to func.
The output of func (the original add) is compared to 2, and altered accordingly.
The code defined under wrapper (currently being called add) returns 3.

Two points might be helpful here:

Think of a function as just everything from the parenthesis onward, excluding the name. Once you think of a function as a block of code that accepts arguments, which can be assigned to any name, things get a little easier to understand.
The (*args, **kw) is a way to collect, pass on, and then unpack all the positional and keyword arguments. A full treatment is beyond the scope of this article. For now, just notice that whatever is passed into wrapper is simply passed on to func.

Writing a Dispatch Decorator¶

Let's look at the syntax of functools.singledispatch again, and think about what we need to do to emulate it for values instead of types.

@functools.singledispatch
def dispatch_on_type(x):
    print("I am the default implementation.")
    
@dispatch_on_type.register(str)
def _(x):
    print(f"'{x}' is a string.")

Decorators that Return Decorators¶

Notice that we actually have two decorators:

functools.singledispatch
dispatch_on_type.register

This means inside singledispatch, the decorated function (in this case, dispatch_on_type) is being assigned an additional attribute, .register, which is also a decorator function.

That might look something like:

def outer_decorator(func):
    
    def inner_decorator(func):
        
        def inner_wrapper():
        
            print("Inner wrapper.")
        
        return inner_wrapper
    
    def wrapper():
        print("The wrapper function.")
    
    wrapper.decorator = inner_decorator
    
    return wrapper

@outer_decorator
def a_function():
    print("Original a_function.") # This will never execute.

@a_function.decorator
def another_function():
    print("Original another_function.") # This will never execute.

a_function()

The wrapper function.

another_function()

Inner wrapper.

Unpacking that a bit:

outer_decorator defines two functions,inner_decorator and wrapper
wrapper is returned by outer_decorator, so it will be executed when a_function is called
inner_decorator is assigned as an attribute of wrapper, so a_function.inner_decorator becomes a usable decorator
inner_decorator defines inner_wrapper and returns it, so it will be executed when another_function is called

Decorators with Arguments¶

You may have noticed that up until now, the decorators created in this article did not included parentheses or arguments when attached to functions. This is because the decorated function is actually passed as the only argument to the function call.

But when registering functions against types, singledispatch included an argument.

@functools.singledispatch
def dispatched():
    return

@dispatched.register(str)
def _():
    return

Incredibly, the way to achieve this is to nest yet another function into the decorator.

That is because, really, register isn't a decorator. Instead, register is a function which returns a decorator when passed an argument.

Let's take our previous example and expand it to include this idea.

def outer_decorator(func):
    
    def faux_decorator_w_arg(arg):
        
        def actual_decorator(func):
            
            def inner_wrapper():
        
                print(f"Inner wrapper. arg was: {arg}")
        
            return inner_wrapper
        
        return actual_decorator
    
    def wrapper():
        print("The wrapper function.")
    
    wrapper.decorator = faux_decorator_w_arg
    
    return wrapper

@outer_decorator
def a_function():
    print("Original a_function.") # This will never execute.

@a_function.decorator("decorator_argument")
def another_function():
    print("Original another_function.") # This will never execute.

a_function()

The wrapper function.

another_function()

Inner wrapper. arg was: decorator_argument

Putting it Together¶

So now we know how to create decorators that return decorators and accepts arguments. With this, plus a dictionary that maps registered values to functions, we can create a dispatch on value decorator.

def dispatch_on_value(func):
    """
    Value-dispatch function decorator.
    
    Transforms a function into a value-dispatch function,
    which can have different behaviors based on the value of the first argument.
    """
    
    registry = {}

    def dispatch(value):

        try:
            return registry[value]
        except KeyError:
            return func

    def register(value, func=None):
       
        if func is None:
            return lambda f: register(value, f)
        
        registry[value] = func
        
        return func

    def wrapper(*args, **kw):
        return dispatch(args[0])(*args, **kw)

    wrapper.register = register
    wrapper.dispatch = dispatch
    wrapper.registry = registry

    return wrapper

@dispatch_on_value
def react_to_status(status):
    print("Everything's fine.")
    

@react_to_status.register("red")
def _(status):
    # Red status is probably bad.
    # So we need lots of complicated code here to deal with it.
    print("Status is red.")

react_to_status("red")

Status is red.

There are a few things here which might not be obvious. So let's take a closer look.

def dispatch(value):

        try:
            return registry[value]
        except KeyError:
            return func

This is called by wrapper, and is the mechanism that determines which registered function is executed. It looks in the registry and returns the appropriate function (without executing it). If the value isn't registered, this will raise a KeyError. The except block catches that error and returns the original function.

def register(value, func=None):

        if func is None:
            return lambda f: register(value, f)

        registry[value] = func

        return func

This acts as both the faux_decorator and the actual_decorator.

It can be called with one or two positional arguments; if the second one is omitted, it is set to None.

At @react_to_status.register("red"), it is being called with only the value argument. This causes the lambda expression to be returned, with value already interpreted. (That is, the return value is lambda f: register("red", f)).

This is the same as:

if func is None:
        def actual_decorator(func):
            register(value, func)
        return actual decorator

But the lambda expression is a bit easier to read, once you know what it is doing.

This returned lambda function is then the actual decorator, and is executed with the wrapped function as its one argument. The function argument is them passed to register, along with the value that got set when the lambda was created.

Now register runs again, but this time it has both arguments. The if func is None is skipped, and the function is added to the registry with value as the key. The function is returned back to the point when the register decorator was called, but it gets assigned to the name _, because we never need to call it directly.

def wrapper(*args, **kw):
        return dispatch(args[0])(*args, **kw)

This is the function that actually gets executed when react_to_status is called. It calls dispatch with the first argument (arg[0]), which return the appropriate function. The returned function is immediatly called, with *args, **kw passed in. Any output from the function is returned to the caller of react_to_status, which completes the entire dispatch process.

Going Further¶

This tutorial looked at value dispatch in order to dig into how decorators work. It does not provide a complete implementation for a practical value dispatch decorator.

For example, in practice you'd probably want value dispatch to include:

values within a range
values in a collection
values matching a regular expression
values meeting criteria defined in a fitness or sorting function

And we didn't even talk about additional functools features that help sort out introspection or dealing with the many problems created by decorators.

For a more complete, production ready implementation of this idea, see Dispatch on Value by minimind.

Credits¶

The final form of dispatch_on_value was based heavily on the Ouroboros implementation of functools.singledispatch.

Classical vs. Functional Modelling of Musical Arithmetic in Python¶

I'm currently building a music theory library in Python, called Ophis.

import ophis

This is an attempt create a utility that "understands" music theory and can manipulate music information, to be used as a base for other applications. This would be handy for all sort of things, from music theory educational apps to AI composition.

In this notebook, we'll look at how I originally implemented basic musical arithmetic in Ophis, the problems with that approach, and why I am moving from a classical to a functional design.

A Classical OOP Design¶

My first approach in implementing this was classically object oriented, and influenced by an essentially Platonic ontology.

The idea was that musical building blocks would be, as much as possible, similar to integers.

# A `Chroma` is the *idea* of a note letter name 
#     Example: "A" or "D FLAT"
# 35 chromae are initialized to constants on load, 
#   representing all 7 letter names, 
#   with sharps, flats, double sharps, and double flats.

ophis.wcs # Western Chroma Set, 
          # the complete list of all initialized chromae

{BDUBFLAT,
 GDUBSHARP,
 BFLAT,
 DDUBSHARP,
 F,
 DFLAT,
 D,
 ADUBFLAT,
 AFLAT,
 G,
 CFLAT,
 C,
 FDUBFLAT,
 GDUBFLAT,
 B,
 GSHARP,
 BSHARP,
 GFLAT,
 ASHARP,
 FDUBSHARP,
 CDUBFLAT,
 DDUBFLAT,
 E,
 EDUBFLAT,
 CSHARP,
 EFLAT,
 EDUBSHARP,
 FFLAT,
 A,
 BDUBSHARP,
 CDUBSHARP,
 DSHARP,
 ADUBSHARP,
 ESHARP,
 FSHARP}

One of the main ideas here is that there is one and only one representation of the idea of C SHARP or F NATURAL . Moreover, the chromae can be inspected, and know how to represent themselves.

ophis.FSHARP.unicode

'F♯'

ophis.FSHARP.ascii

'F#'

ophis.FSHARP.base

'F'

Chromae also carry all the logic needed for musical manipulation and mathematical representation.

int(ophis.FSHARP)

6

ophis.FSHARP.augment()

G

ophis.FSHARP.diminish()

F

A Pitch is a Chroma with an octave designation. Using the special __call__ method on Chroma, and the __repr__ method on Pitch, I was able to make their interactive representation is intuitive.

# in Chroma class

def __call__(self, octave):
    return Pitch(self, octave)

# in Pitch class:

def __repr__(self):
    return self.chroma.name + "(" + self.octave + ")"

# The "standard Python" way to create a pitch. 
ophis.Pitch(ophis.GFLAT, 2)

GFLAT(2)

# The Ophis canonical way.

ophis.GFLAT(2)

GFLAT(2)

Intervals (without octaves) and QualifiedIntervals (with octaves) have a similar relationship to each other as Chroma and Pitch.

Rather than initializing every possible musical interval, the qualities (major, minor, perfect, augmented, diminished) are initialized and callable, to create an intuitive API.

ophis.Major(2) # A Major second.

Major(2)

ophis.Perfect(4, 2) # A Perfect fourth, plus 2 octaves.

Perfect(4)^2

Function caching is used to ensure that only one of any interval is created. (Some experimental benchmarking showed that this would matter in large scores.)

id(ophis.minor(2).augmented()) == id(ophis.Major(2))

True

And, of course, you can use both types of intervals to manipulate chromae and pitches.

ophis.G + ophis.Major(2)

A

ophis.A(2) + ophis.Perfect(5)

E(3)

ophis.FSHARP(1) + ophis.Major(2, 2)

GSHARP(3)

All this lets you do complicated musical manipulation and representation.

(ophis.FFLAT + ophis.Perfect(5)).diminish().unicode

'B♭'

Obviously, all this is only the beginning of what is needed for a music theory library. But it is a beginning. The next submodule will build up Duration and TimeSignature, leading to the creation of Measure and eventually Score. My current plan is to use pandas.DataFrame for multi-voice scores, as that would allow cross-voice analysis in a way that multi-dimensional lists would not.

Problems Appear¶

So that's great, but...

I can't but help wonder if some of this is overwrought.

A number of interrelated concerns occured to me while working on this implementation.

Logic is hard to reason about¶

The math of moving from note to note is riddled with off-by-one and modulo arithmetic problems.

An interval representing no change (from a note to itself) is called a unison, represented with a 1. A difference of one step is called a second, and so on.
The first scale degree is 1. (Not zero indexed.)
We frequently think about scales as having eight notes, but in reality they only have seven. When this is zero indexed, the notes go from 0-6. This is fine for arithmetic, but when thinking as a musician it is jarring.

Because of this difficulty in clear thinking on my part, I often found myself using the guess-and-check method for remembering when to add or subtract a one.

I wrote rigorous tests along the way to keep these errors out, so everything ends up fine in the end. However, this made for slow and sometimes demoralizing progress, and I would hate to have to go back and reason about this code after being away from it.

Incorrect assumptions about logical order¶

The first attempt to implement basic Chroma functionality assumed that Interval — the relationship between two chromae — would depend on Chroma. It turns out this is exactly backwards. Interval is logically prior to Chroma. There is no way to define abstract named pitches without their relationships already existing.

Practically speaking, discovering this simply meant I had to re-order some code. But this challenged my thinking about what the fundamental building blocks of music theory actually are.

Convoluted logic and utility data structures¶

Here's an example, the augment method from the Chroma class.

def augment(self, magnitude=1, modifier_preference="sharp"):
    """Return a chroma higher than the one given.

    Args:
        magnitude (:obj:`int`, :obj:`Interval`,
                   or obj with an ``int`` value; optional): 
            the distance to augment by. 
            Integer values are interpreted as half steps. 
            Defaults to 1.
        modifier_preference (:obj:`str`, 
                             ``'sharp'`` or ``'flat'``;
                             optional)
            Defaults to ``'sharp'``. 

    Examples:

        >>> C.augment()
        CSHARP

        >>> C.augment(1, 'flat')
        DFLAT

        >>> C.augment(minor(3))
        EFLAT

        >>> D.augment(2)
        E

        >>> E.augment()
        F

        >>> E.augment(2, 'flat')
        GFLAT
    """

    value_candidates =  self.essential_set.chroma_by_value(
        int(self) + int(magnitude)
    )
    try:
        letter_candidates = self.essential_set.chroma_by_letter(
            self.base_num + magnitude.distance
        )
        solution, = value_candidates & letter_candidates
        return solution
    except:
        return value_candidates.enharmonic_reduce(modifier_preference)

If it isn't obvious, here's what it does:

Calculate the integer value of the target Chroma and find the set of Chroma objects which have the integer value we're looking for.
Try:
- Calculate the letter name of the target Chroma and find the set of Chroma that have the name value we're looking for.
- Find and return the union of the integer-value set and the note-name value set.
Except:
- Return a member of the integer-value set, basing the selection on some logic (defined elsewhere) that prefers sharps to flats or flats to sharps in certain instances.

This works, but it isn't at all how a musician thinks about this operation. Moreover, it depends on the essential_set, the collection of all initialized chromae. (Referred to above as wcs, the Wesern Chroma Set.) It would be bad enough if this was just used to keep the pool of initialized chromae, so that methods returning C Sharp always returned the same C Sharp. But it doesn't just do that. An inordinate amount of musical knowledge and logic crept into the ChromaSet class that defines the essential_set. While I'm positive that some of this is due to bad coding on my part, I think the bulk of it is due to bad conceptualization.

The final problem with this is that it is non-obvious. This code is hard to read and reason about, because it isn't clear what is actually happening.

Fragile Primitives¶

Python doesn't really allow you to protect object attributes or module-level constants. There are some things you can do to ensure object attributes aren't reassigned accidentally (and I've done them), but (as far as I can tell) module-level constants cannot be protected.

This is a problem, since the fundamental building blocks of music theory in the current implementation are initialized as constants. The object representing C Sharp is created and assigned to the name CSHARP. If that name gets reassigned, you are basically hosed. This could lead to hard-to-trace errors and frustrating interactive sessions.

Poor isomorphism to numbers¶

One of the design goals of Ophis is to be able to treat musical concepts as numbers. That's why the arithmetic operators are implemented and everything has an integer value. I wanted it to be easy for math utilities to operate on pitches and intervals. This would enable things like advanced theoretical analysis and machine learning.

But, they aren't numbers. They just aren't.

You can't (meaningfully) have a Chroma with a float, decimal, or fractional value. This means that microtones are not presently accounted for and will require an extension, the logic of which I can only guess at.

You also can't meaningfully multiply or divide values. Offhand, I'm not sure why you would want to do so, but I can imagine approaches to musical analysis where it would be needed.

Further, even with supported integer-based operations, using any standard math tool requires notes from a score to be converted into numbers, manipulated or analyzed, and converted back. There's no direct access to Ophis "primitives" in Numpy, SciKitLearn, or anything else.

These problems piled up over time as I implemented the basic logic and worked out the implications. Technical debt accumulates through a process of small compromises and justifications. By the time I became aware of the scope of the problem, I had two thoughts:

Re-architecting everything would take too long to be worthwhile. I would probably get disheartened and give up.
I can refactor the internals in the future to make things a bit clearer and cleaner. In the meantime, good documentation would make the code maintainable.

So, my plan was to just keep moving. But then, thinking about the isomorphism problem, I realized another poorly-mapped isomorphism.

Poor isomorphism between Chroma and Intervals¶

Or really, no explicit isomorphism at all. And this is a problem because these are really the same thing.

I had implemented the Interval class, and written all the logic for how intervals are inverted, augmented, and diminished. This requires understanding of the interplay between interval distances (third, fourth, sixth) and their qualities (Major, minor, Perfect), and how many half-steps each are. And of course there's that zero-indexing stuff to think about (second = 1, third = 2).

Then I implemented the Chroma class, and wrote almost the same logic (but just a bit different) for how pitches are augmented and diminished (pitches aren't inverted). This requires an understanding of the interplay between note letter names (C, D, E), how those letter names map to a zero-indexed numerical representation (C = 0, D = 1, E = 2), and how modifiers like sharp and flat affect the total number of halfsteps from C (the origin point in modern music theory).

But these are, as I said, exactly the same thing.

Every note can be represented as an interval from C. And not only can it be represented that way, but that is exactly how it was already defined. There is no other reasonable way to (numerically) define notes.

Here's an example in case this isn't clear:

E Natural is a Major Third away from C.
In our zero-indexed representation intervals, a Third is 2.
A Major Third is 4 half-steps.

Those two numbers, (2, 4), are an integral part of the definition of E Natural; without them, you can't do any of the manipulation that makes the Chroma meaningful.

print(ophis.Major(3).distance, int(ophis.Major(3)))
print(ophis.E.base_num, int(ophis.E))

2 4
2 4

Obviously, this holds for every other Chroma as well.

print(ophis.Perfect(5).distance, int(ophis.Perfect(5)))
print(ophis.G.base_num, int(ophis.G))

4 7
4 7

print(ophis.Augmented(6).distance, int(ophis.Augmented(6)))
print(ophis.ASHARP.base_num, int(ophis.ASHARP))

5 10
5 10

Further, it turns out that these two numbers are the only things you need to know in order to do any standard musical manipulation you might want to do.

g_or_p5 = (4,7) # Tuple representing G or a Perfect Fifth
e_or_maj3 = (2,4) # Tuple representing E or a Major Third

# Add tuples element wise.
sum_of_tuples = (
    g_or_p5[0] + e_or_maj3[0], 
    g_or_p5[1] + e_or_maj3[1]
)

sum_of_tuples # (6,11)

(6, 11)

g_augmented_by_maj3 = ophis.G.augment(ophis.Major(3))
e_augmented_by_p5 = ophis.E.augment(ophis.Perfect(5))

print(g_augmented_by_maj3)
print(e_augmented_by_p5)

B
B

print(ophis.B.base_num, int(ophis.B))

6 11

z = ophis.Perfect(5) + ophis.Major(3)
z

Major(7)

print(z.distance, int(z))

6 11

So any chroma and any interval can be represented by a two-tuple, while manipulations originally implemented as methods in different classes can be a unified set of pure functions that accept tuples as arguments.

Great.

But two-tuples don't provide all the additional information you need to notate pitches or otherwise make them understandable as music.

So we need some "translation" functions. This still involves a lot of "magic number" coding, but hopefully it can be condensed into a small set of mappings that are easy to reason about.

import bidict # efficient two-way indexing of dicts

primary_map = [
    # half steps, scale degree / interval number, 
    # interval name, letter name, Perfect? 
    #                             (False=Major) 
    (0,  1, "unison",  "C", True),  #0
    (2,  2, "second",  "D", False), #1
    (4,  3, "third",   "E", False), #2
    (5,  4, "fourth",  "F", True),  #3
    (7,  5, "fifth",   "G", True),  #4
    (9,  6, "sixth",   "A", False), #5
    (11, 7, "seventh", "B", False)  #6
]

# Split primary map into bidicts for each value.
#     For faster, more sensible referencing.
#     This feels wrong and I need a better way.
#     Maybe something with named tuple...

hs_map = bidict.bidict(
    {x:item[0] for x, item in enumerate(primary_map)}
)
interval_map = bidict.bidict(
    {x:item[1] for x, item in enumerate(primary_map)}
)
interval_name_map = bidict.bidict(
    {x:item[2] for x, item in enumerate(primary_map)}
)
name_map = bidict.bidict(
    {x:item[3] for x, item in enumerate(primary_map)}
)
quality_map = {
    x:item[4] for x, item in enumerate(primary_map)
}

# How to translate between 
# diatonic intervals and modified intervals.
interval_quality_map = {
    True: bidict.bidict({ # Diatonic is Perfect
        -2 : 'double diminished', 
        -1 : 'diminished', 
         0 : 'Perfect',
         1 : 'Augmented', 
         2 : 'Double Augmented'
    }),
    False: bidict.bidict({ # Diatonic is Major
        -2 : 'diminished', 
        -1 : 'minor', 
         0 : 'Major', 
         1 : 'Augmented', 
         2 : 'Double Augmented'
    })
}

modifiers = bidict.bidict({
    -2 : 'doubleflat',
    -1 : 'flat',
     0 : 'natural',
     1 : 'sharp', 
     2 : 'doublesharp'
})

import functools

# Single Dispatch:
#     two functions with the same signature.
#
#     The type of the first argument determines 
#     which function is executed.
#     This way, if a tuple is passed in, 
#         a string is returned,
#     and if a string is passed in, 
#         a tuple is returned.

@functools.singledispatch
def chroma(x):
    return None

@chroma.register(tuple)
def _(xy):
    x,y = xy
    name = name_map[x]
    modifier = modifiers[y - hs_map[x]]
    return " ".join([name, modifier])

@chroma.register(str)
def _(letter, modifier):
    x = name_map.inv[letter]
    mod_diff = modifiers.inv[modifier]
    y = hs_map[x] + mod_diff
    return x,y

@functools.singledispatch
def interval(x):
    return None

@interval.register(tuple)
def _(xy):
    x,y = xy
    name = interval_name_map[x]
    q_mod = y - hs_map[x]
    q = interval_quality_map[quality_map[y]][q_mod]
    return " ".join([q, name])

@interval.register(str)
def _(q, n): # quality, number
    x = n - 1
    is_perfect = quality_map[x]
    q_mod = interval_quality_map[is_perfect].inv[q]
    y = hs_map[x] + q_mod
    return x, y
    
def augment(a, b):
    return tuple(map(sum,zip(a,b)))

def diminish(a, b):
    return tuple(y - b[x] for x,y in enumerate(a))

chroma((0,0))

'C natural'

interval((2,3))

'diminished third'

chroma('D', 'sharp')

(1, 3)

interval('Major', 3)

(2, 4)

chroma(augment(chroma('C', 'sharp'), interval('minor', 3)))

'E natural'

%timeit chroma(
    augment(chroma('C', 'sharp'), interval('minor', 3))
)

22.3 µs ± 1.4 µs per loop (mean ± std. dev. of 7 runs, 100000 loops each)

ophis.CSHARP.augment(ophis.minor(3))

E

%timeit ophis.CSHARP.augment(ophis.minor(3))

101 µs ± 3.95 µs per loop (mean ± std. dev. of 7 runs, 10000 loops each)

A functional approach:

simplifies the math and logic
preserves important isomorphisms
requires much less code
executes much faster

The only downside is that the API for interactive use is a little less elegant, but not so much as to be a problem.

Where to Go From Here¶

The quick functional implementation demonstrated here doesn't include all the things that the OO approach currently has.

Foremost, this version needs to include modulo arithmetic.

augment((7,11),(1,1)) # Should be (0,0), in musical logic.

(8, 12)

# This result is meaningless.
chroma((8,12))  # KeyError

---------------------------------------------------------------------------
KeyError                                  Traceback (most recent call last)
<ipython-input-38-114c113c80ec> in <module>()
      1 # This result is meaningless.
----> 2 chroma((8,12))

/Users/adamwood/amwenv/lib/python3.5/functools.py in wrapper(*args, **kw)
    741 
    742     def wrapper(*args, **kw):
--> 743         return dispatch(args[0].__class__)(*args, **kw)
    744 
    745     registry[object] = func

<ipython-input-28-f2a6c2b4cc47> in _(xy)
     13 def _(xy):
     14     x,y = xy
---> 15     name = name_map[x]
     16     modifier = modifiers[y - hs_map[x]]
     17     return " ".join([name, modifier])

/Users/adamwood/amwenv/lib/python3.5/site-packages/bidict/_common.py in proxy(self, *args)
     94         attr = getattr(self, attrname)
     95         meth = getattr(attr, methodname)
---> 96         return meth(*args)
     97     proxy.__name__ = methodname
     98     proxy.__doc__ = doc or "Like dict's ``%s``." % methodname

KeyError: 8

Additionally, I need to include octave designations. The arithmetic is almost included for free with the functional approach, but the translation functions don't support it.

# Maj Second (or D) and min 3, with a third term for octave designation
augment((1,2,1), (2,3,2))

(3, 5, 3)

# F, 2 octaves above Middle C
chroma((3,5,3)) # ValueError

---------------------------------------------------------------------------
ValueError                                Traceback (most recent call last)
<ipython-input-40-3c4313b92e77> in <module>()
----> 1 chroma((3,5,3)) # F, 2 octaves above Middle C

/Users/adamwood/amwenv/lib/python3.5/functools.py in wrapper(*args, **kw)
    741 
    742     def wrapper(*args, **kw):
--> 743         return dispatch(args[0].__class__)(*args, **kw)
    744 
    745     registry[object] = func

<ipython-input-28-f2a6c2b4cc47> in _(xy)
     12 @chroma.register(tuple)
     13 def _(xy):
---> 14     x,y = xy
     15     name = name_map[x]
     16     modifier = modifiers[y - hs_map[x]]

ValueError: too many values to unpack (expected 2)

The translation functions and associated dictionaries need to be extended to include multiple representations such as Unicode, ASCII, and Lilypond.

Finally, I might also do some experiementation with a hybrid approach that would keep the OO API intact. However, that might get too complicated.

Is Functional Really Better?¶

I don't know.

The difference in execution speed can probably be resolved by cleaning up the OO implememenation and importing the tuple-based arithmetic instead of the union-of-sets approach. I suspect that this would also make the OO code easier to read and reason about.

I'm not at all convinced that there is something inherently wrong with object oriented code. However, I do think that a classical paradigm promotes a "different things are different things" mentality. In some cases this is probably helpful. In music, at least in this case, it obscured a fundamental sameness between two important concepts. Functional programming forced me to recognize that sameness. Someone else might have recognized it anyway, and written a good OO implementation first.

If there is a generalizable lesson here, I think it might this: Think through a few different approaches and paradigms. Try coding up more than one logical implementation in the domain. See how that sheds light on the underlying problems and data structure.

Also, don't be afraid to redesign things. Especially if you don't have any users yet.

hack.write()

Learn About Python Decorators by Writing a Function Dispatcher

A Problem in Need of Decorators¶

A little bit about function dispatching¶

Writing Decorators¶

Writing a Dispatch Decorator¶

Decorators that Return Decorators¶

Decorators with Arguments¶

Putting it Together¶

Going Further¶

Credits¶

Object-oriented vs. Functional Modelling of Musical Arithmetic in Python

Classical vs. Functional Modelling of Musical Arithmetic in Python¶

A Classical OOP Design¶

Problems Appear¶

Logic is hard to reason about¶

Incorrect assumptions about logical order¶

Convoluted logic and utility data structures¶

Fragile Primitives¶

Poor isomorphism to numbers¶

Poor isomorphism between Chroma and Intervals¶

Where to Go From Here¶

Is Functional Really Better?¶

Registering Functions Against Object Methods in Python

What if we went deeper?

Further Reading

Intersection of Non-Empty Sets in Python

List comprehension

With iterable unpacking (tuple unpacking)

Why would you ever do this?

The generalized problem

More specifically...

Some actual code

Another approach

So... what's the point?

Verbiage

Designing vs. Decorating

Docs as Code

Practices

Benefits

DocOps Isn't Just the Fun Part

The Real Reason I Love Static Site Generators

File Names