plcstream2py 0.0.2__tar.gz → 0.0.3__tar.gz

plcstream2py-0.0.3/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

plcstream2py-0.0.3/PKG-INFO

@@ -0,0 +1,19 @@
+Metadata-Version: 2.4
+Name: plcstream2py
+Version: 0.0.3
+Summary: stream2py interface to PLC data
+Home-page: https://github.com/i2mint/plcstream2py
+License: apache-2.0
+Platform: any
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: stream2py
+Requires-Dist: python-snap7<2
+Dynamic: license-file
+
+
+# plcstream2py
+stream2py interface to PLC data
+
+
+To install:	```pip install plcstream2py```

plcstream2py-0.0.3/plcstream2py/__init__.py

@@ -0,0 +1,13 @@
+"""stream2py interface to Siemens S7 PLC data.
+
+Two layers, from low to high:
+
+- :mod:`plcstream2py.raw_plc`: a thin wrapper over ``python-snap7``. ``PlcDataItem``
+  describes one value to read from a PLC (area, word length, DB number, offset, and
+  how to decode the bytes); ``PlcRawRead`` connects to a PLC and reads a list of them.
+- :mod:`plcstream2py.plc`: ``PlcReader``, a ``stream2py.SourceReader`` that polls a
+  ``PlcRawRead`` on a background thread so PLC readings can be consumed as a stream.
+
+Both layers need ``python-snap7``, which wraps the native ``snap7`` library, so they
+are not imported here: ``import plcstream2py`` stays free of that dependency.
+"""

{plcstream2py-0.0.2 → plcstream2py-0.0.3}/plcstream2py/plc.py

@@ -1,3 +1,14 @@
+"""A ``stream2py`` source reader for Siemens S7 PLC data.
+
+:class:`PlcReader` wraps :class:`plcstream2py.raw_plc.PlcRawRead` in a
+``stream2py.SourceReader``: opening it starts a background thread that polls the PLC
+for a fixed list of :class:`plcstream2py.raw_plc.PlcDataItem` values, and ``read``
+pops the readings that have accumulated since the last call.
+
+Importing this module needs ``python-snap7`` (which wraps the native ``snap7``
+library); reading anything from it also needs a reachable PLC.
+"""
+
 import threading
 import time
 from asyncio import Queue
@@ -9,10 +20,10 @@ import snap7
 from snap7.types import S7AreaDB, S7WLReal, S7WLBit, S7WLByte
 
 from stream2py import SourceReader
-from stream2py.sources.raw_plc import PlcRawRead, PlcDataItem, get_byte
-
 from stream2py.utility.typing_hints import ComparableType
 
+from plcstream2py.raw_plc import PlcRawRead, PlcDataItem, get_byte
+
 
 class PlcReader(SourceReader):
     """
@@ -23,7 +34,7 @@ class PlcReader(SourceReader):
         self,
         ip_address: str,
         *,
-        items_to_read: List[PlcDataItem],
+        items_to_read: list[PlcDataItem],
         rack: int,
         slot: int,
         tcp_port: int = 102,
@@ -85,7 +96,7 @@ class PlcReader(SourceReader):
             return True
         return False
 
-    def read(self, blocking: bool = False, timeout: int = 0) -> Optional[Any]:
+    def read(self, blocking: bool = False, timeout: int = 0) -> Any | None:
         """
         :return: timestamp, plc info, read db items as key:value
         """

{plcstream2py-0.0.2 → plcstream2py-0.0.3}/plcstream2py/raw_plc.py

@@ -1,8 +1,22 @@
+"""Thin, snap7-level access to values stored in a Siemens S7 PLC.
+
+:class:`PlcDataItem` describes a single value to read -- where it lives in the PLC
+(area, word length, DB number, start offset, amount) and how to turn the bytes that
+come back into a Python value. :class:`PlcRawRead` connects to a PLC and reads a list
+of those items in one multi-variable request.
+
+This module targets the ``python-snap7`` 1.x API (``snap7.types``, ``snap7.common``,
+``snap7.exceptions``); see ``setup.cfg`` for the pin. :mod:`plcstream2py.plc` builds
+the streaming interface on top of it.
+"""
+
 import ctypes
+import logging
 from contextlib import suppress
 from dataclasses import dataclass
 from pprint import pprint
-from typing import List, Optional, Callable
+from typing import List, Optional
+from collections.abc import Callable
 
 from snap7.common import check_error
 from snap7.exceptions import Snap7Exception
@@ -19,6 +33,8 @@ from snap7.types import (
 from stream2py import SourceReader
 import snap7
 
+logger = logging.getLogger(__name__)
+
 
 def get_byte(_bytearray, byte_index):
     """
