py61850 0.2.0.dev1__tar.gz → 0.3.0__tar.gz

{py61850-0.2.0.dev1 → py61850-0.3.0}/CONTRIBUTING.md

@@ -23,6 +23,26 @@ Contributions that need **no** CLA: issues, bug reports, feature requests,
 questions, and recorded PDUs for `tests/fixtures/` (data captured from a device,
 not authored code).
 
+## What a patch is judged against
+
+py61850 is a general IEC 61850 toolkit. A change is assessed against what any
+61850 tool would need, not only against the use that prompted it:
+
+- **Model the standard, not one file.** "The files I have do not use it" is a
+  reason to document the gap, not to design it out.
+- **No vendor specifics.** Vendors extend SCL through `Private` elements and
+  through standard attributes carrying vendor value grammars. Expose both
+  faithfully; interpret neither. Vendor handling belongs in a library that
+  attaches to this one.
+- **Derive from the file, do not hardcode a list.** A hardcoded set of names
+  standing in for a type the document already declares is wrong on some
+  document. If `DataTypeTemplates` can answer it, resolve it.
+- **Say what you measured.** The commit body carries the numbers that
+  justified the change. "It is faster" is not a claim this project accepts;
+  "1406 ms to 670 ms on a 22 MB SCD" is.
+- **Zero runtime dependencies, Python 3.9, Linux + Windows + macOS.** All
+  three are checked in CI and none is negotiable.
+
 ## What makes a good patch here
 
 The repository conventions worth knowing before you start; the ones that come

{py61850-0.2.0.dev1 → py61850-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: py61850
-Version: 0.2.0.dev1
+Version: 0.3.0
 Summary: Pure-Python IEC 61850 toolkit — MMS (ISO 9506) client today; GOOSE and SV planned. Standard library only.
 Project-URL: Homepage, https://github.com/GuilhermeMarini/py61850
 Project-URL: Repository, https://github.com/GuilhermeMarini/py61850
@@ -40,6 +40,27 @@ TCP → TPKT (RFC1006) → COTP (ISO8073) → ISO Session → ISO Presentation
 See [ROADMAP.md](ROADMAP.md) for what's next (an MMS sniffer, MMS simulation
 from SCL, and a GOOSE sniff/publish interface).
 
+## What this library is for
+
+py61850 is a general IEC 61850 toolkit, not a support library for one
+application. Every part of it is judged against what an open equivalent of
+IEDScout or an IEC browser would need — and against what the *next* project to
+use it will need, not only the one that prompted the code.
+
+Concretely, that means three things for any change here:
+
+- **Model the standard, not the file in front of you.** If IEC 61850 defines
+  it and a vendor-neutral tool would show it, the API should express it — even
+  when today's caller does not ask.
+- **No vendor specifics in this library.** Vendors extend SCL through
+  `Private` elements and through standard attributes carrying their own value
+  grammars (`sAddr` is the usual one). py61850 exposes both faithfully and
+  interprets neither. A vendor library attaches to the model; it does not
+  live inside it.
+- **Derive, do not hardcode.** A list of names that stands in for a type the
+  file already declares will be wrong on some file. Resolve
+  `DataTypeTemplates` and answer from what the document says.
+
 ## Install
 
 ```bash
@@ -114,6 +135,27 @@ with FileTransfer("192.0.2.22") as ft:
                      progress=lambda got, total: print(f"{got}/{total}"))
 ```
 
