py61850 0.3.0.dev1__tar.gz → 0.4.0__tar.gz

py61850-0.4.0/.gitignore

@@ -0,0 +1,45 @@
+__pycache__/
+*.pyc
+*.egg-info/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+downloads/
+relay_files/
+inventory.csv
+
+# SCL / IED capability files (vendor-supplied, large, not redistributable)
+*.icd
+*.ICD
+*.cid
+*.CID
+*.scd
+*.SCD
+*.iid
+*.IID
+*.sed
+*.SED
+fixtures/ICD/
+
+# The round-trip corpus is tracked, by name and never by wildcard.
+#
+# The `*.scd` rule above is right for every SCD except these four: a vendor
+# file dropped in this tree is somebody's substation and must not be
+# committed by accident. The three real ones below were anonymised by
+# `tools/anonymise_scd.py` before they were added -- substation, utility,
+# Windows accounts, machine names and addressing all substituted, IED names
+# deliberately kept. The fourth is hand-written and carries no identity.
+#
+# Named one by one on purpose. A negation like `!tests/fixtures/scl/*.scd`
+# would re-include ANY .scd dropped in that directory, which is exactly how
+# an un-anonymised file reached a sibling repository once.
+!tests/fixtures/scl/sel.scd
+!tests/fixtures/scl/mixed.scd
+!tests/fixtures/scl/siemens.scd
+!tests/fixtures/scl/namespaces.scd
+
+# The substitution mapping names what was substituted -- the substation, the
+# utility, the engineers' accounts. Tracking it would undo the anonymisation.
+tools/*.local.json

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: py61850
-Version: 0.3.0.dev1
+Version: 0.4.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
@@ -135,7 +135,7 @@ with FileTransfer("192.0.2.22") as ft:
                      progress=lambda got, total: print(f"{got}/{total}"))
 ```
 
-### Reading an SCL file
+### Reading an SCL file — and writing it back unchanged
 
 ```python
 from py61850.scl import SclDocument
@@ -153,6 +153,27 @@ for ln in ied.logical_nodes():
         print(attr.reference(), attr.mms_item(), attr.fc, attr.btype)
 ```
 
+A parsed document goes back out as the file it came from:
+
+```python
+doc.write("station.scd")          # atomic: temp file beside it, then os.replace
+raw = doc.to_bytes()              # or the bytes, to hand somewhere else
+```
+
+**Byte for byte**, with no edit applied — comments, indentation, attribute
+order, namespace prefixes, `xmlns` declarations nothing uses, the line ending
+the file was written with and the XML declaration as it was spelled all
+survive. Five differences are permitted, none of them observable through an
+XML parser and every one a limit of the standard library's serialiser:
+attribute quote style, empty-element spacing and form, CDATA boundaries, and
+the spelling of a numeric character reference. `SclDocument.to_bytes` states
+all five; the round-trip test holds them against 44 MB of real station
+exports from three vendors.
+
+That guarantee is the point of the write side. The file goes back into DIGSI
+and SEL Architect, and a library that reformats the 99 % of an SCD it did not
+touch turns every save into a whole-file diff.
+
 `py61850.scl` is imported explicitly and is never pulled in by `import
 py61850`, so the MMS client keeps installing and running unprivileged.
 

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

@@ -108,7 +108,7 @@ with FileTransfer("192.0.2.22") as ft:
                      progress=lambda got, total: print(f"{got}/{total}"))
 ```
 
-### Reading an SCL file
+### Reading an SCL file — and writing it back unchanged
 
 ```python
 from py61850.scl import SclDocument
@@ -126,6 +126,27 @@ for ln in ied.logical_nodes():
         print(attr.reference(), attr.mms_item(), attr.fc, attr.btype)
 ```
 
+A parsed document goes back out as the file it came from:
+
+```python
+doc.write("station.scd")          # atomic: temp file beside it, then os.replace
+raw = doc.to_bytes()              # or the bytes, to hand somewhere else
+```
+
+**Byte for byte**, with no edit applied — comments, indentation, attribute
+order, namespace prefixes, `xmlns` declarations nothing uses, the line ending
+the file was written with and the XML declaration as it was spelled all
+survive. Five differences are permitted, none of them observable through an
+XML parser and every one a limit of the standard library's serialiser:
+attribute quote style, empty-element spacing and form, CDATA boundaries, and
+the spelling of a numeric character reference. `SclDocument.to_bytes` states
+all five; the round-trip test holds them against 44 MB of real station
+exports from three vendors.
+
+That guarantee is the point of the write side. The file goes back into DIGSI
+and SEL Architect, and a library that reformats the 99 % of an SCD it did not
+touch turns every save into a whole-file diff.
+
 `py61850.scl` is imported explicitly and is never pulled in by `import
 py61850`, so the MMS client keeps installing and running unprivileged.
 

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

@@ -111,11 +111,36 @@ Make the client dependable enough for unattended fleet jobs to build on.
       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.
 
 ---
 
+## 0.4 — The SCL round trip ✅
+
+Turns a read-only reader into a read-write one. The model is unchanged; what
+is new is that a document can go back out as the file it came from.
+
+- ✅ **Comment-preserving parse** — `insert_comments` on the tree builder, and
+      every walk in the package tolerates a node whose `tag` is a factory
+      rather than a name. An engineer's note beside a setting is content.
+- ✅ **Namespace fidelity** — prefixes are the document's own, and a
+      declaration the file carries but nothing uses is re-emitted. `sxy:`
+      coordinates are read by DIGSI and SEL Architect to draw a single-line
+      diagram; losing that declaration would damage one silently.
+- ✅ **`SclDocument.to_bytes` / `.write`** — the public write API, atomic on a
+      real path, with the fidelity guarantee and its five cosmetic exceptions
+      stated where a consumer reads them.
+- ✅ **The round-trip test** — four station exports, 44 MB, parsed and written
+      with no edit and compared at the level of bytes. The comparison names
+      what differed rather than that something did.
+
+---
+
 ## 1.0 — MMS simulation 🧭
 
 **Goal:** read an SCL file (`.scd` / `.cid` / `.icd`) and stand up a virtual IED
@@ -137,6 +162,17 @@ image of today's client.
 
       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.3.0.dev1 → py61850-0.4.0}/pyproject.toml

@@ -52,3 +52,9 @@ packages = ["src/py61850"]
 [tool.hatch.build.targets.sdist]
 include = ["src", "tests", "examples", "README.md", "ROADMAP.md", "LICENSE",
            "COMMERCIAL.md", "CONTRIBUTING.md", "CLA.md"]
+# The SCL round-trip corpus is 44 MB of real vendor SCDs -- a development
+# artefact, not something an installer needs. Shipping it would grow the sdist
+# of a zero-dependency standard-library package by ~2.3 MB compressed and buy
+# whoever downloads it nothing. `tests/fixtures/scl/README.md` says how to
+# obtain the corpus; the tests that need it skip when it is absent.
+exclude = ["tests/fixtures/scl/*.scd"]

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

@@ -25,6 +25,11 @@ Public API
                    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
 
@@ -75,11 +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 FUNCTIONAL_CONSTRAINTS, is_control as fc_is_control, \
+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.3.0.dev1"
+__version__ = "0.4.0"
 
 __all__ = [
     "MmsClient",
@@ -90,6 +97,8 @@ __all__ = [
     "FUNCTIONAL_CONSTRAINTS",
     "fc_is_control",
     "fc_read_rank",
+    "CONTROL_DATA_ATTRIBUTES",
+    "fc_is_control_attribute",
     "mms_item",
     "object_reference",
     "split_item",

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

@@ -14,11 +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 and their read ranking
+    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.dev1 → py61850-0.4.0}/src/py61850/core/fc.py

@@ -14,10 +14,18 @@ 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
@@ -44,6 +52,15 @@ FUNCTIONAL_CONSTRAINTS = (
 #: 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
@@ -81,3 +98,24 @@ def read_rank(fc) -> tuple:
     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.dev1 → py61850-0.4.0}/src/py61850/scl/__init__.py

@@ -16,6 +16,18 @@
             for attr in ln.walk():
                 print(attr.reference(), attr.mms_item(), attr.btype)
 
+    doc.write("station.scd")        # atomically, and byte for byte
+
+**Reading is not the whole of it: a document written back out is the file it
+came from.** ``SclDocument.to_bytes`` and ``SclDocument.write`` hold a
+fidelity guarantee -- comments, indentation, attribute order, namespace
+prefixes, declarations nothing uses, the line ending and the XML declaration
+all survive a parse and a serialise, with five exceptions no XML parser can
+observe. :meth:`SclDocument.to_bytes` names all five. It matters because the
+file goes back to DIGSI and to SEL Architect: a library that reformats the
+99 % of a station export it did not touch turns every save into a whole-file
+diff.
+
 **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

{py61850-0.3.0.dev1 → py61850-0.4.0}/src/py61850/scl/controls.py

@@ -111,8 +111,19 @@ class ControlBlock:
 
     @property
     def key(self) -> tuple:
+        """``(iedName, ldInst, name)``.
+
+        ``ldInst`` is ``""`` for a control block on an access-point-level LN,
+        which is what the SCL would spell there too: such a node is in no
+        logical device, so there is no ``inst`` to quote. No file in the
+        reference corpus carries one -- 61850-6 puts control blocks on an
+        ``LN0``, and an access-point LN is never one -- but the key must
+        still be a triple rather than raise, because it is what every
+        publisher/subscriber join in this package looks up by.
+        """
         ld = self.logical_node.ldevice
-        return (ld.ied.name, ld.inst, self.name)
+        return (self.logical_node.ied.name, "" if ld is None else ld.inst,
+                self.name)
 
     def __repr__(self):
         return f"<{self.kind} {self.key!r} datSet={self.dat_set!r}>"