nox-python-standards 0.2.1__py3-none-any.whl

nox_python_standards/__init__.py

@@ -0,0 +1,2 @@
+# src/nox_python_standards/__init__.py
+from __future__ import annotations

nox_python_standards/__main__.py

@@ -0,0 +1,6 @@
+# src/nox_python_standards/__main__.py
+from __future__ import annotations
+
+from nox_python_standards.cli import main
+
+raise SystemExit(main())

nox_python_standards/cli.py

@@ -0,0 +1,45 @@
+# src/nox_python_standards/cli.py
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+import sys
+from typing import cast
+
+from nox_python_standards.config import Configuration, release_version
+from nox_python_standards.repository import StandardsError, project_root
+from nox_python_standards.versions import check_versions
+
+
+def parser() -> argparse.ArgumentParser:
+    result = argparse.ArgumentParser(prog="nox-py-standards")
+    result.add_argument("--version", action="version", version=release_version())
+    result.add_argument(
+        "--root", type=Path, help="Consumer Git root (default: current Git root)"
+    )
+    result.add_argument("command", choices=("check", "sync"))
+    return result
+
+
+def main(arguments: list[str] | None = None) -> int:
+    options = parser().parse_args(arguments)
+    command = cast(str, options.command)
+    try:
+        root = project_root(cast(Path | None, options.root))
+        configuration = Configuration.read(root)
+        if command == "sync":
+            configuration.sync()
+        else:
+            configuration.check()
+            check_versions(configuration)
+        sys.stdout.write(
+            f"nox-python-standards {release_version()}: {command} passed\n"
+        )
+        return 0
+    except (StandardsError, OSError, UnicodeError) as exc:
+        sys.stderr.write(f"nox-py-standards: {exc}\n")
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

nox_python_standards/config.py

