primarysource 0.1.0__py3-none-any.whl

primarysource/__init__.py

@@ -0,0 +1,5 @@
+"""primarysource: the shared core of the citable document libraries (rfclib, itulib, nistlib, usblib, zimlore)."""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"

primarysource/bbf/__init__.py

@@ -0,0 +1,56 @@
+"""Broadband Forum: the TR-181 and other CWMP/USP data models (XML) and Technical Reports such as TR-069.
+
+Two sources in one collection, because one consumer (cwmp) needs both and a ref reads the same way:
+- data-model XML from https://github.com/BroadbandForum/cwmp-data-models, pinned to one commit, BSD-3-Clause
+  notice in every file (image layer allowed): `bbf:tr-181-2-22-0-ip§Device.IP.Interface.{i}.Enable`;
+- Technical Report PDFs fetched by the user into a volume (TR-069 Amendment 6 Corrigendum 1 so far):
+  `bbf:tr-069-1-6-1§3.5¶2`.
+
+Reading XML needs only the standard library (hardened parser in `_xml.py`); importing a PDF needs `pypdf` (the
+`[bbf]` extra). `docs/bbf.md` is the user-facing description.
+"""
+
+from __future__ import annotations
+
+from primarysource.model import Unit
+from primarysource.refs import Ref, RefGrammar
+from primarysource.registry import Collection
+
+BBF_DOC = r"[a-z][a-z0-9]*(?:-[a-z0-9]+)*"
+"""A document by its Forum file stem: `tr-069-1-6-1` (a report), `tr-181-2-22-0-ip` (a data-model file)."""
+
+BBF_SECTION = r"[^\s#¶§][^\s#¶§]*"
+"""A report clause (`3.5`, `A.3.2.3`, a slug) or a data-model node (`Device.IP.Interface.{i}.Enable`,
+`Device.Reboot()`, `Device.Boot!`, `Baseline:1`). No spaces, never `#`, `¶` or `§`."""
+
+
+class _Refs:
+    """The collection's ref parser: `library.parse_ref` (which also takes the `bbf:` prefix and refuses what the
+    collection has no meaning for), imported on first use so the collection loads without its reader."""
+
+    _grammar = RefGrammar(BBF_DOC, BBF_SECTION)
+
+    def parse(self, text: str) -> Ref:
+        from primarysource.bbf.library import parse_ref
+
+        return parse_ref(text)
+
+    def format(self, ref: Ref) -> str:
+        return self._grammar.format(ref)
+
+
+BBF = Collection(
+    name="bbf",
+    title="Broadband Forum data models and Technical Reports (TR-069, TR-181)",
+    prefix="bbf_",
+    unit=Unit.BLOCK,
+    grammar=_Refs(),
+    server="primarysource.bbf.server:server",
+    cli="primarysource.bbf.cli:main",
+)
+"""Refs: `bbf:tr-069-1-6-1§3.5¶2` and `bbf:tr-181-2-22-0-ip§Device.IP.Interface.{i}.Enable¶1`. `§` names a report
+clause by its number or a data-model node by its full path. `¶n` is the nth sentence of a report clause's span
+(a PDF gives sentences) and the nth paragraph of a data-model node's description; every result's `unit:` footer
+says which. The collection's declared unit is therefore `block`. The `bbf:` prefix is optional."""
+
+__all__ = ["BBF", "BBF_DOC", "BBF_SECTION"]

primarysource/bbf/_xml.py

@@ -0,0 +1,63 @@
+"""The bbf collection's XML reader: the core's hardened `primarysource.readers.xml` with bbf's bounds and names.
+
+The parser moved to the core (`cl.reader_xml_hardened`); this wrapper keeps what the data-model reader and its
+tests rely on:
+
+- the bounds below, and a refusal over the byte bound or a structural bound in bbf's own words;
+- namespace prefixes dropped from element names and namespaced attributes (`xsi:schemaLocation`) ignored, because
+  the BBF files qualify only the root (`dm:document`). Prefixes are not resolved, so an undeclared one is not an
+  error;
+- processing instructions dropped, never acted on.
+
+Everything else the core refuses is still refused: any document type declaration (so no entity, internal or
+external, and no parameter entity), notations, encodings other than UTF-8, malformed input and a second root.
+"""
+
+from __future__ import annotations
+
+import xml.etree.ElementTree as ET  # noqa: S405 - only `Element` objects are renamed here; parsing is the core's
+
+from primarysource.errors import LibError
+from primarysource.readers.xml import XmlRefused, XmlTooDeep, XmlTooLarge
+from primarysource.readers.xml import parse as _parse
+
+MAX_BYTES = 16 * 1024 * 1024
+MAX_ELEMENTS = 1_500_000
+MAX_DEPTH = 64
+MAX_ATTRIBUTES = 64
+MAX_ATTRIBUTE_LENGTH = 64 * 1024
+HINT = "data-model files have none; refusing to parse"
+
+
+def _local(name: str) -> str:
+    return name.rpartition(":")[2]
+
+
+def parse(data: bytes) -> ET.Element:
+    """The root element of `data`, or a `LibError`. Never resolves an entity or reads outside `data`."""
+    if len(data) > MAX_BYTES:
+        raise LibError(f"XML is {len(data)} bytes, over the {MAX_BYTES} byte bound", "")
+    try:
+        root = _parse(
+            data,
+            MAX_BYTES,
+            max_depth=MAX_DEPTH,
+            max_elements=MAX_ELEMENTS,
+            max_attributes=MAX_ATTRIBUTES,
+            max_attribute_length=MAX_ATTRIBUTE_LENGTH,
+            max_text=MAX_BYTES,
+            ignore_processing_instructions=True,
+            namespaces=False,
+            hint=HINT,
+        )
+    except (XmlTooDeep, XmlTooLarge) as exc:
+        message = f"the XML exceeds the parser's bounds: {exc.reason}"
+        raise LibError(message, "this is not a Broadband Forum data-model file") from exc
+    except XmlRefused:
+        raise
+    for element in root.iter():
+        element.tag = _local(element.tag)
+        kept = {k: v for k, v in element.attrib.items() if ":" not in k and k != "xmlns"}
+        if len(kept) != len(element.attrib):
+            element.attrib = kept
+    return root