Orion Client Session

The bulk of the interactions with Orion should be done using the OrionSession object that performs all of the HTTP calls necessary to get and update data using the Orion RESTful API.

For most cases users will want to use orionclient.session.APISession which is a pre-configured OrionSession rather than creating their own.

Copyright (C) 2023 Cadence Design Systems, Inc. (Cadence)

class orionclient.session.OrionSession(config: SessionConfig = NOTHING, orion_versions=None, requests_session: Session = NOTHING)

An HTTP Session authenticated against Orion for getting and creating Orion Resources.

assign_paths(*assignments: Dict[str, Any])

Assigns a path to each assignment in assignments.

For each assignment, the fields resource_type, id, and path arguments are required. A name may also be supplied, which will overwrite the item’s previous name within the folder.

Parameters:

assignments (list<dict>) – A list where each object will be assigned to its path

Returns:

None

Constructs a serializable link that can be used to reference an Orion resource, and can be stored in a record of type Link. Later, get_link can use the serialized link to create a Link object that can retrieve the Orion resource.

Parameters:

resource (Types) – A resource to create a link to

Returns:

Link Object

Return type:

dict

create_paths(*paths)

Create the specified paths on Orion

Returns:

None

Parameters:

paths (list<string>) – Paths to create

create_resource(resource_type, params=None, files=None)

A method to create Orion instances of the Types classes, the params and files are the inputs expected by the RESTful API.

Parameters:

  • resource_type (class) – A class from types

  • params (dict) – Parameters to create the resource with

  • files (dict) – Files to create resource with

Returns:

An instance of the resource type

Return type:

resource

Raises:
delete_resource(resource, immediate: bool = False)

Deletes the resource from the Orion API

Parameters:

resource (class) – An instance of an OrionClient type

Returns:

Whether it succeeded or not

Return type:

bool

Raises:
get_current_balance()

Retrieves the current balance for the organization.

Requires the organization cost accounting capability to access

Return type:

CurrentBalance

Raises:
get_current_project()

Retrieves the details about the project the Session is configured with.

Returns:

Instance of the current Project

Return type:

Project

Raises:
get_default_output_folder() → str

Returns the default folder for a user, which is the user’s ‘My Data’ within the profile’s configured project.

Get a link object from a serialized link. The link object can be used to retrieve the resource that it links to.

Parameters:

link_dict (dict) – The dictionary that represents a link

Raises:

OrionLinkError – Link is invalid

Returns:

Link Object

Return type:

OrionLink, RecordLink, ShardLink

get_paths(*items: Dataset | File | ShardCollection) → dict

List the paths corresponding to specified items.

Returns:

dictionary of results

Return type:

dict

Parameters:

items – A list of Dataset, File, and ShardCollection objects

Note

a mixture of files, datasets, and collections are returned in a single response. Each entry will contain a resource_type key to define its type.

get_resource(resource_type, resource_id, timeout=None)

When you want to instantiate an Orion resource that already exists you would use get_resource to construct that instance, specifying the type and identifier of the resource.

Parameters:

  • resource_type (class) – A class from types

  • resource_id (int) – Identifier of the resource

  • timeout (int) – Time to spend getting a resource, best effort timeout

Returns:

An instance of the resource type

Return type:

resource_type

Raises:
get_user_profile()

Retrieves the details about the user the Session is configured with.

Returns:

Instance of the current User

Return type:

UserProfile

Raises:
is_authenticated(reconnect: bool = False) → bool

Notifies the user of whether the Session is authenticated against Orion, either performing a lightweight configuration check or manual session validation. :param reconnect: Option to perform an http request to check if session’s authentication works. If false, only configuration credentials are checked. :type reconnect: bool

Return type:

bool

leave_project(resource, new_owner_id: int | None = None)

This provides you with a method to leave a project

Parameters:

resource (Types) – An instance from types

Raises:
list_resources(resource, filters=None)

Takes a resource class and provides you with an iterator of the resource type.

Warning

Objects returned are not necessarily complete, need to call refresh_resource on the objects to get the full object.

Parameters:

  • resource (class) – A class from types

  • filters (dict) – Query parameters to filter with

Returns:

Iterator of resource_types

Return type:

iter<resource_type>

Raises:

The following example shows how to find the most recent workfloe with a given title.

from orionclient.session import APISession
from orionclient.types import WorkFloeSpec

# Find a WorkFloe spec with the specified title that is ready (as opposed to deprecated)
# Note: the title match will be an inexact match
filters = {"title": "Classic Omega", "state": "ready"}
for workfloe in APISession.list_resources(WorkFloeSpec, filters=filters):
    print(workfloe)

# There could be many that match this filter, so more work should be done to ensure
# the correct WorkFloe specification was found. For example, if the WorkFloe specification
# has a UUID, then it can be used

# Refresh to get the full specification
APISession.refresh_resource(workfloe)
print(workfloe)

Download code

find_workfloe.py

list_shares(resource, resource_id)

Lists the sharing status for the Orion resource

Parameters:

  • resource (class) – A class from types

  • resource_id (int) – Identifier of the resource

Raises:
Returns:

Iterator of Dictionaries that represent sharing status

list_tags(resource)

Lists the tags that are attached to a taggable resource

Parameters:

resource (Types) – A instance from types

Raises:
Returns:

Iterator of Dictionaries that represent tags

ls_path(path, query_params=None)

List the contents of a folder.

Returns:

dictionary of results

Return type:

dict

