py61850 0.3.0.dev2__tar.gz → 0.5.0__tar.gz

py61850-0.5.0/.gitignore

@@ -0,0 +1,60 @@
+__pycache__/
+*.pyc
+*.egg-info/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+downloads/
+relay_files/
+inventory.csv
+# Written by release.yml, from CHANGELOG.md, to be the GitHub release body.
+RELEASE_NOTES.md
+
+# 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
+
+# IEC reference material -- the schema and namespace packages themselves.
+#
+# `docs/IEC61850 files/` holds IEC's own code-component distributions: the SCL
+# XSD sets (2003, 2007B, 2007B4, 2007C5), the 7-2/7-3/7-4 NSD packages and
+# IEC's note on handling code components. They are IEC copyright, the terms
+# are at www.iec.ch/CCv1, and this repository is public and ships to PyPI.
+#
+# Excluded as a directory rather than by extension, because the useful ones
+# arrive as .zip and a future .xsd dropped beside them must not be committed
+# either. What may be DERIVED from them and shipped -- the content-model
+# ordering table -- is a separate question, recorded as Q17 in the plan.
+docs/IEC61850 files/

py61850-0.5.0/CHANGELOG.md

@@ -0,0 +1,224 @@
+# Changelog — py61850
+
+What changed in each released version. `ROADMAP.md` is the other half and is
+forward-looking: it says what the library can do and what is planned, this says
+what moved and when.
+
+**This file starts at 0.5.0.** Releases up to 0.4.0 were written up in their
+GitHub release bodies and are still there; they are not reconstructed here,
+because a record invented after the fact is worth less than a link to the one
+that was written at the time.
+
+---
+
+## 0.5.0 — 2026-09-15
+
+**`py61850.scl` can now CHANGE an SCL document, not only read one and write it
+back.** 0.3.0 gave the object model, 0.4.0 gave the byte-faithful round trip,
+and this release puts an edit layer between them: four invertible primitives, a
+schema-ordering table that decides where a new element goes, and the IEC 61850-6
+rules that make an edit valid rather than merely applied.
+
+The surface grows from **31 names to 132**. Nothing was removed and nothing
+changed meaning — see *Compatibility* at the end, where that is measured rather
+than asserted.
+
+### The shape of it
+
+Every function returns **a list of edits the caller applies in one go**, and
+`apply_edit` returns the edit that undoes it. That is the whole design: an
+operation that touches six elements in four sections of the file is one call,
+one application and one undo step.
+
+```python
+from py61850.scl import SclDocument, Connection, subscribe
+
+doc = SclDocument.parse("station.scd")
+
+sink  = doc.ied("QMA1_MU1").ext_refs()[2]            # an input awaiting a source
+block = doc.ied("TR01_2414").control_blocks()[3]     # the GOOSE that publishes it
+fcda  = block.logical_node.data_sets[block.dat_set].fcdas[12]
+
+edits = subscribe(doc, [Connection(sink=sink.element,
+                                   fcda=fcda.element,
+                                   control_block=block.element)])
+
+undo = doc.apply_edit(edits)     # ONE history entry, however many edits it is
+doc.write("station.scd")         # byte-faithful everywhere it did not touch
+doc.apply_edit(undo)             # and exactly reversible
+```
+
+**The edit layer works on `xml.etree` elements, not on the model objects.** The
+model is how you find things; `.element` is what you hand to an edit function.
+That is deliberate — an edit has to be expressible for a part of the file the
+read model does not cover, and the `Substation` section below is exactly that
+case.
+
+Depending on what the document already holds, that one `subscribe` call writes
+the ExtRef's binding attributes, creates the `Inputs` element if the logical
+node has none, and — **when asked for, with `ignore_supervision=False`, which is
+not the default** — instantiates the `LGOS`/`LSVS` supervision logical node that
+watches the subscribed control block, allocating its `inst` against what the IED
+already uses. Whether that is one edit or six, it is one call, one application
+and one undo, and undoing it serialises byte-identically to what was there
+before. A property test generates edit sequences and asserts exactly that.
+
+It also refuses: the pair above was chosen by the type-restriction guard, and
+the first candidate tried was rejected with
+
+```
+EditRejected: ExtRef expects SPS.t (Timestamp); SPS.stVal is BOOLEAN
+```
+
+**A rejected edit changes nothing.** Every guard raises `EditRejected` before
+touching the tree; there is no partially applied state to clean up.
+
+### What was added
+
+101 names, in fourteen modules. By area:
+
+| Area | New names | What it covers |
+|---|---:|---|
+| `edit` | 5 | `Insert`, `Remove`, `SetAttributes`, `SetTextContent`, `EditRejected` — the primitives, each computing its inverse before it applies |
+| `ordering` | 3 | `reference_for`, `may_contain`, `content_model` — schema-ordered insertion, table-driven from the SCL content models |
+| `extref` | 12 | `subscribe` / `unsubscribe` / `is_subscribed`, the type-restriction matching behind them, and `fcda_type` |
+| `control_block` | 9 | `control_blocks`, `update_dat_set`, `remove_control_block`, `updated_conf_rev`, `path_id`, `control_block_obj_ref` |
+| `data_set` | 10 | `can_add_data_set`, create / update / remove, `can_add_fcda`, `remove_fcda`, `max_attributes` |
+| `address` | 6 | `create_gse`, `create_smv`, `change_gse_content`, `change_smv_content`, `change_gse_or_smv_address` |
+| `report_control` | 7 | `can_add_report_control`, create / update, `max_report_control`, `number_report_control_instances` |
+| `sampled_value_control` | 3 | `can_add_sampled_value_control`, create, update |
+| `ied` | 5 | `insert_ied`, `remove_ied`, `update_ied` — and the rename fan-out, which is the substance |
+| `supervision` | 11 | `can_instantiate_supervision`, `instantiate_supervision`, `remove_supervision`, `max_supervision` |
+| `data_types` | 8 | `import_lnode_types`, `update_lnode_type`, `remove_data_type`, `same_data_type`, `lnode_type_conflicts` |
+| `substation` | 10 | `update_substation`, `update_voltage_level`, `update_bay`, `remove_process_element`, `prune_lnode_specification` |
+| `generator` | 11 | `next_mac_address`, `next_app_id`, `next_ln_inst`, `unique_element_name` and the ranges they allocate from |
+| `controls` | 1 | `CONTROL_BLOCK_TAGS` |
+
+Three of those are worth naming individually, because they are the ones that do
+more than their name suggests:
+
+- **`update_ied` renames across the whole document, not just the `IED`.**
+  Renaming an IED has to follow every `ExtRef@iedName`, every concatenated
+  object reference that embeds it, and the control-block and supervision
+  references that name it — six element names in all, which is what the schema
+  requires rather than what a search-and-replace would find. `remove_ied`
+  cleans up the subscriptions and supervisions pointing at what it removes.
+- **`import_lnode_types` merges type templates between documents**, with a
+  three-way conflict policy, because 165 type ids are shared between a pair of
+  the three reference exports and **141 of them carry different content**. Reuse
+  is decided on the type's whole closure, not on the element that names it.
+- **`remove_control_block` sweeps by the block**, taking the `GSE` or `SMV`
+  address with it and the supervisions that watch it.
+
+### Where this differs from OpenSCD
+
+`open-scd-core` and `scl-lib` are this layer's reference, and the comparison is
+behavioural: what theirs does against what ours does. Most divergences are
+Python idiom or the fact that this document is an `xml.etree` tree on a server
+rather than a DOM in a browser. These are the ones a caller actually meets.
+
+- **Every function returns everything you should apply, input edit first.** The
+  reference is not uniform here — one function returns the array including the
+  edit you passed it, another returns only the extra edit, a third returns a
+  plural array again — so a caller has to remember, per function, whether to
+  also apply its own input. Ours has one rule. The cost is a return type that
+  disagrees with the reference's for some functions, and the benefit is that
+  applying a fragment on its own and leaving the document half-corrected is not
+  a mistake you can make.
+- **Refusals where the reference guesses.** Subscribing refuses a connection it
+  cannot supervise; importing a type refuses an id collision rather than picking
+  a winner; inserting an IED refuses a name the target already holds. Each of
+  those is a place the reference proceeds. The reasoning is the same every
+  time: this library produces files that go back into DIGSI and SEL Architect,
+  and a wrong answer that loads is worse than a refusal that does not.
+- **Three named outcomes replace a boolean** where an import can reuse, rename
+  or conflict, because two of the three are success and a boolean cannot say
+  which.
+- **`fcda_type` keeps its name**, where the reference calls the same function
+  `fcdaBaseTypes`. It was already in 0.4.0's public surface and this is a MINOR
+  release; renaming a published name is not available, and the existing name is
+  the better one anyway — it returns the same `TypeRestriction` that
+  `ext_ref_type_restrictions` returns, so the two read as the pair they are.
+- **Allocated names are `new<Tag>_01`**, matching the reference's documented
+  behaviour. Ours briefly produced `DataSet`/`DataSet_1` and that was corrected
+  before this tag.
+- **`prune_lnode_specification` is not called `updateLnType`**, because the
+  reference's name for it disagrees with its own doc comment, its return type
+  and its directory: it updates no `lnType`, it removes an `LNode`'s
+  specification children, and those children live in IEC TR 61850-6-100's
+  namespace inside a `Private` rather than in 61850-6 at all.
+- **`unique_element_name` is public**, where the reference does not export it.
+
+### What this release does not implement
+
+Stated because overstating it is the one thing a release note can get wrong that
+nobody notices for a year.
+
+- **Nothing renames a `GSEControl`.** The reference exports `createGSEControl`
+  and `updateGSEControl`; there is no Python equivalent. `ReportControl` and
+  `SampledValueControl` have their full create/update pair, `GSEControl` does
+  not. This is a gap the work found in itself and did not close.
+- **No IEC namespace (NSD) data ships**, so neither `nsdToJson` nor anything
+  built on it has an equivalent. This is a licensing posture, not an oversight.
+  It was measured rather than assumed: `pDO` resolves from the document for
+  **0 of 1,244** ExtRefs in one reference export, so the data genuinely is not
+  in the file.
+- **No plugin adapters.** `lNodeTypeToSelection` shapes a type for an
+  `oscd-tree-grid` widget; the structure it walks is already reachable through
+  `TemplatePool`.
+- **No `checkPermission`.** Authorisation belongs to whatever is driving the
+  library.
+- **`Substation` and `Log` still have no READ MODEL**, and the distinction from
+  the edit layer above is real. `update_substation`, `update_voltage_level`,
+  `update_bay` and `remove_process_element` work on the tree directly and are
+  tested against fixtures built by hand. There is no `doc.substation()` object
+  tree, because **all twenty-three Substation-section element names appear zero
+  times in all three reference exports**, in every namespace — a test asserts
+  that emptiness by scanning the bytes. Building a read model with nothing to
+  check it against is how a reader acquires confident wrong answers.
+
+### Python 3.13 is the new floor
+
+`requires-python` moves from `>=3.9` to `>=3.13`. **Two reasons, and they are
+not the same kind of reason:**
+
+- **3.9 and 3.10 are dead weight.** 3.9 reached end of life in October 2025 and
+  3.10 does so in October 2026. That half is a date.
+- **3.11 and 3.12 are dropped for breadth, not for age.** Both are still
+  supported upstream. Six interpreters is more compatibility surface than a
+  library whose consumers all move together has any reason to carry, and one
+  fewer axis on the matrix is one fewer place a difference can hide. That half
+  is a judgement, and it is recorded as one.
+
+**This cannot break code that already runs.** A floor is enforced by the
+resolver, not by the interpreter: `pip install py61850` on 3.12 is served 0.4.0
+and never a failure. That is why it travels in a MINOR release alongside a
+strictly additive API, and the distinction is the one that matters — removing a
+name breaks a program, raising a floor declines to hand one a newer library.
+
+Nothing in the source branched on the interpreter (`sys.version_info` appears
+nowhere in `src/py61850`), so the bump deletes no logic. The CI matrix narrows
+from six versions to two; Windows still covers both ends of the supported range,
+which is now 3.13 and 3.14.
+
+### Compatibility
+
+**Strictly additive, measured one name at a time.** All 31 names of 0.4.0 were
+compared against this tree at the level of kind, module, MRO and the signature of
+every public member. The entire difference is four additions: `ExtRef` and
+`FCDA` each gained an `element` attribute, and `SclDocument` gained `apply_edit`
+and `parent_of`. No name was removed, no signature changed, no class lost a
+member and nothing moved module.
+
+One consequence worth stating for anyone holding model objects across an edit:
+**`apply_edit` invalidates the lazy caches by ancestry, and a model object you
+already hold is not updated.** Editing inside one IED forgets that IED and leaves
+the other 57 of a station warm; re-reading the edited one costs about 41 ms
+against 3 ms warm on a 22 MB export.
+
+### Verification
+
+1,411 tests, the round trip held against 44 MB of real station exports from
+three vendors, and the edit-invertibility property test run over generated
+sequences. `py61850` still has **zero runtime dependencies**, which CI asserts
+on every run.

