vidhubcontrol.common

class vidhubcontrol.common.ConnectionManager(*args, **kwargs)

Bases: pydispatch.dispatch.Dispatcher

A manager for tracking and waiting for connection states

A asyncio.Condition is used to to notify any waiting tasks of changes to state. This requires the underlying lock to be acquired before calling any of the waiter or setter methods and released afterwards.

This class supports the asynchronous context manager protocol for use in async with statements.

Events

state_changed(self: ConnectionManager, state: ConnectionState)

Emitted when the value of state has changed

async acquire()

Acquire the lock

This method blocks until the lock is unlocked, then sets it to locked and returns True.

failure_exception: Optional[Exception]

The Exception raised if an error occured

failure_reason: Optional[str]

A message describing errors (if encountered)

locked() → bool

True if the lock is acquired

release()

Release the lock

Raises

RuntimeError – if called on an unlocked lock

async set_failure(reason: Any, exc: Optional[Exception] = None, state: Optional[Union[vidhubcontrol.common.ConnectionState, str]] = ConnectionState.None)

Set state to indicate a failure

Parameters

• reason – A description of the failure

• exc – The Exception that caused the failure (if available)

• state – The new state to set. Must include ConnectionState.failure

Raises

RuntimeError – If the lock is not acquired before calling this method

async set_state(state: Union[vidhubcontrol.common.ConnectionState, str])

Set the state to the given value

The state argument may be either a ConnectionState member or a string. (see ConnectionState.from_str())

Raises

RuntimeError – If the lock is not acquired before calling this method

property state: vidhubcontrol.common.ConnectionState

The current state

async syncronize(other: vidhubcontrol.common.ConnectionManager)

Copy the state and failure values of another ConnectionManager

Note

The lock must not be acquired before calling this method.

async wait(timeout: Optional[float] = None) → vidhubcontrol.common.ConnectionState

Block until the next time state changes and return the value

Parameters

timeout – If given, the number of seconds to wait. Otherwise, this will wait indefinitely

Raises

• asyncio.TimeoutError – If timeout is given and no state changes occured

• RuntimeError – If the lock is not acquired before calling this method

async wait_for(state: Union[vidhubcontrol.common.ConnectionState, str], timeout: Optional[float] = None) → vidhubcontrol.common.ConnectionState

Wait for a specific state

The state argument may be a ConnectionState member or string as described in ConnectionState.from_str().

If the given state is compound or the state is set as compound, this will wait until all members from the state argument are contained within the state value.

Parameters

• state – The state to wait for

• timeout – If given, the number of seconds to wait. Otherwise, this will wait indefinitely

Raises

• asyncio.TimeoutError – If timeout is given and no matching state changes were found

• RuntimeError – If the lock is not acquired before calling this method

async wait_for_disconnected(timeout: Optional[float] = None) → vidhubcontrol.common.ConnectionState

Wait for ConnectionState.not_connected

Parameters

timeout – If given, the number of seconds to wait. Otherwise, this will wait indefinitely

Raises

• asyncio.TimeoutError – If timeout is given and no matching state changes were found

• RuntimeError – If the lock is not acquired before calling this method

async wait_for_established(timeout: Optional[float] = None) → vidhubcontrol.common.ConnectionState

Wait for either a success (ConnectionState.connected) or failure (ConnectionState.failure)

Parameters

timeout – If given, the number of seconds to wait. Otherwise, this will wait indefinitely

Raises

• asyncio.TimeoutError – If timeout is given and no matching state changes were found

• RuntimeError – If the lock is not acquired before calling this method

class vidhubcontrol.common.ConnectionState(value)

Bases: enum.IntFlag

Enum to describe various connection states

Members may be combined using bitwise operators (&, |, ^, ~)

connected = 8

Indicates the connection is active

connecting = 2

Indicates an attempt to connect is being made

disconnecting = 4

Indicates the connection is being closed

failure = 16

Indicates an error occured

classmethod from_str(s: str) → vidhubcontrol.common.ConnectionState

Create a ConnectionState member by name(s)

Combined states can be created by separating their names with a “|”

>>> from vidhubcontrol.common import ConnectionState
>>> ConnectionState.connected | ConnectionState.not_connected
<ConnectionState.connected|not_connected: 9>
>>> ConnectionState.disconnecting | ConnectionState.failure
<ConnectionState.failure|disconnecting: 20>
>>> # This combination is already defined as "waiting"
>>> ConnectionState.connecting | ConnectionState.disconnecting
<ConnectionState.waiting: 6>

property is_compound: bool

This will evaluate to True for states combined using bitwise operators

property is_connected: bool

Convenience property evaluating as True if self == ConnectionState.connected

not_connected = 1

Indicates there is no connection and no connection attempts are being made

waiting = 6

Indicates the connection is either connecting or disconnecting

class vidhubcontrol.common.SyncronizedConnectionManager(*args, **kwargs)

Bases: vidhubcontrol.common.ConnectionManager

A connection manager that syncronizes itself with another

property other: Optional[vidhubcontrol.common.ConnectionManager]

The manager currently being syncronized to

async set_other(other: Optional[vidhubcontrol.common.ConnectionManager])

Set the manager to syncronize with

This binds to the state_changed() event of other and calls the syncronize() method whenever the state of the other manager changes.

If None is given, state is set to not_connected

Note

The lock must not be acquired before calling this method