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
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
|
# 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)
|