py61850-0.5.0/NOTICE-IEC.txt

@@ -0,0 +1,144 @@
+Third-party notice: IEC code components
+=======================================
+
+Two files in this distribution are DERIVED from IEC code components:
+
+    src/py61850/scl/_content_models.py
+    src/py61850/scl/_nsd_types.py
+
+Neither code component is itself part of this distribution, and each derived
+file takes one narrow dimension of the component it came from.
+
+
+1. src/py61850/scl/_content_models.py
+-------------------------------------
+
+It carries the SCL content models -- which child elements each SCL element may
+hold, and the order they go in -- extracted from the SCL XML schema published
+by IEC as a code component of IEC 61850-6. The schema itself is NOT part of
+this distribution. What is derived from it is one structural dimension: element
+names and their order, and none of the schema's attributes, types,
+enumerations, cardinalities, uniqueness constraints or documentation.
+
+Attribution, as the licence below requires:
+
+    This code was derived from IEC 61850-6:2009/AMD1:2018 within modifications
+    permitted in the relevant IEC standard. Please reproduce this note if
+    possible.
+
+The code component it was derived from:
+
+    IEC 61850-6 SCL schema V2007B4
+    Code component id: IEC_61850-6.2007B4.SCL.XSD
+    Publication: IEC 61850-6:2009/AMD1:2018 (Ed. 2.1), dated 2018-01-22
+
+The copyright notice carried by that code component:
+
+    COPYRIGHT (c) IEC, 2018. This version of this XSD is part of
+    IEC 61850-6:2009/AMD1:2018; see the IEC 61850-6:2009/AMD1:2018 for full
+    legal notices. In case of any differences between the here-below code and
+    the IEC published content, the here-below definition supersedes the IEC
+    publication; it may contain updates. See history files. The whole document
+    has to be taken into account to have a full description of this code
+    component.
+    See www.iec.ch/CCv1 for copyright details.
+
+
+2. src/py61850/scl/_nsd_types.py
+--------------------------------
+
+It carries two facts about the IEC 61850 data model -- which common data class
+each data object name has, and which basic type each of a class's data
+attributes has -- extracted from the namespace definitions published by IEC as
+code components of IEC 61850-7-4 and IEC 61850-7-3. The namespace definitions
+themselves are NOT part of this distribution. What is derived from them is the
+type dimension alone, and none of their functional constraints, presence
+conditions, enumerations and their literals, abbreviations, service parameters,
+UML identifiers or documentation.
+
+Attribution, as the licence below requires:
+
+    This code was derived from IEC 61850-7-3:2010 and IEC 61850-7-4:2020 within
+    modifications permitted in the relevant IEC standard. Please reproduce this
+    note if possible.
+
+The code components it was derived from:
+
+    IEC 61850-7-3 namespace definition V2007B5
+    Code component id: IEC 61850-7-3:2007B5
+    Publication: IEC 61850-7-3:2010 (Ed. 2.1), dated 2024-02-12
+
+    IEC 61850-7-4 namespace definition V2007B5
+    Code component id: IEC 61850-7-4:2007B5
+    Publication: IEC 61850-7-4:2020 (Ed. 2.1), dated 2024-02-14
+
+The copyright notice carried by those code components:
+
+    COPYRIGHT (c) IEC, www.iec.ch/tc57/supportdocuments. This version of this
+    NSD is part of IEC_61850-7-3:2010 Edition 2.1 [respectively
+    IEC_61850-7-4:2020 Edition 2.1]; see that publication for full legal
+    notices. In case of any differences between the here-below code and the IEC
+    published content, the here-below definition supersedes the IEC
+    publication; it may contain updates. See history files. The whole document
+    has to be taken into account to have a full description of this code
+    component.
+    See www.iec.ch/CCv1 for copyright details.
+
+
+py61850 is not endorsed by, affiliated with, or approved by IEC.
+
+
+Code Components -- End-user licence agreement
+---------------------------------------------
+
+Reproduced from www.iec.ch/CCv1, which the code component's manifest names as
+its licence.
+
+Code Components in IEC standards (International Standards, Technical
+Specifications or Technical Reports) which have been identified and approved
+for licensing, are licensed subject to the following conditions:
+
+- Redistributions of software must retain the Copyright Notice, this list of
+  conditions and the disclaimer below ("Disclaimer").
+- The software license extends to modifications permitted under the relevant
+  IEC standard.
+- The software license extends to clarifications and corrections approved by
+  IEC.
+- Neither the name of IEC, nor the names of specific contributors, may be used
+  to endorse or promote products derived from this software without specific
+  prior written permission. The relevant IEC standard may be referenced when
+  claiming compliance with the relevant IEC standard.
+- The user of Code Components shall attribute each such Code Component to IEC
+  and identify the IEC standard from which it is taken. Such attribution (e.g.,
+  "This code was derived from IEC [insert standard reference number:publication
+  year] within modifications permitted in the relevant IEC standard. Please
+  reproduce this note if possible."), may be placed in the code itself or any
+  other reasonable location.
+
+Code Components means components included in IEC standards that are intended to
+be directly processed by a computer and also includes any text found between
+the markers <CODE BEGINS> and <CODE ENDS>, or otherwise clearly labeled in this
+standard as a Code Component.
+
+The Disclaimer is:
+
+EACH OF THE CODE COMPONENTS IS PROVIDED BY THE COPYRIGHT HOLDERS AND
+CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
+PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
+CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
+BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
+IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ARISING IN ANY WAY OUT OF THE USE OF THE CODE COMPONENTS, EVEN IF ADVISED OF
+THE POSSIBILITY OF SUCH DAMAGE.
+
+
+Everything else in this distribution
+------------------------------------
+
+Licensed under AGPL-3.0-or-later; see LICENSE. A commercial licence is
+available from the copyright holder -- see COMMERCIAL.md. The terms above
+apply to the derived files named at the top of this notice, and travel with
+them.

