1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
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)
|