@@ -0,0 +1,286 @@
+# src/nox_python_standards/config.py
+from __future__ import annotations
+
+from dataclasses import dataclass
+from importlib import metadata, resources
+import json
+import os
+from pathlib import Path
+import tempfile
+import tomllib
+from typing import cast
+
+import tomlkit
+from tomlkit.items import Table
+
+from nox_python_standards.repository import (
+    StandardsError,
+    files,
+    in_scope,
+    require_regular,
+)
+
+SNAPSHOT = Path(".noxala/PYTHON_CONVENTIONS.md")
+_RESOURCE_ROOT = resources.files("nox_python_standards").joinpath("resources")
+
+
+def resource(name: str) -> str:
+    return _RESOURCE_ROOT.joinpath(name).read_text(encoding="utf-8")
+
+
+def release_version() -> str:
+    return metadata.version("nox-python-standards")
+
+
+def policy() -> dict[str, object]:
+    return cast(dict[str, object], json.loads(resource("policy.json")))
+
+
+def ownership() -> dict[str, str]:
+    return cast(dict[str, str], json.loads(resource("ownership.json")))
+
+
+def table(value: object, name: str) -> dict[str, object]:
+    if not isinstance(value, dict):
+        raise StandardsError(f"{name}: expected a TOML table")
+    return cast(dict[str, object], value)
+
+
+def strings(value: object) -> bool:
+    return isinstance(value, list) and all(
+        isinstance(item, str) for item in cast(list[object], value)
+    )
+
+
+def same(left: object, right: object) -> bool:
+    if type(left) is not type(right):
+        return False
+    if isinstance(left, list):
+        a, b = cast(list[object], left), cast(list[object], right)
+        return len(a) == len(b) and all(same(x, y) for x, y in zip(a, b, strict=True))
+    return left == right
+
+
+def local_valid(value: object, kind: str) -> bool:
+    if kind == "string":
+        return isinstance(value, str) and bool(value)
+    if kind == "strings":
+        return strings(value)
+    if kind == "private-test-rules":
+        return isinstance(value, dict) and all(
+            key == "test/**/*.py" and same(rules, ["SLF001"])
+            for key, rules in cast(dict[str, object], value).items()
+        )
+    if kind == "test-environments":
+        return isinstance(value, list) and all(
+            same(environment, {"root": "test", "reportPrivateUsage": "none"})
+            for environment in cast(list[object], value)
+        )
+    raise StandardsError(f"Unknown installed ownership schema: {kind}")
+
+
+def validate_boundary(tool: dict[str, object]) -> None:
+    shared, local = policy(), ownership()
+    keys = set(shared) | set(local)
+
+    def visit(value: object, prefix: str) -> None:
+        if prefix in shared:
+            return  # Missing/wrong shared values are checked separately and repairable.
+        if prefix in local:
+            if not local_valid(value, local[prefix]):
+                raise StandardsError(
+                    f"pyproject.toml: tool.{prefix}: invalid consumer value {value!r}; "
+                    f"expected {local[prefix]} (see installed ownership.json)"
+                )
+            return
+        if not any(key.startswith(prefix + ".") for key in keys):
+            raise StandardsError(
+                f"pyproject.toml: tool.{prefix}: unclassified override"
+            )
+        for key, item in sorted(table(value, f"tool.{prefix}").items()):
+            visit(item, f"{prefix}.{key}")
+
+    for name in ("ruff", "pyright"):
+        if name in tool:
+            visit(tool[name], name)
+
+
+def shared_diagnostics(tool: dict[str, object]) -> list[str]:
+    problems: list[str] = []
+    for key, expected in sorted(policy().items()):
+        actual: object = tool
+        missing = False
+        for part in key.split("."):
+            current = table(actual, f"tool.{key}")
+            if part not in current:
+                missing = True
+                break
+            actual = current[part]
+        if missing or not same(actual, expected):
+            shown = "<missing>" if missing else repr(actual)
+            problems.append(
+                f"pyproject.toml: tool.{key}: expected {expected!r}; actual {shown}"
+            )
+    return problems
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Configuration:
+    root: Path
+    text: str
+    data: dict[str, object]
+    tool: dict[str, object]
+    sources: tuple[Path, ...]
+    dependency_group: str
+
+    @classmethod
+    def read(cls, root: Path) -> Configuration:
+        path = require_regular(root, Path("pyproject.toml"))
+        text = path.read_text(encoding="utf-8")
+        try:
+            data = cast(dict[str, object], tomllib.loads(text))
+        except tomllib.TOMLDecodeError as exc:
+            raise StandardsError(f"pyproject.toml: malformed TOML: {exc}") from exc
+        tool = table(data.get("tool", {}), "tool")
+        settings = table(
+            tool.get("nox-python-standards", {}), "tool.nox-python-standards"
+        )
+        if set(settings) - {"sources", "dependency-group", "ruff"}:
+            raise StandardsError("Unclassified tool.nox-python-standards setting")
+        source_values = settings.get("sources")
+        if not strings(source_values) or not source_values:
+            raise StandardsError(
+                "tool.nox-python-standards.sources: expected nonempty paths"
+            )
+        sources: list[Path] = []
+        for source in cast(list[str], source_values):
+            candidate = Path(source)
+            if (
+                candidate.is_absolute()
+                or ".." in candidate.parts
+                or not (root / candidate).exists()
+                or not (root / candidate).resolve().is_relative_to(root)
+                or (root / candidate).is_symlink()
+            ):
+                raise StandardsError(f"Invalid consumer source path: {source!r}")
+            sources.append(candidate)
+        group = settings.get("dependency-group")
+        if not isinstance(group, str) or not group:
+            raise StandardsError(
+                "tool.nox-python-standards.dependency-group is required"
+            )
+        validate_boundary(tool)
+        result = cls(
+            root=root,
+            text=text,
+            data=data,
+            tool=tool,
+            sources=tuple(sources),
+            dependency_group=group,
+        )
+        result.check_discovery()
+        return result
+
+    def check_discovery(self) -> None:
+        for name in ("ruff.toml", ".ruff.toml", "pyrightconfig.json"):
+            if (self.root / name).exists() or (self.root / name).is_symlink():
+                raise StandardsError(f"Conflicting native configuration: {name}")
+        discovered = files(self.root)
+        python_files = [
+            path
+            for path in discovered
+            if path.suffix in {".py", ".pyi"} and in_scope(path, self.sources)
+        ]
+        # Check ancestors too: an ignored config can still shadow a tracked source.
+        directories = {parent for path in python_files for parent in path.parents}
+        for directory in sorted(directories - {Path(".")}):
+            for name in ("ruff.toml", ".ruff.toml", "pyproject.toml"):
+                relative = directory / name
+                path = self.root / relative
+                if not path.exists() and not path.is_symlink():
+                    continue
+                require_regular(self.root, relative)
+                if name == "pyproject.toml":
+                    try:
+                        nested = cast(
+                            dict[str, object], tomllib.loads(path.read_text())
+                        )
+                    except tomllib.TOMLDecodeError as exc:
+                        raise StandardsError(
+                            f"Cannot inspect {relative}: {exc}"
+                        ) from exc
+                    if "ruff" not in table(nested.get("tool", {}), str(relative)):
+                        continue
+                raise StandardsError(
+                    f"Conflicting nested Ruff configuration: {relative}"
+                )
+
+    def check(self) -> None:
+        problems = shared_diagnostics(self.tool)
+        path = self.root / SNAPSHOT
+        if (
+            not path.is_file()
+            or require_regular(self.root, SNAPSHOT).read_bytes()
+            != resource("PYTHON_CONVENTIONS.md").encode()
+        ):
+            problems.append(
+                f"{SNAPSHOT}: expected installed conventions; actual missing/drifted"
+            )
+        if problems:
+            raise StandardsError(
+                f"nox-python-standards {release_version()} in {self.root}:\n"
+                + "\n".join(problems)
+                + "\nReview drift, then explicitly run nox-py-standards sync."
+            )
+
+    def sync(self) -> None:
+        document = tomlkit.parse(self.text)
+        for key, value in policy().items():
+            existing: object = self.tool
+            for part in key.split("."):
+                existing = table(existing, f"tool.{key}").get(part)
+                if existing is None:
+                    break
+            if same(existing, value):
+                continue  # Keep existing array layout and comments byte-for-byte.
+            current = document
+            for part in ["tool", *key.split(".")[:-1]]:
+                if part not in current:
+                    current[part] = tomlkit.table()
+                child = current[part]
+                if not isinstance(child, Table):
+                    raise StandardsError(f"Cannot repair non-table tool.{key}")
+                current = child
+            current[key.split(".")[-1]] = value
+        rendered = tomlkit.dumps(document)
+        proposed = cast(dict[str, object], tomllib.loads(rendered))
+        proposed_tool = table(proposed["tool"], "tool")
+        validate_boundary(proposed_tool)
+        if shared_diagnostics(proposed_tool):
+            raise StandardsError("Rendered shared configuration failed validation")
+        # Preflight both destinations before writing either file.
+        for relative in (Path("pyproject.toml"), SNAPSHOT):
+            destination = self.root / relative
+            if destination.exists() or destination.is_symlink():
+                require_regular(self.root, relative)
+            if any(parent.is_symlink() for parent in destination.parents):
+                raise StandardsError(f"Refusing symlink path: {relative}")
+        atomic_write(self.root / "pyproject.toml", rendered.encode())
+        atomic_write(self.root / SNAPSHOT, resource("PYTHON_CONVENTIONS.md").encode())
+
+
+def atomic_write(path: Path, contents: bytes) -> None:
+    if path.is_file() and path.read_bytes() == contents:
+        return
+    path.parent.mkdir(parents=True, exist_ok=True)
+    mode = path.stat().st_mode & 0o777 if path.exists() else 0o644
+    descriptor, temporary = tempfile.mkstemp(dir=path.parent, prefix=f".{path.name}.")
+    try:
+        with os.fdopen(descriptor, "wb") as output:
+            output.write(contents)
+            output.flush()
+            os.fchmod(output.fileno(), mode)
+        os.replace(temporary, path)
+    finally:
+        if os.path.exists(temporary):
+            os.unlink(temporary)