py61850-0.3.0.dev2/README.md → py61850-0.5.0/PKG-INFO

@@ -1,3 +1,28 @@
+Metadata-Version: 2.5
+Name: py61850
+Version: 0.5.0
+Summary: Pure-Python IEC 61850 toolkit — an MMS (ISO 9506) client, and an SCL reader/writer/editor with a byte-faithful round trip. Standard library only.
+Project-URL: Homepage, https://github.com/GuilhermeMarini/py61850
+Project-URL: Repository, https://github.com/GuilhermeMarini/py61850
+Project-URL: Issues, https://github.com/GuilhermeMarini/py61850/issues
+Project-URL: Changelog, https://github.com/GuilhermeMarini/py61850/blob/main/CHANGELOG.md
+Project-URL: Roadmap, https://github.com/GuilhermeMarini/py61850/blob/main/ROADMAP.md
+Author: Guilherme
+License-Expression: AGPL-3.0-or-later
+License-File: LICENSE
+License-File: NOTICE-IEC.txt
+Keywords: goose,iec61850,ied,iso9506,mms,relay,sampled-values,scada,substation
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: System :: Networking
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
 # py61850 — IEC 61850 toolkit (pure Python)
 
 An importable library (and its CLIs) for talking to an IEC 61850 IED over MMS
