Module neuropype.engine.ports

Functionality for declaring input/output data ports in NeuroPype.

Ports are like Python properties, but add type checking and richer information, like help text and whether the port is editable (usable by GUIs and data-flow frameworks).

This module defines the following classes:

  • HasPorts: A base classes for classes that have ports.
  • Port: An input/output data port.
  • BoolPort: A port with value type boolean.
  • EnumPort: a port that only accepts value out of a pre-defined set.
  • FloatPort: a port with value type float.
  • IntPort: a port with value type int.
  • StringPort: a port with value type str.
  • ListPort: a port with value type list.
  • DictPort: a port with value type dict.
  • SubsetPort: a port whose value is a subset of some base set.
  • DataPort: a port for use with bulk data rather than config parameters.
  • RangePort: a port whose value represents an index range.

This module defines the following constants:

`IN` (int): Constant that defines the intended data flow direction of a       :class:<a title="neuropype.engine.ports.Port" href="#neuropype.engine.ports.Port">`Port`</a> as being input (data is primarily written to it).
`OUT` (int): Constant that defines the intended data flow direction of a         :class:<a title="neuropype.engine.ports.Port" href="#neuropype.engine.ports.Port">`Port`</a> as being output (data is primarily read from it).
`INOUT` (int): Constant that defines the data intended flow direction of a         :class:<a title="neuropype.engine.ports.Port" href="#neuropype.engine.ports.Port">`Port`</a> as both input and output (data is both written and read         from it).
`DIRECTIONS` (tuple): Tuple of (IN, OUT, INOUT).

Functions

def settings_stack()

Get the current settings stack for this thread.

Classes

class BoolPort (*args, **kw_args)

An input/output data port that only accepts Boolean values.

Create a new BoolPort. Args are as in Port, except that there is no ValueType.

Ancestors

Inherited members

class DataPort (*args, **kw_args)

An input/output port that is meant for bulk data as opposed to configuration parameters.

Create a new DataPort.

Arguments are as in Port, except that there is no default value. Also, the default settings differ from Port as follows: * mutating is True – if you know that your setter does not mutate the data, you are encouraged to set mutating to False in order to avoid unnecessary copying * bypassnone is True – if you need your setter to run when a None value is passed, set this to False (only applies if direction=INOUT) * setifequal is True * required is True * editable is False

Ancestors

Inherited members

class DictPort (*args, **kw_args)

An input/output data port that only accepts values that are dicts with string keys and values of some given type.

Create a new DictPort.

Arguments are as in Port, except that the second argument is the type of the dict values.

Ancestors

Inherited members

class EnumPort (*args, **kw_args)

An input/output data port that only accepts values from a restricted domain.

Create a new EnumPort.

Arguments

as in Port, except that the second argument is a sequence of possible values or None.

Ancestors

Inherited members

class FloatPort (*args, **kw_args)

An input/output data port that only accepts floating-point numbers.

Create a new FloatPort.

Arguments are as in Port, except that the second argument is a sequence of [min,max] or [min,lo,hi,max], or None (exceeding lo/hi generates one-time warnings instead of errors).

Ancestors

Inherited members

class HasPorts

Enables any Python class derived from it to declare input/output data ports.

Any class that wishes to have Ports declared must inherit from this class.

Subclasses

Static methods

def natural_order(names, editable=None, builtin=None)

Return the natural assignment order of the given port names.

The natural order will list the editable (i.e., 'parameter') ports first, also respecting their preferred update stage, and then the non-editable (i.e., 'data') ports, where ports marked 'builtin' come first, followed by the non-builtin ports. Generally within each category ports are assigned in their order of definition on the object.

Args

names
list of port names to order
editable
optionally restrict to editable ports (if True) or non-editable ports (if False); unrestricted if None (the default)
builtin
optionally restrict to builtin ports (if True) or non-builtin ports (if False); unrestricted if None (the default); note that only respect this flag for non-editable ports

Returns

given port names in their natural assignment order
 
def port(name)

Retrieve a port by name.

Args

name : str
Name of the port.

Returns

The named :class:Port instance or None if it can't be found.

def ports(**filters)

Retrieve an ordered dictionary of filtered ports.

Args

filters

Arbitrary keyword arguments. Used to filter (by attribute) the set of ports returned by the function. For example, to retrieve all input-only ports that are also editable::

>>> ports = MyClass.ports(direction=IN, editable=True)

In addition to :attr:IN, :attr:OUT and :attr:INOUT the direction filter also supports the following string-based syntax:

  • 'IN': Retrieve all input-only ports. Equivalent to :attr:IN.
  • 'OUT': Retrieve all output-only ports. Equivalent to :attr:OUT.
  • 'INOUT': Retrieve all input/output ports. Equivalent to :attr:INOUT.
  • 'IN*': Retrieve all input-only and input/output ports.
  • '*OUT': Retrieve all output-only and input/output ports.
  • '*': Retrieve all ports. Equivalent to omitting the direction filter.

If no filters are specified, all ports declared by the class are retrieved (including those declared by its parent classes).

Returns

:class:collections.collections.OrderedDict: An ordered dictionary of :class:Port instances.

Methods

def on_preinit(self)

Optional hook that gets called at a point when default values are already assigned to the ._portname fields, but the setters have not yet been run. Can be used to initialize data that is accessed by setters but which depends on default values of ports.

def resolve_variadics(self, argdict)