nox_python_standards/repository.py

@@ -0,0 +1,83 @@
+# src/nox_python_standards/repository.py
+from __future__ import annotations
+
+from pathlib import Path
+import subprocess
+
+
+class StandardsError(RuntimeError):
+    """An actionable configuration or tool contract failure."""
+
+
+IGNORED_DIRS = frozenset(
+    {
+        ".eggs",
+        ".git",
+        ".mypy_cache",
+        ".nox",
+        ".pytest_cache",
+        ".ruff_cache",
+        ".tox",
+        ".venv",
+        "__pycache__",
+        "build",
+        "dist",
+        "htmlcov",
+        "lib",
+        "libs",
+        "node_modules",
+        "site-packages",
+        "third_party",
+        "venv",
+        "vendor",
+    }
+)
+
+
+def git(root: Path, *arguments: str) -> bytes:
+    try:
+        return subprocess.check_output(
+            ["git", "-C", str(root), *arguments], stderr=subprocess.PIPE
+        )
+    except (OSError, subprocess.CalledProcessError) as exc:
+        raise StandardsError(f"Git failed in {root}: {arguments!r}") from exc
+
+
+def project_root(explicit: Path | None) -> Path:
+    location = Path.cwd() if explicit is None else explicit.resolve()
+    root = Path(git(location, "rev-parse", "--show-toplevel").decode().strip())
+    if explicit is not None and root.resolve() != location:
+        raise StandardsError("--root must name the consumer Git root")
+    return root.resolve()
+
+
+def ignored(path: Path) -> bool:
+    return any(
+        part in IGNORED_DIRS or part.endswith((".egg-info", ".dist-info"))
+        for part in path.parts[:-1]
+    )
+
+
+def files(root: Path) -> list[Path]:
+    """Git supplies tracked and relevant untracked files without crawling vendors."""
+    output = git(root, "ls-files", "-z", "--cached", "--others", "--exclude-standard")
+    return sorted(
+        {
+            Path(p.decode())
+            for p in output.split(b"\0")
+            if p and not ignored(Path(p.decode()))
+        }
+    )
+
+
+def in_scope(path: Path, sources: tuple[Path, ...]) -> bool:
+    return any(path == source or source in path.parents for source in sources)
+
+
+def require_regular(root: Path, relative: Path) -> Path:
+    path = root / relative
+    if any(parent.is_symlink() for parent in [path, *path.parents] if parent != root):
+        raise StandardsError(f"Refusing symlink path: {relative}")
+    if not path.is_file():
+        raise StandardsError(f"Expected regular file: {relative}")
+    return path

