yang2sdk 2026.10.16__tar.gz

yang2sdk-2026.10.16/.env.example

@@ -0,0 +1,9 @@
+DEVICE_NAME = 'device_name'
+# OS version: names the generated package (<device>_<os-version>) and feeds
+# --device-version. Also read from $DEVICE_VERSION by the compilers.
+DEVICE_VERSION = '1.4.0'
+DEVICE_IP = '192.168.137.42'
+DEVICE_USER = 'username'
+DEVICE_PASS = 'password'
+RESTCONF_PORT = 443
+NETCONF_PORT = 830

yang2sdk-2026.10.16/.env.lab-device.example

@@ -0,0 +1,19 @@
+# Real lab device (LAB ONLY, shared equipment). Names only, dummy values.
+# The generated SDK and the test-suite resolve these names; nothing here is
+# ever printed, logged, or committed. `.env` itself is gitignored.
+#
+# Fallback: the legacy DEVICE_* names keep working for `yang-downloader`
+# and `sdk-verify`, so an existing .env does not need to change.
+LAB_DEVICE_IP=192.0.2.10
+LAB_DEVICE_NETCONF_PORT=830
+LAB_DEVICE_USER=netconf-operator
+LAB_DEVICE_PASS=change-me
+
+# Optional: pin the device host key so the secure default (verify=True)
+# works end to end. Without it the client fails closed, which is correct.
+#LAB_DEVICE_KNOWN_HOSTS=/path/to/known_hosts
+# Explicit lab opt-out; logs a warning and skips host-key verification.
+#LAB_DEVICE_ALLOW_UNVERIFIED=1
+
+# Gates the write test. Writes are off unless this is exactly 1.
+LAB_DEVICE_ALLOW_WRITE=0

yang2sdk-2026.10.16/.env.notconf.example

@@ -0,0 +1,5 @@
+# Simulator lab only. Defaults match notconf pre-built images (admin/admin).
+# Never commit real device credentials here.
+NOTCONF_USER=admin
+NOTCONF_PASS=admin
+NOTCONF_RUN_INTEGRATION=0

yang2sdk-2026.10.16/.env.srl-lab.example

@@ -0,0 +1,6 @@
+# SR Linux containerlab lab (LAB ONLY). Names only.
+# Defaults match tests/srl/README.md; the fixture skips when nothing listens.
+SRL_DEVICE_IP=127.0.0.1
+SRL_DEVICE_NETCONF_PORT=1830
+SRL_DEVICE_USER=admin
+SRL_DEVICE_PASS=change-me

yang2sdk-2026.10.16/.github/pull_request_template.md

@@ -0,0 +1,41 @@
+## What
+
+<!-- One or two sentences. What changes, and why now? -->
+
+## Why
+
+<!-- The problem this solves. If it fixes a bug, link the issue. -->
+
+## Checklist
+
+- [ ] The five gate commands pass (ruff, ruff format, ty, pyrefly, offline tests)
+- [ ] `AGENTS.md` still describes the behaviour accurately, if the change touches
+      the generator contract, the parity table, or a safety default
+- [ ] New IR fields have template rendering **and** a generated sample that imports
+- [ ] Protocol changes cite an RFC section (`RFCs/*.md`)
+- [ ] No credential, device IP, or `temp/` output committed
+
+## Evidence
+
+Per `AGENTS.md`'s evidence rule — this is the part reviewers rely on most.
+
+**Files changed:**
+
+**Commands run:**
+
+<!-- e.g. the five gate commands; `uv run yang2netconf temp/yang_modules/srl/*.yang --device srl` -->
+
+**Verified:**
+
+**Not verified / WIP:**
+
+<!-- Be explicit. If you did not run the simulator matrix or a lab job, say so.
+     A "skip" is not a pass, and unverified work presented as verified is the
+     one failure mode this repo cannot recover from. -->
+
+## Safety
+
+- [ ] No secure default weakened (`verify=True`, `auto_commit=False`,
+      `replace()` completeness guard, no embedded credentials)
+- [ ] Any device quirk is documented and isolated to a downstream adapter, not
+      baked into the generic path

