s7datablock 0.0.0a0__py3-none-any.whl

s7datablock/__init__.py

@@ -0,0 +1,23 @@
+import sys
+
+if sys.version_info[:2] >= (3, 8):
+    # TODO: Import directly (no need for conditional) when `python_requires = >= 3.8`
+    from importlib.metadata import PackageNotFoundError, version  # pragma: no cover
+else:
+    from importlib_metadata import PackageNotFoundError, version  # pragma: no cover
+
+try:
+    # Change here if project is renamed and does not equal the package name
+    dist_name = "s7datablock"
+    __version__ = version(dist_name)
+except PackageNotFoundError:  # pragma: no cover
+    __version__ = "unknown"
+finally:
+    del version, PackageNotFoundError
+
+# Export public API
+from s7datablock.fields import S7Field
+from s7datablock.mapping import BufferMapping, S7DataBlock
+from s7datablock.parser import parse_db_file
+
+__all__ = ["S7Field", "BufferMapping", "S7DataBlock", "parse_db_file"]

s7datablock/constants.py

@@ -0,0 +1,93 @@
+"""Constants and type definitions for S7 PLC data types."""
+from datetime import datetime, time, timedelta
+from typing import Final, Literal, TypeAlias, Union
+
+# S7 Type Literals
+S7ElementaryType = Literal[
+    "Bool",
+    "Byte",
+    "Word",
+    "DWord",
+    "SInt",
+    "USInt",
+    "Int",
+    "UInt",
+    "DInt",
+    "UDInt",
+    "LInt",
+    "ULInt",
+    "Real",
+    "LReal",
+    "Char",
+    "WChar",
+]
+
+S7DateTimeType = Literal[
+    "S5Time",
+    "Time",
+    "LTime",
+    "Date",
+    "Time_of_Day",
+    "DATE_AND_TIME",
+    "LDT",
+    "DTL",
+    "LTIME_OF_DAY",
+]
+
+S7CompositeType = Literal["Struct"]
+S7Type = Union[S7ElementaryType, S7DateTimeType, S7CompositeType]
+
+# Type Aliases for values
+S7ElementaryValue: TypeAlias = Union[bool, int, float, str]
+S7DateTimeValue: TypeAlias = Union[datetime, time, timedelta, None]  # None for invalid/unset dates
+S7Value: TypeAlias = Union[S7ElementaryValue, S7DateTimeValue]
+
+
+# Sets of types
+S7_ELEMENTARY_TYPES: Final = frozenset(
+    [
+        "Bool",
+        "Byte",
+        "Word",
+        "DWord",
+        "SInt",
+        "USInt",
+        "Int",
+        "UInt",
+        "DInt",
+        "UDInt",
+        "LInt",
+        "ULInt",
+        "Real",
+        "LReal",
+        "Char",
+        "WChar",
+    ]
+)
+
+S7_DATETIME_TYPES: Final = frozenset(
+    ["S5Time", "Time", "LTime", "Date", "Time_of_Day", "DATE_AND_TIME", "LDT", "DTL", "LTIME_OF_DAY"]
+)
+
+S7_COMPOSITE_TYPES: Final = frozenset(["Struct"])
+S7_ALL_TYPES: Final = S7_ELEMENTARY_TYPES | S7_DATETIME_TYPES | S7_COMPOSITE_TYPES
+
+# Struct format mapping
+S7_TYPE_TO_STRUCT_FORMAT: Final = {
+    "Bool": "H",  # 1 byte, but packed as part of a word
+    "Byte": "B",  # 8-bit unsigned
+    "USInt": "B",  # 8-bit unsigned
+    "Char": "c",  # 1 character, 1 byte
+    "SInt": "b",  # 8-bit signed
+    "UInt": "H",  # 16-bit unsigned
+    "Word": "H",  # 16-bit unsigned
+    "Int": "h",  # 16-bit signed
+    "DInt": "i",  # 32-bit signed
+    "UDInt": "I",  # 32-bit unsigned
+    "DWord": "I",  # 32-bit unsigned
+    "Real": "f",  # 32-bit IEEE 754 float
+    "LReal": "d",  # 64-bit IEEE 754 float
+    "Time": "I",  # 32-bit unsigned (milliseconds)
+    "Date": "H",  # 16-bit unsigned (days since 1990-01-01)
+    "Time_of_Day": "I",  # 32-bit unsigned (ms since midnight)
+}

