Extract LIDs from browse() for symbolic access

Complete the symbolic access loop: browse() now captures the LID (from
the object RID in EXPLORE responses) and symbol_crc for each variable.
These can be fed into Tag objects for optimized-block access.

New:
- snap7.tags.from_browse(variables) — converts browse() results to
  dict[str, Tag], producing symbolic Tags when LIDs are present
- _parse_explore_fields now captures "lid" and "symbol_crc" keys

Workflow for optimized DBs:

    variables = client.browse()
    tags = from_browse(variables)
    value = client.read_tag(tags["Motor.Speed"])  # symbolic access

Still experimental — the CRC handling in particular needs real PLC
validation. If browse doesn't provide a CRC, the Tag uses CRC=0
(skip check) which the PLC may or may not accept depending on config.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: gijzelaerr

s7/__init__.py

@@ -20,7 +20,7 @@
 
 from snap7.type import Area, Block, WordLen, SrvEvent, SrvArea
 from snap7.util.db import Row, DB
-from snap7.tags import Tag, load_csv, load_json, load_tia_xml
+from snap7.tags import Tag, load_csv, load_json, load_tia_xml, from_browse
 
 __all__ = [
     "Client",
@@ -40,4 +40,5 @@
     "load_csv",
     "load_json",
     "load_tia_xml",
+    "from_browse",
 ]

s7/_s7commplus_client.py

@@ -868,15 +868,19 @@ def _parse_explore_fields(response: bytes, db_number: int, db_name: str) -> list
     """Parse an EXPLORE response for a single DB to extract field layout.
 
     Returns:
-        List of dicts: ``{"name": str, "db_number": int, "db_name": str,
-        "byte_offset": int, "data_type": str}``
+        List of dicts with keys:
+        ``name``, ``db_number``, ``byte_offset``, ``data_type``, ``lid``,
+        ``symbol_crc``. ``lid`` and ``symbol_crc`` enable symbolic access
+        for optimized DBs.
     """
     from .vlq import decode_uint32_vlq as _vlq32
 
     fields: list[dict[str, Any]] = []
     offset = 0
     field_name = ""
     byte_offset = 0
+    field_lid = 0
+    field_crc = 0
 
     # Skip return code VLQ at start of response
     if offset < len(response):
@@ -890,6 +894,8 @@ def _parse_explore_fields(response: bytes, db_number: int, db_name: str) -> list
         if tag == 0xA1:  # START_OF_OBJECT
             if offset + 4 > len(response):
                 break
+            # The RID bytes serve as the LID for symbolic access
+            field_lid = struct.unpack(">I", response[offset : offset + 4])[0]
             offset += 4
             for _ in range(3):
                 if offset >= len(response):
@@ -898,6 +904,7 @@ def _parse_explore_fields(response: bytes, db_number: int, db_name: str) -> list
                 offset += consumed
             field_name = ""
             byte_offset = 0
+            field_crc = 0
 
         elif tag == 0xA2:  # TERMINATING_OBJECT
             if field_name:
@@ -907,6 +914,8 @@ def _parse_explore_fields(response: bytes, db_number: int, db_name: str) -> list
                         "db_number": db_number,
                         "byte_offset": byte_offset,
                         "data_type": "BYTE",  # default; refined by type info
+                        "lid": field_lid,
+                        "symbol_crc": field_crc,
                     }
                 )
 

snap7/__init__.py

@@ -21,7 +21,7 @@
 from .partner import Partner
 from .logo import Logo
 from .util.db import Row, DB
-from .tags import Tag, load_csv, load_json, load_tia_xml
+from .tags import Tag, load_csv, load_json, load_tia_xml, from_browse
 from .type import Area, Block, WordLen, SrvEvent, SrvArea
 
 __all__ = [
@@ -36,6 +36,7 @@
     "load_csv",
     "load_json",
     "load_tia_xml",
+    "from_browse",
     "Area",
     "Block",
     "WordLen",

snap7/tags.py

@@ -34,7 +34,7 @@
 import re
 from dataclasses import dataclass, field
 from pathlib import Path
-from typing import Union
+from typing import Any, Union
 
 from .type import Area
 
@@ -403,6 +403,42 @@ def load_json(source: Union[str, Path]) -> dict[str, Tag]:
     return tags
 
 
+def from_browse(variables: list[dict[str, Any]]) -> dict[str, Tag]:
+    """Build a dict of Tags from :meth:`s7.Client.browse` results.
+
+    .. warning:: This function is **experimental** and may change.
+
+    When the browse result includes an ``lid`` key, the resulting Tag
+    is configured for symbolic (LID-based) access suitable for
+    optimized DBs. Otherwise it uses byte-offset access.
+
+    Args:
+        variables: List of variable-info dicts from ``client.browse()``.
+
+    Returns:
+        Dictionary mapping variable names to :class:`Tag` objects.
+    """
+    tags: dict[str, Tag] = {}
+    for var in variables:
+        name = var.get("name", "")
+        if not name:
+            continue
+        lid = var.get("lid", 0)
+        crc = var.get("symbol_crc", 0)
+        access_sequence = [lid] if lid else []
+        tags[name] = Tag(
+            area=Area.DB,
+            db_number=int(var.get("db_number", 0)),
+            byte_offset=int(var.get("byte_offset", 0)),
+            datatype=str(var.get("data_type", "BYTE")),
+            count=int(var.get("count", 1)),
+            name=name,
+            access_sequence=access_sequence,
+            symbol_crc=int(crc),
+        )
+    return tags
+
+
 def load_tia_xml(source: Union[str, Path]) -> dict[str, Tag]:
     """Load tags from a TIA Portal DB source XML export.
 

tests/test_tags.py

@@ -5,7 +5,7 @@
 
 import pytest
 
-from snap7.tags import Tag, load_csv, load_json, load_tia_xml
+from snap7.tags import Tag, from_browse, load_csv, load_json, load_tia_xml
 from snap7.type import Area
 
 
@@ -197,6 +197,37 @@ def test_from_file(self, tmp_path: Path) -> None:
         assert "Tank.Level" in tags
 
 
+class TestFromBrowse:
+    """from_browse converts browse results to Tag dicts."""
+
+    def test_classic_browse_result(self) -> None:
+        variables = [
+            {"name": "Motor.Speed", "db_number": 1, "byte_offset": 0, "data_type": "REAL"},
+            {"name": "Motor.Running", "db_number": 1, "byte_offset": 4, "data_type": "BOOL"},
+        ]
+        tags = from_browse(variables)
+        assert "Motor.Speed" in tags
+        assert tags["Motor.Speed"].byte_offset == 0
+        assert tags["Motor.Speed"].datatype == "REAL"
+        assert tags["Motor.Speed"].is_symbolic is False
+
+    def test_symbolic_browse_result(self) -> None:
+        """When browse includes LID, produce symbolic Tags."""
+        variables = [
+            {"name": "Motor.Speed", "db_number": 1, "byte_offset": 0,
+             "data_type": "REAL", "lid": 0xA, "symbol_crc": 0x12345678},
+        ]
+        tags = from_browse(variables)
+        assert tags["Motor.Speed"].is_symbolic is True
+        assert tags["Motor.Speed"].access_sequence == [0xA]
+        assert tags["Motor.Speed"].symbol_crc == 0x12345678
+
+    def test_skips_unnamed(self) -> None:
+        variables = [{"name": "", "db_number": 1, "byte_offset": 0, "data_type": "BYTE"}]
+        tags = from_browse(variables)
+        assert len(tags) == 0
+
+
 class TestSymbolicAccess:
     """Tag.from_access_string and symbolic access fields."""