Metadata-Version: 2.5
Name: bbfmodels
Version: 0.3.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 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.

## 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.
