iblutil.io.net.base

Functions

`external_ip`	Fetch WAN IP address.
`hostname2ip`	Resolve hostname to IP address.
`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.
`Service`	An abstract base class for auxiliary experiment services.

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=10001, 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)[source]

Bases: IntEnum

A set of standard experiment messages for communicating between rigs.

EXPINIT = 10: Experiment has begun.

EXPSTART = 20: Experiment has stopped.

EXPEND = 30: Experiment cleanup begun.

EXPCLEANUP = 40: Experiment interrupted.

EXPINTERRUPT = 50: Experiment status.

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

EXPINFO = 2: Alyx token.

ALYX = 3

static validate(event)[source]

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

Parameters:

event (str, int, ExpMessage) – An event message to validate.

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.

Examples

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

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

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

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 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

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)[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.

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 = await com.on_event('EXPSTART')

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

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