ayon_api.events module

class Event(topic: 'str', data: 'dict[str, Any]' = <factory>, id: 'str | None' = None, sender: 'str | None' = None, event_hash: 'str | None' = None, project_name: 'str | None' = None, dependencies: 'list[str] | None' = None, description: 'str | None' = None, summary: 'str | None' = None, payload: 'dict[str, Any] | None' = None, status: 'str | None' = None, store: 'bool | None' = None)

Bases: object

data: dict[str, Any]

dependencies: list[str] | None = None

description: str | None = None

event_hash: str | None = None

classmethod from_ws_message(data: dict[str, Any]) → Event | None

get(key, default=None) → Any

id: str | None = None

payload: dict[str, Any] | None = None

project_name: str | None = None

sender: str | None = None

status: str | None = None

store: bool | None = None

summary: str | None = None

topic: str

class EventCallback(topic: str, func: Callable, order: int | None = None)

Bases: object

Callback registered to a topic.

The callback function is registered to a topic. Topic is a string which may contain ‘*’ that will be handled as “any characters”.

# Examples: - “entity.folder.attr_changed” - Callback will be triggered if the event

topic is exactly “entity.folder.attr_changed”.

• “entity.*” - Callback will be triggered an event topic starts with

  “entity.” so “entity.folder.created” and “entity.version.created” will trigger the callback.

• “*” Callback will listen to all events.

Callback can be function or method. In both cases it should expect one or none arguments. When 1 argument is expected then the processed ‘Event’ object is passed in.

The callbacks are validated against their reference counter, that is

achieved using ‘weakref’ module. That means that the callback must be stored in memory somewhere. e.g. lambda functions are not supported as valid callback.

You can use ‘weakref_partial’ functions. In that case is partial object

stored in the callback object and reference counter is checked for the wrapped function.

Parameters:

• topic (str) – Topic which will be listened.

• func (Callable) – Callback to a topic.

• order (int | None) – Order of callback. Lower number means higher priority.

Raises:

TypeError – When passed function is not a callable object.

default_order: int = 100

deregister() → None

Calling this function will cause that callback will be removed.

property enabled: bool

Is callback enabled.

Returns:

Is callback enabled.

Return type:

bool

get_order() → int

Get callback order.

Returns:

Callback order.

Return type:

int

property is_ref_valid: bool

Returns: bool: Is reference to callback valid.

property log: Logger

property order: int

Get callback order.

Returns:

Callback order.

Return type:

int

process_event(event: Event) → None

Process event.

Parameters:

event (Event) – Event that was triggered.

set_enabled(enabled: bool) → None

Change if callback is enabled.

Parameters:

enabled (bool) – Change enabled state of the callback.

set_order(order: int) → None

Change callback order.

Parameters:

order (int) – Order of callback. Lower number means higher priority.

property topic: str

topic_matches(topic: str) → bool

Check if event topic matches callback’s topic.

Parameters:

topic (str) – Topic name.

Returns:

Topic matches callback’s topic.

Return type:

bool

validate_ref() → None

Validate if reference to callback is valid.

Deprecated:

Reference is always live checkd with ‘is_ref_valid’.

class EventHub(connection: ServerAPI)

Bases: object

Receive AYON server events via websocket and trigger callbacks.

Websocket connection is handled in a daemon thread, so it never blocks

the caller (e.g. DCC main thread) nor the process exit.

Warning

Callbacks are triggered in the websocket thread! Use own queue

to process them in main thread, especially if a callback touches Qt widgets.

Internal topics:

• ‘connection.opened’ first message received after (re)connection.

• ‘connection.closed’ connection was lost or could not be created.

• ‘auth.failed’ server rejected the token.

Parameters:

connection (ServerAPI) – Server connection.

TOPIC_AUTH_FAILED: str = 'auth.failed'

TOPIC_CONNECTION_CLOSED: str = 'connection.closed'

TOPIC_CONNECTION_OPENED: str = 'connection.opened'

TOPIC_SERVER_RESTART_REQUESTED: str = 'server.restart_requested'

add_callback(topic: str, callback: Callable | weakref_partial, order: int | None = None, *, connect: bool = True) → EventCallback

Register callback in event system.

Parameters:

• topic (str) – Topic for EventCallback.

• callback (Callable | weakref_partial) – Function or method that will be called when topic is triggered.

• order (int | None) – Order of callback. Lower number means higher priority.

