Add project files

Author: Fatal1ty

.gitignore

@@ -0,0 +1,66 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+env/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*,cover
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# PyCharm
+.idea
+
+# pyenv
+.python-version
+
+# OSX
+.DS_Store

MANIFEST.in

@@ -0,0 +1,2 @@
+include README.md
+recursive-include maybe_missing py.typed *.pyi

README.md

@@ -0,0 +1,124 @@
+# maybe-missing
+
+`maybe-missing` is a tiny typed helper for one annoyingly real distinction:
+
+- `None` means “the caller explicitly sent null”
+- `MISSING` means “the caller did not send this value at all”
+
+That difference matters in patch APIs, dataclasses, settings layers, and anywhere a database column is nullable but an omitted field should mean “leave it alone”.
+
+## Why this exists
+
+Python’s `Optional[T]` answers only one question: can the value be `None`?
+
+It does **not** answer the other question: was there a value in the first place?
+
+That becomes awkward fast:
+
+- JSON `null` is a valid payload value
+- a nullable Postgres column may need to be set to `NULL` intentionally
+- omitting a field in a PATCH request should usually mean “don’t update it”
+- a dataclass default should sometimes mean “missing”, not “defaulted to null”
+
+So this package gives you exactly two public names:
+
+- `Maybe[T]`
+- `MISSING`
+
+And then gets out of your way.
+
+## Installation
+
+```bash
+pip install maybe-missing
+```
+
+## Usage
+
+```python
+from maybe_missing import Maybe, MISSING
+
+
+def update_display_name(display_name: Maybe[str | None] = MISSING) -> None:
+    if display_name is MISSING:
+        print("leave the existing value alone")
+    elif display_name is None:
+        print("explicitly store NULL")
+    else:
+        print(f"store {display_name!r}")
+```
+
+## Dataclass example
+
+```python
+from dataclasses import dataclass
+
+from maybe_missing import Maybe, MISSING
+
+
+@dataclass(slots=True)
+class UserPatch:
+    nickname: Maybe[str | None] = MISSING
+    bio: Maybe[str | None] = MISSING
+
+
+def apply_patch(patch: UserPatch) -> None:
+    if patch.nickname is not MISSING:
+        # update nickname to a string or to NULL
+        ...
+
+    if patch.bio is not MISSING:
+        # update bio to a string or to NULL
+        ...
+```
+
+## API example
+
+Imagine a request body for partial updates:
+
+```json
+{
+  "nickname": null
+}
+```
+
+This should mean:
+
+- `nickname` was provided
+- its value is explicitly `null`
+- the server should write `NULL`
+
+While this body:
+
+```json
+{}
+```
+
+should mean:
+
+- `nickname` was not provided
+- keep the current value as is
+
+`Maybe[T]` helps model that cleanly in Python code.
+
+## There are only a couple of lines though
+
+Yes.
+
+There are only a couple of lines.
+
+And that’s exactly why it’s more pleasant not to duplicate them across your projects and just do:
+
+```python
+from maybe_missing import Maybe, MISSING
+```
+
+Isn’t it?
+
+## Typing
+
+The package includes `py.typed`, so type checkers and IDEs can treat it as a typed distribution.
+
+## Compatibility
+
+This package currently targets Python 3.10+.

maybe_missing/__init__.py

@@ -0,0 +1,20 @@
+from enum import Enum as _Enum, auto as _auto
+from typing import (
+    Final as _Final,
+    Literal as _Literal,
+    TypeAlias as _TypeAlias,
+    TypeVar as _TypeVar,
+)
+
+__all__ = ["Maybe", "MISSING"]
+
+_T = _TypeVar("_T")
+
+
+class _MissingSentinel(_Enum):
+    MISSING = _auto()
+
+
+Maybe: _TypeAlias = _T | _Literal[_MissingSentinel.MISSING]
+
+MISSING: _Final = _MissingSentinel.MISSING

maybe_missing/__init__.pyi

@@ -0,0 +1,12 @@
+import enum
+import typing
+
+__all__ = ["Maybe", "MISSING"]
+
+_T = typing.TypeVar("_T")
+
+class _MissingSentinel(enum.Enum):
+    MISSING = ...
+
+MISSING: typing.Final[_MissingSentinel]
+Maybe: typing.TypeAlias = _T | typing.Literal[_MissingSentinel.MISSING]

maybe_missing/py.typed

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["setuptools>=77.0.3"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "maybe-missing"
+version = "0.1"
+license = "Apache-2.0"
+description = "A tiny typed sentinel for distinguishing None from not provided"
+readme = "README.md"
+authors = [{ name = "Alexander Tikhonov", email = "random.gauss@gmail.com" }]
+requires-python = ">=3.10"
+keywords = ["typing", "sentinel", "optional", "api", "dataclass", "maybe"]
+classifiers = [
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Development Status :: 5 - Production/Stable",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://github.com/Fatal1ty/maybe-missing"
+
+[tool.setuptools]
+include-package-data = true
+
+[tool.setuptools.packages.find]
+include = ["maybe_missing*"]
+
+[tool.setuptools.package-data]
+maybe_missing = ["py.typed", "*.pyi"]

pyproject.toml

@@ -0,0 +1,32 @@
+import unittest
+
+import maybe_missing
+from maybe_missing import *  # noqa: F403
+
+
+class PublicApiTests(unittest.TestCase):
+    def test_module_exports_only_public_names(self) -> None:
+        self.assertEqual(maybe_missing.__all__, ["Maybe", "MISSING"])
+
+        public_names = {
+            name
+            for name in dir(maybe_missing)
+            if not name.startswith("_") and name not in {"__all__"}
+        }
+        self.assertEqual(public_names, {"Maybe", "MISSING"})
+
+    def test_star_import_respects_all(self) -> None:
+        self.assertIn("Maybe", globals())
+        self.assertIn("MISSING", globals())
+        self.assertIs(MISSING, maybe_missing.MISSING)  # noqa: F405
+
+    def test_missing_is_distinct_from_none(self) -> None:
+        self.assertIsNot(maybe_missing.MISSING, None)
+        value = None
+        missing = maybe_missing.MISSING
+        self.assertIsNone(value)
+        self.assertIsNot(value, missing)
+
+
+if __name__ == "__main__":
+    unittest.main()