kma 개선에 참여할 때 참고하는 문서입니다. 이 프로젝트는 까다로운 공공 API를 감싸므로, 좋은 변경은 작고 테스트가 있으며 KMA 특유의 예외 상황을 명시적으로 다룹니다.
python -m venv .venv
pip install -e ".[dev]"
python -m pytest기본 테스트는 실제 KMA API를 호출하면 안 됩니다.
AGENTS.md: 작업 소유권과 검증 기준.kma-api.md: endpoint 동작과 KMA 응답의 함정.docs/repeated-mistakes.md: 이미 겪었거나 반복되기 쉬운 실수.SKILL.md: 구현 불변조건.docs/apihub.md: APIHub 함수형 래퍼와 응답 형식.
- 의도적이고 문서화된 변경이 아니라면 public API를 안정적으로 유지합니다.
- timezone 없는
datetime은 KST로 해석합니다. - 외부 프로그램용 위치 입력은
LatLon,GridPoint,location=으로 표준화하고, 기존lat/lon,nx/nyAPI는 호환성을 유지합니다. - 새 코드 식별자를 추가할 때는 가능한 경우
src/kma/enums.py의 public enum과src/kma/codes.pyhelper를 함께 갱신합니다. requests의params=에는 data.go.kr Decoding 인증키를 전달합니다.- 예보 항목의
PCP,SNO범주 문자열은 보존합니다. PTY매핑은 endpoint별로 다르게 처리합니다.- KMA
resultCode가00이 아니면 typed exception으로 변환합니다. - APIHub의 이름 없는 query string은 순서를 보존합니다.
- Python docstring과 내부 설명 문구는 한글로 작성합니다.
- 동작 변경에는 테스트를 함께 추가합니다.
기본 검증:
python -m pytest
python -m compileall src/kma tests선택 검증:
ruff check .
mypy src/kma실제 API 호출 테스트는 반드시 opt-in이어야 합니다.
DATA_GO_KR_SERVICE_KEY=<decoded key> python -m pytest -m integration실제 인증키, 인증키가 포함된 URL, 비밀값이 들어 있는 응답 fixture는 커밋하지 않습니다.
사용자에게 보이는 동작이 바뀌면 다음 중 하나 이상을 갱신합니다.
문서의 파일 위치 정보는 src/kma/client.py, docs/testing.md처럼 프로젝트 루트 기준 상대 경로로 적습니다. 로컬 절대 경로는 문서에 남기지 않습니다. 코드 식별자, 명령어, URL, API 파라미터 이름은 원문을 유지합니다.
README.md: 사용법과 예제.kma-api.md: API 세부 사항.docs/troubleshooting.md: 증상과 해결책.docs/repeated-mistakes.md: 반복 실수를 막는 규칙.kma-api.md: 좌표계, enum, category code 같은 API 세부 규칙.docs/api-coverage.md: 구현 범위와 API 개수.docs/apihub-endpoints.md: APIHub 함수형 endpoint 목록.CHANGELOG.md: 릴리스 관점의 변경 사항.
APIHub 공식 목록을 갱신할 때는 다음을 실행해 코드와 문서를 함께 생성합니다.
python -X utf8 tools/update_apihub_endpoints.py짧은 명령형 문장을 사용합니다. 커밋 메시지는 필요하면 영어를 사용할 수 있지만, 프로젝트 문서는 한글로 작성합니다.
Add endpoint-aware precipitation labels
서로 관련 없는 리팩터링은 기능/버그 수정 커밋에 섞지 않습니다.