pyatlan

The official Python SDK for the Atlan 💙

📖 Documentation • 🐳 Docker • 🤝 Contributing

📊 Project Stats

🐍 Python Versions: 3.9, 3.10, 3.11, 3.12, 3.13
📦 Package Size: Optimized for fast installation
🚀 Performance: Built with modern async/await support
🔧 Dependencies: Minimal, modern stack
📈 Stability: Production-ready

📦 Installation

Production Use

# Latest stable version
pip install pyatlan

# Specific version
pip install pyatlan==7.1.3

# With uv (faster) - install uv first: curl -LsSf https://astral.sh/uv/install.sh | sh
uv add pyatlan

Development Setup

# Clone the repository
git clone https://github.com/atlanhq/atlan-python.git
cd atlan-python

# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install with development dependencies
uv sync --group dev

# Run quality checks
uv run ./qa-checks

# Run tests
uv run pytest tests/unit

Dependency Groups

This project uses uv dependency groups for better dependency management:

Core dependencies: Always installed (uv sync)
Development dependencies: Testing, linting, formatting (uv sync --group dev)
Documentation dependencies: Sphinx docs (uv sync --group docs)

You can install multiple groups:

# Install both dev and docs dependencies
uv sync --group dev --group docs

# Install all dependencies
uv sync --all-groups

🐳 Docker

Pre-built Images (Harbor)

# Latest main image
docker pull registry.atlan.com/public/pyatlan:main-latest

# Version + Python tag
docker pull registry.atlan.com/public/pyatlan:8.5.1-3.11

# Commit-specific image
docker pull registry.atlan.com/public/pyatlan:sha-1a064032

Usage

# Interactive Python session
docker run -it --rm registry.atlan.com/public/pyatlan:main-latest

# Run a script
docker run -it --rm \
  -v $(pwd):/app \
  -e ATLAN_API_KEY=your_key \
  -e ATLAN_BASE_URL=https://your-tenant.atlan.com \
  registry.atlan.com/public/pyatlan:main-latest \
  python your_script.py

🔒 Security Scans

Run Snyk locally (dependencies)

uv export --all-extras --no-hashes > requirements.txt
snyk test --file=requirements.txt --severity-threshold=high --skip-unresolved
rm -f requirements.txt

🧪 Testing

Unit Tests

# Run all unit tests
uv run pytest tests/unit

# Run with coverage
uv run pytest tests/unit --cov=pyatlan --cov-report=html

Integration Tests

# Set up environment
cp .env.example .env
# Edit .env with your Atlan credentials

# Run integration tests
uv run pytest tests/integration

Quality Assurance

# Run all QA checks (formatting, linting, type checking)
uv run ./qa-checks

# Individual checks
uv run ruff format .          # Code formatting
uv run ruff check .           # Linting
uv run mypy .                 # Type checking

🤝 Contributing

We welcome contributions! Here's how to get started:

Development Setup

# Fork and clone the repository
git clone https://github.com/your-username/atlan-python.git
cd atlan-python

# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install development dependencies
uv sync --group dev

# Install pre-commit hooks
uv run pre-commit install

Making Changes

# Create a feature branch
git checkout -b feature/amazing-feature

# Make your changes and test
uv run ./formatter
uv run ./qa-checks
uv run pytest tests/unit

# Commit with conventional commits
git commit -m "feat: add amazing feature"

# Push and create a pull request
git push origin feature/amazing-feature

Guidelines

✅ Follow conventional commits
✅ Add tests for new features
✅ Update documentation as needed
✅ Ensure all QA checks pass

🛠️ SDK Generator

Generate asset models from your Atlan instance:

# Generate models automatically
uv run ./generator

# Force re-download typedefs (bypass cache)
uv run ./generator --override

# Use custom typedefs file
uv run ./generator ./my-typedefs.json

# Both flags can be combined
uv run ./generator --override ./my-typedefs.json

This will:

📥 Retrieve typedefs from your Atlan instance
🏗️ Generate asset models, enums, and structures
🎨 Format code automatically
⚡ Support incremental updates

App Builders Generator

Generate the app builders in pyatlan.model.apps (one per connector app) from your tenant's UI configmaps. Each app gets a typed *Inputs model and a fluent, UI-equivalent builder (Credential → Connection → Metadata), plus a matching unit-test module under tests/unit/apps/.

