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), or on GCP by ATLAN_GCP_BUCKET (and ATLAN_GCP_REGION) through GCS's S3-compatible API with the ATLAN_GCP_HMAC_ACCESS_KEY / ATLAN_GCP_HMAC_SECRET keys; needs the aws extra. These routes return 503 when neither is 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.53.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.53.0
File Size Uploaded Provenance Actions
atlan_application_sdk_api-3.53.0.tar.gz 289.0 kB Without provenance Details for atlan_application_sdk_api-3.53.0.tar.gz

Built distribution (wheel)

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

Total release size: 615.9 kB

Release files / atlan_application_sdk_api-3.53.0.tar.gz

Download URL atlan_application_sdk_api-3.53.0.tar.gz
Size 289.0 kB
Tags Source
SHA-256 checksum
How to use checksums
d8cbbc3d93b954a50881a78c229494762e9da89ab67d5b5cbc44842144b60f76
BLAKE2b-256 checksum
How to use checksums
dedfdcf7f94119d4f4c1b66b889bddfea48bab8373f15a4c53505af8eaaac091
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.5 {"installer":{"name":"uv","version":"0.13.5","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.53.0-py3-none-any.whl

Download URL atlan_application_sdk_api-3.53.0-py3-none-any.whl
Size 327.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
45a806af9569a0f25636f7218908226b451515cf9b69e14518a15f088bd7928a
BLAKE2b-256 checksum
How to use checksums
6bc7e5048f6d311c3d5e404e7d066074512981dd26913fc7fbac1b7926673bf5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.5 {"installer":{"name":"uv","version":"0.13.5","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.53.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