azure-vm-sdk 0.6.0__tar.gz

azure_vm_sdk-0.6.0/.editorconfig

@@ -0,0 +1,23 @@
+# https://editorconfig.org
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 4
+
+[*.{yml,yaml}]
+indent_size = 2
+
+[*.{toml,json,ini,cfg}]
+indent_size = 2
+
+[*.md]
+# Trailing whitespace is meaningful in Markdown (hard line breaks).
+trim_trailing_whitespace = false
+
+[Makefile]
+indent_style = tab

azure_vm_sdk-0.6.0/.gitattributes

@@ -0,0 +1,33 @@
+# Normalize line endings. This SDK is consumed from wherever the caller happens
+# to be, so a CRLF leaked in from a Windows editor breaks things in ways that
+# are hard to spot in review.
+* text=auto eol=lf
+
+*.py    text diff=python
+*.toml  text
+*.yml   text
+*.yaml  text
+*.json  text
+*.md    text diff=markdown
+*.txt   text
+*.ini   text
+*.cfg   text
+
+# Binary assets: never normalize, never try to diff.
+*.png   binary
+*.jpg   binary
+*.jpeg  binary
+*.gif   binary
+*.ico   binary
+*.whl   binary
+*.gz    binary
+*.zip   binary
+
+# Generated at runtime.
+.coverage       linguist-generated=true
+coverage.xml    linguist-generated=true
+# `linguist-generated` keeps this out of the language stats and collapses it in
+# the GitHub diff view, which is right for a generated file. `-diff` is
+# deliberately NOT set: a lockfile pins exact versions and hashes, so a change
+# to it is exactly the kind of thing review should be able to see.
+uv.lock         linguist-generated=true

azure_vm_sdk-0.6.0/.github/workflows/ci.yml

