plesty.lib.traffic

Abstract traffic manager base class and common interface for Plesty devices.

Submodules

Classes

TrafficManager

Abstract base class for managing communication with device resources.

Functions

handle_error(→ None)

Handle a caught error by logging and optionally re-raising it.

Package Contents

plesty.lib.traffic.handle_error(err: Any, error_msg: str | None = None, silent: bool = False, func_name: str = 'Unknown Function') → None

Handle a caught error by logging and optionally re-raising it.

Parameters:

  • err (Any)

  • error_msg (str | None)

  • silent (bool)

  • func_name (str)

Return type:

None

class plesty.lib.traffic.TrafficManager(address: str, timeout: int = 5)

Bases: abc.ABC

Abstract base class for managing communication with device resources.

Defines common interface for opening, closing, and sending commands. The private methods (_open, _send_command, _close) are implemented by subclasses while the public methods (open, send_command, close) provide consistent resource management and error handling.

Initialize the TrafficManager with the given address and timeout.

Parameters:

  • address (str) – The address of the resource.

  • timeout (int, optional) – The timeout for operations in seconds. Defaults to 5.

_resource_in_use: dict[str, Any]
address
timeout = 5
inst = None
command_log_level: int = 20
timeout_cap: int | None = None
property is_open: bool

Return True if the connection is currently open.

Return type:

bool

abstractmethod _open(*args, **kwargs)

Open the connection to the resource.

This method should be implemented by subclasses to handle the specific details of opening the connection.

Parameters:

  • args – Positional arguments for the specific implementation.

  • kwargs – Keyword arguments for the specific implementation.

open(*args, **kwargs) → bool

Open the connection, delegating to _open and registering the resource.

Return type:

bool

_explain_open_error(exc: BaseException) → str | None

Return guidance for an open failure the user cannot read off exc.

The base class knows nothing about transports, so it returns None and open() reports the bare failure. A subclass whose backend reports the wrong port and a held port with the same exception type overrides this to say which one it was and what to do about it; the text is appended to the raised message, not buried in the cause chain.

Parameters:

exc (BaseException) – The exception _open() raised.

Return type:

str | None

abstractmethod _send_command(command: str, timeout=None, *args, **kwargs) → Any

Send a command to the resource and return the response.

Parameters:

  • command (str) – The command to send.

  • timeout – Timeout in seconds; defaults to the instance’s timeout.

  • *args – Additional positional arguments for subclass implementations.

  • **kwargs – Additional keyword arguments for subclass implementations.

Returns:

The response from the resource, or False if the command failed.

Return type:

Any

orphan(command: str) → bool

Transmit command and never read what comes back.

Not a write. A write is a command that sets something, and plenty of instruments acknowledge one — those replies are read, and must be, or the acknowledgement becomes the stale answer handed to the next command. This reads nothing whatever the command means, which is the one thing send_command() cannot express and exactly the condition the buffer-drain gate has to create: a reply left in the instrument’s buffer, as a timed-out query leaves one.

Deliberately narrow. Racing a timeout is the alternative and it is not a lever on every driver — NI-VISA does not enforce short timeouts on some instruments, so the gate silently tested nothing there.

Returns:

True when the command was transmitted, False when this transport cannot transmit without reading — in which case the drain gate skips and says so rather than reporting a pass.

Parameters:

command (str)

Return type:

bool

send_command(command: str, timeout=None, *args, **kwargs) → Any

Send a command, delegating to _send_command with error handling.

Parameters:

command (str)

Return type:

Any

abstractmethod _close()

Close the connection to the resource.

Subclasses must implement this to handle the specific close logic.

close() → bool

Close the connection, unregister the resource, and return success status.

The resource is unregistered even when _close fails. Otherwise a transport that throws on the way out — a clear refused by an unresponsive instrument, a close on a dead handle — leaves the address registered for the life of the process, and every later open is rejected with “already in use” against a resource nothing is holding.

Return type:

bool

__enter__()

Open the resource connection when entering the context manager.

__exit__(exc_type, exc_val, exc_tb)

Close the resource connection when exiting the context manager.