bbfmodels 0.1.0__py3-none-any.whl

bbfmodels/__init__.py

@@ -0,0 +1,16 @@
+"""Typed models and schema tooling for Broadband Forum data models.
+
+The Broadband Forum publishes its device data models (TR-181, TR-098, TR-104
+and the rest) as XML in the TR-106 schema. This package reads that XML once
+into a normalised intermediate representation, works with the models at
+runtime from that representation, and generates typed bindings from it.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("bbfmodels")
+except PackageNotFoundError:  # running from a source tree that is not installed
+    __version__ = "0.1.0"
+
+__all__ = ["__version__"]

bbfmodels/cli.py

@@ -0,0 +1,79 @@
+"""Command line entry point."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from bbfmodels import __version__, sources
+from bbfmodels.ir import Document
+from bbfmodels.parser import ParseError, parse_file
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="bbfmodels",
+        description="Typed models and schema tooling for Broadband Forum data models.",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    sub = parser.add_subparsers(dest="command")
+
+    fetch = sub.add_parser("fetch", help="download published documents into the local cache")
+    fetch.add_argument("names", nargs="*", help="document file names; none means the core set")
+    fetch.add_argument(
+        "--list", choices=sorted(sources.SITES), help="list what the Forum publishes"
+    )
+    fetch.add_argument("--into", type=Path, help="directory to download into")
+
+    ir = sub.add_parser("ir", help="parse a document and write its IR as JSON")
+    ir.add_argument("document", type=Path)
+    ir.add_argument("-o", "--output", type=Path, help="write here instead of stdout")
+    ir.add_argument("--indent", type=int, default=None, help="pretty-print with this indent")
+
+    sub.add_parser("ir-schema", help="print the JSON Schema of the IR")
+
+    args = parser.parse_args(argv)
+    if args.command is None:
+        parser.print_help()
+        return 0
+    try:
+        if args.command == "fetch":
+            return _fetch(args)
+        if args.command == "ir":
+            return _ir(args)
+        if args.command == "ir-schema":
+            print(json.dumps(Document.model_json_schema(), indent=2))
+            return 0
+    except ParseError as exc:
+        print(f"bbfmodels: {exc}", file=sys.stderr)
+        return 1
+    except OSError as exc:
+        print(f"bbfmodels: {exc}", file=sys.stderr)
+        return 1
+    return 2
+
+
+def _fetch(args: argparse.Namespace) -> int:
+    if args.list:
+        for name in sources.available(args.list):
+            print(name)
+        return 0
+    for name in args.names or sources.CORE:
+        print(sources.fetch(name, args.into))
+    return 0
+
+
+def _ir(args: argparse.Namespace) -> int:
+    doc = parse_file(args.document)
+    text = doc.model_dump_json(exclude_defaults=True, indent=args.indent)
+    if args.output:
+        args.output.write_text(text + "\n", encoding="utf-8")
+    else:
+        print(text)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

bbfmodels/codec.py

