Skip to content

Python SDK

Atlan University

Walk through step-by-step in our intro to custom integration course (30 mins).

Repo SphinxDocs PyPI

Obtain the SDK

The SDK is currently available on pypi. You can use pip to install it as follows:

Install the SDK
pip install pyatlan

Configure the SDK

There are two ways to configure the SDK:

Using environment variables

  • ATLAN_API_KEY should be given your Atlan API token , for authentication (don't forget to assign one or more personas to the API token to give access to existing assets!)
  • ATLAN_BASE_URL should be given your Atlan URL (for example, https://tenant.atlan.com)

Here's an example of setting those environment variables:

Set environment variables
export ATLAN_BASE_URL=https://tenant.atlan.com
export ATLAN_API_KEY="..."
atlan_live_test.py
1
2
3
from pyatlan.client.atlan import AtlanClient

client = AtlanClient()

On client creation

If you prefer to not use environment variables, you can do the following:

atlan_live_test.py
1
2
3
4
5
6
from pyatlan.client.atlan import AtlanClient

client = AtlanClient(
    base_url="https://tenant.atlan.com",
    api_key="..."
)

Careful not to expose your API token!

We generally discourage including your API token directly in your code, in case you accidentally commit it into a (public) version control system. But it's your choice exactly how you manage the API token and including it for use within the client.

That's it — once these are set you can start using your SDK to make live calls against your Atlan instance! 🎉

What's next?

Delve into more detailed examples:

Error-handling

The SDK defines exceptions for the following categories of error:

Exception Description
ApiConnectionError Errors when the SDK is unable to connect to the API, for example due to a lack of network access or timeouts.
AuthenticationError Errors when the API token configured for the SDK is invalid or expired.
ConflictError Errors when there is some conflict with an existing asset and the operation cannot be completed as a result.
InvalidRequestError Errors when the request sent to Atlan does not match its expectations. If you are using the built-in methods like toCreate() and toUpdate() this exception should be treated as a bug in the SDK. (These operations take responsibility for avoiding this error.)
LogicError Errors where some assumption made in the SDK's code is proven incorrect. If ever raised, they should be reported as bugs against the SDK.
NotFoundError Errors when the requested resource or asset does not exist in Atlan.
PermissionError Errors when the API token used by the SDK does not have permission to access a resource or carry out an operation on a specific asset.
RateLimitError Errors when the Atlan server is being overwhelmed by requests.

A given API call could fail due to all of the errors above. So these all extend a generic AtlanError exception, and all API operations can potentially raise AtlanError.

Example

For example, when creating a connection there is an asynchronous process that grants permissions to the admins of that connection. So there can be a slight delay between creating the connection and being permitted to do any operations with the connection. During that delay, any attempt to interact with the connection will result in a PermissionError, even if your API token was used to create connection in the first place.

Another example you may occasionally hit is some network issue that causes your connection to Atlan to be interrupted. In these cases, an ApiConnectionError will be raised.

Don't worry, the SDK retries automatically

While these are useful to know for detecting issues, the SDK automatically retries on such problems.

Advanced configuration

Atlan is a distributed, cloud-native application, where network problems can arise. The SDK therefore automatically attempts to handle ephemeral problems.

Logging

The SDK uses logging module of the standard library that can provide a flexible framework for emitting log messages.

You can enable logging for your SDK script by adding the following lines above your snippets:

atlan_python_sdk_test.py
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
import logging
from pyatlan.client.atlan import AtlanClient
from pyatlan.model.assets import AtlasGlossary

logging.basicConfig(level=logging.DEBUG) # (1)

# logging.config.fileConfig('pyatlan/logging.conf') # (2)

# SDK code snippets
client = AtlanClient()

glossary = client.asset.get_by_guid(
    asset_type=AtlasGlossary,
    guid="b4113341-251b-4adc-81fb-2420501c30e6"
)

  1. You can enable logging by using basicConfig with various logging levels:

    • logging.DEBUG: used to give detailed information, typically of interest only when diagnosing problems (mostly used level in SDK).
    • logging.INFO: used to confirm that things are working as expected.
    • logging.WARN: used as an indication that something unexpected happened, or as a warning of some problem in the near future.
    • logging.ERROR: indicates that due to a more serious problem, the SDK has not been able to perform some operation.
    • logging.CRITICAL: indicates a serious error, suggesting that the program itself may be unable to continue running (not used in SDK as of now).

  2. By default, logs will appear in your console. If you want to use file logging, you can add the following line:

    • logging.config.fileConfig('pyatlan/logging.conf'): this will generate logs according to the configuration defined in pyatlan/logging.conf and will generate two log files:

      • /tmp/pyatlan.log: default log file.
      • /tmp/pyatlan.json: log file in JSON format.

Retries

The SDK handles automatically retrying your requests when it detects certain problems:

  • When there is a 403 response indicating that permission for an operation is not (yet) available.
  • When there is a 50x response indicating that something went wrong on the server side.
More details on how they work

If any request encounters one of these problems, it will be retried. Before each retry, the SDK will apply a delay using an exponential backoff.

(Currently the values for the exponential backoff are not configurable.)

For each request that encounters any of these problems, only up to a maximum number of retries will be attempted. (This is set to 3 by default.)

Multi-tenant connectivity

Since version 1.0.0, the Python SDK supports connecting to multiple tenants.1 When you use the AtlanClient() method you are actually setting a default client. This default client will be used behind-the-scenes for any operations that need information specific to an Atlan tenant.

When you want to override that default client you can create a new one and use the set_default_client() method to change it:

Create a client
1
2
3
4
5
6
7
from pyatlan.client.atlan import AtlanClient

client2 = AtlanClient(  # (1)
    base_url="https://tenant.atlan.com",
    api_key="..."
)
Atlan.set_default_client(client2)  # (2)
  1. The AtlanClient() method will return a client for the given base URL, creating a new client and setting this new client as the default client.
  2. If you want to switch between clients that you have already created, you can use Atlan.set_default_client() to change between them.

Limit the number of clients to those you must have

Each client you create maintains its own independent copy of various caches. So the more clients you have, the more resources your code will consume. For this reason, we recommended limiting the number of clients you create to the bare minimum you require — ideally just a single client per tenant.

(And since in the majority of use cases you only need access to a single tenant, this means you can most likely just rely on the default client and the fallback behavior.)

Proxies

Pyatlan uses the Requests library which supports proxy configuration via environment variables. Requests relies on the proxy configuration defined by standard environment variables http_proxy, https_proxy, no_proxy, and all_proxy. Uppercase variants of these variables are also supported. You can therefore set them to configure Pyatlan (only set the ones relevant to your needs):

Configure a proxy
export HTTP_PROXY="http://10.10.1.10:3128"
export HTTPS_PROXY="http://10.10.1.10:1080"
export ALL_PROXY="socks5://10.10.1.10:3434"

To use HTTP Basic Auth with your proxy, use the http://user:password@host/ syntax in any of the above configuration entries:

Configure a proxy with authentication
export HTTPS_PROXY="http://user:pass@10.10.1.10:1080"

  1. Currently, the way this is implemented limits you to either avoiding multiple threads in your Python code (if you need to use multiple clients), or if you want to use multiple threads you should only use a single client. ↩