compat-sentinel 0.1.0__tar.gz

compat_sentinel-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+.DS_Store
+.venv/
+__pycache__/
+.pytest_cache/
+.coverage
+htmlcov/
+*.pyc
+build/
+dist/
+*.egg-info/
+tests/.uv-venvs/
+*-old.py

compat_sentinel-0.1.0/AGENTS.md

@@ -0,0 +1,92 @@
+# AGENTS
+
+## Scope
+
+This file defines repository-specific working instructions for `compat-sentinel`.
+
+## Agent requests: review vs edit
+
+- When the user asks to review, verify, analyze, assess, report, or check,
+  respond with read-only analysis only.
+- Do not change files or implement fixes unless the user explicitly asks for
+  edits, fixes, implementation, or an update.
+- If analysis surfaces a problem, describe it and wait for direction rather
+  than patching the tree unprompted.
+
+## Start here
+
+- `README.md` is the public contract: `sentinel(name, /, *, repr=None)`,
+  matching PEP 661.
+- On Python 3.15 and later, `compat_sentinel.sentinel` is `builtins.sentinel`.
+  Earlier versions use `src/compat_sentinel/_sentinel.py`.
+- Pickle identity comes from importing `__module__` and looking up `__name__`.
+  There is no sentinel registry.
+
+## Roll-build method
+
+- When the user asks for a phased rollout using the roll-build method, start
+  from a clean git tree and tag that point before implementation begins.
+- Use the requested start tag name when one is given. If none is given, ask or
+  use a clearly scoped phase-start tag name.
+- An unqualified `roll-build` means: run all phases for that plan in sequence,
+  committing and tagging each completed phase, and continue into the next phase
+  without stopping unless the guardrails below require a pause.
+- Run the roll-build in the current owning checkout and current branch. Do not
+  create git worktrees, sibling checkouts, or parallel rollout branches unless
+  the user explicitly asks for them in that request.
+- Do not split phases or adjacent roll-build requests into parallel branches.
+  If one roll-build has already produced commits, the next roll-build starts on
+  top of those commits after they are integrated into the current branch.
+- If the current branch is not the intended integration branch, stop and ask
+  before creating or switching branches. Do not invent a branch/worktree strategy
+  from the tag prefix.
+- Implement one phase at a time.
+- After a phase is complete, only commit and tag it if:
+  - the phase goal is actually met
+  - focused verification passes
+  - the remaining ambiguities are minor and non-blocking
+- If there are no more phases, or if confidence drops because of material
+  ambiguity or instability, stop and wait instead of forcing the next phase.
+- If work starts cycling on the same persistent bug or bug family, stop, report
+  the cycle clearly, and ask for direction.
+
+## When to push back on roll-build
+
+- Push back when the next phase has too many unresolved ambiguities to produce a
+  trustworthy checkpoint.
+- Push back when the requested phase is too large or too coupled to complete
+  safely as one checkpoint.
+- Push back when implementation reveals facts that materially break the current
+  design or plan assumptions.
+- Push back when the resulting checkpoint would be misleadingly partial,
+  unstable, or hard to recover from.
+
+## Test-led semantics guardrail
+
+- Do not change public semantics merely to make a test pass without updating the
+  design/docs.
+- If a red test implies a real semantic change rather than a bug fix or missing
+  coverage, stop and update the design/docs before implementing the change.
+- It is acceptable to tighten tests, fix assumptions, or fix correctness bugs
+  that clearly match the current design intent.
+- It is not acceptable to quietly redefine semantics to satisfy a convenient
+  test expectation.
+
+## Test commands
+
+- Focused tests: `uv run --with pytest pytest <test-path> -q`
+- Full suite: `uv run --with pytest pytest -q`
+
+<!-- gearu:agents:start -->
+## Releases
+
+- This repository uses [Gearu](https://owebeeone.github.io/gearu/) for release
+  preparation.
+- Read `RELEASE.md` before planning or performing a release.
+- `gearu plan VERSION` and `gearu plan --bump LEVEL` are read-only. Do not run
+  `gearu release`, push a release tag, or create a GitHub Release unless the
+  user explicitly requests it.
+- Never move or reuse a release tag. Correct released content with a new version.
+- Never publish directly to PyPI, crates.io, or npm from a local checkout.
+  Registry publication belongs in the repository's release workflow.
+<!-- gearu:agents:end -->

compat_sentinel-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gianni Mariani
+
+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.

compat_sentinel-0.1.0/PKG-INFO

@@ -0,0 +1,76 @@
+Metadata-Version: 2.5
+Name: compat-sentinel
+Version: 0.1.0
+Summary: PEP 661 sentinel for Python versions before 3.15
+Project-URL: Repository, https://github.com/owebeeone/compat-sentinel
+Project-URL: Issues, https://github.com/owebeeone/compat-sentinel/issues
+Project-URL: Source, https://github.com/owebeeone/compat-sentinel
+Author: compat-sentinel contributors
+License: MIT License
+        
+        Copyright (c) 2026 Gianni Mariani
+        
+        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.
+License-File: LICENSE
+Keywords: compatibility,pep661,pickle,sentinel
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Requires-Python: >=3.12
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# compat-sentinel
+
+PEP 661 `sentinel` for Python 3.12 and later.
+
+On Python 3.15 and later, `compat_sentinel.sentinel` is the builtin. On older
+interpreters it is a local implementation with the same constructor, copy
+behavior, and pickle lookup.
+
+```python
+from compat_sentinel import sentinel
+
+MISSING = sentinel("MISSING")
+DEFAULT = sentinel("DEFAULT", repr="<default>")
+```
+
+Each call returns a new object. A sentinel pickles back to itself when it can
+be imported from its module under `__name__`:
+
+```python
+MISSING = sentinel("MISSING")
+
+class Box:
+    SHORT = sentinel("Box.SHORT")
+```
+
+A sentinel created in a local scope and never stored under that name does not
+pickle. `__module__` is taken from the caller and is writable; pickle uses the
+value present at dump time.
+
+`int | MISSING` and `MISSING | str` build a `typing.Union`.

compat_sentinel-0.1.0/README.md

@@ -0,0 +1,30 @@
+# compat-sentinel
+
+PEP 661 `sentinel` for Python 3.12 and later.
+
+On Python 3.15 and later, `compat_sentinel.sentinel` is the builtin. On older
+interpreters it is a local implementation with the same constructor, copy
+behavior, and pickle lookup.
+
+```python
+from compat_sentinel import sentinel
+
+MISSING = sentinel("MISSING")
+DEFAULT = sentinel("DEFAULT", repr="<default>")
+```
+
+Each call returns a new object. A sentinel pickles back to itself when it can
+be imported from its module under `__name__`:
+
+```python
+MISSING = sentinel("MISSING")
+
+class Box:
+    SHORT = sentinel("Box.SHORT")
+```
+
+A sentinel created in a local scope and never stored under that name does not
+pickle. `__module__` is taken from the caller and is writable; pickle uses the
+value present at dump time.
+
+`int | MISSING` and `MISSING | str` build a `typing.Union`.

compat_sentinel-0.1.0/RELEASE.md

@@ -0,0 +1,150 @@
+# Release Process
+
+## compat-sentinel Configuration
+
+`gearu.toml` releases the Python distribution from `main`, using immutable
+`v<version>` tags and the `owebeeone/compat-sentinel` GitHub repository.
+
+- Gearu updates `project.version` in `pyproject.toml` and refreshes `uv.lock`.
+- The first candidate check synchronizes the public `compat_sentinel.__version__`
+  mirror in `src/compat_sentinel/__init__.py`. Verification after committing only
+  checks that mirror; it never repairs a tagged candidate.
+- Candidate and exact-commit verification run pytest on every version listed in
+  `tool.compat-sentinel.test-matrix` and check the sdist and wheel with Twine.
+- GitHub Release creation triggers `.github/workflows/publish.yml`, which builds
+  a pure-Python wheel and sdist and publishes them through PyPI trusted
+  publishing for `owebeeone/compat-sentinel`. Gearu does not upload packages
+  locally.
+
+Prerequisites: Gearu 0.1.1 or later, Git, `uv`, and `gh` authenticated for this
+repository when publishing a GitHub Release. Run all commands from the
+repository root. Commit the configuration and docs changes before asking Gearu
+to plan: even planning requires a clean tree.
+
+The configuration contains no fixed next version. Start with
+`gearu plan --bump patch`, review its proposed version, and use that explicit
+version for any subsequently authorized release. Planning does not run the
+checks; it reports the intended changes and commands. Gearu's plan lists the
+manifest update, while the version mirror and lockfile are refreshed during
+candidate preparation.
+
+<!-- gearu:release:start -->
+## Gearu Release Process
+
+Gearu prepares and verifies the repository, creates an immutable tag, and can
+create the GitHub Release that starts this repository's publication workflow.
+It does not publish directly to package registries.
+
+Full documentation: <https://owebeeone.github.io/gearu/>
+
+### Install
+
+Install the released tool with:
+
+```sh
+uv tool install gearu
+```
+
+Upgrade an existing installation with:
+
+```sh
+uv tool upgrade gearu
+```
+
+To test the unreleased `main` branch, install it directly from its repository:
+
+```sh
+uv tool install git+https://github.com/owebeeone/gearu.git
+```
+
+Verify the installation with `gearu --version`.
+
+### Preconditions
+
+- Read `gearu.toml` and this repository's release workflow.
+- Choose an explicit release version or an explicit major, minor, or patch bump.
+  Gearu does not infer release intent from commits.
+- Use a clean checkout on the branch configured by `project.branch`.
+- Synchronize configured release and source branches with their remote.
+- Release required cross-repository dependencies first.
+- Install and authenticate `gh` before requesting GitHub Release creation.
+
+### Plan
+
+Always inspect the read-only plan first:
+
+```sh
+gearu plan VERSION
+```
+
+Or ask Gearu to select the next version:
+
+```sh
+gearu plan --bump patch
+gearu plan --bump minor
+gearu plan --bump major
+```
+
+Gearu compares configured package versions with valid local and remote release
+tags, then bumps the highest version. It reads remote tags directly and does not
+fetch or create local tags while planning.
+
+For a release candidate, use a numbered version such as `1.2.3-rc.1`.
+
+Override a configured dependency tag only when the release intentionally uses a
+different version:
+
+```sh
+gearu plan VERSION --dependency-tag DEPENDENCY=TAG
+```
+
+### Prepare the Local Release
+
+After reviewing the plan:
+
+```sh
+gearu release VERSION
+```
+
+The release command can select the version itself:
+
+```sh
+gearu release --bump minor
+```
+
+This recalculates the next version at release time. To lock the version reviewed
+in a prior bump plan, pass that plan's reported `VERSION` explicitly.
+
+Gearu builds and tests in a temporary worktree. Only a successful candidate is
+applied to the local release branch and tagged. This step does not change a
+remote repository.
+
+### Push and Create the GitHub Release
+
+Push the exact release commit and tag atomically:
+
+```sh
+gearu release VERSION --push
+```
+
+Create the GitHub Release after that push:
+
+```sh
+gearu release VERSION --push --github-release
+```
+
+The final command starts workflows listening for `release.published`, including
+package publication and documentation deployment where configured.
+
+### Recovery
+
+- If candidate checks fail, fix the problem and rerun; the normal checkout is
+  left unchanged.
+- If local preparation succeeds, rerun the same version with `--push`.
+- If the push succeeds but GitHub Release creation fails, rerun with
+  `--push --github-release`.
+- If released contents must change, use a new patch or release-candidate version.
+  Never move or replace the existing tag.
+- If only a publication workflow fails, repair and rerun that workflow for the
+  same GitHub Release.
+<!-- gearu:release:end -->

compat_sentinel-0.1.0/compat_sentinel/__init__.py

@@ -0,0 +1,15 @@
+"""compat_sentinel — PEP 661 sentinel for Python 3.12 and later."""
+
+__version__ = "0.1.0"
+
+try:
+    from builtins import sentinel as sentinel
+except ImportError:
+    from compat_sentinel._sentinel import sentinel
+
+    sentinel.__module__ = __name__
+
+__all__ = [
+    "__version__",
+    "sentinel",
+]

compat_sentinel-0.1.0/compat_sentinel/_sentinel.py

@@ -0,0 +1,98 @@
+"""PEP 661 ``sentinel`` for interpreters that do not provide the builtin."""
+
+from __future__ import annotations
+
+import sys
+from typing import Union
+
+
+class sentinel:
+    """Unique sentinel object.
+
+    ``sentinel(name, /, *, repr=None)`` matches the Python 3.15 builtin.
+    Each call returns a new object. Pickle preserves identity only when the
+    sentinel can be imported from its ``__module__`` under ``__name__``.
+    """
+
+    __slots__ = ("_name", "_module", "_repr")
+
+    def __init_subclass__(cls) -> None:
+        raise TypeError("subclassing sentinel is not supported")
+
+    def __new__(cls, name: str, /, *, repr: str | None = None) -> sentinel:
+        if cls is not sentinel:
+            raise TypeError("sentinel() may not be invoked from a subclass")
+        if not isinstance(name, str):
+            raise TypeError(f"sentinel name must be a str, not {type(name).__name__}")
+        if repr is not None and not isinstance(repr, str):
+            raise TypeError(f"sentinel repr must be a str, not {type(repr).__name__}")
+
+        instance = object.__new__(cls)
+        object.__setattr__(instance, "_name", name)
+        object.__setattr__(instance, "_module", _caller_module())
+        object.__setattr__(instance, "_repr", name if repr is None else repr)
+        return instance
+
+    def __getattribute__(self, name: str) -> object:
+        if name == "__name__":
+            return object.__getattribute__(self, "_name")
+        if name == "__module__":
+            return object.__getattribute__(self, "_module")
+        return object.__getattribute__(self, name)
+
+    def __setattr__(self, name: str, value: object) -> None:
+        if name == "__module__":
+            if not isinstance(value, str):
+                raise TypeError(f"__module__ must be a str, not {type(value).__name__}")
+            object.__setattr__(self, "_module", value)
+            return
+        if name == "__name__":
+            raise AttributeError("readonly attribute")
+        raise AttributeError(f"'sentinel' object has no attribute {name!r}")
+
+    def __delattr__(self, name: str) -> None:
+        raise AttributeError(f"'sentinel' object has no attribute {name!r}")
+
+    def __repr__(self) -> str:
+        return object.__getattribute__(self, "_repr")
+
+    def __str__(self) -> str:
+        return object.__getattribute__(self, "_repr")
+
+    def __bool__(self) -> bool:
+        return True
+
+    def __hash__(self) -> int:
+        return object.__hash__(self)
+
+    def __eq__(self, other: object) -> bool:
+        return self is other
+
+    def __copy__(self) -> sentinel:
+        return self
+
+    def __deepcopy__(self, memo: object) -> sentinel:
+        return self
+
+    def __reduce__(self) -> str:
+        return object.__getattribute__(self, "_name")
+
+    def __or__(self, other: object) -> object:
+        return Union[self, other]
+
+    def __ror__(self, other: object) -> object:
+        return Union[other, self]
+
+
+def _caller_module() -> str:
+    """Return the module that called ``sentinel()``.
+
+    ``__new__`` is the direct caller, so the user frame is one level above it.
+    """
+
+    module_name = sys._getframemodulename(2)
+    if module_name is None:
+        module_name = sys._getframe(2).f_globals.get("__name__", "__main__")
+    if not isinstance(module_name, str) or module_name == "":
+        return "__main__"
+    return module_name

compat_sentinel-0.1.0/gearu.toml

@@ -0,0 +1,34 @@
+[project]
+name = "compat-sentinel"
+branch = "main"
+remote = "origin"
+tag_prefix = "v"
+github_repo = "owebeeone/compat-sentinel"
+
+[python]
+version = "static"
+manifest = "pyproject.toml"
+lockfiles = ["uv.lock"]
+lock_command = ["uv", "lock", "--python", "3.12"]
+
+[release]
+managed_files = ["src/compat_sentinel/__init__.py"]
+checks = [
+    ["uv", "run", "--no-project", "--python", "3.12", "python", "scripts/release_checks.py", "sync-version", "{python_version}"],
+    ["uv", "run", "--no-project", "--python", "3.12", "python", "scripts/release_checks.py", "verify-version", "{python_version}"],
+    ["uv", "run", "--no-project", "--python", "3.12", "python", "scripts/release_checks.py", "test-matrix", "{python_version}"],
+    ["uv", "run", "--no-project", "--python", "3.12", "--with", "build", "--with", "twine", "python", "scripts/release_checks.py", "distributions", "{python_version}"],
+]
+# Verification after the candidate commit must not rewrite its version mirror.
+exact_checks = [
+    ["uv", "run", "--no-project", "--python", "3.12", "python", "scripts/release_checks.py", "verify-version", "{python_version}"],
+    ["uv", "run", "--no-project", "--python", "3.12", "python", "scripts/release_checks.py", "test-matrix", "{python_version}"],
+    ["uv", "run", "--no-project", "--python", "3.12", "--with", "build", "--with", "twine", "python", "scripts/release_checks.py", "distributions", "{python_version}"],
+]
+github_notes = """
+compat-sentinel {tag}.
+
+See the commit history for changes. The release workflow verifies the supported
+Python versions and publishes a pure-Python wheel and source distribution to
+PyPI.
+"""

compat_sentinel-0.1.0/pyproject.toml

@@ -0,0 +1,67 @@
+[build-system]
+requires = ["hatchling>=1.24"]
+build-backend = "hatchling.build"
+
+[project]
+name = "compat-sentinel"
+version = "0.1.0"
+description = "PEP 661 sentinel for Python versions before 3.15"
+readme = "README.md"
+requires-python = ">=3.12"
+authors = [{ name = "compat-sentinel contributors" }]
+license = { file = "LICENSE" }
+keywords = ["sentinel", "pep661", "compatibility", "pickle"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Programming Language :: Python :: 3.15",
+]
+
+[project.urls]
+Repository = "https://github.com/owebeeone/compat-sentinel"
+Issues = "https://github.com/owebeeone/compat-sentinel/issues"
+Source = "https://github.com/owebeeone/compat-sentinel"
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0"]
+test = ["pytest>=7.0"]
+
+[tool.uv]
+exclude-newer = "1 week"
+
+[tool.hatch.version]
+path = "src/compat_sentinel/__init__.py"
+
+[tool.hatch.build]
+sources = ["src"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "src/compat_sentinel",
+  "tests",
+  "scripts/release_checks.py",
+  "gearu.toml",
+  "RELEASE.md",
+  "AGENTS.md",
+  "LICENSE",
+  "README.md",
+]
+
+# Run: uv run --with pytest pytest -q
+[tool.pytest.ini_options]
+pythonpath = [".", "src", "tests"]
+testpaths = ["tests"]
+
+[tool.compat-sentinel.test-matrix]
+python = ["3.12", "3.13", "3.14", "3.15"]
+
+[tool.pyright]
+extraPaths = ["src"]
+
+[tool.basedpyright]
+extraPaths = ["src"]

compat_sentinel-0.1.0/scripts/release_checks.py

@@ -0,0 +1,162 @@
+"""Version synchronization and isolated distribution checks for Gearu."""
+
+from __future__ import annotations
+
+import argparse
+import ast
+import os
+from pathlib import Path
+import subprocess
+import sys
+import tempfile
+import tomllib
+
+
+ROOT = Path(__file__).resolve().parents[1]
+PACKAGE = "compat-sentinel"
+
+
+def _version_assignment(source: str) -> ast.Assign:
+    assignments = [
+        node
+        for node in ast.parse(source).body
+        if isinstance(node, ast.Assign)
+        and any(isinstance(target, ast.Name) and target.id == "__version__" for target in node.targets)
+    ]
+    if len(assignments) != 1:
+        raise ValueError("expected one top-level __version__ assignment")
+    assignment = assignments[0]
+    if (
+        len(assignment.targets) != 1
+        or not isinstance(assignment.value, ast.Constant)
+        or not isinstance(assignment.value.value, str)
+        or assignment.lineno != assignment.end_lineno
+    ):
+        raise ValueError("__version__ must be a standalone string assignment")
+    line = source.splitlines()[assignment.lineno - 1]
+    if line[:assignment.col_offset].strip() or line[assignment.end_col_offset:].strip():
+        raise ValueError("__version__ must be a standalone string assignment")
+    return assignment
+
+
+def _project(root: Path) -> dict:
+    return tomllib.loads((root / "pyproject.toml").read_text(encoding="utf-8"))
+
+
+def _verify_manifest(root: Path, version: str) -> None:
+    project = _project(root)["project"]
+    if project["name"] != PACKAGE or project["version"] != version:
+        raise ValueError(f"pyproject.toml must declare {PACKAGE} {version}")
+
+
+def sync_version(root: Path, version: str) -> None:
+    _verify_manifest(root, version)
+    path = root / "src" / "compat_sentinel" / "__init__.py"
+    source = path.read_text(encoding="utf-8")
+    assignment = _version_assignment(source)
+    if assignment.value.value == version:
+        return
+    lines = source.splitlines(keepends=True)
+    lines[assignment.lineno - 1] = f"__version__ = {version!r}\n"
+    path.write_text("".join(lines), encoding="utf-8")
+
+
+def verify_version(root: Path, version: str) -> None:
+    _verify_manifest(root, version)
+    source = (root / "src" / "compat_sentinel" / "__init__.py").read_text(encoding="utf-8")
+    if _version_assignment(source).value.value != version:
+        raise ValueError(f"compat_sentinel.__version__ must be {version}")
+    lock = tomllib.loads((root / "uv.lock").read_text(encoding="utf-8"))
+    packages = [package for package in lock["package"] if package["name"] == PACKAGE]
+    if len(packages) != 1 or packages[0]["version"] != version:
+        raise ValueError(f"uv.lock must record {PACKAGE} {version}")
+
+
+def check_test_matrix(root: Path, version: str) -> None:
+    verify_version(root, version)
+    versions = _project(root)["tool"]["compat-sentinel"]["test-matrix"]["python"]
+    for python in versions:
+        subprocess.run(
+            [
+                "uv", "run", "--no-project", "--python", str(python),
+                "--with", "pytest", "pytest", "-q",
+            ],
+            cwd=root,
+            check=True,
+        )
+
+
+def check_distributions(root: Path, version: str) -> None:
+    verify_version(root, version)
+    env = os.environ.copy()
+    env.pop("PYTHONPATH", None)
+    env.pop("PYTHONHOME", None)
+    with tempfile.TemporaryDirectory(prefix="compat-sentinel-release-check-") as directory:
+        temporary = Path(directory)
+        dist = temporary / "dist"
+        subprocess.run(
+            [sys.executable, "-m", "build", "--sdist", "--wheel", "--outdir", str(dist)],
+            cwd=root,
+            env=env,
+            check=True,
+        )
+        wheels = list(dist.glob("*.whl"))
+        sdists = list(dist.glob("*.tar.gz"))
+        if len(wheels) != 1 or len(sdists) != 1:
+            raise ValueError("expected exactly one wheel and one source distribution")
+        subprocess.run(
+            [sys.executable, "-m", "twine", "check", str(wheels[0]), str(sdists[0])],
+            cwd=temporary,
+            env=env,
+            check=True,
+        )
+        environment = temporary / "venv"
+        subprocess.run(
+            ["uv", "venv", "--python", sys.executable, str(environment)],
+            cwd=temporary,
+            env=env,
+            check=True,
+        )
+        python = environment / ("Scripts/python.exe" if os.name == "nt" else "bin/python")
+        subprocess.run(
+            ["uv", "pip", "install", "--python", str(python), str(wheels[0])],
+            cwd=temporary,
+            env=env,
+            check=True,
+        )
+        subprocess.run(
+            [
+                str(python), "-I", "-c",
+                "import copy, sys; from importlib.metadata import version; "
+                "import compat_sentinel; from compat_sentinel import sentinel; "
+                "assert compat_sentinel.__version__ == version('compat-sentinel') == sys.argv[1]; "
+                "missing = sentinel('MISSING'); "
+                "assert repr(missing) == 'MISSING'; "
+                "assert copy.copy(missing) is missing",
+                version,
+            ],
+            cwd=temporary,
+            env=env,
+            check=True,
+        )
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "command", choices=("sync-version", "verify-version", "test-matrix", "distributions"),
+    )
+    parser.add_argument("version")
+    args = parser.parse_args()
+    if args.command == "sync-version":
+        sync_version(ROOT, args.version)
+    elif args.command == "verify-version":
+        verify_version(ROOT, args.version)
+    elif args.command == "test-matrix":
+        check_test_matrix(ROOT, args.version)
+    else:
+        check_distributions(ROOT, args.version)
+
+
+if __name__ == "__main__":
+    main()

