mpylab.env.Measure module

This is mpylab.env.Measure with mpylab.env.Measure.Measure being the base class for e.g. mpylab.env.msc.MSC.MSC

author:

Hans Georg Krauthäuser (main author)

license:

GPL-3 or higher

exception mpylab.env.Measure.AmplifierProtectionError(message)

Bases: Error

Report that a requested RF level violates amplifier protection.

Parameters:

message (str) – Human-readable protection failure details.

exception mpylab.env.Measure.Error

Bases: Exception

Base class for all exceptions of this module

class mpylab.env.Measure.Measure(SearchPaths=None)

Bases: object

Base class for measurements.

Parameters:

SearchPaths (iterable of path-like, optional) – Directories searched for measurement configuration files. The current working directory is used by default.

MakeDeslist(thedata, description)

Call make_deslist() for legacy clients.

Parameters:

  • thedata (mapping) – Data indexed by description.

  • description (str, iterable of str, or None) – Requested descriptions.

Returns:

Available requested descriptions.

Return type:

list

MakeWhatlist(thedata, what)

Call make_whatlist() for legacy clients.

Parameters:

  • thedata (mapping) – Data sets containing channel mappings.

  • what (str, iterable of str, or None) – Requested channels.

Returns:

Available requested channels.

Return type:

list

doLeveling(leveling, mg, names, dct)

Backward-compatible no-op stub for removed legacy leveling API.

The legacy callers expect this method to exist and to return either a new level or None. Current code path keeps behavior by returning None.

Parameters:

  • leveling (object) – Unused legacy leveling configuration.

  • mg (MGraph) – Unused measurement graph.

  • names (mapping) – Unused instrumentation names.

  • dct (mapping) – Unused legacy evaluation context.

do_autosave(name_or_obj=None, depth=None, prefixes=None)

Serialize the measurement state using pickle.

Assuming a calling sequence like so:

script -> method of measurement class -> do_autosave

depth=1 stores the command issued in the script as self.ascmd. If the requested depth is too large, the outermost command is used.

Measurement methods may additionally set self.autosave_resume to a structured restart description. ascmd remains available as the human-readable and legacy restart instruction.

Parameters:

  • name_or_obj (str or binary file-like, optional) – Path-like destination or writable binary stream. self.asname is used by default. Path destinations are replaced atomically; caller-owned streams remain open.

  • depth (int, optional) – Number of caller frames used to derive ascmd.

  • prefixes (iterable of str, optional) – Command prefixes considered when deriving the restart command.

do_leveling(leveling, mg, names, dct)

Call the compatibility doLeveling() implementation.

Parameters:

  • leveling (object) – Legacy leveling configuration.

  • mg (MGraph) – Active measurement graph.

  • names (mapping) – Instrumentation names.

  • dct (mapping) – Legacy evaluation context.

Returns:

The removed legacy implementation is intentionally a no-op.

Return type:

None

make_deslist(thedata, description)

Select available data-set descriptions.

Parameters:

  • thedata (mapping) – Data indexed by description.

  • description (str, iterable of str, or None) – Requested descriptions, or None for all available entries.

Returns:

Requested descriptions that exist in thedata.

Return type:

list

make_whatlist(thedata, what)

Select available result-channel names.

Parameters:

  • thedata (mapping) – Data sets containing channel mappings.

  • what (str, iterable of str, or None) – Requested channels, or None for all available channels.

Returns:

Requested channels present in the data.

Return type:

list

out(item)

Print a nested object recursively on one line.

Parameters:

item (object) – Mapping, sequence, or scalar value to print.

setLevel(mg, level_or_names, level_or_leveler=None)

Backward-compatible wrapper for legacy callers.

Supported call shapes: - setLevel(mg, level_dBm) - setLevel(mg, level_dBm, leveler) - setLevel(mg, names_dict, level_dBm) (legacy TEM/Univers code)

