cleave.core package

Subpackages

• cleave.core.client package
  • Submodules
  • cleave.core.client.actuator module
  • cleave.core.client.control module
  • cleave.core.client.physicalsim module
  • cleave.core.client.plant module
  • cleave.core.client.sensor module
  • cleave.core.client.statebase module
  • cleave.core.client.timing module
• cleave.core.network package
  • Submodules
  • cleave.core.network.backend module
  • cleave.core.network.client module
  • cleave.core.network.protocol module

Submodules

cleave.core.config module

exception cleave.core.config.ConfigError

Bases: Exception

class cleave.core.config.Config(config: Mapping[str, Any], defaults: Mapping[str, Any] = {})

Bases: object

Helper class to hold configuration variables with optional default values.

get_parameter(k: str) → Any

Looks up and returns a named parameter from the configuration. If the parameter is not defined and not required, this will returned its default value instead.

Parameters

k – Parameter name.

Returns

The parameter value if defined. If the parameter is not defined but optional, this value will correspond to the parameter’s default value.

Return type

Any

Raises

ConfigError – If the parameter is required and has not been defined.

class cleave.core.config.ConfigFile(config_path: str, cmd_line_overrides: Mapping[str, Any] = {}, defaults: Mapping[str, Any] = {})

Bases: Config

Helper class to wrap access to a config.py file containing configuration variables for the program.

Parameters

• config_path – Path to the config script.

• cmd_line_overrides – Overrides for config variables obtained from the command line. Config parameters defined here will always override the config file.

• defaults – Mapping of fallback values for missing parameters.

cleave.core.logging module

class cleave.core.logging.Logger(namespace: ~typing.Optional[str] = None, source: ~typing.Optional[object] = None, observer: ~typing.Optional[<InterfaceClass twisted.logger._interfaces.ILogObserver>] = None)

Bases: object

A L{Logger} emits log messages to an observer. You should instantiate it as a class or module attribute, as documented in L{this module’s documentation <twisted.logger>}.

@ivar namespace: the namespace for this logger @ivar source: The object which is emitting events via this logger @ivar observer: The observer that this logger will send events to.

@param namespace: The namespace for this logger. Uses a dotted

notation, as used by python modules. If not L{None}, then the name of the module of the caller is used.

@param source: The object which is emitting events via this

logger; this is automatically set on instances of a class if this L{Logger} is an attribute of that class.

@param observer: The observer that this logger will send events to.

If L{None}, use the L{global log publisher <globalLogPublisher>}.

emit(level: LogLevel, format: Optional[str] = None, **kwargs: object) → None

Emit a log event to all log observers at the given level.

@param level: a L{LogLevel} @param format: a message format using new-style (PEP 3101)

formatting. The logging event (which is a L{dict}) is used to render this format string.

@param kwargs: additional key/value pairs to include in the event.

Note that values which are later mutated may result in non-deterministic behavior from observers that schedule work for later execution.

failure(format: str, failure: ~typing.Optional[~twisted.python.failure.Failure] = None, level: ~twisted.logger._levels.LogLevel = <LogLevel=critical>, **kwargs: object) → None

Log a failure and emit a traceback.

For example:

try:
    frob(knob)
except Exception:
    log.failure("While frobbing {knob}", knob=knob)

or:

d = deferredFrob(knob)
d.addErrback(lambda f: log.failure("While frobbing {knob}",
                                   f, knob=knob))

This method is generally meant to capture unexpected exceptions in code; an exception that is caught and handled somehow should be logged, if appropriate, via L{Logger.error} instead. If some unknown exception occurs and your code doesn’t know how to handle it, as in the above example, then this method provides a means to describe the failure in nerd-speak. This is done at L{LogLevel.critical} by default, since no corrective guidance can be offered to an user/administrator, and the impact of the condition is unknown.

@param format: a message format using new-style (PEP 3101) formatting.

The logging event (which is a L{dict}) is used to render this format string.

@param failure: a L{Failure} to log. If L{None}, a L{Failure} is

created from the exception in flight.

@param level: a L{LogLevel} to use. @param kwargs: additional key/value pairs to include in the event.

Note that values which are later mutated may result in non-deterministic behavior from observers that schedule work for later execution.

debug(format: Optional[str] = None, **kwargs: object) → None

Emit a log event at log level L{LogLevel.debug}.

@param format: a message format using new-style (PEP 3101) formatting.

The logging event (which is a L{dict}) is used to render this format string.

@param kwargs: additional key/value pairs to include in the event.

Note that values which are later mutated may result in non-deterministic behavior from observers that schedule work for later execution.

info(format: Optional[str] = None, **kwargs: object) → None

Emit a log event at log level L{LogLevel.info}.

@param format: a message format using new-style (PEP 3101) formatting.

The logging event (which is a L{dict}) is used to render this format string.

@param kwargs: additional key/value pairs to include in the event.

Note that values which are later mutated may result in non-deterministic behavior from observers that schedule work for later execution.

warn(format: Optional[str] = None, **kwargs: object) → None