nox_python_standards/resources/PYTHON_CONVENTIONS.md

@@ -0,0 +1,33 @@
+# Noxala Python conventions
+
+Versioned by the installed `nox-python-standards` release. `nox-py-standards check`
+verifies this snapshot; explicit `sync` adopts it. Review and commit changes.
+
+## Tool policy
+
+Keep complete Ruff/Pyright settings in local `pyproject.toml`. Shared values and
+exact tool pins match the installed release. Paths, exclusions, import
+classification and approved test exceptions stay local; Tach alone generates
+first-party lists.
+
+Ruff version approval is manual; sync, installation and CI never grant it.
+Only PT007 is approved among unsafe fixes. Repositories own tool commands,
+Makefiles, hooks and source-header helpers.
+
+## Python guidance
+
+These are review conventions, not an additional AST checker.
+
+- Use supported modern syntax, built-in generics and PEP 695.
+- Type fully for strict Pyright, without `Unknown`.
+- Check nullability with `is None` / `is not None`.
+- Prefer small abstractions to broad dependencies.
+- Keep a repository-relative path header in each Python source.
+- Default to `@dataclass(frozen=True, slots=True, kw_only=True)`; put factory
+  methods on the dataclass, normally `@classmethod create(...)`.
+- Keep orchestration and I/O with the owning subsystem.
+- Test meaningful success, boundary, invalid-input and conflict behavior.
+  Avoid tests that restate the implementation.
+- Use `whitelist`, `blacklist` and `master`.
+
+Follow repository instructions for architecture and domain rules.

nox_python_standards/resources/ownership.json

@@ -0,0 +1,15 @@
+{
+  "ruff.target-version": "string",
+  "ruff.extend-exclude": "strings",
+  "ruff.lint.isort.known-first-party": "strings",
+  "ruff.lint.isort.known-third-party": "strings",
+  "ruff.lint.per-file-ignores": "private-test-rules",
+  "pyright.include": "strings",
+  "pyright.exclude": "strings",
+  "pyright.extraPaths": "strings",
+  "pyright.stubPath": "string",
+  "pyright.pythonVersion": "string",
+  "pyright.venvPath": "string",
+  "pyright.venv": "string",
+  "pyright.executionEnvironments": "test-environments"
+}

