pymodaq_utils 5.3.4__tar.gz → 5.3.6__tar.gz

{pymodaq_utils-5.3.4 → pymodaq_utils-5.3.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pymodaq_utils
-Version: 5.3.4
+Version: 5.3.6
 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.6/src/pymodaq_utils/plugin_checks.py

@@ -0,0 +1,14 @@
+"""Moved to :mod:`pymodaq_utils.plugin_tools.checks`, this module is an alias kept for existing code.
+
+.. versionadded:: 5.3.1
+.. deprecated:: 5.3.5
+    Use ``pymodaq_utils.plugin_tools.checks``.
+"""
+import sys
+
+from pymodaq_utils.plugin_tools import checks as _module
+
+if __name__ == '__main__':  # python -m pymodaq_utils.plugin_checks
+    raise SystemExit(_module.main())
+
+sys.modules[__name__] = _module

pymodaq_utils-5.3.6/src/pymodaq_utils/plugin_rules.py

@@ -0,0 +1,14 @@
+"""Moved to :mod:`pymodaq_utils.plugin_tools.rules`, this module is an alias kept for existing code.
+
+.. versionadded:: 5.3.1
+.. deprecated:: 5.3.5
+    Use ``pymodaq_utils.plugin_tools.rules``.
+"""
+import sys
+
+from pymodaq_utils.plugin_tools import rules as _module
+
+if __name__ == '__main__':  # python -m pymodaq_utils.plugin_rules
+    raise SystemExit(_module.main())
+
+sys.modules[__name__] = _module

pymodaq_utils-5.3.6/src/pymodaq_utils/plugin_scaffold.py

@@ -0,0 +1,14 @@
+"""Moved to :mod:`pymodaq_utils.plugin_tools.scaffold`, this module is an alias kept for existing code.
+
+.. versionadded:: 5.3.1
+.. deprecated:: 5.3.5
+    Use ``pymodaq_utils.plugin_tools.scaffold``.
+"""
+import sys
+
+from pymodaq_utils.plugin_tools import scaffold as _module
+
+if __name__ == '__main__':  # python -m pymodaq_utils.plugin_scaffold
+    raise SystemExit(_module.main())
+
+sys.modules[__name__] = _module

pymodaq_utils-5.3.6/src/pymodaq_utils/plugin_tools/__init__.py

@@ -0,0 +1,12 @@
+"""Tools to develop and maintain PyMoDAQ instrument plugins.
+
+* :mod:`~pymodaq_utils.plugin_tools.contract`: the methods of a plugin (single definition)
+* :mod:`~pymodaq_utils.plugin_tools.rules`: the static rules (``PMQxxx`` codes)
+* :mod:`~pymodaq_utils.plugin_tools.checks`: the report on a plugin package (``check_plugin`` command)
+* :mod:`~pymodaq_utils.plugin_tools.scaffold`: creation of new plugin modules
+
+They read the source files of the plugins and do not import ``pymodaq``. The previous locations
+(``pymodaq_utils.plugin_tools.checks``, ``plugin_rules`` and ``plugin_scaffold``) still work.
+
+.. versionadded:: 5.3.5
+"""

pymodaq_utils-5.3.4/src/pymodaq_utils/plugin_checks.py → pymodaq_utils-5.3.6/src/pymodaq_utils/plugin_tools/checks.py

@@ -12,7 +12,7 @@ Every check is also exposed as a plain function returning a list of problems (em
 
 To get a report without pytest, for any installed plugin package::
 
-    from pymodaq_utils.plugin_checks import check_plugin_package
+    from pymodaq_utils.plugin_tools.checks import check_plugin_package
     print(check_plugin_package('pymodaq_plugins_mock'))
 
 .. versionadded:: 5.3.1
@@ -33,19 +33,21 @@ 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_python_code, check_pyproject, colorize, is_valid_unit, package_root,
-                                        project_root, use_color)
+from pymodaq_utils.plugin_tools.contract import legacy_names
+from pymodaq_utils.plugin_tools import platforms
+from pymodaq_utils.plugin_tools.rules import (MANDATORY_MOVE_METHODS, MANDATORY_VIEWER_METHODS, PLACEHOLDER_NAMES_RE,
+                                              Finding, Severity, check_file_names, check_leftovers,
+                                              check_os_classifiers, check_plugin_source, check_python_code,
+                                              check_pyproject, colorize, is_valid_unit, package_root, project_root,
+                                              use_color)
 
 VIEWER_DIMS = ('0D', '1D', '2D', 'ND')
 ENTRYPOINT_GROUPS = ('pymodaq.plugins', 'pymodaq.instruments')
 OPTIONAL_ENTRYPOINT_GROUPS = ('pymodaq.extensions', 'pymodaq.models', 'pymodaq.pid_models',
                               'pymodaq.scanners', 'pymodaq.h5exporters')
 
-# 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', 'close')  # stop_motion has a default that does nothing
-MANDATORY_VIEWER_METHODS = ('ini_detector', 'grab_data', 'stop', 'close')
+# the methods that have to be overridden by the plugin are defined in pymodaq_utils.plugin_tools.contract (they are abstract
+# in the base classes, but this is not enforced as the bases are QObjects)
 
 # files generated by parser generators (pycparser/ply) that can end up within the plugin packages
 IGNORED_MODULES = ('lextab', 'yacctab')
@@ -206,8 +208,10 @@ def _check_params(klass: type) -> list[str]:
     return problems
 
 
-def _check_methods(klass: type, base: type, mandatory) -> list[str]:
-    problems = [f'{klass.__name__} should override {m}()' for m in mandatory if not _is_overridden(klass, base, m)]
+def _check_methods(klass: type, base: type, mandatory, legacy: Optional[dict] = None) -> list[str]:
+    legacy = legacy or {}  # old names still called by the base class if the method is not defined (see PMQ312)
+    problems = [f'{klass.__name__} should override {m}()' for m in mandatory
+                if not _is_overridden(klass, base, m) and not (m in legacy and hasattr(klass, legacy[m]))]
     if inspect.isabstract(klass):  # in case a base ever becomes a real ABC
         problems.append(f'{klass.__name__} is abstract: {sorted(klass.__abstractmethods__)}')
     return problems
@@ -218,7 +222,7 @@ def check_move_class(klass: type) -> list[str]:
     from pymodaq.control_modules.move_utility_classes import DAQ_Move_base  # only needed when checking the classes
     if not (inspect.isclass(klass) and issubclass(klass, DAQ_Move_base)):
         return [f'{klass} should derive from DAQ_Move_base']
-    problems = _check_methods(klass, DAQ_Move_base, MANDATORY_MOVE_METHODS)
+    problems = _check_methods(klass, DAQ_Move_base, MANDATORY_MOVE_METHODS, legacy_names('move'))
     problems += _check_params(klass)
 
     axis_names = klass.get_class_axis_names()
@@ -331,7 +335,7 @@ class CheckResult:
 
     ``problems`` are defects of the plugin found on the imported classes. ``warnings`` mean the item could not be
     fully checked, for instance because a third party module or a vendor SDK is not available in the current
-    environment. ``findings`` come from the static rules of :mod:`pymodaq_utils.plugin_rules`.
+    environment. ``findings`` come from the static rules of :mod:`pymodaq_utils.plugin_tools.rules`.
     """
     item: str
     problems: list[str] = field(default_factory=list)
@@ -462,6 +466,7 @@ def check_package_sources(package: str, project: Optional[Path] = None) -> Check
     project = project or project_root(package)  # None if installed from a wheel: no pyproject.toml to check
     if project is not None:
         result.findings.extend(check_pyproject(package, project))
+        result.findings.extend(check_os_classifiers(root, project))
     result.findings.extend(check_file_names(root))
     result.findings.extend(check_leftovers(package, root, project))
     result.findings.extend(check_python_code(root))
@@ -607,7 +612,7 @@ def check_plugin_file(path: str | Path, fail_on: str = 'error', strict_imports:
 
 def main(argv=None) -> int:
     """Print the report of a plugin package, for the developer: the ``check_plugin`` command (or
-    ``python -m pymodaq_utils.plugin_checks``)
+    ``python -m pymodaq_utils.plugin_tools.checks``)
 
     Returns 0 if the checks pass, 1 otherwise (so that it can also be used in a script or a CI).
     """
@@ -623,6 +628,9 @@ def main(argv=None) -> int:
     parser.add_argument('--strict-imports', action='store_true',
                         help='fail on the modules that cannot be imported (missing dependency or SDK)')
     parser.add_argument('-v', '--verbose', action='store_true', help='list every todo')
+    parser.add_argument('--fix-classifiers', action='store_true',
+                        help='write the Operating System classifiers of the pyproject.toml from the '
+                             'supported_platforms declared by the instrument plugins')
     parser.add_argument('--color', choices=['auto', 'always', 'never'], default='auto',
                         help='color the report: auto (default) if the output is a terminal and NO_COLOR is not set')
     args = parser.parse_args(argv)
@@ -637,9 +645,26 @@ def main(argv=None) -> int:
         package, project = resolve_target(args.package)
     except ValueError as e:
         parser.error(str(e))
+    if args.fix_classifiers:
+        root = package_root(package)
+        if root is None or project is None:
+            parser.error('--fix-classifiers needs the folder of the plugin repository (with its pyproject.toml)')
+        if 'classifiers' in toml.load(project / 'pyproject.toml').get('project', {}).get('dynamic', []):
+            print('pyproject.toml: the classifiers are computed when the package is built, nothing to write')
+        else:
+            try:
+                changed = platforms.update_pyproject_classifiers(project / 'pyproject.toml',
+                                                                 platforms.package_platforms(root))
+            except ValueError as e:
+                parser.error(str(e))
+            print('pyproject.toml: classifiers ' + ('updated' if changed else 'already up to date'))
     report = check_plugin_package(package, args.fail_on, args.strict_imports, project,
                                   check_entry_points=is_installed(package) or project is None)
     print(report.format(verbose=args.verbose, color=use_color(args.color)))
+    root = package_root(package)
+    declared = platforms.package_platforms(root) if root is not None else None
+    if declared:
+        print(f'Works on: {platforms.describe(declared)}')
     return 0 if report.ok else 1
 
 

pymodaq_utils-5.3.6/src/pymodaq_utils/plugin_tools/contract.py

@@ -0,0 +1,115 @@
+"""The contract of an instrument plugin: the methods a plugin class has to (or should) override.
+
+This is the single place where these lists are defined. The static rules (:mod:`pymodaq_utils.plugin_tools.rules`), the
+checks (:mod:`pymodaq_utils.plugin_tools.checks`), the plugin tests and the documentation read them from here, so they
+cannot disagree.
+
+.. versionadded:: 5.3.5
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+Kind = Literal['move', 'viewer']
+
+
+@dataclass(frozen=True)
+class PluginMethod:
+    """One method of an actuator or detector plugin
+
+    Parameters
+    ----------
+    name: str
+        name of the method in the plugin class
+    kind: 'move' or 'viewer'
+        actuator (``DAQ_Move_base``) or detector (``DAQ_Viewer_base``)
+    mandatory: bool
+        if True, a plugin that does not override it is wrong (error). Otherwise the base class has a default
+        that does nothing or raises ``NotImplementedError``: override it when the instrument can do it.
+    purpose: str
+        when it is called and what it has to do
+    returns: str
+        what it has to return ('' if nothing)
+    legacy_name: str
+        deprecated name that PyMoDAQ still calls if the method is not defined ('' if none): a plugin defining it
+        fulfils the contract (with a deprecation warning, see rule PMQ312)
+    """
+    name: str
+    kind: Kind
+    mandatory: bool
+    purpose: str
+    returns: str = ''
+    legacy_name: str = ''
+
+
+PLUGIN_METHODS: tuple[PluginMethod, ...] = (
+    PluginMethod('ini_attributes', 'move', False,
+                 'called first, in the constructor: declare the attributes (type hints, ``self.controller = None``)'),
+    PluginMethod('ini_stage', 'move', True,
+                 'initialize the communication when the actuator is initialized; if ``self.is_master`` create the '
+                 'controller, otherwise use the ``controller`` argument (shared with the master)',
+                 '``(info: str, initialized: bool)``'),
+    PluginMethod('get_actuator_value', 'move', True,
+                 'read the current position from the hardware, on request and after each move',
+                 'a ``DataActuator`` with units (or a float if ``data_actuator_type`` is ``float``)',
+                 legacy_name='check_position'),
+    PluginMethod('move_abs', 'move', True,
+                 'move to an absolute value (a ``DataActuator``, in the units of the axis)',
+                 legacy_name='move_Abs'),
+    PluginMethod('move_rel', 'move', True,
+                 'move by a relative value (a ``DataActuator``, in the units of the axis)',
+                 legacy_name='move_Rel'),
+    PluginMethod('move_home', 'move', False, 'send the actuator to its home position'),
+    PluginMethod('stop_motion', 'move', False, 'stop the motion now; the default does nothing'),
+    PluginMethod('commit_settings', 'move', False,
+                 'a setting of the tree changed in the UI: send it to the hardware'),
+    PluginMethod('close', 'move', True, 'release the hardware (safe state, close the communication)'),
+    PluginMethod('ini_attributes', 'viewer', False,
+                 'called first, in the constructor: declare the attributes (type hints, ``self.controller = None``)'),
+    PluginMethod('ini_detector', 'viewer', True,
+                 'initialize the communication when the detector is initialized; if ``self.is_master`` create the '
+                 'controller, otherwise use the ``controller`` argument (shared with the master)',
+                 '``(info: str, initialized: bool)``'),
+    PluginMethod('grab_data', 'viewer', True,
+                 'start an acquisition (``Naverage`` averages); send the data with ``self.dte_signal.emit`` '
+                 '(or ``dte_signal_temp``) as a ``DataToExport`` with axes and units'),
+    PluginMethod('stop', 'viewer', True, 'stop the acquisition in progress'),
+    PluginMethod('commit_settings', 'viewer', False,
+                 'a setting of the tree changed in the UI: send it to the hardware'),
+    PluginMethod('close', 'viewer', True, 'release the hardware (safe state, close the communication)'),
+)
+
+
+def methods_of(kind: Kind) -> tuple[PluginMethod, ...]:
+    """All the methods of the contract of an actuator ('move') or of a detector ('viewer')"""
+    return tuple(m for m in PLUGIN_METHODS if m.kind == kind)
+
+
+def mandatory_methods(kind: Kind) -> tuple[str, ...]:
+    """Names of the methods that a plugin has to override"""
+    return tuple(m.name for m in methods_of(kind) if m.mandatory)
+
+
+def legacy_names(kind: Kind) -> dict[str, str]:
+    """Deprecated names still accepted in place of the mandatory methods: {method name: old name}"""
+    return {m.name: m.legacy_name for m in methods_of(kind) if m.mandatory and m.legacy_name}
+
+
+def recommended_methods(kind: Kind) -> tuple[str, ...]:
+    """Names of the other methods of the contract: to override when the instrument can do it"""
+    return tuple(m.name for m in methods_of(kind) if not m.mandatory)
+
+
+def contract_as_rst() -> str:
+    """The contract as two reStructuredText tables, to be included in the documentation"""
+    out = []
+    for kind, title in (('move', 'Actuator (``DAQ_Move_base``)'), ('viewer', 'Detector (``DAQ_Viewer_base``)')):
+        out += [title, '-' * len(title), '',
+                '.. list-table::', '   :header-rows: 1', '   :widths: 20 12 48 20', '',
+                '   * - Method', '     - Required', '     - When it is called, what it does', '     - Returns']
+        for m in methods_of(kind):
+            out += [f'   * - ``{m.name}``', f'     - {"yes" if m.mandatory else "no"}',
+                    f'     - {m.purpose}', f'     - {m.returns}']
+        out.append('')
+    return '\n'.join(out)

