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 APISession which is a pre-configured OrionSession rather than creating their own.

class orionclient.session.OrionSession(config=NOTHING, requests_session=NOTHING, is_authenticated: bool = None)

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

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:dictionary
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:
  • InvalidCredentials – If session has invalid credentials
  • AuthorizationRequired – If session wasn’t authorized to make the request
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:

boolean
Raises:
  • InvalidCredentials – If session has invalid credentials
  • AuthorizationRequired – If session wasn’t authorized to make the request
get_current_balance()

Retrieves the current balance for the organization.

Requires the organization cost accounting capability to access

Return type:

CurrentBalance
Raises:
  • BadResponse – Don’t have the capability to get the balance
  • InvalidCredentials – If session has invalid credentials
  • AuthorizationRequired – If session wasn’t authorized to make the request
get_current_project()

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

Returns:

Instance of the current Project
Return type:

Project
Raises:
  • InvalidCredentials – If session has invalid credentials
  • InvalidCredentials – If the session profile doesn’t have a project configured
  • AuthorizationRequired – If session wasn’t authorized to make the request

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_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 (integer) – Identifier of the resource
  • timeout (integer) – Time to spend getting a resource, best effort timeout
Returns:

An instance of the resource type
Return type:

resource_type
Raises:
  • InvalidCredentials – If session has invalid credentials
  • AuthorizationRequired – If session wasn’t authorized to make the request
get_user_profile()

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

Returns:

Instance of the current User
Return type:

UserProfile
Raises:
  • InvalidCredentials – If session has invalid credentials
  • AuthorizationRequired – If session wasn’t authorized to make the request
is_authenticated(reconnect=False)

Notifies the user of whether the Session is authenticated against Orion

Return type:boolean
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:
  • InvalidCredentials – If session has invalid credentials
  • AuthorizationRequired – If session wasn’t authorized to make the request

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

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

# 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:
  • BadResponse – Unable to handle tag request
  • ValidationError – If the resource is not taggable
  • InvalidCredentials – If session has invalid credentials
  • AuthorizationRequired – If session wasn’t authorized to make the request
Returns:

Iterator of Dictionaries that represent tags
refresh_resource(resource)

Takes a resource and refreshes its attributes from Orion

Parameters:

resource (class) – An instance of an OrionClient type
Raises:
  • InvalidCredentials – If session has invalid credentials
  • AuthorizationRequired – If session wasn’t authorized to make the request
refresh_resource_until(resource, attribute, until_value, timeout=60, sleep_time=1)

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
  • 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
Raises:
  • InvalidCredentials – If session has invalid credentials
  • AuthorizationRequired – If session wasn’t authorized to make the request
retrieve_token(username, password)

Method that takes a username and password and returns an Orion Token. The token should be set as 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:
  • BadResponse – If unable to share the resource
  • ValidationError – If invalid share_with value
  • ValidationError – If resource or share_with id is not an integer
  • InvalidCredentials – If session has invalid credentials
  • AuthorizationRequired – If session wasn’t authorized to make the request
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:
  • BadResponse – If unable to tag the resource
  • InvalidCredentials – If session has invalid credentials
  • AuthorizationRequired – If session wasn’t authorized to make the request
unshare_resource(resource, share_with)

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:
  • BadResponse – If unable to unshare the resource
  • ValidationError – If invalid share_with value
  • ValidationError – If resource or share_with id is not an int
  • InvalidCredentials – If session has invalid credentials
  • AuthorizationRequired – If session wasn’t authorized to make the request
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:
  • BadResponse – If unable to remove a tag from the resource
  • InvalidCredentials – If session has invalid credentials
  • AuthorizationRequired – If session wasn’t authorized to make the request
update_resource(resource, params)

Takes a resource, updates it on Orion, and refreshes its attributes

Parameters:
  • resource (class) – An instance of an OrionClient type
  • params (dict) – Parameters to update on the resource
Raises:
  • InvalidCredentials – If session has invalid credentials
  • AuthorizationRequired – If session wasn’t authorized to make the request
orionclient.session.in_orion()

A function that can be used to tell if the code is being running inside of Orion or from outside of 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: Union[Dict[int, int], NoneType] = None, request_timeout: int = 60, retry_timeout: int = 300, backoff_dict: Union[Dict[int, Tuple[int, int]], NoneType] = None)

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)

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