pyads-agile 0.1.0__tar.gz

pyads_agile-0.1.0/ACKNOWLEDGMENTS.md

@@ -0,0 +1,12 @@
+# Acknowledgments
+
+`pyads-agile` is based on the upstream `pyads` project created by Stefan Lehmann.
+
+- Upstream project: https://github.com/stlehmann/pyads
+- Original author: Stefan Lehmann
+- License: MIT
+
+This repository is maintained by Agile Automation Technologies GmbH.
+
+We thank Stefan Lehmann and all upstream contributors for creating and maintaining
+the foundation this distribution builds upon.

pyads_agile-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright © 2015 by Stefan Lehmann
+
+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.

pyads_agile-0.1.0/MANIFEST.in

@@ -0,0 +1,10 @@
+#
+# Recipe for extra files to pack for setuptools.
+# MANIFEST.in is a little outdated but the best solution to differentiate files between sdist and wheel builds.
+#
+
+graft adslib
+include ACKNOWLEDGMENTS.md
+global-exclude *.a *.o *.obj *.bin *.so
+prune obj
+prune tests

pyads_agile-0.1.0/PKG-INFO

@@ -0,0 +1,156 @@
+Metadata-Version: 2.4
+Name: pyads-agile
+Version: 0.1.0
+Summary: Agile-maintained Python wrapper for the TwinCAT ADS library, based on pyads
+Author: Agile Automation Technologies GmbH
+Maintainer: Agile Automation Technologies GmbH
+License-Expression: MIT
+Project-URL: Upstream, https://github.com/stlehmann/pyads
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Requires-Python: <4,>=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: setuptools>=82.0.0
+Provides-Extra: docs
+Requires-Dist: sphinx; extra == "docs"
+Requires-Dist: sphinx_rtd_theme; extra == "docs"
+Requires-Dist: recommonmark; extra == "docs"
+Provides-Extra: tests
+Requires-Dist: pytest; extra == "tests"
+Requires-Dist: pytest-cov; extra == "tests"
+Requires-Dist: tox; extra == "tests"
+Provides-Extra: dev
+Requires-Dist: build; extra == "dev"
+Requires-Dist: flake8; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: coverage; extra == "dev"
+Requires-Dist: coveralls; extra == "dev"
+Dynamic: license-file
+
+pyads-agile
+===========
+
+`pyads-agile` is a Python wrapper for the Beckhoff TwinCAT ADS library.
+
+This distribution is maintained by Agile Automation Technologies GmbH and is
+based on the excellent upstream `pyads` project created by Stefan Lehmann:
+https://github.com/stlehmann/pyads
+
+`pyads-agile` intentionally stays drop-in compatible with `pyads`. The public API,
+module name (`import pyads`), and supported interpreter/OS matrix mirror upstream,
+so existing applications can switch distributions without code changes.
+
+## Attribution
+
+- Original project: `pyads` by Stefan Lehmann
+- License: MIT
+- This repository keeps upstream credit and license notices as required
+
+See [ACKNOWLEDGMENTS.md](ACKNOWLEDGMENTS.md) for details.
+
+## Installation
+
+Install the distribution:
+
+```bash
+pip install pyads-agile
+```
+
+Import stays compatible:
+
+```python
+import pyads
+```
+
+## Versioning
+
+`pyads-agile` uses its own independent Semantic Versioning (`MAJOR.MINOR.PATCH`).
+It does not mirror upstream `pyads` version numbers.
+
+## Scope
+
+This package provides Python APIs for communicating with TwinCAT devices using:
+
+- `TcAdsDll.dll` on Windows
+- `adslib.so` on Linux
+
+## Agile-specific enhancements
+
+Beyond compatibility, this fork currently focuses on improved RPC ergonomics:
+
+- **Convenient RPC object proxies.** `Connection.get_object()` exposes TwinCAT
+  function blocks as Python objects and lets you configure return and parameter
+  types per method:
+
+  TwinCAT requirement: each callable method must be annotated in PLC code with
+  `{attribute 'TcRpcEnable'}` directly above the method declaration.
+
+  ```python
+  rpc = plc.get_object(
+      "GVL.fbTestRemoteMethodCall",
+      method_return_types={"m_iSimpleCall": pyads.PLCTYPE_INT},
+  )
+  result = rpc.m_iSimpleCall()
+  ```
+
+- **Multi-parameter RPC calls with native syntax.** Configure method signatures
+  once and then call methods like normal Python methods:
+
+  ```python
+  rpc = plc.get_object(
+      "GVL.fbTestRemoteMethodCall",
+      method_return_types={"m_iSum": pyads.PLCTYPE_INT},
+      method_parameters={"m_iSum": [pyads.PLCTYPE_INT, pyads.PLCTYPE_INT]},
+  )
+  result = rpc.m_iSum(5, 5)
+  ```
+
+  You can still use low-level direct calls when needed:
+
+  ```python
+  result = plc.call_rpc_method(
+      "GVL.fbTestRemoteMethodCall#m_iSimpleCall",
+      return_type=pyads.PLCTYPE_INT,
+      write_value=42,
+      write_type=pyads.PLCTYPE_INT,
+  )
+  ```
+
+## Features
+
+- connect to remote TwinCAT devices
+- create routes on Linux and on remote PLCs
+- support for TwinCAT 2 and TwinCAT 3
+- read and write values by name or by address
+- read and write DUTs (structures)
+- notification callbacks
+
+## Basic usage
+
+```python
+import pyads
+
+plc = pyads.Connection("127.0.0.1.1.1", pyads.PORT_TC3PLC1)
+plc.open()
+i = plc.read_by_name("GVL.int_val")
+plc.write_by_name("GVL.int_val", i)
+plc.close()
+```
+
+## Contribution Policy
+
+This repository is maintained on a best-effort basis for internal and product
+needs.
+
+At this time, we do not accept unsolicited pull requests, and we may not be
+able to respond to feature requests or general support issues.

