Install & Compatibility
Where this runs
tested against v1.1.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.112s · 17.8MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.5s · import 0.100s · 18MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Sentinel
✓ from sentinels import Sentinel
Used to create your own custom sentinel objects.
NOTHING
✓ from sentinels import NOTHING
A pre-defined sentinel often used as a default value when `None` is a valid input.
This quickstart demonstrates how to use the pre-defined `NOTHING` sentinel for dictionary operations where `None` is a valid value, and how to create a custom sentinel using the `Sentinel` class. It highlights the use of `is` for comparison, a key characteristic of sentinel objects.
from sentinels import NOTHING, Sentinel
class MyDict(dict):
def get_default_or_raise(self, key, default=NOTHING):
returned = self.get(key, default)
if returned is NOTHING:
raise KeyError(key)
return returned
# Example usage:
d = MyDict({"valid_none": None, "valid_zero": 0})
# Key exists with a valid None value
print(f"'valid_none' value: {d.get_default_or_raise('valid_none', default=None)}")
# Key exists with a valid zero value
print(f"'valid_zero' value: {d.get_default_or_raise('valid_zero')}")
# Key does not exist, uses NOTHING as default, raises KeyError
try:
d.get_default_or_raise("non_existent_key")
except KeyError as e:
print(f"Caught expected error: {e}")
# Create a custom sentinel
MISSING_VALUE = Sentinel('MISSING_VALUE')
def my_function(arg=MISSING_VALUE):
if arg is MISSING_VALUE:
print("Argument was not provided.")
else:
print(f"Argument provided: {arg}")
my_function()
my_function("hello")
Debug
Known issues
gotchaThis library (`sentinels`, plural) provides generic sentinel objects. Do not confuse it with other similarly named, but unrelated, libraries like `sentinel-sdk` (blockchain), `sentinelsat` (satellite data), or `sentinel` (a different sentinel creation utility that uses `sentinel.create()`).fixEnsure you are importing from the correct package `sentinels` and using `Sentinel` or pre-defined constants like `NOTHING` directly from it.
affects: All versions
gotchaAlways compare sentinel objects using the `is` operator, not `==`. Sentinels are designed to be singletons, and `is` checks for object identity, which is crucial for their intended use. Using `==` might lead to unexpected behavior if another object coincidentally evaluates as equal.fixReplace `if value == NOTHING:` with `if value is NOTHING:`.
affects: All versions
gotchaWhen creating a custom `Sentinel` for use with type checkers (e.g., `MY_SENTINEL = Sentinel('MY_SENTINEL')`), ensure the string name passed to the constructor exactly matches the variable name. This convention is important for proper type inference and narrowing by tools like MyPy.fixUse `MY_SENTINEL = Sentinel('MY_SENTINEL')` instead of `MY_SENTINEL = Sentinel('SOME_OTHER_NAME')`. affects: All versions (relevant for users leveraging type hints)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'sentinels'
The `sentinels` library has not been installed in the current Python environment.
NameError: name 'NOT_SET' is not defined
The `NOT_SET` sentinel was used without being imported or referenced via the `sentinels` module.
fixfrom sentinels import NOT_SET
AttributeError: type object 'Sentinel' has no attribute 'NOT_SET'
The `NOT_SET` sentinel is a module-level instance, not an attribute of the `Sentinel` class itself.
fiximport sentinels
value = sentinels.NOT_SET
AttributeError: module 'sentinels' has no attribute 'NOTSET'
There is a typo in the name of the sentinel instance; it should be `NOT_SET` (with an underscore), not `NOTSET`.
fiximport sentinels
value = sentinels.NOT_SET
Upgrade
Version history
1.1.1latest on PyPI · released Aug 12, 2025
Audit
Dependencies
No dependency data recorded yet.