8.5.16. pymodaq_utils.plugin_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_checks but can be called directly:

from pymodaq_utils.plugin_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_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_rules.Severity(*values)

Bases: str, Enum

ERROR = 'error'

TODO = 'todo'

WARNING = 'warning'

pymodaq_utils.plugin_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_rules.check_leftovers(package, root, project=None)

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

Return type:

list[Finding]

pymodaq_utils.plugin_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_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_rules.check_pyproject(package, project)

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

Return type:

list[Finding]

pymodaq_utils.plugin_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_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_rules.package_root(package)

Folder of the python package, found without importing it

Return type:

Optional[Path]

pymodaq_utils.plugin_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_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_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