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

# Latest version
docker pull ghcr.io/atlanhq/atlan-python:latest

# Specific version
docker pull ghcr.io/atlanhq/atlan-python:7.1.3

Usage

# Interactive Python session
docker run -it --rm ghcr.io/atlanhq/atlan-python: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 \
  ghcr.io/atlanhq/atlan-python:latest \
  python your_script.py

🧪 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

📄 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