py61850 0.3.0.dev1__tar.gz → 0.3.0.dev2__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: py61850
-Version: 0.3.0.dev1
+Version: 0.3.0.dev2
 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

{py61850-0.3.0.dev1 → py61850-0.3.0.dev2}/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.3.0.dev2"
 
 __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.3.0.dev2}/src/py61850/core/__init__.py

@@ -14,7 +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
+    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``

{py61850-0.3.0.dev1 → py61850-0.3.0.dev2}/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.3.0.dev2}/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}>"

{py61850-0.3.0.dev1 → py61850-0.3.0.dev2}/src/py61850/scl/model.py

@@ -63,12 +63,15 @@ class LogicalNode:
     type, its datasets, its privates).
     """
 
-    __slots__ = ("element", "ldevice", "ln_class", "prefix", "inst",
+    __slots__ = ("element", "ldevice", "ied", "ln_class", "prefix", "inst",
                  "ln_type", "desc", "is_ln0", "privates", "_cache")
 
-    def __init__(self, el, ldevice, is_ln0=False):
+    def __init__(self, el, ldevice, is_ln0=False, ied=None):
         self.element = el
+        #: The LDevice this LN is served from, or ``None`` for one declared
+        #: straight under an ``AccessPoint``. See :attr:`reference`.
         self.ldevice = ldevice
+        self.ied = ied if ldevice is None else ldevice.ied
         self.ln_class = el.get("lnClass") or ("LLN0" if is_ln0 else "")
         self.prefix = el.get("prefix") or ""
         self.inst = el.get("inst") or ""
@@ -84,8 +87,17 @@ class LogicalNode:
         return _ln_name(self.prefix, self.ln_class, self.inst)
 
     @property
-    def reference(self) -> str:
-        """``LDName/LNName``."""
+    def reference(self):
+        """``LDName/LNName``, or ``None`` for an access-point-level LN.
+
+        ``None`` is not a failure: an LN declared directly under an
+        ``AccessPoint`` sits in no logical device, so it has no MMS domain
+        and 61850-6 gives it no ``LDName/LNName`` reference to return. It is
+        still a real logical node with a type, inputs and privates -- see
+        :attr:`AccessPoint.logical_nodes`.
+        """
+        if self.ldevice is None:
+            return None
         return f"{self.ldevice.ld_name}/{self.name}"
 
     @property
@@ -99,7 +111,7 @@ class LogicalNode:
         """
         dos = self._cache.get("data_objects")
         if dos is None:
-            pool = self.ldevice.ied.document.templates
+            pool = self.ied.document.templates
             spec = pool.lnode_type(self.ln_type)
             dos = self._cache["data_objects"] = {}
             if spec is not None:
@@ -204,7 +216,7 @@ class Server:
 
 
 class AccessPoint:
-    """One ``AccessPoint``. ``server`` is ``None`` when it hosts none.
+    """One ``AccessPoint``: a ``Server``, and any LNs declared beside it.
 
     An IED may have several -- 41 across 30 IEDs in one reference SCD -- and an
     access point without a Server is normal: it may delegate to a sibling
@@ -217,19 +229,37 @@ class AccessPoint:
     rather than "no Server, full stop" -- a consumer that needs the
     delegation resolved still has to read ``<ServerAt>`` off ``element``
     itself.