pyads_agile-0.1.0/README.md

@@ -0,0 +1,117 @@
+pyads-agile
+===========
+
+`pyads-agile` is a Python wrapper for the Beckhoff TwinCAT ADS library.
+
+This distribution is maintained by Agile Automation Technologies GmbH and is
+based on the excellent upstream `pyads` project created by Stefan Lehmann:
+https://github.com/stlehmann/pyads
+
+`pyads-agile` intentionally stays drop-in compatible with `pyads`. The public API,
+module name (`import pyads`), and supported interpreter/OS matrix mirror upstream,
+so existing applications can switch distributions without code changes.
+
+## Attribution
+
+- Original project: `pyads` by Stefan Lehmann
+- License: MIT
+- This repository keeps upstream credit and license notices as required
+
+See [ACKNOWLEDGMENTS.md](ACKNOWLEDGMENTS.md) for details.
+
+## Installation
+
+Install the distribution:
+
+```bash
+pip install pyads-agile
+```
+
+Import stays compatible:
+
+```python
+import pyads
+```
+
+## Versioning
+
+`pyads-agile` uses its own independent Semantic Versioning (`MAJOR.MINOR.PATCH`).
+It does not mirror upstream `pyads` version numbers.
+
+## Scope
+
+This package provides Python APIs for communicating with TwinCAT devices using:
+
+- `TcAdsDll.dll` on Windows
+- `adslib.so` on Linux
+
+## Agile-specific enhancements
+
+Beyond compatibility, this fork currently focuses on improved RPC ergonomics:
+
+- **Convenient RPC object proxies.** `Connection.get_object()` exposes TwinCAT
+  function blocks as Python objects and lets you configure return and parameter
+  types per method:
+
+  TwinCAT requirement: each callable method must be annotated in PLC code with
+  `{attribute 'TcRpcEnable'}` directly above the method declaration.
+
+  ```python
+  rpc = plc.get_object(
+      "GVL.fbTestRemoteMethodCall",
+      method_return_types={"m_iSimpleCall": pyads.PLCTYPE_INT},
+  )
+  result = rpc.m_iSimpleCall()
+  ```
+
+- **Multi-parameter RPC calls with native syntax.** Configure method signatures
+  once and then call methods like normal Python methods:
+
+  ```python
+  rpc = plc.get_object(
+      "GVL.fbTestRemoteMethodCall",
+      method_return_types={"m_iSum": pyads.PLCTYPE_INT},
+      method_parameters={"m_iSum": [pyads.PLCTYPE_INT, pyads.PLCTYPE_INT]},
+  )
+  result = rpc.m_iSum(5, 5)
+  ```
+
+  You can still use low-level direct calls when needed:
+
+  ```python
+  result = plc.call_rpc_method(
+      "GVL.fbTestRemoteMethodCall#m_iSimpleCall",
+      return_type=pyads.PLCTYPE_INT,
+      write_value=42,
+      write_type=pyads.PLCTYPE_INT,
+  )
+  ```
+
+## Features
+
+- connect to remote TwinCAT devices
+- create routes on Linux and on remote PLCs
+- support for TwinCAT 2 and TwinCAT 3
+- read and write values by name or by address
+- read and write DUTs (structures)
+- notification callbacks
+
+## Basic usage
+
+```python
+import pyads
+
+plc = pyads.Connection("127.0.0.1.1.1", pyads.PORT_TC3PLC1)
+plc.open()
+i = plc.read_by_name("GVL.int_val")
+plc.write_by_name("GVL.int_val", i)
+plc.close()
+```
+
+## Contribution Policy
+
+This repository is maintained on a best-effort basis for internal and product
+needs.
+
+At this time, we do not accept unsolicited pull requests, and we may not be
+able to respond to feature requests or general support issues.

