s7datablock 0.0.1__tar.gz → 0.0.2__tar.gz

{s7datablock-0.0.1 → s7datablock-0.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: s7datablock
-Version: 0.0.1
+Version: 0.0.2
 Summary: A Python library for interacting with Siemens S7 PLC datablocks
 Project-URL: Homepage, https://github.com/CEAD-group/s7datablock
 Project-URL: Documentation, https://github.com/CEAD-group/s7datablock
@@ -45,7 +45,7 @@ Instead of manually mapping byte offsets and types, you can use `.db` definition
 - Clean terminal output using [Rich](https://github.com/Textualize/rich)
 - Easy integration into polling and monitoring loops
 
-![example.png](docs/example.png)
+![example.png](https://github.com/CEAD-group/s7datablock/raw/main/docs/example.png)
 
 ---
 
@@ -92,6 +92,7 @@ df_file_contents = StringIO(
 db = S7DataBlock.from_definition_file(df_file_contents, db_number=1200)
 print(db) # This will print the structure of the data block as a table
 
+print(repr(db))  # Print the raw representation of the data block
 # In a real application, you would create a snap7 client and connect to the PLC
 
 # client = snap7.client.Client()
@@ -103,10 +104,10 @@ with Live(db.to_table(), refresh_per_second=10) as live:
         # db.GET(client)
 
         # For demo, we'll just modify some values
-        db["my_udt.WHEN"] = datetime.now()
-        db["my_udt.PLC_DQ_0"] = not db["my_udt.PLC_DQ_0"]  # Toggle the boolean
-        db["my_udt.Value1"] = db["my_udt.Value1"] + 1  # Increment the integer value
-        db["my_udt.Value2"] = db["my_udt.Value2"] + 0.1  # Increment the real value
+        db["WHEN"] = datetime.now()
+        db["PLC_DQ_0"] = not db["PLC_DQ_0"]  # Toggle the boolean
+        db["Value1"] = db["Value1"] + 1  # Increment the integer value
+        db["Value2"] = db["Value2"] + 0.1  # Increment the real value
 
         # Update the display with current values
         live.update(db.to_table())
@@ -115,26 +116,24 @@ with Live(db.to_table(), refresh_per_second=10) as live:
 
 Running this code should render a live table in your terminal
 ```text
-
-                            Data Block Structure
-┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━┓
-┃ Name                       ┃ Data type   ┃   Offset ┃ Value               ┃
-┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━┩
-│ my_udt                     │ Struct      │          │                     │
-│   my_udt.PLC_DQ_0          │ Bool        │      0.0 │ False               │
-│   my_udt.PLC_DQ_1          │ Bool        │      0.1 │ False               │
-│   my_udt.WHEN              │ DTL         │      2.0 │ 2025-07-14 16:06:06 │
-│     my_udt.WHEN.YEAR       │ UInt        │      2.0 │ 2025                │
-│     my_udt.WHEN.MONTH      │ USInt       │      4.0 │ 7                   │
-│     my_udt.WHEN.DAY        │ USInt       │      5.0 │ 14                  │
-│     my_udt.WHEN.WEEKDAY    │ USInt       │      6.0 │ 1                   │
-│     my_udt.WHEN.HOUR       │ USInt       │      7.0 │ 16                  │
-│     my_udt.WHEN.MINUTE     │ USInt       │      8.0 │ 6                   │
-│     my_udt.WHEN.SECOND     │ USInt       │      9.0 │ 6                   │
-│     my_udt.WHEN.NANOSECOND │ UDInt       │     10.0 │ 195792000           │
-│   my_udt.Value1            │ Int         │     14.0 │ 44                  │
-│   my_udt.Value2            │ Real        │     16.0 │ 4.400               │
-└────────────────────────────┴─────────────┴──────────┴─────────────────────┘
+                        Data Block Structure
+┏━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━┓
+┃ Name              ┃ Data type   ┃   Offset ┃ Value               ┃
+┡━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━┩
+│ PLC_DQ_0          │ Bool        │      0.0 │ True                │
+│ PLC_DQ_1          │ Bool        │      0.1 │ False               │
+│ WHEN              │ DTL         │      2.0 │ 2025-07-14 17:08:40 │
+│   WHEN.YEAR       │ UInt        │      2.0 │ 2025                │
+│   WHEN.MONTH      │ USInt       │      4.0 │ 7                   │
+│   WHEN.DAY        │ USInt       │      5.0 │ 14                  │
+│   WHEN.WEEKDAY    │ USInt       │      6.0 │ 1                   │
+│   WHEN.HOUR       │ USInt       │      7.0 │ 17                  │
+│   WHEN.MINUTE     │ USInt       │      8.0 │ 8                   │
+│   WHEN.SECOND     │ USInt       │      9.0 │ 40                  │
+│   WHEN.NANOSECOND │ UDInt       │     10.0 │ 568441000           │
+│ Value1            │ Int         │     14.0 │ 757                 │
+│ Value2            │ Real        │     16.0 │ 75.699              │
+└───────────────────┴─────────────┴──────────┴─────────────────────┘
 ```
 
 

{s7datablock-0.0.1 → s7datablock-0.0.2}/README.md

@@ -23,7 +23,7 @@ Instead of manually mapping byte offsets and types, you can use `.db` definition
 - Clean terminal output using [Rich](https://github.com/Textualize/rich)
 - Easy integration into polling and monitoring loops
 
-![example.png](docs/example.png)
+![example.png](https://github.com/CEAD-group/s7datablock/raw/main/docs/example.png)
 
 ---
 
@@ -70,6 +70,7 @@ df_file_contents = StringIO(
 db = S7DataBlock.from_definition_file(df_file_contents, db_number=1200)
 print(db) # This will print the structure of the data block as a table
 
+print(repr(db))  # Print the raw representation of the data block
 # In a real application, you would create a snap7 client and connect to the PLC
 
 # client = snap7.client.Client()
@@ -81,10 +82,10 @@ with Live(db.to_table(), refresh_per_second=10) as live:
         # db.GET(client)
 
         # For demo, we'll just modify some values
-        db["my_udt.WHEN"] = datetime.now()
-        db["my_udt.PLC_DQ_0"] = not db["my_udt.PLC_DQ_0"]  # Toggle the boolean
-        db["my_udt.Value1"] = db["my_udt.Value1"] + 1  # Increment the integer value
-        db["my_udt.Value2"] = db["my_udt.Value2"] + 0.1  # Increment the real value
+        db["WHEN"] = datetime.now()
+        db["PLC_DQ_0"] = not db["PLC_DQ_0"]  # Toggle the boolean
+        db["Value1"] = db["Value1"] + 1  # Increment the integer value
+        db["Value2"] = db["Value2"] + 0.1  # Increment the real value
 
         # Update the display with current values
         live.update(db.to_table())
@@ -93,26 +94,24 @@ with Live(db.to_table(), refresh_per_second=10) as live:
 
 Running this code should render a live table in your terminal
 ```text
-
-                            Data Block Structure
-┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━┓
-┃ Name                       ┃ Data type   ┃   Offset ┃ Value               ┃
-┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━┩
-│ my_udt                     │ Struct      │          │                     │
-│   my_udt.PLC_DQ_0          │ Bool        │      0.0 │ False               │
-│   my_udt.PLC_DQ_1          │ Bool        │      0.1 │ False               │
-│   my_udt.WHEN              │ DTL         │      2.0 │ 2025-07-14 16:06:06 │
-│     my_udt.WHEN.YEAR       │ UInt        │      2.0 │ 2025                │
-│     my_udt.WHEN.MONTH      │ USInt       │      4.0 │ 7                   │
-│     my_udt.WHEN.DAY        │ USInt       │      5.0 │ 14                  │
-│     my_udt.WHEN.WEEKDAY    │ USInt       │      6.0 │ 1                   │
-│     my_udt.WHEN.HOUR       │ USInt       │      7.0 │ 16                  │
-│     my_udt.WHEN.MINUTE     │ USInt       │      8.0 │ 6                   │
-│     my_udt.WHEN.SECOND     │ USInt       │      9.0 │ 6                   │
-│     my_udt.WHEN.NANOSECOND │ UDInt       │     10.0 │ 195792000           │
-│   my_udt.Value1            │ Int         │     14.0 │ 44                  │
-│   my_udt.Value2            │ Real        │     16.0 │ 4.400               │
-└────────────────────────────┴─────────────┴──────────┴─────────────────────┘
+                        Data Block Structure
+┏━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━┓
+┃ Name              ┃ Data type   ┃   Offset ┃ Value               ┃
+┡━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━┩
+│ PLC_DQ_0          │ Bool        │      0.0 │ True                │
+│ PLC_DQ_1          │ Bool        │      0.1 │ False               │
+│ WHEN              │ DTL         │      2.0 │ 2025-07-14 17:08:40 │
+│   WHEN.YEAR       │ UInt        │      2.0 │ 2025                │
+│   WHEN.MONTH      │ USInt       │      4.0 │ 7                   │
+│   WHEN.DAY        │ USInt       │      5.0 │ 14                  │
+│   WHEN.WEEKDAY    │ USInt       │      6.0 │ 1                   │
+│   WHEN.HOUR       │ USInt       │      7.0 │ 17                  │
+│   WHEN.MINUTE     │ USInt       │      8.0 │ 8                   │
+│   WHEN.SECOND     │ USInt       │      9.0 │ 40                  │
+│   WHEN.NANOSECOND │ UDInt       │     10.0 │ 568441000           │
+│ Value1            │ Int         │     14.0 │ 757                 │
+│ Value2            │ Real        │     16.0 │ 75.699              │
+└───────────────────┴─────────────┴──────────┴─────────────────────┘
 ```
 
 

{s7datablock-0.0.1 → s7datablock-0.0.2}/examples/live_monitor.py

@@ -6,6 +6,7 @@ from rich.live import Live
 
 from s7datablock.mapping import S7DataBlock
 
+# Example in-line definition file contents. Alternatively, you can pass a PAth to a *.db file.
 df_file_contents = StringIO(
     """
         TYPE "my_udt"
@@ -26,9 +27,12 @@ df_file_contents = StringIO(
     """
 )
 
-db = S7DataBlock.from_definition_file(df_file_contents, db_number=1200, nesting_depth_to_skip=0)
+db = S7DataBlock.from_definition_file(df_file_contents, db_number=1200)
+print(db)  # This will print the structure of the data block as a table
 
+print(repr(db))  # Print the raw representation of the data block
 # In a real application, you would create a snap7 client and connect to the PLC
+
 # client = snap7.client.Client()
 # client.connect('192.168.0.1', 0, 1)
 
@@ -38,10 +42,10 @@ with Live(db.to_table(), refresh_per_second=10) as live:
         # db.GET(client)
 
         # For demo, we'll just modify some values
-        db["my_udt.WHEN"] = datetime.now()
-        db["my_udt.PLC_DQ_0"] = not db["my_udt.PLC_DQ_0"]  # Toggle the boolean
-        db["my_udt.Value1"] = db["my_udt.Value1"] + 1  # Increment the integer value
-        db["my_udt.Value2"] = db["my_udt.Value2"] + 0.1  # Increment the real value
+        db["WHEN"] = datetime.now()
+        db["PLC_DQ_0"] = not db["PLC_DQ_0"]  # Toggle the boolean
+        db["Value1"] = db["Value1"] + 1  # Increment the integer value
+        db["Value2"] = db["Value2"] + 0.1  # Increment the real value
 
         # Update the display with current values
         live.update(db.to_table())

{s7datablock-0.0.1 → s7datablock-0.0.2}/examples/parse_file.py

@@ -22,7 +22,7 @@ END_DATA_BLOCK
 """
 )
 
-db = S7DataBlock.from_definition_file(db_buff, db_number=1200, nesting_depth_to_skip=0)
+db = S7DataBlock.from_definition_file(db_buff, db_number=1200, prefix_levels_to_skip=0)
 
 # Set initial datetime value
 now = datetime(2025, 7, 9, 14, 30, 45, 123456)  # microseconds = 123456

{s7datablock-0.0.1 → s7datablock-0.0.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "s7datablock"
-version = "0.0.1"
+version = "0.0.2"
 description = "A Python library for interacting with Siemens S7 PLC datablocks"
 readme = "README.md"
 authors = [

{s7datablock-0.0.1 → s7datablock-0.0.2}/src/s7datablock/mapping.py

@@ -172,17 +172,18 @@ class S7DataBlock(BufferMapping):
         self.db_size = db_size
 
     @classmethod
-    def from_definition_file(cls, path, db_number: int | None = None, nesting_depth_to_skip: int = 1) -> "S7DataBlock":
+    def from_definition_file(cls, path, db_number: int | None = None, prefix_levels_to_skip: int = 1) -> "S7DataBlock":
         """Create an S7DataBlock from a TIA Portal export file.
 
         Args:
             path: Path to the TIA Portal export file
             db_number: Optional DB number for PLC communication
+            prefix_levels_to_skip: How many prefix levels to skip when generating fieldnames. Default=1 skips the UDT name.
 
         Returns:
             S7DataBlock: The created datablock
         """
-        mapping, size = parse_db_file(path, nesting_depth_to_skip=nesting_depth_to_skip)
+        mapping, size = parse_db_file(path, prefix_levels_to_skip=prefix_levels_to_skip)
         return cls(buffer=bytearray(size), mapping=mapping, db_number=db_number, db_size=size)
 
     def GET(self, client: snap7.client.Client):

{s7datablock-0.0.1 → s7datablock-0.0.2}/src/s7datablock/parser.py

@@ -20,12 +20,12 @@ def resolve_data_types(types: dict[str, Any], prefix: list[str], d: Any) -> Iter
         yield prefix, d
 
 
-def parse_db_file(p: Path | StringIO, nesting_depth_to_skip=1) -> DBParseResult:
+def parse_db_file(p: Path | StringIO, prefix_levels_to_skip=1) -> DBParseResult:
     """Parse a DB file and return a S7Field mapping and total size.
 
     Args:
         p (Path): Path to the DB file
-        nesting_depth_to_skip (int, optional): How many levels in the nested data to skip when generating the fieldnames for nested fields.
+        prefix_levels_to_skip (int, optional): How many prefix levels to skip when generating fieldnames. Default=1 skips the UDT name.
 
     Returns:
         tuple[dict[str, S7Field], int]: The S7Field mapping and total size in bytes
@@ -37,8 +37,8 @@ def parse_db_file(p: Path | StringIO, nesting_depth_to_skip=1) -> DBParseResult:
     else:
         raise TypeError("Input must be a Path or StringIO")
 
-    if nesting_depth_to_skip < 0:
-        raise ValueError("nesting_depth_to_skip must be a non-negative integer")
+    if prefix_levels_to_skip < 0:
+        raise ValueError("prefix_levels_to_skip must be a non-negative integer")
     result = program.parseString(string, parse_all=True).as_dict()
     types = result["TYPES"]
     data = result["DATA_BLOCK"]
@@ -53,7 +53,7 @@ def parse_db_file(p: Path | StringIO, nesting_depth_to_skip=1) -> DBParseResult:
     current_bools: list[str] = []
     prev_base_name = ""
     for i in name_types:
-        name_parts = i.name[nesting_depth_to_skip:]
+        name_parts = i.name[prefix_levels_to_skip:]
         full_name = ".".join(name_parts)
         base_name = ".".join(name_parts[:-1])
         if current_bools and (base_name != prev_base_name or i.type != "Bool"):

{s7datablock-0.0.1 → s7datablock-0.0.2}/tests/test_dtl_struct.py

@@ -26,7 +26,7 @@ BEGIN
 END_DATA_BLOCK
 """
     )
-    return S7DataBlock.from_definition_file(db_buff, db_number=1200, nesting_depth_to_skip=0)
+    return S7DataBlock.from_definition_file(db_buff, db_number=1200, prefix_levels_to_skip=0)
 
 
 def test_db_structure(sample_dtl_db):

{s7datablock-0.0.1 → s7datablock-0.0.2}/tests/test_s7_parsing.py

@@ -129,9 +129,9 @@ def test_parse_db_from_stringio():
     assert "PLC_DQ_0" in result.mapping
 
 
-def test_parse_db_no_nesting_depth_to_skip():
-    """Test parsing with nesting_depth_to_skip=0 to keep full S7Field names."""
-    result = parse_db_file(Path("tests/definitions/s7_1200_out.db"), nesting_depth_to_skip=0)
+def test_parse_db_no_prefix_levels_to_skip():
+    """Test parsing with prefix_levels_to_skip=0 to keep full S7Field names."""
+    result = parse_db_file(Path("tests/definitions/s7_1200_out.db"), prefix_levels_to_skip=0)
 
     assert isinstance(result, DBParseResult)
     assert result.length == 16
@@ -154,9 +154,9 @@ def test_parse_db_no_nesting_depth_to_skip():
     }
 
 
-def test_parse_db_with_nesting_depth_to_skip():
-    """Test parsing with nesting_depth_to_skip=1 to skip top-level UDT name."""
-    result = parse_db_file(Path("tests/definitions/s7_1200_out.db"), nesting_depth_to_skip=1)
+def test_parse_db_with_prefix_levels_to_skip():
+    """Test parsing with prefix_levels_to_skip=1 to skip top-level UDT name."""
+    result = parse_db_file(Path("tests/definitions/s7_1200_out.db"), prefix_levels_to_skip=1)
 
     assert isinstance(result, DBParseResult)
     assert result.length == 16
@@ -182,8 +182,8 @@ def test_parse_db_with_nesting_depth_to_skip():
 def test_parse_db_invalid_input(sample_db_file):
     """Test that invalid inputs raise appropriate exceptions."""
     # Test invalid nesting depth
-    with pytest.raises(ValueError, match="nesting_depth_to_skip must be a non-negative integer"):
-        parse_db_file(sample_db_file, nesting_depth_to_skip=-1)
+    with pytest.raises(ValueError, match="prefix_levels_to_skip must be a non-negative integer"):
+        parse_db_file(sample_db_file, prefix_levels_to_skip=-1)
 
     # Test invalid input type
     with pytest.raises(TypeError, match="Input must be a Path or StringIO"):

{s7datablock-0.0.1 → s7datablock-0.0.2}/uv.lock

@@ -218,7 +218,7 @@ wheels = [
 
 [[package]]
 name = "s7datablock"
-version = "0.0.1"
+version = "0.0.2"
 source = { editable = "." }
 dependencies = [
     { name = "pyparsing" },