Home Original page

GitHub - atlanhq/atlan-python: Official Python SDK for the Atlan 💙

-----------------------------------------------------

📊 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

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

This will:

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

📁 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:

-----------------------------------------------------