pymodaq_utils 5.3.1__tar.gz → 5.3.2__tar.gz

{pymodaq_utils-5.3.1 → pymodaq_utils-5.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pymodaq_utils
-Version: 5.3.1
+Version: 5.3.2
 Summary: Modular Data Acquisition with Python
 Project-URL: Homepage, http://pymodaq.cnrs.fr
 Project-URL: Source, https://github.com/PyMoDAQ/PyMoDAQ

{pymodaq_utils-5.3.1 → pymodaq_utils-5.3.2}/src/pymodaq_utils/plugin_checks.py

@@ -34,7 +34,7 @@ import toml
 from pymodaq_utils.utils import get_entrypoints
 
 from pymodaq_utils.plugin_rules import (PLACEHOLDER_NAMES_RE, Finding, Severity, check_file_names, check_leftovers,
-                                        check_plugin_source, check_pyproject, colorize, is_valid_unit, package_root,
+                                        check_plugin_source, check_python_code, check_pyproject, colorize, is_valid_unit, package_root,
                                         project_root, use_color)
 
 VIEWER_DIMS = ('0D', '1D', '2D', 'ND')
@@ -44,7 +44,7 @@ OPTIONAL_ENTRYPOINT_GROUPS = ('pymodaq.extensions', 'pymodaq.models', 'pymodaq.p
 
 # methods that have to be overridden by the plugin (they are abstract in the base classes, but these are not
 # enforced as the bases are QObjects)
-MANDATORY_MOVE_METHODS = ('ini_stage', 'get_actuator_value', 'stop_motion', 'close')
+MANDATORY_MOVE_METHODS = ('ini_stage', 'get_actuator_value', 'close')  # stop_motion has a default that does nothing
 MANDATORY_VIEWER_METHODS = ('ini_detector', 'grab_data', 'stop', 'close')
 
 # files generated by parser generators (pycparser/ply) that can end up within the plugin packages
@@ -365,6 +365,14 @@ def check_plugin_module(plugin_module: PluginModule) -> CheckResult:
             (result.warnings if e.environmental else result.problems).append(str(e))
     if loaded:
         result.problems = check_move_class(klass) if plugin_module.kind == 'move' else check_viewer_class(klass)
+        if plugin_module.kind == 'move':
+            from pymodaq.control_modules.move_utility_classes import DAQ_Move_base
+            if not _is_overridden(klass, DAQ_Move_base, 'stop_motion'):
+                result.findings.append(Finding(
+                    'PMQ311', Severity.WARNING,
+                    'stop_motion() is not overridden: the Stop of the actuator does nothing',
+                    'implement it with the stop command of your controller (or ignore this if it cannot be stopped)',
+                    path, None))
     if path is not None:
         result.findings.extend(check_plugin_source(path, plugin_module.kind, plugin_module.class_name,
                                                    static_fallback=not loaded))
@@ -444,6 +452,7 @@ def check_package_sources(package: str, project: Optional[Path] = None) -> Check
         result.findings.extend(check_pyproject(package, project))
     result.findings.extend(check_file_names(root))
     result.findings.extend(check_leftovers(package, root, project))
+    result.findings.extend(check_python_code(root))
     return result
 
 

{pymodaq_utils-5.3.1 → pymodaq_utils-5.3.2}/src/pymodaq_utils/plugin_rules.py

@@ -25,6 +25,7 @@ import importlib.util
 import os
 import re
 import sys
+import warnings
 from dataclasses import dataclass
 from enum import Enum
 from pathlib import Path
@@ -42,9 +43,20 @@ PLACEHOLDER_AUTHORS = ('Name Surname', 'myname@test.fr')
 PLACEHOLDER_NAMES_RE = re.compile(r'python_wrapper_file_of_your_instrument|PythonWrapperObjectOfYourInstrument|'
                                   r'your_method_to_\w+|a_method_or_atttribute_to_check_if_init')
 
-MANDATORY_MOVE_METHODS = ('ini_stage', 'get_actuator_value', 'stop_motion', 'close')
+MANDATORY_MOVE_METHODS = ('ini_stage', 'get_actuator_value', 'close')  # stop_motion has a default that does nothing
 MANDATORY_VIEWER_METHODS = ('ini_detector', 'grab_data', 'stop', 'close')
 
+# hooks of the plugins that were renamed: PyMoDAQ still calls the old ones, with a deprecation warning
+DEPRECATED_HOOKS = {'check_position': 'get_actuator_value', 'move_Abs': 'move_abs', 'move_Rel': 'move_rel',
+                    'move_Home': 'move_home'}
+# attributes of the actuators that were renamed
+DEPRECATED_ATTRIBUTES = {'current_position': 'current_value', 'target_position': 'target_value'}
+# names of the groups of settings that were renamed: PyMoDAQ only translates them in settings[...], not in
+# settings.child(...)
+LEGACY_SETTINGS = {'multiaxes': 'controller', 'multi_status': 'controller_status'}
+WINDOWS_ONLY_IMPORTS = {'winreg', 'msvcrt', '_winreg', 'win32api', 'win32com'}
+WINDOWS_PATH_RE = re.compile(r'^[A-Za-z]:[\\/]')
+
 # features of [features] in pyproject.toml -> folders (relative to the package) holding the corresponding code
 FEATURE_FOLDERS = {'instruments': ('daq_move_plugins', 'daq_viewer_plugins'),
                    'extensions': ('extensions',),
@@ -194,6 +206,65 @@ def check_file_names(root: Path) -> list[Finding]:
             if '__pycache__' not in path.parts and path.stem not in IGNORED_MODULES and not path.stem.isidentifier()]
 
 
+def _guarded(node: ast.AST, parents: dict) -> bool:
+    """Whether a node is inside a ``try`` with handlers or an ``if`` testing the platform"""
+    parent = parents.get(node)
+    while parent is not None:
+        if isinstance(parent, ast.Try) and parent.handlers:
+            return True
+        if isinstance(parent, ast.If) and re.search(r'platform|os\.name|\'nt\'|win32|system\(', ast.dump(parent.test)):
+            return True
+        parent = parents.get(parent)
+    return False
+
+
+def check_python_code(root: Path) -> list[Finding]:
+    """Rules on all the python files of the package (plugins and hardware wrappers)
+
+    * PMQ315: invalid escape sequence in a string (``"C:\\Program Files"``): a warning of python since 3.6, a
+      ``SyntaxWarning`` since 3.12, that will be an error
+    * PMQ317: code that only works on Windows and is executed when the module is imported (``windll``, ``winreg``,
+      path with a drive letter): the plugin cannot be imported, nor listed, on the other systems
+    """
+    findings = []
+    for path in _python_files(root):
+        source = path.read_text(errors='replace')
+        with warnings.catch_warnings(record=True) as caught:
+            warnings.simplefilter('always')
+            try:
+                tree = ast.parse(source, filename=str(path))
+            except SyntaxError:
+                continue  # reported by the other rules
+        for warning in caught:
+            if 'invalid escape sequence' in str(warning.message):
+                findings.append(Finding('PMQ315', Severity.WARNING, str(warning.message),
+                                        "use a raw string (r'...') or double the backslash", path, warning.lineno))
+        parents = {child: node for node in ast.walk(tree) for child in ast.iter_child_nodes(node)}
+        windows = []
+        for node in ast.walk(tree):
+            what = None
+            if isinstance(node, ast.ImportFrom) and node.module == 'ctypes' and any(a.name == 'windll' for a in
+                                                                                    node.names):
+                what = 'ctypes.windll'
+            elif isinstance(node, ast.Import) and any(a.name.split('.')[0] in WINDOWS_ONLY_IMPORTS
+                                                      for a in node.names):
+                what = next(a.name for a in node.names if a.name.split('.')[0] in WINDOWS_ONLY_IMPORTS)
+            elif isinstance(node, ast.ImportFrom) and (node.module or '').split('.')[0] in WINDOWS_ONLY_IMPORTS:
+                what = node.module
+            elif isinstance(node, ast.Constant) and isinstance(node.value, str) and WINDOWS_PATH_RE.match(node.value):
+                what = f'the path {node.value!r}'
+            if what is not None and not _guarded(node, parents):
+                windows.append((node.lineno, what))
+        if windows:
+            line, what = windows[0]
+            more = f' (and {len(windows) - 1} more in this file)' if len(windows) > 1 else ''
+            findings.append(Finding('PMQ317', Severity.WARNING, f'only works on Windows: {what}{more}',
+                                    'import it lazily, in the method that needs it, or guard it with '
+                                    'sys.platform, so that the plugin can be imported on the other systems',
+                                    path, line))
+    return findings
+
+
 # -------------------------------------------------------------------------------------------------------------------
 # PMQ1xx: packaging
 # -------------------------------------------------------------------------------------------------------------------
@@ -406,13 +477,16 @@ def check_plugin_source(path: Path, kind: str, class_name: str, static_fallback:
     methods = {n.name: n for n in cls.body if isinstance(n, (ast.FunctionDef, ast.AsyncFunctionDef))}
     if kind == 'move':
         findings.extend(_check_move_source(path, cls, attrs, static_fallback))
+        findings.extend(_check_deprecated_api(path, tree, methods))
         mandatory = MANDATORY_MOVE_METHODS
     else:
         mandatory = MANDATORY_VIEWER_METHODS
+    findings.extend(_check_legacy_settings(path, tree))
     simple_bases = all(b in ('DAQ_Move_base', 'DAQ_Viewer_base') for b in _base_names(cls))
     if static_fallback and simple_bases:
         for meth in mandatory:
-            if meth not in methods:
+            # the base class still calls check_position if get_actuator_value is not defined (see PMQ312)
+            if meth not in methods and not (meth == 'get_actuator_value' and 'check_position' in methods):
                 findings.append(Finding('PMQ306', Severity.ERROR, f'{class_name} should define {meth}()',
                                         'implement it (see the template)', path, cls.lineno))
     init = methods.get('ini_stage' if kind == 'move' else 'ini_detector')
@@ -461,6 +535,48 @@ def _check_move_source(path: Path, cls: ast.ClassDef, attrs: dict, static_fallba
     return findings
 
 
+def _check_deprecated_api(path: Path, tree: ast.Module, methods: dict) -> list[Finding]:
+    """PMQ312-314: parts of the API of an actuator that were renamed or changed"""
+    findings = []
+    for old, new in DEPRECATED_HOOKS.items():
+        if old in methods:
+            findings.append(Finding('PMQ312', Severity.WARNING, f'{old}() is deprecated, it is still called but with '
+                                    f'a warning', f'rename it {new}()', path, methods[old].lineno))
+    for attr, new in DEPRECATED_ATTRIBUTES.items():
+        uses = [n for n in ast.walk(tree) if isinstance(n, ast.Attribute) and n.attr == attr and
+                isinstance(n.value, ast.Name) and n.value.id == 'self']
+        if uses:
+            more = f' ({len(uses)} times in this file)' if len(uses) > 1 else ''
+            findings.append(Finding('PMQ313', Severity.WARNING, f"'{attr}' is deprecated{more}", f"use '{new}'",
+                                    path, min(n.lineno for n in uses)))
+    # comon_parameters of the actuators is a function since pymodaq 5 (it was a list), the one of the viewers a list
+    names = {a.asname or a.name for n in ast.walk(tree) if isinstance(n, ast.ImportFrom) and
+             (n.module or '').endswith('move_utility_classes') for a in n.names if a.name == 'comon_parameters'}
+    if names:
+        called = {id(n.func) for n in ast.walk(tree) if isinstance(n, ast.Call)}
+        for node in ast.walk(tree):
+            if isinstance(node, ast.Name) and node.id in names and isinstance(node.ctx, ast.Load) and \
+                    id(node) not in called:
+                findings.append(Finding('PMQ314', Severity.ERROR, "'comon_parameters' is used as a list but it is "
+                                        "a function", "call it: comon_parameters_fun(is_multiaxes, axis_names=..., "
+                                        "epsilon=...), or comon_parameters(epsilon)", path, node.lineno))
+    return findings
+
+
+def _check_legacy_settings(path: Path, tree: ast.Module) -> list[Finding]:
+    """PMQ316: names of groups of settings that were renamed"""
+    hits = [n for n in ast.walk(tree) if isinstance(n, ast.Constant) and n.value in LEGACY_SETTINGS]
+    if not hits:
+        return []
+    first = min(hits, key=lambda n: n.lineno)
+    more = f' ({len(hits)} times in this file)' if len(hits) > 1 else ''
+    return [Finding('PMQ316', Severity.WARNING, f"settings group '{first.value}' was renamed "
+                    f"'{LEGACY_SETTINGS[first.value]}'{more}",
+                    "PyMoDAQ only translates the old names in settings[...], not in settings.child(...): use the "
+                    "new ones", path,
+                    first.lineno)]
+
+
 def check_package_sources(package: str) -> list[Finding]:
     """All the static rules on an installed (or editable) plugin package: packaging, leftovers and plugin classes"""
     from pymodaq_utils.plugin_checks import find_plugin_modules  # no import cycle at module level
@@ -472,6 +588,7 @@ def check_package_sources(package: str) -> list[Finding]:
     findings = check_pyproject(package, project) if project is not None else []
     findings.extend(check_file_names(root))
     findings.extend(check_leftovers(package, root, project))
+    findings.extend(check_python_code(root))
     for mod in find_plugin_modules(package):
         file = Path(importlib.util.find_spec(mod.import_path).origin)
         findings.extend(check_plugin_source(file, mod.kind, mod.class_name))

pymodaq_utils-5.3.2/src/pymodaq_utils/plugin_testing.py

@@ -0,0 +1,22 @@
+"""Moved to :mod:`pymodaq.utils.plugin_testing`, with the tools to test the behaviour of a plugin.
+
+The pytest mixin was in ``pymodaq_utils`` to avoid the initialization of ``pymodaq`` when importing it. As it is used
+in tests that import the plugins (hence ``pymodaq``) anyway, it now sits with the other plugin testing tools. This
+module is kept for the plugin repositories written for PyMoDAQ 5.3.1 and will be removed in a later version.
+
+.. versionadded:: 5.3.1
+.. deprecated:: 5.3.2
+    Use ``from pymodaq.utils.plugin_testing import PluginPackageChecks``.
+"""
+from pymodaq_utils.warnings import deprecation_msg
+
+
+def __getattr__(name):
+    if name == 'PluginPackageChecks':
+        try:
+            from pymodaq.utils.plugin_testing import PluginPackageChecks
+        except ImportError as e:  # pragma: no cover
+            raise ImportError('PluginPackageChecks needs pymodaq >= 5.3.2: pymodaq.utils.plugin_testing') from e
+        deprecation_msg('pymodaq_utils.plugin_testing is deprecated, use pymodaq.utils.plugin_testing instead')
+        return PluginPackageChecks
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

pymodaq_utils-5.3.1/src/pymodaq_utils/plugin_testing.py

@@ -1,69 +0,0 @@
-"""Pytest mixin applying the acceptance checks of :mod:`pymodaq_utils.plugin_checks` to a plugin package.
-
-It is in ``pymodaq_utils`` (and not in ``pymodaq``) so that importing it does not start the whole PyMoDAQ
-initialization. Use it in a test module of a plugin repository::
-
-    from pymodaq_utils.plugin_testing import PluginPackageChecks
-
-    class TestMyPlugin(PluginPackageChecks):
-        package_name = 'pymodaq_plugins_myinstrument'  # optional, found from the package folder if omitted
-        fail_on = 'error'  # or 'warning', 'todo'
-        strict_imports = True
-
-.. versionadded:: 5.3.1
-"""
-from pathlib import Path
-from typing import Optional
-
-import pytest
-
-from pymodaq_utils.plugin_checks import (VIEWER_DIMS, PluginModule, check_package_layout, check_package_sources,
-                                         check_plugin_module, find_plugin_modules, guess_package_name)
-
-
-class PluginPackageChecks:
-    """Mixin to subclass in a test module of a plugin repository, see the module documentation.
-
-    Test classes are parametrized per plugin module so that every failure is reported individually.
-    """
-    package_name: Optional[str] = None
-    fail_on = 'error'  # 'error', 'warning' or 'todo' (the unfinished parts: TODO comments, placeholders...): the
-    # findings of the static rules of this level and above fail the tests
-    strict_imports = False  # if True, a module that cannot be imported because of a missing third party module or
-    # SDK fails instead of being skipped (recommended in the CI of a plugin as its dependencies are installed there)
-
-    @pytest.fixture
-    def package(self, request) -> str:
-        return self.package_name or guess_package_name(Path(request.fspath).parent)
-
-    def pytest_generate_tests(self, metafunc):
-        if 'plugin_module' not in metafunc.fixturenames:
-            return
-        package = self.package_name or guess_package_name(Path(str(metafunc.definition.fspath)).parent)
-        kinds = {'move': ('move',), 'viewer': VIEWER_DIMS}
-        wanted = metafunc.function.__name__
-        modules = [m for m in find_plugin_modules(package)
-                   if m.kind in (kinds['move'] if '_move_' in wanted else kinds['viewer'])]
-        metafunc.parametrize('plugin_module', modules, ids=str)
-
-    def test_package_layout(self, package):
-        problems = check_package_layout(package)
-        assert not problems, '\n'.join(problems)
-
-    def test_move_plugin(self, plugin_module):
-        self._assert_module_ok(plugin_module)
-
-    def test_viewer_plugin(self, plugin_module):
-        self._assert_module_ok(plugin_module)
-
-    def test_package_sources(self, package):
-        result = check_package_sources(package)
-        messages = result.failing(self.fail_on)
-        assert not messages, '\n'.join(messages)
-
-    def _assert_module_ok(self, plugin_module: PluginModule):
-        result = check_plugin_module(plugin_module)
-        messages = result.failing(self.fail_on, self.strict_imports)
-        assert not messages, '\n'.join(messages)
-        if result.warnings:
-            pytest.skip('; '.join(result.warnings))