nox_python_standards/resources/policy.json

@@ -0,0 +1,25 @@
+{
+  "ruff.required-version": "==0.15.14",
+  "ruff.fix": false,
+  "ruff.fix-only": false,
+  "ruff.unsafe-fixes": false,
+  "ruff.lint.extend-safe-fixes": ["PT007"],
+  "ruff.lint.extend-unsafe-fixes": [],
+  "ruff.lint.fixable": ["ALL"],
+  "ruff.lint.unfixable": [],
+  "ruff.line-length": 88,
+  "ruff.format.quote-style": "double",
+  "ruff.format.indent-style": "space",
+  "ruff.format.line-ending": "lf",
+  "ruff.format.skip-magic-trailing-comma": false,
+  "ruff.format.docstring-code-format": true,
+  "ruff.lint.select": ["A", "B", "DTZ", "E", "F", "I", "LOG", "N", "PGH", "PIE", "PT", "RET", "RUF", "SIM", "SLF", "T20", "UP", "W"],
+  "ruff.lint.ignore": [],
+  "ruff.lint.extend-ignore": ["RET504", "SIM102", "SIM103", "SIM108", "SIM110"],
+  "ruff.lint.isort.combine-as-imports": true,
+  "ruff.lint.isort.force-sort-within-sections": true,
+  "ruff.lint.isort.required-imports": ["from __future__ import annotations"],
+  "pyright.typeCheckingMode": "strict",
+  "pyright.reportMissingImports": "error",
+  "pyright.reportMissingTypeStubs": false
+}

nox_python_standards/resources/versions.json

@@ -0,0 +1,4 @@
+{
+  "ruff": "0.15.14",
+  "pyright": "1.1.411"
+}

nox_python_standards/versions.py