+
+    ``logical_nodes`` holds the LNs 61850-6 allows DIRECTLY under an access
+    point, outside any ``Server``. They are how a gateway or proxy declares
+    the interface it presents -- an ``ITCI`` for a telecontrol interface, an
+    ``IHMI`` for an operator one -- and they are real logical nodes: they
+    carry a type, privates, and their own ``Inputs``. What they do not carry
+    is a logical device, so they have no MMS domain and no
+    ``LDName/LNName`` reference; :attr:`LogicalNode.reference` is ``None``
+    for them.
+
+    Measured on the reference corpus: exactly one, the ``ITCI`` on the RTAC
+    gateway's ``C1`` access point in the SEL station, and it holds 58 bound
+    ``ExtRef`` entries -- a quarter of that station's subscriptions.  Before
+    they were modelled, ``Ied.ext_refs()`` claimed to return every ExtRef in
+    the IED and returned 1,290 of that gateway's 1,348.
     """
 
-    __slots__ = ("element", "name", "server", "privates")
+    __slots__ = ("element", "name", "server", "logical_nodes", "privates")
 
     def __init__(self, el, ied):
         self.element = el
         self.name = el.get("name") or ""
         server_el = next(children_local(el, "Server"), None)
         self.server = Server(server_el, ied) if server_el is not None else None
+        self.logical_nodes = [LogicalNode(n, None, ied=ied)
+                              for n in children_local(el, "LN")]
         self.privates = privates_of(el)
 
     def __repr__(self):
-        return f"<AccessPoint {self.name!r} server={self.server is not None}>"
+        return (f"<AccessPoint {self.name!r} server={self.server is not None} "
+                f"lns={len(self.logical_nodes)}>")
 
 
 class Ied:
@@ -282,8 +312,18 @@ class Ied:
                 for ld in ap.server.ldevices]
 
     def logical_nodes(self) -> list:
-        """Every logical node in the IED, in document order."""
-        return [n for ld in self.ldevices() for n in ld.logical_nodes]
+        """Every logical node in the IED, in document order.
+
+        The LDevices' nodes first, then the ones declared directly under an
+        access point. The access-point ones come last rather than in strict
+        document order because they are the exception: a consumer walking
+        this list is almost always after the servable model, and the
+        handful that answer :attr:`LogicalNode.reference` with ``None``
+        are better met at the end than interleaved.
+        """
+        nodes = [n for ld in self.ldevices() for n in ld.logical_nodes]
+        nodes.extend(n for ap in self.access_points for n in ap.logical_nodes)
+        return nodes
 
     def ldevice(self, inst):
         """The LDevice with this ``inst``, or ``None``."""
@@ -358,9 +398,18 @@ class DataAttribute:
         """``CSWI1$CO$Pos$Oper$ctlVal`` -- the 61850-8-1 name."""
         return _mms_item(self.logical_node.name, self.fc or "", self.path)
 
-    def reference(self) -> str:
-        """``QPC1PRO/CSWI1.Pos.Oper.ctlVal`` -- the 61850-6 object reference."""
-        return _object_reference(self.logical_node.ldevice.ld_name,
+    def reference(self):
+        """``QPC1PRO/CSWI1.Pos.Oper.ctlVal`` -- the 61850-6 object reference.
+
+        ``None`` when the logical node is not in a logical device, which is
+        the access-point-level case: there is no MMS domain to name it in.
+        :meth:`mms_item` is unaffected -- it names the attribute within its
+        LN and never needed the domain.
+        """
+        ldevice = self.logical_node.ldevice
+        if ldevice is None:
+            return None
+        return _object_reference(ldevice.ld_name,
                                  self.logical_node.name, self.path)
 
     def walk(self):
@@ -395,7 +444,7 @@ class DataObject:
         self.attributes = {}
         self.sub_objects = {}
         self.privates = privates_of(doi_el) if doi_el is not None else {}
-        pool = logical_node.ldevice.ied.document.templates
+        pool = logical_node.ied.document.templates
         spec = pool.do_type(do_type_id)
         if spec is None:
             self.cdc = None
@@ -424,8 +473,13 @@ class DataObject:
                 yield item
 
     @property
-    def reference(self) -> str:
-        return _object_reference(self.logical_node.ldevice.ld_name,
+    def reference(self):
+        """``None`` for an access-point-level LN; see
+        :meth:`DataAttribute.reference`."""
+        ldevice = self.logical_node.ldevice
+        if ldevice is None:
+            return None
+        return _object_reference(ldevice.ld_name,
                                  self.logical_node.name, self.path)
 
     def __repr__(self):

{py61850-0.3.0.dev1 → py61850-0.3.0.dev2}/tests/unit/scl_fixtures.py

@@ -160,9 +160,11 @@ def ldevice(inst, body="", **attrs):
     return f'<LDevice inst="{inst}"{extra}>{body}</LDevice>'
 
 
-def access_point(name="S1", body="", server=True):
+def access_point(name="S1", body="", server=True, lns=""):
+    """An `<AccessPoint>`. `lns` goes BESIDE the Server, not inside it --
+    that is where 61850-6 puts a gateway's proxy LNs."""
     inner = f"<Server>{body}</Server>" if server else body
-    return f'<AccessPoint name="{name}">{inner}</AccessPoint>'
+    return f'<AccessPoint name="{name}">{inner}{lns}</AccessPoint>'
 
 
 def dai(name, val=None, s_addr=None, body=""):

{py61850-0.3.0.dev1 → py61850-0.3.0.dev2}/tests/unit/test_fc.py

@@ -39,6 +39,49 @@ class TestControl(unittest.TestCase):
             self.assertFalse(fc.is_control(other), other)
 
 
