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.

class orionclient.session.OrionSession(config: orionclient.session.SessionConfig = _Nothing.NOTHING, requests_session: requests.sessions.Session = _Nothing.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)

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: Union[orionclient.types.datasets.Dataset, orionclient.types.files.File, orionclient.types.shards.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: Optional[int] = 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_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: Optional[int] = 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: Optional[Dict[int, int]] = None, request_timeout: int = 60, retry_timeout: int = 3600, backoff_dict: Optional[Dict[int, Tuple[int, int]]] = None, log_failed_headers: bool = False) → requests.sessions.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