s7datablock 0.0.0a0__tar.gz → 0.0.2__tar.gz

s7datablock-0.0.2/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: s7datablock
+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
+Author-email: Thijs Damsma <thijs@damsma.net>
+License: MIT
+License-File: AUTHORS.md
+License-File: LICENSE.txt
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python
+Requires-Python: >=3.11
+Requires-Dist: pyparsing
+Requires-Dist: python-snap7
+Requires-Dist: rich
+Provides-Extra: testing
+Requires-Dist: pytest; extra == 'testing'
+Requires-Dist: pytest-cov; extra == 'testing'
+Requires-Dist: ruff; extra == 'testing'
+Description-Content-Type: text/markdown
+
+# S7DataBlock
+
+- [S7DataBlock](#s7datablock)
+  - [Key Features](#key-features)
+  - [Data Transfer](#data-transfer)
+  - [Live Monitoring PLC Values](#live-monitoring-plc-values)
+  - [Installation](#installation)
+  - [Contributing and Issues](#contributing-and-issues)
+
+**A Python library for parsing Siemens S7 PLC data blocks, in conjunction with Snap7.**
+
+`s7datablock` is a Python utility designed to parse and interpret Siemens S7 PLC data blocks using structured data definitions exported from the TIA Portal. It works seamlessly with the excellent [python-snap7](https://github.com/gijzelaerr/python-snap7) library to enable high-level, dictionary-like access to binary PLC data.
+
+Instead of manually mapping byte offsets and types, you can use `.db` definition files exported from TIA Portal to generate a clean, versionable Python representation of your data block structures.
+
+---
+
+## Key Features
+
+- Uses exported TIA Portal `*.db` files for accurate structure mapping
+- Read and write entire PLC data blocks with `.GET()` and `.SET()` (or the more pythonic `pull()` and `push()`)
+- Structure and sub-structure access via dot notation
+- Clean terminal output using [Rich](https://github.com/Textualize/rich)
+- Easy integration into polling and monitoring loops
+
+![example.png](https://github.com/CEAD-group/s7datablock/raw/main/docs/example.png)
+
+---
+
+## Data Transfer
+
+This library deliberately uses manual .GET() and .SET() calls instead of automatic syncing to prioritize:
+ - **Clarity** – Developers control exactly when data is transferred
+ - **Performance** – Avoid unnecessary communication overhead
+ - **Atomicity** – Batch multiple updates into one write
+
+## Live Monitoring PLC Values
+
+You can monitor PLC values by creating a polling loop. Here's an example using Rich for clean terminal output:
+
+```python
+from time import sleep
+from rich.live import Live
+from datetime import datetime
+from io import StringIO
+
+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"
+        VERSION : 0.1
+        STRUCT
+            PLC_DQ_0 : Bool;
+            PLC_DQ_1 : Bool;
+            WHEN : DTL;
+            Value1 : Int;
+            Value2 : Real;
+        END_STRUCT;
+        END_TYPE
+        DATA_BLOCK "my_udt"
+        VERSION : 0.1
+        "my_udt"
+        BEGIN
+        END_DATA_BLOCK
+    """
+)
+
+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)
+
+with Live(db.to_table(), refresh_per_second=10) as live:
+    while True:
+        # In a real application, you would call GET() here
+        # db.GET(client)
+
+        # For demo, we'll just modify some values
+        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())
+        sleep(0.2)
+```
+
+Running this code should render a live table in your terminal
+```text
+                        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              │
+└───────────────────┴─────────────┴──────────┴─────────────────────┘
+```
+
+
+
+## Installation
+
+```bash
+pip install s7datablock
+```
+
+
+## Contributing and Issues
+
+The library is in its early stages, and contributions are welcome. Feel free to submit a pull request or open an issue on GitHub.

s7datablock-0.0.2/README.md

@@ -0,0 +1,128 @@
+# S7DataBlock
+
+- [S7DataBlock](#s7datablock)
+  - [Key Features](#key-features)
+  - [Data Transfer](#data-transfer)
+  - [Live Monitoring PLC Values](#live-monitoring-plc-values)
+  - [Installation](#installation)
+  - [Contributing and Issues](#contributing-and-issues)
+
+**A Python library for parsing Siemens S7 PLC data blocks, in conjunction with Snap7.**
+
+`s7datablock` is a Python utility designed to parse and interpret Siemens S7 PLC data blocks using structured data definitions exported from the TIA Portal. It works seamlessly with the excellent [python-snap7](https://github.com/gijzelaerr/python-snap7) library to enable high-level, dictionary-like access to binary PLC data.
+
+Instead of manually mapping byte offsets and types, you can use `.db` definition files exported from TIA Portal to generate a clean, versionable Python representation of your data block structures.
+
+---
+
+## Key Features
+
+- Uses exported TIA Portal `*.db` files for accurate structure mapping
+- Read and write entire PLC data blocks with `.GET()` and `.SET()` (or the more pythonic `pull()` and `push()`)
+- Structure and sub-structure access via dot notation
+- Clean terminal output using [Rich](https://github.com/Textualize/rich)
+- Easy integration into polling and monitoring loops
+
+![example.png](https://github.com/CEAD-group/s7datablock/raw/main/docs/example.png)
+
+---
+
+## Data Transfer
+
+This library deliberately uses manual .GET() and .SET() calls instead of automatic syncing to prioritize:
+ - **Clarity** – Developers control exactly when data is transferred
+ - **Performance** – Avoid unnecessary communication overhead
+ - **Atomicity** – Batch multiple updates into one write
+
+## Live Monitoring PLC Values
+
+You can monitor PLC values by creating a polling loop. Here's an example using Rich for clean terminal output:
+
+```python
+from time import sleep
+from rich.live import Live
+from datetime import datetime
+from io import StringIO
+
+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"
+        VERSION : 0.1
+        STRUCT
+            PLC_DQ_0 : Bool;
+            PLC_DQ_1 : Bool;
+            WHEN : DTL;
+            Value1 : Int;
+            Value2 : Real;
+        END_STRUCT;
+        END_TYPE
+        DATA_BLOCK "my_udt"
+        VERSION : 0.1
+        "my_udt"
+        BEGIN
+        END_DATA_BLOCK
+    """
+)
+
+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)
+
+with Live(db.to_table(), refresh_per_second=10) as live:
+    while True:
+        # In a real application, you would call GET() here
+        # db.GET(client)
+
+        # For demo, we'll just modify some values
+        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())
+        sleep(0.2)
+```
+
+Running this code should render a live table in your terminal
+```text
+                        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              │
+└───────────────────┴─────────────┴──────────┴─────────────────────┘
+```
+
+
+
+## Installation
+
+```bash
+pip install s7datablock
+```
+
+
+## Contributing and Issues
+
+The library is in its early stages, and contributions are welcome. Feel free to submit a pull request or open an issue on GitHub.

{s7datablock-0.0.0a0 → s7datablock-0.0.2}/examples/basic_usage.py

@@ -24,10 +24,6 @@ def main():
     buffered_vars["setpointHz2"] = 23.5
     print("Buffer after setting setpointHz2 (hex):", " ".join(f"{b:02X}" for b in buffered_vars.buffer))
 
-    # Display the full structure with values
-    print("\nFull structure:")
-    print(buffered_vars)
-
 
 if __name__ == "__main__":
     main()

s7datablock-0.0.2/examples/live_monitor.py

@@ -0,0 +1,52 @@
+from datetime import datetime
+from io import StringIO
+from time import sleep
+
+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"
+        VERSION : 0.1
+        STRUCT
+            PLC_DQ_0 : Bool;
+            PLC_DQ_1 : Bool;
+            WHEN : DTL;
+            Value1 : Int;
+            Value2 : Real;
+        END_STRUCT;
+        END_TYPE
+        DATA_BLOCK "my_udt"
+        VERSION : 0.1
+        "my_udt"
+        BEGIN
+        END_DATA_BLOCK
+    """
+)
+
+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)
+
+with Live(db.to_table(), refresh_per_second=10) as live:
+    while True:
+        # In a real application, you would call GET() here
+        # db.GET(client)
+
+        # For demo, we'll just modify some values
+        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())
+        sleep(0.2)

{s7datablock-0.0.0a0 → 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.0a0 → s7datablock-0.0.2}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "s7datablock"
-version = "0.0.0-alpha"
-description = "A Python library interacting with Siemens S7 PLC datablocks"
+version = "0.0.2"
+description = "A Python library for interacting with Siemens S7 PLC datablocks"
 readme = "README.md"
 authors = [
     { name = "Thijs Damsma", email = "thijs@damsma.net" }
@@ -36,8 +36,8 @@ line-length = 120
 
 
 [project.urls]
-Homepage = "https://github.com/pyscaffold/pyscaffold/"
-Documentation = "https://pyscaffold.org/"
+Homepage = "https://github.com/CEAD-group/s7datablock"
+Documentation = "https://github.com/CEAD-group/s7datablock"
 
 [project.optional-dependencies]
 testing = [

{s7datablock-0.0.0a0 → s7datablock-0.0.2}/src/s7datablock/mapping.py

@@ -68,6 +68,21 @@ class BufferMapping(MutableMapping[str, ElementalType]):
         Returns a formatted string showing field names, data types, offsets, and current values
         with proper hierarchical indentation.
         """
+        total_size = self.total_size()
+        table = self.to_table()
+
+        console = Console(record=True, width=120)
+        with console.capture() as capture:
+            console.print()  # Empty line before table
+            for _ in range(17):
+                console.print(" ", end="")
+            console.print(table)
+            console.print(f"             Total size: {total_size} bytes")
+            console.print()  # Empty line after
+
+        return capture.get()
+
+    def to_table(self) -> Table:
         table = Table(
             show_edge=True,
             show_header=True,
@@ -112,22 +127,12 @@ class BufferMapping(MutableMapping[str, ElementalType]):
             table.add_row(*field.get_table_row(name=name, indent_level=indent_level, buffer=self.buffer))
             prev_sub = sub
 
-        # Calculate total size
-        total_size = max(
-            field.offset[0] + 2 if isinstance(field.offset, tuple) else field.offset + field.struct_width
-            for field in self.mapping.values()
-        )
+        return table
 
-        console = Console(record=True, width=120)
-        with console.capture() as capture:
-            console.print()  # Empty line before table
-            for _ in range(17):
-                console.print(" ", end="")
-            console.print(table)
-            console.print(f"             Total size: {total_size} bytes")
-            console.print()  # Empty line after
-
-        return capture.get()
+    def total_size(self) -> int:
+        """Calculate the total size of the buffer based on the maximum offset of all fields."""
+        total_size = max(field.offset + field.struct_width for field in self.mapping.values())
+        return total_size
 
     def keys(self):
         """Returns a view of the field names in the mapping."""
@@ -167,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.0a0 → 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.0a0 → 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.0a0 → 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.0a0 → s7datablock-0.0.2}/uv.lock

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

s7datablock-0.0.0a0/PKG-INFO

@@ -1,136 +0,0 @@
-Metadata-Version: 2.4
-Name: s7datablock
-Version: 0.0.0a0
-Summary: A Python library interacting with Siemens S7 PLC datablocks
-Project-URL: Homepage, https://github.com/pyscaffold/pyscaffold/
-Project-URL: Documentation, https://pyscaffold.org/
-Author-email: Thijs Damsma <thijs@damsma.net>
-License: MIT
-License-File: AUTHORS.md
-License-File: LICENSE.txt
-Classifier: Development Status :: 4 - Beta
-Classifier: Programming Language :: Python
-Requires-Python: >=3.11
-Requires-Dist: pyparsing
-Requires-Dist: python-snap7
-Requires-Dist: rich
-Provides-Extra: testing
-Requires-Dist: pytest; extra == 'testing'
-Requires-Dist: pytest-cov; extra == 'testing'
-Requires-Dist: ruff; extra == 'testing'
-Description-Content-Type: text/markdown
-
-# S7DataBlock
-
-- [S7DataBlock](#s7datablock)
-  - [Introduction](#introduction)
-  - [Installation](#installation)
-    - [Parsing Data Blocks](#parsing-data-blocks)
-  - [Contributing and Issues](#contributing-and-issues)
-
-## Introduction
-
-> A Python library for parsing Siemens S7 PLC data blocks, in conjunction with Snap7.
-
-`s7datablock` is a Python library designed to parse and interpret Siemens S7 PLC data blocks. It works in conjunction with the [python-snap7](https://github.com/gijzelaerr/python-snap7) library, providing a set of tools and utilities to read and write the bytes in a PLC datablock as structured data, using the DB definitions as exported from a TIA Portal project. This makes it easier for developers and engineers to work with Siemens S7 PLCs in their Python applications.
-
-Instead of manually mapping bytes, the dataformat defined in Tia Portal can be used to generate the appropriate Python mapping. The configuration file can be kept separate from the code, making it easier to track versions and support complicated data structures.
-
-## Installation
-
-```bash
-pip install s7datablock
-```
-
-### Parsing Data Blocks
-
-In this example, we will demonstrate how to use the `s7datablock` library to parse and interpret Siemens S7 PLC data blocks.
-
-First, we define a s7_1200_out user-defined type (UDT) and a data block in Structured Control Language (SCL). The UDT, named "s7_1200_out_udt", consists of five boolean variables and one integer variable. The data block, named "s7_1200_out", uses this UDT. This file was defined in and exported from Tia Portal, using the `generate source from blocks, including all dependent blocks` option.
-
-```scl
-# s7_1200_out.db
-TYPE "s7_1200_out_udt"
-VERSION : 0.1
-   STRUCT
-      PLC_DQ_0 : Bool;  # Boolean variable
-      PLC_DQ_1 : Bool;  # Boolean variable
-      PLC_DQ_2 : Bool;  # Boolean variable
-      PLC_DQ_3 : Bool;  # Boolean variable
-      PLC_DQ_4 : Bool;  # Boolean variable
-      SB_AQ_0 : Int;    # Integer variable
-   END_STRUCT;
-END_TYPE
-
-DATA_BLOCK "s7_1200_out"
-{ S7_Optimized_Access := 'FALSE' }
-VERSION : 0.1
-NON_RETAIN
-"s7_1200_out_udt"
-
-BEGIN
-
-END_DATA_BLOCK
-```
-
-Next, we use the `S7DataBlock` class from the `s7datablock` library to parse the data block definition file. We then display the parsed data block and its initial buffer state. Finally, we modify one of the boolean variables in the data block and display the updated buffer state.
-
-```python
-# Import necessary modules
-from s7datablock.mapping import S7DataBlock
-from pathlib import Path
-
-# Parse the data block definition file
-db1200 = S7DataBlock.from_definition_file(
-    Path("tests/definitions/s7_1200_out.db"),
-    db_number=1200
-)
-
-# The printing the db1200 datasrutcure produces a nicely formatted output
-print(db1200)
-```
-
-```raw
-                   Data Block Structure
-┏━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━┓
-┃ Name             ┃ Data type   ┃   Offset ┃ Value       ┃
-┡━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━┩
-│ PLC_DQ_0         │ Bool        │      0.0 │ False       │
-│ PLC_DQ_1         │ Bool        │      0.1 │ False       │
-│ PLC_DQ_2         │ Bool        │      0.2 │ False       │
-│ PLC_DQ_3         │ Bool        │      0.3 │ False       │
-│ PLC_DQ_4         │ Bool        │      0.4 │ False       │
-│ SB_AQ_0          │ Int         │      2.0 │ 0           │
-│ TIMEFIELD        │ DTL         │      4.0 │ None        │
-│   YEAR           │ UInt        │      4.0 │ 0           │
-│   MONTH          │ USInt       │      6.0 │ 0           │
-│   DAY            │ USInt       │      7.0 │ 0           │
-│   WEEKDAY        │ USInt       │      8.0 │ 0           │
-│   HOUR           │ USInt       │      9.0 │ 0           │
-│   MINUTE         │ USInt       │     10.0 │ 0           │
-│   SECOND         │ USInt       │     11.0 │ 0           │
-│   NANOSECOND     │ UDInt       │     12.0 │ 0           │
-└──────────────────┴─────────────┴──────────┴─────────────┘
-             Total size: 16 bytes
-```
-
-```python
-# db1200 maps the data like a dictionary but the hood it stores the data in a continuous buffer,
-# using the same format and byte ordering as the PLC
-# Initially the buffer is only zeros
-print(db1200.buffer)
-# Output: bytearray(b'\x00\x00\x00\x00')
-
-# Modify one of the boolean variables
-db1200["PLC_DQ_3"] = True
-
-# Now one bit has changed
-print(db1200.buffer)
-# Output: bytearray(b'\x08\x00\x00\x00')
-```
-
-
-
-## Contributing and Issues
-
-The library is in its early stages, and contributions are welcome. Feel free to submit a pull request or open an issue on GitHub.

s7datablock-0.0.0a0/README.md

@@ -1,114 +0,0 @@
-# S7DataBlock
-
-- [S7DataBlock](#s7datablock)
-  - [Introduction](#introduction)
-  - [Installation](#installation)
-    - [Parsing Data Blocks](#parsing-data-blocks)
-  - [Contributing and Issues](#contributing-and-issues)
-
-## Introduction
-
-> A Python library for parsing Siemens S7 PLC data blocks, in conjunction with Snap7.
-
-`s7datablock` is a Python library designed to parse and interpret Siemens S7 PLC data blocks. It works in conjunction with the [python-snap7](https://github.com/gijzelaerr/python-snap7) library, providing a set of tools and utilities to read and write the bytes in a PLC datablock as structured data, using the DB definitions as exported from a TIA Portal project. This makes it easier for developers and engineers to work with Siemens S7 PLCs in their Python applications.
-
-Instead of manually mapping bytes, the dataformat defined in Tia Portal can be used to generate the appropriate Python mapping. The configuration file can be kept separate from the code, making it easier to track versions and support complicated data structures.
-
-## Installation
-
-```bash
-pip install s7datablock
-```
-
-### Parsing Data Blocks
-
-In this example, we will demonstrate how to use the `s7datablock` library to parse and interpret Siemens S7 PLC data blocks.
-
-First, we define a s7_1200_out user-defined type (UDT) and a data block in Structured Control Language (SCL). The UDT, named "s7_1200_out_udt", consists of five boolean variables and one integer variable. The data block, named "s7_1200_out", uses this UDT. This file was defined in and exported from Tia Portal, using the `generate source from blocks, including all dependent blocks` option.
-
-```scl
-# s7_1200_out.db
-TYPE "s7_1200_out_udt"
-VERSION : 0.1
-   STRUCT
-      PLC_DQ_0 : Bool;  # Boolean variable
-      PLC_DQ_1 : Bool;  # Boolean variable
-      PLC_DQ_2 : Bool;  # Boolean variable
-      PLC_DQ_3 : Bool;  # Boolean variable
-      PLC_DQ_4 : Bool;  # Boolean variable
-      SB_AQ_0 : Int;    # Integer variable
-   END_STRUCT;
-END_TYPE
-
-DATA_BLOCK "s7_1200_out"
-{ S7_Optimized_Access := 'FALSE' }
-VERSION : 0.1
-NON_RETAIN
-"s7_1200_out_udt"
-
-BEGIN
-
-END_DATA_BLOCK
-```
-
-Next, we use the `S7DataBlock` class from the `s7datablock` library to parse the data block definition file. We then display the parsed data block and its initial buffer state. Finally, we modify one of the boolean variables in the data block and display the updated buffer state.
-
-```python
-# Import necessary modules
-from s7datablock.mapping import S7DataBlock
-from pathlib import Path
-
-# Parse the data block definition file
-db1200 = S7DataBlock.from_definition_file(
-    Path("tests/definitions/s7_1200_out.db"),
-    db_number=1200
-)
-
-# The printing the db1200 datasrutcure produces a nicely formatted output
-print(db1200)
-```
-
-```raw
-                   Data Block Structure
-┏━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━┓
-┃ Name             ┃ Data type   ┃   Offset ┃ Value       ┃
-┡━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━┩
-│ PLC_DQ_0         │ Bool        │      0.0 │ False       │
-│ PLC_DQ_1         │ Bool        │      0.1 │ False       │
-│ PLC_DQ_2         │ Bool        │      0.2 │ False       │
-│ PLC_DQ_3         │ Bool        │      0.3 │ False       │
-│ PLC_DQ_4         │ Bool        │      0.4 │ False       │
-│ SB_AQ_0          │ Int         │      2.0 │ 0           │
-│ TIMEFIELD        │ DTL         │      4.0 │ None        │
-│   YEAR           │ UInt        │      4.0 │ 0           │
-│   MONTH          │ USInt       │      6.0 │ 0           │
-│   DAY            │ USInt       │      7.0 │ 0           │
-│   WEEKDAY        │ USInt       │      8.0 │ 0           │
-│   HOUR           │ USInt       │      9.0 │ 0           │
-│   MINUTE         │ USInt       │     10.0 │ 0           │
-│   SECOND         │ USInt       │     11.0 │ 0           │
-│   NANOSECOND     │ UDInt       │     12.0 │ 0           │
-└──────────────────┴─────────────┴──────────┴─────────────┘
-             Total size: 16 bytes
-```
-
-```python
-# db1200 maps the data like a dictionary but the hood it stores the data in a continuous buffer,
-# using the same format and byte ordering as the PLC
-# Initially the buffer is only zeros
-print(db1200.buffer)
-# Output: bytearray(b'\x00\x00\x00\x00')
-
-# Modify one of the boolean variables
-db1200["PLC_DQ_3"] = True
-
-# Now one bit has changed
-print(db1200.buffer)
-# Output: bytearray(b'\x08\x00\x00\x00')
-```
-
-
-
-## Contributing and Issues
-
-The library is in its early stages, and contributions are welcome. Feel free to submit a pull request or open an issue on GitHub.

s7datablock-0.0.0a0/docs/Makefile

@@ -1,29 +0,0 @@
-# Makefile for Sphinx documentation
-#
-
-# You can set these variables from the command line, and also
-# from the environment for the first two.
-SPHINXOPTS    ?=
-SPHINXBUILD   ?= sphinx-build
-SOURCEDIR     = .
-BUILDDIR      = _build
-AUTODOCDIR    = api
-
-# User-friendly check for sphinx-build
-ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $?), 1)
-$(error "The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from https://sphinx-doc.org/")
-endif
-
-.PHONY: help clean Makefile
-
-# Put it first so that "make" without argument is like "make help".
-help:
-	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
-
-clean:
-	rm -rf $(BUILDDIR)/* $(AUTODOCDIR)
-
-# Catch-all target: route all unknown targets to Sphinx using the new
-# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
-%: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

s7datablock-0.0.0a0/docs/_static/.gitignore

@@ -1 +0,0 @@
-# Empty directory

s7datablock-0.0.0a0/docs/authors.md

@@ -1,4 +0,0 @@
-```{include} ../AUTHORS.md
-:relative-docs: docs/
-:relative-images:
-```

s7datablock-0.0.0a0/docs/changelog.md

@@ -1,4 +0,0 @@
-```{include} ../CHANGELOG.md
-:relative-docs: docs/
-:relative-images:
-```

s7datablock-0.0.0a0/docs/conf.py

@@ -1,299 +0,0 @@
-# This file is execfile()d with the current directory set to its containing dir.
-#
-# This file only contains a selection of the most common options. For a full
-# list see the documentation:
-# https://www.sphinx-doc.org/en/master/usage/configuration.html
-#
-# All configuration values have a default; values that are commented out
-# serve to show the default.
-
-import os
-import sys
-import shutil
-
-# -- Path setup --------------------------------------------------------------
-
-__location__ = os.path.dirname(__file__)
-
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-sys.path.insert(0, os.path.join(__location__, "../src"))
-
-# -- Run sphinx-apidoc -------------------------------------------------------
-# This hack is necessary since RTD does not issue `sphinx-apidoc` before running
-# `sphinx-build -b html . _build/html`. See Issue:
-# https://github.com/readthedocs/readthedocs.org/issues/1139
-# DON'T FORGET: Check the box "Install your project inside a virtualenv using
-# setup.py install" in the RTD Advanced Settings.
-# Additionally it helps us to avoid running apidoc manually
-
-try:  # for Sphinx >= 1.7
-    from sphinx.ext import apidoc
-except ImportError:
-    from sphinx import apidoc
-
-output_dir = os.path.join(__location__, "api")
-module_dir = os.path.join(__location__, "../src/s7datablock")
-try:
-    shutil.rmtree(output_dir)
-except FileNotFoundError:
-    pass
-
-try:
-    import sphinx
-
-    cmd_line = f"sphinx-apidoc --implicit-namespaces -f -o {output_dir} {module_dir}"
-
-    args = cmd_line.split(" ")
-    if tuple(sphinx.__version__.split(".")) >= ("1", "7"):
-        # This is a rudimentary parse_version to avoid external dependencies
-        args = args[1:]
-
-    apidoc.main(args)
-except Exception as e:
-    print("Running `sphinx-apidoc` failed!\n{}".format(e))
-
-# -- General configuration ---------------------------------------------------
-
-# If your documentation needs a minimal Sphinx version, state it here.
-# needs_sphinx = '1.0'
-
-# Add any Sphinx extension module names here, as strings. They can be extensions
-# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = [
-    "sphinx.ext.autodoc",
-    "sphinx.ext.intersphinx",
-    "sphinx.ext.todo",
-    "sphinx.ext.autosummary",
-    "sphinx.ext.viewcode",
-    "sphinx.ext.coverage",
-    "sphinx.ext.doctest",
-    "sphinx.ext.ifconfig",
-    "sphinx.ext.mathjax",
-    "sphinx.ext.napoleon",
-]
-
-# Add any paths that contain templates here, relative to this directory.
-templates_path = ["_templates"]
-
-
-# Enable markdown
-extensions.append("myst_parser")
-
-# Configure MyST-Parser
-myst_enable_extensions = [
-    "amsmath",
-    "colon_fence",
-    "deflist",
-    "dollarmath",
-    "html_image",
-    "linkify",
-    "replacements",
-    "smartquotes",
-    "substitution",
-    "tasklist",
-]
-
-# The suffix of source filenames.
-source_suffix = [".rst", ".md"]
-
-# The encoding of source files.
-# source_encoding = 'utf-8-sig'
-
-# The master toctree document.
-master_doc = "index"
-
-# General information about the project.
-project = "s7datablock"
-copyright = "2023, Thijs Damsma"
-
-# The version info for the project you're documenting, acts as replacement for
-# |version| and |release|, also used in various other places throughout the
-# built documents.
-#
-# version: The short X.Y version.
-# release: The full version, including alpha/beta/rc tags.
-# If you don’t need the separation provided between version and release,
-# just set them both to the same value.
-try:
-    from s7datablock import __version__ as version
-except ImportError:
-    version = ""
-
-if not version or version.lower() == "unknown":
-    version = os.getenv("READTHEDOCS_VERSION", "unknown")  # automatically set by RTD
-
-release = version
-
-# The language for content autogenerated by Sphinx. Refer to documentation
-# for a list of supported languages.
-# language = None
-
-# There are two options for replacing |today|: either, you set today to some
-# non-false value, then it is used:
-# today = ''
-# Else, today_fmt is used as the format for a strftime call.
-# today_fmt = '%B %d, %Y'
-
-# List of patterns, relative to source directory, that match files and
-# directories to ignore when looking for source files.
-exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", ".venv"]
-
-# The reST default role (used for this markup: `text`) to use for all documents.
-# default_role = None
-
-# If true, '()' will be appended to :func: etc. cross-reference text.
-# add_function_parentheses = True
-
-# If true, the current module name will be prepended to all description
-# unit titles (such as .. function::).
-# add_module_names = True
-
-# If true, sectionauthor and moduleauthor directives will be shown in the
-# output. They are ignored by default.
-# show_authors = False
-
-# The name of the Pygments (syntax highlighting) style to use.
-pygments_style = "sphinx"
-
-# A list of ignored prefixes for module index sorting.
-# modindex_common_prefix = []
-
-# If true, keep warnings as "system message" paragraphs in the built documents.
-# keep_warnings = False
-
-# If this is True, todo emits a warning for each TODO entries. The default is False.
-todo_emit_warnings = True
-
-
-# -- Options for HTML output -------------------------------------------------
-
-# The theme to use for HTML and HTML Help pages.  See the documentation for
-# a list of builtin themes.
-html_theme = "alabaster"
-
-# Theme options are theme-specific and customize the look and feel of a theme
-# further.  For a list of options available for each theme, see the
-# documentation.
-html_theme_options = {"sidebar_width": "300px", "page_width": "1200px"}
-
-# Add any paths that contain custom themes here, relative to this directory.
-# html_theme_path = []
-
-# The name for this set of Sphinx documents.  If None, it defaults to
-# "<project> v<release> documentation".
-# html_title = None
-
-# A shorter title for the navigation bar.  Default is the same as html_title.
-# html_short_title = None
-
-# The name of an image file (relative to this directory) to place at the top
-# of the sidebar.
-# html_logo = ""
-
-# The name of an image file (within the static path) to use as favicon of the
-# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
-# pixels large.
-# html_favicon = None
-
-# Add any paths that contain custom static files (such as style sheets) here,
-# relative to this directory. They are copied after the builtin static files,
-# so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ["_static"]
-
-# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
-# using the given strftime format.
-# html_last_updated_fmt = '%b %d, %Y'
-
-# If true, SmartyPants will be used to convert quotes and dashes to
-# typographically correct entities.
-# html_use_smartypants = True
-
-# Custom sidebar templates, maps document names to template names.
-# html_sidebars = {}
-
-# Additional templates that should be rendered to pages, maps page names to
-# template names.
-# html_additional_pages = {}
-
-# If false, no module index is generated.
-# html_domain_indices = True
-
-# If false, no index is generated.
-# html_use_index = True
-
-# If true, the index is split into individual pages for each letter.
-# html_split_index = False
-
-# If true, links to the reST sources are added to the pages.
-# html_show_sourcelink = True
-
-# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
-# html_show_sphinx = True
-
-# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
-# html_show_copyright = True
-
-# If true, an OpenSearch description file will be output, and all pages will
-# contain a <link> tag referring to it.  The value of this option must be the
-# base URL from which the finished HTML is served.
-# html_use_opensearch = ''
-
-# This is the file name suffix for HTML files (e.g. ".xhtml").
-# html_file_suffix = None
-
-# Output file base name for HTML help builder.
-htmlhelp_basename = "s7datablock-doc"
-
-
-# -- Options for LaTeX output ------------------------------------------------
-
-latex_elements = {
-    # The paper size ("letterpaper" or "a4paper").
-    # "papersize": "letterpaper",
-    # The font size ("10pt", "11pt" or "12pt").
-    # "pointsize": "10pt",
-    # Additional stuff for the LaTeX preamble.
-    # "preamble": "",
-}
-
-# Grouping the document tree into LaTeX files. List of tuples
-# (source start file, target name, title, author, documentclass [howto/manual]).
-latex_documents = [("index", "user_guide.tex", "s7datablock Documentation", "Thijs Damsma", "manual")]
-
-# The name of an image file (relative to this directory) to place at the top of
-# the title page.
-# latex_logo = ""
-
-# For "manual" documents, if this is true, then toplevel headings are parts,
-# not chapters.
-# latex_use_parts = False
-
-# If true, show page references after internal links.
-# latex_show_pagerefs = False
-
-# If true, show URL addresses after external links.
-# latex_show_urls = False
-
-# Documents to append as an appendix to all manuals.
-# latex_appendices = []
-
-# If false, no module index is generated.
-# latex_domain_indices = True
-
-# -- External mapping --------------------------------------------------------
-python_version = ".".join(map(str, sys.version_info[0:2]))
-intersphinx_mapping = {
-    "sphinx": ("https://www.sphinx-doc.org/en/master", None),
-    "python": ("https://docs.python.org/" + python_version, None),
-    "matplotlib": ("https://matplotlib.org", None),
-    "numpy": ("https://numpy.org/doc/stable", None),
-    "sklearn": ("https://scikit-learn.org/stable", None),
-    "pandas": ("https://pandas.pydata.org/pandas-docs/stable", None),
-    "scipy": ("https://docs.scipy.org/doc/scipy/reference", None),
-    "setuptools": ("https://setuptools.pypa.io/en/stable/", None),
-    "pyscaffold": ("https://pyscaffold.org/en/stable", None),
-}
-
-print(f"loading configurations for {project} {version} ...", file=sys.stderr)

s7datablock-0.0.0a0/docs/contributing.md

@@ -1,4 +0,0 @@
-```{include} ../CONTRIBUTING.md
-:relative-docs: docs/
-:relative-images:
-```

s7datablock-0.0.0a0/docs/index.md

@@ -1,39 +0,0 @@
-# s7datablock
-
-Add a short description here!
-
-
-## Note
-
-> This is the main page of your project's [Sphinx] documentation. It is
-> formatted in [Markdown]. Add additional pages by creating md-files in
-> `docs` or rst-files (formatted in [reStructuredText]) and adding links to
-> them in the `Contents` section below.
->
-> Please check [Sphinx] and [MyST] for more information
-> about how to document your project and how to configure your preferences.
-
-
-## Contents
-
-```{toctree}
-:maxdepth: 2
-
-Overview <readme>
-Contributions & Help <contributing>
-License <license>
-Authors <authors>
-Changelog <changelog>
-Module Reference <api/modules>
-```
-
-## Indices and tables
-
-* {ref}`genindex`
-* {ref}`modindex`
-* {ref}`search`
-
-[Sphinx]: http://www.sphinx-doc.org/
-[Markdown]: https://daringfireball.net/projects/markdown/
-[reStructuredText]: http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
-[MyST]: https://myst-parser.readthedocs.io/en/latest/

s7datablock-0.0.0a0/docs/license.md

@@ -1,5 +0,0 @@
-# License
-
-```{literalinclude} ../LICENSE.txt
-:language: text
-```

s7datablock-0.0.0a0/docs/readme.md

@@ -1,4 +0,0 @@
-```{include} ../README.md
-:relative-docs: docs/
-:relative-images:
-```

s7datablock-0.0.0a0/docs/requirements.txt

@@ -1,6 +0,0 @@
-# Requirements file for ReadTheDocs, check .readthedocs.yml.
-# To build the module reference correctly, make sure every external package
-# under `install_requires` in `setup.cfg` is also listed here!
-# sphinx_rtd_theme
-myst-parser[linkify]
-sphinx>=3.2.1