> ## Documentation Index
> Fetch the complete documentation index at: https://avala.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Python SDK

> Avala Python SDK 전체 가이드

<Info>Python SDK는 \*\*Python 3.9+\*\*가 필요합니다.</Info>

## 설치

```bash theme={null}
pip install avala
```

## 빠른 시작

```python theme={null}
from avala import Client

client = Client(api_key="your-api-key")

# 모든 데이터셋 목록
datasets = client.datasets.list()
for dataset in datasets:
    print(dataset.name, dataset.uid)
```

## 계정 생성

`signup` 함수는 새 Avala 계정을 생성하고 API 키를 반환합니다. 인증이 필요 없습니다.

```python theme={null}
from avala import signup

result = signup(
    email="dev@acme.com",
    password="SecurePass123!",
    first_name="Jane",       # 선택사항
    last_name="Doe",         # 선택사항
)

print(f"User: {result.user.email}")
print(f"API Key: {result.api_key}")
```

## 인증

SDK는 `X-Avala-Api-Key` 헤더를 통해 모든 요청에 전송되는 Avala API 키로 인증합니다.

**방법 1: 키 직접 전달**

```python theme={null}
from avala import Client

client = Client(api_key="your-api-key")
```

**방법 2: 환경 변수 사용**

```bash theme={null}
export AVALA_API_KEY="your-api-key"
```

```python theme={null}
from avala import Client

# 환경에서 AVALA_API_KEY를 자동으로 읽음
client = Client()
```

## 비동기 지원

SDK는 `httpx` 위에 구축된 완전한 비동기 클라이언트를 제공합니다.

```python theme={null}
import asyncio
from avala import AsyncClient

async def main():
    async with AsyncClient() as client:
        datasets = await client.datasets.list()
        for dataset in datasets:
            print(dataset.name)

asyncio.run(main())
```

## 데이터셋 작업

```python theme={null}
# 데이터셋 목록
datasets = client.datasets.list()
for dataset in datasets:
    print(f"{dataset.name} ({dataset.uid})")

# 데이터셋 가져오기
dataset = client.datasets.get("550e8400-e29b-41d4-a716-446655440000")
print(dataset.name)
```

## 프로젝트 작업

```python theme={null}
projects = client.projects.list()
for project in projects:
    print(f"{project.name} ({project.uid})")
    print(f"  Status: {project.status}")
```

## 내보내기 작업

```python theme={null}
# 내보내기 생성
export = client.exports.create(project="770a9600-a40d-63f6-c938-668877660000")
print(f"Export started: {export.uid}")

# 완료까지 폴링
import time
while export.status != "completed":
    time.sleep(2)
    export = client.exports.get(export.uid)
print(f"Download: {export.download_url}")
```

## 오류 처리

SDK는 다양한 실패 모드를 정밀하게 처리할 수 있도록 타입이 지정된 예외를 발생시킵니다.

```python theme={null}
from avala import Client
from avala.errors import (
    AvalaError,
    NotFoundError,
    RateLimitError,
    ValidationError,
)

client = Client()

try:
    dataset = client.datasets.get("nonexistent")
except NotFoundError as e:
    print(f"Dataset not found: {e.message}")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after} seconds.")
except AvalaError as e:
    print(f"API error ({e.status_code}): {e.message}")
```

| 예외                    | 설명                                            |
| --------------------- | --------------------------------------------- |
| `AvalaError`          | 모든 Avala API 오류의 기본 예외.                       |
| `AuthenticationError` | 유효하지 않거나 누락된 API 키 (HTTP 401).                |
| `NotFoundError`       | 요청된 리소스가 존재하지 않음 (HTTP 404).                  |
| `RateLimitError`      | API 속도 제한 초과 (HTTP 429). `retry_after` 속성 포함. |
| `ValidationError`     | 요청 페이로드 검증 실패 (HTTP 400/422).                 |
| `ServerError`         | 서버 내부 오류 (HTTP 5xx).                          |

## 페이지네이션

```python theme={null}
# 현재 페이지의 항목을 반복
for dataset in client.datasets.list():
    print(dataset.name)

# 수동 페이지네이션
page = client.datasets.list(limit=10)
for dataset in page.items:
    print(dataset.name)

if page.has_more:
    next_page = client.datasets.list(limit=10, cursor=page.next_cursor)
```

## 구성

```python theme={null}
from avala import Client

client = Client(
    api_key="your-api-key",
    base_url="https://api.avala.ai/api/v1",  # 기본값
    timeout=60,        # 요청 타임아웃(초) (기본값: 30)
    max_retries=3,     # 일시적 오류 시 재시도 횟수 (기본값: 2)
)
```