s7datablock 0.0.0a0__tar.gz

s7datablock-0.0.0a0/.coveragerc

@@ -0,0 +1,28 @@
+# .coveragerc to control coverage.py
+[run]
+branch = True
+source = s7datablock
+# omit = bad_file.py
+
+[paths]
+source =
+    src/
+    */site-packages/
+
+[report]
+# Regexes for lines to exclude from consideration
+exclude_lines =
+    # Have to re-enable the standard pragma
+    pragma: no cover
+
+    # Don't complain about missing debug-only code:
+    def __repr__
+    if self\.debug
+
+    # Don't complain if tests don't hit defensive assertion code:
+    raise AssertionError
+    raise NotImplementedError
+
+    # Don't complain if non-runnable code isn't run:
+    if 0:
+    if __name__ == .__main__.:

s7datablock-0.0.0a0/.github/workflows/ci.yml

@@ -0,0 +1,91 @@
+# GitHub Actions configuration **EXAMPLE**,
+# MODIFY IT ACCORDING TO YOUR NEEDS!
+# Reference: https://docs.github.com/en/actions
+
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - "main"
+    tags: ['v*']  # Keep tag support for releases
+
+permissions:
+  pull-requests: write
+  contents: write
+  id-token: write  # Needed for PyPI publishing
+
+env:
+  UV_CACHE_DIR: /tmp/.uv-cache
+
+jobs:
+  test:
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+        platform: [ubuntu-latest, ]
+        # platform: [ubuntu-latest, macos-latest, windows-latest]  # Uncomment for cross-platform testing
+    runs-on: ${{ matrix.platform }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Restore uv cache
+        uses: actions/cache@v4
+        with:
+          path: ${{ env.UV_CACHE_DIR }}
+          key: uv-${{ runner.os }}-${{ hashFiles('uv.lock') }}
+          restore-keys: |
+            uv-${{ runner.os }}-${{ hashFiles('uv.lock') }}
+            uv-${{ runner.os }}
+
+      - name: Install dependencies
+        run: uv sync --locked --all-extras
+
+      - name: Run linting
+        run: uv run ruff check .
+
+      - name: Run tests with coverage
+        run: uv run pytest --cov s7datablock --cov-report=term-missing
+
+      - name: Minimize uv cache
+        run: uv cache prune --ci
+
+  build-and-publish:
+    needs: test
+    if: startsWith(github.ref, 'refs/tags/')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.11"
+
+      - name: Update version from tag
+        run: |
+          VERSION=${GITHUB_REF#refs/tags/v}
+          echo "Setting version to $VERSION"
+          sed -i 's/^version = ".*"/version = "'$VERSION'"/' pyproject.toml
+
+      - name: Build package
+        run: |
+          uv pip install build
+          uv run python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+          prerelease: ${{ contains(github.ref, 'alpha') || contains(github.ref, 'beta') }}

s7datablock-0.0.0a0/.gitignore

@@ -0,0 +1,54 @@
+# Temporary and binary files
+*~
+*.py[cod]
+*.so
+*.cfg
+!.isort.cfg
+!setup.cfg
+*.orig
+*.log
+*.pot
+__pycache__/*
+.cache/*
+.*.swp
+*/.ipynb_checkpoints/*
+.DS_Store
+
+# Project files
+.ropeproject
+.project
+.pydevproject
+.settings
+.idea
+.vscode
+tags
+
+# Package files
+*.egg
+*.eggs/
+.installed.cfg
+*.egg-info
+
+# Unittest and coverage
+htmlcov/*
+.coverage
+.coverage.*
+.tox
+junit*.xml
+coverage.xml
+.pytest_cache/
+
+# Build and docs folder/files
+build/*
+dist/*
+sdist/*
+docs/api/*
+docs/_rst/*
+docs/_build/*
+cover/*
+MANIFEST
+
+# Per-project virtualenvs
+.venv*/
+.conda*/
+.python-version

s7datablock-0.0.0a0/.isort.cfg

@@ -0,0 +1,3 @@
+[settings]
+profile = black
+known_first_party = s7datablock

s7datablock-0.0.0a0/.pre-commit-config.yaml

@@ -0,0 +1,54 @@
+exclude: |
+  (?x)^(
+      docs/.*|                  # exclude docs folder
+      tests/definitions/.*      # exclude files in the definitions folder
+  )$
+
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: check-added-large-files
+      - id: check-ast
+      - id: check-json
+      - id: check-merge-conflict
+      - id: check-xml
+      - id: check-yaml
+      - id: debug-statements
+      - id: end-of-file-fixer
+      - id: requirements-txt-fixer
+      - id: mixed-line-ending
+        args: ["--fix=auto"] # replace 'auto' with 'lf' to enforce Linux/Mac line endings or 'crlf' for Windows
+
+  # If you want to automatically "modernize" your Python code:
+  - repo: https://github.com/asottile/pyupgrade
+    rev: v3.10.1
+    hooks:
+      - id: pyupgrade
+        args: ["--py311-plus"]
+
+  - repo: https://github.com/PyCQA/isort
+    rev: 5.12.0
+    hooks:
+      - id: isort
+
+  - repo: https://github.com/psf/black
+    rev: 23.7.0
+    hooks:
+      - id: black
+        language_version: python3
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    # Ruff version.
+    rev: v0.0.284
+    hooks:
+      - id: ruff
+        args: [--fix, --exit-non-zero-on-fix]
+
+  # Check for misspells in documentation files:
+  - repo: https://github.com/codespell-project/codespell
+    rev: v2.2.5
+    hooks:
+      - id: codespell
+        args: [-L gud]

s7datablock-0.0.0a0/.readthedocs.yml

@@ -0,0 +1,27 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  configuration: docs/conf.py
+
+# Build documentation with MkDocs
+#mkdocs:
+#  configuration: mkdocs.yml
+
+# Optionally build your docs in additional formats such as PDF
+formats:
+  - pdf
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
+python:
+  install:
+    - requirements: docs/requirements.txt
+    - {path: ., method: pip}

s7datablock-0.0.0a0/AUTHORS.md

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

s7datablock-0.0.0a0/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.

s7datablock-0.0.0a0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,114 @@
+# 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

@@ -0,0 +1,29 @@
+# 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

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

s7datablock-0.0.0a0/docs/authors.md

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

s7datablock-0.0.0a0/docs/changelog.md

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