Repository navigation
Release v0.4.0 — cleanup and consolidation - #31
Merged
Merged
Conversation
The pyvyos.specs Pydantic models were never imported by the runtime and had 0% test coverage. The pyvyos.exceptions hierarchy was defined but never raised anywhere. The request_id helper generated UUIDs that were attached to log records but never propagated to callers — half-implemented tracing is worse than none. This commit does not alter request/response logic or HTTP payloads. It only removes code that was never executed and tests for that code. Removed: - pyvyos/specs/ (Pydantic models package) - pyvyos/exceptions.py (SDKError, HttpError, ApiError, ValidationError) - pyvyos/utils/ids.py (request_id helper) - tests/test_exceptions.py - tests/utils/test_ids.py Edited: - pyvyos/core/rest_client.py: drop request_id import and log extras - pyvyos/utils/__init__.py: drop request_id export Tests: 66 -> 57 passing. Coverage: 54% -> 87%. Public API unchanged.
This commit modernizes the project's tooling and packaging without
changing the runtime code. It addresses dead workflows, obsolete
helper scripts, duplicated configuration, and stale developer docs.
Removed:
- .github/workflows/python-app.yml: targeted Python 3.12, referenced a
non-existent requirements.txt, ran only flake8 with pytest commented out
- Makefile: hard-coded env/bin/python paths that do not work with uv
- run_tests.sh and run_tests.py: duplicated each other and referenced
removed modules (test_exceptions, test_quick)
- sphinx/ and .readthedocs.yaml: the RTD config pointed to
docs/source/conf.py while the sphinx tree lived under sphinx/source,
so the build never worked and no docs were ever published
- docs/development/architecture.md, refactor-roadmap.md, and
quality-and-utils.md: described the pre-cleanup proposal that
included specs/exceptions/request_id, now contradicted by the code
Edited:
- pyproject.toml:
- dropped the validation extra (Pydantic) — specs/ is gone
- dropped the duplicated [tool.hatch.metadata].dependencies block
- dropped the duplicated [dependency-groups].dev block
- declared the wheel package explicitly via
[tool.hatch.build.targets.wheel].packages
- bumped pytest floor to >=8.0 (Python 3.13 compatible)
- added richer classifiers (Development Status, audience, topic,
Typing :: Typed), keywords, license file pointer, and a Changelog URL
- .github/workflows/python-pr-validation.yml: upgraded to
actions/checkout@v4 and setup-python@v5, switched to astral-sh/setup-uv,
removed obsolete architecture argument
- .github/dependabot.yml: added the github-actions ecosystem so
workflow versions stay current
Added:
- pyvyos/py.typed: PEP 561 marker advertising the package as typed
- .pre-commit-config.yaml: neutral hooks only (whitespace, EOF, YAML/TOML
syntax, large-file guard); no formatters or linters yet
Kept:
- docs/development/vyos_api/: JSON reference for the VyOS HTTPS API,
useful for future contract tests
Tests still pass: 57/57.
Rewrite the README around the supported public API, add a public API stability policy, document the deprecation timeline, and refresh the CHANGELOG with the full 0.4.0 scope. Add a short CONTRIBUTING guide. Apply minor pending fixes to LICENSE and .env.example. Fix a couple of verify=False antipatterns in the docs/ pages. README: - Badges (PyPI version, Python versions, license, CI). - Quick start that actually runs (no missing import, no global disable_warnings, correct VYDEVICE_VERIFY_SSL parse). - Environment variable table with defaults. - ApiResponse contract documented as a dataclass. - Compact API overview (configure / retrieve / show / generate / reset / config-file / system / image). - Public API stability section with the 0.4 -> 0.5 -> 0.6 -> 1.0 deprecation timeline. - Logging section: NullHandler default, pyvyos logger, redacted key. - VyOS compatibility note (1.4 LTS, 1.5 rolling). - Development with uv; optional pre-commit. CHANGELOG: - Consolidated 0.4.0 entry covering both the architecture refactor and this cleanup, since 0.4.0 was tagged in git but never published. - Explicit Added / Changed / Removed / Fixed / Compatibility / Notes sections. - 0.3.0 entry annotated as 'tagged but never released to PyPI'. CONTRIBUTING.md: - Scope statement (thin HTTPS API wrapper). - Pull request rules; explicit 'do not change HTTP payload in passing'. - Development setup with uv. - Public API stability summary. Fixes from the previous review-fixes branch: - LICENSE copyright now reads 'GravScale, Roberto Berto'. - .env.example default flipped to VYDEVICE_VERIFY_SSL=true with field descriptions. - docs/getting-started.md: VERIFY_SSL default to true; urllib3 disable_warnings now passes the specific InsecureRequestWarning. - docs/index.md: quick example uses verify=True; removed RTD link (RTD config was removed in this release because the build never worked).
- delete CONTRIB.md (superseded by CONTRIBUTING.md) - delete requirements.txt (duplicated [project].dependencies) - delete test_quick.py (ad-hoc smoke covered by tests/test_shims.py) - rewrite example.py as examples/basic.py using the public API (from pyvyos import VyDevice) and drop the RuntimeWarning suppression - move vagrant/ to examples/vagrant/ - stop tracking uv.lock and add it to .gitignore (library, not app) - README: link the examples/ directory - CHANGELOG: document the moves and removals
- configure_multiple_op uses op_path=, not path= - ApiResponse.result is dict | list | str | None (varies per endpoint), not just dict | list - VYDEVICE_VERIFY_SSL parsing accepts 1/true/yes - describe logging accurately: log records only carry structural fields (no payload, no key); sanitization applies to ApiResponse.request, not to logs; do not claim a NullHandler is attached (none is) - shims at 1.0.0: phrase as a decision deferred to release time
The previous examples/basic.py ran destructive operations (configure_set, configure_delete, generate, reset, config_file_load) by default. That is not what a public 'basic' example should do. - examples/basic.py: rewritten as a read-only example (retrieve_show_config, show, retrieve_return_values), uses a robust env-bool parser, prints response.result via a small helper, and uses the supported public import 'from pyvyos import ApiResponse, VyDevice'. - examples/integration_smoke.py: renamed from the old basic.py, keeps the mutating operations, and refuses to run unless PYVYOS_ALLOW_MUTATING_EXAMPLE=1 is set. - README: link both examples and describe what each one does. Note: the dev/ note about a future Docker-based e2e harness is tracked in the unreleased issue drafts; it is not part of this release.
- requires-python: >=3.13 -> >=3.11. The code does not use any
3.13-only feature. typing.List/Dict/Union/Optional throughout, no
PEP 695 generics, no Self, no match. Classifiers updated to advertise
3.11/3.12/3.13.
- runtime dependencies: trim to requests only.
- python-dotenv is only used by examples; move to the dev extra.
- urllib3 is never imported by pyvyos directly; it remains available
transitively through requests.
- pre-existing dev tooling (pytest, pytest-cov, pytest-env) untouched.
- CI: PR validation runs on a 3.11/3.12/3.13 matrix.
- README: reword the Python requirement.
- .python-version: 3.13.0 -> 3.13 (CI uses the matrix).
- Wheel build verified to include pyvyos/py.typed and to declare
Requires-Python: >=3.11 with requests as the only runtime requirement.
The matrix job in commit 7aa4989 left astral-sh/setup-uv@v3 with its default cache fingerprint of "**/uv.lock". This repo is a library and intentionally does not commit uv.lock (commit a2df706), so the glob matches nothing and the action errors out. Switch the fingerprint to pyproject.toml, the actual source of truth for dependencies. Cache hits remain across PRs that don't touch dependencies; cache invalidates on dependency changes.
Adds an opt-in end-to-end harness that runs pyvyos against a real
VyOS HTTPS API on a Proxmox VE host.
tests/pve/ shell-based VM lifecycle on a remote PVE host:
preflight, ensure-template (state-machine over the
VMID with manual-install phase 1 and cloud-init
phase 2), create/start/stop/destroy, run-e2e.
Cloud-init seed ISO is generated on the PVE host
itself; nothing local-side beyond ssh is required.
.env is gitignored; .env.example documents the
full set of variables.
tests/e2e/ pytest suite that exercises the public methods
most likely to regress on a payload change:
show, retrieve_show_config, configure_set /
retrieve_return_values / configure_delete round
trip, and configure_multiple_op batch. Auto-skipped
unless PYVYOS_E2E=1.
The cloud-init template now sets 'service https api rest' before
the API key. Without that flag VyOS only exposes /info; the other
HTTPS routes return 404. README and tests/pve/README document the
requirement, both for cloud-init and for the manual-fallback path.
Also fixes a pre-existing footgun in pyproject.toml: the pytest-env
defaults overwrote VYDEVICE_HOSTNAME from the shell, which made
the e2e tests silently aim at the stale 192.168.56.100 fixture
host. The entries now use the 'D:' (default) prefix so live runs
can override from the environment as expected.
Validated against VyOS rolling 2026.05.18-0045: 4 e2e + 57 unit
tests pass.
This commit does not change pyvyos HTTP payloads, request handling,
or response parsing.
GitHub deprecation notice: Node.js 20 will be removed from runners in September 2026 and forced to Node 24 in June 2026. Pin to current majors that already run on Node 24. - actions/checkout@v4 -> v6 - actions/setup-python@v5 -> v6 - astral-sh/setup-uv@v3 -> v8 - pypa/gh-action-pypi-publish@v1.13.0 -> v1.14.0 - pre-commit/pre-commit-hooks@v5.0.0 -> v6.0.0 This commit does not change pyvyos HTTP payloads, request handling, or response parsing.
Per OpenSSF Scorecard 'Pinned-Dependencies' guidance, third-party GitHub Actions should be referenced by full commit SHA, not by tag. Tags are mutable; a SHA is not. Each pin keeps a '# vX.Y.Z' trailing comment so Dependabot can read the current version and propose updates while still pinning by SHA. - actions/checkout de0fac2 # v6.0.2 - actions/setup-python a309ff8 # v6.2.0 - astral-sh/setup-uv 0880764 # v8.1.0 - pypa/gh-action-pypi-publish cef2210 # v1.14.0 This commit does not change pyvyos HTTP payloads, request handling, or response parsing.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This release cleans up unused code, packaging, and documentation while preserving
the existing public API and HTTP payload behavior.
4 commits, logically separated:
refactor: remove unused specs, exceptions, and request_idchore: clean packaging and development toolingdocs: prepare v0.4.0 releasechore: trim root, move examples, drop committed uv.lockRoot directory after cleanup: 9 files + 5 directories.
See CHANGELOG.md for the full breakdown.
Merge strategy
Please use merge commit (not squash) — the commits are intentional history.