+### Reading an SCL file
+
+```python
+from py61850.scl import SclDocument
+
+doc = SclDocument.parse("station.scd")
+
+for name, header in doc.ied_headers.items():           # cheap: no instance tree
+    print(name, header.manufacturer, header.config_version)
+
+print(doc.communication.ip_by_ied())                   # {iedName: IP}
+
+ied = doc.ied("QPC1_TR1_UPC1")                         # built on demand, cached
+for ln in ied.logical_nodes():
+    for attr in ln.walk():
+        print(attr.reference(), attr.mms_item(), attr.fc, attr.btype)
+```
+
+`py61850.scl` is imported explicitly and is never pulled in by `import
+py61850`, so the MMS client keeps installing and running unprivileged.
+
 Errors share one base, so a fleet job catches the whole family at once:
 
 ```python

{py61850-0.2.0.dev1 → py61850-0.3.0}/README.md

@@ -13,6 +13,27 @@ TCP → TPKT (RFC1006) → COTP (ISO8073) → ISO Session → ISO Presentation
 See [ROADMAP.md](ROADMAP.md) for what's next (an MMS sniffer, MMS simulation
 from SCL, and a GOOSE sniff/publish interface).
 
+## What this library is for
+
+py61850 is a general IEC 61850 toolkit, not a support library for one
+application. Every part of it is judged against what an open equivalent of
+IEDScout or an IEC browser would need — and against what the *next* project to
+use it will need, not only the one that prompted the code.
+
+Concretely, that means three things for any change here:
+
+- **Model the standard, not the file in front of you.** If IEC 61850 defines
+  it and a vendor-neutral tool would show it, the API should express it — even
+  when today's caller does not ask.
+- **No vendor specifics in this library.** Vendors extend SCL through
+  `Private` elements and through standard attributes carrying their own value
+  grammars (`sAddr` is the usual one). py61850 exposes both faithfully and
+  interprets neither. A vendor library attaches to the model; it does not
+  live inside it.
+- **Derive, do not hardcode.** A list of names that stands in for a type the
+  file already declares will be wrong on some file. Resolve
+  `DataTypeTemplates` and answer from what the document says.
+
 ## Install
 
 ```bash
@@ -87,6 +108,27 @@ with FileTransfer("192.0.2.22") as ft:
                      progress=lambda got, total: print(f"{got}/{total}"))
 ```
 
+### Reading an SCL file
+
+```python
+from py61850.scl import SclDocument
+
+doc = SclDocument.parse("station.scd")
+
+for name, header in doc.ied_headers.items():           # cheap: no instance tree
+    print(name, header.manufacturer, header.config_version)
+
+print(doc.communication.ip_by_ied())                   # {iedName: IP}
+
+ied = doc.ied("QPC1_TR1_UPC1")                         # built on demand, cached
+for ln in ied.logical_nodes():
+    for attr in ln.walk():
+        print(attr.reference(), attr.mms_item(), attr.fc, attr.btype)
+```
+
+`py61850.scl` is imported explicitly and is never pulled in by `import
+py61850`, so the MMS client keeps installing and running unprivileged.
+
 Errors share one base, so a fleet job catches the whole family at once:
 
 ```python

{py61850-0.2.0.dev1 → py61850-0.3.0}/ROADMAP.md

@@ -105,15 +105,53 @@ Make the client dependable enough for unattended fleet jobs to build on.
 
 ---
 
+## 0.3 — The SCL model ✅
+
+- ✅ `core/fc.py` — the 13 functional constraints of 61850-7-2 and a
+      documented read-preference ranking. In `core` rather than `scl` because
+      a client matching items against `GetLogicalDeviceDirectory` needs the
+      same vocabulary as a reader walking a file.
+- ✅ `core/fc.py` also carries the control model's own data attributes
+      (`Oper`, `SBOw`, `SBO`, `Cancel`) and `is_control_attribute`, which asks
+      "command or reading?" of an attribute NAME. Both directions are needed:
+      an attribute path is often in hand when its FC is not.
+- ✅ `core/refs.py` — object reference ↔ MMS domain and item name (61850-8-1).
+- ✅ `scl/` — see 1.0 below.
+
+---
+
 ## 1.0 — MMS simulation 🧭
 
 **Goal:** read an SCL file (`.scd` / `.cid` / `.icd`) and stand up a virtual IED
 on the network that a real client/HMI can associate to and browse — the mirror
 image of today's client.
 
