Service¶
The default Descartes Labs HTTP Service used to communicate with its servers. |
|
A JsonApi oriented default Descateslabs Labs HTTP Service. |
|
The default Descartes Labs HTTP Service used for 3rd party servers. |
|
The HTTP Session that performs the actual HTTP request. |
|
The HTTP Session that performs the actual JSONAPI HTTP request. |
-
class
Service
(url, token=None, auth=None, retries=None, session_class=None)[source]¶ The default Descartes Labs HTTP Service used to communicate with its servers.
This service has a default timeout and retry policy that retries HTTP requests depending on the timeout and HTTP status code that was returned. This is based on the requests timeouts and the urllib3 retry object.
The default timeouts are set to 9.5 seconds for establishing a connection (slightly larger than a multiple of 3, which is the TCP default packet retransmission window), and 30 seconds for reading a response.
The default retry logic retries up to 3 times total, a maximum of 2 for establishing a connection, 2 for reading a response, and 2 for unexpected HTTP status codes. The backoff_factor is a random number between 1 and 3, but will never be more than 2 minutes. The unexpected HTTP status codes that will be retried are
500
,502
,503
, and504
for any of the HTTP requests.- Parameters
url (str) – The URL prefix to use for communication with the Descartes Labs server.
token (str, optional) – Deprecated.
auth (Auth, optional) – A Descartes Labs
Auth
instance. If not provided, a default one will be instantiated.retries (int or urllib3.util.retry.Retry) – If a number, it’s the number of retries that will be attempled. If a
urllib3.util.retry.Retry
instance, it will determine the retry behavior. If not provided, the default retry policy as described above will be used.session_class (class) – The session class to use when instantiating the session. This must be a derived class from
Session
. If not provided, the default session class is used. You can register a default session class withService.set_default_session_class()
.
- Raises
TypeError – If you try to use a session class that is not derived from
Session
.
Methods
Get the default session class for
Service
.set_default_session_class
(session_class)Set the default session class for
Service
.Attributes
The session instance used by this service.
The bearer token used in the requests.
-
classmethod
set_default_session_class
(session_class)[source]¶ Set the default session class for
Service
.The default session is used for any
Service
that is instantiated without specifying the session class.
-
property
token
¶ The bearer token used in the requests.
- Type
str
-
class
JsonApiService
(url, session_class=None, rewrite_errors=False, **kwargs)[source]¶ Bases:
descarteslabs.client.services.service.service.Service
A JsonApi oriented default Descateslabs Labs HTTP Service.
For details see the
Service
. This service adheres to the JsonApi standard and interprets responses as needed.This service uses the
JsonApiSession
which provides some optional functionality.- Parameters
url (str) – The URL prefix to use for communication with the Descartes Labs servers.
session_class (class) – The session class to use when instantiating the session. This must be a derived class from
JsonApiSession
. If not provided, the default session class is used. You can register a default session class withJsonApiService.set_default_session_class()
.rewrite_errors (bool) – When set to
True
, errors are rewritten to be more readable. Each JsonApi error becomes a single line of error information without tags.auth (Auth, optional) – A Descartes Labs
Auth
instance. If not provided, a default one will be instantiated.retries (int or urllib3.util.retry.Retry If a number, it's the number of retries) – that will be attempled. If a
urllib3.util.retry.Retry
instance, it will determine the retry behavior. If not provided, the default retry policy as described above will be used.
- Raises
TypeError – If you try to use a session class that is not derived from
JsonApiSession
.
Methods
Get the default session class for
JsonApiService
.jsonapi_collection
(type, attributes_list[, …])Return a JsonApi document with a collection of resources.
jsonapi_document
(type, attributes[, id])Return a JsonApi document with a single resource.
set_default_session_class
(session_class)Set the default session class for
JsonApiService
.Attributes
The session instance used by this service.
The bearer token used in the requests.
-
classmethod
get_default_session_class
()[source]¶ Get the default session class for
JsonApiService
.- Returns
The default session class, which is
JsonApiService
itself or a derived class fromJsonApiService
.- Return type
-
static
jsonapi_collection
(type, attributes_list, ids_list=None)[source]¶ Return a JsonApi document with a collection of resources.
The number of elements in the
attributes_list
must be identical to the number of elements in theids_list
.A JsonApi collection has the following structure:
{ "data": [ { "type": "...", "id": "...", // Optional "attributes": { "...": "...", ... } }, { ... }, { ... ] }
- Parameters
type (str) – The type of resource; this becomes the
type
key for each resource in the collection. The JsonApi collection contains resources of the same type.attributes (list(dict)) – A list of attributes for each resource; this becomes the
attributes
key for each resource in the collection.id (list(str), optional) – The optional id for the resource; if provided this becomes the
id
key for each resource in the collection.
- Returns
A dictionary representing the JsonApi document with
data
as the top-level key, which itself contains a list of resources.- Return type
dict
- Raises
ValueError – If the number of elements in
attributes_list
differs from the number of elements inids_list
.
-
static
jsonapi_document
(type, attributes, id=None)[source]¶ Return a JsonApi document with a single resource.
A JsonApi document has the following structure:
{ "data": { "type": "...", "id": "...", // Optional "attributes": { "...": "...", ... } } }
- Parameters
type (str) – The type of resource; this becomes the
type
key in thedata
element.attributes (dict) – The attributes for this resource; this becomes the
attributes
key in thedata
element.id (str, optional) – The optional id for the resource; if provided this becomes the
id
key in thedata
element.
- Returns
A dictionary representing the JsonApi document with
data
as the top-level key, which itself contains a single resource.- Return type
dict
-
classmethod
set_default_session_class
(session_class)[source]¶ Set the default session class for
JsonApiService
.The default session is used for any
JsonApiService
that is instantiated without specifying the session class.- Parameters
session_class (class) – The session class to use when instantiating the session. This must be the class
JsonApiSession
itself or a derived class fromJsonApiSession
.
-
property
token
¶ The bearer token used in the requests.
- Type
str
-
class
ThirdPartyService
(url='', session_class=None)[source]¶ The default Descartes Labs HTTP Service used for 3rd party servers.
Methods
Get the default session class for the
ThirdPartyService
.set_default_session_class
([session_class])Set the default session class for
ThirdPartyService
.This service has a default timeout and retry policy that retries HTTP requests depending on the timeout and HTTP status code that was returned. This is based on the requests timeouts and the urllib3 retry object.
The default timeouts are set to 9.5 seconds for establishing a connection (slightly larger than a multiple of 3, which is the TCP default packet retransmission window), and 30 seconds for reading a response.
The default retry logic retries up to 10 times total, a maximum of 2 for establishing a connection. The backoff_factor is a random number between 1 and 3, but will never be more than 2 minutes. The unexpected HTTP status codes that will be retried are
429
,500
,502
,503
, and504
for any of the HTTP requests.- Parameters
url (str) – The URL prefix to use for communication with the 3rd party server.
session_class (class) – The session class to use when instantiating the session. This must be a derived class from
Session
. If not provided, the default session class is used. You can register a default session class withThirdPartyService.set_default_session_class()
.
- Raises
TypeError – If you try to use a session class that is not derived from
Session
.
-
classmethod
get_default_session_class
()[source]¶ Get the default session class for the
ThirdPartyService
.
-
classmethod
set_default_session_class
(session_class=None)[source]¶ Set the default session class for
ThirdPartyService
.The default session is used for any
ThirdPartyService()
that is instantiated without specifying the session class.
-
class
Session
(base_url, timeout=None)[source]¶ The HTTP Session that performs the actual HTTP request.
This is the base session that is used for all Descartes Labs HTTP calls which itself is derived from requests.Session.
You cannot control its instantiation, but you can derive from this class and pass it as the class to use when you instantiate a
Service
or register it as the default session class usingService.set_default_session_class()
.- Parameters
base_url (str) – The URL prefix to use for communication with the Descartes Labs servers.
timeout (int or tuple(int, int)) –
See requests timeouts.
Methods
handle_proxy_authentication
(method, url, …)Handle proxy authentication when the HTTP request was denied.
Initialize the
Session
instancerequest
(method, url, **kwargs)Sends an HTTP request and emits Descartes Labs specific errors.
-
handle_proxy_authentication
(method, url, **kwargs)[source]¶ Handle proxy authentication when the HTTP request was denied.
This method can be overridden in a derived class. By default a
ProxyAuthenticationRequiredError
will be raised.- Returns
Return True if the proxy authentication has been handled and no further exception should be raised. Return False if a
ProxyAuthenticationRequiredError
should be raised.- Return type
bool
-
initialize
()[source]¶ Initialize the
Session
instanceYou can override this method in a derived class to add your own initialization. This method does nothing in the base class.
-
request
(method, url, **kwargs)[source]¶ Sends an HTTP request and emits Descartes Labs specific errors.
- Parameters
method (str) – The HTTP method to use.
url (str) – The URL to send the request to.
kwargs (dict) – Additional arguments. See requests.request.
- Returns
A
request.Response
object.- Return type
Response
- Raises
BadRequestError – Either a 400 or 422 HTTP response status code was encountered.
NotFoundError – A 404 HTTP response status code was encountered.
ProxyAuthenticationRequiredError – A 407 HTTP response status code was encountered and the resulting
handle_proxy_authentication()
did not indicate that the proxy authentication was handled.ConflictError – A 409 HTTP response status code was encountered.
RateLimitError – A 429 HTTP response status code was encountered.
GatewayTimeoutError – A 504 HTTP response status code was encountered.
ServerError – Any HTTP response status code larger than 400 that was not covered above is returned as a ServerError. The original HTTP response status code can be found in the attribute
original_status
.
-
class
JsonApiSession
(*args, **kwargs)[source]¶ Bases:
descarteslabs.client.services.service.service.Session
The HTTP Session that performs the actual JSONAPI HTTP request.
You cannot control its instantiation, but you can derive from this class and pass it as the class to use when you instantiate a
JsonApiService
or register it as the default session class usingJsonApiService.set_default_session_class()
.- Parameters
base_url (str) – The URL prefix to use for communication with the Descartes Labs servers.
timeout (int or tuple(int, int)) –
See requests timeouts.
Methods
handle_proxy_authentication
(method, url, …)Handle proxy authentication when the HTTP request was denied.
Initialize the
Session
instancerequest
(*args, **kwargs)Sends an HTTP request and emits Descartes Labs specific errors.
-
handle_proxy_authentication
(method, url, **kwargs)[source]¶ Handle proxy authentication when the HTTP request was denied.
This method can be overridden in a derived class. By default a
ProxyAuthenticationRequiredError
will be raised.- Returns
Return True if the proxy authentication has been handled and no further exception should be raised. Return False if a
ProxyAuthenticationRequiredError
should be raised.- Return type
bool
-
initialize
()[source]¶ Initialize the
Session
instanceYou can override this method in a derived class to add your own initialization. This method does nothing in the base class.
-
request
(*args, **kwargs)[source]¶ Sends an HTTP request and emits Descartes Labs specific errors.
- Parameters
method (str) – The HTTP method to use.
url (str) – The URL to send the request to.
kwargs (dict) –
Additional arguments. See requests.request.
- Returns
A
request.Response
object.- Return type
Response
- Raises
BadRequestError – Either a 400 or 422 HTTP response status code was encountered.
NotFoundError – A 404 HTTP response status code was encountered.
ProxyAuthenticationRequiredError – A 407 HTTP response status code was encountered and the resulting
handle_proxy_authentication()
did not indicate that the proxy authentication was handled.ConflictError – A 409 HTTP response status code was encountered.
RateLimitError – A 429 HTTP response status code was encountered.
GatewayTimeoutError – A 504 HTTP response status code was encountered.
ServerError – Any HTTP response status code larger than 400 that was not covered above is returned as a ServerError. The original HTTP response status code can be found in the attribute
original_status
.
Note
If
rewrite_errors
was set toTrue
in the correspondingJsonApiService
, the JSONAPI errors will be rewritten in a more human readable format.