@@ -0,0 +1,134 @@
+# src/nox_python_standards/versions.py
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+import re
+import shutil
+import subprocess
+from typing import cast
+
+from nox_python_standards.config import Configuration, resource, table
+from nox_python_standards.repository import StandardsError
+
+_VERSION = r"([0-9]+\.[0-9]+\.[0-9]+)"
+
+
+def tool_environment() -> dict[str, str]:
+    environment = os.environ.copy()
+    # Use bundled Pyright; Node availability is checked before launching its probe.
+    environment.update(
+        {
+            "PYRIGHT_PYTHON_FORCE_VERSION": release_pins()["pyright"],
+            "PYRIGHT_PYTHON_USE_BUNDLED_PYRIGHT": "1",
+            "PYRIGHT_PYTHON_GLOBAL_NODE": "1",
+            "PYRIGHT_PYTHON_NODEJS_WHEEL": "0",
+            "PYRIGHT_PYTHON_IGNORE_WARNINGS": "1",
+        }
+    )
+    environment.pop("PYRIGHT_PYTHON_PYLANCE_VERSION", None)
+    return environment
+
+
+def group_values(
+    groups: dict[str, object],
+    name: str,
+    ancestors: frozenset[str] = frozenset(),
+) -> list[object]:
+    if name in ancestors:
+        raise StandardsError(f"Cyclic dependency-group include: {name}")
+    values = groups.get(name)
+    if not isinstance(values, list):
+        raise StandardsError(f"dependency-groups.{name} must be an array")
+    flattened: list[object] = []
+    for value in cast(list[object], values):
+        if isinstance(value, str):
+            flattened.append(value)
+        else:
+            include = table(value, f"dependency-groups.{name}")
+            target = include.get("include-group")
+            if set(include) != {"include-group"} or not isinstance(target, str):
+                raise StandardsError(f"Invalid dependency-group include in {name}")
+            flattened.extend(group_values(groups, target, ancestors | {name}))
+    return flattened
+
+
+def release_pins() -> dict[str, str]:
+    """Supported tools are policy data, not package runtime dependencies."""
+    return cast(dict[str, str], json.loads(resource("versions.json")))
+
+
+def consumer_pin(dependencies: list[object], name: str) -> str:
+    declarations = [
+        dependency
+        for dependency in dependencies
+        if isinstance(dependency, str)
+        and re.match(rf"^\s*{name}(?:\s|[<>=!~@;\[]|$)", dependency, re.IGNORECASE)
+    ]
+    if len(declarations) != 1:
+        raise StandardsError(
+            f"Development group must contain exactly one {name} dependency"
+        )
+    match = re.fullmatch(
+        rf"\s*{name}\s*==\s*{_VERSION}\s*", declarations[0], re.IGNORECASE
+    )
+    if match is None:
+        raise StandardsError(
+            f"Development dependency must use exact '{name}==X.Y.Z' pin"
+        )
+    return match.group(1)
+
+
+def check_versions(configuration: Configuration) -> None:
+    groups = table(configuration.data.get("dependency-groups"), "dependency-groups")
+    dependencies = group_values(groups, configuration.dependency_group)
+    settings = table(configuration.tool["nox-python-standards"], "standards settings")
+    approval = table(settings.get("ruff"), "tool.nox-python-standards.ruff")
+    authorized = approval.get("authorized_version")
+    if (
+        set(approval) != {"authorized_version"}
+        or not isinstance(authorized, str)
+        or re.fullmatch(rf"v{_VERSION}", authorized) is None
+    ):
+        raise StandardsError("Ruff authorized_version must use the form 'vX.Y.Z'")
+    supported = release_pins()
+    for name, expected in supported.items():
+        declared = consumer_pin(dependencies, name)
+        if declared != expected or (name == "ruff" and authorized != f"v{expected}"):
+            raise StandardsError(
+                f"{name} version mismatch: standards {expected}, "
+                f"dependency {declared}, Ruff approval {authorized}. "
+                "Update dependencies deliberately; "
+                "Ruff approval requires manual review."
+            )
+    for name, expected in supported.items():
+        located = shutil.which(name)
+        if located is None:
+            raise StandardsError(
+                f"Could not find {name!r} on PATH; "
+                "install locked development dependencies"
+            )
+        # GLOBAL_NODE prefers PATH but falls back to installing nodeenv if absent.
+        if name == "pyright" and shutil.which("node") is None:
+            raise StandardsError(
+                "Node.js must be installed on PATH; no downloads are attempted"
+            )
+        try:
+            # Only probe versions. Never format, lint, typecheck or install tools.
+            output = subprocess.check_output(
+                [str(Path(located).absolute()), "--version"],
+                cwd=configuration.root,
+                text=True,
+                stderr=subprocess.STDOUT,
+                env=tool_environment(),
+            ).strip()
+        except (OSError, subprocess.CalledProcessError) as exc:
+            raise StandardsError(f"{name} --version failed: {exc}") from exc
+        actual = re.fullmatch(
+            rf"{name}\s+{_VERSION}(?:[ \t].*)?", output, re.IGNORECASE
+        )
+        if actual is None or actual.group(1) != expected:
+            raise StandardsError(
+                f"{name} executable mismatch: expected {expected}; actual {output!r}"
+            )

nox_python_standards-0.2.1.dist-info/METADATA