@@ -74,12 +90,16 @@ class PlcDataItem:
 
         assert _size != 0, 'Unknown word len'
 
-        print(f'PlcDataItem {self.key}: size = {_size}, amount = {self.amount}')
+        logger.debug(
+            'PlcDataItem %s: size = %s, amount = %s', self.key, _size, self.amount
+        )
 
         try:
             self.buffer = ctypes.create_string_buffer(_size * self.amount)
         except Exception as ex:
-            print(f'ERROR: Failed to allocate string buffer for item {self.key} : {ex}')
+            logger.error(
+                'Failed to allocate string buffer for item %s: %s', self.key, ex
+            )
             return
 
         try:
@@ -87,6 +107,7 @@ class PlcDataItem:
                 ctypes.pointer(self.buffer), ctypes.POINTER(ctypes.c_uint8)
             )
         except Exception as ex:
+            logger.error('Failed to cast buffer for item %s: %s', self.key, ex)
             return
 
     def get_item(self):
@@ -125,7 +146,7 @@ class PlcRawRead:
 
     @classmethod
     def todict(cls, struct):
-        return dict((field, getattr(struct, field)) for field, _ in struct._fields_)
+        return {field: getattr(struct, field) for field, _ in struct._fields_}
 
     def get_info(self):
         if self._plc.get_connected():
@@ -147,10 +168,10 @@ class PlcRawRead:
 
         self._plc.destroy()
 
-    def write_items(self, items: List[PlcDataItem]) -> bool:
+    def write_items(self, items: list[PlcDataItem]) -> bool:
         return False
 
-    def read_items(self, items: List[PlcDataItem]) -> List[dict] or None:
+    def read_items(self, items: list[PlcDataItem]) -> list[dict] or None:
 
         _items = (S7DataItem * len(items))()
         for _i in range(0, len(items)):

plcstream2py-0.0.3/plcstream2py.egg-info/PKG-INFO

@@ -0,0 +1,19 @@
+Metadata-Version: 2.4
+Name: plcstream2py
+Version: 0.0.3
+Summary: stream2py interface to PLC data
+Home-page: https://github.com/i2mint/plcstream2py
+License: apache-2.0
+Platform: any
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: stream2py
+Requires-Dist: python-snap7<2
+Dynamic: license-file
+
+
+# plcstream2py
+stream2py interface to PLC data
+
+
+To install:	```pip install plcstream2py```

{plcstream2py-0.0.2 → plcstream2py-0.0.3}/plcstream2py.egg-info/SOURCES.txt

@@ -1,3 +1,4 @@
+LICENSE
 README.md
 setup.cfg
 setup.py
@@ -8,4 +9,6 @@ plcstream2py.egg-info/PKG-INFO
 plcstream2py.egg-info/SOURCES.txt
 plcstream2py.egg-info/dependency_links.txt
 plcstream2py.egg-info/not-zip-safe
-plcstream2py.egg-info/top_level.txt
+plcstream2py.egg-info/requires.txt
+plcstream2py.egg-info/top_level.txt
+tests/test_plc_import.py

plcstream2py-0.0.3/plcstream2py.egg-info/requires.txt

@@ -0,0 +1,2 @@
+stream2py
+python-snap7<2

{plcstream2py-0.0.2 → plcstream2py-0.0.3}/setup.cfg

@@ -1,12 +1,11 @@
 [metadata]
 name = plcstream2py
-version = 0.0.2
+version = 0.0.3
 url = https://github.com/i2mint/plcstream2py
 platforms = any
 description_file = README.md
 root_url = https://github.com/i2mint/
 license = apache-2.0
-author = OtoSense
 description = stream2py interface to PLC data
 long_description = file:README.md
 long_description_content_type = text/markdown
@@ -18,6 +17,8 @@ packages = find:
 include_package_data = True
 zip_safe = False
 install_requires = 
+	stream2py
+	python-snap7<2
 
 [egg_info]
 tag_build = 

plcstream2py-0.0.3/tests/test_plc_import.py

