Omniverse Client Library Python API

omni.client

class omni.client.AccessFlags

Members:

READ : Can read

WRITE : Can write

ADMIN : Can change ACLs

property name

handle) -> str

Type

(self

class omni.client.ChannelEvent

Members:

ERROR : Error.

MESSAGE : Someone sent a message.

HELLO : You joined a channel that someone else was already in, and they said hello.

JOIN : Someone joined.

LEFT : Someone left.

DELETED : Someone deleted the channel or changed ACLs so you no longer have access.

property name

handle) -> str

Type

(self

class omni.client.ConnectionStatus

Members:

CONNECTING : Attempting to connect

CONNECTED : Successfully connected

CONNECT_ERROR : Connection error

DISCONNECTED : Disconnected

SIGNED_OUT : omniClientSignOut called

NO_USERNAME : No username was provided (This status is no longer used)

AUTH_ABORT : Application requested auth abort

AUTH_CANCELLED : User or application request auth cancel

AUTH_ERROR : Internal error while trying to authenticate

AUTH_FAILED : Authentication failed

SERVER_INCOMPATIBLE : The server is not compatible with this version of the client library

INVALID_HOST : The host name is invalid

property name

handle) -> str

Type

(self

class omni.client.Content

Object to hold file content.

Use python memoryview to access it. For example:

_, content = await omni.client.read_file_async("omniverse://ov-sandbox/some/file.txt")
print(memoryview(content).tobytes())

class omni.client.CopyBehavior

Members:

ERROR_IF_EXISTS : Fails to copy with an error if the destination already exists

OVERWRITE : Overwrites any files on copy

property name

handle) -> str

Type

(self

class omni.client.FileStatus

Members:

READING : Reading

WRITING : Writing

COPYING : Copying

MOVING : Moving

DELETING : Deleting

OBLITERATING : Obliterating

SENDING_UPDATE : Sending Live Update

RECEIVED_UPDATE : Received Live Update

LISTING : Listing

STATING : Stating

property name

handle) -> str

Type

(self

class omni.client.ItemFlags

Members:

READABLE_FILE : You can call read_file on this. note: ACLs may still prevent you from reading it

WRITEABLE_FILE : You can call write_file on this. note: ACLs may still prevent you from writing it

CAN_HAVE_CHILDREN : This thing can contain other things (a folder-like thing)

DOES_NOT_HAVE_CHILDRENThis thing does not have any children. The lack of this flag does not mean it does have children!

Sometimes we are not sure if it has children until you attempt to list the children. This is only intended to be used for UI elements to hide the ‘expand’ button if we are sure it does not have any children.

IS_MOUNT : This thing is the root of a mount point

IS_INSIDE_MOUNT : This thing is located inside a mounted folder

CAN_LIVE_UPDATE : This thing supports live updates

IS_OMNI_OBJECT : This thing is in omni-object format. You must use a special API to read/write it

IS_CHANNEL : This thing is a channel. You can call join_channel on it

IS_CHECKPOINTED : This item is checkpointed (meaning you can revert to it)

IS_DELETED : This item is deleted

property name

handle) -> str

Type

(self

class omni.client.ListEvent

Members:

UNKNOWN

CREATED

UPDATED

DELETED

METADATA

LOCKED

UNLOCKED

OBLITERATED

property name

handle) -> str

Type

(self

class omni.client.ListIncludeOption

Members:

NO_DELETED_FILES : Ignore deleted files

INCLUDE_DELETED_FILES : Include deleted files

ONLY_DELETED_FILES : Only deleted files

property name

handle) -> str

Type

(self

class omni.client.LogLevel

Members:

DEBUG : Extra chatty

VERBOSE : Chatty

INFO : Not a problem

WARNING : Potential problem

ERROR : Definite problem

property name

handle) -> str

Type

(self

class omni.client.Request

Generic request object. Can be used to stop request before completing.

is_finished(self: omni.client._omniclient.Request) → bool

stop(self: omni.client._omniclient.Request) → None

wait(self: omni.client._omniclient.Request) → None

class omni.client.Result

Members:

OK

OK_LATEST

OK_NOT_YET_FOUND

ERROR

ERROR_CONNECTION

ERROR_NOT_SUPPORTED

ERROR_ACCESS_DENIED

ERROR_NOT_FOUND

ERROR_BAD_VERSION

ERROR_ALREADY_EXISTS

ERROR_SOURCE_IS_DEST

ERROR_ACCESS_LOST

ERROR_LOCKED

ERROR_BAD_REQUEST

ERROR_FOLDER_NOT_EMPTY

property name

handle) -> str

Type