+class TestControlDataAttributes(unittest.TestCase):
+    """The control model's own attributes -- the "is this a command?" question
+    asked of a NAME rather than of an FC."""
+
+    def test_the_7_2_control_attributes_are_present(self):
+        self.assertEqual(sorted(fc.CONTROL_DATA_ATTRIBUTES),
+                         ["Cancel", "Oper", "SBO", "SBOw"])
+
+    def test_a_control_root_makes_the_whole_descent_a_command(self):
+        # The FC belongs to the root DA, and so does this: everything under
+        # `Oper` is part of the command, not a reading of the point.
+        self.assertTrue(fc.is_control_attribute("Oper"))
+        self.assertTrue(fc.is_control_attribute("Oper.ctlVal"))
+        self.assertTrue(fc.is_control_attribute("SBOw.ctlNum"))
+        self.assertTrue(fc.is_control_attribute("Cancel.origin.orIdent"))
+
+    def test_both_spellings_of_the_descent(self):
+        # SCL writes an SDI descent with '.', MMS spells every level with '$'.
+        self.assertTrue(fc.is_control_attribute("Oper$ctlVal"))
+        self.assertEqual(fc.is_control_attribute("Oper$ctlVal"),
+                         fc.is_control_attribute("Oper.ctlVal"))
+
+    def test_parts_already_split_are_accepted(self):
+        self.assertTrue(fc.is_control_attribute(("Oper", "ctlVal")))
+
+    def test_a_bare_ctlval_leaf_is_a_command_without_its_root(self):
+        # This is the rule the root test does not cover: a consumer may hold
+        # the leaf alone, and `ctlVal` occurs nowhere but inside a control.
+        self.assertTrue(fc.is_control_attribute("ctlVal"))
+
+    def test_a_status_attribute_is_not_a_command(self):
+        for reading in ("stVal", "general", "phsA", "mag.f", "q", "t",
+                        "setVal", "dirGeneral"):
+            self.assertFalse(fc.is_control_attribute(reading), reading)
+
+    def test_an_empty_path_is_not_a_command(self):
+        # Refusing is the safe answer: an unknown shape must not be promoted
+        # into "this is a command" any more than into "this is a reading".
+        self.assertFalse(fc.is_control_attribute(""))
+        self.assertFalse(fc.is_control_attribute(None))
+        self.assertFalse(fc.is_control_attribute(()))
+
+
 class TestReadRank(unittest.TestCase):
     def test_status_beats_measurement_beats_config(self):
         self.assertLess(fc.read_rank("ST"), fc.read_rank("MX"))

{py61850-0.3.0.dev1 → py61850-0.3.0.dev2}/tests/unit/test_public_api.py

