Session¶
The Session class can be used to start a new Quantamatics session for a given user to access the Quantamatics API. The Quantamatics API uses JSON Web Tokens to Authorize users on the Quantamatics Platform. Additionally the session class will perform its operations, such as sending API Requests and authorizing users, asynchronously.
The creation of a new session object is akin to initializing a new session of the Quantamatics platform, requiring its own authorization. Upon creating a new session object, the constructor will get any cached API tokens from the operating system before applying caching and compression settings.
Parameters¶
enableCaching¶
A boolean parameter that will set the session setting of enableCaching to True or False. This parameter is True by default.
enableCompression¶
A boolean parameter that will set the session setting of enableCompression to True or False. This parameter is False by default.
Methods¶
getAPIToken()¶
This method will return a String of the Session’s token. This token may have been set during the creation of the session if it was cached on the Quantamatics Platform. Otherwise, the access token can be set using the login() method.
Parameters¶
No parameters are available for the getAPIToken() method
Return Values¶
Returns A String value dependent on the state of the token. If the token was retrieved successfully, the cached token will be returned. Otherwise, no value is returned
Exceptions¶
A QException is raised if the token has either expired or has not been set.
If the token has expired, the message “Token Expired” will be returned as part of the exception
If the Access Token is not set, the message will additionally prompt for the
login()function to be used for setting the Access Token
login()¶
This method utilizes credentials of a username and password to authenticate the user and set an access token for the session. This method needs to be used if the session’s access token was not already set upon the creation of the session.
Parameters¶
user
A String credential used for authentication of a given user. This parameter will be posted on the given API Endpoint within settings.
password
A String credential used for authentication of a given user. This parameter will be posted on the given API Endpoint within settings.
Return Values¶
Returns a Boolean value of True. True means the Authentication succeeded and the Access Token was Set. If the Authentication was unsuccessful, an exception will be raised and no value returned.
Exceptions¶
A QException will be raised for one of the following reasons:
The API Endpoint within the Settings is not defined
A connection to the API endpoint could not be made
Authentication with given credentials was unsuccessful
There was an error accessing the API endpoint
The appropriate message will be attached to the raised exception along with any status codes.
apiWrapper()¶
Provides a streamlined way of accessing the API on the Client side. Will utilize the Caching and Compression settings of the Session along with a dictionary of params to send a get request. The JSON response will be transpiled into a pandas DataFrame object which will then be returned.
Parameters¶
api_relative_path
A String value representing the path relative to the API Endpoint within Settings. Therefore, a concatenation of the endpoint with the relative path will result in the full path.
params
A dictionary value. This value is an empty dictionary by default. Any value within the params that is set to None will be filtered out. Additionally, any boolean params will automatically be converted to a lowercase version, i.e True will become true. This dictionary will be sent as data in a GET request to the full path.
enableCompressionOverride
This value will be used to create the headers dictionary. If this value is set to True, the header Accept-Encoding will be set to ‘gzip, deflate, br’ otherwise, this value is set to None.
The enableCompressionOverride parameter is set to None by default and will be set to the Session’s setting before its use in the headers dictionary.
enableCachingOverride
This value will be used to create the headers dictionary. If this value is set to True, the header ‘Cache-Control’ will be set to ‘gzip, deflate, br’ otherwise, this value is set to None.
The enableCachingOverride parameter is set to None by default and will be set to the Session’s setting before its use in the headers dictionary.
Return Values¶
Returns a pandas DataFrame object. This DataFrame is made from the JSON value obtained by the GET request with the given params and headers. If there are no records in the DataFrame, it will still be returned with an empty column.
Exceptions¶
A QException will be raised for the following reasons:
There was an authentication error (Status code 401)
There was a general error on the client’s side (Status code 400)
There was an error on accessing the endpoint (Status code 5XX)
An error arose upon encoding JSON data (Status code 5XX)
The API response provided an unknown type for the DataFrame object (Status code 5XX)
The appropriate message will be attached to the raised exception along with any status codes.
handleRequest()¶
Provides a streamlined way of accessing the API on the Client side. Will utilize the Caching and Compression settings of the Session along with a dictionary of params to send a get request. The JSON response will be transpiled into a pandas DataFrame object which will then be returned.
Parameters¶
api_relative_path
A String value representing the path relative to the API Endpoint. A concatenation of the endpoint with the relative path will result in the full path.
params
A dictionary value. This value is an empty dictionary by default. Any value within the params that is set to None will be filtered out. Additionally, any boolean params will automatically be converted to a lowercase version, i.e True will become true. This dictionary will be sent as data in a GET request to the full path.
enableCompressionOverride
This value will be used to create the headers dictionary. If this value is set to True, the header Accept-Encoding will be set to ‘gzip, deflate, br’ otherwise, this value is set to None.
The enableCompressionOverride parameter is set to None by default and will be set to the Session’s setting before its use in the headers dictionary.
enableCachingOverride
This value will be used to create the headers dictionary. If this value is set to True, the header ‘Cache-Control’ will be set to ‘gzip, deflate, br’ otherwise, this value is set to None.
The enableCachingOverride parameter is set to None by default and will be set to the Session’s setting before its use in the headers dictionary.
params_type
A string value that dictates the type of parameters that are being passed. May either be URL or JSON. If no value is passed, params_type will be URL by default.
A QException will be raised if a value is passed that is neither URL nor JSON.
method_type
A string value that dictates the type of method being performed onto the API. Default value of this parameter will be GET.
Return Values¶
Returns a pandas DataFrame object. This DataFrame is made from the JSON value obtained by the GET request with the given params and headers. If there are no records in the DataFrame, it will still be returned with an empty column.
Exceptions¶
A QException will be raised for the following reasons:
There was an authentication error (Status code 401)
There was a general error on the client’s side (Status code 400)
There was an error on accessing the endpoint (Status code 5XX)
An error arose upon encoding JSON data (Status code 5XX)
The API response provided an unknown type for the DataFrame object (Status code 5XX)
The appropriate message will be attached to the raised exception along with any status codes.