yang2sdk-2026.10.16/.github/workflows/ci-nightly.yaml

@@ -0,0 +1,38 @@
+name: ci-nightly
+on:
+  schedule:
+    - cron: "0 2 * * *"
+  workflow_dispatch:
+
+jobs:
+  full-matrix:
+    runs-on: ubuntu-24.04
+    strategy:
+      fail-fast: false
+      matrix:
+        image:
+          - { package: notconf, tag: latest }
+          - { package: notconf-ietf, tag: latest }
+          - { package: notconf-sros, tag: "21.10" }
+          - { package: notconf-sros, tag: "22.2" }
+          - { package: notconf-junos, tag: 21.1R1 }
+          - { package: notconf-junos, tag: 23.4R1 }
+          - { package: notconf-cisco-xr, tag: "762" }
+          - { package: notconf-cisco-xr, tag: "771" }
+          - { package: notconf-cisco-xr, tag: "2411" }
+          - { package: notconf-cisco-xr, tag: "2531" }
+          - { package: notconf-cisco-nx, tag: 10.4-4 }
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --locked --group dev --extra lab
+      - run: >-
+          uv run pytest tests/test_notconf_protocol.py tests/test_sdk_generate.py
+          tests/test_sdk_verify_ci.py -v
+        env:
+          NOTCONF_RUN_INTEGRATION: "1"
+          NOTCONF_IMAGE_PACKAGE: ${{ matrix.image.package }}
+          NOTCONF_IMAGE_TAG: ${{ matrix.image.tag }}
+      - name: Collect container logs
+        if: always()
+        run: docker ps -a --format '{{.Names}}' | grep -e yang2sdk- || true

yang2sdk-2026.10.16/.github/workflows/ci-pr.yaml

@@ -0,0 +1,80 @@
+name: ci-pr
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  lint-typecheck:
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --locked --group dev --extra lab
+      # `uv run`, not `uvx`: the four gates are pinned exactly in the dev group
+      # so CI installs what uv.lock says. `uvx` would resolve the newest release
+      # on every run and could redden main with no commit to explain it.
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+      - run: uv run ty check
+      - run: uv run pyrefly check
+
+  offline-tests:
+    needs: lint-typecheck
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --locked --group dev --extra lab
+      - run: uv run pytest tests/test_matrix.py -v
+
+  smoke:
+    needs: lint-typecheck
+    runs-on: ubuntu-24.04
+    strategy:
+      fail-fast: false
+      matrix:
+        image:
+          - { package: notconf, tag: latest }
+          - { package: notconf-ietf, tag: latest }
+          - { package: notconf-sros, tag: "22.2" }
+          - { package: notconf-junos, tag: 23.4R1 }
+          - { package: notconf-cisco-xr, tag: "2411" }
+          - { package: notconf-cisco-nx, tag: 10.4-4 }
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --locked --group dev --extra lab
+      # test_sdk_verify_ci.py drives `sdk-verify` (every reachable node + every RPC
+      # Input serialised) against the same container the other two reuse, so it
+      # adds no container startup. It was a manual lab harness in no workflow,
+      # which is how three shipped defects survived: the RESTCONF
+      # ancestor-envelope unwrap, the NETCONF augment-closure gap, and the
+      # ietf-notification-capabilities model hole. Blocking, per image.
+      - run: >-
+          uv run pytest tests/test_notconf_protocol.py tests/test_sdk_generate.py
+          tests/test_sdk_verify_ci.py -v
+        env:
+          NOTCONF_RUN_INTEGRATION: "1"
+          NOTCONF_IMAGE_PACKAGE: ${{ matrix.image.package }}
+          NOTCONF_IMAGE_TAG: ${{ matrix.image.tag }}
+
+  # ci-gate: the single required check on main. It `needs` every other job in
+  # this workflow, so the branch ruleset only has to require this one stable
+  # name instead of one context per job/matrix shard. When you add a job to
+  # this workflow, add it to ci-gate's `needs` in the same PR (forgetting it
+  # fails open: the new job simply isn't gated).
+  ci-gate:
+    needs: [lint-typecheck, offline-tests, smoke]
+    if: always()
+    runs-on: ubuntu-latest
+    steps:
+      - name: Fail unless every ci-pr job succeeded
+        run: |
+          needs='${{ toJSON(needs) }}'
+          echo "$needs" | jq -c 'with_entries(.value = .value.result)'
+          if ! echo "$needs" | jq -e 'all(.[]; .result == "success")' > /dev/null; then
+            echo "::error::ci-gate: one or more ci-pr jobs did not succeed"
+            exit 1
+          fi
+          echo "all ci-pr jobs succeeded"

