assembly-api-client 1.1.0

A Python client for the Korean National Assembly Open API

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를 사용하여 의존성을 관리하는 것을 권장합니다.

# 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 파일을 생성하거나 환경 변수를 설정합니다.

export ASSEMBLY_API_KEY="YOUR_API_KEY"

방법 B: 클라이언트 직접 주입

client = AssemblyAPIClient(api_key="YOUR_API_KEY")

2. 기본 데이터 조회

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 명세 동기화:

uv run python -m assembly_client.cli sync

사용 가능한 API 목록 조회:

uv run python -m assembly_client.cli list

유지보수 (Maintenance)

API 명세 및 Fixture 업데이트

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

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

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

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

개발 및 기여 (Development)

테스트 실행

pytest

코드 재생성 (수동)

./scripts/update_client.sh

기여하기 (Contributing)

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

라이선스 (License)

MIT License