ayon_api.server_api module

Server API.

Provides access to server API.

class GraphQlResponse(data)

Bases: object

GraphQl response.

class ServerAPI(base_url: str, token: ~typing.Optional[str] = None, site_id: ~typing.Optional[str] = <object object>, client_version: ~typing.Optional[str] = None, default_settings_variant: ~typing.Optional[str] = None, sender_type: ~typing.Optional[str] = None, sender: ~typing.Optional[str] = None, ssl_verify: ~typing.Optional[~typing.Union[bool, str]] = None, cert: ~typing.Optional[str] = None, create_session: bool = True, timeout: ~typing.Optional[float] = None, max_retries: ~typing.Optional[int] = None)

Bases: InstallersAPI, DependencyPackagesAPI, SecretsAPI, BundlesAddonsAPI, EventsAPI, AttributesAPI, ProjectsAPI, FoldersAPI, TasksAPI, ProductsAPI, VersionsAPI, RepresentationsAPI, WorkfilesAPI, ThumbnailsAPI, ActivitiesAPI, ActionsAPI, LinksAPI, ListsAPI

Base handler of connection to server.

Requires url to server which is used as base for api and graphql calls.

Login cause that a session is used

Parameters:

• base_url (str) – Example: http://localhost:5000

• token (Optional[str]) – Access token (api key) to server.

• site_id (Optional[str]) – Unique name of site. Should be the same when connection is created from the same machine under same user.

• client_version (Optional[str]) – Version of client application (used in desktop client application).

• default_settings_variant (Optional[Literal["production", "staging"]]) – Settings variant used by default if a method for settings won’t get any (by default is ‘production’).

• sender_type (Optional[str]) – Sender type of requests. Used in server logs and propagated into events.

• sender (Optional[str]) – Sender of requests, more specific than sender type (e.g. machine name). Used in server logs and propagated into events.

• ssl_verify (Optional[Union[bool, str]]) – Verify SSL certificate Looks for env variable value AYON_CA_FILE by default. If not available then ‘True’ is used.

• cert (Optional[str]) – Path to certificate file. Looks for env variable value AYON_CERT_FILE by default.

• create_session (Optional[bool]) – Create session for connection if token is available. Default is True.

• timeout (Optional[float]) – Timeout for requests.

• max_retries (Optional[int]) – Number of retries for requests.

property access_token: Optional[str]

Access token used for authorization to server.

Returns:

Token string or None if not authorized yet.

Return type:

Optional[str]

as_username(username: Optional[str], ignore_service_error: bool = False)

Service API will temporarily work as other user.

This method can be used only if service API key is logged in.

Parameters:

• username (Optional[str]) – Username to work as when service.

• ignore_service_error (Optional[bool]) – Ignore error when service API key is not used.

Raises:

ValueError – When connection is not yet authenticated or api key is not service token.

property base_url

property cert

Current cert file used for connection to server.

Returns:

Path to cert file.

Return type:

Union[str, None]

property client_version: Optional[str]

Version of client used to connect to server.

Client version is AYON client build desktop application.

Returns:

Client version string used in connection.

Return type:

str

close_session()

create_session(ignore_existing: bool = True, force: bool = False)

Create a connection session.

Session helps to keep connection with server without need to reconnect on each call.

Parameters:

• ignore_existing (bool) – If session already exists, ignore creation.

• force (bool) – If session already exists, close it and create new.

default_download_chunk_size = 1048576

property default_settings_variant: str

Default variant used for settings.

Returns:

name of variant or None.

Return type:

Union[str, None]

default_upload_chunk_size = 1048576

delete(entrypoint: str, **kwargs)

download_file(endpoint: str, filepath: str, chunk_size: Optional[int] = None, progress: Optional[TransferProgress] = None) → TransferProgress

Download file from AYON server.

Endpoint can be full url (must start with ‘base_url’ of api object).

