nyl 0.10.4__tar.gz → 0.26.0__tar.gz

nyl-0.26.0/.gitignore

@@ -0,0 +1,30 @@
+# Nyl runtime cache
+.nyl/
+
+# Build artifacts
+/result
+
+# Rust
+nyl/target/
+nyl/Cargo.lock
+nyl/book/book/
+**/*.rs.bk
+*.pdb
+
+# Development
+todo.txt
+.claude/
+.worktrees/
+
+# Added by cargo
+
+/target
+.codex
+
+# Python client
+python/.venv/
+python/dist/
+__pycache__/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/

nyl-0.26.0/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.5
+Name: nyl
+Version: 0.26.0
+Summary: Render and inspect Kubernetes manifests with the Nyl CLI
+Project-URL: Homepage, https://niklasrosenstein.github.io/nyl/
+Project-URL: Repository, https://github.com/NiklasRosenstein/nyl
+Author: Niklas Rosenstein
+License-Expression: MIT
+Requires-Python: >=3.11
+Requires-Dist: ruamel-yaml<0.19,>=0.18.6
+Description-Content-Type: text/markdown
+
+# Nyl Python client
+
+`nyl` is a small Python 3.11+ library for rendering and inspecting Kubernetes
+manifests. Install it with `uv add nyl` or `pip install nyl`.
+
+Install the [Nyl CLI](https://niklasrosenstein.github.io/nyl/start/getting-started/)
+separately and put it on `PATH`, or pass its executable path.
+
+```python
+from nyl import NylClient
+
+client = NylClient(project="/path/to/infrastructure", executable="nyl", timeout=120)
+manifests = client.render("applications/workloads/web.yaml", target="development")
+deployment = manifests.one("Deployment", "web")
+
+assert deployment.namespace == "web"
+for container in deployment.containers(include_init=True):
+    assert container.security_context["allowPrivilegeEscalation"] is False
+    assert container.env.value("PGHOST") == "database-rw"
+    assert container.env.secret_ref("PGPASSWORD") == ("database-app", "password")
+```
+
+`namespace` is the authored namespace. Resources without one return `None`,
+even when the Release or Argo CD Application has a destination namespace.
+
+## Rendering
+
+`NylClient(project, executable="nyl", timeout=120)` fixes the invocation directory
+and requires a positive, finite timeout in seconds. `render(source, *, target=None,
+offline=False, allow_secret_inputs=False)` invokes only `nyl render`. Relative
+source paths are relative to `project`; absolute paths are passed through.
+Calls leave Python's working directory and environment unchanged and use no shell.
+Timeouts terminate the invocation's process group on POSIX and its process tree
+with Windows' built-in `taskkill`; diagnostics are collected after termination.
+
+Rust owns configuration resolution, validation, rendering, and caching. Target-aware
+Releases use the compiled target's rendering rules. Each call runs the CLI again;
+Nyl's cache may reuse valid artifacts. Project-configured validation remains enabled
+according to the CLI's defaults. A validation failure yields an exception even if
+the CLI emits manifests. `offline=True` forwards `--offline` (cached Git references
+and publication inputs); it is not a universal network prohibition for validators
+or other external tools. `allow_secret_inputs=True` explicitly forwards the CLI's
+opt-in for project secrets and admitted environment inputs.
+
+Only single-file render entry points are supported. Full-tree loading needs a
+documented manifest inventory: a published tree can also contain ownership indexes
+and non-manifest state. This package neither downloads the executable nor applies,
+publishes, or reconciles resources, and has no persistent Python cache.
+
+## Inspecting declarations
+
+`ManifestSet` is iterable, has a length, and preserves document order.
+`select(kind=None, name=None, *, namespace=..., api_version=None)` returns another
+`ManifestSet`. `one(kind, name=None, *, namespace=..., api_version=None)` requires
+exactly one match. Omit `namespace` to search all namespaces; explicitly pass
+`namespace=None` to select resources with no declared namespace. Selection errors
+show resource identities without manifest bodies. `ManifestSet.from_yaml(text)`
+safely reads multi-document YAML 1.2, ignores empty documents, and rejects invalid
+resource envelopes. Nyl's emitted quoting preserves strings such as `"on"`, `"yes"`,
+and `"001"`; no YAML 1.1 boolean coercion is applied by Python.
+
+Resources expose `raw`, `api_version`, `kind`, `name`, and `namespace`.
+`containers(include_init=False)` handles Pods, Deployments, StatefulSets, DaemonSets,
+ReplicaSets, ReplicationControllers, Jobs, and CronJobs. It yields regular containers
+in order, followed by init containers when requested. Unsupported kinds raise
+`DeclarationError`.
+
+Containers expose `raw`, `name`, `security_context` (an empty dictionary when
+omitted), and `env`. `env.value(name)` requires an explicit literal string;
+`env.secret_ref(name)` requires one Secret key reference and returns `(name, key)`.
+Missing, duplicate, malformed, and incompatible declarations raise `DeclarationError`.
+These helpers do not resolve Secrets, ConfigMaps, `envFrom`, Pod-level security
+context inheritance, or live cluster data. Raw dictionaries remain mutable.
+
+## Errors and compatibility
+
+All library errors derive from `NylError` and are exported from `nyl`:
+
+| Error | Meaning |
+| --- | --- |
+| `ExecutableNotFoundError` | Install the CLI or correct its executable path |
+| `RenderTimeoutError` | The subprocess exceeded its deadline |
+| `RenderError` | A nonzero exit status or an OS execution error |
+| `InvalidOutputError` | stdout is not valid rendered resource YAML |
+| `ResourceNotFoundError` | `one()` found zero matches |
+| `AmbiguousResourceError` | `one()` found several matches |
+| `DeclarationError` | A helper cannot interpret the declaration |
+
+Execution errors derive from `ExecutionError` and retain `command` (an argument
+tuple), `exit_code` (`None` when unavailable), and `diagnostics` (stderr).
+They do not retain or automatically print stdout. YAML errors omit input excerpts;
+resource and container representations include only identities. CLI diagnostics
+can contain sensitive information and should be handled accordingly.
+
+Tested with Nyl CLI **0.5.9**. The package's version is available through
+`importlib.metadata.version("nyl")`.
+
+## Development and releases
+
+From the repository root:
+
+```bash
+mise run python-check  # Ruff, type checking, parallel tests, checkout-built CLI
+mise run python-build # Stamp Cargo-derived version, then build wheel and sdist
+mise run pre-commit   # Required Rust and Python checks
+```
+
+Or inside `python/`:
+
+```bash
+uv sync --locked
+uv run python scripts/version.py
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy
+uv run pytest
+uv build
+```
+
+The test fixture builds the CLI and reads Cargo's executable artifact, honoring
+Cargo's configured target and output directory. Set `NYL_TEST_EXECUTABLE` to use
+a binary you built separately.
+
+`scripts/version.py` derives the release version from root `Cargo.toml` and stamps
+`src/nyl/_version.py` before building. For CLI `0.MINOR.PATCH`, Python uses
+`0.2MINOR.PATCH` (concatenation): `0.5.9` → `0.25.9`, `0.10.3` → `0.210.3`.
+From CLI 1.x, versions match. Strict SemVer prereleases `alpha.N`, `beta.N`, and
+`rc.N` map to PEP 440 `aN`, `bN`, and `rcN`. Other prereleases and build metadata
+are rejected. The stamped file is build metadata, not a separately maintained
+release counter. Stamp after synchronizing the development environment;
+`uv run --no-sync` can use that environment when preparing a newer native release.
+The source distribution includes its stamped version and builds without the Rust
+repository, Cargo, or Nyl.
+
+The handwritten `.github/workflows/python.yaml` tests and builds artifacts on
+relevant pull requests, `develop` changes, and native `v*` tags. The tag must match
+the Cargo version. Its publish job consumes the tested artifacts and uses PyPI
+Trusted Publishing from the `pypi` environment for `NiklasRosenstein/nyl`.
+Release through the repository's native release command (`scripts/release.sh X.Y.Z`);
+no separate Python counter or PyPI API token is needed.

nyl-0.26.0/README.md

@@ -0,0 +1,140 @@
+# Nyl Python client
+
+`nyl` is a small Python 3.11+ library for rendering and inspecting Kubernetes
+manifests. Install it with `uv add nyl` or `pip install nyl`.
+
+Install the [Nyl CLI](https://niklasrosenstein.github.io/nyl/start/getting-started/)
+separately and put it on `PATH`, or pass its executable path.
+
+```python
+from nyl import NylClient
+
+client = NylClient(project="/path/to/infrastructure", executable="nyl", timeout=120)
+manifests = client.render("applications/workloads/web.yaml", target="development")
+deployment = manifests.one("Deployment", "web")
+
+assert deployment.namespace == "web"
+for container in deployment.containers(include_init=True):
+    assert container.security_context["allowPrivilegeEscalation"] is False
+    assert container.env.value("PGHOST") == "database-rw"
+    assert container.env.secret_ref("PGPASSWORD") == ("database-app", "password")
+```
+
+`namespace` is the authored namespace. Resources without one return `None`,
+even when the Release or Argo CD Application has a destination namespace.
+
+## Rendering
+
+`NylClient(project, executable="nyl", timeout=120)` fixes the invocation directory
+and requires a positive, finite timeout in seconds. `render(source, *, target=None,
+offline=False, allow_secret_inputs=False)` invokes only `nyl render`. Relative
+source paths are relative to `project`; absolute paths are passed through.
+Calls leave Python's working directory and environment unchanged and use no shell.
+Timeouts terminate the invocation's process group on POSIX and its process tree
+with Windows' built-in `taskkill`; diagnostics are collected after termination.
+
+Rust owns configuration resolution, validation, rendering, and caching. Target-aware
+Releases use the compiled target's rendering rules. Each call runs the CLI again;
+Nyl's cache may reuse valid artifacts. Project-configured validation remains enabled
+according to the CLI's defaults. A validation failure yields an exception even if
+the CLI emits manifests. `offline=True` forwards `--offline` (cached Git references
+and publication inputs); it is not a universal network prohibition for validators
+or other external tools. `allow_secret_inputs=True` explicitly forwards the CLI's
+opt-in for project secrets and admitted environment inputs.
+
+Only single-file render entry points are supported. Full-tree loading needs a
+documented manifest inventory: a published tree can also contain ownership indexes
+and non-manifest state. This package neither downloads the executable nor applies,
+publishes, or reconciles resources, and has no persistent Python cache.
+
+## Inspecting declarations
+
+`ManifestSet` is iterable, has a length, and preserves document order.
+`select(kind=None, name=None, *, namespace=..., api_version=None)` returns another
+`ManifestSet`. `one(kind, name=None, *, namespace=..., api_version=None)` requires
+exactly one match. Omit `namespace` to search all namespaces; explicitly pass
+`namespace=None` to select resources with no declared namespace. Selection errors
+show resource identities without manifest bodies. `ManifestSet.from_yaml(text)`
+safely reads multi-document YAML 1.2, ignores empty documents, and rejects invalid
+resource envelopes. Nyl's emitted quoting preserves strings such as `"on"`, `"yes"`,
+and `"001"`; no YAML 1.1 boolean coercion is applied by Python.
+
+Resources expose `raw`, `api_version`, `kind`, `name`, and `namespace`.
+`containers(include_init=False)` handles Pods, Deployments, StatefulSets, DaemonSets,
+ReplicaSets, ReplicationControllers, Jobs, and CronJobs. It yields regular containers
+in order, followed by init containers when requested. Unsupported kinds raise
+`DeclarationError`.
+
+Containers expose `raw`, `name`, `security_context` (an empty dictionary when
+omitted), and `env`. `env.value(name)` requires an explicit literal string;
+`env.secret_ref(name)` requires one Secret key reference and returns `(name, key)`.
+Missing, duplicate, malformed, and incompatible declarations raise `DeclarationError`.
+These helpers do not resolve Secrets, ConfigMaps, `envFrom`, Pod-level security
+context inheritance, or live cluster data. Raw dictionaries remain mutable.
+
+## Errors and compatibility
+
+All library errors derive from `NylError` and are exported from `nyl`:
+
+| Error | Meaning |
+| --- | --- |
+| `ExecutableNotFoundError` | Install the CLI or correct its executable path |
+| `RenderTimeoutError` | The subprocess exceeded its deadline |
+| `RenderError` | A nonzero exit status or an OS execution error |
+| `InvalidOutputError` | stdout is not valid rendered resource YAML |
+| `ResourceNotFoundError` | `one()` found zero matches |
+| `AmbiguousResourceError` | `one()` found several matches |
+| `DeclarationError` | A helper cannot interpret the declaration |
+
+Execution errors derive from `ExecutionError` and retain `command` (an argument
+tuple), `exit_code` (`None` when unavailable), and `diagnostics` (stderr).
+They do not retain or automatically print stdout. YAML errors omit input excerpts;
+resource and container representations include only identities. CLI diagnostics
+can contain sensitive information and should be handled accordingly.
+
+Tested with Nyl CLI **0.5.9**. The package's version is available through
+`importlib.metadata.version("nyl")`.
+
+## Development and releases
+
+From the repository root:
+
+```bash
+mise run python-check  # Ruff, type checking, parallel tests, checkout-built CLI
+mise run python-build # Stamp Cargo-derived version, then build wheel and sdist
+mise run pre-commit   # Required Rust and Python checks
+```
+
+Or inside `python/`:
+
+```bash
+uv sync --locked
+uv run python scripts/version.py
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy
+uv run pytest
+uv build
+```
+
+The test fixture builds the CLI and reads Cargo's executable artifact, honoring
+Cargo's configured target and output directory. Set `NYL_TEST_EXECUTABLE` to use
+a binary you built separately.
+
+`scripts/version.py` derives the release version from root `Cargo.toml` and stamps
+`src/nyl/_version.py` before building. For CLI `0.MINOR.PATCH`, Python uses
+`0.2MINOR.PATCH` (concatenation): `0.5.9` → `0.25.9`, `0.10.3` → `0.210.3`.
+From CLI 1.x, versions match. Strict SemVer prereleases `alpha.N`, `beta.N`, and
+`rc.N` map to PEP 440 `aN`, `bN`, and `rcN`. Other prereleases and build metadata
+are rejected. The stamped file is build metadata, not a separately maintained
+release counter. Stamp after synchronizing the development environment;
+`uv run --no-sync` can use that environment when preparing a newer native release.
+The source distribution includes its stamped version and builds without the Rust
+repository, Cargo, or Nyl.
+
+The handwritten `.github/workflows/python.yaml` tests and builds artifacts on
+relevant pull requests, `develop` changes, and native `v*` tags. The tag must match
+the Cargo version. Its publish job consumes the tested artifacts and uses PyPI
+Trusted Publishing from the `pypi` environment for `NiklasRosenstein/nyl`.
+Release through the repository's native release command (`scripts/release.sh X.Y.Z`);
+no separate Python counter or PyPI API token is needed.

nyl-0.26.0/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["hatchling>=1.27,<2"]
+build-backend = "hatchling.build"
+
+[project]
+name = "nyl"
+dynamic = ["version"]
+description = "Render and inspect Kubernetes manifests with the Nyl CLI"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [{name = "Niklas Rosenstein"}]
+dependencies = ["ruamel.yaml>=0.18.6,<0.19"]
+
+[project.urls]
+Homepage = "https://niklasrosenstein.github.io/nyl/"
+Repository = "https://github.com/NiklasRosenstein/nyl"
+
+[dependency-groups]
+dev = [
+  "build>=1.2,<2",
+  "hatchling>=1.27,<2",
+  "mypy>=1.15,<2",
+  "pip>=25",
+  "pytest>=8,<10",
+  "pytest-xdist>=3.6,<4",
+  "ruff>=0.11,<1",
+]
+
+[tool.hatch.version]
+path = "src/nyl/_version.py"
+
+[tool.hatch.build.targets.sdist]
+include = ["src/nyl", "README.md", "pyproject.toml"]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+files = ["src/nyl", "scripts/version.py"]
+
+[tool.pytest.ini_options]
+addopts = "-n auto --maxprocesses=4"
+testpaths = ["tests"]

nyl-0.26.0/src/nyl/__init__.py

@@ -0,0 +1,34 @@
+"""Render Kubernetes manifests through an independently installed Nyl CLI."""
+
+from .client import NylClient
+from .errors import (
+    AmbiguousResourceError,
+    DeclarationError,
+    ExecutableNotFoundError,
+    ExecutionError,
+    InvalidOutputError,
+    NylError,
+    RenderError,
+    RenderTimeoutError,
+    ResourceNotFoundError,
+    SelectionError,
+)
+from .manifests import Container, Environment, ManifestSet, Resource
+
+__all__ = [
+    "AmbiguousResourceError",
+    "Container",
+    "DeclarationError",
+    "Environment",
+    "ExecutableNotFoundError",
+    "ExecutionError",
+    "InvalidOutputError",
+    "ManifestSet",
+    "NylClient",
+    "NylError",
+    "RenderError",
+    "RenderTimeoutError",
+    "Resource",
+    "ResourceNotFoundError",
+    "SelectionError",
+]

nyl-0.26.0/src/nyl/_version.py

@@ -0,0 +1 @@
+__version__ = "0.26.0"

nyl-0.26.0/src/nyl/client.py

@@ -0,0 +1,113 @@
+"""The subprocess boundary delegates rendering policy and caching to Rust."""
+
+import math
+import os
+import signal
+import subprocess
+import sys
+from pathlib import Path
+
+from .errors import ExecutableNotFoundError, RenderError, RenderTimeoutError
+from .manifests import ManifestSet
+
+
+class NylClient:
+    """Invoke an installed Nyl executable from a fixed project directory."""
+
+    def __init__(
+        self,
+        project: str | os.PathLike[str],
+        executable: str | os.PathLike[str] = "nyl",
+        timeout: float = 120,
+    ) -> None:
+        if not math.isfinite(timeout) or timeout <= 0:
+            raise ValueError("timeout must be positive and finite")
+        self.project = Path(project).resolve()
+        self.executable = os.fspath(executable)
+        self.timeout = timeout
+
+    def render(
+        self,
+        source: str | os.PathLike[str],
+        *,
+        target: str | None = None,
+        offline: bool = False,
+        allow_secret_inputs: bool = False,
+    ) -> ManifestSet:
+        """Render one source file, preserving the project's validation defaults.
+
+        Relative source paths are resolved by the CLI from ``project``. Each call
+        executes the CLI afresh; its own cache decides which artifacts to reuse.
+        """
+        command = [self.executable, "render"]
+        if target is not None:
+            command.extend(["--target", target])
+        if offline:
+            command.append("--offline")
+        if allow_secret_inputs:
+            command.append("--allow-secret-inputs")
+        command.extend(["--", os.fspath(source)])
+        try:
+            with subprocess.Popen(
+                command,
+                shell=False,
+                cwd=self.project,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                start_new_session=sys.platform != "win32",
+            ) as process:
+                try:
+                    stdout, stderr = process.communicate(timeout=self.timeout)
+                except BaseException as error:
+                    _terminate_tree(process)
+                    _, stderr = process.communicate(timeout=5)
+                    if isinstance(error, subprocess.TimeoutExpired):
+                        error.stderr = stderr
+                    raise
+                exit_code = process.returncode
+        except FileNotFoundError:
+            if not self.project.is_dir():
+                raise RenderError(
+                    f"Project directory does not exist: {self.project}", command=command
+                ) from None
+            raise ExecutableNotFoundError(
+                f"Nyl executable not found: {self.executable!r}; install the Nyl CLI separately",
+                command=command,
+            ) from None
+        except subprocess.TimeoutExpired as error:
+            raise RenderTimeoutError(
+                f"Nyl rendering exceeded {self.timeout} seconds",
+                command=command,
+                diagnostics=(error.stderr or b"").decode("utf-8", errors="replace"),
+            ) from None
+        except OSError as error:
+            raise RenderError(f"Could not execute Nyl: {error.strerror}", command=command) from None
+        diagnostics = stderr.decode("utf-8", errors="replace")
+        if exit_code:
+            raise RenderError(
+                f"Nyl rendering failed with exit code {exit_code}",
+                command=command,
+                diagnostics=diagnostics,
+                exit_code=exit_code,
+            )
+        return ManifestSet.from_yaml(stdout)
+
+
+def _terminate_tree(process: subprocess.Popen[bytes]) -> None:
+    if sys.platform == "win32":
+        try:
+            subprocess.run(
+                ["taskkill", "/F", "/T", "/PID", str(process.pid)],
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+                timeout=5,
+                check=False,
+            )
+        finally:
+            if process.poll() is None:
+                process.kill()
+    else:
+        try:
+            os.killpg(process.pid, signal.SIGKILL)
+        except ProcessLookupError:
+            pass

nyl-0.26.0/src/nyl/errors.py

@@ -0,0 +1,54 @@
+"""Errors contain diagnostics and identities, never rendered manifest bodies."""
+
+
+class NylError(Exception):
+    """Base class for the client's errors."""
+
+
+class ExecutionError(NylError):
+    """A CLI invocation failed; diagnostics may contain sensitive CLI messages."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        command: list[str],
+        diagnostics: str = "",
+        exit_code: int | None = None,
+    ) -> None:
+        self.command = tuple(command)
+        self.diagnostics = diagnostics
+        self.exit_code = exit_code
+        super().__init__(f"{message}\n{diagnostics}".rstrip())
+
+
+class ExecutableNotFoundError(ExecutionError):
+    """The configured Nyl executable is unavailable."""
+
+
+class RenderTimeoutError(ExecutionError):
+    """Rendering exceeded the client's timeout."""
+
+
+class RenderError(ExecutionError):
+    """The CLI returned a nonzero exit code or could not start."""
+
+
+class InvalidOutputError(NylError):
+    """Rendered stdout is not a stream of Kubernetes resource dictionaries."""
+
+
+class SelectionError(NylError):
+    """A resource selector does not identify exactly one resource."""
+
+
+class ResourceNotFoundError(SelectionError):
+    """No resource matches a selector."""
+
+
+class AmbiguousResourceError(SelectionError):
+    """Several resources match a selector."""
+
+
+class DeclarationError(NylError):
+    """A container helper cannot interpret the authored declaration."""