@@ -10,8 +35,14 @@ TCP → TPKT (RFC1006) → COTP (ISO8073) → ISO Session → ISO Presentation
     → ACSE (AARQ/AARE) → MMS (Initiate + confirmed services)
 ```
 
+It is also a **61850-6 (SCL) toolkit**: `py61850.scl` reads an `.scd`/`.cid`/
+`.icd` into a general object model, **changes** it through an edit layer whose
+every operation is invertible, and writes it back **byte for byte** where it did
+not touch. That half needs no relay and no network at all.
+
 See [ROADMAP.md](ROADMAP.md) for what's next (an MMS sniffer, MMS simulation
-from SCL, and a GOOSE sniff/publish interface).
+from SCL, and a GOOSE sniff/publish interface), and
+[CHANGELOG.md](CHANGELOG.md) for what changed in each release.
 
 ## What this library is for
 
@@ -40,11 +71,12 @@ Concretely, that means three things for any change here:
 pip install -e .          # from a checkout (editable)
 # or, once published/tagged:
 # pip install py61850
-# pip install "git+https://github.com/OWNER/py61850@v0.1.0"
+# pip install "git+https://github.com/OWNER/py61850@v0.5.0"
 ```
 
-Requires Python ≥ 3.9. Installs `py61850` (subcommands) plus `mms-scan` and
-`mms-files` for the two MMS drivers directly.
+Requires **Python ≥ 3.13** (raised from 3.9 in 0.5.0 — see
+[CHANGELOG.md](CHANGELOG.md) for both reasons). Installs `py61850`
+(subcommands) plus `mms-scan` and `mms-files` for the two MMS drivers directly.
 
 ## Use as a library
 
