Metadata-Version: 2.4
Name: simple-elements
Version: 0.1.0
Summary: Lightweight utilities and helpers shared across the simple-libs ecosystem.
Author-email: "Dalibor Sova (Sudip2708)" <daliborsova@seznam.cz>
License-Expression: MIT
Project-URL: Homepage, https://github.com/simple-libs/simple-elements
Project-URL: Repository, https://github.com/simple-libs/simple-elements
Project-URL: Issues, https://github.com/simple-libs/simple-elements/issues
Project-URL: Changelog, https://github.com/simple-libs/simple-elements/blob/main/CHANGELOG.md
Keywords: utilities,helpers,sentinel,tools,simple-libs
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Dynamic: license-file

# simple-elements

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

![Python](https://img.shields.io/badge/python-3.11%2B-blue)
![Licence](https://img.shields.io/badge/licence-MIT-green)
![PyPI](https://img.shields.io/pypi/v/simple-elements)

---

## Contents

- [Installation](#installation)
- [Sentinels](#sentinels)
- [About the Simple ecosystem](#about-the-simple-ecosystem)

---

## Installation
```bash
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:
```python
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 `==`:
```python
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.*
