py61850 0.2.0.dev1__tar.gz → 0.3.0.dev1__tar.gz

{py61850-0.2.0.dev1 → py61850-0.3.0.dev1}/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.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: py61850
-Version: 0.2.0.dev1
+Version: 0.3.0.dev1
 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.dev1}/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.dev1}/ROADMAP.md

@@ -105,15 +105,38 @@ 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/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`.
 - 🧭 **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.dev1}/src/py61850/__init__.py

@@ -21,6 +21,13 @@ 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
+
+    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 +75,11 @@ 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 FUNCTIONAL_CONSTRAINTS, is_control as fc_is_control, \
+    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.dev1"
 
 __all__ = [
     "MmsClient",
@@ -77,6 +87,13 @@ __all__ = [
     "DirEntry",
     "LogicalNode",
     "folder_of",
+    "FUNCTIONAL_CONSTRAINTS",
+    "fc_is_control",
+    "fc_read_rank",
+    "mms_item",
+    "object_reference",
+    "split_item",
+    "da_parts",
     "Iec61850Error",
     "TransportError",
     "MmsError",

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

@@ -14,6 +14,8 @@ 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 and their read ranking
+    refs      IEC 61850-8-1 object reference <-> MMS domain/item names
     quality   the IEC 61850 13-bit Quality bitstring
     time      MMS ``UtcTime`` / ``BinaryTime``
 

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

@@ -0,0 +1,83 @@
+# 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.
+"""
+
+from __future__ import annotations
+
+#: 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"})
+
+# 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))

py61850-0.3.0.dev1/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.dev1/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",
+]

py61850-0.3.0.dev1/src/py61850/scl/_xmlsafe.py

@@ -0,0 +1,113 @@
+# 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.
+"""Refuse an XML document that declares a DTD, before anything expands it.
+
+Every SCL file this library reads arrives from outside -- what a client's
+integrator sent, what a vendor's tool exported. "The file is trusted" is not
+true even on a substation LAN.
+
+A DTD may define entities, and entities may reference each other, so each
+level multiplies::
+
+    <!ENTITY a "AAAAAAAAAA">                        10 chars
+    <!ENTITY b "&a;&a;&a;&a;&a;&a;&a;&a;&a;&a;">    100
+    <!ENTITY c "&b;&b;...">                         1 000
+
+The file stays tiny because it stores only the definitions; the expansion
+happens in memory while parsing, and the parser cannot stop half way -- it
+finishes or the process dies. Measured against this stack: 317 bytes on the
+wire became 1,000,000 characters in 7 ms, a factor of 3155, and two more
+levels of the same file is 100 million. Python's own documentation lists
+``xml.etree.ElementTree`` as vulnerable to it; the attack is old enough to
+have a name, "billion laughs".
+
+Refusing the whole construct is what makes the class gone rather than
+mitigated. It costs nothing, because SCL does not use DTDs -- IEC 61850
+validates against an XSD schema referenced by namespace. Measured over a
+696-file corpus of factory ICDs and substation exports (345 factory ICDs
+and 351 substation SCD/ICD/CID files): **0 with a DOCTYPE**.
+
+Why a separate pass rather than a parser flag: ``xml.etree``'s C parser does
+not expose the expat instance underneath it, so there is no handler to install
+on the parse that actually builds the tree. This runs expat over the PROLOG
+only and stops at the root element, so it reads a few hundred bytes of a 22 MB
+file -- 0.7 ms even on a document padded with a 500 kB comment, which is the
+shape that would defeat a "look at the first N bytes" check.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import BinaryIO
+from xml.parsers import expat
+
+from ..errors import SclError
+
+
+class DtdNotAllowed(SclError, ValueError):
+    """The document declares a ``<!DOCTYPE>``. See this module's docstring.
+
+    Both bases are load-bearing: ``SclError`` so that a caller catching
+    ``Iec61850Error`` catches this too, and ``ValueError`` because that is
+    what it has always been to the callers that predate this package.
+    """
+
+
+class _ReachedRoot(Exception):
+    """Internal: the prolog ended without a DTD, so there is nothing to check."""
+
+
+def _scan(chunks) -> None:
+    """Feed ``chunks`` to expat until the root element or a DTD declaration.
+
+    A malformed prolog raises ``ExpatError``, which is swallowed: the real
+    parse is about to hit the very same bytes with the very same grammar and
+    will report it properly. That is not a way past this check -- a document
+    whose prolog expat cannot read is a document ``ET.parse`` cannot read
+    either.
+    """
+    parser = expat.ParserCreate()
+
+    def _on_doctype(name, sysid, pubid, has_internal_subset):
+        raise DtdNotAllowed(
+            f"the document declares a DTD (<!DOCTYPE {name}>), which this "
+            f"format does not use and which permits entity expansion"
+        )
+
+    def _on_root(name, attrs):
+        raise _ReachedRoot
+
+    parser.StartDoctypeDeclHandler = _on_doctype
+    parser.StartElementHandler = _on_root
+
+    try:
+        for chunk in chunks:
+            parser.Parse(chunk, not chunk)
+    except _ReachedRoot:
+        return
+    except expat.ExpatError:
+        return
+
+
+def _file_chunks(stream: BinaryIO, size: int = 8192):
+    while True:
+        chunk = stream.read(size)
+        yield chunk
+        if not chunk:
+            return
+
+
+def reject_dtd_in_file(path: Path) -> None:
+    """Raise :class:`DtdNotAllowed` if the file at ``path`` declares a DTD."""
+    with open(path, "rb") as fh:
+        _scan(_file_chunks(fh))
+
+
+def reject_dtd_in_bytes(data: bytes) -> None:
+    """Raise :class:`DtdNotAllowed` if ``data`` declares a DTD."""
+    _scan(iter((data, b"")))