omitted

A Do-Not-Care Value for Python

Let's Talk About Kwargs

It's easy to take for granted, but one of the most elegant aspects of Python is its handling of functional keyword arguments (kwargs). This one construct provides:

1. A way to specify parameters without having to know its position in the argument list
2. Automatic checking of expected parameters
3. An elegant way to specify parameter defaults
4. A meaningful, self-documenting function signature

Most of the time kwargs work flawlessly; but there are a few cases where their use becomes tricky.

I'm going to talk about that problem, show one common anti-pattern that attempts to fix it, and then propose an alternate approach that retains all of the benefits mentioned above at the cost of introducing a new concept to Python, the Omitted singleton.

Problem, What Problem?

Let's start off with an example. Suppose you have a function which takes a person and allows you to update the person's name, age, both, or neither. Naively, you might write that function as something like:

def update(person, name=None, age=None):
    person.name = name
    person.age = age

Now let's call this function, but only update the person's age:

> person = Person(name='Alice', age=32)
> update(person, age=33)
> person.age
33
> person.name
None

Notice that the code correctly set the age but, unexpectedly from the caller's point-of-view, also set the name to None. Not what we intended.

The problem here is that None can't be used to both represent a valid value and at the same time we used to represent a do-not-care condition.

Realizing we need a way to differentiate these two conditions, we modify the code slightly:

def update(person, **kwargs):
    for k, v in kwargs.items():
        setattr(person, k, v)

Here we're using the presence or absence of the key in the kwargs dict to represent the do-not-care condition and the value of None is solely reserved for actually setting the attribute to None (pretty reasonable, huh?).

Let's call this new version of update again:

> person = Person(name='Alice', age=32)
> update(person, age=33)
> person.age
33
> person.name
'Alice'

The method behaved exactly as we expected. And from my experience, many developers stop here because It Just Works. But it comes at a cost: we no longer have expected kwarg checking (benefit #2), no elegant way of setting default parameters (benefit #3), and we've lost our meaningful function signature (benefit #4). For these reasons, I consider this an anti-pattern and propose a different approach.

None More None

To retain the benefits of explicit kwargs, we need a way for the value of the keyword to differentiate between the do-not-care condition and a valid value. As we've seen above, None isn't good enough since None is a perfectly reasonable value for many attributes.

Instead we need to create a new value, a singleton like None that can represent this case which I call Omitted. With it, our function becomes:

Omitted = object()

def update(person, name=Omitted, age=Omitted):
    if name is not Omitted:
        person.name = name

    if age is not Omitted:
        person.age = age

We end up with code that behaves exactly as we'd expect when called, but also preserves the benefits of explicit kwargs:

update(person, age=33)      # Just set the age to 33
update(person, name=None)   # Set the name to None
update(person)              # Doesn't update any attributes
update(person, foo=bar)     # Raises a TypeError because foo isn't an
                            # expected kwargs (benefit #2)

So What's The Catch?

So, solving our default kwarg problem, we've gone ahead and published our library containing our update function. Now suppose that someone comes along and wants to use our library. First of all, they'll be appreciative of our usage of explicit kwargs--once they get past the unusual looking Omitted defaults.

However, when they go to use it, they might do something like:

Omitted = object()

def update_with_email(person, name=Omitted, age=Omitted):
    update(person, name=name, age=age)
    send_email(person)

> person = Person(name='Alice', age=32)
> update_with_email(age=33)
> person.age
33
> person.name
<object object at 0x105ae2080>

As you can see, person.name has ended up with the value of Omitted. The problem here is that caller's Omitted instance is different from the libraries Omitted instance, so they don't compare as identical.

What we'd like is a way to define a single global singleton that represents this do-not-care condition across all Python packages, in the same way that None is identical no matter where it's used.

Introducing...

This Python module aims to solve this problem by defining the one-and-only Omitted instance, shareable between all packages on the system.

To be clear, just because a library uses Omitted, it doesn't mean the calling code must as well. Not passing the kwarg or setting it to None will behave correctly without having to know that Omitted was used behind the scenes to make it work.

The only time a caller would need to import Omitted is if they wanted to proxy the do-not-care condition from the caller into the library. In that case, you'd just do something like:

from libperson import update
from omitted import Omitted

def update_with_email(person, name=Omitted, age=Omitted):
    update(person, name=name, age=age)
    send_email(person)

With that in mind, go ahead, import Omitted and let your code stop caring.