@@ -0,0 +1,232 @@
+"""Convert between wire text and Python values, and validate against facets.
+
+CWMP and USP carry every parameter value as text. TR-106 defines how each
+base type is written: integers in decimal, booleans as ``true``/``false``
+or ``1``/``0``, dates in ISO 8601 with the Unknown Time as
+``0001-01-01T00:00:00Z``, binary as upper-case hex or base64, and lists as
+comma-separated items of the base type. ``decode`` and ``encode`` are the
+two directions of that rule; ``problems`` checks a value against the
+syntax's facets and reports every violation it finds.
+"""
+
+from __future__ import annotations
+
+import base64
+import binascii
+import re
+from datetime import UTC, datetime
+from decimal import Decimal, InvalidOperation
+
+from bbfmodels.ir import BaseType, Range, Size, Syntax
+
+Scalar = str | int | bool | datetime | bytes | Decimal
+Value = Scalar | list[Scalar]
+
+UNKNOWN_TIME = datetime(1, 1, 1, tzinfo=UTC)
+
+_BOUNDS = {
+    BaseType.INT: (-(2**31), 2**31 - 1),
+    BaseType.UNSIGNED_INT: (0, 2**32 - 1),
+    BaseType.LONG: (-(2**63), 2**63 - 1),
+    BaseType.UNSIGNED_LONG: (0, 2**64 - 1),
+}
+
+
+class CodecError(ValueError):
+    """The text is not a value of the parameter's type."""
+
+
+# -- scalars ----------------------------------------------------------------
+
+
+def decode_scalar(base_type: BaseType, text: str) -> Scalar:
+    try:
+        match base_type:
+            case BaseType.STRING:
+                return text
+            case BaseType.BOOLEAN:
+                if text in ("1", "true"):
+                    return True
+                if text in ("0", "false"):
+                    return False
+                raise CodecError(f"{text!r} is not a boolean")
+            case BaseType.INT | BaseType.UNSIGNED_INT | BaseType.LONG | BaseType.UNSIGNED_LONG:
+                return int(text)
+            case BaseType.DECIMAL:
+                return Decimal(text)
+            case BaseType.DATE_TIME:
+                return datetime.fromisoformat(text.replace("Z", "+00:00"))
+            case BaseType.HEX_BINARY:
+                return bytes.fromhex(text)
+            case BaseType.BASE64:
+                return base64.b64decode(text, validate=True)
+    except (ValueError, InvalidOperation, binascii.Error) as exc:
+        raise CodecError(f"{text!r} is not a {base_type.value}") from exc
+    raise CodecError(f"unknown base type {base_type!r}")
+
+
+def encode_scalar(base_type: BaseType, value: Scalar) -> str:
+    match base_type:
+        case BaseType.STRING:
+            if isinstance(value, str):
+                return value
+        case BaseType.BOOLEAN:
+            if isinstance(value, bool):
+                return "true" if value else "false"
+        case BaseType.INT | BaseType.UNSIGNED_INT | BaseType.LONG | BaseType.UNSIGNED_LONG:
+            if isinstance(value, int) and not isinstance(value, bool):
+                return str(value)
+        case BaseType.DECIMAL:
+            if isinstance(value, Decimal | int) and not isinstance(value, bool):
+                return str(value)
+        case BaseType.DATE_TIME:
+            if isinstance(value, datetime):
+                if value.tzinfo is None:
+                    raise CodecError("a dateTime needs a time zone")
+                text = value.astimezone(UTC).isoformat()
+                return text.replace("+00:00", "Z")
+        case BaseType.HEX_BINARY:
+            if isinstance(value, bytes):
+                return value.hex().upper()
+        case BaseType.BASE64:
+            if isinstance(value, bytes):
+                return base64.b64encode(value).decode("ascii")
+    raise CodecError(f"{value!r} cannot be written as a {base_type.value}")
+
+
+# -- lists ------------------------------------------------------------------
+
+
+def split_list(text: str, nested_brackets: bool = False) -> list[str]:
+    """Items of a comma-separated list, whitespace around items removed.
+
+    With ``nested_brackets`` an item may itself be a bracketed list, as in
+    ``[a,b],[c]``, and the split happens only at the top level.
+    """
+    if text.strip() == "":
+        return []
+    if not nested_brackets:
+        return [item.strip() for item in text.split(",")]
+    items: list[str] = []
+    depth = 0
+    start = 0
+    for i, ch in enumerate(text):
+        if ch == "[":
+            depth += 1
+        elif ch == "]":
+            depth -= 1
+        elif ch == "," and depth == 0:
+            items.append(text[start:i].strip())
+            start = i + 1
+    items.append(text[start:].strip())
+    return items
+
+
+def join_list(items: list[str]) -> str:
+    return ",".join(items)
+
+
+# -- syntax -----------------------------------------------------------------
+
+
+def decode(syntax: Syntax, text: str) -> Value:
+    """The Python value of a parameter's wire text."""
+    if syntax.list is not None:
+        items = split_list(text, syntax.list.nested_brackets)
+        return [decode_scalar(syntax.base_type, item) for item in items]
+    return decode_scalar(syntax.base_type, text)
+
+
+def encode(syntax: Syntax, value: Value) -> str:
+    """The wire text of a Python value for a parameter."""
+    if syntax.list is not None:
+        if isinstance(value, list):
+            return join_list([encode_scalar(syntax.base_type, item) for item in value])
+        if isinstance(value, str):
+            # A list given as text is passed through as the caller wrote it.
+            return value
+        raise CodecError(f"{value!r} is not a list")
+    if isinstance(value, list):
+        raise CodecError("a list was given for a single value")
+    return encode_scalar(syntax.base_type, value)
+
+
+def problems(syntax: Syntax, text: str) -> list[str]:
+    """Every way the wire text violates the syntax; empty means valid."""
+    found: list[str] = []
+    if syntax.list is not None:
+        items = split_list(text, syntax.list.nested_brackets)
+        lf = syntax.list
+        if lf.min_items is not None and len(items) < lf.min_items:
+            found.append(f"list has {len(items)} items, at least {lf.min_items} required")
+        if lf.max_items is not None and len(items) > lf.max_items:
+            found.append(f"list has {len(items)} items, at most {lf.max_items} allowed")
+        for size in lf.sizes:
+            if size.max_length is not None and len(text) > size.max_length:
+                found.append(f"list text is {len(text)} characters, at most {size.max_length}")
+        for item in items:
+            found.extend(f"item {item!r}: {p}" for p in _scalar_problems(syntax, item))
+        return found
+    return _scalar_problems(syntax, text)
+
+
+def _scalar_problems(syntax: Syntax, text: str) -> list[str]:
+    try:
+        value = decode_scalar(syntax.base_type, text)
+    except CodecError as exc:
+        return [str(exc)]
+    f = syntax.facets
+    found: list[str] = []
+    if isinstance(value, int) and not isinstance(value, bool):
+        low, high = _BOUNDS.get(syntax.base_type, (None, None))
+        if low is not None and high is not None and not low <= value <= high:
+            found.append(f"{value} is outside the {syntax.base_type.value} range")
+        if f.ranges and not any(_in_range(value, r) for r in f.ranges):
+            found.append(f"{value} is outside the allowed ranges")
+    if (
+        isinstance(value, str | bytes)
+        and f.sizes
+        and not any(_in_size(len(value), s) for s in f.sizes)
+    ):
+        found.append(f"length {len(value)} is outside the allowed sizes")
+    if isinstance(value, str):
+        if (
+            f.enumerations
+            and f.enumeration_ref is None
+            and value not in {e.value for e in f.enumerations}
+        ):
+            found.append(f"{value!r} is not one of the enumerated values")
+        if f.patterns and not any(_matches(p.value, value) for p in f.patterns):
+            found.append(f"{value!r} matches none of the patterns")
+    return found
+
+
+def _in_range(value: int, r: Range) -> bool:
+    if r.min_inclusive is not None and value < r.min_inclusive:
+        return False
+    if r.max_inclusive is not None and value > r.max_inclusive:
+        return False
+    return not (r.step and (value - (r.min_inclusive or 0)) % r.step)
+
+
+def _in_size(length: int, s: Size) -> bool:
+    if s.min_length is not None and length < s.min_length:
+        return False
+    return s.max_length is None or length <= s.max_length
+
+
+_pattern_cache: dict[str, re.Pattern[str] | None] = {}
+
+
+def _matches(pattern: str, value: str) -> bool:
+    # TR-106 patterns are XML Schema regular expressions, which are implicitly
+    # anchored. Python's syntax covers the ones the Forum publishes; a pattern
+    # Python cannot compile is treated as matching rather than rejecting
+    # every value.
+    if pattern not in _pattern_cache:
+        try:
+            _pattern_cache[pattern] = re.compile(pattern)
+        except re.error:
+            _pattern_cache[pattern] = None
+    compiled = _pattern_cache[pattern]
+    return compiled is None or compiled.fullmatch(value) is not None