@@ -0,0 +1,97 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  # ---------------------------------------------------------------------------
+  # Lint, format, types, security.
+  #
+  # Runs the same hooks as local development through pre-commit, so the two can
+  # not drift. This is the first CI this repository has had: it previously had
+  # no .github/workflows at all, so nothing was checked on push.
+  # ---------------------------------------------------------------------------
+  pre-commit:
+    name: pre-commit (ruff, basedpyright, bandit, import-linter)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          # ruff's target-version is py311 and basedpyright is pointed at the
+          # 3.11 venv, so linting on the declared floor is the honest choice.
+          python-version: "3.11"
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+
+      - name: Install the project
+        run: uv sync --frozen
+
+      - name: Install pre-commit
+        run: python -m pip install --upgrade pip pre-commit
+
+      - name: Cache pre-commit environments
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/pre-commit
+          key: pre-commit-${{ hashFiles('.pre-commit-config.yaml') }}
+
+      - name: Run pre-commit
+        run: pre-commit run --all-files --show-diff-on-failure --color=always
+
+  # ---------------------------------------------------------------------------
+  # Tests + coverage gate.
+  #
+  # pyproject.toml sets `addopts = "-m 'not integration'"`, so the tests that
+  # need real Azure credentials and OpenTofu stay out of this job. The coverage
+  # threshold lives in [tool.coverage.report] and is deliberately not repeated
+  # as a --cov-fail-under flag here: stating it in two places is how the two
+  # come to disagree, with the command-line flag silently winning.
+  # ---------------------------------------------------------------------------
+  test:
+    name: pytest (py${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        # 3.11 is the declared floor (requires-python >=3.11).
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+
+      - name: Install project
+        run: uv sync --frozen
+
+      - name: Run tests with coverage
+        run: uv run --frozen pytest --cov-report=xml
+
+      - name: Upload coverage artifact
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-${{ matrix.python-version }}
+          path: coverage.xml
+          if-no-files-found: ignore

azure_vm_sdk-0.6.0/.github/workflows/release.yml

@@ -0,0 +1,66 @@
+name: Release
+
+# A PyPI version can be yanked but never reused, so this only runs on a tag, and
+# the tag is checked against the version the build actually produced before
+# anything is uploaded.
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    name: Build and publish azure-vm-sdk
+    runs-on: ubuntu-latest
+    # Must match the environment registered as this project's trusted publisher
+    # on PyPI, along with owner, repository and this filename.
+    environment: pypi
+    permissions:
+      # The whole credential: PyPI trusts a short-lived OIDC token minted here,
+      # so no API token is stored in the repository or in a secret.
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+
+      - name: Build azure-vm-sdk
+        run: uv build --out-dir dist
+
+      # The check that matters: uploading 0.7.0 under the tag v0.6.0 would burn
+      # the 0.7.0 version number permanently.
+      - name: Check the tag matches the built version
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          # Globs every wheel rather than "<name>-*.whl". The wheel is named after
+          # the distribution, not the module, and for azure-vm-sdk the two differ
+          # (`azure_vm_sdk` against `azure_vm`), so a module-based glob matched
+          # nothing and failed the build. One package per repository, so one wheel.
+          wheels=(dist/*.whl)
+          if [ "${#wheels[@]}" -ne 1 ]; then
+            echo "expected exactly one wheel in dist/, found ${#wheels[@]}" >&2
+            ls -la dist/ >&2
+            exit 1
+          fi
+          artifact="$(basename "${wheels[0]}")"
+          case "$artifact" in
+            *"-$tag-"*) echo "tag $GITHUB_REF_NAME matches $artifact" ;;
+            *)
+              echo "tag $GITHUB_REF_NAME does not match the built $artifact" >&2
+              exit 1
+              ;;
+          esac
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+        with:
+          packages-dir: dist/

azure_vm_sdk-0.6.0/.gitignore

@@ -0,0 +1,22 @@
+__pycache__/
+.pytest_cache/
+.venv/
+*.pyc
+*.egg-info/
+build/
+dist/
+*.svg
+.pydeps/
+.basedpyright/
+.ruff_cache/
+.mypy_cache/
+.grimp_cache/
+
+# Coverage reports. `uv.lock` is deliberately NOT ignored any more: this
+# repository tracks it so CI can run `uv sync --frozen`, like the sibling
+# projects. Leaving it ignored meant a clean checkout had no lockfile at all and
+# `--frozen` could not be used.
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/

azure_vm_sdk-0.6.0/.importlinter

@@ -0,0 +1,33 @@
+[importlinter]
+root_package = azure_vm
+
+[importlinter:contract:models_and_exceptions_are_independent]
+name = models and exceptions must not depend on other internal packages
+type = forbidden
+source_modules =
+    azure_vm.models
+    azure_vm.exceptions
+forbidden_modules =
+    azure_vm._backend
+    azure_vm.vm
+    azure_vm.client
+
+[importlinter:contract:backend_is_independent]
+name = _backend must not depend on higher-level packages
+type = forbidden
+source_modules =
+    azure_vm._backend
+forbidden_modules =
+    azure_vm.vm
+    azure_vm.client
+
+[importlinter:contract:internal_modules_are_independent]
+name = internal modules must not depend on public API layer
+type = forbidden
+source_modules =
+    azure_vm._templates
+    azure_vm._workspace
+    azure_vm._discovery
+forbidden_modules =
+    azure_vm.client
+    azure_vm.vm

azure_vm_sdk-0.6.0/.pre-commit-config.yaml

@@ -0,0 +1,87 @@
+# Pre-commit hooks for azure-vm-sdk.
+#
+#   uv run pre-commit install          # enable on commit
+#   uv run pre-commit run --all-files  # run everything once
+#
+# Version policy: the ruff revision below MUST stay in sync with the `ruff`
+# pin in pyproject.toml. A newer ruff in pre-commit than in the dev environment
+# makes the hook report violations that `uv run ruff check` does not.
+#
+# No default_language_version is set on purpose: pinning it to a specific
+# python3.x makes pre-commit fail outright on a machine that does not have that
+# interpreter on PATH, and the one hook that needs the project's interpreter
+# (basedpyright) runs through `uv run --frozen` against the project venv anyway.
+
+fail_fast: false
+
+repos:
+  # ---------------------------------------------------------------------------
+  # Ruff - lint + format
+  # ---------------------------------------------------------------------------
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.16.6
+    hooks:
+      - id: ruff
+        name: ruff (lint)
+        args: [--fix, --exit-non-zero-on-fix]
+      - id: ruff-format
+        name: ruff (format)
+
+  # ---------------------------------------------------------------------------
+  # Type checking
+  #
+  # Runs through the project environment rather than a pre-commit mirror:
+  # basedpyright has to resolve `azure_vm` itself, and [tool.basedpyright]
+  # carries the include list and venv settings that make the pass meaningful.
+  # ---------------------------------------------------------------------------
+  - repo: local
+    hooks:
+      - id: basedpyright
+        name: basedpyright
+        entry: uv run --frozen basedpyright
+        language: system
+        pass_filenames: false
+        types: [python]
+
+      # The architectural contracts CI checks, run locally too.
+      - id: import-linter
+        name: import-linter
+        entry: uv run --frozen lint-imports --config .importlinter --no-cache
+        language: system
+        pass_filenames: false
+        files: ^src/
+
+  # ---------------------------------------------------------------------------
+  # Security
+  #
+  # This SDK drives an Azure VM over SSH and through OpenTofu, so subprocess
+  # and paramiko are its subject matter rather than a smell. B602 (shell=True)
+  # is deliberately not skipped anywhere: no call here uses it, and that must
+  # stay true.
+  # ---------------------------------------------------------------------------
+  - repo: https://github.com/PyCQA/bandit
+    rev: "1.9.4"
+    hooks:
+      - id: bandit
+        args: ["-c", "pyproject.toml"]
+        additional_dependencies: ["bandit[toml]"]
+        # pre-commit passes explicit filenames, which bypasses bandit's own
+        # exclude_dirs - so the test tree has to be excluded here as well.
+        exclude: ^tests/
+
+  # ---------------------------------------------------------------------------
+  # Generic file hygiene
+  # ---------------------------------------------------------------------------
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: check-toml
+      - id: check-yaml
+      - id: check-merge-conflict
+      - id: check-added-large-files
+        args: [--maxkb=1024]
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+        exclude: \.md$
+      - id: mixed-line-ending
+        args: [--fix=lf]

azure_vm_sdk-0.6.0/.python-version

@@ -0,0 +1 @@
+3.11

azure_vm_sdk-0.6.0/CLAUDE.md

@@ -0,0 +1,109 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Overview
+
+A Pythonic SDK for managing Azure VMs through OpenTofu: a higher-level API over
+a rendered OpenTofu workspace plus SSH access to the resulting machines. It is
+consumed by `nanolab` through a git pin, so the public API in `azure_vm.__all__`
+is a contract with that project.
+
+## Setup
+
+```bash
+uv sync
+```
+
+Requires [uv](https://docs.astral.sh/uv/). Azure credentials and OpenTofu are
+NOT required for the unit tests.
+
+The toolchain (ruff, basedpyright, bandit, import-linter, pytest, pre-commit)
+lives in `[dependency-groups].dev`, which a plain `uv sync` installs. It must
+stay there and not move to `[project.optional-dependencies]`: extras are skipped
+by `uv run`, so the basedpyright pre-commit hook — which runs `uv run --frozen
+basedpyright` — would fail in CI with "Failed to spawn: basedpyright".
+
+## Commands
+
+```bash
+# Tests (the integration marker is deselected by addopts)
+uv run pytest
+uv run pytest tests/unit/test_vm.py::test_name -v
+
+# Integration tests - need real Azure credentials and OpenTofu
+uv run pytest -m integration -v
+
+# Lint, format, types, security, contracts - the same hooks CI runs
+uv run ruff check .
+uv run ruff format .
+uv run basedpyright
+uv run bandit -c pyproject.toml -r src
+uv run lint-imports --config .importlinter --no-cache
+uv run pre-commit run --all-files
+```
+
+`azure-vm-quality` runs ruff, basedpyright, bandit and import-linter together
+and exits non-zero if any of them fails.
+
+## Architecture
+
+`src/azure_vm/` contains the package:
+
+- `_backend.py` — the `TofuBackend` protocol and the subprocess implementation
+  that shells out to `tofu`. All process execution goes through a backend, which
+  is what makes the SDK testable without Azure.
+- `_discovery.py` — locating the OpenTofu binary and the workspace root.
+- `_templates.py` — rendering the `.tf` files for a VM.
+- `_workspace.py` — the on-disk OpenTofu workspace: rendering, `init`, `apply`,
+  output parsing.
+- `models.py` — dataclasses (`VmConfig`, `VmInfo`, `VmSize`, `ImageInfo`,
+  `VmState`, `VmArchitecture`, `CommandResult`, …).
+- `exceptions.py` — typed hierarchy rooted at `AzureVmError`, plus
+  `SshConnectionError` and the rest, so callers catch a specific failure rather
+  than an opaque one.
+- `vm.py` — `AzureVM`: the per-VM handle (info, start/stop/restart, delete,
+  clone, `exec`, `exec_structured`, `transfer`, `wait_for_ip`, `wait_ready`).
+  SSH goes through paramiko and commands are shell-quoted with `shlex.join`.
+- `client.py` — `AzureClient`: cluster-level operations (launch, launch_many,
+  get_vm, ensure_running, list, find, list_sizes, purge).
+- `testing.py` — `FakeTofuBackend` for consumers writing their own tests.
+- `e2e.py` — the `azure-vm-e2e` console script: an end-to-end lifecycle
+  harness. Not imported by the library, and omitted from coverage.
+- `devtools/` — repository tooling exposed as console scripts:
+  `azure-vm-quality`, `azure-vm-package-report` (import graph metrics via
+  `grimp`), `azure-vm-eval` (AST and coupling checks).
+
+The architectural contracts live in `.importlinter`: `models` and `exceptions`
+must not depend on the rest of the package, and the layers must not be imported
+in the wrong direction. CI runs them, and so does pre-commit.
+
+## Callers must not be broken
+
+`nanolab` consumes this package through a git pin, so a change to a name in
+`__all__`, to a signature, or to a returned model's attributes is a breaking
+change for it even though nothing in this repository fails. Check that project
+before renaming or removing a public symbol.
+
+## Tooling
+
+The same stack as the sibling projects.
+
+| Concern | Tool | Config |
+| --- | --- | --- |
+| Lint + format | ruff (88 cols) | `[tool.ruff]` |
+| Types | basedpyright (standard) | `[tool.basedpyright]` |
+| Security | bandit | `[tool.bandit]` |
+| Import layers | import-linter | `.importlinter` |
+| Coverage | pytest-cov | `[tool.coverage.report]`, `fail_under = 80` |
+
+Notes that are easy to get wrong:
+
+- `SLF` (flake8-self) is part of the rule set here, as it was before the
+  migration; the per-file-ignores record where private access is deliberate.
+- This package supports Python 3.11, so `reportImplicitOverride` is off
+  (`typing.override` needs 3.12).
+- `uv.lock` is tracked, so CI can run `uv sync --frozen`. It used to be
+  gitignored, which meant a clean checkout had no lockfile at all.
+- `src/azure_vm/e2e.py` is omitted from coverage: it only runs against real
+  Azure.

azure_vm_sdk-0.6.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 miciav
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.