Parameters:

  • mg (MGraph) – Active measurement graph.

  • level_or_names (Quantity, float, or mapping) – Requested level, or a legacy names mapping.

  • level_or_leveler (Quantity, float, or Leveler, optional) – Legacy level argument or leveler instance.

Returns:

Applied signal-generator level returned by set_level().

Return type:

Quantity

set_autosave(name)

Set the autosave filename used by do_autosave().

Parameters:

name (path-like or None) – Autosave destination, or None to disable file output.

set_autosave_interval(interval)

Set the minimum interval between automatic saves.

Parameters:

interval (float) – Minimum interval in seconds.

set_autosave_resume(measurement, method, description, parameter_source='current_configuration')

Store a structured restart instruction alongside ascmd.

Parameters:

  • measurement (str) – Stable measurement-family identifier.

  • method (str) – Method used to continue the measurement.

  • description (str) – Data-set description to resume.

  • parameter_source (str, optional) – Source from which restart parameters must be reconstructed.

Returns:

Pickle-friendly structured restart instruction.

Return type:

dict

set_interactive_runner(runner)

Configure the callback used for interactive sessions.

Parameters:

runner (callable) – Callback starting an interactive session.

set_level(mg, l, leveler=None)

Set the signal-generator level, optionally respecting a leveler.

Parameters:

  • mg (MGraph) – Active measurement graph containing the signal generator.

  • l (Quantity or float) – Requested power. Numeric values are interpreted as dBm.

  • leveler (Leveler, optional) – Leveler whose MaxSafe value limits the request.

Returns:

Level reported as applied by the signal generator.

Return type:

Quantity

set_level_protected(mg, level, output=None, actor=None, leveler=None, reason=None)

Set a signal-generator level without exceeding graph safety limits.

If output is given, MGraph.AmplifierProtect() is used as the hard safety check. Unsafe requests are clipped to MGraph.MaxSafeLevel(); the level is still applied and metadata is returned so measurement code can record that the requested target was unreachable due to amplifier protection.

Parameters:

  • mg (MGraph) – Active measurement graph.

  • level (Quantity or float) – Requested power. Numeric values are interpreted as dBm.

  • output (str, optional) – End node of the path checked for amplifier protection.

  • actor (str, optional) – Signal-generator node. The graph’s sg name is used by default.

  • leveler (Leveler, optional) – Leveler providing an additional MaxSafe constraint.

  • reason (str, optional) – Operation recorded when protection limits the request.

Returns:

Applied level and protection metadata. max_safe_level contains the strictest effective limit when multiple protection sources are active.

Return type:

tuple of (Quantity, dict)

set_logfile(name)

Open or replace the append-only measurement log file.

Parameters:

name (path-like) – Requested log-file path. The filename component is sanitized.

set_logger(logger=None)

Configure the callbacks receiving measurement log messages.

Parameters:

logger (callable or iterable of callable, optional) – Logger callbacks. stdlogger() is used by default.

set_messenger(messenger)

Configure the callback used for user-facing messages.

Parameters:

messenger (callable) – Messenger compatible with stdUserMessenger().

set_post_user_event(event_cb)

Configure the callback run after user-facing interactions.

Parameters:

event_cb (callable) – Callback invoked after an interaction finishes.

set_pre_user_event(event_cb)

Configure the callback run before user-facing interactions.

Parameters:

event_cb (callable) – Callback invoked before an interaction begins.

set_ui_adapter(adapter)

Replace the complete measurement UI adapter.

Parameters:

adapter (UIAdapter) – Adapter providing messaging, logging, and interaction hooks.

set_user_interrupt_Tester(tester)

Call set_user_interrupt_tester() for legacy clients.

Parameters:

tester (callable) – Non-blocking user-interrupt callback.

set_user_interrupt_tester(tester)

Configure the non-blocking user-interrupt callback.

Parameters:

tester (callable) – Callback compatible with stdUserInterruptTester().

static stdEutStatusChecker(status)

Return whether a legacy EUT status denotes normal operation.