pymodaq_utils-5.3.6/src/pymodaq_utils/plugin_tools/platforms.py

@@ -0,0 +1,229 @@
+"""Operating systems and processor architectures supported by an instrument plugin.
+
+A plugin that only works on some systems (a Windows driver, a Raspberry Pi board...) declares it in the class of its
+instrument plugin::
+
+    class DAQ_Move_Xxxx(DAQ_Move_base):
+        supported_platforms = ('win32',)                   # values of sys.platform: 'win32', 'linux', 'darwin'
+        supported_architectures = ('aarch64', 'armv7l')    # optional, values of platform.machine()
+
+``None`` (the default of the base classes) means all of them. PyMoDAQ then refuses to initialize the plugin on another
+system, with a message, and ``check_plugin`` reads the declaration to check (and update with ``--fix-classifiers``)
+the ``Operating System`` classifiers of the ``pyproject.toml``.
+
+.. versionadded:: 5.3.5
+"""
+from __future__ import annotations
+
+import ast
+import platform
+import re
+import sys
+from pathlib import Path
+from typing import Iterable, Optional
+
+#: values of ``sys.platform`` and the matching name and PyPI classifier
+PLATFORMS = {
+    'win32': ('Windows', 'Operating System :: Microsoft :: Windows'),
+    'linux': ('Linux', 'Operating System :: POSIX :: Linux'),
+    'darwin': ('macOS', 'Operating System :: MacOS'),
+}
+OS_INDEPENDENT = 'Operating System :: OS Independent'
+
+#: values of ``platform.machine()`` (compared without case), with their aliases
+ARCHITECTURES = {
+    'x86_64': ('x86_64', 'amd64'),
+    'i686': ('i686', 'i386', 'x86'),
+    'aarch64': ('aarch64', 'arm64'),
+    'armv7l': ('armv7l', 'armv8l'),
+    'armv6l': ('armv6l',),
+}
+_ARCH_ALIASES = {alias: name for name, aliases in ARCHITECTURES.items() for alias in aliases}
+
+PLUGIN_CLASS_RE = re.compile(r'^DAQ_(Move|[0-2N]DViewer)_\w+$')
+_OS_CLASSIFIER_RE = re.compile(r'^(?P<indent>\s*)(?P<quote>["\'])Operating System ::.*$')
+
+
+def _as_tuple(value) -> Optional[tuple]:
+    if value is None:
+        return None
+    return (value,) if isinstance(value, str) else tuple(value)
+
+
+def normalize_architecture(machine: str) -> str:
+    """Canonical name of an architecture (``arm64`` -> ``aarch64``...), the lowercased input if unknown"""
+    return _ARCH_ALIASES.get(machine.lower(), machine.lower())
+
+
+def describe(platforms: Optional[Iterable[str]] = None, architectures: Optional[Iterable[str]] = None) -> str:
+    """Text for the user, for instance ``Linux (aarch64, armv7l)``; empty if there is no restriction"""
+    platforms, architectures = _as_tuple(platforms), _as_tuple(architectures)
+    text = ' or '.join(PLATFORMS.get(p, (p,))[0] for p in platforms) if platforms else ''
+    if architectures:
+        arch = ', '.join(architectures)
+        text = f'{text} ({arch})' if text else f'the architectures {arch}'
+    return text
+
+
+def unsupported_reason(platforms: Optional[Iterable[str]] = None, architectures: Optional[Iterable[str]] = None,
+                       system: Optional[str] = None, machine: Optional[str] = None) -> str:
+    """Why a plugin cannot run on this computer, or an empty string if it can
+
+    Parameters
+    ----------
+    platforms: iterable of str or None
+        values of ``sys.platform`` the plugin works on (``None``: all). A prefix is enough: ``linux`` matches
+        ``linux2``
+    architectures: iterable of str or None
+        values of ``platform.machine()`` the plugin works on (``None``: all)
+    system, machine: str
+        replace ``sys.platform`` and ``platform.machine()``, for tests
+    """
+    platforms, architectures = _as_tuple(platforms), _as_tuple(architectures)
+    system = sys.platform if system is None else system
+    machine = platform.machine() if machine is None else machine
+    ok_system = not platforms or any(system.startswith(p) for p in platforms)
+    ok_machine = not architectures or normalize_architecture(machine) in {normalize_architecture(a)
+                                                                         for a in architectures}
+    if ok_system and ok_machine:
+        return ''
+    return f'This plugin only works on {describe(platforms, architectures)} (this computer: {system}, {machine})'
+
+
+def classifiers_for(platforms: Optional[Iterable[str]] = None) -> list[str]:
+    """The ``Operating System`` classifiers of a plugin working on these systems (``None``: OS independent)"""
+    platforms = _as_tuple(platforms)
+    if not platforms:
+        return [OS_INDEPENDENT]
+    return [PLATFORMS[p][1] for p in PLATFORMS if p in platforms]
+
+
+def invalid_values(platforms: Optional[Iterable[str]], architectures: Optional[Iterable[str]]) -> list[str]:
+    """Problems of a declaration: unknown system or architecture names, empty lists"""
+    problems = []
+    platforms, architectures = _as_tuple(platforms), _as_tuple(architectures)
+    if platforms is not None:
+        if not platforms:
+            problems.append('supported_platforms is empty, use None for all the systems')
+        problems.extend(f"unknown system '{p}' in supported_platforms, use {list(PLATFORMS)}"
+                        for p in platforms if p not in PLATFORMS)
+    if architectures is not None:
+        if not architectures:
+            problems.append('supported_architectures is empty, use None for all the architectures')
+        problems.extend(f"unknown architecture '{a}' in supported_architectures, use values of platform.machine() "
+                        f"like {list(ARCHITECTURES)}" for a in architectures if normalize_architecture(a) not in
+                        ARCHITECTURES)
+    return problems
+
+
+def declared_in_class(cls: ast.ClassDef) -> tuple[Optional[tuple], Optional[tuple]]:
+    """``(supported_platforms, supported_architectures)`` written in the body of a plugin class (None if absent or
+    not a literal)"""
+    found = {}
+    for node in cls.body:
+        targets = []
+        if isinstance(node, ast.Assign):
+            targets, value = [t for t in node.targets if isinstance(t, ast.Name)], node.value
+        elif isinstance(node, ast.AnnAssign) and isinstance(node.target, ast.Name) and node.value is not None:
+            targets, value = [node.target], node.value
+        for target in targets:
+            if target.id in ('supported_platforms', 'supported_architectures'):
+                try:
+                    found[target.id] = _as_tuple(ast.literal_eval(value))
+                except (ValueError, SyntaxError):
+                    pass
+    return found.get('supported_platforms'), found.get('supported_architectures')
+
+
+def package_platforms(root: Path) -> Optional[set]:
+    """Systems on which the instruments of a plugin package work (union over the instrument modules), read from the
+    sources. ``None`` if at least one instrument works on all of them"""
+    systems: set = set()
+    files = sorted(set(root.rglob('daq_move_*.py')) | set(root.rglob('daq_*viewer_*.py')))
+    for file in files:
+        try:
+            tree = ast.parse(file.read_text(encoding='utf-8'))
+        except (SyntaxError, UnicodeDecodeError, OSError):
+            continue
+        for cls in (n for n in tree.body if isinstance(n, ast.ClassDef) and PLUGIN_CLASS_RE.match(n.name)):
+            declared, _ = declared_in_class(cls)
+            if not declared:
+                return None
+            systems.update(declared)
+    return systems or None
+
+
+def pyproject_os_classifiers(classifiers: Iterable[str]) -> list[str]:
+    return [c for c in classifiers if c.startswith('Operating System ::')]
+
+
+def update_pyproject_classifiers(pyproject: Path, platforms: Optional[Iterable[str]]) -> bool:
+    """Replace the ``Operating System`` classifiers in the ``classifiers`` list of a ``pyproject.toml`` (a text edit,
+    the rest of the file is kept). Returns True if the file changed"""
+    wanted = classifiers_for(platforms)
+    lines = pyproject.read_text(encoding='utf-8').splitlines(keepends=True)
+    start = next((i for i, line in enumerate(lines) if re.match(r'^\s*classifiers\s*=\s*\[', line)), None)
+    if start is None:
+        raise ValueError('no classifiers = [...] list in the pyproject.toml (dynamic classifiers?)')
+    end = next((i for i in range(start, len(lines)) if lines[i].strip().startswith(']') or
+                (i == start and lines[i].rstrip().endswith(']'))), None)
+    if end is None or end == start:
+        raise ValueError('the classifiers list must be written on several lines')
+    indexes = [i for i in range(start + 1, end) if _OS_CLASSIFIER_RE.match(lines[i])]
+    sample = lines[indexes[0]] if indexes else lines[end - 1]
+    indent = re.match(r'\s*', sample).group(0) or '    '
+    quote = '"'
+    new = [f'{indent}{quote}{c}{quote},\n' for c in wanted]
+    if indexes:
+        first = indexes[0]
+        rebuilt = [line for i, line in enumerate(lines) if i not in indexes]
+        rebuilt[first:first] = new
+    else:
+        rebuilt = lines[:end] + new + lines[end:]
+        if lines[end - 1].rstrip().endswith('"') or lines[end - 1].rstrip().endswith("'"):
+            rebuilt[end - 1] = lines[end - 1].rstrip() + ',\n'
+    changed = rebuilt != lines
+    if changed:
+        pyproject.write_text(''.join(rebuilt), encoding='utf-8')
+    return changed
+
+
+#: Python versions PyMoDAQ is developed for, they give the ``Programming Language :: Python`` classifiers
+PYTHON_VERSIONS = ('3.10', '3.11', '3.12', '3.13')
+
+
+def python_classifiers(requires_python: str = '') -> list[str]:
+    """``Programming Language :: Python :: 3.x`` for each of :data:`PYTHON_VERSIONS` accepted by ``requires-python``
+    (all of them if empty or invalid)"""
+    from packaging.specifiers import InvalidSpecifier, SpecifierSet
+    try:
+        spec = SpecifierSet(requires_python or '')
+    except InvalidSpecifier:
+        spec = SpecifierSet('')
+    return [f'Programming Language :: Python :: {v}' for v in PYTHON_VERSIONS if spec.contains(f'{v}.0')]
+
+
+def dynamic_classifiers(pyproject: dict, package_folder: Path) -> list[str]:
+    """The classifiers of a plugin whose ``classifiers`` field is *dynamic* in the ``pyproject.toml``: those listed in
+    ``[tool.pymodaq] classifiers`` (the ``Operating System`` and ``Programming Language :: Python :: 3.x`` ones are
+    ignored) followed by the Python versions accepted by ``requires-python`` and the systems computed from the
+    ``supported_platforms`` of its instrument plugins. Used by the hatch metadata hook at build time"""
+    listed = pyproject.get('tool', {}).get('pymodaq', {}).get('classifiers', [])
+    kept = [c for c in listed if not c.startswith(('Operating System ::', 'Programming Language :: Python :: 3.'))]
+    return (kept + python_classifiers(pyproject.get('project', {}).get('requires-python', '')) +
+            classifiers_for(package_platforms(package_folder)))
+
+
+def platforms_as_rst() -> str:
+    """The accepted values as two reStructuredText tables, to be included in the documentation"""
+    out = ['.. list-table::', '   :header-rows: 1', '   :widths: 20 20 60', '',
+           '   * - ``supported_platforms``', '     - System', '     - Classifier']
+    for key, (label, classifier) in PLATFORMS.items():
+        out += [f'   * - ``{key}``', f'     - {label}', f'     - ``{classifier}``']
+    out += ['', '.. list-table::', '   :header-rows: 1', '   :widths: 30 70', '',
+            '   * - ``supported_architectures``', '     - Also accepted (same architecture)']
+    for key, aliases in ARCHITECTURES.items():
+        other = ', '.join(f'``{a}``' for a in aliases if a != key)
+        out += [f'   * - ``{key}``', f'     - {other}']
+    out.append('')
+    return '\n'.join(out)