-- 🧭 **SCL parser** — `py61850.scl` (package reserved): parse IEDs, LDs, LNs, DOs, DAs,
-      DataSets, and Report/Setting control blocks from an SCL XML file into an
-      in-memory object model. (Shared by MMS-sim and GOOSE-sim below.)
+- ✅ **SCL parser** — `py61850.scl`: a general IEC 61850-6 object model.
+      `SclDocument` owns the file; `DataTypeTemplates` is resolved once per
+      document into a shared type pool; the instance tree
+      (IED → AccessPoint → Server → LDevice → LN → DO → DA, plus DataSets,
+      control blocks and ExtRefs) is built per IED on demand. Every node
+      exposes its `Private` elements, which is how a vendor library attaches
+      its own half without parsing the file again.
+
+      It landed ahead of the rest of 1.0 because it is the shared spine: the
+      MMS server answers GetNameList and GetVariableAccessAttributes out of
+      this model, and the GOOSE publisher builds frames from the GoCB and
+      dataset in the same model.
+
+      Not modelled, because no file in the reference corpus carries them: the
+      `Substation` section and `Log`.
+
+      **The vendor seam is proven by two unrelated vendors**, which is what
+      0.3.0 waited for rather than shipping on its author's word. Two
+      libraries outside this project were rebuilt on the model, sharing no
+      code with each other and neither written against it: one reads SEL's
+      `sAddr` value grammar (178,406 configured attributes in one station),
+      the other Siemens' `Private` elements (5,886 of a single type). Both
+      reproduce every field their own XML readers produced, on the same
+      files — one of which is a Siemens export containing SEL relays, read by
+      both without either opening it twice. Nothing was added to this package
+      for the second one.
 - 🧭 **Model → MMS server** — a listening `MmsServer` on TCP 102 that answers the
       confirmed services the client already speaks, driven by the SCL model:
       - Initiate / association (server side of `associate.py`)

{py61850-0.2.0.dev1 → py61850-0.3.0}/src/py61850/__init__.py

@@ -21,6 +21,18 @@ Public API
     LogicalNode    one LN returned by MmsClient.find_logical_nodes()
     folder_of      the folder part of an MMS file name, for grouping hits
 
+    FUNCTIONAL_CONSTRAINTS / fc_is_control / fc_read_rank
+                   the 61850-7-2 functional constraints, shared by the SCL
+                   reader and the live MMS path
+
+    CONTROL_DATA_ATTRIBUTES / fc_is_control_attribute
+                   the control model's own data attributes -- the same
+                   "command, not a reading" question asked of an attribute
+                   name rather than of an FC
+
+    mms_item / object_reference / split_item / da_parts
+                   61850-8-1 naming: object reference <-> MMS domain and item
+
     Iec61850Error  base of every error the library raises
       TransportError   TPKT/COTP/socket and OSI framing failures
       MmsError         MMS service errors, rejects, refused associations
@@ -68,8 +80,13 @@ from .mms.services.directory import LogicalNode
 from .mms.services.files import folder_of
 from .mms.service_error import decode_service_error
 from .mms.types import decode_data_definition
+from .core.fc import CONTROL_DATA_ATTRIBUTES, FUNCTIONAL_CONSTRAINTS, \
+    is_control as fc_is_control, \
+    is_control_attribute as fc_is_control_attribute, \
+    read_rank as fc_read_rank
+from .core.refs import da_parts, mms_item, object_reference, split_item
 
