⚖️ simplibs-sentinels
Shared sentinel values for the simplibs ecosystem — precise tools for distinguishing different states of absence and intent.
simplibs-sentinels provides a small, dependency-free vocabulary for representing states that ordinary Python values cannot always distinguish clearly — such as "nothing was provided", "an expected value is missing", "use the default behaviour", or "there is no associated value".
The library deliberately stays small. It defines only the sentinel concepts that are useful as general-purpose building blocks across the simplibs ecosystem, while leaving domain-specific sentinels and existing standard-library sentinels where they naturally belong.
from simplibs.sentinels import UNSET, MISSING, DEFAULT, EMPTY
def configure(timeout: int | None | UnsetType = UNSET):
if timeout is UNSET:
timeout = get_default_timeout()
elif timeout is None:
timeout = 0
🧭 The Core Philosophy
A sentinel is useful when several states that look similar at the value level need to remain semantically distinct.
For example, None alone cannot distinguish between:
the caller provided nothing
the caller explicitly provided None
A sentinel gives the API a separate identity for the first state:
def connect(timeout: int | None | UnsetType = UNSET):
if timeout is UNSET:
timeout = get_default_timeout()
elif timeout is None:
timeout = 0
The important distinction is not the sentinel's truthiness but its identity.
Always test sentinels using is:
if timeout is UNSET:
...
rather than:
if timeout == UNSET:
...
simplibs-owned sentinels are singletons and falsy. EMPTY is an existing
sentinel adopted from Python's inspect module and retains its original
implementation and identity.
📦 Installation
pip install simplibs-sentinels
The library has no runtime dependencies.
It is intentionally positioned at the bottom of the simplibs dependency hierarchy so that other simplibs libraries can depend on it without introducing a dependency chain of their own.
🚀 The Four Core Sentinels
simplibs-sentinels currently exposes four general-purpose sentinel values:
| Sentinel | Semantics | Typical use |
|---|---|---|
UNSET |
A value was not supplied or has not been set | optional parameters, object state |
MISSING |
An expected value is absent | dictionaries, input data, parsing |
DEFAULT |
Default behaviour was explicitly requested | dynamic defaults, configuration |
EMPTY |
There is no associated value | absence of a value, especially introspection |
These concepts overlap at the edges, but they deliberately describe different states.
UNSET
UNSET represents a value that was not provided or has not been set.
Its most common use is distinguishing an omitted function argument from an
explicitly supplied None:
from simplibs.sentinels import UNSET, UnsetType
def connect(
host: str,
timeout: int | None | UnsetType = UNSET,
):
if timeout is UNSET:
timeout = get_default_timeout()
elif timeout is None:
timeout = 0
...
The resulting states are distinct:
UNSET → the caller supplied nothing
None → the caller explicitly supplied None
value → the caller supplied an actual value
UNSET is implemented by UnsetType, a SentinelType subclass.
MISSING
MISSING represents an expected value that is absent from some input
data or source.
It is particularly useful when the absence of a key or field must be
distinguished from an existing key whose value happens to be None:
from simplibs.sentinels import MISSING, MissingType
def validate(data: dict, key: str):
value = data.get(key, MISSING)
if value is MISSING:
raise ValueError(f"Required key '{key}' is missing.")
elif value is None:
...
Here:
MISSING → the expected key is absent
None → the key exists and explicitly contains None
MISSING is implemented by MissingType, a SentinelType subclass.
DEFAULT
DEFAULT represents an explicit request for default behaviour.
This is different from simply omitting a value:
from simplibs.sentinels import DEFAULT, DefaultType
def render(color: str | DefaultType = DEFAULT):
if color is DEFAULT:
color = theme.primary_color
...
The distinction is:
UNSET → nothing was supplied
DEFAULT → default behaviour was explicitly requested
This is particularly useful when the default is resolved dynamically at runtime rather than being a fixed value.
For example:
if color is DEFAULT:
color = resolve_default_color()
DEFAULT is implemented by DefaultType, a SentinelType subclass.
EMPTY
EMPTY represents the absence of an associated value.
Unlike UNSET, MISSING, and DEFAULT, EMPTY is not implemented by
simplibs.
It is the existing sentinel provided by Python's inspect module:
from inspect import Parameter
EMPTY is Parameter.empty
simplibs.sentinels.EMPTY therefore refers to the same object:
from simplibs.sentinels import EMPTY
import inspect
EMPTY is inspect.Parameter.empty
# True
EMPTY is inspect.Signature.empty
# True
This identity is intentional.
Rather than creating another EmptyType and introducing a second object
representing the same general concept, simplibs adopts the existing
standard-library sentinel.
This also means that EMPTY has no corresponding EmptyType in the
simplibs.sentinels API.
The type of the existing object can always be obtained with:
type(EMPTY)
but that implementation type is not part of the simplibs.sentinels
public vocabulary.
🔍 How the Sentinels Differ
The four sentinels can be viewed as four different questions:
| Sentinel | Question it answers |
|---|---|
UNSET |
Was anything supplied or set? |
MISSING |
Is the expected value present in the input? |
DEFAULT |
Did the caller explicitly request default behaviour? |
EMPTY |
Is there an associated value at all? |
For example:
UNSET
"This was not set."
MISSING
"The thing I expected is not there."
DEFAULT
"I explicitly want the normal/default behaviour."
EMPTY
"There is no associated value."
The distinctions are semantic rather than mechanically enforced. An API should use the sentinel whose meaning matches the state it needs to represent.
🧱 Sentinel Types
The three simplibs-owned sentinels expose their implementation types:
from simplibs.sentinels import (
DefaultType,
MissingType,
UnsetType,
)
This allows them to be used in type annotations:
from simplibs.sentinels import UNSET, UnsetType
def process(
value: str | UnsetType = UNSET,
) -> None:
...
The sentinel instances themselves are the values normally used by application code.
SentinelType is the shared implementation base:
from simplibs.sentinels import SentinelType
It provides singleton behaviour and falsy boolean behaviour for simplibs-owned sentinels.
EMPTY is deliberately excluded from this hierarchy because it is an
existing external sentinel whose identity is preserved.
🧩 Singleton Behaviour
Each simplibs-owned sentinel is a singleton:
from simplibs.sentinels import UNSET, UnsetType
UNSET is UnsetType()
# True
Different sentinel types remain distinct:
from simplibs.sentinels import MISSING, UNSET
MISSING is UNSET
# False
The same principle applies to EMPTY, although its singleton identity is
provided by inspect rather than by SentinelType:
from simplibs.sentinels import EMPTY
import inspect
EMPTY is inspect.Parameter.empty
# True
Sentinel identity should therefore always be checked using is.
🪶 Minimal by Design
The package deliberately does not attempt to collect every sentinel-like object from Python's standard library.
Many standard-library sentinels are tightly coupled to a particular module
or protocol. For example, a sentinel meaningful specifically to argparse,
subprocess, signal, or unittest.mock does not automatically become
more useful merely because it is re-exported from simplibs.sentinels.
Likewise, a sentinel whose import path is already direct and unambiguous does not benefit from being duplicated here.
The package therefore focuses on a much smaller question:
Is this sentinel a general-purpose concept that benefits from being part of the shared simplibs vocabulary?
At present, the answer is the four values exposed by this library.
🔭 About the library, from the author's point of view
simplibs-sentinels was originally created for a very simple reason:
multiple simplibs libraries needed an UNSET sentinel, and defining that
sentinel independently in every library would create multiple sources of
truth.
The original goal was therefore to have one small, dependency-free library
that could provide a shared UNSET object to the rest of the ecosystem.
The intention was always to return to the library later and expand it with other generally useful sentinel values.
When that time finally came, the question turned out to be less about finding things to add and more about determining which things genuinely belonged here.
The standard library contains many sentinel-like objects, but most of them
are specific to the API that owns them. Re-exporting those objects through
simplibs.sentinels would add another import path without providing a
meaningful abstraction.
Other concepts are useful in particular domains — for example configuration
states such as AUTO or DISABLED — but they are not sufficiently general
to justify making them part of this core library without a concrete need.
The one notable exception is EMPTY.
Python's inspect module already provides a canonical empty sentinel through
inspect.Parameter.empty, and that same object is also used by
inspect.Signature.empty. Creating another EMPTY object in simplibs
would unnecessarily split one established concept into two identities.
Starting with version 0.2.0, simplibs.sentinels.EMPTY therefore adopts
the existing inspect.Parameter.empty object directly.
The result is intentionally small:
UNSET,MISSING, andDEFAULTare concepts owned bysimplibs;EMPTYis an existing canonical sentinel adopted bysimplibs;- domain-specific standard-library sentinels remain in their own APIs;
- no additional sentinel is added merely for completeness.
In that sense, the library's small size is not an unfinished feature list. It is the result of deliberately keeping the lowest-level vocabulary small and unambiguous.
☯️ About simplibs
All libraries in the simplibs (Simple Libraries) ecosystem share a common engineering philosophy:
- Dyslexia-friendly: We actively minimize cognitive load. Code is atomized into small, self-contained units, files are named directly after the logical task they perform, and explanations describe why something is designed, not just what it is.
- Programmer's Zen: Nothing should be missing, and nothing should be superfluous. We value clean execution paths and robust, understandable code architectures over rushed, messy feature sets.
- Defensive Style: We actively anticipate edge cases and failure modes so that only safe operational paths remain. Our code is built to degrade gracefully rather than crash unexpectedly.
- Minimalism: Find the most direct path to the goal in as few operational steps as possible without taking shortcuts on safety, readability, or completeness.
- Code as Craft: Code should be pleasant to look at, readable at a glance, and evoke structural harmony. We treat software engineering as a precision trade.
🤝 Contributing & Community
This is an open-source project built with love and care. We strongly believe in community collaboration and welcome any feedback, bug reports, or feature ideas!
- Want to contribute? Feel free to open an Issue or submit a Pull Request.
- Want to get in touch? If you'd like to discuss the project further, collaborate, or just say hello, feel free to open a GitHub Issue or start a Discussion.
📝 License
This library is released under the MIT License. Build great things!
Metadata
Release files for simplibs-sentinels 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| simplibs_sentinels-0.2.0.tar.gz | 17.4 kB | Without provenance | Details for simplibs_sentinels-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| simplibs_sentinels-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for simplibs_sentinels-0.2.0-py3-none-any.whl |
Total release size: 32.9 kB
Release files / simplibs_sentinels-0.2.0.tar.gz
| Download URL | simplibs_sentinels-0.2.0.tar.gz |
|---|---|
| Size | 17.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
8eb21c9006274936b81bc7a624709b3edca383286ed243392ecbac66d50dd5cc
|
|
BLAKE2b-256 checksum How to use checksums |
6c1042c53e68d6fbbe39c020765eee3ebc8e473cbcf4418f4063d1494050c80d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.9
|
Release files / simplibs_sentinels-0.2.0-py3-none-any.whl
| Download URL | simplibs_sentinels-0.2.0-py3-none-any.whl |
|---|---|
| Size | 15.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d72e9462c3f721e64ec3a52aa023d801b81e0b1ca8ce368557ffc7f93fb05d3a
|
|
BLAKE2b-256 checksum How to use checksums |
d349bb0d2bde152e1142ae1183e8d3d3c8819ff9a191fcef2b2789753f4610fd
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.9
|
Security for simplibs-sentinels 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.