Emit a log event at log level L{LogLevel.warn}.

@param format: a message format using new-style (PEP 3101) formatting.

The logging event (which is a L{dict}) is used to render this format string.

@param kwargs: additional key/value pairs to include in the event.

Note that values which are later mutated may result in non-deterministic behavior from observers that schedule work for later execution.

error(format: Optional[str] = None, **kwargs: object) → None

Emit a log event at log level L{LogLevel.error}.

@param format: a message format using new-style (PEP 3101) formatting.

The logging event (which is a L{dict}) is used to render this format string.

@param kwargs: additional key/value pairs to include in the event.

Note that values which are later mutated may result in non-deterministic behavior from observers that schedule work for later execution.

critical(format: Optional[str] = None, **kwargs: object) → None

Emit a log event at log level L{LogLevel.critical}.

@param format: a message format using new-style (PEP 3101) formatting.

The logging event (which is a L{dict}) is used to render this format string.

@param kwargs: additional key/value pairs to include in the event.

Note that values which are later mutated may result in non-deterministic behavior from observers that schedule work for later execution.

class cleave.core.logging.LogLevel

Bases: Names

Constants describing log levels.

@cvar debug: Debugging events: Information of use to a developer of the

software, not generally of interest to someone running the software unless they are attempting to diagnose a software issue.

@cvar info: Informational events: Routine information about the status of

an application, such as incoming connections, startup of a subsystem, etc.

@cvar warn: Warning events: Events that may require greater attention than

informational events but are not a systemic failure condition, such as authorization failures, bad data from a network client, etc. Such events are of potential interest to system administrators, and should ideally be phrased in such a way, or documented, so as to indicate an action that an administrator might take to mitigate the warning.

@cvar error: Error conditions: Events indicating a systemic failure, such

as programming errors in the form of unhandled exceptions, loss of connectivity to an external system without which no useful work can proceed, such as a database or API endpoint, or resource exhaustion. Similarly to warnings, errors that are related to operational parameters may be actionable to system administrators and should provide references to resources which an administrator might use to resolve them.

@cvar critical: Critical failures: Errors indicating systemic failure (ie.

service outage), data corruption, imminent data loss, etc. which must be handled immediately. This includes errors unanticipated by the software, such as unhandled exceptions, wherein the cause and consequences are unknown.

Classes representing constants containers are not intended to be instantiated.

The class object itself is used directly.

classmethod levelWithName(name: str) → NamedConstant

Get the log level with the given name.

@param name: The name of a log level.

@return: The L{LogLevel} with the specified C{name}.

@raise InvalidLogLevelError: if the C{name} does not name a valid log

level.

cleave.core.recordable module

class cleave.core.recordable.Recorder(recordable: Recordable)

Bases: ABC

Interface for Recorder objects. Recorder and Recordable objects together implement the Observable pattern for text records of the plant state.

abstract notify(latest_record: NamedTuple)

Notify this recorder of the latest record generated by a recordable it is monitoring.

initialize()

Called on plant startup.

shutdown()

Called on plant shutdown.

flush()

Mainly intended for IO-backed recorders, to force flushing of any potentially memory-stored data.

class cleave.core.recordable.Recordable

Bases: ABC

Interface for Recordable objects. Recorder and Recordable objects together implement the Observable pattern for text records of the plant state.

class cleave.core.recordable.NamedRecordable(name: str, record_fields: Sequence[str], opt_record_fields: Mapping[str, Any] = {})

Bases: Recordable

A base implementation of a named recordable object.

class cleave.core.recordable.CSVRecorder(recordable: Recordable, output_dir: Path, metric_name: str, chunk_size: int = 1000)

Bases: Recorder

Implementation of a CSV-file backed Recorder.

initialize() → None

Called on plant startup.

flush() → None

Flushes the internal record buffer to the backing CSV file.

notify(latest_record: NamedTuple) → None

Notify this recorder of the latest record generated by a recordable it is monitoring.

shutdown() → None

Called on plant shutdown.

cleave.core.util module

class cleave.core.util.SingleElementQ

Bases: object

Utility class to hold a single variable in a thread-safe manner. Subsequent calls to put() without calling pop() will overwrite the stored variable. Conversely, pop() always returns the LATEST value for the stored variable.

put(value: Any) → None

Thread-safely store a value. Overwrites any previously stored value.

Parameters

value – The value to store in this container.

pop(timeout: Optional[float] = None) → Any

Pop the latest value for the stored variable. If timeout is None (the default), block until a value is available. Otherwise, block for up to timeout seconds, after which an Empty exception is raised if no value was made available within that time.

Parameters

timeout – Number of seconds to block for. If None, blocks indefinitely.

Returns

The stored value.

Return type

Any

Raises

Empty – If timeout is not None and no value is available when it runs out.

pop_nowait() → Any

Pops the latest value for the stored variable without waiting. If no value has been set yet, raises an Empty exception.

Returns

Latest value for the stored variable.

Return type

Any

Raises

Empty – If no value for the stored variable exists.