pymodaq_utils-5.3.4/src/pymodaq_utils/plugin_rules.py → pymodaq_utils-5.3.6/src/pymodaq_utils/plugin_tools/rules.py

@@ -10,9 +10,9 @@ Severities:
 * ``warning``: deprecated or suspicious, should be fixed
 * ``todo``: the plugin is not finished (leftover of the template: TODO comments, placeholders, ``NotImplementedError``)
 
-They are used by :mod:`pymodaq_utils.plugin_checks` but can be called directly::
+They are used by :mod:`pymodaq_utils.plugin_tools.checks` but can be called directly::
 
-    from pymodaq_utils.plugin_rules import check_package_sources
+    from pymodaq_utils.plugin_tools.rules import check_package_sources
     for finding in check_package_sources('pymodaq_plugins_xxxx'):
         print(finding)
 
@@ -21,6 +21,7 @@ They are used by :mod:`pymodaq_utils.plugin_checks` but can be called directly::
 from __future__ import annotations
 
 import ast
+import functools
 import importlib.util
 import os
 import re
@@ -33,6 +34,9 @@ from typing import Optional
 
 import toml
 
+from pymodaq_utils.plugin_tools.contract import legacy_names, mandatory_methods
+from pymodaq_utils.plugin_tools import platforms as _platforms
+
 DOC = 'https://pymodaq.cnrs.fr/en/latest/developer_folder/instrument_plugins.html'
 TEMPLATE_NAME = 'pymodaq_plugins_template'
 