@@ -0,0 +1,148 @@
+Metadata-Version: 2.4
+Name: nox-python-standards
+Version: 0.2.1
+Summary: Check and sync complete local copies of Noxala Python standards
+License-Expression: 0BSD
+Project-URL: Repository, https://github.com/noxala/nox-python-standards
+Project-URL: Issues, https://github.com/noxala/nox-python-standards/issues
+Requires-Python: <3.15,>=3.14.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: tomlkit==0.15.0
+Dynamic: license-file
+
+# nox-python-standards
+
+Shared Noxala Python settings, checked against complete local `pyproject.toml`
+files. Each repository owns its Makefile, hooks, CI and native tool commands.
+
+## Install and adopt
+
+Use the Python/uv versions in [pyproject.toml](pyproject.toml), Git, and Node.js
+on PATH for `check`.
+
+Add development dependencies with an exact PyPI version and the
+[approved tool versions](src/nox_python_standards/resources/versions.json):
+
+```toml
+[dependency-groups]
+dev = [
+    "nox-python-standards==0.2.1",
+    "ruff==0.15.14",
+    "pyright==1.1.411",
+]
+
+[tool.nox-python-standards]
+sources = ["."]
+dependency-group = "dev"
+
+[tool.nox-python-standards.ruff]
+authorized_version = "v0.15.14"  # manual approval
+```
+
+Keep local path/exclusion/import settings. Lock and install dependencies, run
+`uv run nox-py-standards sync`, then review and commit the config, lockfile and
+`.noxala/PYTHON_CONVENTIONS.md`. Root agent instructions should require that
+snapshot before Python edits and state repository-specific rules.
+
+For upgrades, review the release, update pins/lockfile, install, and explicitly
+sync. Ruff version changes require separate manual approval.
+
+## Check and sync
+
+- **`check`** verifies shared settings, ownership, conventions, config discovery,
+  exact tool pins, manual Ruff approval and active tool versions. It is read-only;
+  tool calls are limited to `--version` probes. Node must exist before probing
+  Pyright; the probe selects its bundled pinned release without downloading tools.
+- **`sync`** adopts shared settings and conventions, preserving local settings,
+  comments, dependency pins, lockfiles and approval. It needs no Ruff/Pyright
+  installation. Invalid TOML, unclassified overrides and competing configs block
+  writes. Repeated sync is byte-stable; each changed file is replaced atomically.
+
+Run from any consumer subdirectory, or use `nox-py-standards --root /repo check`.
+`python -m nox_python_standards` exposes the same commands. Neither command installs
+dependencies. Repositories control their normal tool execution and environment.
+
+From 0.1: `config check/sync` becomes `check/sync`; other commands are removed.
+`check` no longer runs source lint, formatting, headers, typing or tests.
+
+## Native fix policy
+
+Checked Ruff settings enforce its exact version and approve PT007 via
+`extend-safe-fixes = ["PT007"]`; other unsafe fixes remain disabled. Keep repair
+recipes local, for example:
+
+```make
+ruff:
+	uv run --locked nox-py-standards check
+	uv run --locked ruff format .
+	uv run --locked ruff check --fix .
+	uv run --locked ruff format .
+```
+
+Repeat until stable. CLI flags can override settings; review and test recipes
+to preserve the policy.
+
+## Configuration ownership
+
+| Authority | Owns |
+| --- | --- |
+| [policy.json](src/nox_python_standards/resources/policy.json) | Shared settings |
+| [ownership.json](src/nox_python_standards/resources/ownership.json) | Local keys and types |
+| [versions.json](src/nox_python_standards/resources/versions.json) | Exact Ruff/Pyright versions |
+
+Shared values must match exactly, even when native defaults agree. Paths,
+exclusions, import classification and approved test exceptions stay local; Tach
+owns generated first-party lists. Unrelated tables are preserved.
+
+Unclassified overrides, inheritance, root `ruff.toml`, `.ruff.toml` or
+`pyrightconfig.json`, and nested Ruff configs affecting scoped Git sources fail.
+
+Policy originated in [COMO](https://github.com/noxala/como/tree/da28acec147d114270ba4524f51a47a5afb2515e);
+this package has no consumer dependency.
+
+## CI and package development
+
+Consumers run `uv run --locked nox-py-standards check` after locked installation,
+before generators/fixes, and first in local pre-commit/pre-push hooks. Require
+the gate unconditionally, then run repository checks. Never auto-sync in CI.
+
+For code or packaging changes here:
+
+```sh
+uv sync --locked
+uv run --locked nox-py-standards check
+uv run --locked ruff format --check .
+uv run --locked ruff check .
+uv run --locked pyright --threads 4
+uv run --locked pytest
+uv run --locked python tools/verify_distribution.py
+```
+
+[CI](.github/workflows/ci.yml) runs on Linux/macOS. Distribution verification
+rebuilds from sdist and tests an isolated, non-editable installation, including
+sync without tools and check with missing/present tools.
+
+Repository administrators should enable auto-merge and require `quality (Linux)`
+and `quality (macOS)`.
+
+## Publishing
+
+Licensed under [0BSD](LICENSE). Releases publish wheels and sdists to
+[PyPI](https://pypi.org/project/nox-python-standards/) through GitHub OIDC;
+no persistent PyPI token is needed.
+
+One-time setup: on your [PyPI publishing page](https://pypi.org/manage/account/publishing/),
+add a pending GitHub publisher with project `nox-python-standards`, owner `noxala`,
+repository `nox-python-standards`, workflow `publish.yml`, and environment `pypi`.
+The GitHub repository must have the matching `pypi` environment.
+
+For each release, update `project.version` and this installation example, run
+`uv lock`, and merge through the required checks. Publish a GitHub release tagged
+`v<version>` at that merged commit. [Publish](.github/workflows/publish.yml)
+reruns Linux/macOS quality checks, requires the tag to match the package version
+and belong to `master`, builds distributions, then uploads through the `pypi`
+environment. To publish an existing tag, run Publish manually from `master`
+with that tag. A failed upload can be retried before either file is published;
+after a partial upload, inspect PyPI before retrying. Published files cannot be
+overwritten; subsequent changes need a new version.

nox_python_standards-0.2.1.dist-info/RECORD

@@ -0,0 +1,17 @@
+nox_python_standards/__init__.py,sha256=9iE4vnPRRAAdVYaBfPnQRGVYaJ0F77JSnRdeKXzX5Wc,74
+nox_python_standards/__main__.py,sha256=C-XpX_Rcc3kRAgnTa4wEP3wDJdQbxBMjUW7yEpQ9BiQ,143
+nox_python_standards/cli.py,sha256=mb_qv3HZDdWKFl-EJ-kEaSvnXhsS2DY5gcDBFX1u7go,1459
+nox_python_standards/config.py,sha256=GSsst_AupbB7hvLwLDipB1-RDTTMXPya9m6mf-vltD0,11014
+nox_python_standards/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+nox_python_standards/repository.py,sha256=SSRhBzQbZSzkY_40r1Nb0RLsejQRAqzhmfrx4eBTwJw,2344
+nox_python_standards/versions.py,sha256=n485sKtC7JO8gtPsgw7MHZ5n4_PL5QB8GF1BEgwEHAg,5274
+nox_python_standards/resources/PYTHON_CONVENTIONS.md,sha256=zfabwTF6aMniCP4V1u-OgK0DSyjd5LVs_QGaH3Mo8-k,1447
+nox_python_standards/resources/ownership.json,sha256=BS2PhFu8qqew5-cz29k5KEFktyWvejpShtUMIzYEH58,512
+nox_python_standards/resources/policy.json,sha256=_v1ePzg0MHJ8sQ9WwVWGC6gqbCXamHMLUAi5sAWlG94,1043
+nox_python_standards/resources/versions.json,sha256=piyUSGXXkHQxSE8_4M2aNqlS-McNIS3xM_FlNRM2HJM,48
+nox_python_standards-0.2.1.dist-info/licenses/LICENSE,sha256=SbK1hmb8Qbqmih86aEBVlBB6dD8TYfKp1nWa5zh5KXY,656
+nox_python_standards-0.2.1.dist-info/METADATA,sha256=Vu5iW_K_qkKWB9B4Sx9P7tZd_uxEWZdFmZR7zfL3GVc,6107
+nox_python_standards-0.2.1.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+nox_python_standards-0.2.1.dist-info/entry_points.txt,sha256=CY5ZSUO61H5GtQ1RI2tWRDhHtUIRGslIGLH9RaKm8ec,67
+nox_python_standards-0.2.1.dist-info/top_level.txt,sha256=OjxZIsid7sll0WeVJ4Wa_aeq-uaxBm2tH9w10Wn1KaU,21
+nox_python_standards-0.2.1.dist-info/RECORD,,

nox_python_standards-0.2.1.dist-info/WHEEL

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

nox_python_standards-0.2.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+nox-py-standards = nox_python_standards.cli:main

nox_python_standards-0.2.1.dist-info/licenses/LICENSE

@@ -0,0 +1,14 @@
+Zero-Clause BSD
+
+Copyright (c) 2026 Noxala Inc.
+
+Permission to use, copy, modify, and/or distribute this software for
+any purpose with or without fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL
+WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES
+OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE
+FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY
+DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN
+AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
+OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

nox_python_standards-0.2.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+nox_python_standards