iblutil.io.net.base

Functions

`external_ip`	Fetch WAN IP address.
`hostname2ip`	Resolve hostname to IP address.
`is_success`	Check if future successfully resolved.
`is_valid_ip`	Test whether IP address is valid.
`validate_uri`	Ensure URI is complete and correct.

Classes

`Communicator`	A base class for communicating between experimental rigs.
`ExpMessage`	A set of standard experiment messages for communicating between rigs.
`ExpStatus`	A set of standard statuses for communicating between rigs.
`Service`	An abstract base class for auxiliary experiment services.

is_success(future: Future) → bool[source]: Check if future successfully resolved.

external_ip()[source]

Fetch WAN IP address.

NB: Requires internet.

Returns:: The computer’s default WAN IP address.
Return type:: ipaddress.IPv4Address, ipaddress.IPv6Address

is_valid_ip(ip_address) → bool[source]

Test whether IP address is valid.

Parameters:: ip_address (str) – An IP address to validate.
Returns:: True is IP address is valid.
Return type:: bool

hostname2ip(hostname=None)[source]

Resolve hostname to IP address.

Parameters:: hostname (str, optional) – The hostname to resolve. If None, resolved this computer’s hostname.
Returns:: The resolved IP address.
Return type:: ipaddress.IPv4Address, ipaddress.IPv6Address
Raises:: ValueError – Failed to resolve IP for hostname.

validate_uri(uri, resolve_host=True, default_port=11001, default_proc='udp')[source]

Ensure URI is complete and correct.

Parameters:

uri (str, ipaddress.IPv4Address, ipaddress.IPv6Address) – A full URI, hostname or hostname and port.
resolve_host (bool) – If the URI is not an IP address, attempt to resolve hostname to IP.
default_port (int, str) – If the port is absent from the URI, append this one.
default_proc (str) – If the URI scheme is missing, prepend this one.

Returns:

The complete URI.

Return type:

str

Raises:

TypeError – URI type not supported.
ValueError – Failed to resolve host name to IP address. URI host contains invalid characters (expects only alphanumeric + hyphen). Port number not within range (must be > 1, <= 65535).

