bbfmodels 0.1.0__tar.gz → 0.2.1__tar.gz

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

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

bbfmodels-0.2.1/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+## [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.1.0 → bbfmodels-0.2.1}/CLAUDE.md

@@ -10,7 +10,12 @@ is for anyone, person or coding agent, working in the repository.
   architecture decision records and `context/README.md` indexes them. Read
   it before touching the parser, the IR or a generator, and add a record
   when a change makes or reverses a significant decision.
-- `src/bbfmodels/` is the package. `cli.py` is the command line entry point.
+- `src/bbfmodels/` is the package. `cli.py` is the command line entry point,
+  `parser.py` reads the XML into the IR in `ir.py`, `schema.py`, `tree.py`
+  and `codec.py` are the runtime, `generate.py` writes the model packages.
+- `src/bbfmodels/tr*/` are generated packages, one per published document.
+  Never edit them; run `make generate` after changing the generator or
+  the pinned documents in `sources.py`. A test fails when they are stale.
 - `tests/` holds the pytest suite.
 - `docs/` is the documentation site (mkdocs), built strictly in CI. A page
   exists when it has content; nothing is scaffolded empty.

{bbfmodels-0.1.0 → bbfmodels-0.2.1}/CONTRIBUTING.md

@@ -20,7 +20,8 @@ make lint              # format check, lint and type check, what CI runs
   rejects any other title.
 - One change per PR. PRs are squash merged, so the title is the commit.
 - Generated files are never edited by hand. Change the generator or the
-  source document and regenerate; CI fails when committed output is stale.
+  pinned source document and run `make generate`; CI fails when committed
+  output is stale.
 - Attribute and class names keep the Forum's PascalCase verbatim.
 - The tool carries no knowledge of any vendor or product. Vendor behaviour
   comes from a vendor's own data model document, never from code.

{bbfmodels-0.1.0 → bbfmodels-0.2.1}/Makefile

@@ -1,5 +1,5 @@
 .DEFAULT_GOAL := help
-.PHONY: help build test lint run docs clean
+.PHONY: help build test lint run generate docs clean
 
 help: ## List available targets
 	@awk 'BEGIN {FS = ":.*## "} /^[a-zA-Z_-]+:.*## / {printf "%-12s %s\n", $$1, $$2}' $(MAKEFILE_LIST)
@@ -18,6 +18,9 @@ lint: ## Format check, lint and type check, the same commands CI runs
 run: ## Run the command line tool
 	uv run bbfmodels
 
+generate: ## Regenerate the shipped model packages from the pinned documents
+	uv run bbfmodels generate
+
 docs: ## Build the documentation site strictly
 	uv run --with-requirements requirements.txt --no-project python -m unittest discover -s hooks
 	uv run --with-requirements requirements.txt --no-project mkdocs build --strict

