bbfmodels 0.3.0__tar.gz → 0.4.0__tar.gz

bbfmodels-0.4.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.4.0"
+}

bbfmodels-0.4.0/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+## [0.4.0](https://github.com/ispx-limited/bbfmodels/compare/v0.3.0...v0.4.0) (2026-11-02)
+
+
+### Added
+
+* **models:** USP commands and events as classes and paths, and the xsi:type a CWMP stack needs ([#20](https://github.com/ispx-limited/bbfmodels/issues/20)) ([eca0c46](https://github.com/ispx-limited/bbfmodels/commit/eca0c46a10c6fc205dbc198d051dbb860f321003))
+
+## [0.3.0](https://github.com/ispx-limited/bbfmodels/compare/v0.2.1...v0.3.0) (2026-11-02)
+
+
+### Added
+
+* **paths:** typed paths with autocomplete for every model, no pydantic model needed ([#17](https://github.com/ispx-limited/bbfmodels/issues/17)) ([ba3a7b7](https://github.com/ispx-limited/bbfmodels/commit/ba3a7b7781129477aed7ee015d51f9079521b331))
+
+## [0.2.1](https://github.com/ispx-limited/bbfmodels/compare/v0.2.0...v0.2.1) (2026-11-02)
+
+
+### Fixed
+
+* **models:** generated files no longer record the tool version, which broke the release build ([#10](https://github.com/ispx-limited/bbfmodels/issues/10)) ([ab909c7](https://github.com/ispx-limited/bbfmodels/commit/ab909c7d67b102b11f09122d8c01cea674859e8c))
+* **parser:** a vendor document's empty syntax is read as a string instead of failing ([#11](https://github.com/ispx-limited/bbfmodels/issues/11)) ([7cdb4a1](https://github.com/ispx-limited/bbfmodels/commit/7cdb4a1c4fa39b7741c90a67c84b43812c889fe2))
+* **parser:** a vendor document's unknown vocabulary values fall back with a warning instead of failing ([#13](https://github.com/ispx-limited/bbfmodels/issues/13)) ([bb3e807](https://github.com/ispx-limited/bbfmodels/commit/bb3e80723320fdd69d2b2263ef066d790a28feb2))
+
+## [0.2.0](https://github.com/ispx-limited/bbfmodels/compare/v0.1.0...v0.2.0) (2026-11-02)
+
+
+### Added
+
+* **models:** generated pydantic models for every published data model, and a generator for any document ([#7](https://github.com/ispx-limited/bbfmodels/issues/7)) ([adf73f2](https://github.com/ispx-limited/bbfmodels/commit/adf73f2004eb7cf24673a52298a251af45f39364))
+
+## 0.1.0 (2026-11-02)
+
+
+### Added
+
+* **parser:** read a published document into the intermediate representation ([#1](https://github.com/ispx-limited/bbfmodels/issues/1)) ([462d045](https://github.com/ispx-limited/bbfmodels/commit/462d04530a7d3a7d62a3da440404f4afcadb2c4f))
+* **runtime:** resolve paths, hold a device's values and validate them against the schema ([#3](https://github.com/ispx-limited/bbfmodels/issues/3)) ([35146ad](https://github.com/ispx-limited/bbfmodels/commit/35146adb52757ac9a05836415f87815135c55b94))

bbfmodels-0.4.0/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.5
+Name: bbfmodels
+Version: 0.4.0
+Summary: Typed models and schema tooling for Broadband Forum data models (TR-181, TR-098, TR-104 and more), generated from the published XML
+Project-URL: Homepage, https://github.com/ispx-limited/bbfmodels
+Project-URL: Documentation, https://docs.bbfmodels.ispx.co/
+Project-URL: Changelog, https://docs.bbfmodels.ispx.co/changelog/
+Author: ISPX LIMITED
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Keywords: broadband-forum,cwmp,data-model,tr-069,tr-098,tr-181,tr-369,usp
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Telecommunications Industry
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Networking
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: pydantic>=2.14
+Description-Content-Type: text/markdown
+
+# bbfmodels
+
+Typed models and schema tooling for Broadband Forum data models (TR-181,
+TR-098, TR-104 and the rest), generated from the XML the Forum publishes.
+
+The Forum defines what a broadband gateway exposes to its management system
+as XML in the TR-106 schema: thousands of objects and parameters, their types,
+ranges, enumerations, writability and multi-instance tables. Everyone who
+builds against those models, an ACS, a USP controller, a device simulator, an
+integration script, re-derives the same facts from the same XML and hand-types
+the same parameter paths as strings. bbfmodels does it once:
+
+- A parser that reads the published XML into a normalised intermediate
+  representation, published as JSON with its own schema.
+- A Python runtime that works from that representation: resolve a path,
+  validate a value against the model's constraints, convert between the flat
+  path and value lists that CWMP and USP carry on the wire and a typed tree.
+- Generated typed bindings: pydantic models for Python, shipped for TR-181
+  and TR-098 and the service models (TR-104 voice, TR-135 set-top box,
+  TR-140 storage, TR-196 femtocell, TR-517 Matter), and generated on demand
+  for any other document, a vendor's included.
+- Typed paths for code that only needs correct path strings:
+  `str(Device.WiFi.SSID[1].SSID)` with autocomplete over the whole model
+  and the parameter's definition one attribute away. JSON Schema and TypeScript follow from the
+  same representation, Go when there is a consumer.
+
+Names stay as the Forum wrote them. `Device.WiFi.SSID.{i}.SSID` is a table of
+`SSID` entries indexed by instance number, and the attribute is `SSID`, not
+`ssid`.
+
+## Install
+
+```sh
+pip install bbfmodels
+```
+
+Python 3.11 or later. The one runtime dependency is pydantic.
+
+## Status
+
+Early. The parser, the intermediate representation, the runtime, the
+generated Python models with USP commands and events, and typed paths are
+in place. JSON Schema and TypeScript come next. Before 1.0 a minor release
+may change the IR and the runtime API.
+
+```python
+from bbfmodels.tr181_cwmp import Device
+
+device = Device.from_flat(values_from_the_device)
+radio = device.WiFi.Radio[1]
+radio.Channel  # 36, an int
+radio.Enable  # True
+device.problems()  # every value outside the model's constraints
+device.flatten()  # back to path and text pairs
+```
+
+The design decisions behind the code are in `context/decisions/`, indexed in
+`context/README.md`. Read them before changing the parser or the IR.
+
+## Development
+
+Prerequisites: git and [uv](https://docs.astral.sh/uv/). The pinned Python is
+installed by uv.
+
+```sh
+scripts/bootstrap.sh
+make test
+make lint
+```
+
+`make help` lists the rest. Documentation is built from `docs/` with
+`make docs` and published at https://docs.bbfmodels.ispx.co/.
+
+## Licence
+
+Apache-2.0, copyright ISPX LIMITED. The Broadband Forum publishes its data
+models under the BSD 3-clause licence; output derived from them carries the
+Forum's notice.

bbfmodels-0.4.0/README.md

@@ -0,0 +1,78 @@
+# bbfmodels
+
+Typed models and schema tooling for Broadband Forum data models (TR-181,
+TR-098, TR-104 and the rest), generated from the XML the Forum publishes.
+
+The Forum defines what a broadband gateway exposes to its management system
+as XML in the TR-106 schema: thousands of objects and parameters, their types,
+ranges, enumerations, writability and multi-instance tables. Everyone who
+builds against those models, an ACS, a USP controller, a device simulator, an
+integration script, re-derives the same facts from the same XML and hand-types
+the same parameter paths as strings. bbfmodels does it once:
+
+- A parser that reads the published XML into a normalised intermediate
+  representation, published as JSON with its own schema.
+- A Python runtime that works from that representation: resolve a path,
+  validate a value against the model's constraints, convert between the flat
+  path and value lists that CWMP and USP carry on the wire and a typed tree.
+- Generated typed bindings: pydantic models for Python, shipped for TR-181
+  and TR-098 and the service models (TR-104 voice, TR-135 set-top box,
+  TR-140 storage, TR-196 femtocell, TR-517 Matter), and generated on demand
+  for any other document, a vendor's included.
+- Typed paths for code that only needs correct path strings:
+  `str(Device.WiFi.SSID[1].SSID)` with autocomplete over the whole model
+  and the parameter's definition one attribute away. JSON Schema and TypeScript follow from the
+  same representation, Go when there is a consumer.
+
+Names stay as the Forum wrote them. `Device.WiFi.SSID.{i}.SSID` is a table of
+`SSID` entries indexed by instance number, and the attribute is `SSID`, not
+`ssid`.
+
+## Install
+
+```sh
+pip install bbfmodels
+```
+
+Python 3.11 or later. The one runtime dependency is pydantic.
+
+## Status
+
+Early. The parser, the intermediate representation, the runtime, the
+generated Python models with USP commands and events, and typed paths are
+in place. JSON Schema and TypeScript come next. Before 1.0 a minor release
+may change the IR and the runtime API.
+
+```python
+from bbfmodels.tr181_cwmp import Device
+
+device = Device.from_flat(values_from_the_device)
+radio = device.WiFi.Radio[1]
+radio.Channel  # 36, an int
+radio.Enable  # True
+device.problems()  # every value outside the model's constraints
+device.flatten()  # back to path and text pairs
+```
+
+The design decisions behind the code are in `context/decisions/`, indexed in
+`context/README.md`. Read them before changing the parser or the IR.
+
+## Development
+
+Prerequisites: git and [uv](https://docs.astral.sh/uv/). The pinned Python is
+installed by uv.
+
+```sh
+scripts/bootstrap.sh
+make test
+make lint
+```
+
+`make help` lists the rest. Documentation is built from `docs/` with
+`make docs` and published at https://docs.bbfmodels.ispx.co/.
+
+## Licence
+
+Apache-2.0, copyright ISPX LIMITED. The Broadband Forum publishes its data
+models under the BSD 3-clause licence; output derived from them carries the
+Forum's notice.

bbfmodels-0.4.0/context/README.md

@@ -0,0 +1,25 @@
+# Design memory
+
+This directory is the project's design memory: the decisions that shape
+the code and the reasons behind them, so a contributor, or a coding agent
+working with one, can change the code without undoing a decision by
+accident. Read it before touching the parser, the IR or a generator.
+
+`decisions/` holds one record per significant decision: context, decision,
+consequences, in a page or less. Records are append-only. When a decision
+changes, a new record is written and the old one is marked superseded.
+
+| Number | Title | Status |
+| --- | --- | --- |
+| [0001](decisions/0001-one-parser-one-ir-several-emitters.md) | One parser, one intermediate representation, several emitters | Accepted |
+| [0002](decisions/0002-names-stay-as-the-forum-wrote-them.md) | Names stay as the Forum wrote them | Accepted |
+| [0003](decisions/0003-parse-the-flattened-full-documents.md) | Parse the Forum's flattened full documents | Accepted |
+| [0004](decisions/0004-generated-output-is-committed.md) | Generated output is committed and checked for drift | Accepted |
+| [0005](decisions/0005-python-models-are-pydantic.md) | Generated Python models are pydantic, built lazily per subtree | Accepted |
+| [0006](decisions/0006-everything-optional-unknown-paths-kept.md) | Everything is optional and unknown paths round-trip | Accepted |
+| [0007](decisions/0007-vendor-extensions-are-overlays.md) | Vendor extensions are overlays in the same schema | Accepted |
+| [0008](decisions/0008-python-toolchain.md) | Python toolchain: uv, ruff, mypy, pytest, standard library XML | Accepted |
+| [0009](decisions/0009-the-tree-keeps-wire-text.md) | The data tree keeps wire text and decodes on demand | Accepted |
+| [0010](decisions/0010-generated-python-packages.md) | One generated package per document, lenient on input, strict in `problems` | Accepted |
+| [0011](decisions/0011-typed-paths-are-a-stub-over-the-schema.md) | Typed paths are a generic runtime plus a stub, not generated classes | Accepted |
+| [0012](decisions/0012-commands-and-events-have-argument-paths.md) | Commands and events get argument paths, and classes named by owner | Accepted |

bbfmodels-0.4.0/context/decisions/0012-commands-and-events-have-argument-paths.md

@@ -0,0 +1,47 @@
+# 0012: Commands and events get argument paths, and classes named by owner
+
+## Context
+
+USP adds commands (`Device.Reboot()`, `Device.IP.Diagnostics.TraceRoute()`)
+with input and output arguments, and events (`Device.Boot!`) with a
+payload. The specification gives the command and the event a path but not
+their arguments: an Operate request carries input arguments as a map of
+names to values, and the response the output the same way, with objects
+inside an output (`RouteHops.{i}.`) flattened into dotted names. The
+schema, the models and the paths each needed a way to refer to those
+arguments, and command names repeat across objects (`Reset()`,
+`Upload()`, `ScheduleTimer()`), so a class cannot be named after the
+command alone.
+
+## Decision
+
+- **The schema indexes arguments as objects under synthetic paths**:
+  `Device.IP.Diagnostics.TraceRoute().Input.`,
+  `Device.IP.Diagnostics.TraceRoute().Output.`, `Device.Boot!.`, with the
+  objects inside an output under them
+  (`...TraceRoute().Output.RouteHops.{i}.`). Argument values then resolve
+  and validate like any parameter. These objects are not `children()` of
+  the owning object; they are reached through the command or event.
+- **Generated classes are named by owner, command and side**:
+  `IP_Diagnostics_TraceRoute_Input`, `IP_Diagnostics_TraceRoute_Output`,
+  `IP_Diagnostics_TraceRoute_Output_RouteHops`; an event is `Device_Boot_Event`, the suffix keeping it apart from an object class of the same name.
+  Each package exposes `COMMANDS`, a map from command path to its input
+  and output classes, and `EVENTS`, from event path to its class, so a
+  controller can pick the class for a response by the path it sent.
+  `flatten("")` gives the bare argument names an Operate request carries.
+- **Paths name commands and events as the specification does**:
+  `str(Device.IP.Diagnostics.TraceRoute)` is `Device.IP.Diagnostics.TraceRoute()`
+  and `str(Device.Boot)` is `Device.Boot!`; attribute access drops the
+  suffix, `child()` takes the full name.
+- **`codec.xsd_type` gives the `xsi:type` CWMP carries** for a parameter,
+  derived from its base type, `xsd:string` for any list. This is the one
+  piece a CWMP stack needs from the model that the model alone did not
+  state. SOAP and protobuf envelopes stay out of scope.
+
+## Consequences
+
+- The synthetic paths are bbfmodels' own notation and never appear on the
+  wire; they exist so that one validation routine serves parameters and
+  arguments alike.
+- TR-181 USP generates 1486 classes rather than 975; import time is
+  unchanged at about a third of a second.

bbfmodels-0.4.0/docs/guides/models.md

@@ -0,0 +1,178 @@
+# Generated models
+
+A generated package has a pydantic class per object, a typed optional
+field per parameter and a `dict[int, Child]` per table. Names are the
+Forum's names, PascalCase and all. These packages ship with bbfmodels:
+
+| Package | Document | Root class |
+| --- | --- | --- |
+| `bbfmodels.tr181_cwmp` | TR-181 issue 2, CWMP edition | `Device` |
+| `bbfmodels.tr181_usp` | TR-181 issue 2, USP edition | `Device` |
+| `bbfmodels.tr098` | TR-098 | `InternetGatewayDevice` |
+| `bbfmodels.tr104_1` | TR-104 issue 1, voice on TR-098 gateways | `VoiceService` |
+| `bbfmodels.tr104_cwmp`, `bbfmodels.tr104_usp` | TR-104 issue 2, voice | `VoiceService` |
+| `bbfmodels.tr135_cwmp`, `bbfmodels.tr135_usp` | TR-135, set-top box | `STBService` |
+| `bbfmodels.tr140_cwmp`, `bbfmodels.tr140_usp` | TR-140, storage | `StorageService` |
+| `bbfmodels.tr196_cwmp`, `bbfmodels.tr196_usp` | TR-196, femtocell | `FAPService` |
+| `bbfmodels.tr517_usp` | TR-517, Matter | `MatterService` |
+
+Each package records `SOURCE`, `SPEC` and `MODEL`, and `schema()` returns
+the `Schema` of the IR it was generated from.
+
+## From device values and back
+
+`from_flat` takes the path and value pairs an ACS or USP controller
+returns. Values coerce to their Python type: integers, booleans (`1` and
+`true` alike), dates, binary, decimals, and comma-separated lists.
+
+```python
+from bbfmodels.tr181_cwmp import Device
+
+device = Device.from_flat({
+    "Device.DeviceInfo.UpTime": "1234",
+    "Device.DeviceInfo.FirstUseDate": "2026-01-02T03:04:05Z",
+    "Device.WiFi.Radio.1.Enable": "1",
+    "Device.WiFi.Radio.1.Channel": "36",
+    "Device.WiFi.SSID.1.LowerLayers": "Device.WiFi.Radio.1",
+})
+device.DeviceInfo.UpTime           # 1234
+device.DeviceInfo.FirstUseDate     # datetime(2026, 1, 2, 3, 4, 5, tzinfo=UTC)
+device.WiFi.Radio[1].Enable        # True
+device.WiFi.SSID[1].LowerLayers    # ['Device.WiFi.Radio.1']
+device.WiFi.Radio[2]               # KeyError: only instance 1 was given
+```
+
+Every field is optional, because no device exposes the whole model, and a
+child object that was not given is `None`. Paths may also be relative to
+the object: `Device.from_flat({"WiFi.Radio.1.Channel": "36"})`.
+
+`flatten` writes the model back as path and text pairs in canonical form:
+`true` for a boolean, `a,b` for a list, upper-case hex for binary.
+
+```python
+device.flatten()
+# {'Device.DeviceInfo.UpTime': '1234', ..., 'Device.WiFi.Radio.1.Enable': 'true', ...}
+```
+
+## Validation
+
+Parsing is lenient on purpose. Ranges, sizes, patterns and enumerations are
+not enforced when a model is built, because a real device returns values
+outside them and a model that refused them could not hold what the device
+said. `problems()` reports every violation against the shipped schema:
+
+```python
+device.WiFi.Radio[1].Channel = 999
+device.WiFi.Radio[1].Status = "zz"
+device.problems()
+# [('Device.WiFi.Radio.1.Status', "'zz' is not one of the enumerated values"),
+#  ('Device.WiFi.Radio.1.Channel', '999 is outside the allowed ranges')]
+```
+
+An enumeration is typed `Literal[...] | str`: an editor completes the
+Forum's values, and a vendor's extra value still validates. A parameter
+that takes its allowed values from another parameter, as
+`OperatingChannelBandwidth` does from `SupportedOperatingChannelBandwidths`,
+is not checked against a fixed list, because the list is the device's.
+
+## Tables and construction
+
+A table is a plain `dict[int, Child]`. Classes construct directly, and
+`flatten` takes the data path to write under:
+
+```python
+from bbfmodels.tr181_cwmp.wifi import WiFi_Radio
+
+radio = WiFi_Radio(Enable=True, Channel=36, OperatingFrequencyBand="5GHz")
+radio.flatten("Device.WiFi.Radio.1.")
+# {'Device.WiFi.Radio.1.Enable': 'true', 'Device.WiFi.Radio.1.OperatingFrequencyBand': '5GHz', 'Device.WiFi.Radio.1.Channel': '36'}
+```
+
+Class names are the object's path with the root dropped and dots replaced:
+`WiFi_Radio`, `WiFi_Radio_Stats`, `IP_Interface_IPv4Address`. They live in
+the module of their top-level subtree: `bbfmodels.tr181_cwmp.wifi`,
+`bbfmodels.tr181_cwmp.ip`.
+
+## Vendor parameters
+
+Parameters and objects the model does not define are kept as pydantic
+extras and written back by `flatten`. An unknown parameter is text; an
+unknown object is a nested dict with instance numbers as string keys.
+
+```python
+device = Device.from_flat({
+    "Device.WiFi.Radio.1.X_ACME_TxPower": "high",
+    "Device.X_ACME_Mesh.1.Role": "controller",
+})
+device.WiFi.Radio[1].X_ACME_TxPower   # 'high'
+device.X_ACME_Mesh                    # {'1': {'Role': 'controller'}}
+device.flatten()                      # both paths come back
+```
+
+For typed access to a vendor's extensions, generate a package from the
+vendor's document: see [vendor models](vendor-models.md).
+
+## Service models
+
+A service model's root is a table, `VoiceService.{i}.`, that a device
+mounts under its `Services.` object. The generated classes carry the
+document's paths and the mount is given when converting:
+
+```python
+from bbfmodels.tr104_cwmp import VoiceService
+
+voice = VoiceService.from_flat(values, "Device.Services.VoiceService.1.")
+voice.Capabilities.MaxLineCount
+voice.flatten("Device.Services.VoiceService.1.")
+voice.problems("Device.Services.VoiceService.1.")
+```
+
+Without a prefix, `from_flat` takes paths relative to the instance
+(`Capabilities.MaxLineCount`) and `problems` reports against instance 1.
+
+## Commands and events
+
+The USP packages carry a class for every command's input and output and
+every event's payload. `COMMANDS` maps a command path to its two classes
+and `EVENTS` an event path to its class, which is how a controller picks
+the class for the response to the Operate it sent:
+
+```python
+from bbfmodels.tr181_usp import COMMANDS, EVENTS
+
+request_cls, response_cls = COMMANDS["Device.IP.Diagnostics.TraceRoute()"]
+request = request_cls(Host="example.net", NumberOfTries=3)
+request.flatten("")           # {'Host': 'example.net', 'NumberOfTries': '3'}, the input_args of an Operate
+
+response = response_cls.from_flat({
+    "Status": "Complete",
+    "ResponseTime": "12",
+    "RouteHops.1.Host": "gw",
+    "RouteHops.1.RTTimes": "1,2,3",
+})
+response.RouteHops[1].RTTimes   # [1, 2, 3]
+response.problems()             # checked like any parameter
+
+boot = EVENTS["Device.Boot!"].from_flat({"Cause": "LocalReboot"})
+```
+
+The classes are importable by name too, `IP_Diagnostics_TraceRoute_Input`
+from `bbfmodels.tr181_usp.ip`, named by the owning object, the command
+and the side. In the schema the arguments live under
+`Device.IP.Diagnostics.TraceRoute().Input.` and `.Output.`, and an event's
+under `Device.Boot!.`, which is where `problems()` reports them.
+
+## Names that had to change
+
+Three kinds of Forum name cannot be a Python field as written. The field
+gets a safe name and the Forum's name as its alias, so `from_flat` and
+`flatten` are unaffected:
+
+| Forum name | Field | Why |
+| --- | --- | --- |
+| `Config` | `Config_` | pydantic reads `Config` from a class body as its legacy configuration |
+| `11kRSSIHighThresholdOffset` | `N11kRSSIHighThresholdOffset` | an identifier cannot start with a digit |
+| a name with a hyphen or other symbol | the symbol becomes `_` | not an identifier |
+
+None of the Forum's own documents needs the second or third; vendor
+documents do.

bbfmodels-0.4.0/docs/guides/paths.md

@@ -0,0 +1,104 @@
+# Typed paths
+
+Most code that talks to an ACS or a USP controller never builds a tree of
+values. It asks an API for `Device.WiFi.SSID.1.SSID` by name and reads a
+string back. Typed paths make that name a chain of attributes an editor
+completes and a type checker verifies, with no model involved:
+
+```python
+from bbfmodels.tr181_cwmp.paths import Device
+
+str(Device.WiFi.SSID[1].SSID)              # 'Device.WiFi.SSID.1.SSID'
+str(Device.IP.Interface[1].IPv4Address[2].IPAddress)
+Device.WiFi.Radio[2].Channel == "Device.WiFi.Radio.2.Channel"   # True
+```
+
+Every shipped package has a `paths` module whose root is the model's root
+object. A table is indexed by instance number; the table itself renders as
+the partial path CWMP uses to ask for all of it, and `search` gives the USP
+search path:
+
+```python
+str(Device.WiFi.Radio)          # 'Device.WiFi.Radio.'
+Device.WiFi.Radio.search        # 'Device.WiFi.Radio.*.'
+Device.WiFi.Radio.schema_path   # 'Device.WiFi.Radio.{i}.'
+```
+
+A path knows its definition in the shipped schema, so the type, access,
+constraints and description of a parameter are one attribute away:
+
+```python
+channel = Device.WiFi.Radio[1].Channel
+channel.definition.syntax.base_type        # <BaseType.UNSIGNED_INT: 'unsignedInt'>
+channel.definition.access                  # <Access.READ_WRITE: 'readWrite'>
+channel.definition.syntax.facets.ranges    # (Range(min_inclusive=1, max_inclusive=255, step=None),)
+channel.definition.description[:60]
+Device.WiFi.Radio.definition.num_entries_parameter   # 'RadioNumberOfEntries'
+```
+
+Paths compare and hash as their string, so they work as dictionary keys
+and in sets alongside plain strings.
+
+## Editors and type checkers
+
+At runtime one generic class walks the schema, so the `paths` module is
+three lines and costs nothing to import. Beside it, `paths.pyi` is a stub
+that declares every object and parameter with the Python type of its
+value, which is what the editor completes and the type checker reads:
+
+```python
+class WiFi_RadioPath(ObjectPathBase):
+    Enable: ParamPath[bool]
+    Channel: ParamPath[int]
+    SupportedFrequencyBands: ParamPath[list[str]]
+    Stats: WiFi_Radio_StatsPath
+```
+
+A typo is caught twice: the type checker rejects `Device.WiFi.Radioo`, and
+at runtime it raises `AttributeError` naming the object that has no such
+member.
+
+## Commands and events
+
+In the USP packages a command or event is a member like any other, named
+without its suffix and rendered with it:
+
+```python
+from bbfmodels.tr181_usp.paths import Device
+
+str(Device.IP.Diagnostics.TraceRoute)             # 'Device.IP.Diagnostics.TraceRoute()'
+Device.IP.Diagnostics.TraceRoute.definition.is_async   # True
+str(Device.Boot)                                  # 'Device.Boot!'
+str(Device.child("Reboot()"))                     # the same by its full name
+```
+
+When a parameter or object already has the bare name, the command or event
+takes a trailing underscore: Matter's `ValveFault` parameter sits beside
+its `ValveFault!` event, reached as `ValveFault_`.
+
+## Names the schema does not know
+
+A vendor parameter whose document was not generated is reached
+explicitly, so a typo in a standard name is never silently taken for one:
+
+```python
+str(Device.WiFi.Radio[1].child("X_ACME_TxPower"))   # 'Device.WiFi.Radio.1.X_ACME_TxPower'
+```
+
+Generate the vendor's document instead and the name completes like any
+other; see [vendor models](vendor-models.md). A Forum name that is not a
+Python identifier is exposed the way the models expose it, `N11kEnable` for
+`11kEnable`, and renders the Forum's spelling.
+
+## Service models
+
+A service model's root is a table, and the document does not say where a
+device mounts it, so its paths render from the document's root. Prefix the
+mount when calling an API:
+
+```python
+from bbfmodels.tr104_cwmp.paths import VoiceService
+
+str(VoiceService[1].Capabilities.MaxLineCount)   # 'VoiceService.1.Capabilities.MaxLineCount'
+"Device.Services." + str(VoiceService[1].Capabilities.MaxLineCount)
+```