@@ -43,8 +47,9 @@ 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', 'close')  # stop_motion has a default that does nothing
-MANDATORY_VIEWER_METHODS = ('ini_detector', 'grab_data', 'stop', 'close')
+# defined once in pymodaq_utils.plugin_tools.contract
+MANDATORY_MOVE_METHODS = mandatory_methods('move')
+MANDATORY_VIEWER_METHODS = mandatory_methods('viewer')
 
 # 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',
@@ -131,9 +136,17 @@ class Finding:
     def location(self) -> str:
         if self.path is None:
             return ''
+        name = self._path_in_package()
         if not self.line:
-            return self.path.name
-        return f'{self.path.name}:{self.line}' + (f':{self.column}' if self.column else '')
+            return name
+        return f'{name}:{self.line}' + (f':{self.column}' if self.column else '')
+
+    def _path_in_package(self) -> str:
+        """Path of the file from the folder of the plugin package (``hardware/driver.py``), its name if outside"""
+        for parent in self.path.parents:
+            if parent.name.startswith('pymodaq_plugins_'):
+                return self.path.relative_to(parent).as_posix()
+        return self.path.name
 
     def format(self, color: bool = False) -> str:
         """Text of the finding, with colors for a terminal if ``color``"""
@@ -224,9 +237,11 @@ def check_python_code(root: Path) -> list[Finding]:
     * 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
