|
1 | | -<!-- SPDX-License-Identifier: CC-BY-4.0 --> |
2 | | -<!-- Copyright 2022 Atlan Pte. Ltd. --> |
| 1 | +<div align="center"> |
3 | 2 |
|
4 | | -[](https://atlanhq.github.io/atlan-python/) |
| 3 | +<img src="https://github.com/user-attachments/assets/38243809-d723-4464-8f1c-4869795ea0c8" alt="pyatlan Logo" width="300"> |
5 | 4 |
|
6 | | -# Atlan Python SDK |
| 5 | +**The official Python SDK for the Atlan π** |
7 | 6 |
|
8 | | -This repository houses the code for a Python SDK to interact with [Atlan](https://atlan.com). |
| 7 | +[](https://pypi.org/project/pyatlan/) |
| 8 | +[](https://pypi.org/project/pyatlan/) |
| 9 | +[](https://opensource.org/licenses/Apache-2.0) |
| 10 | +[](https://pypi.org/project/pyatlan/) |
| 11 | +[](https://github.com/atlanhq/atlan-python/actions/workflows/pyatlan-pr.yaml) |
| 12 | +[](https://developer.atlan.com/getting-started/python-sdk/) |
| 13 | +[](https://github.com/atlanhq/atlan-python/pkgs/container/atlan-python) |
9 | 14 |
|
10 | | -## [Documentation](https://developer.atlan.com/getting-started/python-sdk/) |
| 15 | +--- |
11 | 16 |
|
12 | | -[https://developer.atlan.com/getting-started/python-sdk/](https://developer.atlan.com/getting-started/python-sdk/) |
| 17 | +[**π Documentation**](https://developer.atlan.com/getting-started/python-sdk/) β’ |
| 18 | +[**π³ Docker**](#-docker) β’ |
| 19 | +[**π€ Contributing**](#-contributing) |
13 | 20 |
|
14 | | -## Installing for Development |
| 21 | +</div> |
15 | 22 |
|
16 | | -### Initial Setup |
17 | | -To get started developing the SDK: |
| 23 | + |
18 | 24 |
|
19 | | -1. Clone the repository: |
20 | | - ```bash |
21 | | - git clone <repository-url> |
22 | | - ``` |
| 25 | +## π Project Stats |
23 | 26 |
|
24 | | -2. Ensure you have Python 3.8 or later installed. You can verify your Python version with: |
25 | | - ```bash |
26 | | - python --version |
27 | | - ``` |
28 | | - or |
29 | | - ```bash |
30 | | - python3 --version |
31 | | - ``` |
| 27 | +- π **Python Versions**: 3.8, 3.9, 3.10, 3.11, 3.12, 3.13 |
| 28 | +- π¦ **Package Size**: Optimized for fast installation |
| 29 | +- π **Performance**: Built with modern async/await support |
| 30 | +- π§ **Dependencies**: Minimal, modern stack |
| 31 | +- π **Stability**: Production-ready |
32 | 32 |
|
33 | | -3. Set up a virtual environment for development: |
34 | | - ```bash |
35 | | - python -m venv venv |
36 | | - source venv/bin/activate # On macOS/Linux |
37 | | - venv\Scripts\activate # On Windows |
38 | | - ``` |
| 33 | +## π¦ Installation |
39 | 34 |
|
40 | | -4. Install the required dependencies: |
41 | | - ```bash |
42 | | - # Install dependencies using uv |
43 | | - uv sync --extra dev |
44 | | - ``` |
45 | | - |
46 | | -### Code Formatting |
47 | | -Before committing code, ensure it adheres to the repository's formatting guidelines. You can apply the required formatting using the below command: |
| 35 | +### Production Use |
48 | 36 |
|
49 | 37 | ```bash |
50 | | -uv run ./formatter |
51 | | -``` |
| 38 | +# Latest stable version |
| 39 | +pip install pyatlan |
52 | 40 |
|
53 | | -### Environment Setup |
54 | | -For running integration tests, you'll need to configure your environment: |
55 | | - |
56 | | -1. Copy the example environment file: |
57 | | - ```bash |
58 | | - cp .env.example .env |
59 | | - ``` |
60 | | -2. Update the `.env` file with your Atlan API key and base URL. |
61 | | -3. Load the environment variables: |
62 | | - - For macOS/Linux: |
63 | | - ```bash |
64 | | - export $(cat .env | xargs) |
65 | | - ``` |
66 | | - - For Windows (PowerShell): Load environment variables |
67 | | - ```powershell |
68 | | - # Run this in PowerShell (not Command Prompt) |
69 | | - Get-Content .env | ForEach-Object { |
70 | | - if ($_ -match '^(.*?)=(.*)$') { |
71 | | - $env:($matches[1]) = $matches[2] |
72 | | - } |
73 | | - } |
74 | | - ``` |
75 | | - - For macOS/Linux: Load environment variables from .env file |
76 | | - ```bash |
77 | | - export $(cat .env | xargs) |
78 | | - ``` |
79 | | -
|
80 | | -
|
81 | | -## Testing the SDK |
82 | | -
|
83 | | -### Run all the QA checks |
84 | | -You can run all the QA checks using the following command: |
| 41 | +# Specific version |
| 42 | +pip install pyatlan==7.1.3 |
85 | 43 |
|
86 | | -```bash |
87 | | -uv run ./qa-checks |
| 44 | +# With uv (faster) - install uv first: curl -LsSf https://astral.sh/uv/install.sh | sh |
| 45 | +uv add pyatlan |
88 | 46 | ``` |
89 | 47 |
|
90 | | -### Running Unit Tests |
91 | | -You can run the SDK's unit tests **without needing access to an Atlan environment**: |
| 48 | +### Development Setup |
92 | 49 |
|
93 | 50 | ```bash |
94 | | -uv run pytest tests/unit |
95 | | -``` |
| 51 | +# Clone the repository |
| 52 | +git clone https://github.com/atlanhq/atlan-python.git |
| 53 | +cd atlan-python |
| 54 | + |
| 55 | +# Install uv (if not already installed) |
| 56 | +curl -LsSf https://astral.sh/uv/install.sh | sh |
96 | 57 |
|
97 | | -### Running Integration Tests |
98 | | -Once the environment is set up, you can run integration tests: |
| 58 | +# Install with development dependencies |
| 59 | +uv sync --extra dev |
99 | 60 |
|
100 | | -- All integration tests: |
101 | | - ```bash |
102 | | - uv run pytest tests/integration |
103 | | - ``` |
104 | | -- Specific integration tests: |
105 | | - ```bash |
106 | | - uv run pytest tests/integration/<test_specific_feature>.py |
107 | | - ``` |
| 61 | +# Run quality checks |
| 62 | +uv run ./qa-checks |
108 | 63 |
|
109 | | -## Docker |
| 64 | +# Run tests |
| 65 | +uv run pytest tests/unit |
| 66 | +``` |
110 | 67 |
|
111 | | -### Using Published Images |
| 68 | +## π³ Docker |
| 69 | + |
| 70 | +### Pre-built Images |
112 | 71 |
|
113 | | -Pre-built Docker images are available from GitHub Container Registry: |
114 | 72 |
|
115 | 73 | ```bash |
116 | 74 | # Latest version |
117 | 75 | docker pull ghcr.io/atlanhq/atlan-python:latest |
118 | 76 |
|
119 | 77 | # Specific version |
120 | | -docker pull ghcr.io/atlanhq/atlan-python:7.1.1 |
| 78 | +docker pull ghcr.io/atlanhq/atlan-python:7.1.3 |
121 | 79 | ``` |
122 | 80 |
|
123 | | -**Usage:** |
| 81 | +### Usage |
| 82 | + |
124 | 83 | ```bash |
125 | 84 | # Interactive Python session |
126 | 85 | docker run -it --rm ghcr.io/atlanhq/atlan-python:latest |
127 | 86 |
|
128 | | -# Run a Python script |
129 | | -docker run -it --rm -v $(pwd):/app ghcr.io/atlanhq/atlan-python:latest python your_script.py |
130 | | -
|
131 | | -# With environment variables |
| 87 | +# Run a script |
132 | 88 | docker run -it --rm \ |
133 | | - -e ATLAN_API_KEY=your_api_key \ |
| 89 | + -v $(pwd):/app \ |
| 90 | + -e ATLAN_API_KEY=your_key \ |
134 | 91 | -e ATLAN_BASE_URL=https://your-tenant.atlan.com \ |
135 | | - ghcr.io/atlanhq/atlan-python:latest |
| 92 | + ghcr.io/atlanhq/atlan-python:latest \ |
| 93 | + python your_script.py |
136 | 94 | ``` |
137 | 95 |
|
138 | | -### Building Locally |
| 96 | +## π§ͺ Testing |
| 97 | + |
| 98 | +### Unit Tests |
| 99 | +```bash |
| 100 | +# Run all unit tests |
| 101 | +uv run pytest tests/unit |
139 | 102 |
|
140 | | -You can build the Docker image locally: |
| 103 | +# Run with coverage |
| 104 | +uv run pytest tests/unit --cov=pyatlan --cov-report=html |
| 105 | +``` |
| 106 | + |
| 107 | +### Integration Tests |
| 108 | +```bash |
| 109 | +# Set up environment |
| 110 | +cp .env.example .env |
| 111 | +# Edit .env with your Atlan credentials |
| 112 | + |
| 113 | +# Run integration tests |
| 114 | +uv run pytest tests/integration |
| 115 | +``` |
141 | 116 |
|
| 117 | +### Quality Assurance |
142 | 118 | ```bash |
143 | | -# Build the image |
144 | | -docker build -t pyatlan --build-arg VERSION=7.1.1 . |
| 119 | +# Run all QA checks (formatting, linting, type checking) |
| 120 | +uv run ./qa-checks |
145 | 121 |
|
146 | | -# Test the image |
147 | | -docker run -it --rm pyatlan python -c "import pyatlan; print('PyAtlan loaded successfully!')" |
| 122 | +# Individual checks |
| 123 | +uv run ruff format . # Code formatting |
| 124 | +uv run ruff check . # Linting |
| 125 | +uv run mypy . # Type checking |
148 | 126 | ``` |
149 | 127 |
|
150 | | -**Available images:** |
151 | | -- **Latest**: `ghcr.io/atlanhq/atlan-python:latest` |
152 | | -- **Versioned**: `ghcr.io/atlanhq/atlan-python:x.y.z` |
| 128 | +## π€ Contributing |
| 129 | + |
| 130 | +We welcome contributions! Here's how to get started: |
153 | 131 |
|
154 | | -### Running the SDK Model Generator |
| 132 | +### Development Setup |
155 | 133 |
|
156 | | -If you've pushed new typedefs to Atlan and want to generate SDK asset models to manage them via the SDK, this section covers how to run the SDK generator. |
| 134 | +```bash |
| 135 | +# Fork and clone the repository |
| 136 | +git clone https://github.com/your-username/atlan-python.git |
| 137 | +cd atlan-python |
157 | 138 |
|
158 | | -> [!NOTE] |
159 | | -> Before running any generator scripts, make sure you have [configured your environment variables](https://developer.atlan.com/sdks/python/#configure-the-sdk) specifically `ATLAN_BASE_URL` and `ATLAN_API_KEY`. |
| 139 | +# Install uv (if not already installed) |
| 140 | +curl -LsSf https://astral.sh/uv/install.sh | sh |
160 | 141 |
|
161 | | -1. Run the combined generator script that handles all steps automatically: |
| 142 | +# Install development dependencies |
| 143 | +uv sync --extra dev |
162 | 144 |
|
163 | | - ```shell |
164 | | - # Use default location (/tmp/typedefs.json) |
165 | | - uv run ./generator |
| 145 | +# Install pre-commit hooks |
| 146 | +uv run pre-commit install |
| 147 | +``` |
166 | 148 |
|
167 | | - # Or specify a custom typedefs file location |
168 | | - uv run ./generator ./my-typedefs.json |
169 | | - ``` |
| 149 | +### Making Changes |
170 | 150 |
|
171 | | - This script will: |
172 | | - - Check if typedefs file exists and is current (skip if already created today) |
173 | | - - Retrieve typedefs from your Atlan instance if needed |
174 | | - - Generate the asset `models`, `enums`, and `struct` modules |
175 | | - - Format the generated code automatically |
176 | | - - Support custom typedefs file paths for flexibility |
| 151 | +```bash |
| 152 | +# Create a feature branch |
| 153 | +git checkout -b feature/amazing-feature |
177 | 154 |
|
178 | | -## Attribution |
| 155 | +# Make your changes and test |
| 156 | +uv run ./formatter |
| 157 | +uv run ./qa-checks |
| 158 | +uv run pytest tests/unit |
179 | 159 |
|
180 | | -Portions of the SDK are based on original work from https://github.com/apache/atlas. Those classes that derive from this original work have an extra heading comment as follows: |
| 160 | +# Commit with conventional commits |
| 161 | +git commit -m "feat: add amazing feature" |
181 | 162 |
|
182 | | -```python |
183 | | -# Based on original code from https://github.com/apache/atlas (under Apache-2.0 license) |
| 163 | +# Push and create a pull request |
| 164 | +git push origin feature/amazing-feature |
184 | 165 | ``` |
185 | 166 |
|
186 | | -Portions of the SDK are based on original work from https://github.com/elastic/elasticsearch-dsl-py. Those classes that derive from this original work have an extra heading comment as follows: |
| 167 | +### Guidelines |
| 168 | + |
| 169 | +- β
Follow [conventional commits](https://www.conventionalcommits.org/) |
| 170 | +- β
Add tests for new features |
| 171 | +- β
Update documentation as needed |
| 172 | +- β
Ensure all QA checks pass |
187 | 173 |
|
188 | | -```python |
189 | | -# Based on original code from https://github.com/elastic/elasticsearch-dsl-py.git (under Apache-2.0 license) |
| 174 | +## π οΈ SDK Generator |
| 175 | + |
| 176 | +Generate asset models from your Atlan instance: |
| 177 | + |
| 178 | +```bash |
| 179 | +# Generate models automatically |
| 180 | +uv run ./generator |
| 181 | + |
| 182 | +# Use custom typedefs file |
| 183 | +uv run ./generator ./my-typedefs.json |
190 | 184 | ``` |
191 | | ----- |
192 | | -License: [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), |
193 | | -Copyright 2022 Atlan Pte. Ltd. |
| 185 | + |
| 186 | +This will: |
| 187 | +- π₯ Retrieve typedefs from your Atlan instance |
| 188 | +- ποΈ Generate asset models, enums, and structures |
| 189 | +- π¨ Format code automatically |
| 190 | +- β‘ Support incremental updates |
| 191 | + |
| 192 | +## π License |
| 193 | + |
| 194 | +This project is licensed under the **Apache License 2.0** - see the [LICENSE](LICENSE) file for details. |
| 195 | + |
| 196 | +## π Attribution |
| 197 | + |
| 198 | +Portions of this SDK are based on original work from: |
| 199 | +- **[Apache Atlas](https://github.com/apache/atlas)** (Apache-2.0 license) |
| 200 | +- **[Elasticsearch DSL](https://github.com/elastic/elasticsearch-dsl-py)** (Apache-2.0 license) |
| 201 | + |
| 202 | +<div align="center"> |
| 203 | + |
| 204 | +**Built with π by [Atlan](https://atlan.com)** |
| 205 | + |
| 206 | +[Website](https://atlan.com) β’ [Documentation](https://developer.atlan.com) β’ [Support](mailto:support@atlan.com) |
| 207 | + |
| 208 | +</div> |
| 209 | + |
| 210 | + |
0 commit comments