diff options
Diffstat (limited to 'docs/development')
| -rw-r--r-- | docs/development/architecture.md | 77 | ||||
| -rw-r--r-- | docs/development/quality-and-utils.md | 72 | ||||
| -rw-r--r-- | docs/development/refactor-roadmap.md | 56 |
3 files changed, 0 insertions, 205 deletions
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_<do>_when_<condition>` -- 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) |