# Needs a tenant with the apps installed
export ATLAN_BASE_URL=https://<your-tenant-host>
export ATLAN_API_KEY=<your-api-key>

# Regenerate all app builders + their tests
uv run generate-apps

This will:

🔎 Discover installed apps (live discovery ∪ the manifest in generate_apps.py)
🧩 Read each app's UI configmaps for fields, labels, enums, and the credential form
🏗️ Emit a {App}Inputs model + {App} builder per app (hand-written builders are never overwritten)
🧪 Generate a per-app config-assertion test module
🎨 Format code automatically

To cover an app that isn't currently running on the tenant, add its (app_id, entrypoint) to MANIFEST in pyatlan/generator/generate_apps.py.

🏗️ pyatlan_v9 Model Generation (msgspec)

The pyatlan_v9 package uses msgspec Struct-based models generated from Pkl type definitions in the atlanhq/models repo.

Using Claude Code

The recommended way to regenerate models is via the Claude Code skill:

# From the atlan-python repo root:
/generate-v9-models              # Generate from models@master
/generate-v9-models <branch>     # Generate from a specific models branch
/generate-v9-models test         # Generate and run tests
/generate-v9-models <branch> test

The skill will:

Clone/update atlanhq/models at ../models
Run the Pkl code generator with SDK mode (pkl eval typedefs/*.pkl -m . -p sdk=true)
Selectively sync generated files to pyatlan_v9/model/assets/ (excluding hand-written types)
Apply post-sync patches (e.g., set[str] fields in asset.py)
Optionally run tests_v9/unit/ tests

Overlay Files

Custom methods (creator(), updater(), policy helpers, etc.) live in pyatlan_v9/model/assets/_overlays/. These are Python files read by the Pkl renderer and injected into generated classes. Each overlay file uses import directives:

# IMPORT: — external imports (not remapped)
# INTERNAL_IMPORT: — internal imports (remapped to pyatlan_v9.*)
# STDLIB_IMPORT: — standard library imports

Hand-written Types

Some types are not yet fully generated and are maintained by hand:

Infrastructure: __init__.py, entity.py, referenceable.py
GTC types: atlas_glossary.py, atlas_glossary_term.py, atlas_glossary_category.py
Others: persona.py, purpose.py, badge.py, access_control.py, auth_policy.py, etc.

📁 Project Structure

Understanding the codebase layout will help you navigate and contribute effectively:

atlan-python/
├── pyatlan/                          # 🐍 Main Python package
│   ├── __init__.py                   # Package initialization
│   ├── cache/                        # 💾 Caching mechanisms
│   │   ├── atlan_tag_cache.py       # Tag name ↔ GUID mapping
│   │   ├── custom_metadata_cache.py  # Custom metadata definitions
│   │   ├── enum_cache.py            # Enum value caching
│   │   └── aio/                     # Async versions of caches
│   ├── client/                       # 🌐 HTTP client implementations
│   │   ├── atlan.py                 # Main synchronous client
│   │   ├── asset.py                 # Asset operations (CRUD, search)
│   │   ├── admin.py                 # Administrative operations
│   │   ├── audit.py                 # Audit log operations
│   │   ├── common/                  # Shared client logic
│   │   └── aio/                     # Async client implementations
│   ├── model/                        # 📊 Data models and assets
│   │   ├── assets/                  # Asset type definitions
│   │   │   ├── core/                # Core asset types (Table, Database, etc.)
│   │   │   └── relations/           # Relationship models
│   │   ├── fields/                  # Search field definitions
│   │   ├── open_lineage/            # OpenLineage specification models
│   │   ├── packages/                # Package/workflow models
│   │   └── aio/                     # Async model variants
│   ├── generator/                    # 🏗️ Code generation tools
│   │   ├── templates/               # Jinja2 templates for generation
│   │   └── class_generator.py       # Main generation logic
│   ├── pkg/                         # 📦 Package creation utilities
│   ├── events/                      # 🔔 Event handling (webhooks, lambdas)
│   ├── samples/                     # 💡 Example code and scripts
│   └── test_utils/                  # 🧪 Testing utilities
├── tests/                            # 🧪 Test suite
│   ├── unit/                        # Unit tests (fast, no external deps)
│   ├── integration/                 # Integration tests (require Atlan instance)
│   └── data/                        # Test fixtures and mock data
├── docs/                            # 📚 Sphinx documentation
│   ├── conf.py                      # Sphinx configuration
│   └── *.rst                       # Documentation source files
├── pyproject.toml                   # 📋 Project configuration (deps, tools)
├── uv.lock                          # 🔒 Locked dependencies
├── qa-checks                        # ✅ Quality assurance script
├── formatter                        # 🎨 Code formatting script
└── generator                        # 🏗️ Model generation script

Key Components

🌐 Client Layer (`pyatlan/client/`)

Synchronous: Direct HTTP operations using httpx
Asynchronous: Async/await operations using httpx.AsyncClient
Common: Shared business logic between sync/async clients
Specialized: Domain-specific clients (admin, audit, lineage, etc.)

📊 Model Layer (`pyatlan/model/`)

Assets: 400+ asset types (tables, dashboards, pipelines, etc.)
Core Models: Base classes, requests, responses
Fields: Search and filtering field definitions
OpenLineage: Data lineage specification compliance

💾 Cache Layer (`pyatlan/cache/`)

Tag Cache: Maps human-readable tag names to internal GUIDs
Custom Metadata: Caches custom attribute definitions
Connection Cache: Stores connector and connection metadata
Async Variants: Full async implementations for all caches

🏗️ Generation System (`pyatlan/generator/`)

Templates: Jinja2 templates for assets, enums, documentation
Generator: Retrieves typedefs and generates Python models
Incremental: Only regenerates changed models for efficiency

🧪 Testing Strategy

Unit Tests: Fast, isolated tests with mocks/fixtures
Integration Tests: Real API calls (requires credentials)
VCR Cassettes: Record/replay HTTP interactions for consistent testing

📦 Package System (`pyatlan/pkg/`)

Custom Packages: Framework for building Atlan-deployable packages
Templates: Pre-built package structures and configurations
Utilities: Helper functions for package development

Development Workflow

Models: Generated from your Atlan instance's typedefs
Clients: Hand-crafted for optimal developer experience
Tests: Mix of unit (fast iteration) and integration (real validation)
Quality: Automated formatting, linting, and type checking
Documentation: Auto-generated from docstrings and examples

📄 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

🙏 Attribution

Portions of this SDK are based on original work from:

Apache Atlas (Apache-2.0 license)
Elasticsearch DSL (Apache-2.0 license)

Built with 💙 by Atlan

Website • Documentation • Support

Release files for pyatlan 11.4.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 pyatlan 11.4.0
File	Size	Uploaded
pyatlan-11.4.0.tar.gz	3.8 MB	Sep 18, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for pyatlan 11.4.0
File	Interpreter	ABI	Platform	Reset
pyatlan-11.4.0-py3-none-any.whl 5.7 MB Sep 18, 2026	Python 3	none	any	Details

Total release size: 9.5 MB

Release files / pyatlan-11.4.0.tar.gz

Download URL	pyatlan-11.4.0.tar.gz
Size	3.8 MB
Tags	Source
SHA-256 checksum How to use checksums	`b9ab9c504758090a991fff6187f51214685670b3268c59700943d6e7d9f2137a`
BLAKE2b-256 checksum How to use checksums	`37d76a26d57e7eb6e6334900c9b16f207c6c0c759bf3162d321dc07eb781059e`
Upload date	Sep 18, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.12.16 {"installer":{"name":"uv","version":"0.12.16","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 / pyatlan-11.4.0-py3-none-any.whl

Download URL	pyatlan-11.4.0-py3-none-any.whl
Size	5.7 MB
Tags	Python 3
SHA-256 checksum How to use checksums	`8d683eb308fffa7a599c1be60b6a1428a61bd3a4c9e1ac51e0051aa5fdcf7bc4`
BLAKE2b-256 checksum How to use checksums	`a3cd3871269a203c67173350dab96cce03de3ff9c25f4899b9173b1613b0699f`
Upload date	Sep 18, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.12.16 {"installer":{"name":"uv","version":"0.12.16","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}`