@@ -0,0 +1,86 @@
+"""Import-level regression tests for :mod:`plcstream2py.plc`.
+
+``plcstream2py.plc`` used to pull ``PlcRawRead``, ``PlcDataItem`` and ``get_byte``
+from ``stream2py.sources.raw_plc``. stream2py deleted that module when it dropped its
+bundled sources, and the code was relocated into this package as
+:mod:`plcstream2py.raw_plc` -- but the import statement was never updated, so
+``plcstream2py.plc`` raised ``ModuleNotFoundError`` on any current stream2py.
+
+That was one instance of a general failure mode: a module the package imports by path
+goes away upstream, and nothing notices until a user tries to import. The tests here
+cover both halves of it -- that ``plcstream2py.plc`` imports, and that every
+``snap7`` attribute the package hard-codes still exists in the library it is pinned
+to. When ``python-snap7`` is installed they run against it; see ``tests/conftest.py``
+for the stand-in used when it is not.
+"""
+
+import importlib
+import sys
+
+import pytest
+
+#: The names :mod:`plcstream2py.plc` needs from the relocated raw-PLC module.
+RELOCATED_NAMES = ('PlcRawRead', 'PlcDataItem', 'get_byte')
+
+#: The module that used to provide them, and must never be reached again.
+ABANDONED_SOURCE_MODULE = 'stream2py.sources.raw_plc'
+
+#: Every ``snap7`` attribute ``plcstream2py`` reaches for by path. A ``python-snap7``
+#: release that moves or renames any of these breaks the package on import, so this
+#: is the contract both the real library and the test stand-in must satisfy.
+SNAP7_ATTRIBUTES_USED = {
+    'snap7.client': ('Client',),
+    'snap7.common': ('check_error',),
+    'snap7.exceptions': ('Snap7Exception',),
+    'snap7.types': (
+        'S7DataItem',
+        'S7AreaDB',
+        'S7WLBit',
+        'S7WLByte',
+        'S7WLWord',
+        'S7WLDWord',
+        'S7WLReal',
+    ),
+    'snap7.util': ('get_bool', 'get_dword', 'get_int', 'get_real', 'get_string'),
+}
+
+
+def _missing_snap7_attributes():
+    """The ``SNAP7_ATTRIBUTES_USED`` entries the importable ``snap7`` does not have."""
+    return [
+        f'{module_name}.{attribute}'
+        for module_name, attributes in SNAP7_ATTRIBUTES_USED.items()
+        for attribute in attributes
+        if not hasattr(importlib.import_module(module_name), attribute)
+    ]
+
+
+def test_plc_module_is_importable(importable_snap7):
+    """``plcstream2py.plc`` imports, given ``snap7`` and the declared dependencies."""
+    plc = importlib.import_module('plcstream2py.plc')
+    assert hasattr(plc, 'PlcReader')
+
+
+def test_raw_plc_names_come_from_this_package(importable_snap7):
+    """The raw-PLC names come from this package, not from a stream2py submodule."""
+    importlib.import_module('plcstream2py.plc')
+
+    # Asserted on what the import pulled in, not on how plc.py spells the import,
+    # so that a rewrite of the import statement does not turn this red for nothing.
+    assert 'plcstream2py.raw_plc' in sys.modules
+    assert ABANDONED_SOURCE_MODULE not in sys.modules
+
+    raw_plc = sys.modules['plcstream2py.raw_plc']
+    assert [name for name in RELOCATED_NAMES if not hasattr(raw_plc, name)] == []
+
+
+@pytest.mark.parametrize('snap7_source', ('real_snap7', 'stubbed_snap7'))
+def test_snap7_provides_the_attributes_the_package_uses(snap7_source, request):
+    """Both the installed ``python-snap7`` and the test stand-in honour the contract.
+
+    Against the real library this catches an upstream move of any attribute
+    ``plcstream2py`` hard-codes; against the stand-in it stops that stand-in from
+    drifting away from the shape it claims to have.
+    """
+    request.getfixturevalue(snap7_source)
+    assert _missing_snap7_attributes() == []

plcstream2py-0.0.2/PKG-INFO

@@ -1,16 +0,0 @@
-Metadata-Version: 2.1
-Name: plcstream2py
-Version: 0.0.2
-Summary: stream2py interface to PLC data
-Home-page: https://github.com/i2mint/plcstream2py
-Author: OtoSense
-License: apache-2.0
-Description: 
-        # plcstream2py
-        stream2py interface to PLC data
-        
-        
-        To install:	```pip install plcstream2py```
-        
-Platform: any
-Description-Content-Type: text/markdown

plcstream2py-0.0.2/plcstream2py.egg-info/PKG-INFO

@@ -1,16 +0,0 @@
-Metadata-Version: 2.1
-Name: plcstream2py
-Version: 0.0.2
-Summary: stream2py interface to PLC data
-Home-page: https://github.com/i2mint/plcstream2py
-Author: OtoSense
-License: apache-2.0
-Description: 
-        # plcstream2py
-        stream2py interface to PLC data
-        
-        
-        To install:	```pip install plcstream2py```
-        
-Platform: any
-Description-Content-Type: text/markdown