@@ -108,7 +140,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 +158,74 @@ 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.
+
+### Changing it — the edit layer
+
+Since 0.5.0 a document can also be **edited**, and every edit is invertible.
+Four primitives (`Insert`, `Remove`, `SetAttributes`, `SetTextContent`) each
+compute their inverse *before* they apply; a list of them is itself an edit,
+applied in order and inverted in reverse. On top of those sit the IEC 61850-6
+rules that decide what may be created where, what a rename has to drag along,
+and where in a parent a new element belongs.
+
+```python
+from py61850.scl import SclDocument, Connection, subscribe
+
+doc = SclDocument.parse("station.scd")
+
+sink  = doc.ied("QMA1_MU1").ext_refs()[2]            # an input awaiting a source
+block = doc.ied("TR01_2414").control_blocks()[3]     # the GOOSE that publishes it
+fcda  = block.logical_node.data_sets[block.dat_set].fcdas[12]
+
+edits = subscribe(doc, [Connection(sink=sink.element,
+                                   fcda=fcda.element,
+                                   control_block=block.element)])
+
+undo = doc.apply_edit(edits)     # ONE history entry, however many edits it is
+doc.write("station.scd")
+doc.apply_edit(undo)             # restores the document exactly
+```
+
+Three things hold the layer together:
+
+- **Every function returns everything you should apply, input edit first.** One
+  rule, one `apply_edit` call, one undo entry — so "subscribe this ExtRef",
+  which may touch an `ExtRef`, an `Inputs` and a supervision logical node in
+  three places, is one step in a caller's history.
+- **The edit functions take `xml.etree` elements, not the model objects.** The
+  model is how you find things and `.element` is what you pass; that is what
+  lets an edit reach a part of the file the read model does not cover.
+- **A rejected edit changes nothing.** Guards raise `EditRejected` before the
+  tree is touched, so there is no half-applied state — the same rule the round
+  trip depends on.
+
+`py61850.scl.__all__` is 132 names across the areas it can edit: control blocks
+and datasets, GSE/SMV addresses, report and sampled-value control, IEDs and the
+rename fan-out, subscription supervision, `DataTypeTemplates` import and merge,
+the `Substation` section, and the allocators for MAC addresses, APPIDs and
+instance numbers. `CHANGELOG.md` lists them by area, says where this diverges
+from OpenSCD and — more usefully — what it does **not** implement.
+
 `py61850.scl` is imported explicitly and is never pulled in by `import
 py61850`, so the MMS client keeps installing and running unprivileged.
 