compat_sentinel-0.1.0/tests/sentinel_subjects.py

@@ -0,0 +1,12 @@
+"""Importable sentinels used to check pickle identity."""
+
+from compat_sentinel import sentinel
+
+
+MISSING = sentinel("MISSING")
+CUSTOM = sentinel("CUSTOM", repr="<custom>")
+SAME_NAME = sentinel("MISSING")
+
+
+class Box:
+    SHORT = sentinel("Box.SHORT")

compat_sentinel-0.1.0/tests/test_sentinel.py

@@ -0,0 +1,213 @@
+from __future__ import annotations
+
+import copy
+import os
+from pathlib import Path
+import pickle
+import subprocess
+import sys
+import typing
+import weakref
+
+import pytest
+
+from compat_sentinel import sentinel
+import sentinel_subjects
+
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def test_each_call_returns_a_new_object() -> None:
+    left = sentinel("MISSING")
+    right = sentinel("MISSING")
+
+    assert left is not right
+    assert left == left
+    assert left != right
+    assert (left == "MISSING") is False
+
+
+def test_repr_name_and_custom_repr() -> None:
+    value = sentinel("MISSING")
+    custom = sentinel("MISSING", repr="<missing>")
+
+    assert repr(value) == "MISSING"
+    assert str(value) == "MISSING"
+    assert repr(custom) == "<missing>"
+    assert str(custom) == "<missing>"
+    assert value.__name__ == "MISSING"
+    assert custom.__name__ == "MISSING"
+
+
+def test_constructor_rejects_bad_arguments() -> None:
+    with pytest.raises(TypeError):
+        sentinel("MISSING", "<missing>")
+    with pytest.raises(TypeError):
+        sentinel(name="MISSING")
+    with pytest.raises(TypeError):
+        sentinel(1)
+    with pytest.raises(TypeError):
+        sentinel("MISSING", repr=1)
+
+
+def test_caller_module_is_recorded() -> None:
+    value = sentinel("LOCAL")
+
+    assert value.__module__ == __name__
+
+
+def test_attributes_are_closed() -> None:
+    value = sentinel("MISSING")
+
+    with pytest.raises(AttributeError):
+        value.__name__ = "OTHER"
+    with pytest.raises(AttributeError):
+        value.extra = 1
+    with pytest.raises(AttributeError):
+        del value.__name__
+
+    value.__module__ = "other.module"
+    assert value.__module__ == "other.module"
+    with pytest.raises(TypeError):
+        value.__module__ = 1
+
+
+def test_sentinel_is_truthy_and_hashable() -> None:
+    value = sentinel("MISSING")
+
+    assert bool(value) is True
+    assert {value: "present"}[value] == "present"
+
+
+def test_copy_preserves_identity() -> None:
+    value = sentinel("MISSING")
+
+    assert copy.copy(value) is value
+    assert copy.deepcopy(value) is value
+
+
+def test_ordering_and_weakrefs_are_rejected() -> None:
+    left = sentinel("LEFT")
+    right = sentinel("RIGHT")
+
+    with pytest.raises(TypeError):
+        left < right
+    with pytest.raises(TypeError):
+        weakref.ref(left)
+
+
+def test_subclassing_is_rejected() -> None:
+    with pytest.raises(TypeError):
+
+        class Child(sentinel):
+            pass
+
+
+def test_union_accepts_sentinel_on_either_side() -> None:
+    value = sentinel("MISSING")
+    forward = int | value
+    reverse = value | str
+
+    assert forward == typing.Union[int, value]
+    assert reverse == typing.Union[value, str]
+    assert value in typing.get_args(forward)
+    assert value in typing.get_args(reverse)
+
+
+def test_module_global_pickle_preserves_identity() -> None:
+    restored = pickle.loads(pickle.dumps(sentinel_subjects.MISSING))
+
+    assert restored is sentinel_subjects.MISSING
+
+
+def test_custom_repr_survives_pickle() -> None:
+    restored = pickle.loads(pickle.dumps(sentinel_subjects.CUSTOM))
+
+    assert restored is sentinel_subjects.CUSTOM
+    assert repr(restored) == "<custom>"
+
+
+def test_pickle_uses_module_and_name_lookup() -> None:
+    blob = pickle.dumps(sentinel_subjects.MISSING)
+
+    assert b"sentinel_subjects" in blob
+    assert b"MISSING" in blob
+    assert b"_reconstruct" not in blob
+
+
+def test_same_name_does_not_share_pickle_identity() -> None:
+    assert sentinel_subjects.SAME_NAME is not sentinel_subjects.MISSING
+    with pytest.raises(pickle.PicklingError):
+        pickle.dumps(sentinel_subjects.SAME_NAME)
+
+
+def test_class_attribute_pickle_preserves_identity() -> None:
+    restored = pickle.loads(pickle.dumps(sentinel_subjects.Box.SHORT))
+
+    assert restored is sentinel_subjects.Box.SHORT
+    assert repr(restored) == "Box.SHORT"
+
+
+def test_unassigned_sentinel_is_not_picklable() -> None:
+    value = sentinel("EPHEMERAL")
+
+    with pytest.raises(pickle.PicklingError):
+        pickle.dumps(value)
+
+
+def test_writable_module_controls_pickle_lookup() -> None:
+    holder = sentinel("HOLDER")
+    globals()["HOLDER"] = holder
+    try:
+        assert pickle.loads(pickle.dumps(holder)) is holder
+        holder.__module__ = "not.a.real.module"
+        with pytest.raises(pickle.PicklingError):
+            pickle.dumps(holder)
+    finally:
+        del globals()["HOLDER"]
+
+
+def test_other_process_resolves_the_defining_module() -> None:
+    env = os.environ.copy()
+    env["PYTHONPATH"] = os.pathsep.join(
+        [str(ROOT / "src"), str(ROOT / "tests"), env.get("PYTHONPATH", "")]
+    )
+    env.pop("PYTHONSAFEPATH", None)
+    script = """
+import pickle
+import sys
+
+blob = sys.stdin.buffer.read()
+restored = pickle.loads(blob)
+import sentinel_subjects
+print("missing", restored is sentinel_subjects.MISSING)
+print("repr", repr(restored))
+"""
+    completed = subprocess.run(
+        [sys.executable, "-c", script],
+        input=pickle.dumps(sentinel_subjects.CUSTOM),
+        capture_output=True,
+        env=env,
+        check=False,
+    )
+
+    assert completed.returncode == 0, completed.stderr.decode()
+    assert completed.stdout.decode().splitlines() == [
+        "missing False",
+        "repr <custom>",
+    ]
+
+    completed = subprocess.run(
+        [sys.executable, "-c", script],
+        input=pickle.dumps(sentinel_subjects.MISSING),
+        capture_output=True,
+        env=env,
+        check=False,
+    )
+
+    assert completed.returncode == 0, completed.stderr.decode()
+    assert completed.stdout.decode().splitlines() == [
+        "missing True",
+        "repr MISSING",
+    ]