8.5.1.5. pymodaq_utils.plugin_tools.rules module

Static rules to guide the development of a PyMoDAQ instrument plugin (pymodaq_plugins_*).

The rules read the source files of a plugin package (pyproject.toml, python modules): nothing is imported, so they also work when the instrument SDK or other dependencies are not installed. Each rule produces Finding objects with a stable code, a severity, a location and a hint about how to fix it.

Severities:

• error: the plugin will not work or will not be seen by PyMoDAQ

• 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 pymodaq_utils.plugin_tools.checks but can be called directly:

from pymodaq_utils.plugin_tools.rules import check_package_sources
for finding in check_package_sources('pymodaq_plugins_xxxx'):
    print(finding)

Added in version 5.3.1.

class pymodaq_utils.plugin_tools.rules.Finding(code, severity, message, hint='', path=None, line=None, column=None)

Bases: object

One thing found by a rule

Variables:

• code (str) – stable identifier of the rule, PMQ1xx: packaging, PMQ2xx: unfinished plugin, PMQ3xx: plugin classes

• severity (Severity)

• message (str)

• hint (str) – how to fix it

• path (Path) – file concerned

• line (int) – line concerned

• column (int) – column concerned

Attributes:

column

line

location

path

Methods

format([color])

Text of the finding, with colors for a terminal if color

format(color=False)

Text of the finding, with colors for a terminal if color

Return type:

str

code: str

column: int | None = None

hint: str = ''

line: int | None = None

property location: str

message: str

path: Path | None = None

severity: Severity

class pymodaq_utils.plugin_tools.rules.Severity(*values)

Bases: str, Enum

ERROR = 'error'

TODO = 'todo'

WARNING = 'warning'

pymodaq_utils.plugin_tools.rules.check_extension_source(path)

Rules on a module of the extensions folder of a plugin package, without importing it

• PMQ330: EXTENSION_NAME or CLASS_NAME missing in a module defining an extension: the Dashboard does not list it

• PMQ331: CLASS_NAME is not the name of a class of the module

• PMQ332: the class does not derive from CustomExt (CustomApp has no access to the Dashboard)

• PMQ333: import from a module of pymodaq that only remains as a deprecated shim

• PMQ334: deprecated hooks setup_docks / setup_menu

• PMQ335: the extension creates its own ExperimentManager or StateManager

• PMQ336: the __init__ does not take the parent and dashboard arguments given by the Dashboard

• PMQ337: the __init__ of a class deriving from CustomExt never calls self.setup_ui()

• PMQ338: a class deriving directly from CustomExt has no _quit_fun guard, or one that never returns True

• PMQ339: the extension class overrides quit_fun instead of _quit_fun

Return type:

list[Finding]

pymodaq_utils.plugin_tools.rules.check_extensions(root)

The rules on every module of the extensions folder of the package

Return type:

list[Finding]

pymodaq_utils.plugin_tools.rules.check_file_names(root)

Python files whose name is not a valid module name: they cannot be imported and should not be shipped

Return type:

list[Finding]

pymodaq_utils.plugin_tools.rules.check_leftovers(package, root, project=None)

Template leftovers: TODO comments, placeholders, NotImplementedError, example modules

Return type:

list[Finding]

pymodaq_utils.plugin_tools.rules.check_os_classifiers(package_folder, project)

PMQ320: the Operating System classifiers of the pyproject.toml do not match the supported_platforms declared by the instrument plugins

Return type:

list[Finding]

pymodaq_utils.plugin_tools.rules.check_package_sources(package)

All the static rules on an installed (or editable) plugin package: packaging, leftovers and plugin classes

Return type:

list[Finding]

pymodaq_utils.plugin_tools.rules.check_plugin_source(path, kind, class_name, static_fallback=False)

Rules on the source of a plugin module, without importing it

Parameters:

• path (Path) – the python file

• kind (str) – ‘move’ or the dimensionality of a viewer (‘0D’, ‘1D’, ‘2D’, ‘ND’)

• class_name (str) – name of the plugin class that is expected in the module

• static_fallback (bool) – if True also apply the rules that duplicate the checks done on the imported class (use it when the module cannot be imported because of a missing dependency)

Return type:

list[Finding]

pymodaq_utils.plugin_tools.rules.check_pyproject(package, project)

Rules on the pyproject.toml and the layout of the project

Return type:

list[Finding]

pymodaq_utils.plugin_tools.rules.check_python_code(root)

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. Not reported in the modules that only the instruments declaring supported_platforms = ('win32',) use

Return type:

list[Finding]

pymodaq_utils.plugin_tools.rules.colorize(text, style, enabled=True)

Wrap a text in the ANSI escape codes of a style (bold, dim, red, green, yellow, cyan) if enabled

Return type:

str

pymodaq_utils.plugin_tools.rules.is_valid_unit(unit)

Whether a unit is known from pint (with the units of PyMoDAQ if pymodaq_data is installed)

Return type:

bool

pymodaq_utils.plugin_tools.rules.package_root(package)

Folder of the python package, found without importing it

Return type:

Optional[Path]

pymodaq_utils.plugin_tools.rules.project_root(package)

Folder holding the pyproject.toml of the plugin: only exists for a source tree or an editable install

Return type:

Optional[Path]

pymodaq_utils.plugin_tools.rules.syntax_error_finding(code, path, error)

Finding with the location (line and column) and the offending line of a syntax error

Return type:

Finding

pymodaq_utils.plugin_tools.rules.use_color(mode='auto', stream=None)

Whether to color the output: mode is ‘always’, ‘never’ or ‘auto’

auto colors if the stream (stdout by default) is a terminal and the NO_COLOR environment variable is not set, or if FORCE_COLOR is set (see https://no-color.org).

Return type:

bool