Metadata-Version: 2.4
Name: assembly-api-client
Version: 1.1.0
Summary: A Python client for the Korean National Assembly Open API
Author-email: StatPan <statpan@naver.com>
License: MIT
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.8
Requires-Dist: httpx>=0.24.0
Requires-Dist: openpyxl>=3.1.0
Requires-Dist: platformdirs>=3.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: tenacity>=8.0.0
Requires-Dist: typer>=0.9.0
Description-Content-Type: text/markdown

# Assembly API Client
# Assembly API Client (국회 오픈 API 클라이언트)

대한민국 국회 오픈 API(Open API)를 위한 강력하고 유연한 비동기 Python 클라이언트입니다.

## 주요 기능 (Features)

- **동적 스펙 파싱 (Dynamic Spec Parsing)**: 엑셀 명세서를 자동으로 다운로드하고 파싱하여 API 엔드포인트를 동적으로 해결합니다.
- **타입 안정성 (Type Safety)**: Pydantic 모델을 사용하여 데이터 타입을 검증하고 자동 완성 기능을 제공합니다. API의 불규칙한 데이터 타입(문자열/숫자 혼용)에도 유연하게 대응합니다.
- **강력한 복원력 (Resilience)**: 내장된 재시도(Retry) 로직과 에러 핸들링으로 안정적인 데이터 수집이 가능합니다.
- **자동화된 업데이트 (Automated Updates)**: 매주 자동으로 최신 API 명세를 동기화하고 코드를 재생성하는 CI/CD 파이프라인이 포함되어 있습니다.
- **CLI 도구**: API 명세 동기화 및 검색을 위한 커맨드라인 도구를 제공합니다.

## 설치 (Installation)

이 프로젝트는 [uv](https://github.com/astral-sh/uv)를 사용하여 의존성을 관리하는 것을 권장합니다.

```bash
# uv 설치 (없는 경우)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 가상환경 생성 및 패키지 설치
uv venv
source .venv/bin/activate
uv pip install assembly-api-client
```

## 사용법 (Usage)

### 1. API 키 설정 (API Key Configuration)

API 키는 두 가지 방식으로 설정할 수 있습니다.

**방법 A: 환경 변수 사용 (권장)**
`.env` 파일을 생성하거나 환경 변수를 설정합니다.
```bash
export ASSEMBLY_API_KEY="YOUR_API_KEY"
```

**방법 B: 클라이언트 직접 주입**
```python
client = AssemblyAPIClient(api_key="YOUR_API_KEY")
```

### 2. 기본 데이터 조회

```python
import asyncio
from assembly_client.api import AssemblyAPIClient
from assembly_client.generated import Service

async def main():
    # 환경 변수가 설정되어 있다면 api_key 생략 가능
    async with AssemblyAPIClient() as client:
        
        # 서비스 ID 또는 Enum을 사용하여 데이터 조회
        # 예: 국회의원 발의법률안 조회
        data = await client.get_data(Service.국회의원_발의법률안, params={"AGE": "21"})
        
        for item in data:
            print(f"법안명: {item.BILL_NAME}, 발의자: {item.PROPOSER}")

if __name__ == "__main__":
    asyncio.run(main())
```

### 3. CLI 사용 (uv 기반)

API 명세 동기화:
```bash
uv run python -m assembly_client.cli sync
```

사용 가능한 API 목록 조회:
```bash
uv run python -m assembly_client.cli list
```

## 유지보수 (Maintenance)

### API 명세 및 Fixture 업데이트
국회 API는 수시로 변경되거나 새로운 서비스가 추가될 수 있습니다. 
새로운 API가 추가되면 `sync` 명령어로 명세를 업데이트하고, 테스트를 위한 Fixture도 새로 받아야 합니다.

이 프로젝트는 매일 자동으로 변경사항을 확인하도록 설정되어 있습니다. 수동으로 업데이트하려면:

```bash
# 1. 명세 동기화 및 코드 재생성
./scripts/update_client.sh

# 2. (필요시) 새로운 Fixture 생성
# 새로운 서비스가 추가되었다면 해당 서비스의 샘플 데이터를 받아 테스트에 추가해야 합니다.
```

## 개발 및 기여 (Development)

### 테스트 실행
```bash
pytest
```

### 코드 재생성 (수동)
```bash
./scripts/update_client.sh
```

## 기여하기 (Contributing)

이 프로젝트에 기여하고 싶으시다면 [기여 가이드](docs/CONTRIBUTING.md)를 참고해 주세요. 커밋 메시지 규약 및 자동 배포 프로세스에 대한 자세한 내용을 확인하실 수 있습니다.

## 라이선스 (License)

MIT License