yang2sdk-2026.10.16/.github/workflows/ci-srl.yaml

@@ -0,0 +1,216 @@
+name: ci-srl
+# SR Linux (Nokia) in containerlab — the repo's only real *commercial* NOS.
+#
+# Why this exists: every notconf image is a simulator built from a handful of
+# IETF/vendor models, and the Groove G30 is a single lab device that is
+# writable-running only. None of them exercise a full vendor model tree
+# (hundreds of modules, deep augment closure, identityref leaves) through the
+# generated client. SR Linux does, in a container, for free.
+#
+# NOT an NMDA device, contrary to an earlier revision of this file. Measured
+# against SR Linux 25.10.1 from a raw <hello> (370 capabilities): its complete
+# base-capability set is candidate, confirmed-commit, rollback-on-error,
+# startup, url, validate, with-defaults, with-operational-defaults and
+# yang-library. It ships the ietf-netconf-nmda *module* but does NOT advertise
+# `:nmda:1.0` — precisely the false positive guarded in
+# tests/test_matrix.py::test_nmda_is_detected_from_the_capability_uri_not_a_module_name.
+# So this job must not be described as NMDA coverage.
+#
+# Cost: this repository is public, so standard GitHub-hosted runners are free.
+# Do NOT move this job to a `*-large` runner — larger runners are billed even
+# for public repositories.
+#
+# Severity is deliberately split:
+#   deploy / readiness / get-schema / generate -> BLOCKING. Zero coverage must
+#     never render as a green run, and each of these failing means the steps
+#     after it prove nothing.
+#   pytest / sdk-verify                         -> non-blocking
+#     (continue-on-error). Device boot timing and init races are real; a
+#     failure here is a signal to read, not a merge blocker.
+# Every blocking step must also pass for pytest to run at all (the default
+# `if: success()`), so a broken lab is never reported as "tests passed".
+on:
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: ci-srl-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  srl-containerlab:
+    # Standard runner, not a larger one: 4 vCPU / 16 GB RAM is above SR Linux's
+    # documented 2 vCPU / 4 GB minimum, and it keeps the job free for a public repo.
+    runs-on: ubuntu-24.04
+    timeout-minutes: 45
+    # Deliberately no `needs:`. GitHub Actions cannot express dependencies
+    # across workflow files, so this cannot wait on ci-pr.yaml's lint-typecheck
+    # job — it runs in parallel with ci-pr instead, and does its own `uv sync`.
+    # Since the pytest step is non-blocking, ordering against the real gates
+    # would buy nothing anyway.
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+
+      - name: Install containerlab (pinned)
+        # CLAB_VERSION is pinned for the same reason tests/srl/srl.clab.yml pins
+        # the SR Linux image: an unpinned containerlab release can change deploy
+        # or readiness behaviour overnight and turn a green pipeline red with no
+        # code change. Bump it deliberately, and note the bump in the PR.
+        # `install-containerlab` only — the runner already ships docker and has
+        # passwordless sudo, and "all" would try to install its own docker.
+        env:
+          CLAB_VERSION: "0.79.0"
+        run: |
+          curl -sL https://containerlab.dev/setup | sudo -E bash -s install-containerlab
+          containerlab version
+
+      - name: Install project
+        run: uv sync --locked --group dev --extra lab
+
+      - name: Deploy SR Linux lab
+        # `sudo -E` keeps $HOME so containerlab writes its lab state next to
+        # the topology file (tests/srl/clab-*/, already gitignored) instead of
+        # under /root. containerlab needs root for the privileged SR Linux node.
+        #
+        # Most likely failure mode on a new runner: SR Linux's DPDK-based XDP
+        # datapath needs the SSSE3 instruction set and containerlab *aborts*
+        # deploy without it. GitHub's AMD EPYC runners have SSSE3, but keep the
+        # full deploy output in the log so that diagnosis is one scroll away.
+        run: |
+          sudo -E containerlab deploy -t tests/srl/srl.clab.yml
+
+      - name: Wait for NETCONF readiness
+        # The lab is not usable the instant `deploy` returns: SR Linux takes
+        # minutes to bring up its management plane. tests/srl/lab.py polls the
+        # RFC 6241 Sec 8 hello with the lab's own credentials and exits
+        # non-zero on timeout, so a node that never boots fails here loudly
+        # rather than skipping every test below.
+        run: uv run python -m tests.srl.lab
+
+      - name: Download YANG from the node (get-schema)
+        # Same path the notconf suite uses: the shipped yang-downloader, so the
+        # integration suite exercises the code users actually run. It also
+        # writes features.json from the <hello> capability set, which
+        # yang2netconf picks up automatically as --features-file.
+        #
+        # Single source of truth for host/port/credentials: the committed
+        # tests/srl/.env.srl.example (published containerlab defaults, not
+        # secrets). It must be sourced *here* — every `run:` is a fresh shell,
+        # so exporting it in an earlier step would not survive. downloader.main()
+        # reads DEVICE_IP / NETCONF_PORT / DEVICE_USER / DEVICE_PASS /
+        # DEVICE_NAME from the environment and exits 2 if any is missing.
+        # DEVICE_NAME is what makes the output land in temp/yang_modules/srl.
+        #
+        # NOTE: downloader.main() discards download_all()'s failure count and
+        # still exits 0, so a partial extraction looks like success. Guard on
+        # the artefacts instead of trusting the exit code.
+        run: |
+          set -a
+          # shellcheck disable=SC1091
+          source tests/srl/.env.srl.example
+          set +a
+          echo "lab endpoint ${DEVICE_IP}:${NETCONF_PORT} as device '${DEVICE_NAME}'"
+          uv run yang-downloader
+          count=$(find temp/yang_modules/srl -name '*.yang' | wc -l)
+          echo "downloaded ${count} YANG modules"
+          if [ "$count" -lt 10 ]; then
+            echo "::error::get-schema returned only ${count} modules — refusing to compile"
+            exit 1
+          fi
+          test -f temp/yang_modules/srl/features.json \
+            || { echo "::error::features.json missing — <hello> capability parse failed"; exit 1; }
+
+      - name: Generate the NETCONF client from the node's own models
+        # Roots are the two the tests navigate to: <system> (system/name/host-name,
+        # management, logging) and the interfaces list.
+        #
+        # yang2netconf now resolves the augment closure itself (88c2681), so the
+        # explicit closure.py step that used to live here is redundant — passing
+        # the two root files is enough. Kept as a single command so this job
+        # exercises the documented user path rather than a special one.
+        run: |
+          uv run yang2netconf \
+            temp/yang_modules/srl/srl_nokia-system@*.yang \
+            temp/yang_modules/srl/srl_nokia-interfaces@*.yang \
+            --device srl \
+            --yang-dir temp/yang_modules/srl \
+            --output-dir temp/netconf_clients/srl
+          test -f temp/netconf_clients/srl/__init__.py
+
+      - name: SR Linux NETCONF suite
+        # NON-BLOCKING on purpose. Everything above must pass for this step to
+        # even run (default `if: success()`), so a broken lab is still a red X.
+        # A failure *here* is a device/timing or generator-regression signal that
+        # should be read, not a merge blocker.
+        #
+        # Expect one skip: test_hostname_mutate_restore. A whole-<system> merge
+        # is not expressible against this device for two verified reasons —
+        # SR Linux rejects identityref writes in the RFC 7951 string form it
+        # itself emits, and a write below the root omits the ancestor path the
+        # device requires. Both are documented at tests/test_srl_netconf.py.
+        # This job's first run earned that skip: it is not a pre-existing
+        # condition.
+        id: srl-tests
+        continue-on-error: true
+        env:
+          NOTCONF_RUN_INTEGRATION: "1"
+        run: uv run pytest tests/test_srl_netconf.py -v
+
+      - name: sdk-verify against the full vendor tree
+        # NON-BLOCKING, same severity as the pytest step above. This is the
+        # exhaustive walk — every reachable node at bounded depth, every RPC
+        # Input serialised — over a tree the notconf simulators cannot match
+        # (397 modules, deep augment closure, identityref leaves).
+        #
+        # `crud` is enabled here and only here. It is a writer: it holds the
+        # candidate lock, merges, reads back, discards, and proves restoration
+        # with a whole-tree digest, and it refuses to run without BOTH
+        # --write and a second acknowledgement (--allow-running-writes here,
+        # since SR Linux has :candidate). That is why it does not belong in the
+        # notconf smoke matrix.
+        #
+        # Measured locally against 25.10.1: 291 pass / 0 fail / 170 skip, with
+        # `verify-restore: config digest matches snapshot`.
+        id: srl-sdk-verify
+        continue-on-error: true
+        run: |
+          set -a
+          # shellcheck disable=SC1091
+          source tests/srl/.env.srl.example
+          set +a
+          uv run sdk-verify \
+            --device srl \
+            --protocol netconf \
+            --tiers read,rpc,crud \
+            --write \
+            --allow-running-writes \
+            --no-verify-tls \
+            --snapshot temp/verify/srl-netconf-crud-snapshot.json \
+            --json-out temp/verify/srl-netconf-report.json
+
+      - name: Container logs
+        # `failure()` alone would MISS the case that matters most: a failing
+        # pytest step does not put the job in a failed state, because it is
+        # continue-on-error. Check those steps' own outcomes too, or a
+        # generator regression would be reported with no device logs to
+        # explain it. Runs before destroy, while the containers still exist.
+        if: >-
+          failure() ||
+          steps.srl-tests.outcome == 'failure' ||
+          steps.srl-sdk-verify.outcome == 'failure'
+        run: |
+          docker ps -a --format '{{.Names}}' | grep -e clab- || true
+          for c in $(docker ps -a --format '{{.Names}}' | grep -e clab- || true); do
+            echo "===== ${c} ====="
+            docker logs --tail 200 "$c" || true
+          done
+
+      - name: Destroy the lab
+        # Always: an abandoned privileged container keeps its port binding and
+        # its ~2 GB of disk until the runner is reclaimed.
+        if: always()
+        run: |
+          sudo -E containerlab destroy -t tests/srl/srl.clab.yml --cleanup || true