Rewrite a given dictionary of arguments such that any variadic forms (e.g., 'inN': ['a','b', 'c']) are replaced by their corresponding indexed forms (e.g., 'in0': 'a', 'in1': 'b', 'in2': 'c'). Performs the necessary checks to ensure that the required ports actually exist.

Args

argdict
the dictionary to rewrite in-place
class IntPort (*args, **kw_args)

An input/output data port that only accepts integer numbers.

Create a new FloatPort.

Arguments are as in Port, except that the second argument is a sequence of [min,max] or [min,lo,hi,max], or None (exceeding lo/hi generates one-time warnings instead of errors). Values are automatically being coerced into integers.

Ancestors

Inherited members

class Keep
class ListPort (*args, **kw_args)

An input/output data port that only accepts values that are lists of some type.

Create a new ListPort.

Arguments are as in Port, except that the second argument is the type of the list elements.

Ancestors

Inherited members

class MetaHasPorts (class_name, bases, attrs)

Meta-class of HasPorts.

This class ensures that ports are stored in the .ports attribute of the class where they're defined, that each port knows the name under which it was declared, and that . variables are pre-initialized in the class.

Ancestors

  • builtins.type
class Port (*args, **kw_args)

An input/output data port.

A port is essentially a "fancy" property. In addition to a setter and getter, a port has a type, help text, and flags that affect how a flow graph or GUI makes use of it.

Ports are used in NeuroPype to represent the input/output ports of a given processing node (including the data inlet and outlets, as well as any sort of configuration properties).

Create a new port.

Args

default
the default value of the port (default: None)
value_type
the value type that this port holds (default: object)
help
help text (default: '')
direction
intended data-flow direction going through this port (can be IN, OUT, or INOUT) (default: INOUT)

Keyword args: category: the category und which this port shall be displayed in GUIs (default: '') debug_output: whether to print debug output when a value is being assigned to this port (default: False) expert: whether this port is for use by experts (a GUI framework might hide such ports in non-expert mode) (default: False) editable: whether the value of this port can be edited in a GUI (i.e., acts as a configurable property in contrast to non-editable ports, which are taken as "data" ports, like the image in an image processing function) (default: True) required: whether a value is required for this port (i.e., whether the object that declares this port requires that a value be assigned to the port); most of the time this is True if editable is False (default: False) builtin: whether this port is marked as "built-in" in the class where it's defined; typically this is only used for framework- level ports, such as the special 'update' port of the Node class (default: False) autocast: whether to automatically cast values into value_type upon assignment (default: False) canbenone: whether values assigned to this port can be None (default: True) bypassnone: if True, None values will bypass custom setters and will be handled by the default setter (default: False) variable_name: optionally the instance variable name that i/o through this port writes to (default: _) verbose_name: optionally the verbose (human-friendly) name of this port (default: derived from port name) mutating: whether the setter function mutates the passed-in value, or somehow passes out a data structure that references parts or all of the passed-in value (in which case it may be mutated by something else in the program); if True, Port will by default deepcopy it before assignment (default: False) migrate: optionally a dictionary of migration rules for deprecated values (dictionary from old to new values) setifequal: whether the setter function should also be called if the value did not change (default: False) safe: whether allowing users to enter arbitrary values to this port is safe or can be used for privilege escalation, etc. (e.g., in cloud environments). (default: True) update_stage: stage at which to update (assign) the given port; can be 'early', 'main', 'late' (default: 'main'); this value is used by systems that control the order in which ports get assigned on an object (can be used to ensure that certain ports get set before or after others); this feature should not be used lightly, and should be treated as a last-resort fix fget: optionally an overridden getter function fset: optionally an overridden setter function deprecated: optionally, flag this port as deprecated (default: False); deprecated ports can still hold a value but will trigger a warning. can also be a string, in which case it is taken as the deprecation message to display. If set, expert will default to True as well, unless explicitly set to False.

Notes

  • access to the object owning one or more ports is serialized with a per-object mutex for fine-grained locking

Subclasses

Instance variables

var port_type

The type of the port.

Methods

def creation_counter(self)

Retrieve the port's creation counter. The first declared port created has a counter value of 1, the next port has 2, and so on.

def getter(self, fget)

Returns a decorator that can be used to turn a function into a getter for this port. This is the same as Python's property.getter.

Example: @myport.getter def myport(self):

# _myport is the place where one would typically store the data
# accessed by port named myport #
return self._myport
def setter(self, fset)

Returns a decorator that can be used to turn a function into a setter for this port. This is the same as Python's property.setter.

Example: @myport.setter def myport(self, value):

# _myport is the place where one would typically store the data
# accessed by port named myport #
self._myport = value
def validate(self, value)

Validate the given value. Throws ValidationError on failure. Automatically called when a value is assigned to the port.

class RangePort (*args, **kw_args)

A port that can accept an index range in various forms, e.g., list of indices, list of values, slice. Currently the range port does no parsing or validation on its own; it is purely declarative (this will change).

Create a new StringPort.

Args

is_filename
whether this port accepts file name (if this is set, then the

rest as in Port, except that there is no value_type.

Ancestors

Inherited members

class StringPort (*args, **kw_args)

An input/output data port that only accepts strings.

Create a new StringPort.

Args

is_filename
whether this port accepts file name (if this is set, then the

rest as in Port, except that there is no value_type.

Ancestors

Inherited members

class SubsetPort (*args, **kw_args)

An input/output data port that only accepts values that are subsets of some base set, with values of a given type.

Create a new SubsetPort.

Arguments are as in Port, except that the second argument is the base set of which subsets are accepted by the port.

Ancestors

Inherited members