pyads_agile-0.1.0/pyproject.toml

@@ -0,0 +1,124 @@
+[project]
+name = "pyads-agile"
+description = "Agile-maintained Python wrapper for the TwinCAT ADS library, based on pyads"
+authors = [
+    { name = "Agile Automation Technologies GmbH" },
+]
+maintainers = [
+    { name = "Agile Automation Technologies GmbH" },
+]
+readme = "README.md"
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Libraries",
+    "Operating System :: Microsoft :: Windows",
+    "Operating System :: POSIX :: Linux",
+]
+license = "MIT"
+license-files = ["LICENSE"]
+dynamic = ["version"]
+dependencies = [
+    "setuptools>=82.0.0",
+]
+requires-python = ">= 3.9,<4"
+# Outdated Python versions are still included, until they cause problems (after which they will bed dropped)
+# Python 3.8 cannot be used anymore because of a setuptoools minimum version
+
+[project.optional-dependencies]
+docs = [
+    "sphinx",
+    "sphinx_rtd_theme",
+    "recommonmark",
+]
+tests = [
+    "pytest",
+    "pytest-cov",
+    "tox",
+]
+dev = [
+    "build",
+    "flake8",
+    "pytest",
+    "coverage",
+    "coveralls",
+]
+
+[project.urls]
+Upstream = "https://github.com/stlehmann/pyads"
+
+[build-system]
+requires = ["setuptools >= 77.0.3", "wheel"]
+# ^ Support for new `license` format
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+packages = ["pyads", "pyads.testserver"]
+package-dir = { "" = "src" }
+include-package-data = true
+# ^ needed for MANIFEST.in
+
+#[tool.setuptools.package-data]
+# Package data (adslib/) is handled by MANIFEST.in instead
+
+[tool.setuptools.exclude-package-data]
+pyads = ["adslib/**"]
+# ^ Odd trick, put this excludes the adslib source again from a wheel build and from a pip install
+
+[tool.setuptools.dynamic]
+version = {attr = "pyads.__version__"}
+
+[tool.cibuildwheel.linux]
+before-all = "apt install -y meson"
+
+[tool.tox]
+legacy_tox_ini = """
+    [tox]
+    envlist = py38, py39, py310, py311, py312, py313, py314
+
+    [testenv]
+    commands = discover
+    deps = discover
+    changedir = tests
+    whitelist_externals=*
+    passenv = TWINCAT3DIR
+
+    [pytest]
+    testpaths = tests
+"""
+
+[tool.black]
+line-length = 88
+target-version = ['py38', 'py39', 'py310', 'py311', 'py312', 'py313', 'py314']
+include = '\.pyi?$'
+exclude = '''
+(
+  /(
+      .eggs
+    | .git
+    | .mypy_cache
+    | .tox
+    | .venv
+    | _build
+    | buck-out
+    | build
+    | dist
+    | adslib
+    | pyads.egg-info
+  )/
+  | pyads/__init__.py
+)
+'''
+
+[tool.pydocstyle]
+ignore = ["D105", "D213", "D203", "D107"]
+
+[tool.coverage.run]
+include = ["pyads/*"]
+omit = ["pyads/testserver/__main__.py"]

