simple-elements

Lightweight utilities and helpers shared across the simple-libs ecosystem — each one self-contained and usable independently in any Python project.

Contents

• Installation
• Sentinels
• About the Simple ecosystem

Installation

pip install simple-elements

Sentinels

UNSET and UnsetType

A sentinel for distinguishing an unset value from an intentionally passed None — because None is a valid Python value with its own meaning. Evaluates as False in a boolean context:

from simple_elements import UNSET, UnsetType

def connect(host: str, timeout: int | UnsetType = UNSET):
    if timeout is UNSET:
        timeout = get_default_timeout()  # not provided → use default
    elif timeout is None:
        timeout = 0                      # None passed intentionally → no timeout

if not UNSET:
    print("UNSET is falsy ✓")            # True — bool(UNSET) == False

Comparison must always use is, never ==:

value is UNSET      # ✓ correct
value == UNSET      # ✗ never do this

About the Simple ecosystem

simple-elements is part of the Simple ecosystem — a collection of small, self-contained Python libraries. Each one solves exactly one thing — but all of them share a common philosophy:

Dyslexia-friendly — minimise mental load. Atomise code into self-contained units, name files after the logic they contain, write explanations that describe why — not just what.

Programmer's zen — nothing should be missing and nothing should be superfluous. The journey is the destination: code should be fully understood; better to go slowly and correctly than quickly and with mistakes. The crystallisation approach — not perfection on the first try, but gradual refinement towards it.

Defensive style — anticipate all possible failure modes so that only safe paths remain. Never raise unexpected errors; degrade gracefully.

Minimalism — find the path to the goal in as few steps as possible, but leave nothing out. Each file has one responsibility.

Code as craft — code should be pleasant to look at and evoke a sense of harmony. Treat code as a small work of art — like a carpenter carving a sculpture. Optimise for the user: everything should make sense without having to study the documentation at length.

These are aspirations — a sense of direction. And that is exactly what the note about the journey becoming the destination is all about. 🙂

The library is covered by tests across all modules. Tests are part of the repository and serve as living documentation of the expected behaviour.