Features

• sentinels are unique

• sentinels are singletons — the only instance of their own anonymous class

• sentinels can be used with is comparisons

• sentinels can be used with pickle

• sentinels can be used with copy.deepcopy

• you can add arbitrary attributes and methods to sentinels

• sentinels have a nice, self-documenting __repr__!

Example

Sentinels are useful when other objects such as None, False, 0, -1, are valid values within some data structure. For example, setting default values when all other values are valid with: dict.setdefault():

d = {"stdout": None, "stdin": 0, "EOF": -1}

MissingEntry = sentinel.create()

[d.setdefault(key, MissingEntry) for key in ("stdin", "stdout", "stderr")]
[0, None, MissingEntry]

Alternatively, using dict.get() when fetching values:

>>> d = {"stdout": None, "stdin": 0, "EOF": -1}
>>> d.get("stdout", MissingEntry)
None
>>> d.get("stdin", MissingEntry)
0
>>> d.get("stderr", MissingEntry)
MissingEntry

Since a new sentinel can never occur in the original dictionary, you can tell which entries are missing or unset in a dictionary in a self-documenting way:

Unset = sentinel.create()
if d.get("stdin", Unset) is Unset:
    stdin = 0  # some reasonable default

Adding extra methods and class attributes

Sentinels may also inherit from base classes, or implement extra methods.

Consider a binary search tree with two kinds of nodes: interior nodes (Node) which contain some payload and leaves (Leaf), which simply terminate traversal.

To create singleton leaf which implements a search method and an is_leaf property, you may provide any extra class attributes in the cls_dict keyword argument. The following is a full example of both the singleton Leaf and its Node counterpart:

def _search_leaf(self, key):
    raise KeyError(key)

Leaf = sentinel.create('Leaf', cls_dict={
    'search': _search_leaf,
    'is_leaf': property(lambda self: True)
})

class Node(object):
    def __init__(self, key, payload, left=Leaf, right=Leaf):
        self.left = left
        self.right = right
        self.key = key
        self.payload = payload

    def search(self, key):
        if key < self.key:
            return self.left.search(key)
        elif key > self.key:
            return self.right.search(key)
        else:
            return self.payload

    is_leaf = property(lambda: false)

Example usage:

>>> tree = Node(2, 'bar', Node(1, 'foo'), Node(3, 'baz'))
>>> tree.search(1)
'foo'
>>> tree.search(4)
Traceback (most recent call last):
    ...
KeyError: 2