-__version__ = "0.2.0.dev1"
+__version__ = "0.3.0"
 
 __all__ = [
     "MmsClient",
@@ -77,6 +94,15 @@ __all__ = [
     "DirEntry",
     "LogicalNode",
     "folder_of",
+    "FUNCTIONAL_CONSTRAINTS",
+    "fc_is_control",
+    "fc_read_rank",
+    "CONTROL_DATA_ATTRIBUTES",
+    "fc_is_control_attribute",
+    "mms_item",
+    "object_reference",
+    "split_item",
+    "da_parts",
     "Iec61850Error",
     "TransportError",
     "MmsError",

{py61850-0.2.0.dev1 → py61850-0.3.0}/src/py61850/core/__init__.py

@@ -14,9 +14,17 @@ subscriber and a publisher (GOOSE/SV), and be unit-tested offline.
     ber       definite-length BER TLV encode/decode
     data      MMS ``Data`` values -- the CHOICE reused verbatim by GOOSE
               ``allData`` and inside the SV ``savPdu`` envelope
+    fc        the IEC 61850-7-2 functional constraints, the control
+              model's own data attributes, and the read ranking over both
+    refs      IEC 61850-8-1 object reference <-> MMS domain/item names
     quality   the IEC 61850 13-bit Quality bitstring
     time      MMS ``UtcTime`` / ``BinaryTime``
 
-Import these from ``py61850.core.<module>``; they are internal to the package
-and may change between releases.
+Most of this is internal and may change between releases. The exception is
+what the top level re-exports -- ``FUNCTIONAL_CONSTRAINTS``,
+``CONTROL_DATA_ATTRIBUTES``, ``fc_is_control``, ``fc_is_control_attribute``,
+``fc_read_rank``, ``mms_item``, ``object_reference``, ``split_item`` and
+``da_parts``. Those are public API and are reached as ``py61850.<name>``; the
+rest is reached as ``py61850.core.<module>.<name>`` and carries no such
+promise.
 """

py61850-0.3.0/src/py61850/core/fc.py

@@ -0,0 +1,121 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 Guilherme Marini
+#
+# This file is part of py61850. It is free software under the GNU Affero
+# General Public License v3 or later; see LICENSE. A commercial licence,
+# for use in software you do not wish to release under the AGPL, is
+# available from the copyright holder -- see COMMERCIAL.md.
+"""The IEC 61850-7-2 functional constraints.
+
+An FC says what a data attribute *is for* -- a status, a measurement, a
+setting, a command -- and it appears in two places that must agree: the
+``fc`` attribute of a ``DA`` in an SCL file, and the middle segment of an
+MMS item name (``LN$ST$Pos$stVal``).  That is why this lives in ``core``
+rather than under ``scl``: a client matching an item against
+``GetLogicalDeviceDirectory`` needs the same vocabulary as a reader walking
+a file, and must not have to import the SCL package to get it.
+
+The same module answers the same question from the other direction.  An FC
+says a whole container is a command; the control model of 61850-7-2 says
+which *attributes* of a controllable data object carry one.  Both are needed,
+because the two are not always available together -- see
+:func:`is_control_attribute`.
+"""
+
+from __future__ import annotations
+
+from .refs import da_parts
+
+#: Every functional constraint IEC 61850-7-2 defines.
+#:
+#: The first twelve were measured across the three reference SCDs (7.1, 13.5
+#: and 23.5 MB, SEL and Siemens): ``ST SR CF EX SE DC MX OR CO SV SP BL``.
+#: ``SG`` (setting group) completes the standard's set and is kept even
+#: though that corpus does not use it -- a vocabulary with a hole in it fails
+#: silently on the first file that fills it.
+FUNCTIONAL_CONSTRAINTS = (
+    "ST",   # status
+    "MX",   # measurand
+    "SP",   # setpoint
+    "SV",   # substitution
+    "CF",   # configuration
+    "DC",   # description
+    "SG",   # setting group
+    "SE",   # setting group editable
+    "SR",   # service response / service tracking
+    "OR",   # operate received
+    "BL",   # blocking
+    "EX",   # extended definition
+    "CO",   # control
+)
+
+#: The FCs that carry a command rather than a reading.
+CONTROL_FCS = frozenset({"CO"})
+
+#: The data attributes of the 61850-7-2 control model: the ones through which
+#: a controllable data object (SPC, DPC, INC, ENC, BSC, ISC, APC, BAC) is
+#: COMMANDED rather than read.  They are the attribute-name counterpart of
+#: ``CONTROL_FCS``, and they are not redundant with it: an attribute path is
+#: often in hand when its FC is not.  A live client resolving a name against
+#: ``GetLogicalDeviceDirectory``, or any consumer holding an item name whose
+#: middle segment it has not yet parsed, has only the spelling to go on.
+CONTROL_DATA_ATTRIBUTES = frozenset({"Oper", "SBOw", "SBO", "Cancel"})
+
+# Ordered best-to-worst for "if this attribute is reachable under several FCs,
+# which one should be read?".  Status first, then measurand, then the settings
+# and descriptive constraints.  Controls are absent on purpose -- they are
+# ranked by `read_rank` below, strictly last, and never by position here.
+_READ_PREFERENCE = ("ST", "MX", "SP", "CF", "DC", "SR", "OR", "EX", "SV",
+                    "SG", "SE", "BL")
+
+
+def _norm(value) -> str:
+    return value.upper() if isinstance(value, str) else ""
+
+
+def is_valid(fc) -> bool:
+    """Is this one of the 13 functional constraints 7-2 defines?"""
+    return _norm(fc) in FUNCTIONAL_CONSTRAINTS
+
+
+def is_control(fc) -> bool:
+    """Does this FC carry a command rather than a reading?"""
+    return _norm(fc) in CONTROL_FCS
+
+
+def read_rank(fc) -> tuple:
+    """Sort key for one candidate FC; lower is a better thing to poll.
+
+    ``(0, position)`` for anything that is not a control, ``(1, 0)`` for one
+    that is.  The two tiers are deliberate: they keep a control strictly worse
+    than *every* reading, including an FC this table has never heard of.  A
+    command SETS a point, so polling it returns what the device was last told
+    rather than what it sees, and that is worse than an unfamiliar reading.
+    """
+    name = _norm(fc)
+    if name in CONTROL_FCS:
+        return (1, 0)
+    if name in _READ_PREFERENCE:
+        return (0, _READ_PREFERENCE.index(name))
+    return (0, len(_READ_PREFERENCE))
+
+
+def is_control_attribute(path) -> bool:
+    """Does this attribute path address a command rather than a reading?
+
+    Takes either spelling of the descent -- ``"Oper.ctlVal"`` as SCL writes
+    it, ``"Oper$ctlVal"`` as MMS does, or the parts already split.
+
+    Two rules, and the second is not covered by the first.  The path is a
+    command when it descends through one of :data:`CONTROL_DATA_ATTRIBUTES`,
+    which is the control model's own vocabulary; and also when its leaf is a
+    ``ctlVal``, because ``ctlVal`` appears only inside a control and a
+    consumer may hold the leaf without the root that carried it.  The leaf
+    test is a prefix match: 7-3 spells the analogue control value
+    ``ctlVal`` on its own but attaches the setpoint variants beside it, and
+    a name that begins ``ctlVal`` is a control value in every one of them.
+    """
+    parts = da_parts(path)
+    if not parts:
+        return False
+    return parts[0] in CONTROL_DATA_ATTRIBUTES or parts[-1].startswith("ctlVal")

py61850-0.3.0/src/py61850/core/refs.py

@@ -0,0 +1,94 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 Guilherme Marini
+#
+# This file is part of py61850. It is free software under the GNU Affero
+# General Public License v3 or later; see LICENSE. A commercial licence,
+# for use in software you do not wish to release under the AGPL, is
+# available from the copyright holder -- see COMMERCIAL.md.
+"""IEC 61850-8-1 naming: object reference <-> MMS domain and item name.
+
+The same data attribute has two spellings, and a tool that reads files and
+talks to devices needs both::
+
+    object reference   QPC1PRO/PTRC1.Op.general      (61850-6, 61850-7-2)
+    MMS domain + item  QPC1PRO  PTRC1$ST$Op$general  (61850-8-1)
+
+The mapping is mechanical but not obvious: the functional constraint sits
+*between* the logical node and the data object in the MMS spelling and does
+not appear in the object reference at all, and the MMS domain is the LDevice's
+``ldName`` when it has one, or ``iedName`` concatenated with ``inst`` when it
+does not.
+
+This is in ``core`` because it belongs to neither side exclusively: an SCL
+reader builds these names from a file, and an MMS client parses them back out
+of ``GetNameList``.
+"""
+
+from __future__ import annotations
+
+
+def ld_name(ied_name: str, ld_inst: str, ld_name_attr=None) -> str:
+    """The MMS domain of one LDevice.
+
+    ``ldName`` when the file gives one -- 61850-6 allows an LDevice to name
+    itself outright, and then that name IS the domain. Otherwise the 8-1
+    default: the IED's name with the LDevice's ``inst`` appended.
+    """
+    explicit = (ld_name_attr or "").strip()
+    if explicit:
+        return explicit
+    return f"{ied_name or ''}{ld_inst or ''}"
+
+
+def ln_name(prefix, ln_class, inst) -> str:
+    """The MMS spelling of one logical node: prefix + class + instance.
+
+    ``LN0`` is spelled ``LLN0`` by its ``lnClass``, so no special case is
+    needed here -- the caller passes what the element carries.
+    """
+    return f"{prefix or ''}{ln_class or ''}{inst or ''}"
+
+
+def mms_item(ln: str, fc: str, path) -> str:
+    """``PTRC1``, ``ST``, ``["Op", "general"]`` -> ``PTRC1$ST$Op$general``.
+
+    ``path`` is the descent from the data object down to the leaf attribute,
+    one entry per level: ``["Pos", "Oper", "ctlVal"]`` for a control.
+    """
+    return "$".join([ln, fc] + [str(p) for p in path])
+
+
+def object_reference(ld: str, ln: str, path) -> str:
+    """``QPC1PRO``, ``PTRC1``, ``["Op", "general"]``
+    -> ``QPC1PRO/PTRC1.Op.general``.
+
+    The functional constraint is absent by design: an object reference names
+    the object, and the FC says how it is being accessed.
+    """
+    return f"{ld}/{ln}." + ".".join(str(p) for p in path)
+
+
+def split_item(item: str):
+    """``PTRC1$ST$Op$general`` -> ``("PTRC1", "ST", ("Op", "general"))``.
+
+    ``None`` for anything that is not an attribute item -- a bare logical
+    node name, or an empty string. Refusing is deliberate: inventing an FC
+    for a name that carries none produces an item no device serves, and the
+    failure then surfaces far downstream as a silent missing value.
+    """
+    parts = [p for p in (item or "").split("$") if p]
+    if len(parts) < 3:
+        return None
+    return parts[0], parts[1], tuple(parts[2:])
+
+
+def da_parts(da) -> tuple:
+    """``"Oper.ctlVal"`` / ``"Oper$ctlVal"`` -> ``("Oper", "ctlVal")``.
+
+    SCL writes the descent through an SDI with ``.``; MMS spells every level
+    with ``$``. A tool reading both needs one canonical form, and empty
+    segments are dropped rather than preserved.
+    """
+    if not isinstance(da, str):
+        return tuple(da) if da else ()
+    return tuple(p for p in da.replace("$", ".").split(".") if p)

py61850-0.3.0/src/py61850/scl/__init__.py

@@ -0,0 +1,98 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 Guilherme Marini
+#
+# This file is part of py61850. It is free software under the GNU Affero
+# General Public License v3 or later; see LICENSE. A commercial licence,
+# for use in software you do not wish to release under the AGPL, is
+# available from the copyright holder -- see COMMERCIAL.md.
+"""SCL -- the substation configuration files (``.scd`` / ``.cid`` / ``.icd``).
+
+    from py61850.scl import SclDocument
+
+    doc = SclDocument.parse("station.scd")
+    for name in doc.ied_names:
+        ied = doc.ied(name)
+        for ln in ied.logical_nodes():
+            for attr in ln.walk():
+                print(attr.reference(), attr.mms_item(), attr.btype)
+
+**What this package is for.** It is a general IEC 61850-6 implementation,
+judged against what any SCL tool would need -- IEDScout, IEC Browser, OpenSCD
+-- not against what one consumer happens to extract today. If a vendor-neutral
+tool would show it or act on it, the model should express it.
+
+**Vendor specifics never enter this package; they attach to it.** Two seams
+carry them, and both are standard SCL:
+
+- ``Private`` elements, exposed on every model node as ``.privates``, keyed by
+  ``type``. One reference station carries 5,886 of a single vendor's type.
+- Standard attributes whose VALUE holds a vendor grammar. ``sAddr`` is the
+  common one: this package hands over the string and takes no view on it,
+  because the grammar inside it belongs to whoever wrote the file.
+
+A vendor library reads its own half off these model nodes. It never parses the
+XML a second time, and no vendor concept is reflected here.
+
+**Layers.** The granularity follows SCL's own sections rather than being
+imposed on them:
+
+    SclDocument     the file: load/parse, edition, header, privates
+    .templates      DataTypeTemplates -- station-wide, built once, cached
+    .communication  SubNetwork/ConnectedAP/Address/GSE/SMV -- shallow, cheap
+    .ied_headers    identifying fields, no instance tree
+    .ied(name)      the full instance tree for ONE IED, on demand and cached
+
+Templates are document-scoped because they are shared by every IED; instance
+trees are per IED because that is the unit a consumer works in. One reference
+SCD carries 178,406 ``DAI`` elements across 30 IEDs.
+
+This package is never imported by ``py61850`` itself, so the MMS client keeps
+installing and running unprivileged on any OS. It is pure ``xml.etree`` over
+the standard library: no network, no privileges, no dependencies.
+
+**Not implemented yet**, because no file in the reference corpus carries them:
+the ``Substation`` section (VoltageLevel/Bay/ConductingEquipment) and ``Log``.
+Both are in the schema; neither has test material, and building a tree with
+nothing to check it against is how a reader acquires confident wrong answers.
+"""
+
+from ._xmlsafe import DtdNotAllowed, reject_dtd_in_bytes, reject_dtd_in_file
+from .communication import (
+    Address,
+    Communication,
+    ConnectedAP,
+    ControlBlockAddress,
+    SubNetwork,
+)
+from .controls import ControlBlock, DataSet, ExtRef, FCDA, SettingControl
+from .document import (
+    Header,
+    SclDocument,
+    children_local,
+    iter_local,
+    privates_of,
+    strip_ns,
+)
+from .model import (
+    AccessPoint,
+    DataAttribute,
+    DataObject,
+    Ied,
+    IedHeader,
+    LDevice,
+    LogicalNode,
+    Server,
+)
+from .templates import AttributeSpec, DoTypeSpec, LNodeTypeSpec, TemplatePool
+
+__all__ = [
+    "SclDocument", "Header",
+    "DtdNotAllowed", "reject_dtd_in_file", "reject_dtd_in_bytes",
+    "TemplatePool", "LNodeTypeSpec", "DoTypeSpec", "AttributeSpec",
+    "Communication", "SubNetwork", "ConnectedAP", "Address",
+    "ControlBlockAddress",
+    "IedHeader", "Ied", "AccessPoint", "Server", "LDevice", "LogicalNode",
+    "DataObject", "DataAttribute",
+    "DataSet", "FCDA", "ControlBlock", "SettingControl", "ExtRef",
+    "strip_ns", "iter_local", "children_local", "privates_of",
+]