{bbfmodels-0.1.0 → bbfmodels-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: bbfmodels
-Version: 0.1.0
+Version: 0.2.1
 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/
@@ -40,20 +40,41 @@ the same parameter paths as strings. bbfmodels does it once:
 - 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 first, JSON Schema and
-  TypeScript from the same representation, Go when there is a consumer.
+- 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. 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
 
-Pre-release. The parser, the intermediate representation and the runtime
-are in place: `bbfmodels fetch` downloads the Forum's published documents,
-`bbfmodels ir` turns one into JSON, and the `Schema` and `Tree` classes
-resolve paths, hold a device's values and validate them. Generated Python
-models come next. Until the first release there is no package on PyPI.
+Early. The parser, the intermediate representation, the runtime and the
+generated Python models are in place. Commands and events in the generated
+models, 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.

{bbfmodels-0.1.0 → bbfmodels-0.2.1}/README.md

@@ -15,20 +15,41 @@ the same parameter paths as strings. bbfmodels does it once:
 - 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 first, JSON Schema and
-  TypeScript from the same representation, Go when there is a consumer.
+- 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. 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
 
-Pre-release. The parser, the intermediate representation and the runtime
-are in place: `bbfmodels fetch` downloads the Forum's published documents,
-`bbfmodels ir` turns one into JSON, and the `Schema` and `Tree` classes
-resolve paths, hold a device's values and validate them. Generated Python
-models come next. Until the first release there is no package on PyPI.
+Early. The parser, the intermediate representation, the runtime and the
+generated Python models are in place. Commands and events in the generated
+models, 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.

{bbfmodels-0.1.0 → bbfmodels-0.2.1}/context/README.md

@@ -20,3 +20,4 @@ changes, a new record is written and the old one is marked superseded.
 | [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 |

bbfmodels-0.2.1/context/decisions/0010-generated-python-packages.md

@@ -0,0 +1,64 @@
+# 0010: One generated package per document, lenient on input, strict in `problems`
+
+## Context
+
+Decision 0005 settled on pydantic models built lazily. Generating them
+raised questions the decision did not answer: how packages and classes are
+named, what a field's type is when the model gives an enumeration or a
+range, how values the model does not allow are treated, and how a Forum
+parameter can be named like a Python helper.
+
+## Decision
+
+- **One package per published document**, named after it: `tr181_cwmp`,
+  `tr181_usp`, `tr098`, `tr104_cwmp`, and so on. The CWMP and USP editions
+  of a document differ in commands, events and a few objects, and a user
+  works against one of them; an older issue that is still deployed carries
+  its issue number (`tr104_1`, the voice model of TR-098 gateways). The
+  package ships the IR it was generated from as `ir.json.gz` and exposes
+  it through `schema()`.
+- **Service models are generated as the document writes them.** A service
+  model's root (`VoiceService.{i}.`) is a table that a device mounts under
+  its `Services.` object, and the document does not say under which root.
+  The classes carry the document's paths; the mount is given when
+  converting: `VoiceService.from_flat(values, "Device.Services.VoiceService.1.")`.
+  Documents that only hold components (TR-143, TR-157) are not generated,
+  because their content is already merged into the root models.
+- **A class per object, a module per top-level subtree.** The root object
+  is a class named after it (`Device`) in `device.py`; every other object
+  is `WiFi_Radio_Stats`, its path with the root dropped, in `wifi.py`.
+  Children are emitted before parents, annotations are evaluated eagerly
+  rather than as strings, and every helper is imported under a
+  leading-underscore alias. Together these make a class body resolve a
+  class name before a field of the same name exists in it, and keep a
+  parameter named `Param` (TR-181 has one) from shadowing the helper.
+  The class's own metadata, its schema path and the package holding its
+  IR, lives in dunder attributes (`__bbf_path__`, `__bbf_package__`):
+  Forum names never start with an underscore, so nothing can collide with
+  them, and pydantic leaves dunder names alone.
+- **Types coerce, facets report.** A field's type is the parameter's
+  Python type: `int`, `bool`, `datetime`, `bytes`, `Decimal`, `str`, or a
+  comma-list of one of them. Ranges, sizes, patterns and enumerations are
+  not pydantic constraints, because a real device returns out-of-range
+  values and vendor enumeration members and a model that rejects them
+  cannot hold what the device said (decision 0006). `problems()` reports
+  every facet violation from the shipped IR instead. An enumeration is
+  typed `Literal[...] | str`, so an editor completes the Forum's values and
+  any other string still validates.
+- **Everything optional, tables are `dict[int, Child]`, unknown paths are
+  kept** as pydantic extras, nested dicts for unknown objects, and
+  `flatten()` writes them back. `flatten()` writes canonical text (`true`,
+  not `1`) because the model holds typed values, not wire text; the data
+  tree (decision 0009) is the exact round-trip surface.
+- **No descriptions in generated code.** They are three megabytes for
+  TR-181 and live in the shipped IR, reachable through `schema()`.
+
+## Consequences
+
+- `import bbfmodels.tr181_cwmp` takes about a third of a second and the
+  first validation about a fifth; the test suite asserts a ceiling.
+- A field whose Forum name collides with a pydantic attribute is emitted
+  with a trailing underscore and an alias of the original name, so wire
+  conversion is unaffected. None of the shipped documents needs it today.
+- Generated code is excluded from the formatter and the linter, and
+  type-checked like the rest of the package.

bbfmodels-0.2.1/docs/guides/cli.md

@@ -0,0 +1,22 @@
+# Command line
+
+```
+bbfmodels fetch [NAME ...] [--list cwmp|usp] [--into DIR]
+bbfmodels ir DOCUMENT [-o FILE] [--indent N]
+bbfmodels ir-schema
+bbfmodels generate [DOCUMENT --package NAME] [--root DIR]
+bbfmodels --version
+```
+
+| Command | Does |
+| --- | --- |
+| `fetch` | Downloads published documents into the cache; no names means the core set. `--list` prints what the Forum publishes for a protocol. |
+| `ir` | Parses a document and writes the IR as JSON, to stdout or `-o`. |
+| `ir-schema` | Prints the JSON Schema of the IR. |
+| `generate` | Writes a package of pydantic models from a document under `--root` (default `src`). With no document, regenerates every shipped package. |
+
+The cache is `~/.cache/bbfmodels`, or `$XDG_CACHE_HOME/bbfmodels`, or
+`$BBFMODELS_CACHE` when set.
+
+Exit status is 0 on success, 1 when a document cannot be read or a file
+cannot be written, with the reason on stderr, and 2 for a usage error.

bbfmodels-0.2.1/docs/guides/documents.md

@@ -0,0 +1,117 @@
+# Documents and the IR
+
+The Broadband Forum publishes each data model as XML in the TR-106 schema,
+in two forms. The modular files assemble objects from imports and reusable
+components; the flattened `-full.xml` files have all of that resolved.
+bbfmodels reads the flattened form only.
+
+## Fetching
+
+`fetch` downloads a document into a local cache, `~/.cache/bbfmodels` or
+`$BBFMODELS_CACHE`, and reuses what is there. Published files never change.
+
+```sh
+bbfmodels fetch                                  # the core set
+bbfmodels fetch tr-181-2-21-0-usp-full.xml       # one document
+bbfmodels fetch --list cwmp                      # everything published for CWMP
+bbfmodels fetch --list usp
+```
+
+The core set is TR-098, TR-104 (both issues), TR-135, TR-140, TR-157,
+TR-181 (CWMP and USP), TR-196 and TR-517. The same call exists in Python:
+
+```python
+from bbfmodels.sources import fetch, available, CORE
+
+path = fetch("tr-181-2-21-0-cwmp-full.xml")
+```
+
+## The intermediate representation
+
+`ir` parses a document into the intermediate representation (IR), the one
+structure everything else in bbfmodels reads:
+
+```sh
+bbfmodels ir tr-181-2-21-0-cwmp-full.xml -o tr-181.json --indent 2
+bbfmodels ir-schema > ir-schema.json             # the IR's JSON Schema
+```
+
+A document has named data types and models. A model has objects keyed by
+path, with `{i}` marking a table exactly as the specification writes it.
+An object has parameters, and in USP documents commands and events; a
+parameter has a syntax with its base type, the name of its data type if it
+used one, and its facets.
+
+```json
+{
+  "spec": "urn:broadband-forum-org:tr-181-2-21-0-cwmp",
+  "protocol": "cwmp",
+  "models": [{
+    "name": "Device:2.21",
+    "objects": {
+      "Device.WiFi.Radio.{i}.": {
+        "path": "Device.WiFi.Radio.{i}.",
+        "access": "readOnly",
+        "min_entries": 0,
+        "max_entries": null,
+        "num_entries_parameter": "RadioNumberOfEntries",
+        "unique_keys": [{"functional": false, "parameters": ["Alias"]}, {"functional": false, "parameters": ["Name"]}],
+        "parameters": {
+          "Channel": {
+            "name": "Channel",
+            "access": "readWrite",
+            "syntax": {
+              "base_type": "unsignedInt",
+              "facets": {"ranges": [{"min_inclusive": 1, "max_inclusive": 255}]}
+            }
+          }
+        }
+      }
+    }
+  }]
+}
+```
+
+Fields at their default are left out: an object without `status` is
+current, a parameter without `list` is a single value, `max_entries` of
+`null` is unbounded.
+
+Named data types are resolved. A parameter declared as `IPv4Address` has
+`"data_type": "IPv4Address"` and a syntax whose base type and facets are
+the fully inherited ones, so no consumer needs a second lookup. The
+document's `data_types` table is there for emitters that want to generate
+a named type.
+
+In Python:
+
+```python
+from bbfmodels.parser import parse_file
+
+doc = parse_file("tr-181-2-21-0-cwmp-full.xml")
+model = doc.models[0]
+radio = model.objects["Device.WiFi.Radio.{i}."]
+radio.multi_instance              # True
+radio.name, radio.parent_path     # 'Radio', 'Device.WiFi.'
+channel = radio.parameters["Channel"].syntax
+channel.base_type                 # <BaseType.UNSIGNED_INT: 'unsignedInt'>
+channel.facets.ranges[0].max_inclusive   # 255
+reboot = parse_file("tr-181-2-21-0-usp-full.xml").models[0].objects["Device."].commands["Reboot()"]
+reboot.input.parameters["Cause"].mandatory   # False
+```
+
+## What the parser tolerates
+
+The published documents are not always well-formed XML, and vendor
+documents captured from devices depart from the schema in small ways. The
+parser repairs what it has seen and warns where it had to decide:
+
+| In the document | What happens |
+| --- | --- |
+| Bare `&` or literal `<OUI>` markup in prose | Escaped before parsing |
+| An attribute published as `value="""` | Read as a quote |
+| Whitespace around a name (`name="Queueing "`) | Dropped |
+| An empty `<syntax/>` | Read as a string, with a `ParseWarning` |
+| An unknown `status`, `access` or `activeNotify` value | The conservative default (`current`, `readOnly`, `normal`), with a `ParseWarning` |
+| `<import>` or `<component>` elements | Rejected: use the flattened `-full.xml` edition |
+
+Anything else the schema does not allow is a `ParseError` naming the place.

bbfmodels-0.2.1/docs/guides/models.md

@@ -0,0 +1,146 @@
+# 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.
+
+## 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.2.1/docs/guides/quickstart.md

@@ -0,0 +1,57 @@
+# Quickstart
+
+```sh
+pip install bbfmodels
+```
+
+Python 3.11 or later; the one runtime dependency is pydantic.
+
+## Typed models of a device
+
+The packages `bbfmodels.tr181_cwmp`, `bbfmodels.tr181_usp`, `bbfmodels.tr098`
+and the service models ship with the package. Build a model from the path
+and value pairs an ACS returns and read typed values:
+
+```python
+from bbfmodels.tr181_cwmp import Device
+
+device = Device.from_flat({
+    "Device.DeviceInfo.UpTime": "1234",
+    "Device.WiFi.Radio.1.Enable": "1",
+    "Device.WiFi.Radio.1.Channel": "36",
+    "Device.WiFi.Radio.1.SupportedFrequencyBands": "2.4GHz,5GHz",
+})
+radio = device.WiFi.Radio[1]
+radio.Channel                     # 36
+radio.SupportedFrequencyBands     # ['2.4GHz', '5GHz']
+device.problems()                 # [] : every value is within the model's constraints
+device.flatten()                  # back to path and text pairs
+```
+
+The [models guide](models.md) covers construction, validation, tables,
+vendor parameters and the service models.
+
+## Resolve and validate paths without generated code
+
+```python
+from bbfmodels.parser import parse_file
+from bbfmodels.schema import Schema
+from bbfmodels.sources import fetch
+
+schema = Schema.from_documents(parse_file(fetch("tr-181-2-21-0-cwmp-full.xml")))
+r = schema.resolve("Device.WiFi.Radio.2.Channel")
+r.schema_path                     # 'Device.WiFi.Radio.{i}.Channel'
+r.parameter.syntax.facets.ranges  # (Range(min_inclusive=1, max_inclusive=255, step=None),)
+```
+
+The [runtime guide](runtime.md) covers the schema, the data tree and the
+codec.
+
+## Generate models for a vendor's document
+
+```sh
+bbfmodels generate vendor-datamodel.xml --package acme.gateway --root src
+```
+
+The [vendor models guide](vendor-models.md) walks through a real vendor
+document from the Forum's XML to typed access to its `X_` extensions.