bbfmodels/ir.py

@@ -0,0 +1,327 @@
+"""The intermediate representation (IR) of a Broadband Forum data model.
+
+The IR is the contract between the parser and everything else. The parser
+turns a published TR-106 XML document into one ``Document``; the runtime
+and every code generator read the ``Document`` and never the XML. It is a
+plain, fully resolved description of the model:
+
+- Every object carries its parameters, and for USP its commands and events,
+  keyed by name in document order.
+- Every parameter's syntax carries its effective base type and facets, with
+  named data types (``IPAddress``, ``StatsCounter32``) already resolved
+  through their inheritance chain, so a consumer needs no second lookup.
+  The name of the data type is kept as well, for emitters that want to
+  generate one named type and refer to it.
+- Paths keep the Forum's spelling. A multi-instance object's path ends in
+  ``{i}.`` exactly as the specification writes it; a data path on a device
+  replaces ``{i}`` with an instance number.
+- An attribute the document leaves out is ``None`` or the schema's default
+  (an object or parameter without ``status`` is current).
+
+The models are pydantic so the IR serialises to JSON and has a JSON Schema
+of its own without a second description of it.
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class Status(StrEnum):
+    CURRENT = "current"
+    DEPRECATED = "deprecated"
+    OBSOLETED = "obsoleted"
+    DELETED = "deleted"
+
+
+class Access(StrEnum):
+    READ_ONLY = "readOnly"
+    READ_WRITE = "readWrite"
+    WRITE_ONCE_READ_ONLY = "writeOnceReadOnly"
+
+
+class BaseType(StrEnum):
+    """The primitive types of TR-106. Every parameter resolves to one."""
+
+    STRING = "string"
+    INT = "int"
+    UNSIGNED_INT = "unsignedInt"
+    LONG = "long"
+    UNSIGNED_LONG = "unsignedLong"
+    BOOLEAN = "boolean"
+    DATE_TIME = "dateTime"
+    HEX_BINARY = "hexBinary"
+    BASE64 = "base64"
+    DECIMAL = "decimal"
+
+
+class ActiveNotify(StrEnum):
+    NORMAL = "normal"
+    FORCE_ENABLED = "forceEnabled"
+    FORCE_DEFAULT_ENABLED = "forceDefaultEnabled"
+    CAN_DENY = "canDeny"
+
+
+class _Node(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+
+class Size(_Node):
+    min_length: int | None = None
+    max_length: int | None = None
+
+
+class Range(_Node):
+    min_inclusive: int | None = None
+    max_inclusive: int | None = None
+    step: int | None = None
+
+
+class Enumeration(_Node):
+    value: str
+    code: int | None = None
+    access: Access | None = None
+    optional: bool = False
+    status: Status = Status.CURRENT
+    version: str | None = None
+    description: str = ""
+
+
+class Pattern(_Node):
+    value: str
+    status: Status = Status.CURRENT
+    version: str | None = None
+    description: str = ""
+
+
+class PathRef(_Node):
+    """The parameter holds the path of another object or parameter."""
+
+    ref_type: Literal["strong", "weak"] = "strong"
+    target_parent: str | None = None
+    target_type: str = "row"
+    target_data_type: str | None = None
+
+
+class InstanceRef(_Node):
+    """The parameter holds the instance number of a row of another table."""
+
+    ref_type: Literal["strong", "weak"] = "strong"
+    target_parent: str | None = None
+
+
+class EnumerationRef(_Node):
+    """The allowed values are whatever another parameter lists."""
+
+    target_param: str
+    null_value: str | None = None
+
+
+class Facets(_Node):
+    """Constraints on a value. Which ones apply depends on the base type."""
+
+    sizes: tuple[Size, ...] = ()
+    ranges: tuple[Range, ...] = ()
+    enumerations: tuple[Enumeration, ...] = ()
+    patterns: tuple[Pattern, ...] = ()
+    units: str | None = None
+    path_ref: PathRef | None = None
+    instance_ref: InstanceRef | None = None
+    enumeration_ref: EnumerationRef | None = None
+
+    def merged_over(self, base: Facets) -> Facets:
+        """These facets applied on top of an inherited set.
+
+        A facet kind stated here replaces the inherited one of the same kind;
+        a kind left unstated is inherited. This is how a parameter that uses
+        a named data type narrows it, for example a ``StatsCounter64`` with
+        its own units.
+        """
+        return Facets(
+            sizes=self.sizes or base.sizes,
+            ranges=self.ranges or base.ranges,
+            enumerations=self.enumerations or base.enumerations,
+            patterns=self.patterns or base.patterns,
+            units=self.units if self.units is not None else base.units,
+            path_ref=self.path_ref or base.path_ref,
+            instance_ref=self.instance_ref or base.instance_ref,
+            enumeration_ref=self.enumeration_ref or base.enumeration_ref,
+        )
+
+
+class ListFacets(_Node):
+    """The parameter is a comma-separated list of items of the base type."""
+
+    min_items: int | None = None
+    max_items: int | None = None
+    sizes: tuple[Size, ...] = ()
+    nested_brackets: bool = False
+
+
+class DataType(_Node):
+    """A named data type defined at document level."""
+
+    name: str
+    base: str | None = None
+    base_type: BaseType
+    facets: Facets = Facets()
+    list: ListFacets | None = None
+    description: str = ""
+    status: Status = Status.CURRENT
+
+
+class Default(_Node):
+    kind: Literal["object", "factory", "implementation", "parameter"]
+    value: str
+    status: Status = Status.CURRENT
+
+
+class Syntax(_Node):
+    base_type: BaseType
+    data_type: str | None = None
+    facets: Facets = Facets()
+    list: ListFacets | None = None
+    hidden: bool = False
+    secured: bool = False
+    command: bool = False
+    default: Default | None = None
+
+
+class Parameter(_Node):
+    name: str
+    access: Access | None = None
+    description: str = ""
+    version: str | None = None
+    status: Status = Status.CURRENT
+    active_notify: ActiveNotify = ActiveNotify.NORMAL
+    forced_inform: bool = False
+    mandatory: bool | None = None
+    syntax: Syntax
+
+
+class UniqueKey(_Node):
+    functional: bool = True
+    parameters: tuple[str, ...]
+
+
+class Arguments(_Node):
+    """The input or output of a command, or the payload of an event."""
+
+    parameters: dict[str, Parameter] = Field(default_factory=dict)
+    objects: dict[str, Object] = Field(default_factory=dict)
+
+
+class Command(_Node):
+    name: str
+    is_async: bool = False
+    description: str = ""
+    version: str | None = None
+    status: Status = Status.CURRENT
+    input: Arguments = Field(default_factory=Arguments)
+    output: Arguments = Field(default_factory=Arguments)
+
+
+class Event(_Node):
+    name: str
+    description: str = ""
+    version: str | None = None
+    status: Status = Status.CURRENT
+    arguments: Arguments = Field(default_factory=Arguments)
+
+
+class Object(_Node):
+    """An object of the model, keyed by its path.
+
+    ``path`` is the full path with a trailing dot, ``Device.WiFi.Radio.{i}.``.
+    Inside a command's arguments or an event's payload it is relative to the
+    containing object, ``RouteHops.{i}.``.
+    """
+
+    path: str
+    access: Access | None = None
+    min_entries: int = 1
+    max_entries: int | None = 1
+    num_entries_parameter: str | None = None
+    enable_parameter: str | None = None
+    discriminator_parameter: str | None = None
+    mount_type: str | None = None
+    unique_keys: tuple[UniqueKey, ...] = ()
+    description: str = ""
+    version: str | None = None
+    status: Status = Status.CURRENT
+    parameters: dict[str, Parameter] = Field(default_factory=dict)
+    commands: dict[str, Command] = Field(default_factory=dict)
+    events: dict[str, Event] = Field(default_factory=dict)
+
+    @property
+    def name(self) -> str:
+        """The last segment of the path, ``Radio`` for ``Device.WiFi.Radio.{i}.``."""
+        parts = self.path.rstrip(".").split(".")
+        return parts[-2] if parts[-1] == "{i}" else parts[-1]
+
+    @property
+    def multi_instance(self) -> bool:
+        return self.path.endswith("{i}.")
+
+    @property
+    def parent_path(self) -> str:
+        """The containing object's path, or ``""`` for a root object."""
+        stem = self.path[:-4] if self.multi_instance else self.path
+        head = stem.rstrip(".").rpartition(".")[0]
+        return head + "." if head else ""
+
+
+# Arguments refers to Object, which is defined after it.
+Arguments.model_rebuild()
+
+
+class ProfileObject(_Node):
+    path: str
+    requirement: str
+    parameters: dict[str, str] = Field(default_factory=dict)
+    commands: dict[str, str] = Field(default_factory=dict)
+    events: dict[str, str] = Field(default_factory=dict)
+
+
+class Profile(_Node):
+    name: str
+    base: str | None = None
+    extends: tuple[str, ...] = ()
+    version: str | None = None
+    status: Status = Status.CURRENT
+    description: str = ""
+    parameters: dict[str, str] = Field(default_factory=dict)
+    objects: dict[str, ProfileObject] = Field(default_factory=dict)
+
+
+class Model(_Node):
+    """A root data model, ``Device:2.21``, or a service model, ``VoiceService:2.0``."""
+
+    name: str
+    is_service: bool = False
+    description: str = ""
+    parameters: dict[str, Parameter] = Field(default_factory=dict)
+    objects: dict[str, Object] = Field(default_factory=dict)
+    profiles: dict[str, Profile] = Field(default_factory=dict)
+
+    @property
+    def root(self) -> str:
+        return self.name.partition(":")[0]
+
+    @property
+    def version(self) -> str:
+        return self.name.partition(":")[2]
+
+
+class Document(_Node):
+    """One parsed data model document."""
+
+    spec: str
+    file: str | None = None
+    protocol: Literal["cwmp", "usp"] | None = None
+    description: str = ""
+    data_types: dict[str, DataType] = Field(default_factory=dict)
+    models: tuple[Model, ...] = ()