Parameters:

status (object) – Legacy EUT status value.

Returns:

True only for "ok" or "OK".

Return type:

bool

static stdInteractiveSession(obj, banner)

Start the default terminal-based interactive session.

Parameters:

  • obj (object) – Object exposed to the interactive session.

  • banner (str) – Introductory text shown by the interactive console.

static stdPostUserEvent()

stdPostUserEvent method.

static stdPreUserEvent()

stdPreUserEvent method.

static stdUserInterruptTester() → int | None

Poll the standard keyboard source for a user interrupt.

Returns:

Key code from mpylab.tools.keyboard.anykeyevent(), or None when no key is available.

Return type:

int or None

stdUserMessenger(msg: str = 'Are you ready?', but: list[str] | None = None, level: str = '', dct: dict[Any, Any] | None = None) → int

Present a message and optionally wait for a button selection.

Parameters:

  • msg (str, optional) – Message shown to the operator.

  • but (list of str, optional) – Button labels selectable by their initial character.

  • level (str, optional) – Message category; "email" enables the legacy email path.

  • dct (mapping, optional) – Supplemental message data, including legacy email fields.

Returns:

Selected button index, or -1 when no buttons are supplied.

Return type:

int

static std_eut_status_checker(status)

Call stdEutStatusChecker() using the snake-case name.

Parameters:

status (object) – Legacy EUT status value.

Returns:

Whether the status denotes normal operation.

Return type:

bool

stdlogger(block, *args)

The standard method to write messages to log file.

Print block to self.logfile or to stdout (if self.logfile is None). If block has attribute keys (i.e. is a dict), the elements are processed with the local function out_block(). Else, the block is printed directly.

Parameters:

  • block (object) – Mapping or scalar message to log.

  • *args (object) – Additional positional values retained for callback compatibility; they are ignored by the standard logger.

wait(delay, dct, uitester, intervall=0.1)

Wait while repeatedly polling an interrupt callback.

Parameters:

  • delay (float) – Number of seconds to wait.

  • dct (mapping) – Namespace passed to legacy callbacks accepting one argument.

  • uitester (callable) – Interrupt callback accepting either dct or no arguments.

  • intervall (float, optional) – Delay in seconds between callback invocations.

class mpylab.env.Measure.MpyLabCompatUnpickler(file, *, fix_imports=True, encoding='ASCII', errors='strict', buffers=())

Bases: Unpickler

Unpickler for legacy mpylab pickle files.

find_class(module, name)

Resolve renamed legacy modules before loading a pickled class.

Parameters:

  • module (str) – Module name stored in the pickle.

  • name (str) – Class or global name stored in the pickle.

Returns:

Resolved class or global object.

Return type:

object

mpylab.env.Measure.dump_pickle(obj, pfile, protocol=4)

Serialize an mpylab object to an open binary file.

Parameters:

  • obj – Object to serialize.

  • pfile – Writable binary file-like object.

  • protocol – Pickle protocol to use. The default is the stable protocol 4, which is smaller and faster for measurement data than the legacy protocol 2 while remaining supported by all mpylab Python versions.

The cyclic garbage collector is paused during serialization because large evaluated measurement objects otherwise trigger costly collections. Its previous state is always restored. Reference counting remains active.

mpylab.env.Measure.load_pickle_compat(fname)

Load current and legacy mpylab pickle files.

The compatibility path supports old pickle files that still reference the former mpy package name and Python 2 style byte strings. Gzip-compressed files may use .gz or the historical .zip suffix; the latter does not denote a standard ZIP archive.

Parameters:

fname (path-like) – Pickle or gzip-compressed pickle file to load.

Returns:

Deserialized object graph.

Return type:

object

mpylab.env.Measure.parse_quantity(s: str)

Parse a simple quantity string representation.

Parameters:

s (str) – Text in the form Quantity(UNIT, value).

Returns:

Unit name and numeric value.

Return type:

tuple of (str, float)