Skip to main content

atlan-application-sdk-api

Experimental. The contents of this package and how it is built may change between releases. If you are building an Atlan app, depend on atlan-application-sdk, which installs this package for you.

The handler part of the Atlan Application SDK, packaged on its own.

An Atlan app has two halves:

  • a worker, which runs the app's workflows (extraction, publishing) on Temporal and Dapr;
  • a handler, a small HTTP service that answers Atlan while a user sets up a connection: do these credentials work?, is the source ready?, which databases and schemas can I pick?

This package contains everything the handler needs and none of the worker runtime. Its core dependencies are FastAPI, Pydantic, orjson, httpx and python-multipart. That lets one lightweight process serve the handlers of many apps.

Do I need this?

Usually not. atlan-application-sdk depends on this package at exactly the same version, so installing the SDK gives you both, and your imports stay the same:

from application_sdk.handler import Handler  # same module either way

Install this package directly only to run handlers without the worker runtime, for example to serve them from a separate, smaller service.

Installation

pip install atlan-application-sdk-api
# or
uv add atlan-application-sdk-api

Requires Python 3.11 or newer. Add an extra when your handler uses that part of the SDK:

Extra When your handler uses
sql The SDK's SQL client (SQLAlchemy)
aws The SDK's AWS helpers (boto3), or the config and file routes
pandas Query results as pandas DataFrames
pyatlan The Atlas conversion helpers on ConnectionRef
pip install "atlan-application-sdk-api[sql]"

The extras have the same version pins as the matching extras of atlan-application-sdk.

Quick start

Write a handler by subclassing Handler and implementing its three methods. Then turn it into a FastAPI app with build_asgi_app:

from application_sdk.handler import (
    AuthInput,
    AuthOutput,
    AuthStatus,
    Handler,
    MetadataInput,
    MetadataOutput,
    PreflightInput,
    PreflightOutput,
    PreflightStatus,
    SqlMetadataOutput,
)
from application_sdk.handler.asgi import build_asgi_app


class DemoHandler(Handler):
    async def test_auth(self, input: AuthInput) -> AuthOutput:
        # Check input.credentials against your source.
        return AuthOutput(status=AuthStatus.SUCCESS)

    async def preflight_check(self, input: PreflightInput) -> PreflightOutput:
        # Confirm the source is ready to be extracted.
        return PreflightOutput(status=PreflightStatus.READY)

    async def fetch_metadata(self, input: MetadataInput) -> MetadataOutput:
        # List what the user can choose to extract.
        return SqlMetadataOutput(
            objects=[{"TABLE_CATALOG": "analytics", "TABLE_SCHEMA": "public"}]
        )


app = build_asgi_app(DemoHandler(), app_name="demo")

Serve it with any ASGI server (not included), for example pip install uvicorn and then uvicorn demo:app:

curl -X POST localhost:8000/workflows/v1/auth \
  -H 'content-type: application/json' -d '{"credentials": []}'
# {"success": true, "data": {"status": "success", ...}, "message": "Authentication success"}

Routes

build_asgi_app serves the same routes the full SDK's handler service does, so an app answers identically from either one:

Route Answered by
GET /health Always {"status": "ok"}
POST /workflows/v1/auth Handler.test_auth
POST /workflows/v1/check Handler.preflight_check
POST /workflows/v1/metadata Handler.fetch_metadata
POST /workflows/v1/warmup Handler.warmup (optional)
GET /workflows/v1/configmap/{id}, /configmaps, /input-contract, GET/POST /workflows/v1/manifest The app's generated/ folder, if the app package ships one
GET/POST /workflows/v1/config/{id}, POST /workflows/v1/file An S3 bucket named by ATLAN_S3_BUCKET (and ATLAN_S3_REGION); needs the aws extra. These routes return 503 when it isn't set
Your own routes FastAPI routers returned from Handler.routers(), served after the SDK's

build_asgi_app takes a few keyword options:

  • app_package: where the app's code and generated/ folder live;
  • blocking_threads: the size of this app's thread pool, default 8;
  • generated_dir;
  • object_store.

Each app built this way gets its own thread pool for run_in_thread, so several apps in one process don't block each other.

What's included

Module Contents
application_sdk.handler Handler, HandlerContext, and the request and response models
application_sdk.handler.asgi build_asgi_app
application_sdk.errors AppError and typed error classes; secrets and URL credentials are redacted from messages
application_sdk.credentials Credential specs, types and parsing
application_sdk.contracts, application_sdk.templates.contracts Input-contract models
application_sdk.common.concurrency run_in_thread, for blocking calls inside async handlers
application_sdk.common.logger get_logger
application_sdk.clients.sql (sql extra) The SQL client base
application_sdk.common.aws_utils (aws extra) AWS helpers

The complete file list is in api-files.txt.

Not included: Temporal, Dapr, the SDK's object-store layer, its structured logging and telemetry, or anything else that runs workflows. That stays in atlan-application-sdk.

A few handler features depend on the worker runtime. Without it they raise a clear, typed error instead of failing on an import. For example, self.context.get_secret() raises SecretStoreNotConfiguredError because there is no secret store. Credentials sent with the request work normally.

Versioning

This package is released together with atlan-application-sdk, from the same commit and always with the same version number. For example, atlan-application-sdk 3.51.0 requires atlan-application-sdk-api 3.51.0.

A new version can contain the same code as the previous one when a release changed only the worker part of the SDK.

Upgrading from an SDK release older than this package

Before this package existed, atlan-application-sdk shipped these files itself. Upgrading across that boundary with pip can delete them. pip installs this package first, then deletes the same files when it removes the old SDK. Starting the app (python -m application_sdk.main) reports this and tells you to run:

pip install --force-reinstall --no-deps atlan-application-sdk-api

uv is not affected. This only happens once; later upgrades are clean.

Metadata

Release files for atlan-application-sdk-api 3.51.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for atlan-application-sdk-api 3.51.0
File Size Uploaded Provenance Actions
atlan_application_sdk_api-3.51.0.tar.gz 276.3 kB Without provenance Details for atlan_application_sdk_api-3.51.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for atlan-application-sdk-api 3.51.0
File Interpreter ABI Platform Actions
atlan_application_sdk_api-3.51.0-py3-none-any.whl Python 3 none any Details for atlan_application_sdk_api-3.51.0-py3-none-any.whl

Total release size: 589.8 kB

Release files / atlan_application_sdk_api-3.51.0.tar.gz

Download URL atlan_application_sdk_api-3.51.0.tar.gz
Size 276.3 kB
Tags Source
SHA-256 checksum
How to use checksums
24fd6b872a351b2756c648347b4bb99b21d9976465ec2d16c96463f9a9180531
BLAKE2b-256 checksum
How to use checksums
5ac0bc6e1f132a7c15c2cc8fc111280dbb5250d8ed8827e97e179c46ca66a8d1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.4 {"installer":{"name":"uv","version":"0.13.4","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / atlan_application_sdk_api-3.51.0-py3-none-any.whl

Download URL atlan_application_sdk_api-3.51.0-py3-none-any.whl
Size 313.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
e9d1d832a4cdcc6a40609617d480bcee6b9f67bd0811af20e68e06fec6e182af
BLAKE2b-256 checksum
How to use checksums
2b65018843e9021c62425a79371a1da0c9855d21a75be8f3b67ae2c93befeafa
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.4 {"installer":{"name":"uv","version":"0.13.4","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for atlan-application-sdk-api 3.51.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page