(self

omni.client.add_bookmark(name: str, url: str) → None

Add a bookmark.

omni.client.add_default_search_path(search_path: str) → None

Add a default search path to the list of search paths used by resolve

New default search paths are added to the top of the stack (meaning they will match before older default search paths), but all default search paths are underneath the search_paths explicitly provided to resolve.

If this search_path is already in the list, it is moved to the top

omni.client.add_user_to_group(url: str, user: str, group: str) → omni.client.Result

Add a user to a group and wait for the result.

See: omni.client.add_user_to_group_with_callback()

async omni.client.add_user_to_group_async(url: str, user: str, group: str) → omni.client.Result

Asynchronously Add a user to a group

See: omni.client.add_user_to_group_with_callback()

omni.client.add_user_to_group_with_callback(url: str, user: str, group: str, callback: Callable[[omni.client.Result], None]) → omni.client.Request

Add a user to a group

omni.client.authentication_cancel(auth_handle: int) → None

Cancel an authentication attempt.

This should be called in response to a user clicking the “Cancel” button in an authentication message box.

Parameters

auth_handle – The parameter passed to a callback registered with set_authentication_message_box_callback.

omni.client.break_url(url: str) → omni.client.Url

Break a URL into components. This behaves similarly to omni.client.break_url_reference() except it assumes the URL is either a full URL (which starts with a scheme:) or is a raw local file path (such as “C:path” on Windows or “/path” on Linux). This affects how it handles special characters such as : % ? and #. If is_raw on the returned object is True, the URL was determined to be a raw local file path, and only the ‘path’ value is set.

omni.client.break_url_reference(url: str) → omni.client.Url

Break a URL into components. This should be used instead of omni.client.break_url() if you have a URL such as ‘/path?query#fragment’ which could be interpreted as a local file path.

omni.client.combine_urls(base_url: str, other_url: str) → str

Returns a URL which is a combination of the base_url and other_url

omni.client.combine_with_base_url(other_url: str) → str

This calls omni.client.combine_urls() with the URL on top of the base url stack.

omni.client.copy(src_url: str, dst_url: str, behavior: omni.client.CopyBehavior = CopyBehavior.ERROR_IF_EXISTS, message: str = '') → omni.client.Result

Copy an item from src_url to dst_url and wait for the result.

See: omni.client.copy_with_callback()

async omni.client.copy_async(src_url: str, dst_url: str, behavior: omni.client.CopyBehavior = CopyBehavior.ERROR_IF_EXISTS, message: str = '') → omni.client.Result

Asynchronously Copy an item from src_url to dst_url

See: omni.client.copy_with_callback()

omni.client.copy_with_callback(src_url: str, dst_url: str, callback: Callable[[omni.client.Result], None], behavior: omni.client.CopyBehavior = CopyBehavior.ERROR_IF_EXISTS, message: str = None) → omni.client.Request

Copy a thing from src_url to dst_url.

The thing can be anything that supports copying (files, folders, etc..) If both src and dst are on the same server, this is done on the server Otherwise the file is first downloaded from ‘src’ then uploaded to ‘dst’.

Destination folders will be created as needed

Parameters

• src_url – Source url.

• dst_url – Destination url.

• callback – Callback to be called with the result.

• behavior – behavior if the destination exists.

• message – Message to apply to atomic checkpoint of destination url.

Returns

Request object.

omni.client.create_checkpoint(url: str, comment: str, force: bool = False) → Tuple[omni.client.Result, str]

Create a checkpoint of an item and wait for the result.

See: omni.client.create_checkpoint_with_callback()

async omni.client.create_checkpoint_async(url: str, comment: str, force: bool = False) → Tuple[omni.client.Result, str]

Asynchronously Create a checkpoint of an item

See: omni.client.create_checkpoint_with_callback()

omni.client.create_checkpoint_with_callback(url: str, comment: str, force: bool = False, callback: Callable[[omni.client.Result, str], None]) → omni.client.Request

Create a checkpoint.

Parameters

• url – URL of file to create a checkpoint for.

• comment – Comment to associate with the checkpoint

• force – Set to true to force creating a checkpoint even if there are no changes

• callback – Callback to be called with the result.

Returns

Request object.

omni.client.create_folder(url: str) → omni.client.Result

Create a folder and wait for the result.

See: omni.client.create_folder_with_callback()

async omni.client.create_folder_async(url: str) → omni.client.Result

Asynchronously Create a folder

See: omni.client.create_folder_with_callback()

omni.client.create_folder_with_callback(url: str, callback: Callable[[omni.client.Result], None]) → omni.client.Request

Create a folder.

Parameters

• url – URL of folder to create.

• callback – Callback to be called with the result.

Returns

Request object.

omni.client.create_group(url: str, group: str) → omni.client.Result

Create a group and wait for the result.

See: omni.client.create_group_with_callback()

async omni.client.create_group_async(url: str, group: str) → omni.client.Result

Asynchronously Create a group

See: omni.client.create_group_with_callback()

omni.client.create_group_with_callback(url: str, group: str, callback: Callable[[omni.client.Result], None]) → omni.client.Request

Create a group

omni.client.create_with_hash(url: str, hash: str, overwrite: bool) → Tuple[omni.client.Result, str, str]

Create an asset with a known hash and wait for the result.

See: omni.client.create_with_hash_with_callback()

async omni.client.create_with_hash_async(url: str, hash: str, overwrite: bool) → Tuple[omni.client.Result, str, str]

Asynchronously Create an asset with a known hash

See: omni.client.create_with_hash_with_callback()

omni.client.create_with_hash_with_callback(url: str, hash: str, overwrite: bool, callback: Callable[[omni.client.Result, str, str], None], message: str = None) → omni.client.Request

Create a new file with the content the hash describes, will fail if the server doesn’t know the hash

Parameters

• url – URL of file to create.

• hash – Hash of content.

• overwrite – Allow to overwrite an existing file or fail if file exists

• callback – Callback to be called with the result.

• message – Message to apply to atomic checkpoint of destination url.

Returns

Request object.

omni.client.delete(url: str) → omni.client.Result

Delete an item and wait for the result.

See: omni.client.delete_with_callback()

async omni.client.delete_async(url: str) → omni.client.Result

Asynchronously Delete an item

See: omni.client.delete_with_callback()

omni.client.delete_with_callback(url: str, callback: Callable[[omni.client.Result], None]) → omni.client.Request

Delete something (file, folder, mount, live object, channel etc..).

Parameters

• url – URL of item to delete.

• callback – Callback to be called with the result.

Returns

Request object.

omni.client.enable_nucleus_cache_bypass(bypass_on: bool) → bool

For unit tests only. Enable/disable Nucleus Cache bypass.

omni.client.get_acls(url: str) → Tuple[omni.client.Result, List[omni.client.AclEntry]]

Get the ACLs for an item and wait for the result.

See: omni.client.get_acls_with_callback()

async omni.client.get_acls_async(url: str) → Tuple[omni.client.Result, List[omni.client.AclEntry]]

Asynchronously Get the ACLs for an item

See: omni.client.get_acls_with_callback()

omni.client.get_acls_with_callback(url: str, callback: Callable[[omni.client.Result, List[omni.client.AclEntry]], None]) → omni.client.Request

Get the ACL’s on a folder/file.

Parameters

• url – URL of item to get the ACLs for.

• callback – Callback to be called with the result and current ACLs.

Returns

Request object.

omni.client.get_base_url() → str

Returns the top of the base URL stack

Returns

The top of the base URL stack, or None if the stack is empty.

Return type

str

omni.client.get_branch_and_checkpoint_from_query(query: str) → tuple

Extract the branch and checkpoint from a query parameter

omni.client.get_default_search_paths() → List[str]

Retrieve the current list of default search paths

Returns

The list of default search paths.

Return type

List[str]

omni.client.get_group_users(url: str, group: str) → Tuple[omni.client.Result, List[str]]

Get a list of all users in a group and wait for the result.

See: omni.client.get_group_users_with_callback()

async omni.client.get_group_users_async(url: str, group: str) → Tuple[omni.client.Result, List[str]]

Asynchronously Get a list of all users in a group

See: omni.client.get_group_users_with_callback()

omni.client.get_group_users_with_callback(url: str, group: str, callback: Callable[[omni.client.Result, List[str]], None]) → omni.client.Request

Get a list of users in a group

omni.client.get_groups(url: str) → Tuple[omni.client.Result, List[str]]

Get a list of all groups and wait for the result.

See: omni.client.get_groups_with_callback()

async omni.client.get_groups_async(url: str) → Tuple[omni.client.Result, List[str]]

Asynchronously Get a list of all groups

See: omni.client.get_groups_with_callback()

omni.client.get_groups_with_callback(url: str, callback: Callable[[omni.client.Result, List[str]], None]) → omni.client.Request

Get a list of all groups

omni.client.get_hub_version() → Tuple[omni.client.Result, str]

Get Hub Version and wait for the result.

See: omni.client.get_hub_version_with_callback()

async omni.client.get_hub_version_async() → Tuple[omni.client.Result, str]

Asynchronously Get Hub Version

See: omni.client.get_hub_version_with_callback()

omni.client.get_hub_version_with_callback(callback: Callable[[omni.client.Result, str], None]) → omni.client.Request

omni.client.get_local_file(url: str, download: bool) → Tuple[omni.client.Result, str]

Get local file path from a URL and wait for the result.

See: omni.client.get_local_file_with_callback()

async omni.client.get_local_file_async(url: str, download: bool) → Tuple[omni.client.Result, str]

Asynchronously Get local file path from a URL

See: omni.client.get_local_file_with_callback()

omni.client.get_local_file_with_callback(url: str, download: bool, callback: Callable[[omni.client.Result, str], None]) → omni.client.Request

Get local file path for remote file.

Parameters

• url – URL of file to get the local path for.

• download – Pass false to get the local filename without downloading the file.

• callback – Callback to be called with the result.

Returns

Request object.

omni.client.get_server_info(url: str) → Tuple[omni.client.Result, omni.client.ServerInfo]

Get Server Info and wait for the result.

See: omni.client.get_server_info_with_callback()

async omni.client.get_server_info_async(url: str) → Tuple[omni.client.Result, omni.client.ServerInfo]

Asynchronously Get Server Info

See: omni.client.get_server_info_with_callback()

omni.client.get_server_info_with_callback(url: str, callback: Callable[[omni.client.Result, omni.client.ServerInfo], None]) → omni.client.Request

omni.client.get_user_groups(url: str, user: str) → Tuple[omni.client.Result, List[str]]

Get a list of groups the user is in and wait for the result.

See: omni.client.get_user_groups_with_callback()

async omni.client.get_user_groups_async(url: str, user: str) → Tuple[omni.client.Result, List[str]]

Asynchronously Get a list of groups the user is in

See: omni.client.get_user_groups_with_callback()

omni.client.get_user_groups_with_callback(url: str, user: str, callback: Callable[[omni.client.Result, List[str]], None]) → omni.client.Request

Retrieve the groups a user is in

omni.client.get_users(url: str) → Tuple[omni.client.Result, List[str]]

Get a list of all users and wait for the result.

See: omni.client.get_users_with_callback()

async omni.client.get_users_async(url: str) → Tuple[omni.client.Result, List[str]]

Asynchronously Get a list of all users

See: omni.client.get_users_with_callback()

omni.client.get_users_with_callback(url: str, callback: Callable[[omni.client.Result, List[str]], None]) → omni.client.Request

Get a list of all users

omni.client.get_version() → str

Get the version of the client library being used.

Returns

Returns a human readable version string.

omni.client.initialize(version: int = 844588138889222) → bool

Initialize the client library.

Returns

False if the library failed to initialize.

omni.client.join_channel_with_callback(url: str, callback: Callable[[omni.client.Result, omni.client.ChannelEvent, str, omni.client.Content], None]) → omni.client.Request

Join a channel.

Parameters

• url – URL of of channel to join.

• callback – Callback to be called with the result.

Returns

Request object.

omni.client.list(url: str, include_deleted_option: omni.client.ListIncludeOption = ListIncludeOption.NO_DELETED_FILES) → Tuple[omni.client.Result, Tuple[omni.client.ListEntry]]

List contents of a folder and wait for the result.

See: omni.client.list_with_callback()

async omni.client.list_async(url: str, include_deleted_option: omni.client.ListIncludeOption = ListIncludeOption.NO_DELETED_FILES) → Tuple[omni.client.Result, Tuple[omni.client.ListEntry]]

Asynchronously List contents of a folder

See: omni.client.list_with_callback()

omni.client.list_bookmarks_with_callback(callback: Callable[[Dict[str, str]], None]) → omni.client.Subscription

Retrieve a list of bookmarks. The callback is called any time the list changes (by this application or any other).

omni.client.list_checkpoints(url: str) → Tuple[omni.client.Result, Tuple[omni.client.ListEntry]]

List the checkpoints of an item and wait for the result.

See: omni.client.list_checkpoints_with_callback()

async omni.client.list_checkpoints_async(url: str) → Tuple[omni.client.Result, Tuple[omni.client.ListEntry]]

Asynchronously List the checkpoints of an item

See: omni.client.list_checkpoints_with_callback()

omni.client.list_checkpoints_with_callback(url: str, callback: Callable[[omni.client.Result, List[omni.client.ListEntry]], None]) → omni.client.Request

List checkpoints.

Parameters

• url – URL of file to list the checkpoints of.

• callback – Callback to be called with the result.

Returns

Request object.

omni.client.list_subscribe_with_callback(url: str, list_callback: Callable[[omni.client.Result, List[omni.client.ListEntry]], None], subscribe_callback: Callable[[omni.client.Result, omni.client.ListEvent, omni.client.ListEntry], None], include_deleted_option: omni.client.ListIncludeOption = ListIncludeOption.NO_DELETED_FILES) → omni.client.Subscription

Subscribe to change notifications for a url.

‘list_callback is called once with the initial list,

then ‘subscribe_callback’ may be called multiple times after that as items change.

Parameters

• url – URL of folder to subscribe to.

• list_callback – Callback to be called once with the list.

• subscribe_callback – Callback to be called when changes happen.

• include_deleted_option – Option to include deleted files (default NO_DELETED_FILES)

Returns

Subscription object.

omni.client.list_with_callback(url: str, callback: Callable[[omni.client.Result, List[omni.client.ListEntry]], None], include_deleted_option: omni.client.ListIncludeOption = ListIncludeOption.NO_DELETED_FILES) → omni.client.Request

List content of a folder.

Parameters

• url – URL of a folder to list the contents of.

• callback – Callback to be called with the results.

• include_deleted_option – Option to include deleted files (default NO_DELETED_FILES)

Returns

Request object.

omni.client.live_get_latest_server_time(url: str) → int

Returns the server timestamp of the most recently received message (0 if no messages have been received).

omni.client.live_process() → None

Call this to process live updates received from the server.

omni.client.live_process_up_to(url: str, server_time: int) → None

Same as omni.client.live_process() but you can specify a server time to stop processing updates.

Parameters

• url – URL of server to process updates for. Only the “prefix” such as “omniverse://content.ov.nvidia.com” is needed, the path is ignored.

• server_time – The server time to stop processing updates.

omni.client.live_register_queued_callback(callback: Callable[[OmniClientLiveUpdateType, omni.client.Result, str, int, int, int], None]) → omni.client.Registration

Register a function which is called any time we receive a live update.

This is intended to notify you that you should call live_process. DO NOT call omni.client.live_process() from within the callback function!

Parameters

callback – Callback to be called with information about the live update that was queued.

Returns

Subscription Object. Callback will be unregistered once subcription is released.

omni.client.live_set_queued_callback(callback: Callable[[], None]) → None

DEPRECATED: Use live_register_queued_callback

omni.client.live_wait_for_pending_updates() → None

Call this to wait for all pending live updates to complete.

omni.client.lock_with_callback(url: str, callback: Callable[[omni.client.Result], None]) → omni.client.Request

Lock a URL so only this client can modify it.

Parameters

url – URL of file to lock.

omni.client.make_file_url(path: str) → str

Returns a “file:” URL for the given path

omni.client.make_printable(url: str) → str

Returns a url which is safe for printing (no invalid UTF-8 sequences or ASCII control characters)

omni.client.make_query_from_branch_and_checkpoint(branch: str, checkpoint: int) → str

Return a query parameter that can be used to reference this branch and checkpoint

omni.client.make_relative_url(base_url: str, other_url: str) → str

Returns a url which will result in other_url, when combined with base_url

omni.client.make_url(scheme: str = None, user: str = None, host: str = None, port: str = None, path: str = None, query: str = None, fragment: str = None) → str

Compose a URL from the provided parts

omni.client.move(src_url: str, dst_url: str, behavior: omni.client.CopyBehavior = CopyBehavior.ERROR_IF_EXISTS, message: str = '') → Tuple[omni.client.Result, bool]

Move an item from src_url to dst_url and wait for the result.

See: omni.client.move_with_callback()

async omni.client.move_async(src_url: str, dst_url: str, behavior: omni.client.CopyBehavior = CopyBehavior.ERROR_IF_EXISTS, message: str = '') → Tuple[omni.client.Result, bool]

Asynchronously Move an item from src_url to dst_url

See: omni.client.move_with_callback()

omni.client.move_with_callback(src_url: str, dst_url: str, callback: Callable[[omni.client.Result, bool], None], behavior: omni.client.CopyBehavior = CopyBehavior.ERROR_IF_EXISTS, message: str = None) → omni.client.Request

Move a thing from src_url to dst_url.

If both src and dst are on the same server, this is done on the server. Otherwise, it is first copied from srcUrl to dstUrl, then deleted from dstUrl Note it is possible for the copy to succeed and the delete to fail. In this case the result will be the error code from the delete but ‘copied’ will be true.

If the result is ‘Ok’ but ‘copied’ is false, that means the move was done entirely on the server, so no local copy had to be made.

Destination folders will be created as needed

Parameters

• src_url – Source url.

• dst_url – Destination url.

• callback – Callback to be called with the result.

• behavior – behavior if the destination exists.

• message – Message to apply to atomic checkpoint of destination url.

Returns

Request object.

omni.client.normalize_url(url: str) → str

Normalize a URL by parsing it then recomposing it

omni.client.obliterate(url: str, obliterate_checkpoints: bool) → omni.client.Result

Obliterate an item and wait for the result.

See: omni.client.obliterate_with_callback()

async omni.client.obliterate_async(url: str, obliterate_checkpoints: bool) → omni.client.Result

Asynchronously Obliterate an item

See: omni.client.obliterate_with_callback()

omni.client.obliterate_with_callback(url: str, obliterate_checkpoints: bool, callback: Callable[[omni.client.Result], None]) → omni.client.Request

Obliterate a path

Doesn’t support recursive removal, doesn’t support wildcards Supports branches / checkpoints Only empty folders can be obliterated

Parameters

• url – URL of item to delete.

• obliterate_checkpoints – whether to obliterate all checkpoints

• callback – Callback to be called with the result of the operation

Returns

Request object.

omni.client.pop_base_url(*args, **kwargs)

Overloaded function.

1. pop_base_url(url: str) -> bool

Pop a URL off the base stack

2. pop_base_url(base_url: str) -> bool

   Pop a base URL from the context stack

   If the provided base_url is not on the top of the stack, a warning will be printed to the log and this will return false

omni.client.push_base_url(*args, **kwargs)

Overloaded function.

1. push_base_url(url: str) -> None

Push a URL onto the base stack, which is used with omni.client.combine_with_base_url().

2. push_base_url(base_url: str) -> None

   Push a base URL for relative URLs to resolve against

   For example if you push “omniverse://sandbox.ov.nvidia.com/path/” then calling omniList(“subpath”) will return the results of “omniverse://sandbox.ov.nvidia.com/path/subpath”. The rules for combining a relative URL with a base URLs is defined by https://tools.ietf.org/html/rfc3986 and is the same as a web browser would resolve links inside an HTML document. ** Note that the context is per-thread! ** This is so you can load resources on different threads with different base URLs

omni.client.read_file(url: str) → Tuple[omni.client.Result, str, omni.client.Content]

Read a file and wait for the result.

See: omni.client.read_file_with_callback()

async omni.client.read_file_async(url: str) → Tuple[omni.client.Result, str, omni.client.Content]

Asynchronously Read a file

See: omni.client.read_file_with_callback()

omni.client.read_file_with_callback(url: str, callback: Callable[[omni.client.Result, str, omni.client.Content], None]) → omni.client.Request

Read a file.

Parameters

• url – URL of file to read.

• callback – Callback to be called with the result.

Returns

Request object.

omni.client.reconnect(url: str) → None

Reconnect to a URL after a failure.

The client library doesn’t automatically reconnect after failures.

This triggers a background reconnect attempt, you can call a function such as omni.client.stat() or use omni.client.register_connection_status_callback() to determine if the reconnect attempt was successful.

Parameters

url – Attempt to connect to this url

omni.client.refresh_auth_token(url: str) → Tuple[omni.client.Result, str]

Refresh Auth Token and wait for the result.

See: omni.client.refresh_auth_token_with_callback()

async omni.client.refresh_auth_token_async(url: str) → Tuple[omni.client.Result, str]

Asynchronously Refresh Auth Token

See: omni.client.refresh_auth_token_with_callback()

omni.client.refresh_auth_token_with_callback(url: str, callback: Callable[[omni.client.Result, str], None]) → omni.client.Request

omni.client.register_authentication_callback(callback: Callable[[str], object]) → omni.client.Registration

Register an authentication callback.

The callback receives the URL prefix (such as “scheme://server:port”) as a parameter and should return either:

• None or False: Continue to the next authentication callback (or default authentication method)

• AUTH_ABORT: Abort the connection

• String: The auth_token provided by get_server_info

• (String, String): A username and password or you can return (“$omni-api-token”, api_token) to use an API token.

Parameters

callback – Callback to be called to provide authentication information.

Returns

Subscription Object. Callback will be unregistered once subscription is released.

omni.client.register_authorize_callback(callback: Callable[[str], object]) → omni.client.Registration

DEPRECATED - Use register_authentication_callback

omni.client.register_connection_status_callback(callback: Callable[[str, omni.client.ConnectionStatus], None]) → omni.client.Registration

Register connection status callback.

Parameters

callback – Callback to be called with the status.

Returns

Subscription Object. Callback will be unregistered once subcription is released.

omni.client.register_device_flow_auth_callback(callback: Callable[[int, omni.client.AuthDeviceFlowParams], None]) → omni.client.Registration

Register a “Device Flow” authentication callback.

If _any_ device flow auth callbacks are registered, we will prefer the device flow auth instead of launching a web browser.

Parameters

callback – Function to be called when performing device flow auth. It receives an auth handle (which can be used with authentication_cancel) and an object containing information that you should display to the user to complete authentication. If the information object is None that means the authentication attempt is finished (either sucessfully or not, register a connection status callback to determine which).

Returns

Subscription Object. The callback will be unregistered once subcription is released.

omni.client.register_file_status_callback(callback: Callable[[str, omni.client.FileStatus, int], None]) → omni.client.Registration

Register file status callback.

Parameters

callback – Callback to be called with the status.

Returns

Subscription Object. Callback will be unregistered once subcription is released.

omni.client.remove_bookmark(name: str) → None

Remove a bookmark.

omni.client.remove_default_search_path(search_path: str) → None

Remove a default search path from the list of search paths used by resolve

omni.client.remove_group(url: str, group: str) → Tuple[omni.client.Result, int]

Remove a group and wait for the result.

See: omni.client.remove_group_with_callback()

async omni.client.remove_group_async(url: str, group: str) → Tuple[omni.client.Result, int]

Asynchronously Remove a group

See: omni.client.remove_group_with_callback()

omni.client.remove_group_with_callback(url: str, group: str, callback: Callable[[omni.client.Result, int], None]) → omni.client.Request

Remove a group

omni.client.remove_user_from_group(url: str, user: str, group: str) → omni.client.Result

Remove a user from a group and wait for the result.

See: omni.client.remove_user_from_group_with_callback()

async omni.client.remove_user_from_group_async(url: str, user: str, group: str) → omni.client.Result

Asynchronously Remove a user from a group

See: omni.client.remove_user_from_group_with_callback()

omni.client.remove_user_from_group_with_callback(url: str, user: str, group: str, callback: Callable[[omni.client.Result], None]) → omni.client.Request

Remove a user from a group

omni.client.rename_group(url: str, group: str, new_group: str) → omni.client.Result

Rename a group and wait for the result.

See: omni.client.rename_group_with_callback()

async omni.client.rename_group_async(url: str, group: str, new_group: str) → omni.client.Result

Asynchronously Rename a group

See: omni.client.rename_group_with_callback()

omni.client.rename_group_with_callback(url: str, group: str, new_group: str, callback: Callable[[omni.client.Result], None]) → omni.client.Request

Rename a group

omni.client.resolve(url: str, search_urls: List[str]) → Tuple[omni.client.Result, omni.client.ListEntry, str]

Resolves a relative URL against a list of search URLs and wait for the result.

See: omni.client.resolve_with_callback()

async omni.client.resolve_async(url: str, search_urls: List[str]) → Tuple[omni.client.Result, omni.client.ListEntry, str]

Asynchronously Resolves a relative URL against a list of search URLs

See: omni.client.resolve_with_callback()

omni.client.resolve_subscribe_with_callback(url: str, search_urls: List[str], resolve_callback: Callable[[omni.client.Result, omni.client.ListEntry, str], None], subscribe_callback: Callable[[omni.client.Result, omni.client.ListEvent, omni.client.ListEntry, str], None]) → omni.client.Subscription

Resolve & subscribe to change notifications for a url.

Performs ‘resolve’ but also establishes a subscription so you will be notified if the resolution changes.

If ‘url’ is a file, you will only receive information about that file. If ‘url’ is a folder, you will only receive information about that folder. ‘resolve_callback is called once with the initial resolve info,then ‘subscribe_callback’ may be called multiple times after that the item changes.

Parameters

• url – URL of item to resolve. Can be relative or absolute.

• search_urls – List of URLs to search.

• resolve_callback – Callback to be called once with the initial resolve.

• subscribe_callback – Callback to be called when changes happen.

Returns

Subscrption object.

omni.client.resolve_with_callback(url: str, search_urls: List[str], callback: Callable[[omni.client.Result, omni.client.ListEntry, str], None]) → omni.client.Request

Resolve a file or folder, looking in the search paths for it.

Parameters

• url – URL of item to resolve.

• search_urls – List of URLs to search.

• callback – Callback to be called with the results.

Returns

Request object.

omni.client.send_message(join_request_id: int, content: bytes) → omni.client.Result

Send a message to a channel and wait for the result.

See: omni.client.send_message_with_callback()

async omni.client.send_message_async(join_request_id: int, content: bytes) → omni.client.Result

Asynchronously Send a message to a channel

See: omni.client.send_message_with_callback()

omni.client.send_message_with_callback(join_request_id: int, content: buffer, callback: Callable[[omni.client.Result], None]) → omni.client.Request

Send a message to a channel.

Parameters

• join_request_id – Request.id that you get from omni.client.join_channel_with_callback().

• content – Message content.

• callback – Callback to be called with the result.

Returns

Request object.

omni.client.set_acls(url: str, acls: List[omni.client.AclEntry]) → omni.client.Result

Set the ACLs for an item and wait for the result.

See: omni.client.set_acls_with_callback()

async omni.client.set_acls_async(url: str, acls: List[omni.client.AclEntry]) → omni.client.Result

Asynchronously Set the ACLs for an item

See: omni.client.set_acls_with_callback()

omni.client.set_acls_with_callback(url: str, acls: list, callback: Callable[[omni.client.Result], None]) → omni.client.Request

Set the ACL’s on a folder/file.

Parameters

• url – URL of item to set the ACLs on.

• acls – the complete new set of ACLs to put on this file/folder.

• callback – Callback to be called with the result and current ACLs.

Returns

Request object.

omni.client.set_alias(alias: str, value: str) → None

Redirect a URL to a different location

For example set_alias(“home:”, “C:Usersmyname")

Call it with value=None to remove an alias

omni.client.set_authentication_message_box_callback(callback: Callable[[bool, str, int], None]) → None

Set an authentication message box callback.

The callback is called when authentication requires opening a web browser to complete sign-in.

The intention is the application should show a dialog box letting the user know that a browser window has opened and to complete signing in using the web browser.

The callback receives:

1. A bool indicating if the dialog should be shown (true) or hidden (false)

2. A string indicating the host name that the authentication is for

3. An integer handle that can be passed to “authentication_cancel”

You should provide a “Cancel” button and call cancel_authentication if the user presses it.

You should call this function with “None” as the callback prior to shutting down in order to

free memory that was allocated to store the callback.

Note that signing in to multiple servers simultaneously is allowed, so you may receive multiple callbacks with “show” set to true before receiving them with “show” set to false. You can use the third parameter to track show/hide pairs.

Parameters

callback – Callback to be called to show an authentication dialog box.

omni.client.set_azure_sas_token(host: str, container: str, sasToken: str, writeConfig: bool) → omni.client.Result

Set SAS Token for an Azure blob container.

Returns

OmniClient Result code.

omni.client.set_hang_detection_time_ms(timeout: int) → None

Configure the amount of time to wait before the blocking versions of each function prints a warning (and a stack trace).

Note: this value must be set per thread!

Parameters

timeout – The amount of time to wait (in milliseconds) before printing a warning.

omni.client.set_log_callback(callback: Callable[[str, str, omni.client.LogLevel, str], None]) → None

Set a function which is called any time the library wants to print something to the log.

def log_callback(thread, component, level, message):
    print(f"{thread} {component} {level} {message}")

omni.client.set_log_callback(log_callback)

omni.client.set_log_level(log_level: omni.client.LogLevel) → None

Only print messages to the log which are at this level or higher.

omni.client.set_product_info(name: str, version: str = None, extra: str = None) → None

Sets product information that’s sent to Nucleus when connecting.

If you’re already connected to a Nucleus server, this will not send the new values to the server, only on reconnect. For this reason you should set the product information prior to connecting.

This is also used in Hub to help identify which applications are running.

Parameters

• name – The human-readable name of this product.

• version – The version of this product (not the client library version).

• extra – Any additional information you think would be valuable in the logs.

omni.client.set_retries(max_ms: int, base_ms: int, jitter_ms: int) → tuple

Set parameters to control retry behavior

The formula for delay between retries is: delay_ms = (base_ms * count * count) + rand(0, jitter_ms * count) where “count” is the current retry count.

Retries are aborted after ‘max_ms’ time has elapsed. Set it to 0 to disable retries.

Default behavior is: max_ms = 120,000 base_ms = 100 jitter_ms = 100

Returns previous values in a tuple of (max_ms, base_ms, jitter_ms).

omni.client.set_s3_configuration(url: str, bucket: str, region: str, accessKeyId: str, secretAccessKey: str, cloudfrontUrl: str, cloudfrontForList: bool, writeConfig: bool) → omni.client.Result

Set S3 configuration for a URI.

Returns

OmniClient Result code.

omni.client.shutdown() → None

Shut down the client library.

It is not safe to call any client library functions after calling shutdown.

omni.client.sign_out(url: str) → None

Sign out specific url connection.

Parameters

url – Immediately disconnect from the server specified by this URL. Any outstanding requests will call their callbacks with OmniClientResult.ErrorConnection. Additionally, clear the saved authentication token so future requests to this server will trigger re-authentication.

omni.client.stat(url: str, include_deleted_option: omni.client.ListIncludeOption = ListIncludeOption.NO_DELETED_FILES) → Tuple[omni.client.Result, omni.client.ListEntry]

Retrieve information about a single item and wait for the result.

See: omni.client.stat_with_callback()

async omni.client.stat_async(url: str, include_deleted_option: omni.client.ListIncludeOption = ListIncludeOption.NO_DELETED_FILES) → Tuple[omni.client.Result, omni.client.ListEntry]

Asynchronously Retrieve information about a single item

See: omni.client.stat_with_callback()

omni.client.stat_subscribe_with_callback(url: str, stat_callback: Callable[[omni.client.Result, omni.client.ListEntry], None], subscribe_callback: Callable[[omni.client.Result, omni.client.ListEvent, omni.client.ListEntry], None], include_deleted_option: omni.client.ListIncludeOption = ListIncludeOption.NO_DELETED_FILES) → omni.client.Subscription

Subscribe to change notifications for a url.

If ‘url’ is a file, you will only receive information about that file. If ‘url’ is a folder, you will only receive information about that folder. ‘stat_callback is called once with the initial stat info,then ‘subscribe_callback’ may be called multiple times after that the item changes.

Parameters

• url – URL of item to stat.

• stat_callback – Callback to be called once with the initial stat.

• subscribe_callback – Callback to be called when changes happen.

• include_deleted_option – Option to include deleted files (default NO_DELETED_FILES)

Returns

Subscription object.

omni.client.stat_with_callback(url: str, callback: Callable[[omni.client.Result, omni.client.ListEntry], None], include_deleted_option: omni.client.ListIncludeOption = ListIncludeOption.NO_DELETED_FILES) → omni.client.Request

Retrieve information about a file or folder.

Parameters

• url – URL of item to stat.

• callback – Callback to be called with the results.

• include_deleted_option – Option to include deleted files (default NO_DELETED_FILES)

Returns

Request object.

omni.client.trace_start() → bool

Start tracing using carb::tracer

If the client library is already using tracer, this does nothing.

Tracing is automatically started when the library is loaded, but this function may be used if the tracer library was downloaded and installed while the application was running.

Returns True if tracing was enabled (or was already enabled).

omni.client.trace_stop() → None

Stop tracing using carb::tracer

If the client library is not using tracer, this does nothing.

Tracing is automatically stopped when the library is unloaded, but this can be used to stop it early.

omni.client.undelete(url: str) → omni.client.Result

Undelete an item and wait for the result.

See: omni.client.undelete_with_callback()

async omni.client.undelete_async(url: str) → omni.client.Result

Asynchronously Undelete an item

See: omni.client.undelete_with_callback()

omni.client.undelete_with_callback(url: str, callback: Callable[[omni.client.Result], None]) → omni.client.Request

Undelete soft-deleted paths

Supports recursive parents undelete

Parameters

• url – URL of item to undelete

• callback – Callback to be called with the result of the operation

Returns

Request object.

omni.client.unlock_with_callback(url: str, callback: Callable[[omni.client.Result], None]) → omni.client.Request

Unlock a URL so other clients can modify it.

Parameters

url – URL of file to unlock.

omni.client.write_file(url: str, content: bytes, message: str = '') → omni.client.Result

Write a file and wait for the result.

See: omni.client.write_file_with_callback()

async omni.client.write_file_async(url: str, content: bytes, message: str = '') → omni.client.Result

Asynchronously Write a file

See: omni.client.write_file_with_callback()

omni.client.write_file_ex(url: str, content: bytes, message: str = '') → Tuple[omni.client.Result, omni.client.WriteFileExInfo]

Write a file (and retrieve extra info) and wait for the result.

See: omni.client.write_file_ex_with_callback()

async omni.client.write_file_ex_async(url: str, content: bytes, message: str = '') → Tuple[omni.client.Result, omni.client.WriteFileExInfo]

Asynchronously Write a file (and retrieve extra info)

See: omni.client.write_file_ex_with_callback()

omni.client.write_file_ex_with_callback(url: str, content: buffer, callback: Callable[[omni.client.Result, omni.client.WriteFileExInfo], None], message: str = None) → omni.client.Request

Create a new file, overwriting if it already exists.

Parameters

• url – URL of file to create.

• content – File content.

• callback – Callback to be called with the result.

• message – Message to apply to atomic checkpoint of destination url.

Returns

Request object.

omni.client.write_file_with_callback(url: str, content: buffer, callback: Callable[[omni.client.Result], None], message: str = None) → omni.client.Request

Create a new file, overwriting if it already exists.

Parameters

• url – URL of file to create.

• content – File content.

• callback – Callback to be called with the result.

• message – Message to apply to atomic checkpoint of destination url.

Returns

Request object.