py61850 0.3.0.dev2__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.dev2 → py61850-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: py61850
-Version: 0.3.0.dev2
+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.dev2 → 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.dev2 → 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.dev2 → 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.dev2 → py61850-0.4.0}/src/py61850/__init__.py

@@ -86,7 +86,7 @@ from .core.fc import CONTROL_DATA_ATTRIBUTES, FUNCTIONAL_CONSTRAINTS, \
     read_rank as fc_read_rank
 from .core.refs import da_parts, mms_item, object_reference, split_item
 
-__version__ = "0.3.0.dev2"
+__version__ = "0.4.0"
 
 __all__ = [
     "MmsClient",

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

@@ -20,6 +20,11 @@ subscriber and a publisher (GOOSE/SV), and be unit-tested offline.
     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.dev2 → 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