s7datablock/fields.py

@@ -0,0 +1,341 @@
+"""S7Field definitions for S7 PLC data types."""
+from __future__ import annotations
+
+import struct
+from abc import ABC
+from datetime import datetime, timedelta
+from typing import Any, Generic, NamedTuple, TypeVar, cast
+
+from rich.style import Style
+from rich.text import Text
+
+from s7datablock.constants import S7Type, S7Value
+
+T = TypeVar("T", bound=S7Value)
+
+
+class NameType(NamedTuple):
+    """Type for storing S7Field name and type information."""
+
+    name: list[str]
+    type: S7Type
+
+
+class SubField(NamedTuple):
+    """Represents a subfield in a structure."""
+
+    name: str
+    s7_type: S7Type
+    relative_offset: int
+
+
+class FormattedTableRow(NamedTuple):
+    """Represents a formatted row in a table with rich text support."""
+
+    name: str
+    type: Text
+    offset: str
+    value: Text
+
+
+class S7Field(ABC, Generic[T]):
+    """Base class for all S7 PLC fields"""
+
+    _registry: dict[str, type[S7Field]] = {}
+
+    buffer_slice: slice
+    offset: int  # Can be a byte offset or (byte, bit) tuple for bit-addressed fields
+    offset_bit: int = 0  # Bit offset for bit-addressed fields
+    s7_type: S7Type
+    struct_fmt: str
+    struct_width: int  # Width of the struct in bytes, used for packing/unpacking
+
+    def __init_subclass__(cls, *, s7_type: S7Type | None = None, subfield_config: list[SubField] | None = None) -> None:
+        super().__init_subclass__()
+        if s7_type is not None:
+            S7Field._registry[s7_type] = cls
+            cls.s7_type = s7_type
+        cls.subfield_config = subfield_config or []
+
+    def __init__(self, offset: int, offset_bit: int = 0):
+        self.offset = offset
+        self.offset_bit = offset_bit
+        self.struct_width = struct.calcsize(self.struct_fmt)
+        self.buffer_slice = slice(offset, offset + self.struct_width)
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, S7Field):
+            return NotImplemented
+        # Compare core attributes that define S7Field equality
+        if not (self.s7_type == other.s7_type and self.offset == other.offset):
+            return False
+        # For boolean fields, also compare bit position
+        if isinstance(self.offset, tuple) and isinstance(other.offset, tuple):
+            return self.offset[1] == other.offset[1]
+        return True
+
+    def __repr__(self) -> str:
+        offset_str = f"({self.offset[0]}, {self.offset[1]})" if isinstance(self.offset, tuple) else str(self.offset)
+        return f"{self.__class__.__name__}(offset={offset_str}, s7_type='{self.s7_type}')"
+
+    def unpack(self, buffer: bytearray) -> T:
+        """Unpack value from buffer."""
+        return cast(T, struct.unpack(self.struct_fmt, buffer[self.buffer_slice])[0])
+
+    def pack(self, buffer: bytearray, value: T) -> None:
+        """Pack value into buffer."""
+        buffer[self.buffer_slice] = struct.pack(self.struct_fmt, value)
+
+    def format_value(self, value: T) -> str:
+        """Format a value for display based on its type."""
+        if isinstance(value, bool):
+            return str(value)
+        elif isinstance(value, float):
+            return f"{value:.3f}"
+        elif isinstance(value, datetime):
+            return value.strftime("%Y-%m-%d %H:%M:%S")
+        return str(value)
+
+    def get_table_row(self, name: str, buffer: bytearray, indent_level: int = 0) -> FormattedTableRow:
+        """Get a formatted row for the rich text table."""
+        display_name = "  " * indent_level + name
+        type_style = Style(
+            color={
+                # Elementary types (blue family)
+                "SInt": "#4169E1",  # Royal blue
+                "Int": "#324AB2",  # Medium royal blue
+                "DInt": "#1E4BB8",  # Deep royal blue
+                # Unsigned integers (turquoise family)
+                "USInt": "#20B2AA",  # Light turquoise
+                "UInt": "#17887F",  # Medium turquoise
+                "UDInt": "#0F5E54",  # Deep turquoise
+                # Floating point (purple family)
+                "Real": "#B87FD9",  # Light purple
+                "LReal": "#9B4FC3",  # Deep purple
+                # Word types (cyan family)
+                "Byte": "#69C5CE",  # Light cyan
+                "Word": "#4AACB5",  # Medium cyan
+                "DWord": "#2B939C",  # Deep cyan
+                # Character types (warm gray family)
+                "Char": "#D4C5BC",  # Light warm gray
+                "String": "#B5A69C",  # Medium warm gray
+                "WChar": "#96877C",  # Deep warm gray
+                # Special types with distinct colors
+                "Bool": "#FFD700",  # Gold for booleans
+                "DTL": "#FF8C42",  # Bright orange for date/time
+                "Struct": "#F0F0F0",  # Soft white for structures
+            }.get(self.s7_type, "#FFFFFF")
+        )
+
+        return FormattedTableRow(
+            name=display_name,
+            type=Text(self.s7_type, style=type_style),
+            offset=f"{self.offset}.{self.offset_bit}",
+            value=Text(self.format_value(self.unpack(buffer)), style=type_style),
+        )
+
+    @property
+    def subfields(self) -> dict[str, S7Field[S7Value]]:
+        """Get all the component fields of the structure."""
+        assert isinstance(self.offset, int), "Offset must be an integer for subfields"
+        return {
+            name: S7Field.create(self.offset + rel_offset, s7_type)
+            for name, s7_type, rel_offset in self.subfield_config
+        }
+
+    @staticmethod
+    def create(offset: int, s7_type: str, offset_bit: int = 0) -> S7Field[S7Value]:
+        """Create a new S7Field instance of the appropriate type."""
+        field_class = S7Field._registry.get(s7_type)
+        if field_class is None:
+            raise ValueError(f"Unknown S7 type: {s7_type}")
+        return field_class(offset, offset_bit)
+
+    def __str__(self) -> str:
+        return repr(self)
+
+
+class S7Bool(S7Field[bool], s7_type="Bool"):
+    """Boolean S7Field type."""
+
+    struct_fmt = "?"
+
+    def pack(self, buffer: bytearray, value: bool) -> None:
+        byte = buffer[self.offset]
+        if value:
+            byte |= 1 << self.offset_bit
+        else:
+            byte &= ~(1 << self.offset_bit)
+        buffer[self.offset] = byte
+
+    def unpack(self, buffer: bytearray) -> bool:
+        return bool(buffer[self.offset] & (1 << self.offset_bit))
+
+
+class S7Real(S7Field[float], s7_type="Real"):
+    """32-bit floating point S7Field."""
+
+    struct_fmt = ">f"
+
+
+class S7Byte(S7Field[int], s7_type="Byte"):
+    """8-bit unsigned integer S7Field."""
+
+    struct_fmt = "B"
+
+
+class S7Word(S7Field[int], s7_type="Word"):
+    """16-bit unsigned integer S7Field."""
+
+    struct_fmt = ">H"
+
+
+class S7DWord(S7Field[int], s7_type="DWord"):
+    """32-bit unsigned integer S7Field."""
+
+    struct_fmt = ">I"
+
+
+class S7DInt(S7Field[int], s7_type="DInt"):
+    """32-bit signed integer S7Field."""
+
+    struct_fmt = ">i"
+
+
+class S7UInt(S7Field[int], s7_type="UInt"):
+    """16-bit unsigned integer S7Field."""
+
+    struct_fmt = ">H"
+
+
+class S7UDInt(S7Field[int], s7_type="UDInt"):
+    """32-bit unsigned integer S7Field."""
+
+    struct_fmt = ">I"
+
+
+class S7USInt(S7Field[int], s7_type="USInt"):
+    """8-bit unsigned integer S7Field."""
+
+    struct_fmt = "B"
+
+
+class S7Char(S7Field[str], s7_type="Char"):
+    """Single character S7Field."""
+
+    struct_fmt = "c"
+
+    def pack(self, buffer: bytearray, value: str) -> None:
+        buffer[self.buffer_slice] = value.encode("ascii")
+
+    def unpack(self, buffer: bytearray) -> str:
+        return buffer[self.buffer_slice].decode("ascii")
+
+
+# Date and time types
+class S7DTL(
+    S7Field[datetime | None],
+    s7_type="DTL",
+    subfield_config=[
+        SubField("YEAR", "UInt", 0),
+        SubField("MONTH", "USInt", 2),
+        SubField("DAY", "USInt", 3),
+        SubField("WEEKDAY", "USInt", 4),
+        SubField("HOUR", "USInt", 5),
+        SubField("MINUTE", "USInt", 6),
+        SubField("SECOND", "USInt", 7),
+        SubField("NANOSECOND", "UDInt", 8),
+    ],
+):
+    """DTL (Date and Time Long) S7Field type."""
+
+    struct_fmt = ">HBBBBBBI"  # Year(2), Month(1), Day(1), Weekday(1), Hour(1), Minute(1), Second(1), Nanosecond(4)
+
+    def unpack(self, buffer: bytearray) -> datetime | None:
+        try:
+            year, month, day, _, hour, minute, second, ns = struct.unpack(self.struct_fmt, buffer[self.buffer_slice])
+            return datetime(
+                year=year, month=month, day=day, hour=hour, minute=minute, second=second, microsecond=ns // 1000
+            )
+        except (ValueError, struct.error):
+            return None
+
+    def pack(self, buffer: bytearray, value: datetime | None) -> None:
+        if value is None:
+            buffer[self.buffer_slice] = bytes(12)
+            return
+        buffer[self.buffer_slice] = struct.pack(
+            self.struct_fmt,
+            value.year,
+            value.month,
+            value.day,
+            value.isoweekday() % 7,  # 0=Sunday
+            value.hour,
+            value.minute,
+            value.second,
+            value.microsecond * 1000,
+        )
+
+
+class S7Time(S7Field[timedelta], s7_type="Time"):
+    """Time duration S7Field type."""
+
+    struct_fmt = "I"
+
+    def unpack(self, buffer: bytearray) -> timedelta:
+        ms = struct.unpack(self.struct_fmt, buffer[self.buffer_slice])[0]
+        return timedelta(milliseconds=ms)
+
+    def pack(self, buffer: bytearray, value: timedelta) -> None:
+        ms = int(value.total_seconds() * 1000)
+        buffer[self.buffer_slice] = struct.pack(self.struct_fmt, ms)
+
+
+class S7Date(S7Field[datetime | None], s7_type="Date"):
+    """Date S7Field type."""
+
+    struct_fmt = ">H"
+
+    def unpack(self, buffer: bytearray) -> datetime | None:
+        try:
+            (days,) = struct.unpack(self.struct_fmt, buffer[self.buffer_slice])
+            return datetime(1990, 1, 1) + timedelta(days=days)
+        except (ValueError, struct.error):
+            return None
+
+    def pack(self, buffer: bytearray, value: datetime | None) -> None:
+        if value is None:
+            buffer[self.buffer_slice] = bytes(2)
+            return
+        days = (value - datetime(1990, 1, 1)).days
+        buffer[self.buffer_slice] = struct.pack(self.struct_fmt, days)
+
+
+class S7TimeOfDay(S7Field[timedelta], s7_type="Time_of_Day"):
+    """Time of day S7Field type."""
+
+    struct_fmt = ">I"
+
+    def unpack(self, buffer: bytearray) -> timedelta:
+        """Unpack Time of Day value from buffer to timedelta"""
+        ms_since_midnight = struct.unpack(self.struct_fmt, buffer[self.buffer_slice])[0]
+        return timedelta(milliseconds=ms_since_midnight)
+
+    def pack(self, buffer: bytearray, value: timedelta) -> None:
+        """Pack a timedelta value into the buffer."""
+        ms = int(value.total_seconds() * 1000)
+        buffer[self.buffer_slice] = struct.pack(self.struct_fmt, ms)
+
+
+class DBParseResult(NamedTuple):
+    """Result type for DB parsing operations"""
+
+    mapping: dict[str, S7Field[Any]]
+    length: int
+
+
+# Signed integer types
+class S7Int(S7Field[int], s7_type="Int"):
+    """16-bit signed integer S7Field."""
+
+    struct_fmt = "h"