Progress object can be used to track download. Can be used when download happens in thread and other thread want to catch changes over time.

Todos:

Use retries and timeout. Return RestApiResponse.

Parameters:

• endpoint (str) – Endpoint or URL to file that should be downloaded.

• filepath (str) – Path where file will be downloaded.

• chunk_size (Optional[int]) – Size of chunks that are received in single loop.

• progress (Optional[TransferProgress]) – Object that gives ability to track download progress.

download_file_to_stream(endpoint: str, stream: StreamType, chunk_size: Optional[int] = None, progress: Optional[TransferProgress] = None) → TransferProgress

Download file from AYON server to IOStream.

Endpoint can be full url (must start with ‘base_url’ of api object).

Progress object can be used to track download. Can be used when download happens in thread and other thread want to catch changes over time.

Todos:

Use retries and timeout. Return RestApiResponse.

Parameters:

• endpoint (str) – Endpoint or URL to file that should be downloaded.

• stream (StreamType) – Stream where output will be stored.

• chunk_size (Optional[int]) – Size of chunks that are received in single loop.

• progress (Optional[TransferProgress]) – Object that gives ability to track download progress.

get(entrypoint: str, **kwargs)

get_background_operations_status(project_name: str, task_id: str) → BackgroundOperationTask

Get status of background operations task.

Parameters:

• project_name (str) – Project name.

• task_id (str) – Backgorund operation task id.

Returns:

Background operation.

Return type:

BackgroundOperationTask

get_base_url()

get_cert()

Current cert file used for connection to server.

Returns:

Path to cert file.

Return type:

Union[str, None]

get_client_version() → Optional[str]

Version of client used to connect to server.

Client version is AYON client build desktop application.

Returns:

Client version string used in connection.

Return type:

str

get_default_fields_for_type(entity_type: str) → set[str]

Default fields for entity type.

Returns most of commonly used fields from server.

Parameters:

entity_type (str) – Name of entity type.

Returns:

Fields that should be queried from server.

Return type:

set[str]

classmethod get_default_max_retries()

Default value for requests max retries.

First looks for environment variable SERVER_RETRIES_ENV_KEY, which can affect max retries value. If not available then use class attribute ‘_default_max_retries’.

Returns:

Max retries value.

Return type:

int

get_default_service_username() → Optional[str]

Default username used for callbacks when used with service API key.

Returns:

Username if any was filled.

Return type:

Union[str, None]

get_default_settings_variant() → str

Default variant used for settings.

Returns:

name of variant or None.

Return type:

Union[str, None]

classmethod get_default_timeout()

Default value for requests timeout.

Utils function ‘get_default_timeout’ is used by default.

Returns:

Timeout value in seconds.

Return type:

float

get_graphql_schema() → dict[str, Any]

get_headers(content_type: Optional[str] = None) → dict[str, str]

get_info() → dict[str, Any]

Get information about current used api key.

By default, the ‘info’ contains only ‘uptime’ and ‘version’. With logged user info also contains information about user and machines on which was logged in.

Todos:

Use this method for validation of token instead of ‘get_user’.

Returns:

Information from server.

Return type:

dict[str, Any]

get_max_retries() → int

Current value for requests max retries.

Returns:

Max retries value.

Return type:

int

get_rest_entity_by_id(project_name: str, entity_type: str, entity_id: str) → Optional[AnyEntityDict]

Get entity using REST on a project by its id.

Parameters:

• project_name (str) – Name of project where entity is.

• entity_type (Literal["folder", "task", "product", "version"]) – The entity type which should be received.

• entity_id (str) – Id of entity.

Returns:

Received entity data.

Return type:

Optional[AnyEntityDict]

get_rest_url()

get_schemas() → dict[str, Any]

Get components schema.

Name of components does not match entity type names e.g. ‘project’ is under ‘ProjectModel’. We should find out some mapping. Also, there are properties which don’t have information about reference to object e.g. ‘config’ has just object definition without reference schema.