@@ -36,6 +36,7 @@ class TestPublicApi(unittest.TestCase):
         self.assertEqual(sorted(py61850.__all__), sorted([
             "MmsClient", "FileTransfer", "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",
             "LinkError", "GooseError", "SvError", "SclError",

{py61850-0.3.0.dev1 → py61850-0.3.0.dev2}/tests/unit/test_scl_model.py

@@ -126,6 +126,83 @@ class TestIed(_Base):
         self.assertEqual([ld.inst for ld in ied.ldevices()], ["PRO"])
 
 
+class TestAccessPointLogicalNodes(_Base):
+    """LNs declared directly under an `<AccessPoint>`, outside any Server.
+
+    61850-6 allows them, and a gateway uses them: the reference SEL station's
+    RTAC carries an `ITCI` on its `C1` access point holding 58 bound
+    `ExtRef`s. While they were unmodelled, `Ied.ext_refs()` -- documented as
+    "every ExtRef in the IED" -- returned 1,290 of that device's 1,348.
+    """
+
+    def ap_ied(self):
+        return self.doc(
+            fx.templates(fx.lnode_type("T_ITCI", ln_class="ITCI")),
+            fx.ied("GW", body=fx.access_point(
+                "C1",
+                body=fx.ldevice("PRO", body=fx.ln0()),
+                lns=fx.ln("ITCI", inst="1", prefix="I", ln_type="T_ITCI",
+                          body=fx.inputs(fx.ext_ref(
+                              iedName="PUB", srcLDInst="CFG",
+                              srcCBName="GoSB00", intAddr="VB001"))))))
+
+    def test_they_are_reachable_from_the_access_point(self):
+        ap = self.ap_ied().ied("GW").access_points[0]
+        self.assertEqual([n.name for n in ap.logical_nodes], ["IITCI1"])
+        self.assertEqual(ap.logical_nodes[0].ln_class, "ITCI")
+
+    def test_they_are_not_confused_with_the_servers_own_nodes(self):
+        # The Server's LNs stay where they are: an AccessPoint-level LN is a
+        # sibling of <Server>, never a member of it.
+        ap = self.ap_ied().ied("GW").access_points[0]
+        self.assertEqual([n.name for n in ap.server.ldevices[0].logical_nodes],
+                         ["LLN0"])
+
+    def test_the_ieds_logical_nodes_include_them(self):
+        names = [n.name for n in self.ap_ied().ied("GW").logical_nodes()]
+        self.assertEqual(names, ["LLN0", "IITCI1"])
+
+    def test_their_ext_refs_reach_ied_ext_refs(self):
+        # The bug this class exists for: 58 real subscriptions of a gateway
+        # were invisible to a caller asking the IED for its inputs.
+        refs = self.ap_ied().ied("GW").ext_refs()
+        self.assertEqual([r.int_addr for r in refs], ["VB001"])
+        self.assertEqual(refs[0].source_key, ("PUB", "CFG", "GoSB00"))
+
+    def test_they_have_no_logical_device_and_so_no_reference(self):
+        # Not a failure to report a name: an LN outside a Server is in no MMS
+        # domain, so 61850-6 gives it no LDName/LNName to return.
+        node = self.ap_ied().ied("GW").access_points[0].logical_nodes[0]
+        self.assertIsNone(node.ldevice)
+        self.assertIsNone(node.reference)
+
+    def test_they_still_resolve_their_type_through_the_document_pool(self):
+        # The type pool hangs off the DOCUMENT, not off the LDevice, so an
+        # LN with no LDevice resolves like any other.
+        d = self.doc(
+            fx.templates(
+                fx.lnode_type("T_ITCI", ln_class="ITCI",
+                              dos=[("Health", "T_INS")]),
+                fx.do_type("T_INS", cdc="INS",
+                           das=[{"name": "stVal", "fc": "ST",
+                                 "bType": "INT32"}])),
+            fx.ied("GW", body=fx.access_point(
+                "C1", server=False,
+                lns=fx.ln("ITCI", inst="1", ln_type="T_ITCI"))))
+        node = d.ied("GW").access_points[0].logical_nodes[0]
+        attr = node.data_objects["Health"].attributes["stVal"]
+        self.assertEqual(attr.fc, "ST")
+        self.assertEqual(attr.btype, "INT32")
+        # The item name never needed the domain; the object reference does.
+        self.assertEqual(attr.mms_item(), "ITCI1$ST$Health$stVal")
+        self.assertIsNone(attr.reference())
+
+    def test_an_access_point_with_no_lns_reports_none(self):
+        d = self.doc(fx.ied("A", body=fx.access_point(
+            body=fx.ldevice("PRO", body=fx.ln0()))))
+        self.assertEqual(d.ied("A").access_points[0].logical_nodes, [])
+
+
 class TestLDevice(_Base):
     def test_ld_name_defaults_to_ied_name_plus_inst(self):
         d = self.doc(fx.ied("QPC1", body=fx.access_point(

{py61850-0.3.0.dev1 → py61850-0.3.0.dev2}/tests/unit/test_xmlsafe.py

@@ -63,6 +63,24 @@ class TestRejectFile(unittest.TestCase):
     def test_a_clean_file_passes(self):
         _xmlsafe.reject_dtd_in_file(self._write(_CLEAN))
 
+    def test_a_doctype_behind_a_large_comment_is_still_found(self):
+        # The file reader needs its own version of the bytes test above, and
+        # a mutation check is what proved it: turning the file scan into a
+        # fixed 4 kB window left the in-memory test passing, because that one
+        # hands the whole document over at once. Only the streaming reader
+        # can be fooled by a prolog longer than its window.
+        padded = (b'<?xml version="1.0"?>\n<!--' + b'x' * 500_000 + b'-->\n'
+                  + _BILLION_LAUGHS.split(b'\n', 1)[1])
+        with self.assertRaises(_xmlsafe.DtdNotAllowed):
+            _xmlsafe.reject_dtd_in_file(self._write(padded))
+
+    def test_the_scan_stops_at_the_root_and_does_not_read_the_body(self):
+        # It reads the PROLOG, not the document: a 22 MB SCD must not be read
+        # end to end just to check its first line.
+        big = _CLEAN.replace(b"</SCL>", b"<Junk/>" * 200_000 + b"</SCL>")
+        self.assertGreater(len(big), 1_000_000)
+        _xmlsafe.reject_dtd_in_file(self._write(big))   # must not raise
+
 
 class TestErrorTree(unittest.TestCase):
     def test_it_is_both_an_scl_error_and_a_value_error(self):