From 6b4e9015744ab8c9f17a6b8e23387cd676b1d827 Mon Sep 17 00:00:00 2001 From: roberto berto Date: Sun, 2 Nov 2025 22:54:44 +0000 Subject: feat: v0.4.0 - Architecture refactor, bug fixes, and quality improvements - Fixed #25: config_file_save/load now include path: [] in payload - Added exception hierarchy (SDKError, HttpError, ApiError, ValidationError) - Added utility functions (json, ids, paths) - Added structured logging with request ID tracking - Added optional Pydantic validation models - Refactored to pyvyos.core.* structure with backward compatibility shims - Moved JSON specs to docs/development/vyos_api/ - Added comprehensive test suite (19 shim tests, 16 utils tests, 6 exception tests) - Updated pyproject.toml for uv sync editable installation - Added development documentation (architecture, roadmap, quality guidelines) Maintains 100% backward compatibility with 0.3.0 --- docs/development/refactor-roadmap.md | 56 ++++++++++++++++++++++++++++++++++++ 1 file changed, 56 insertions(+) create mode 100644 docs/development/refactor-roadmap.md (limited to 'docs/development/refactor-roadmap.md') diff --git a/docs/development/refactor-roadmap.md b/docs/development/refactor-roadmap.md new file mode 100644 index 0000000..eeee879 --- /dev/null +++ b/docs/development/refactor-roadmap.md @@ -0,0 +1,56 @@ +# 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