yang2sdk-2026.10.16/.github/workflows/release.yaml

@@ -0,0 +1,94 @@
+name: release
+
+# Publishes to PyPI when a `v*` tag is pushed. Nothing here runs on a PR, so
+# this workflow is deliberately NOT part of `ci-pr`'s `ci-gate` needs list
+# (AGENTS.md: `main` requires only that one stable check name).
+#
+# Tagging without this workflow shipped nothing — the repo had no publish job
+# at all, which is why v0.1.0 needed one written from scratch.
+#
+# One-time setup (PyPI side, not automatable from this repo):
+#   * Preferred: configure "Trusted Publishing" for this repo on PyPI. No
+#     secret is needed at all, and the `PYPI_TOKEN` environment reference
+#     below stays empty.
+#   * Otherwise create a PyPI API token scoped to this project and add it as
+#     the repository secret `PYPI_TOKEN`.
+#   Either way the `environment: pypi` gate below should be created in the
+#   repo settings so publishing requires an approver.
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-24.04
+    outputs:
+      version: ${{ steps.version.outputs.value }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+
+      # GitHub records a `run` step's outputs ONLY from `name=value` lines on
+      # stdout (or the deprecated `::set-output::`). A bare `print()` writes
+      # nothing to $GITHUB_OUTPUT, so `steps.version.outputs.value` below was
+      # always empty and the guard failed for EVERY tag -- including one that
+      # matched -- which is why the first release run (38891426993) failed with
+      # "pyproject.toml says " and an empty version rather than the real
+      # mismatch. Write the output explicitly, and fail here if it is empty
+      # instead of letting the comparison below treat "" as a version.
+      #
+      # `python3`, not `uv run`: tomllib is stdlib on the runner's 3.12, so the
+      # guard needs no synced environment, and the step then runs offline in
+      # `tests/test_matrix.py::test_release_tag_guard_*` without nesting uv.
+      - name: Read pyproject version
+        id: version
+        run: |
+          v="$(python3 -c 'import tomllib,pathlib;print(tomllib.loads(pathlib.Path("pyproject.toml").read_text()).get("project",{}).get("version",""))')"
+          if [ -z "$v" ]; then
+            echo "could not read [project].version from pyproject.toml" >&2
+            exit 1
+          fi
+          echo "value=$v" >> "$GITHUB_OUTPUT"
+
+      - name: Fail if the tag does not match pyproject
+        run: |
+          set -euo pipefail
+          want="${GITHUB_REF_NAME#v}"
+          if [ "$want" != "${{ steps.version.outputs.value }}" ]; then
+            echo "tag $GITHUB_REF_NAME implies $want but pyproject.toml says ${{ steps.version.outputs.value }}" >&2
+            exit 1
+          fi
+
+      - run: uv build --out-dir dist
+
+      # --strict: fail on anything PyPI would reject, so a rejected upload is
+      # caught here rather than after the tag is already public.
+      - run: uv run --with twine twine check --strict dist/*
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/*
+
+  publish:
+    needs: build
+    runs-on: ubuntu-24.04
+    environment: pypi
+    permissions:
+      # id-token is what Trusted Publishing needs; harmless when a token is used.
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist
+      # With no `password` this uses Trusted Publishing (OIDC). With
+      # PYPI_TOKEN set in the environment it falls back to that token. The
+      # value is passed via `env`, never interpolated into the `with:` block,
+      # so it cannot be echoed into a log.
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        env:
+          PYPI_TOKEN: ${{ secrets.PYPI_TOKEN }}

yang2sdk-2026.10.16/.gitignore

@@ -0,0 +1,28 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+*.log
+
+# Virtual environments
+.venv
+.ruff_cache
+.pytest_cache/
+
+# env files
+*.env
+
+# containerlab runtime state (LAB ONLY) — lives next to the topology file
+tests/srl/clab-*/
+
+# Temporary files
+digest.txt
+# Simulator snapshot payloads (run-local; strict golden comparison is follow-up)
+tests/fixtures/golden/*.json
+# Ephemeral workspace (yang_modules/, *_clients/, yang_tree/, verify/,
+# model_gaps/). Never committed; every writer creates its own output dir
+# on demand, so `rm -rf temp/` is always recoverable (re-download/recompile).
+temp/

yang2sdk-2026.10.16/.python-version

@@ -0,0 +1 @@
+3.12