simple-elements 0.1.0__py3-none-any.whl

simple_elements/__init__.py

@@ -0,0 +1,18 @@
+from .sentinels import UnsetType, UNSET
+
+__all__ = [
+    # Sentinel
+    "UnsetType",
+    "UNSET",
+]
+
+
+_DESIGN_NOTES = """
+# simple_elements
+
+## Public API
+| Name                           | Description                                                       |
+|--------------------------------|-------------------------------------------------------------------|
+| `UNSET`                        | Sentinel for an unset value                                       |
+| `UnsetType`                    | Sentinel type — for type annotations                              |
+"""

simple_elements/sentinels/UNSET.py

@@ -0,0 +1,73 @@
+from typing import Final
+
+
+class UnsetType:
+    """Singleton sentinel type representing an unset value."""
+
+    # Attribute for the singleton instance
+    _instance = None
+
+    # Create the singleton instance
+    def __new__(cls):
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+
+    def __repr__(self):
+        return "UNSET"
+
+    def __bool__(self):
+        return False
+
+
+# Sentinel
+UNSET: Final = UnsetType()
+
+
+_DESIGN_NOTES = """
+# UnsetType and UNSET
+
+## Purpose
+A sentinel for distinguishing an unset value from an intentionally passed `None` —
+because `None` is a valid Python value with its own meaning.
+
+## Why not None?
+```python
+def func(value = None):
+    if value is None:
+        # ambiguous — was None passed intentionally, or was the parameter not provided at all?
+```
+```python
+def func(value: UnsetType = UNSET):
+    if value is UNSET:
+        # parameter was not provided → apply default behaviour
+    elif value is None:
+        # None was passed intentionally → specific logic applies
+```
+
+## Singleton
+`UnsetType` is implemented as a singleton — all instances are identical.
+Comparisons must therefore always use `is`, never `==`:
+```python
+value is UNSET      # ✓ correct
+value == UNSET      # ✗ never do this
+```
+
+## __bool__
+`UnsetType.__bool__` returns `False` — `UNSET` therefore behaves as a falsy value:
+```python
+if not value:
+    # true for UNSET, None, False, "", and 0
+```
+For an explicit check, always use `is UNSET`.
+
+## UNSET
+A pre-created singleton instance of `UnsetType` — serves as a shared primitive
+across the entire simple-libs ecosystem. Every library that needs to distinguish
+an unset parameter from `None` imports it from here.
+
+## Notes
+- The `Final` annotation ensures that `UNSET` cannot be reassigned.
+- Both objects (`UnsetType` and `UNSET`) are exported from the library —
+  users may use them in their own type annotations and checks.
+"""

simple_elements/sentinels/__init__.py

@@ -0,0 +1,14 @@
+from .UNSET import UnsetType, UNSET
+
+
+_DESIGN_NOTES = """
+# utils/sentinel
+
+## Contents
+The simple library's sentinel values — exported from the library and available to users.
+
+| Name        | Description                                                  |
+|-------------|--------------------------------------------------------------|
+| `UnsetType` | Singleton type representing an unset value                   |
+| `UNSET`     | A pre-created instance of `UnsetType` — used throughout      |
+"""

simple_elements-0.1.0.dist-info/METADATA

@@ -0,0 +1,113 @@
+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.*

simple_elements-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+simple_elements/__init__.py,sha256=5_ZiGrCSW5u28MEeSD7DoNZ4aZPxtAyzOfRCPCLcm7o,589
+simple_elements/sentinels/UNSET.py,sha256=V3_WOAfNd6IZAIlfBvt0rbTUwjBu21iaz2OJ1Vy1AWI,2049
+simple_elements/sentinels/__init__.py,sha256=EavHIqw4833901oVv_UWqMO71CXJdnzeDBjGJ6WWV_4,514
+simple_elements-0.1.0.dist-info/licenses/LICENSE,sha256=S47IxnGIoMNACXzGEKr80I6y6FKOcIJga-o57WTKfCg,1100
+simple_elements-0.1.0.dist-info/METADATA,sha256=Y5V_fy-W-loX9ocRoFPuBHI4TsrpwifF1U180xWMGI0,4162
+simple_elements-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+simple_elements-0.1.0.dist-info/top_level.txt,sha256=1ki5IH-Ko7C1xNo33v8U61Mx0L9DnyeUamIDHbgXNGM,16
+simple_elements-0.1.0.dist-info/RECORD,,

simple_elements-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

simple_elements-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dalibor Sova (Sudip2708)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

simple_elements-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+simple_elements