s7datablock/grammar.py

@@ -0,0 +1,112 @@
+"""Grammar definitions for parsing TIA Portal DB exports."""
+from functools import reduce
+from operator import or_
+
+from pyparsing import CaselessKeyword, Combine, Dict, Forward, Group, OneOrMore
+from pyparsing import Opt as Optional  # workaround for mypy bug
+from pyparsing import Regex, Suppress, Word, ZeroOrMore, alphanums, alphas, nums
+
+from s7datablock.constants import S7_ALL_TYPES
+
+# Basic tokens
+QUOTE = Suppress(Word("'\""))
+UNQUOTED_IDENT = Word(f"{alphas}_", f"{alphanums}_")
+QUOTED_IDENT = QUOTE + Word(f"{alphanums}_. ") + QUOTE
+IDENT = QUOTED_IDENT | UNQUOTED_IDENT
+REAL = Regex(r"\d+\.\d*")
+INT = Regex(r"\d+")
+LBRACE, RBRACE, SEMI, COLON = map(Suppress, "{};:")
+EQUALS = Suppress(":=")
+BOOLEAN = CaselessKeyword("True") | CaselessKeyword("False")
+COMMENT = Suppress("//" + Regex(r".*"))
+POINT = Suppress(".")
+hex_prefix = Combine(Word(nums) + "#")
+hex_digits = Word(nums + "ABCDEFabcdef")
+HEX = Combine(hex_prefix + hex_digits)
+VALUE = BOOLEAN | HEX | REAL | INT
+
+# S7 specific grammar
+S7_DTYPE = reduce(or_, map(CaselessKeyword, S7_ALL_TYPES))
+DURATION = Regex(r"T#\d+[sMHmsdh]")
+
+# Attribute assignments and values
+optional_attribute_assignments = Suppress(
+    Optional(
+        LBRACE + ZeroOrMore(IDENT + EQUALS + QUOTE + (BOOLEAN | S7_DTYPE | REAL) + QUOTE + Optional(SEMI)) + RBRACE
+    )
+)
+
+date = IDENT + optional_attribute_assignments
+value_assignment = EQUALS + (REAL | BOOLEAN | INT | DURATION)
+optional_default_value = Suppress(Optional(expr=value_assignment, default=None))
+
+# Structure definitions
+struct_def = Forward()
+
+struct_element = Dict(
+    Group(
+        Optional(date)
+        + Optional(IDENT)
+        + optional_attribute_assignments
+        + COLON
+        + Optional((S7_DTYPE + optional_default_value + SEMI) | (QUOTED_IDENT + SEMI) | struct_def)
+    )
+    + Optional(COMMENT)
+)
+
+struct_def <<= (
+    Suppress(CaselessKeyword("STRUCT"))
+    + Optional(COMMENT)
+    + Group(OneOrMore(struct_element))
+    + Suppress(CaselessKeyword("END_STRUCT"))
+    + SEMI
+)
+
+# Type and variable definitions
+type_def = Dict(
+    Group(
+        Suppress("TYPE")
+        + IDENT
+        + Suppress("VERSION")
+        + COLON
+        + Suppress(REAL("version"))
+        + struct_def
+        + Suppress("END_TYPE")
+    )
+)
+
+var_def = Dict(
+    Group(
+        Suppress(CaselessKeyword("VAR"))
+        + ZeroOrMore(struct_element)
+        + Group(OneOrMore(struct_element))
+        + Suppress("END_VAR")
+    )
+)
+
+# Default values and data block definitions
+default_value_element = Group(ZeroOrMore(IDENT + POINT) + IDENT + Suppress(EQUALS) + VALUE + Suppress(SEMI)) + Group(
+    ZeroOrMore(Suppress(EQUALS) + VALUE + Suppress(SEMI))
+)
+
+defaults_values_block = Dict(
+    Group(Suppress(CaselessKeyword("BEGIN")) + ZeroOrMore(default_value_element) + Suppress("END_DATA_BLOCK"))
+)("BEGIN")
+
+data_block_def = Dict(
+    Group(
+        Suppress("DATA_BLOCK")
+        + QUOTE
+        + IDENT
+        + QUOTE
+        + optional_attribute_assignments
+        + Suppress("VERSION")
+        + COLON
+        + Suppress(REAL)
+        + Suppress(Optional(CaselessKeyword("NON_RETAIN")))
+        + (var_def | struct_def | QUOTED_IDENT)
+    )
+)("DATA_BLOCK")
+
+# Complete program grammar
+program = Group(ZeroOrMore(type_def))("TYPES") + data_block_def + defaults_values_block

