pyatlan 9.5.0

Atlan Python Client

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

🏗️ 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:

1. Clone/update atlanhq/models at ../models
2. Run the Pkl code generator with SDK mode (pkl eval typedefs/*.pkl -m . -p sdk=true)
3. Selectively sync generated files to pyatlan_v9/model/assets/ (excluding hand-written types)
4. Apply post-sync patches (e.g., set[str] fields in asset.py)
5. 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

1. Models: Generated from your Atlan instance's typedefs
2. Clients: Hand-crafted for optimal developer experience
3. Tests: Mix of unit (fast iteration) and integration (real validation)
4. Quality: Automated formatting, linting, and type checking
5. 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