+      path with a drive letter): the plugin cannot be imported, nor listed, on the other systems. Not reported when
+      all the instruments of the package declare ``supported_platforms = ('win32',)``
     """
     findings = []
+    windows_only_package = _platforms.package_platforms(root) == {'win32'}
     for path in _python_files(root):
         source = path.read_text(errors='replace')
         with warnings.catch_warnings(record=True) as caught:
@@ -255,7 +270,7 @@ def check_python_code(root: Path) -> list[Finding]:
                 what = f'the path {node.value!r}'
             if what is not None and not _guarded(node, parents):
                 windows.append((node.lineno, what))
-        if windows:
+        if windows and not windows_only_package:
             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}',
@@ -400,6 +415,31 @@ def check_leftovers(package: str, root: Path, project: Optional[Path] = None) ->
     return findings
 
 
+NOQA_RE = re.compile(r'#\s*noqa\s*:?\s*(PMQ\d+(?:\s*,\s*PMQ\d+)*)', re.IGNORECASE)
+
+
+def _honour_noqa(rule):
+    """Drop the findings of a rule whose line carries a ``# noqa: PMQxxx`` comment (on purpose, like for flake8)"""
+    @functools.wraps(rule)
+    def wrapper(*args, **kwargs):
+        lines = {}
+        kept = []
+        for finding in rule(*args, **kwargs):
+            if finding.path is not None and finding.line is not None:
+                if finding.path not in lines:
+                    try:
+                        lines[finding.path] = Path(finding.path).read_text(errors='replace').splitlines()
+                    except OSError:
+                        lines[finding.path] = []
+                text = lines[finding.path]
+                match = NOQA_RE.search(text[finding.line - 1]) if 0 < finding.line <= len(text) else None
+                if match and finding.code in {c.strip().upper() for c in match.group(1).split(',')}:
+                    continue
+            kept.append(finding)
+        return kept
+    return wrapper
+
+
 def _is_name(node: Optional[ast.AST], name: str) -> bool:
     if isinstance(node, ast.Call):
         node = node.func