pyads_agile-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pyads_agile-0.1.0/setup.py

@@ -0,0 +1,127 @@
+import os
+import struct
+import subprocess
+import sys
+from pathlib import Path
+
+from setuptools import setup
+from setuptools.command.bdist_wheel import bdist_wheel, get_platform
+from setuptools.command.build_py import build_py
+from setuptools.command.install import install
+
+
+def _is_32bit_interpreter() -> bool:
+    return struct.calcsize("P") == 4
+
+
+src_folder = Path(__file__).parent.absolute() / "src"
+# ^ This will be on PATH for editable install
+adslib_folder = Path(__file__).parent.absolute() / "adslib/build"
+adslib_file = src_folder / "adslib.so"
+
+
+class CustomBuildPy(build_py):
+    """Custom command for `build_py`.
+
+    This command class is used because it is always run, also for an editable install.
+    """
+
+    @classmethod
+    def compile_adslib(cls) -> bool:
+        """Return `True` if adslib was actually compiled."""
+        if cls.platform_is_unix():
+            cls._clean_library()
+            cls._compile_library()
+            return True
+
+        return False
+
+    @staticmethod
+    def _compile_library():
+        """Use `make` to build adslib - build is done in-place."""
+        # Produce `adslib.so`:
+        subprocess.call(["make", "-C", "adslib"])
+
+    @staticmethod
+    def _clean_library():
+        """Remove all compilation artifacts."""
+        patterns = (
+            "*.a",
+            "**/*.o",
+            "*.bin",
+            "*.so",
+        )
+        for pattern in patterns:
+            for file in adslib_folder.glob(pattern):
+                os.remove(file)
+
+        if adslib_file.is_file():
+            os.remove(adslib_file)
+
+    @staticmethod
+    def platform_is_unix():
+        return sys.platform.startswith("linux") or sys.platform.startswith("darwin")
+
+    def run(self):
+        if self.compile_adslib():
+            # Move .so file from Git submodule into src/ to have it on PATH:
+            self.move_file(
+                str(adslib_folder / "adslib.so"),
+                str(adslib_file),
+            )
+
+        super().run()
+
+
+class CustomInstall(install):
+    """Install compiled adslib (but only for Linux)."""
+
+    def run(self):
+        if CustomBuildPy.platform_is_unix():
+            adslib_dest = Path(self.install_lib)
+            if not adslib_dest.exists():
+                adslib_dest.mkdir(parents=True)
+            self.copy_file(
+                str(adslib_file),
+                str(adslib_dest),
+            )
+        super().run()
+
+
+class CustomBDistWheel(bdist_wheel):
+    """Manually mark our wheel for a specific platform."""
+
+    def get_tag(self):
+        """
+
+        See https://packaging.python.org/en/latest/specifications/platform-compatibility-tags/
+        """
+        impl_tag = "py3"  # Same wheel across Python versions
+        abi_tag = "none"  # Same wheel across ABI versions (not a C-extension)
+
+        # But we need to differentiate on the platform for the compiled adslib
+
+        # The following code is copied from `setuptools.command.bdist_wheel.get_tag()`
+        plat_name = get_platform(self.bdist_dir)
+
+        if _is_32bit_interpreter():
+            if plat_name in ("linux-x86_64", "linux_x86_64"):
+                plat_name = "linux_i686"
+            if plat_name in ("linux-aarch64", "linux_aarch64"):
+                plat_name = "linux_armv7l"
+
+        plat_name = (
+            plat_name.lower().replace("-", "_").replace(".", "_").replace(" ", "_")
+        )
+
+        return impl_tag, abi_tag, plat_name
+
+
+# noinspection PyTypeChecker
+setup(
+    cmdclass={
+        "build_py": CustomBuildPy,
+        "install": CustomInstall,
+        "bdist_wheel": CustomBDistWheel,
+    },
+)

