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.