GeezerVison

The official Python SDK for the Atlan 💙

📖 Documentation • 🐳 Docker • 🤝 Contributing

📊 Project Stats

📦 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

# 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

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

🛠️ SDK Generator

# 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

App Builders Generator

# 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

🏗️ pyatlan_v9 Model Generation (msgspec)

Using Claude Code

# 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

Overlay Files

Hand-written Types

📁 Project Structure

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/)

📊 Model Layer (pyatlan/model/)

💾 Cache Layer (pyatlan/cache/)

🏗️ Generation System (pyatlan/generator/)

🧪 Testing Strategy

📦 Package System (pyatlan/pkg/)

Development Workflow

📄 License

🙏 Attribution

Built with 💙 by Atlan

Website • Documentation • Support