Parameters:

  • path (str) – path to list contents or search

  • query_params (dict) – api parameters to filter the ls results. Valid key/value pairs are as: | ‘path’ : ‘/path/on/Orion’ | ‘name’ : ‘name_of_resource’ | ‘name_contains’ : ‘string_that_name_must_contain’ | ‘name_icontains’ : ‘string_in_name_ignore_case’ | ‘order_by’ : ‘created’ # or other valid resource attribute’ | ‘types’ : ‘dataset’ # or dataset or file | ‘tag_filters’ : ‘Job <job_id>’ # or other tag | ‘systag_filters’ : ‘3D’ # or other system tag | ‘list’ : ‘data’ OR ‘list’ : ‘folders’ | ‘limit’ : 250 # Or any integer (default 250)

Note

a mixture of files, datasets, and collections are returned in a single response. Each entry will contain a resource_type key to define its type.

refresh_resource(resource)

Takes a resource and refreshes its attributes from Orion

Parameters:

resource (class) – An instance of an OrionClient type

Raises:
refresh_resource_until(resource, attribute: str, until_value: Any, timeout: int = 60, sleep_time: int = 1, debug_log: bool = True, not_match: bool = False)

Takes a resource and refreshes its attributes from Orion until the attribute matches a desired value or until a certain time

Parameters:

  • resource (class) – An instance of an OrionClient type

  • attribute (string) – Name of an attribute on the resource

  • until_value – The desired value of an attribute

  • timeout (int) – The maximum amount of time to wait for the desired state

  • sleep_time (int) – The amount of time to wait between refreshes

  • debug_log (bool) – Add debug logs

  • not_match (bool) – Return if the value of the given attribute is not equal to until_value

Raises:
remove_paths(*paths)

Delete the specified paths on Orion

Returns:

None

Parameters:

paths (list<string>) – Paths to delete

retrieve_token(username, password)

Method that takes a username and password and returns an Orion Token. The token should be set as the ‘Authorization’ header in the form, ‘Token:<token-value>’

Parameters:

  • username (string) – Username of user to retrieve token of

  • password (string) – User’s password

Returns:

Orion Token

Return type:

string

share_resource(resource, share_with, permissions=None)

This provides you with a method to share resources that are sharable.

Parameters:

  • resource (Types) – An instance from types

  • share_with (Types) – OrionUser, Project to share resource with

  • permissions (list) – Permissions to share with, read, write, delete, share, default is read

Raises:
stat_path(path)

Determine object type by path

Returns:

details of the object (ID, resource_type, path)

Return type:

dict

Parameters:

path (string) – The path to the object

tag_resource(resource, *tags, project=None)

This provides you with a method to tag the resources that are taggable.

Parameters:

  • resource (Types) – A instance from types

  • tags (list<string>) – String to tag resource with

  • project (Project) – The project the tag should to belong to

Raises:
unshare_resource(resource, share_with, new_owner_id: int | None = None)

This provides you with a method to unshare resources that have been shared

Parameters:

  • resource (Types) – An instance from types

  • share_with (Types) – OrionUser, Project to share resource with

Raises:
untag_resource(resource, *tags, project=None)

This provides you with a method to untag taggable resources.

If a resource does not contain the tag that is removed, the server will silently ignore the tag.

Parameters:

  • resource (Types) – A instance from types

  • tags (list<string>) – Tag to remove from resource

  • project (Project) – The project the tag belongs to (currently ignored)

Raises:
update_resource(resource, params)
Takes a resource, updates it on Orion, and refreshes its attributes

This does not handle folder path, so use assign_paths if you need to update or set a path.

Parameters:

  • resource (class) – An instance of an OrionClient type

  • params (dict) – Parameters to update on the resource

Raises:
validate_authentication() → bool

Checks whether Session is authenticated against Orion by performing an API request

Return type:

bool

orionclient.session.in_orion()

A function that can be used to tell if the code is being running inside of Orion or from outside orion

orionclient.session.get_profile_config(profile=None)

Retrieve the SessionConfig for a specific Orion profile configuration. If this is in Orion, this will always return the same configuration

You can setup a OrionSession with the config by doing the following

session = OrionSession(config=get_profile_config())
orionclient.session.get_session(retry_dict: Dict[int, int] | None = None, request_timeout: int = 60, retry_timeout: int = 3600, backoff_dict: Dict[int, Tuple[int, int]] | None = None, log_failed_headers: bool = False) → Session

This creates a session using the Retryable class, which contains a dictionary mapping HTTP Status Codes to some number of retries, so upon receiving a response in the set of retryable codes, it will retry whatever number of times specified in the retry_dict or until retry_timout is reached.

It is inadvisable to set the request_timeout below 60 seconds when communicating with Orion because there is a load balancer timeout of 60 and a database statement timeout of 30.

Parameters:

  • retry_dict (dict) – number of attempts for different HTTP status codes. status_code –> #retries

  • request_timeout (int) – seconds to wait for a response to a request

  • retry_timeout (int) – maximum number of seconds to keep retrying

  • backoff_dict (dict) – status_code –> (backoff_base_seconds, backoff_cap_seconds)

  • log_failed_headers (bool) – print headers useful for AWS support

Return type:

Session

Example:

from orionclient.session import get_session

unauthed_session = get_session(
    {400: 3, 404: 3, 500: 3}, request_timeout=10, retry_timeout=600
)
resp = unauthed_session.get("https://www.eyesopen.com")

Download code

backoff_session.py