s7datablock/mapping.py

@@ -0,0 +1,207 @@
+from collections.abc import ItemsView, MutableMapping, ValuesView
+from datetime import datetime
+
+import snap7
+from rich.console import Console
+from rich.style import Style
+from rich.table import Table
+from rich.text import Text
+
+from s7datablock.fields import S7Field, S7Value
+from s7datablock.parser import parse_db_file
+
+ElementalType = float | int | bool | datetime
+
+
+class BufferMapping(MutableMapping[str, ElementalType]):
+    """A mapping that allows for easy access to a buffer of bytes.
+
+    The buffer is Siemens S7 compatible (for unoptimised DB's), including the bit packing
+    where multiple bools are packed into a single byte.
+
+    Args:
+        buffer: A bytearray containing the raw data.
+        mapping: A dict mapping names to either:
+            - Field or S7Field objects (recommended)
+
+    """
+
+    def __init__(self, buffer: bytearray, mapping: dict[str, S7Field[S7Value]]) -> None:
+        self.buffer = buffer
+        self.mapping = mapping
+
+    def __getitem__(self, name: str):
+        # Check if this is a DTL subfield access (e.g. "datetime.SECOND")
+        if name in self.mapping:
+            field: S7Field = self.mapping[name]
+            return field.unpack(self.buffer)
+        raise KeyError(f"'{name}' not found")
+
+    def __setitem__(self, name: str, value) -> None:
+        if name in self.mapping:
+            field: S7Field = self.mapping[name]
+            return field.pack(self.buffer, value)
+        raise KeyError(f"'{name}' not found")
+
+    def __delitem__(self, name: str) -> None:
+        """Delete an item from the mapping.
+
+        Not supported as the buffer has a fixed size and structure.
+        """
+        raise NotImplementedError("Cannot delete items from a fixed buffer mapping")
+
+    def __len__(self) -> int:
+        """Return the number of fields in the mapping."""
+        return len(self.mapping)
+
+    def __iter__(self):
+        """Return an iterator over the field names."""
+        return iter(self.mapping)
+
+    def __repr__(self) -> str:
+        # return the unpacked values instead of the mapping S7Field
+        return {k: self[k] for k in self.mapping.keys()}.__repr__()
+
+    def __str__(self) -> str:
+        """Generate a rich table representation of the data block structure.
+
+        Returns a formatted string showing field names, data types, offsets, and current values
+        with proper hierarchical indentation.
+        """
+        table = Table(
+            show_edge=True,
+            show_header=True,
+            show_lines=False,
+            padding=(0, 1),
+            title="\nData Block Structure",
+            width=None,
+        )
+
+        table.add_column("Name", justify="left", min_width=16, style=Style(color="bright_cyan", bold=True))
+        table.add_column("Data type", justify="left", min_width=11)
+        table.add_column("Offset", justify="right", min_width=8)
+        table.add_column("Value", justify="left", min_width=11)
+
+        prev_bases = []
+        prev_sub = ""
+        for name, field in self.mapping.items():
+            (*bases, sub) = name.split(".")  # Split on the last dot to get the parent name
+            indent_level = len(name.split(".")) - 1
+            if bases != prev_bases:
+                # Add an empty row for the new base
+                n = 0
+                while n < len(bases) and n < len(prev_bases):
+                    if bases[n] != prev_bases[n]:
+                        break
+                    n += 1
+                if bases and bases[-1] == prev_sub:
+                    # If the last base is the same as the previous sub, we don't need to add a new row
+                    n += 1
+
+                for m in range(n, len(bases)):
+                    # Add a new base row
+                    table.add_row(
+                        "  " * m + bases[m],  # Indent based on the hierarchy level
+                        Text("Struct", Style(color="bright_white", bold=True)),
+                        "",
+                        "",
+                    )
+                prev_bases = bases
+
+            # Add a row to the table
+            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()
+        )
+
+        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 keys(self):
+        """Returns a view of the field names in the mapping."""
+        return self.mapping.keys()
+
+    def values(self):
+        """Returns a view of the current values in the mapping."""
+        return ValuesView(self)
+
+    def items(self):
+        """Returns a view of (name, value) pairs for all fields in the mapping."""
+        return ItemsView(self)
+
+    def to_dict(self) -> dict[str, ElementalType]:
+        """Convert the mapping to a regular dictionary.
+
+        Returns:
+            A dictionary containing all field names and their current values
+        """
+        return dict(self.items())
+
+
+class S7DataBlock(BufferMapping):
+    buffer: bytearray
+    db_number: int | None
+    db_size: int
+
+    def __init__(
+        self,
+        buffer: bytearray,
+        mapping: dict[str, S7Field],
+        db_number: int | None,
+        db_size: int,
+    ):
+        super().__init__(buffer, mapping)
+        self.db_number = db_number
+        self.db_size = db_size
+
+    @classmethod
+    def from_definition_file(cls, path, db_number: int | None = None, nesting_depth_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
+
+        Returns:
+            S7DataBlock: The created datablock
+        """
+        mapping, size = parse_db_file(path, nesting_depth_to_skip=nesting_depth_to_skip)
+        return cls(buffer=bytearray(size), mapping=mapping, db_number=db_number, db_size=size)
+
+    def GET(self, client: snap7.client.Client):
+        """Read all values from PLC.
+
+        Args:
+            client: snap7.client.Client instance
+        """
+        if self.db_number is None:
+            raise ValueError("No DB number specified")
+
+        self.buffer = client.db_read(self.db_number, 0, self.db_size)
+
+    def SET(self, client: snap7.client.Client):
+        """Write all values to PLC.
+
+        Args:
+            client: snap7.client.Client instance
+        """
+        if self.db_number is None:
+            raise ValueError("No DB number specified")
+
+        client.db_write(self.db_number, 0, self.buffer)
+
+    # Alias methods for backward compatibility
+    pull = GET
+    push = SET

s7datablock/parser.py

@@ -0,0 +1,83 @@
+"""Functions to parse DB definitions exported from TIA Portal."""
+import math
+from collections.abc import Iterator
+from copy import deepcopy
+from io import StringIO
+from pathlib import Path
+from typing import Any
+
+from s7datablock.fields import DBParseResult, NameType, S7Field
+from s7datablock.grammar import program
+
+
+def resolve_data_types(types: dict[str, Any], prefix: list[str], d: Any) -> Iterator[tuple[list[str], Any]]:
+    if isinstance(d, dict):
+        for k, v in d.items():
+            yield from resolve_data_types(types, prefix + [k], v)
+    elif d in types:
+        yield from resolve_data_types(types, prefix, deepcopy(types[d]))
+    else:
+        yield prefix, d
+
+
+def parse_db_file(p: Path | StringIO, nesting_depth_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.
+
+    Returns:
+        tuple[dict[str, S7Field], int]: The S7Field mapping and total size in bytes
+    """
+    if isinstance(p, Path):
+        string = p.read_text(encoding="utf-8-sig")
+    elif isinstance(p, StringIO):
+        string = p.read()
+    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")
+    result = program.parseString(string, parse_all=True).as_dict()
+    types = result["TYPES"]
+    data = result["DATA_BLOCK"]
+    result["BEGIN"]  # default values could be handled here
+
+    # Get the flattened list of fields and types
+    name_types = [NameType(name=k, type=v) for k, v in list(resolve_data_types(types, [], data))]
+
+    # Process fields into S7Field mapping
+    mapping = {}
+    offset = 0
+    current_bools: list[str] = []
+    prev_base_name = ""
+    for i in name_types:
+        name_parts = i.name[nesting_depth_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"):
+            offset += flush_bools(current_bools, offset, mapping)
+            current_bools = []
+        prev_base_name = base_name
+        if i.type == "Bool":
+            current_bools.append(full_name)
+            continue
+
+        field = S7Field.create(offset, i.type)
+        mapping[full_name] = field
+        for k, v in field.subfields.items():
+            mapping[f"{full_name}.{k}"] = v
+        offset += field.struct_width
+
+    if current_bools:
+        offset += flush_bools(current_bools, offset, mapping)
+
+    return DBParseResult(mapping=mapping, length=offset)
+
+
+def flush_bools(current_bools: list[str], offset: int, mapping: dict[str, S7Field]) -> int:
+    """Pack boolean fields into byte-aligned memory and update the mapping."""
+    for i, name in enumerate(current_bools):
+        mapping[name] = S7Field.create(offset + (i // 8), "Bool", offset_bit=i % 8)
+    return 2 * math.ceil(len(current_bools) / 16)

s7datablock-0.0.0a0.dist-info/METADATA

@@ -0,0 +1,136 @@
+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.dist-info/RECORD

@@ -0,0 +1,12 @@
+s7datablock/__init__.py,sha256=W9jDPLmxl-FMN6OXjWjR8D7Yxho4x5QCtZUrKypXgyM,818
+s7datablock/constants.py,sha256=BPvINBVkIZlyg5epw_t6HrVMc7jEVxgHJpjuwWM7dkE,2267
+s7datablock/fields.py,sha256=ZhppVdLlJxNU2t72deXSNwKulLGFP8ilE9eSp4dNRKo,11084
+s7datablock/grammar.py,sha256=fI3k2zyftTdNAsShvzUcRAp_91CZQyhPTRUIlU53_yo,3286
+s7datablock/mapping.py,sha256=VoZdTK4zbU7Xo4nAs-xkhuuuYIsfhyXYi0w3Ib8q5OE,7130
+s7datablock/parser.py,sha256=Lk2vddIg_Et37swLvOEG9vTE1tKpCdkBSc52VW_3vWw,3095
+s7datablock/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+s7datablock-0.0.0a0.dist-info/METADATA,sha256=Zlj-nE5BUIzd2dbM69TZcymBGzL-FLwutdtK6sHnALM,5825
+s7datablock-0.0.0a0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+s7datablock-0.0.0a0.dist-info/licenses/AUTHORS.md,sha256=J6wEVz7P0KscmxwBFWWgzZFNJrEan2u1Rb9jmR6YTF8,75
+s7datablock-0.0.0a0.dist-info/licenses/LICENSE.txt,sha256=CAKsax5K78p1TWRfIDTfNvdhfCU9dkqYzm0hVpxfhf4,1061
+s7datablock-0.0.0a0.dist-info/RECORD,,

s7datablock-0.0.0a0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

s7datablock-0.0.0a0.dist-info/licenses/AUTHORS.md

@@ -0,0 +1,3 @@
+# Contributors
+
+* Thijs Damsma [thijs@damsma.net](mailto:thijs@damsma.net)

s7datablock-0.0.0a0.dist-info/licenses/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 CEAD
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.