sentinels

What it is and what it does

Sentinels is a minimal utility that provides singleton sentinel objects—special placeholder values distinct from None, False, or any other Python value. The primary use case is solving a common design problem: when None is a valid data value in your code (e.g., a dictionary value or function return), you need a different marker to represent 'no value provided' or 'missing'. The package exports a pre-built NOTHING sentinel and a Sentinel class for creating custom ones. Sentinels are identity-based (compared with `is`), pickle-safe, and copy-safe—deepcopy and pickle.loads both return the same singleton object.

The package has no runtime dependencies and is pure Python, making it trivial to install. It supports Python 3.9 through 3.13. The typical pattern is to use a sentinel as a function default argument, then check identity in the function body to distinguish between 'no argument provided' and 'None was explicitly passed'. This is especially useful in wrapper classes, optional-argument APIs, and anywhere None carries semantic meaning.

Use it for:

• Implement optional-argument methods where None is a valid value and you need to distinguish 'not provided' from 'explicitly None'.
• Wrap dictionaries or other data structures with methods that raise on missing keys only when no default was given.
• Create guard values in configuration or state machines where you need distinct markers beyond True/False/None.
• Design library APIs that accept None as a meaningful input but need an internal 'unset' marker.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Provides singleton sentinel objects with special meanings—distinct placeholder values that can be used in function signatures and conditionals where None is a valid data value.

Yes. Sentinels solves a real, recurring design problem with zero dependencies and minimal code. The package is stable, permissively licensed, and widely downloaded. Maintenance is infrequent but the codebase is small and mature—there is little reason for frequent updates. Install it when you need to distinguish 'not provided' from None in your function signatures or conditionals.

Install

sentinels on PyPI

pip install sentinels

uv add sentinels

poetry add sentinels

Installing sentinels

Before you install

Low friction: pure Python wheel with no runtime dependencies. Maintenance is aging—last release was 367 days ago and the repository shows minimal recent activity, though it remains unarchived and the package is stable enough that infrequent updates may reflect maturity rather than abandonment.

License in practice

BSD 3-Clause License (permissive) places no restrictions on use, modification, or distribution in proprietary or open-source projects.

Quickstart

pip install sentinels

from sentinels import NOTHING

def get_or_raise(d, key, default=NOTHING):
    result = d.get(key, default)
    if result is NOTHING:
        raise KeyError(key)
    return result

Requires Python 3.9 or later.

Verify before relying

• Whether the package is actively maintained or in stable-maintenance mode—last commit was recent but release cadence is infrequent.
• Real-world adoption patterns and whether 8M monthly downloads reflect active use or transitive dependency chains.

Package facts

Evidence: sentinels-1.1.1-py3-none-any.whl

Tags

More Software Development packages