nox-python-standards 0.2.1__tar.gz

nox_python_standards-0.2.1/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,135 @@
+# 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/pyproject.toml

@@ -0,0 +1,93 @@
+[build-system]
+requires = ["setuptools>=80"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "nox-python-standards"
+version = "0.2.1"
+description = "Check and sync complete local copies of Noxala Python standards"
+readme = "README.md"
+license = "0BSD"
+license-files = ["LICENSE"]
+requires-python = ">=3.14.10,<3.15"
+dependencies = ["tomlkit==0.15.0"]
+
+[project.urls]
+Repository = "https://github.com/noxala/nox-python-standards"
+Issues = "https://github.com/noxala/nox-python-standards/issues"
+
+[project.scripts]
+nox-py-standards = "nox_python_standards.cli:main"
+
+[dependency-groups]
+dev = ["pytest==9.0.3", "ruff==0.15.14", "pyright==1.1.411"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+nox_python_standards = ["resources/*.json", "resources/*.md", "py.typed"]
+
+[tool.uv]
+required-version = ">=0.13.6"
+
+[tool.nox-python-standards]
+sources = ["src", "test", "tools"]
+dependency-group = "dev"
+
+[tool.nox-python-standards.ruff]
+authorized_version = "v0.15.14"
+
+# Shared fields are checked against the installed release. Explicit adoption:
+# nox-py-standards sync; CI: nox-py-standards check.
+[tool.ruff]
+required-version = "==0.15.14"
+fix = false
+fix-only = false
+unsafe-fixes = false
+line-length = 88
+target-version = "py314"
+extend-exclude = ["build", "dist", ".venv"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+line-ending = "lf"
+skip-magic-trailing-comma = false
+docstring-code-format = true
+
+[tool.ruff.lint]
+extend-safe-fixes = ["PT007"]
+extend-unsafe-fixes = []
+fixable = ["ALL"]
+unfixable = []
+select = ["A", "B", "DTZ", "E", "F", "I", "LOG", "N", "PGH", "PIE", "PT", "RET", "RUF", "SIM", "SLF", "T20", "UP", "W"]
+ignore = []
+extend-ignore = ["RET504", "SIM102", "SIM103", "SIM108", "SIM110"]
+
+[tool.ruff.lint.isort]
+combine-as-imports = true
+force-sort-within-sections = true
+required-imports = ["from __future__ import annotations"]
+known-first-party = ["nox_python_standards"]
+known-third-party = []
+
+[tool.ruff.lint.per-file-ignores]
+"test/**/*.py" = ["SLF001"]
+
+[tool.pyright]
+typeCheckingMode = "strict"
+reportMissingImports = "error"
+reportMissingTypeStubs = false
+include = ["src", "test", "tools"]
+exclude = ["build", "dist", ".venv"]
+extraPaths = ["src"]
+pythonVersion = "3.14"
+venvPath = "."
+venv = ".venv"
+executionEnvironments = [{ root = "test", reportPrivateUsage = "none" }]
+
+[tool.pytest.ini_options]
+testpaths = ["test"]
+addopts = "-ra"
+filterwarnings = ["error"]

nox_python_standards-0.2.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

nox_python_standards-0.2.1/src/nox_python_standards/__init__.py

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

nox_python_standards-0.2.1/src/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-0.2.1/src/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())