From ea8c349f6dce955696850198b8544d0203b467fb Mon Sep 17 00:00:00 2001 From: Roberto Bertó <463349+robertoberto@users.noreply.github.com> Date: Tue, 19 May 2026 02:35:08 +0000 Subject: chore: clean packaging and development tooling MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- docs/development/architecture.md | 77 ----------------------------------- docs/development/quality-and-utils.md | 72 -------------------------------- docs/development/refactor-roadmap.md | 56 ------------------------- 3 files changed, 205 deletions(-) delete mode 100644 docs/development/architecture.md delete mode 100644 docs/development/quality-and-utils.md delete mode 100644 docs/development/refactor-roadmap.md (limited to 'docs/development') diff --git a/docs/development/architecture.md b/docs/development/architecture.md deleted file mode 100644 index aceda08..0000000 --- a/docs/development/architecture.md +++ /dev/null @@ -1,77 +0,0 @@ -# Development Architecture (Proposed) - -## Goals -- Strong separation of concerns (transport, domain, specs, utils) -- Backward compatibility for 0.3.0 via shims -- Clear public API surface and internal boundaries -- Minimal maintenance burden for a public, official SDK - -## Source Layout (file tree) -``` -pyvyos/ - __init__.py # public API exports (VyDevice, ApiResponse) - core/ # internal, stable layers - __init__.py - rest_client.py # RestClient, ApiResponse (transport layer) - device.py # VyDevice (domain layer) - specs/ # optional Pydantic models (validation) - __init__.py - models.py # base models (ApiRequest/Response) - commands/ # split by responsibility - __init__.py - configure.py # set, delete, multiple_op - retrieve.py # show_config, return_values - config_file.py # save, load (path: []) - show.py # show - generate.py # generate - reset.py # reset - system.py # reboot, poweroff - image.py # add, delete - utils/ # reusable helpers (no side effects) - __init__.py - json.py # safe_json, redact_key - http.py # timeouts, retries (future) - paths.py # path builder helpers - ids.py # request_id helpers - exceptions.py # typed exceptions (SDKError, HttpError, ApiError) - types.py # public typing aliases if needed - device.py # shim re-export (compat) - rest.py # shim re-export (compat) - vyos_api/ # JSON specs (docs/reference, optional at runtime) -``` - -## Layers & Responsibilities -- Transport (core.rest_client): HTTP, payload assembly, response validation -- Domain (core.device): high-level methods (configure, show, reset, etc.) -- Specs (specs.*): optional Pydantic models to validate requests/answers -- Utils: pure helpers (formatting, ids, path building) -- Shims (device.py, rest.py): ensure 0.3.0 compatibility - -## Public API Surface -- `from pyvyos import VyDevice, ApiResponse` -- Stable imports; internal moves hidden by shims - -## Compatibility Strategy -- Keep shims until 1.0.0 -- Deprecation policy: warn after N minors, remove at next major -- Document migration path (import from `pyvyos.core` for new code) - -## Data Validation Flow (optional) -- App builds `path` with utils.paths -- If validation enabled, use `specs.commands.*` models -- RestClient serializes payload and executes request -- Response validated (structure: success/data/error) - -## Testing Strategy -- Unit: core.rest_client and core.device isolated via monkeypatch -- Contract: JSON fixtures mirror VyOS responses -- E2E (future): optional with test VyOS VM - -## Packaging -- Include `vyos_api/` only if needed at runtime -- Otherwise treat it as docs/reference, not required by the package - -## Naming & Conventions -- Use underscores `_` in file and module names -- One responsibility per module (keep files small) -- Typed public APIs, specific exceptions, no prints (only logging) diff --git a/docs/development/quality-and-utils.md b/docs/development/quality-and-utils.md deleted file mode 100644 index ff78ec2..0000000 --- a/docs/development/quality-and-utils.md +++ /dev/null @@ -1,72 +0,0 @@ -# Quality, Utils, and Pitfalls - -## Goals -- Reduce regressions and supportability burden -- Consistent error handling and logging -- Clear utilities to avoid duplication - -## Exceptions (typed) -- `SDKError` (base) -- `HttpError(status, message)` -- `ApiError(message, details=None)` # when success=False -- `ValidationError(message)` # client-side validation - -## Logging -- Use `logging.getLogger("pyvyos")` -- Include: op, command, status, elapsed_ms, request_id -- Redact secrets (api key) – via `utils.json.redact_key(data, keys=["key"])` -- Default INFO; DEBUG guarded by env `PYVYOS_DEBUG=1` - -## Timeouts & Retries -- Default timeout: 10s (configurable) -- No implicit retries by default -- Future: retry idempotent ops only (exponential backoff) - -## Security -- `verify=True` by default -- Document `urllib3.disable_warnings()` only for dev -- Never log secrets or full payloads by default - -## Utilities (proposal) -- `utils.paths.build(*segments) -> list[str]` -- `utils.ids.request_id() -> str` -- `utils.json.safe_dumps(obj) -> str` (with redaction) -- `utils.http.timeout(seconds) -> int` (normalize) - -## Validation (optional) -- `specs.commands.*` Pydantic models validate request structures -- Enforce path rules (e.g., config-file requires `path=[]`) -- Gate behind feature flag or optional dependency group - -## Testing -- Unit: small, isolated, no real I/O -- Contract: success/error fixtures per command -- Naming: `test_should__when_` -- Use monkeypatch on `_execute_request` - -## Documentation -- Keep developer docs scoped and short (≤100 lines) -- Update api-reference and path rules on changes - -## Style & Types -- Type hints on public APIs, avoid `Any` -- Early returns, no deep nesting, no bare `except` -- Constants for command/operation strings - -## Release Hygiene -- Conventional commits; CHANGELOG generated -- Tag every release; ensure `git push --tags` -- Patch bumps for fixes, minor for features - -## Potential Pitfalls & Fixes -- Path handling inconsistencies → centralize in RestClient -- Logging secrets → redact before logging -- Tight coupling device↔transport → maintain clean core boundaries -- Hidden breaking changes → keep shims until 1.0.0 -- Non-deterministic tests → remove sleeps, use fixed seeds - -## Next Steps (ordered) -1. Introduce `exceptions.py` and wire into RestClient -2. Add `utils/` with `json.py`, `paths.py`, `ids.py` -3. Add optional `specs/` models for high-value commands -4. CI: lint+type-check, codecov, test matrix diff --git a/docs/development/refactor-roadmap.md b/docs/development/refactor-roadmap.md deleted file mode 100644 index eeee879..0000000 --- a/docs/development/refactor-roadmap.md +++ /dev/null @@ -1,56 +0,0 @@ -# Refactor Roadmap (Prioritized) - -## Priorities -- P0 (now): safety, compatibility, correctness -- P1 (next): validation, observability, developer UX -- P2 (later): performance, async, resiliency - -## P0 — Immediate -- Stabilize transport: keep `_get_payload(include_empty_path)`; special-case `config-file` -- Keep shims: `pyvyos/device.py` and `pyvyos/rest.py` re-export from `pyvyos/core/*` -- Typed exceptions: introduce `SDKError`, `HttpError`, `ApiError`, `ValidationError` -- Timeouts: ensure sane defaults, expose in `VyDevice` -- Logging: centralize in transport, structured key fields (op, command, status) -- Tests: payload assertions for `config-file` (path: []), regression for others -- Docs: architecture and path rules (done) - -## P1 — Short Term -- Specs (optional): Pydantic models in `pyvyos/specs/commands/*` -- `utils/`: path builders, request_id, safe_json redaction -- Deprecation policy: note in README; warn on internal imports (future only) -- CI: test matrix (Python 3.13), codecov, lint (ruff/flake8), type-check (pyright/mypy) -- Release: conventional commits + CHANGELOG; ensure tags push -- Docs: contributor guide, release playbook (short) - -## P2 — Medium Term -- Async client: `AsyncRestClient` (aiohttp/httpx), opt-in -- Retries & backoff: idempotent ops only; circuit-breaker (future) -- Rate limiting: client-side token bucket (opt-in) -- Caching: read-only `show/retrieve` (TTL) optional -- Batch ops: smarter `configure_multiple_op` planning - -## Migration & Compatibility -- Public API: `from pyvyos import VyDevice, ApiResponse` (stable) -- Internal: prefer `pyvyos.core.*` for new code -- Shims stay until 1.0.0; removal at next major only - -## Testing Plan -- Unit: transport (errors, timeouts), domain (paths) -- Contract: sample JSON fixtures per command -- E2E: optional job against a test VyOS (gated, non-blocking) - -## Release Flow (lean) -- Branch: feature → PR → squash merge -- Pre-release (optional): `-rcX` tags -- Tag + publish: GitHub Action (uv build + PyPI publish) - -## Risks & Mitigations -- Hidden breakages → keep shims, add regression tests -- API drift (VyOS) → specs folder eases updates -- Logging noise → default INFO; debug gated via env -- Security → default `verify=True`, redact secrets in logs - -## Success Criteria -- 0.3.x users unaffected -- New structure adopted by contributors -- Lower maintenance overhead (fewer regressions) -- cgit v1.2.3