Installation

Note

We strongly suggest to use a virtual environment such as Conda to work with the Descartes Labs Platform. For more information please see Managing a Development Environment.

Install the latest client library via pip

pip install descarteslabs

This base version will not include support for interactive features (maps and graphs in a notebook environment), nor does it include the new Tables client.

To install with support for the interactive features:

pip install "descarteslabs[visualization]"

To install with support for the Tables client:

pip install "descarteslabs[tables]"

To install with all features and dependencies:

pip install "descarteslabs[complete]"

Note

tables will install geopandas (https://geopandas.org/en/stable/) as a dependency by default on linux installations and skip its installation otherwise. If geopandas has not been previously installed on a non-linux system, then pandas will be used. See the installation instructions (https://geopandas.org/en/stable/getting_started/install.html#installing-with-pip) for more information on installing on non-linux systems.

The latest development version can always be found on GitHub. It can be installed via pip

pip install -U git+https://github.com/descarteslabs/descarteslabs-python.git

Windows Users

The client library requires shapely, which can be hard to install on Windows with pip.

We recommended using Anaconda to first install shapely. If you’re unfamiliar with conda, check out the document on development environments for recommendations.

conda install shapely
pip install descarteslabs

Using a Firewall Proxy

If your company uses a firewall proxy, you can set environment variables to point at your company’s proxy server:

$ export HTTP_PROXY="http://10.10.1.10:8080"
$ export HTTPS_PROXY="http://10.10.1.10:8443"

# Setting GRPC is optional, it will fallback to using HTTPS_PROXY
$ export GRPC_PROXY="http://10.10.1.11:8888"

Or if you also need to specify a username/password:

$ export HTTP_PROXY="http://user:pass@10.10.1.10:8080"
$ export HTTPS_PROXY="http://user:pass@10.10.1.10:8443"

# Setting GRPC is optional, it will fallback to using HTTPS_PROXY
$ export GRPC_PROXY="http://user:pass@10.10.1.10:8888"

Proxies can also be specified for each protocol using our ProxyAuthentication class. If a proxy is specified here, it will take priority over the environment variables HTTP_PROXY, HTTPS_PROXY, and GRPC_PROXY

from descarteslabs.common.http import ProxyAuthentication

# sets the proxy for all protocols
ProxyAuthentication.set_proxy("http://10.10.1.10:8080")

# Or
ProxyAuthentication.set_proxy("http://user:pass@some-proxy:8080", "http")
ProxyAuthentication.set_proxy("http://user:pass@some-proxy:8443", "https")
ProxyAuthentication.set_proxy("http://user:pass@grpc-proxy:8443", "grpc")

You can also specify a CA_BUNDLE file:

$ export REQUESTS_CA_BUNDLE="/path/to/bundle/file"

# (Optional) Set bundle for GRPC. GRPC will fallback to using one of:
#   `SSL_CERT_FILE`
#   `REQUESTS_CA_BUNDLE`
#   `CURL_CA_BUNDLE`
#   Searching system PATH

$ export GRPC_CA_BUNDLE="/path/to/grpc/bundle/file"

Also refer to the requests proxies documentation and requests SSL certificate verification.

Custom Proxy Authentication

If you need more control and want additional headers, you can register a instance or subclass of ProxyAuthentication.

from descarteslabs.common.http import ProxyAuthentication

class MyProxyAuth(ProxyAuthentication):
    def authorize(self, proxy, protocol) -> dict:
        # You can do whatever you need to here to generate the approprate headers.

        # Return should be a dictionary with any headers you require.
        # For example
        return {
            "Proxy-Authentication": "Digest some-token",
            "X-Open-Says-Me": "some-super-secret-token",
        }

ProxyAuthentication.register(MyProxyAuth)

# Or you can pass an instance instead
ProxyAuthentication.register(MyProxyAuth())

If you need even more control, you can subclass our Session and JsonApiSession classes, implement the initialize() method and register them with Service.set_default_session_class(), JsonApiService.set_default_session_class() and ThirdPartyService.set_default_session_class().

For more information see our API documentation.

Authentication and Configuration

Once you have installed the Descartes Labs python client, you will need to proceed to authenticate yourself as a user and configure your client.