class ExpMessage(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntFlag

A set of standard experiment messages for communicating between rigs.

EXPINIT = 1: Experiment has begun.

EXPSTART = 2: Experiment has stopped.

EXPEND = 4: Experiment cleanup begun.

EXPCLEANUP = 8: Experiment interrupted.

EXPINTERRUPT = 16: Experiment status.

EXPSTATUS = 32: Experiment info, including task protocol start and end.

EXPINFO = 64: Alyx token.

ALYX = 128

classmethod any() → ExpMessage[source]

Return enumeration comprising all possible messages.

NB: This doesn’t include the null ExpMessage (0), used to indicate API errors.

static validate(event, allow_bitwise=True)[source]

Validate an event message, returning a corresponding enumeration if valid and raising an exception if not.

Parameters:

event (str, int, ExpMessage) – An event message to validate.
allow_bitwise (bool) – If false, raise if event is the result of a bitwise operation.

Returns:

The corresponding event enumeration.

Return type:

ExpMessage

Raises:

TypeError – event is neither a string, integer nor enumeration.
ValueError – event does not correspond to any ExpMessage enumeration, neither in its integer form nor its string name, or allow_bitwise is false and value is combination of events.

Examples

>>> ExpMessage.validate('expstart')
ExpMessage.EXPSTART

>>> ExpMessage.validate(10)
ExpMessage.EXPINIT

>>> ExpMessage.validate(ExpMessage.EXPEND)
ExpMessage.EXPEND

class ExpStatus(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntEnum

A set of standard statuses for communicating between rigs.

CONNECTED = 0: Service is initialized.

INITIALIZED = 10: Service is running.

RUNNING = 20: Experiment has stopped.

STOPPED = 30

class Service[source]

Bases: ABC

An abstract base class for auxiliary experiment services.

abstract init(data=None)[source]

Initialize an experiment.

This is intended to specify the expected message signature. The subclassed method should serialize the returned values and pass them to the transport layer.

Parameters:

data (any) – Optional extra data to send to the remote server.

Returns:

ExpMessage.EXPINIT – The EXPINIT event.
any, None – Optional extra data.

abstract start(exp_ref, data=None)[source]

Start an experiment.

This is intended to specify the expected message signature. The subclassed method should serialize the returned values and pass them to the transport layer.

Parameters:

exp_ref (str) – An experiment reference string in the form yyyy-mm-dd_n_subject.
data (any) – Optional extra data to send to the remote server.

Returns:

ExpMessage.EXPSTART – The EXPSTART event.
str – The experiment reference string.
any, None – Optional extra data.

abstract stop(data=None, immediately=False)[source]

Stop an experiment.

This is intended to specify the expected message signature. The subclassed method should serialize the returned values and pass them to the transport layer.

Parameters:

data (any) – Optional extra data to send to the remote server.
immediately (bool) – If True, an EXPINTERRUPT message is returned.

Returns:

ExpMessage.EXPINTERRUPT, ExpMessage.EXPEND – The EXPEND event, or EXPINTERRUPT if immediately is True.
any, None – Optional extra data.

abstract status(status)[source]

Report experiment status.

NB: This is intended to be lightweight. For more detail and custom data use the info method.

This is intended to specify the expected message signature. The subclassed method should serialize the returned values and pass them to the transport layer.

Parameters:

status (ExpStatus) – The experiment status enumeration.

Returns:

ExpMessage.EXPSTATUS – The EXPSTATUS event.
ExpStatus – The validated experiment status.

abstract info(status, data=None)[source]

Report experiment information.

This is intended to specify the expected message signature. The subclassed method should serialize the returned values and pass them to the transport layer.

Parameters:

status (ExpStatus) – The experiment status enumeration.
data (any) – Optional extra data to send to the remote server.

Returns:

ExpMessage.EXPINFO – The EXPINFO event.
ExpStatus – The validated experiment status.
any, None – Optional extra data.

abstract cleanup(data=None)[source]

Clean up an experiment.

This is intended to specify the expected message signature. The subclassed method should serialize the returned values and pass them to the transport layer.

Parameters:

data (any) – Optional extra data to send to the remote server.

Returns:

ExpMessage.EXPCLEANUP – The EXPCLEANUP event.
any, None – Optional extra data.

abstract alyx(alyx)[source]

Request/send Alyx token.

This is intended to specify the expected message signature. The subclassed method should serialize the returned values and pass them to the transport layer.

Parameters:

alyx (one.webclient.AlyxClient) – Optional instance of Alyx to send.

Returns:

ExpMessage.ALYX – The ALYX event.
str – The Alyx database URL.
dict – The Alyx token in the form {user: token}.

name

class Communicator(server_uri, name=None, logger=None)[source]

Bases: Service

A base class for communicating between experimental rigs.

name

An arbitrary label for the remote host

Type:: str

server_uri

The full URI of the remote device, e.g. udp://192.168.0.1:1001

Type:: str

server_uri

name

logger

assign_callback(event, callback)[source]

Assign a callback to be called when an event occurs.

NB: Unlike with futures, an assigned callback may be triggered multiple times, whereas coroutines may only be set once after which they are cleared.

Parameters:

event (str, int, iblutil.io.net.base.ExpMessage) – The event for which the callback is registered.
callback (function, asyncio.Future) – A function or Future to trigger when an event occurs.

See also

EchoProtocol.receive: The method that processes the callbacks upon receiving a message.

clear_callbacks(event, callback=None, cancel_futures=True)[source]

For a given event, remove the provided callback, or all callbacks if none were provided.

Parameters:

event (str, int, iblutil.io.net.base.ExpMessage) – The event for which the callback was registered.
callback (function, asyncio.Future) – The callback or future to remove.
cancel_futures (bool) – If True and callback is a Future, cancel before removing.

Returns:

The number of callbacks removed.

Return type:

int

async on_event(event)[source]

Await an event from the remote host.

Parameters:: event (str, int, iblutil.io.net.base.ExpMessage) – The event to wait on.
Returns:: The response data returned by the remote host.
Return type:: any

Examples

>>> data, addr = await com.on_event('EXPSTART')

>>> event = await asyncio.create_task(com.on_event('EXPSTART'))
>>> ...
>>> data = await event

Await more than one event

>>> data, addr, event = await com.on_event(ExpMessage.EXPEND | ExpMessage.EXPINTERRUPT)

property port: int

the remote port

Type:: int

property hostname: str

the remote hostname or IP address

Type:: str

property protocol: str

the protocol scheme, e.g. udp, ws

Type:: str

abstract property is_connected: bool

True if the remote device is connected

Type:: bool

abstract send(data, addr=None)[source]: Serialize and pass data to the transport layer

static encode(data) → bytes[source]

Serialize data for transmission.

None-string or -bytes objects are encoded as JSON before converting to bytes.

Parameters:: data (any) – The data to serialize.
Returns:: The encoded data.
Return type:: bytes

static decode(data: bytes)[source]

De-serialize and parse bytes data.

This function attempts to decode the data as a JSON object. On failing that, returns a string.

Parameters:: data (bytes) – The data to de-serialize.
Returns:: Deserialized data.
Return type:: any

close()[source]: De-register all callbacks and cancel futures