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
- create_link(resource)¶
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
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
bool
- 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
- 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
- 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_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_link(link_dict)¶
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
- 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
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
- Raises
InvalidCredentials – If session has invalid credentials
AuthorizationRequired – If session wasn’t authorized to make the request
- 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
BadResponse – If unable to leave the project
ValidationError – If resource is not a Project or new_owner_id is not an int
InvalidCredentials – If session has invalid credentials
AuthorizationRequired – If session wasn’t authorized to make the request
- 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.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
- 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
- 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
InvalidCredentials – If session has invalid credentials
AuthorizationRequired – If session wasn’t authorized to make the request
- 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
InvalidCredentials – If session has invalid credentials
AuthorizationRequired – If session wasn’t authorized to make the request
- 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
This provides you with a method to share resources that are sharable.
- Parameters
- 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
- 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
- Raises
BadResponse – If unable to tag the resource
InvalidCredentials – If session has invalid credentials
AuthorizationRequired – If session wasn’t authorized to make the request
This provides you with a method to unshare resources that have been shared
- Parameters
- 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
- 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
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
InvalidCredentials – If session has invalid credentials
AuthorizationRequired – If session wasn’t authorized to make the request
- 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