README.md

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