@@ -157,6 +257,9 @@ use one client per thread.
 | `Iec61850Error` | base of `TransportError`, `MmsError`, and the reserved `LinkError` / `GooseError` / `SvError` / `SclError` |
 | `decode_read_response`, `decode_data_definition`, `decode_service_error` | TLV decoders |
 
+`py61850.scl` has a public surface of its own — 132 names, imported from
+`py61850.scl` rather than from `py61850` — and the two do not overlap.
+
 Everything else — `core.ber`, `mms.pdu`, `osi.*`, `CotpTransport` — is internal
 and may change between releases.
 
@@ -248,7 +351,14 @@ src/py61850/
 ├── link/               # packet-capture sources — planned (ROADMAP 0.2, 2.0)
 ├── goose/              # GOOSE pub/sub — planned (ROADMAP 2.0)
 ├── sv/                 # Sampled Values — planned (after GOOSE)
-├── scl/                # SCL parsing — planned (ROADMAP 1.0)
+├── scl/                # IEC 61850-6: read, edit, write. The largest package
+│   │                   #   here, and never imported by `py61850` itself
+│   ├── document.py     #   SclDocument: parse, the byte-faithful write, edits
+│   ├── model.py        #   the instance tree, built per IED on demand
+│   ├── templates.py    #   DataTypeTemplates resolved once per document
+│   ├── edit.py         #   the four primitives, each inverted before it applies
+│   ├── ordering.py     #   where a new element goes, from the content models
+│   └── …               #   one module per 61850-6 area it can edit
 └── cli/
     ├── main.py         # `py61850` — subcommand dispatcher
     ├── scan.py         # `mms-scan` — data-model scan driver