pyads_agile-0.1.0/src/pyads/__init__.py

@@ -0,0 +1,121 @@
+"""The pyads package.
+
+:author: Stefan Lehmann <stlm@posteo.de>
+:license: MIT, see license file or https://opensource.org/licenses/MIT
+:created on: 2018-06-11 18:15:53
+
+"""
+from .structs import AmsAddr, NotificationAttrib
+
+from .ads import (
+    open_port,
+    close_port,
+    get_local_address,
+    add_route,
+    add_route_to_plc,
+    delete_route,
+    set_local_address,
+    set_timeout,
+    size_of_structure,
+    dict_from_bytes,
+    bytes_from_dict,
+    StructureDef,
+)
+
+from .connection import Connection
+
+from .pyads_ex import ADSError
+
+from .constants import (
+    PLCTYPE_BOOL,
+    PLCTYPE_BYTE,
+    PLCTYPE_DATE,
+    PLCTYPE_DINT,
+    PLCTYPE_DT,
+    PLCTYPE_DWORD,
+    PLCTYPE_INT,
+    PLCTYPE_LINT,
+    PLCTYPE_LREAL,
+    PLCTYPE_REAL,
+    PLCTYPE_SINT,
+    PLCTYPE_STRING,
+    PLCTYPE_WSTRING,
+    PLCTYPE_TIME,
+    PLCTYPE_TOD,
+    PLCTYPE_ULINT,
+    PLCTYPE_UDINT,
+    PLCTYPE_UINT,
+    PLCTYPE_USINT,
+    PLCTYPE_WORD,
+    PLCTYPE_ARR_DINT,
+    PLCTYPE_ARR_INT,
+    PLCTYPE_ARR_LREAL,
+    PLCTYPE_ARR_REAL,
+    PLCTYPE_ARR_SHORT,
+    PLC_DEFAULT_STRING_SIZE,
+    DATATYPE_MAP,
+)
+
+from .constants import (
+    PORT_EVENTLOGGER,
+    PORT_IO,
+    PORT_LOGGER,
+    PORT_NC,
+    PORT_NOCKE,
+    PORT_SCOPE,
+    PORT_SPECIALTASK1,
+    PORT_SPECIALTASK2,
+    PORT_SPS1,
+    PORT_SPS2,
+    PORT_SPS3,
+    PORT_SPS4,
+    PORT_SYSTEMSERVICE,
+    PORT_CAM,
+    PORT_TC2PLC1,
+    PORT_TC2PLC2,
+    PORT_TC2PLC3,
+    PORT_TC2PLC4,
+    PORT_TC3PLC1,
+)
+
+from .constants import (
+    INDEXGROUP_MEMORYBYTE,
+    INDEXGROUP_MEMORYBIT,
+    INDEXGROUP_MEMORYSIZE,
+    INDEXGROUP_RETAIN,
+    INDEXGROUP_RETAINSIZE,
+    INDEXGROUP_DATA,
+    INDEXGROUP_DATASIZE,
+)
+
+from .constants import (
+    ADSSTATE_INVALID,
+    ADSSTATE_IDLE,
+    ADSSTATE_RESET,
+    ADSSTATE_INIT,
+    ADSSTATE_START,
+    ADSSTATE_RUN,
+    ADSSTATE_STOP,
+    ADSSTATE_SAVECFG,
+    ADSSTATE_LOADCFG,
+    ADSSTATE_POWERFAILURE,
+    ADSSTATE_POWERGOOD,
+    ADSSTATE_ERROR,
+    ADSSTATE_SHUTDOWN,
+    ADSSTATE_SUSPEND,
+    ADSSTATE_RESUME,
+    ADSSTATE_CONFIG,
+    ADSSTATE_RECONFIG,
+)
+
+from .constants import (
+    ADSTRANS_NOTRANS,
+    ADSTRANS_CLIENTCYCLE,
+    ADSTRANS_CLIENT1REQ,
+    ADSTRANS_SERVERCYCLE,
+    ADSTRANS_SERVERONCHA,
+)
+
+from .symbol import AdsSymbol
+
+__version__ = '0.1.0'