@@ -482,11 +522,19 @@ def check_plugin_source(path: Path, kind: str, class_name: str, static_fallback:
     else:
         mandatory = MANDATORY_VIEWER_METHODS
     findings.extend(_check_legacy_settings(path, tree))
+    findings.extend(_check_controller_init(path, tree))
+    for problem in _platforms.invalid_values(*_platforms.declared_in_class(cls)):
+        findings.append(Finding('PMQ319', Severity.WARNING, problem,
+                                'supported_platforms: values of sys.platform (win32, linux, darwin); '
+                                'supported_architectures: values of platform.machine() (x86_64, aarch64, armv7l...)',
+                                path, cls.lineno))
     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:
-            # 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):
+            # the base class still calls the old names (check_position, move_Abs...) if the method is not defined
+            # (see PMQ312)
+            old = legacy_names(kind).get(meth) if kind == 'move' else None
+            if meth not in methods and not (old and old 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')
@@ -512,7 +560,8 @@ def _check_move_source(path: Path, cls: ast.ClassDef, attrs: dict, static_fallba
         findings.append(Finding('PMQ302', Severity.ERROR, "the axes are declared as 'axis_names', that is ignored",
                                 "use '_axis_names'", path, attrs['axis_names'].lineno))
     dat = attrs.get('data_actuator_type')
-    if dat is None or 'DataActuator' not in ast.dump(dat):
+    inherits = dat is None and not all(b == 'DAQ_Move_base' for b in _base_names(cls))  # may be set by a parent
+    if not inherits and (dat is None or 'DataActuator' not in ast.dump(dat)):
         findings.append(Finding('PMQ303', Severity.WARNING, 'data_actuator_type is not DataActuatorType.DataActuator',
                                 'new plugins should exchange DataActuator objects: set '
                                 'data_actuator_type = DataActuatorType.DataActuator', path,
@@ -572,14 +621,28 @@ def _check_legacy_settings(path: Path, tree: ast.Module) -> list[Finding]:
     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,
+                    "PyMoDAQ still translates the old names in settings[...] (deprecated), but not in "
+                    "settings.child(...): use the new ones", path,
                     first.lineno)]
 
 
+def _check_controller_init(path: Path, tree: ast.Module) -> list[Finding]:
+    """PMQ318: deprecated call of ini_stage_init / ini_detector_init to initialize the controller"""
+    calls = [n for n in ast.walk(tree) if isinstance(n, ast.Call) and isinstance(n.func, ast.Attribute) and
+             n.func.attr in ('ini_stage_init', 'ini_detector_init') and
+             isinstance(n.func.value, ast.Name) and n.func.value.id == 'self']
+    if not calls:
+        return []
+    first = min(calls, key=lambda n: n.lineno)
+    more = f' ({len(calls)} times in this file)' if len(calls) > 1 else ''
+    return [Finding('PMQ318', Severity.WARNING, f'{first.func.attr}() is deprecated{more}',
+                    "write: if self.is_master: self.controller = AWrapper() else: self.controller = controller",
+                    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
+    from pymodaq_utils.plugin_tools.checks import find_plugin_modules  # no import cycle at module level
 
     root = package_root(package)
     if root is None:
@@ -593,3 +656,31 @@ def check_package_sources(package: str) -> list[Finding]:
         file = Path(importlib.util.find_spec(mod.import_path).origin)
         findings.extend(check_plugin_source(file, mod.kind, mod.class_name))
     return findings
+
+
+def check_os_classifiers(package_folder: Path, project: Path) -> list[Finding]:
+    """PMQ320: the ``Operating System`` classifiers of the pyproject.toml do not match the ``supported_platforms``
+    declared by the instrument plugins"""
+    path = project / 'pyproject.toml'
+    try:
+        proj = toml.load(path).get('project', {})
+    except toml.TomlDecodeError:
+        return []
+    if 'classifiers' in proj.get('dynamic', []):
+        return []
+    declared = _platforms.package_platforms(package_folder)
+    expected = set(_platforms.classifiers_for(declared))
+    actual = set(_platforms.pyproject_os_classifiers(proj.get('classifiers', [])))
+    if actual == expected:
+        return []
+    what = (f"the plugins work on {_platforms.describe(declared)}" if declared else
+            'no instrument plugin declares supported_platforms (they work on all the systems)')
+    line = next((i for i, text in enumerate(path.read_text().splitlines(), 1) if 'classifiers' in text), None)
+    return [Finding('PMQ320', Severity.WARNING,
+                    f'the Operating System classifiers {sorted(actual) or "(none)"} do not match the code: {what}',
+                    'run check_plugin --fix-classifiers to write ' + ', '.join(sorted(expected)), path, line)]
+
+
+check_plugin_source = _honour_noqa(check_plugin_source)
+check_python_code = _honour_noqa(check_python_code)
+check_leftovers = _honour_noqa(check_leftovers)

pymodaq_utils-5.3.4/src/pymodaq_utils/plugin_scaffold.py → pymodaq_utils-5.3.6/src/pymodaq_utils/plugin_tools/scaffold.py

@@ -1,11 +1,11 @@
 """Helper to add a new, correctly named, instrument to a PyMoDAQ plugin package (``pymodaq_plugins_*``).
 
-It is a development helper, independent of the plugin checks (see :mod:`pymodaq_utils.plugin_checks`). The generated
+It is a development helper, independent of the plugin checks (see :mod:`pymodaq_utils.plugin_tools.checks`). The generated
 module follows the naming convention, derives from the right base class, declares the mandatory attributes and
 methods, and holds ``TODO`` comments (and ``NotImplementedError``) where the instrument specific code goes::
 
-    python -m pymodaq_utils.plugin_scaffold move Xxxx      # actuator: daq_move_Xxxx.py, class DAQ_Move_Xxxx
-    python -m pymodaq_utils.plugin_scaffold 1D Xxxx        # 1D detector: daq_1Dviewer_Xxxx.py, class DAQ_1DViewer_Xxxx
+    python -m pymodaq_utils.plugin_tools.scaffold move Xxxx      # actuator: daq_move_Xxxx.py, class DAQ_Move_Xxxx
+    python -m pymodaq_utils.plugin_tools.scaffold 1D Xxxx        # 1D detector: daq_1Dviewer_Xxxx.py, class DAQ_1DViewer_Xxxx
 
 from the root of the plugin repository (or use ``--folder`` to give the package folder). The same is available from
 python with :func:`create_instrument`.

{pymodaq_utils-5.3.4 → pymodaq_utils-5.3.6}/src/pymodaq_utils/resources/hatch_build_plugins.py

@@ -1,6 +1,7 @@
 from pathlib import Path
 import toml
 
+from pymodaq_utils.plugin_tools.platforms import dynamic_classifiers
 from pymodaq_utils.logger import set_logger, get_module_name
 
 logger = set_logger(get_module_name(__file__))
@@ -43,3 +44,8 @@ def update_metadata_from_toml(metadata: dict, here: Path) -> None:
     metadata['entry-points'] = entrypoints
 
     logger.debug(f'created entry-points: {entrypoints}')
+
+    if 'classifiers' in src_dict.get('project', {}).get('dynamic', []):
+        folder = here / 'src' / PLUGIN_NAME
+        metadata['classifiers'] = dynamic_classifiers(src_dict, folder if folder.is_dir() else here / PLUGIN_NAME)
+        logger.debug(f"created classifiers: {metadata['classifiers']}")