HTTP

ProxyAuthentication	Provides a common interface to handle proxies and authentication between HTTP and GRPC.
Session	The HTTP Session that performs the actual HTTP request.
HTTPAdapter	Custom HTTPAdapter to integrate ProxyAuthentication with requests.

class ProxyAuthentication

Provides a common interface to handle proxies and authentication between HTTP and GRPC.

See ProxyAuthentication.authorize() for more information.

class Protocol

Protocols supported by ProxyAuthentication.

GRPC

gRPC protocol.

Type:enum

HTTP

HTTP Protocol.

Type:enum

HTTPS

HTTPS Protocol.

Type:enum

abstract authorize(proxy: str, protocol: descarteslabs.common.http.proxy.ProxyAuthentication.Protocol) → dict

This method is used to authorize an HTTP, HTTPS, or GRPC connection to a service.

If you are attempting to use basic auth, you should include your username and password in the proxy URL. In this case, you do not need to implement this interface.

proxy = "http://user:pass@someproxy:8080"
os.environ["HTTPS_PROXY"] = proxy
# OR
ProxyAuthentication.set_proxy(proxy, ProxyAuthentication.Protocol.HTTPS)
ProxyAuthentication.set_proxy(proxy, ProxyAuthentication.Protocol.GRPC)
# OR
ProxyAuthentication.set_proxy(proxy) # sets all known protocols

If you are implementing this interface, you should return a dictionary with the headers as the keys and any string values that should be sent.

class MyProxyAuth(ProxyAuthentication)
    def __init__(self, client_id: str = None, secret: str = None):
        self.client_id = client_id
        self.secret = secret

    def authorize(self, proxy: str, protocol: str) -> dict:
        # Here you could use the instance variables to fetch a new key.
        # Or whatever implementation you desire.

        return {
            "some-header": "some value",
            "x-api-key": "123456",
        }

ProxyAuthentication.register(MyProxyAuth)
# OR
ProxyAuthentication.register(MyProxyAuth("some-client-id", "some-secret"))

Parameters:

• proxy (str) – The URL of the proxy that was selected for the connection.
• protocol (Protocol) – The Protocol that will be used for requests across the proxy after the connection is established.

Notes

For HTTP (urls starting with http://):

Authorize is called for every HTTP request.

The returned headers are merged with the original request headers.

For HTTPS (urls starting with https://) and GRPC:

Authorize is called for the initial CONNECT request for the underlying socket to the proxy server.

The returned headers will not be present on any requests through the established connection to prevent data leaking.

For HTTPS Proxies (proxy urls starting with https://) and GRPC:

Unless your proxy is signed by a third party Certificate Authority, you will need to configure a CA certificate.

This can be done at the system level or through the CURL_CA_BUNDLE or REQUESTS_CA_BUNDLE environment variable.

classmethod clear_proxy(protocol: descarteslabs.common.http.proxy.ProxyAuthentication.Protocol = None)

Clears a proxy that was defined by set_proxy.

If no protocol is specified, all programmatically specified proxies will be cleared. This will result in environment variables being used instead.

Parameters:protocol (Protocol) – The Protocol for which to clear the proxy configuration.

classmethod get_proxies()

Returns a dictionary of the configured proxy for each protocol.

User defined proxies will take precedence over default environment vars.

classmethod get_proxy(protocol: descarteslabs.common.http.proxy.ProxyAuthentication.Protocol) → str

Determines the proxy to use for a given protocol.

Attempts to use user defined proxies and fallsback to proxies defined by environment variables.

Parameters:protocol (Protocol) – The Protocol for which to retrieve the proxy URL.

get_verified_headers(proxy: str, protocol: descarteslabs.common.http.proxy.ProxyAuthentication.Protocol) → dict

Calls authorize and verifies the returned headers.

Intended to be used to retrieve the headers instead of calling py:meth:ProxyAuthentication.authorize directly.

Parameters:

• proxy (str) – The URL of the proxy that was selected for the connection.
• protocol (Protocol) – The Protocol that will be used for requests across the proxy after the connection is established.

Raises:

TypeError – When ProxyAuthentication.authorize() returns a type that is not a dictionary.

classmethod register(implementation: Union[type, ProxyAuthentication])

Registers a proxy authentication implementation.

Parameters:implementation (Union[type, ProxyAuthentication]) – An instance or subclass type of ProxyAuthentication.

classmethod set_proxy(proxy: str, protocol: descarteslabs.common.http.proxy.ProxyAuthentication.Protocol = None)

Configures a proxy for a given protocol.

If no protocol is specified, all known protocols will be configured to use the specified proxy.

Parameters:

• proxy (str) – The URL of the proxy.
• protocol (Protocol) – The Protocol that should be modified to use the specified proxy.

class Session(base_url='', timeout=None, retries=None)

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.

initialize()

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)

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 HTTPAdapter(pool_connections=10, pool_maxsize=10, max_retries=0, pool_block=False)

Custom HTTPAdapter to integrate ProxyAuthentication with requests.

get_connection(url, proxies=None)

Copied from requests.adapters.HTTPAdapter to pass request url to proxy_manager_for()

Parameters:

• url (str) – The request URL.
• proxies (Optional[dict]) – The proxies configured for this request.

proxy_headers(proxy: str, url: str = None)

Sets headers used for the connection to the proxy.

Parameters:

• proxy (str) – The proxy URL.
• url (Optional[str]) – The request URL.

Note

If the URL starts with http://, the headers are merged with the request headers.

proxy_manager_for(proxy, url=None, **proxy_kwargs)

Copied from requests.adapters.HTTPAdapter to pass request url to proxy_headers()

Parameters:

• proxy (str) – The selected proxy for the request.
• url (str) – The URL of the request.
• proxy_kwargs (dict) – Additional request arguments see requests.adapter.HTTPAdapter.proxy_manager_for().

send(request: requests.models.PreparedRequest, proxies=None, **kwargs) → requests.models.Response

Override the base send method of the adapter to be able to specify proxies from ProxyAuthentication.

Parameters:

• request (requests.PreparedRequest) – The prepared request to send.
• proxies (dict) – The proxies to use for the request.
• kwargs (dict) – Additional request arguments see requests.adapter.HTTPAdapter.send().