Service¶

`Service`	The default Descartes Labs HTTP Service used to communicate with its servers.
`JsonApiService`	A JsonApi oriented default Descateslabs Labs HTTP Service.
`ThirdPartyService`	The default Descartes Labs HTTP Service used for 3rd party servers.
`Session`	The HTTP Session that performs the actual HTTP request.
`JsonApiSession`	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, and 504 for any of the HTTP requests. Note that 429s are retried automatically according to their retry-after headers without us specifying anything here (see the source for urllib3.util.Retry as the API documentation doesn’t make this clear).

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 with Service.set_default_session_class().

Raises:

TypeError – If you try to use a session class that is not derived from Session.

Methods:

`get_default_session_class`()	Get the default session class for `Service`.
`set_default_session_class`(session_class)	Set the default session class for `Service`.

Attributes:

`session`	The session instance used by this service.
`token`	The bearer token used in the requests.

classmethod get_default_session_class()[source]¶

Get the default session class for Service.

Returns:	The default session class, which is `Session` itself or a derived class from `Session`.
Return type:	Session

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.

Parameters:	session_class (class) – The session class to use when instantiating the session. This must be the class `Session` itself or a derived class from `Session`.

property session¶

The session instance used by this service.

Type:	Session

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 with JsonApiService.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_default_session_class`()	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:

`session`	The session instance used by this service.
`token`	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 from `JsonApiService`.
Return type:	JsonApiService

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 the ids_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 in `ids_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 the `data` element. attributes (dict) – The attributes for this resource; this becomes the `attributes` key in the `data` element. id (str, optional) – The optional id for the resource; if provided this becomes the `id` key in the `data` 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 from `JsonApiSession`.

property session¶

The session instance used by this service.

Type:	Session

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.

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, and 504 for any of the HTTP requests. Here we specify 429s explicitly (unlike for the Service class) because we have no guarantee that third party services are consistent about providing a retry-after header.

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 with `ThirdPartyService.set_default_session_class()`.
Raises:	TypeError – If you try to use a session class that is not derived from `Session`.

Methods:

`get_default_session_class`()	Get the default session class for the `ThirdPartyService`.
`set_default_session_class`([session_class])	Set the default session class for `ThirdPartyService`.

classmethod get_default_session_class()[source]¶

Get the default session class for the ThirdPartyService.

Returns:	The default session class, which is `Session` itself or a derived class from `Session`.
Return type:	Session

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.

Parameters:	session_class (class) – The session class to use when instantiating the session. This must be the class `Session` itself or a derived class from `Session`.

class Session(base_url='', timeout=None, retries=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 using set_default_session_class().

Notes

Session is not thread safe due to the Adapter and the connection pool which it uses. Instead, you should ensure that each thread is using it’s own session instead of trying to share one.

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:

`initialize`()	Initialize the `Session` instance
`request`(method, url[, headers])	Sends an HTTP request and emits Descartes Labs specific errors.

initialize()[source]¶

Initialize the Session instance

You can override this method in a derived class to add your own initialization. This method does nothing in the base class.

request(method, url, headers=None, **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. headers (dict) – The Headers to set on the request. 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 indicating proxy authentication was not handled or was invalid. ConflictError – A 409 HTTP response status code was encountered. GoneError – A 410 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.common.http.session.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 using JsonApiService.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:

`initialize`()	Initialize the `Session` instance
`request`(args, *kwargs)	Sends an HTTP request and emits Descartes Labs specific errors.

initialize()[source]¶

Initialize the Session instance

You 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 indicating proxy authentication was not handled or was invalid. 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 to True in the corresponding JsonApiService, the JSONAPI errors will be rewritten in a more human readable format.