Returns:

Component schemas.

Return type:

dict[str, Any]

get_sender() → str

Sender used to send requests.

Returns:

Sender name or None.

Return type:

Union[str, None]

get_sender_type() → Optional[str]

Sender type used to send requests.

Sender type is supported since AYON server 1.5.5 .

Returns:

Sender type or None.

Return type:

Optional[str]

get_server_schema() → Optional[dict[str, Any]]

Get server schema with info, url paths, components etc.

Todos:

Cache schema - How to find out it is outdated?

Returns:

Full server schema.

Return type:

dict[str, Any]

get_server_version() → str

Get server version.

Version should match semantic version (https://semver.org/).

Returns:

Server version.

Return type:

str

get_server_version_tuple() → ServerVersion

Get server version as tuple.

Version should match semantic version (https://semver.org/).

This function only returns first three numbers of version.

Returns:

Server version.

Return type:

ServerVersion

get_site_id() → Optional[str]

Site id used for connection.

Site id tells server from which machine/site is connection created and is used for default site overrides when settings are received.

Returns:

Site id value or None if not filled.

Return type:

Optional[str]

get_ssl_verify()

Enable ssl verification.

Returns:

Current state of ssl verification.

Return type:

bool

get_timeout() → float

Current value for requests timeout.

Returns:

Timeout value in seconds.

Return type:

float

get_user(username: Optional[str] = None) → Optional[dict[str, Any]]

Get user info using REST endpoint.

User contains only explicitly set attributes in ‘attrib’.

Parameters:

username (Optional[str]) – Username.

Returns:

User info or None if user is not

found.

Return type:

Optional[dict[str, Any]]

get_user_by_name(username: str, project_name: Optional[str] = None, fields: Optional[Iterable[str]] = None) → Optional[dict[str, Any]]

Get user by name using GraphQl.

Only administrators and managers can fetch all users. For other users

it is required to pass in ‘project_name’ filter.

Parameters:

• username (str) – Username.

• project_name (Optional[str]) – Define scope of project.

• fields (Optional[Iterable[str]]) – Fields to be queried for users.

Returns:

User info or None if user is not

found.

Return type:

Union[dict[str, Any], None]

get_users(project_name: Optional[str] = None, usernames: Optional[Iterable[str]] = None, emails: Optional[Iterable[str]] = None, fields: Optional[Iterable[str]] = None) → Generator[dict[str, Any], None, None]

Get Users.

Only administrators and managers can fetch all users. For other users

it is required to pass in ‘project_name’ filter.

Parameters:

• project_name (Optional[str]) – Project name.

• usernames (Optional[Iterable[str]]) – Filter by usernames.

• emails (Optional[Iterable[str]]) – Filter by emails.

• fields (Optional[Iterable[str]]) – Fields to be queried for users.

Returns:

Queried users.

Return type:

Generator[dict[str, Any]]

property graphql_allows_traits_in_representations: bool

Check server support for representation traits.

property has_valid_token: bool

property is_server_available: bool

is_service_user() → bool

Check if connection is using service API key.

Returns:

Used api key belongs to service user.

Return type:

bool

property log: Logger

login(username: str, password: str, create_session: bool = True)

Login to server.

Parameters:

• username (str) – Username.

• password (str) – Password.

• create_session (Optional[bool]) – Create session after login. Default: True.

Raises:

AuthenticationError – Login failed.

logout(soft: bool = False)

property max_retries: int

Current value for requests max retries.

Returns:

Max retries value.

Return type:

int

patch(entrypoint: str, **kwargs)

post(entrypoint: str, **kwargs)

put(entrypoint: str, **kwargs)

query_graphql(query: str, variables: Optional[dict[str, Any]] = None) → GraphQlResponse

Execute GraphQl query.

Parameters:

• query (str) – GraphQl query string.

• variables (Optional[dict[str, Any]) – Variables that can be used in query.

Returns:

Response from server.

Return type:

GraphQlResponse

raw_delete(entrypoint: str, **kwargs)

raw_get(entrypoint: str, **kwargs)

raw_patch(entrypoint: str, **kwargs)

raw_post(entrypoint: str, **kwargs)

raw_put(entrypoint: str, **kwargs)

reset_token()

property rest_url

send_background_batch_operations(project_name: str, operations: list[dict[str, Any]], *, can_fail: bool = False, wait: bool = False, raise_on_fail: bool = True) → BackgroundOperationTask

Post multiple CRUD operations to server.

When multiple changes should be made on server side this is the best way to go. It is possible to pass multiple operations to process on a server side and do the changes in a transaction.

Compared to ‘send_batch_operations’ this function creates a task on

server which then can be periodically checked for a status and receive it’s result.

When used with ‘wait’ set to ‘True’ this method blocks until task is

finished. Which makes it work as ‘send_batch_operations’ but safer for large operations batch as is not bound to response timeout.

Parameters:

• project_name (str) – On which project should be operations processed.

• operations (list[dict[str, Any]]) – Operations to be processed.

• can_fail (Optional[bool]) – Server will try to process all operations even if one of them fails.

• wait (bool) – Wait for operations to end.

• raise_on_fail (Optional[bool]) – Raise exception if an operation fails. You can handle failed operations on your own when set to ‘False’. Used when ‘wait’ is enabled.

Raises:

• ValueError – Operations can’t be converted to json string.

• FailedOperations – When output does not contain server operations or ‘raise_on_fail’ is enabled and any operation fails.

Returns:

Background operation.

Return type:

BackgroundOperationTask

send_batch_operations(project_name: str, operations: list[dict[str, Any]], can_fail: bool = False, raise_on_fail: bool = True) → list[dict[str, Any]]

Post multiple CRUD operations to server.

When multiple changes should be made on server side this is the best way to go. It is possible to pass multiple operations to process on a server side and do the changes in a transaction.

Parameters:

• project_name (str) – On which project should be operations processed.

• operations (list[dict[str, Any]]) – Operations to be processed.

• can_fail (Optional[bool]) – Server will try to process all operations even if one of them fails.

• raise_on_fail (Optional[bool]) – Raise exception if an operation fails. You can handle failed operations on your own when set to ‘False’.

Raises:

• ValueError – Operations can’t be converted to json string.

• FailedOperations – When output does not contain server operations or ‘raise_on_fail’ is enabled and any operation fails.

Returns:

Operations result with process details.

Return type:

list[dict[str, Any]]

property sender: str

Sender used to send requests.

Returns:

Sender name or None.

Return type:

Union[str, None]

property sender_type: Optional[str]

Sender type used to send requests.

Sender type is supported since AYON server 1.5.5 .

Returns:

Sender type or None.

Return type:

Optional[str]

property server_version: str

Get server version.

Version should match semantic version (https://semver.org/).

Returns:

Server version.

Return type:

str

property server_version_tuple: ServerVersion

Get server version as tuple.

Version should match semantic version (https://semver.org/).

This function only returns first three numbers of version.

Returns:

Server version.

Return type:

ServerVersion

set_cert(cert)

Change cert file used for connection to server.

Parameters:

cert (Union[str, None]) – Path to cert file.

set_client_version(client_version: Optional[str])

Set version of client used to connect to server.

Client version is AYON client build desktop application.

Parameters:

client_version (Optional[str]) – Client version string.

set_default_service_username(username: Optional[str] = None)

Service API will work as other user.

Service API keys can work as other user. It can be temporary using context manager ‘as_user’ or it is possible to set default username if ‘as_user’ context manager is not entered.

Parameters:

username (Optional[str]) – Username to work as when service.

Raises:

ValueError – When connection is not yet authenticated or api key is not service token.

set_default_settings_variant(variant: str)

Change default variant for addon settings.

Note

It is recommended to set only ‘production’ or ‘staging’ variants

as default variant.

Parameters:

variant (str) – Settings variant name. It is possible to use ‘production’, ‘staging’ or name of dev bundle.

set_max_retries(max_retries: Optional[int])

Change max retries value for requests.

Parameters:

max_retries (Optional[int]) – Max retries value.

set_sender(sender: Optional[str])

Change sender used for requests.

Parameters:

sender (Optional[str]) – Sender name or None.

set_sender_type(sender_type: Optional[str])

Change sender type used for requests.

Parameters:

sender_type (Optional[str]) – Sender type or None.

set_site_id(site_id: Optional[str])

Change site id of connection.

Behave as specific site for server. It affects default behavior of settings getter methods.

Parameters:

site_id (Optional[str]) – Site id value, or ‘None’ to unset.

set_ssl_verify(ssl_verify)

Change ssl verification state.

Parameters:

ssl_verify (Union[bool, str, None]) – Enabled/disable ssl verification, can be a path to file.

set_timeout(timeout: Optional[float])

Change timeout value for requests.

Parameters:

timeout (Optional[float]) – Timeout value in seconds.

set_token(token: Optional[str])

property site_id: Optional[str]

Site id used for connection.

Site id tells server from which machine/site is connection created and is used for default site overrides when settings are received.

Returns:

Site id value or None if not filled.

Return type:

Optional[str]

property ssl_verify

Enable ssl verification.

Returns:

Current state of ssl verification.

Return type:

bool

property timeout: float

Current value for requests timeout.

Returns:

Timeout value in seconds.

Return type:

float

trigger_server_restart()

Trigger server restart.

Restart may be required when a change of specific value happened on server.

upload_file(endpoint: str, filepath: str, progress: Optional[TransferProgress] = None, request_type: Optional[RequestType] = None, **kwargs) → Response

Upload file to server.

Todos:

Use retries and timeout. Return RestApiResponse.

Parameters:

• endpoint (str) – Endpoint or url where file will be uploaded.

• filepath (str) – Source filepath.

• progress (Optional[TransferProgress]) – Object that gives ability to track upload progress.

• request_type (Optional[RequestType]) – Type of request that will be used to upload file.

• **kwargs (Any) – Additional arguments that will be passed to request function.

Returns:

Response object

Return type:

requests.Response

upload_file_from_stream(endpoint: str, stream: StreamType, progress: Optional[TransferProgress] = None, request_type: Optional[RequestType] = None, **kwargs) → requests.Response

Upload file to server from bytes.

Todos:

Use retries and timeout. Return RestApiResponse.

Parameters:

• endpoint (str) – Endpoint or url where file will be uploaded.

• stream (StreamType) – File content stream.

• progress (Optional[TransferProgress]) – Object that gives ability to track upload progress.

• request_type (Optional[RequestType]) – Type of request that will be used to upload file.

• **kwargs (Any) – Additional arguments that will be passed to request function.

Returns:

Response object

Return type:

requests.Response

upload_reviewable(project_name: str, version_id: str, filepath: str, label: Optional[str] = None, content_type: Optional[str] = None, filename: Optional[str] = None, progress: Optional[TransferProgress] = None, headers: Optional[dict[str, Any]] = None, **kwargs) → Response

Upload reviewable file to server.

Parameters:

• project_name (str) – Project name.

• version_id (str) – Version id.

• filepath (str) – Reviewable file path to upload.

• label (Optional[str]) – Reviewable label. Filled automatically server side with filename.

• content_type (Optional[str]) – MIME type of the file.

• filename (Optional[str]) – User as original filename. Filename from ‘filepath’ is used when not filled.

• progress (Optional[TransferProgress]) – Progress.

• headers (Optional[dict[str, Any]]) – Headers.

Returns:

Server response.

Return type:

requests.Response

validate_server_availability()

validate_token() → bool