• connect (bool) – Create websocket connection if not already created.

Returns:

Created callback object which can be used to

stop listening.

Return type:

EventCallback

add_callbacks(callbacks: list[ayon_api.events.EventCallback], *, connect: bool = True) → None

Register callback in event system.

Parameters:

• callbacks (list[EventCallback]) – List of EventCallback objects to register.

• connect (bool) – Create websocket connection if not already created.

check_server_available() → bool | None

Quick synchronous check if server is available.

Websocket connection is created in a background thread, so it takes

a while until the connection state is known. This check can be used e.g. when a tool is opened to find out that the server is not available before the tool tries to fetch data from it.

Request is sent only if the connection state is not known yet. When

the server is not available, the state is changed to disconnected and ‘connection.closed’ event is emitted.

Returns:

‘False’ if server is not available, ‘True’ if

websocket is connected, ‘None’ if server did respond but websocket connection is not established yet.

Return type:

bool | None

emit_event(event: Event) → None

Emit event object.

Parameters:

event (Event) – Prepared event with topic and data.

get_connection_state() → bool | None

Connection state as was reported by events.

Returns:

‘True’ if connected, ‘False’ if disconnected and

’None’ if state is not known yet.

Return type:

bool | None

is_auth_failed() → bool

is_connected() → bool

Check if event loop is connected to server.

Returns:

Is event loop connected to server.

Return type:

bool

is_running() → bool

Check if event loop is running.

Returns:

Is event loop running.

Return type:

bool

is_server_restarting() → bool

reauthenticate() → None

Authenticate websocket connection with current token.

Should be called when token of the server connection did change.

Websocket connection is kept if is open, otherwise next connection attempt happens immediately.

reconnect() → None

Drop current websocket connection and connect again.

Should be called when websocket connection should be recreated,

e.g. server url of the connection did change.

start() → None

Start event loop.

Websocket connection is created in a daemon thread, this method

does not block.

stop() → None

is_func_signature_supported(func, *args, **kwargs)

Check if a function signature supports passed args and kwargs.

This check does not actually call the function, just look if function can be called with the arguments.

Notes

This does NOT check if the function would work with passed arguments

only if they can be passed in. If function have *args, **kwargs in parameters, this will always return ‘True’.

Example

>>> def my_function(my_number):
...     return my_number + 1
...
>>> is_func_signature_supported(my_function, 1)
True
>>> is_func_signature_supported(my_function, 1, 2)
False
>>> is_func_signature_supported(my_function, my_number=1)
True
>>> is_func_signature_supported(my_function, number=1)
False
>>> is_func_signature_supported(my_function, "string")
True
>>> def my_other_function(*args, **kwargs):
...     my_function(*args, **kwargs)
...
>>> is_func_signature_supported(
...     my_other_function,
...     "string",
...     1,
...     other=None
... )
True

Parameters:

• func (Callable) – A function where the signature should be tested.

• *args (Any) – Positional arguments for function signature.

• **kwargs (Any) – Keyword arguments for function signature.

Returns:

Function can pass in arguments.

Return type:

bool

class weakref_partial(func: Callable, *args, **kwargs)

Bases: object

Partial function with weak reference to the wrapped function.

Can be used as ‘functools.partial’ but it will store weak reference to

function. That means that the function must be reference counted to avoid garbage collecting the function itself.

When the referenced functions is garbage collected then calling the weakref partial (no matter the args/kwargs passed) will do nothing. It will fail silently, returning None. The is_valid() method can be used to detect whether the reference is still valid.

Is useful for object methods. In that case the callback is

deregistered when object is destroyed.

Warning

Values passed as *args and **kwargs are stored strongly in memory.

That may “keep alive” objects that should be already destroyed. It is recommended to pass only immutable objects like ‘str’, ‘bool’, ‘int’ etc.

Parameters:

• func (Callable) – Function to wrap.

• *args – Arguments passed to the wrapped function.

• **kwargs – Keyword arguments passed to the wrapped function.

get_func() → Callable | None

Get wrapped function.

Returns:

Wrapped function or None if it was destroyed.

Return type:

Callable | None

is_valid() → bool

Check if wrapped function is still valid.

Returns:

Is wrapped function still valid.

Return type:

bool

validate_signature(*args, **kwargs) → bool

Validate if passed arguments are supported by wrapped function.

Returns:

Are passed arguments supported by wrapped function.

Return type:

bool