ecos-reader 0.1.2__tar.gz → 0.1.4__tar.gz

{ecos_reader-0.1.2 → ecos_reader-0.1.4}/API_REFERENCE.md

@@ -2,7 +2,7 @@
 
 **한국은행 ECOS API를 Python에서 쉽게 사용하기**
 
-버전: 0.1.2 | 최종 업데이트: 2025-12-30
+버전: 0.1.3 | 최종 업데이트: 2025-12-30
 
 ---
 
@@ -20,6 +20,7 @@
 7. [실전 활용 예제](#실전-활용-예제)
 8. [문제 해결](#문제-해결)
 9. [빠른 참조](#빠른-참조)
+10. [지표 구현 현황](#지표-구현-현황)
 
 ---
 
@@ -1692,15 +1693,47 @@ from ecos import (
 
 ---
 
+## 지표 구현 현황
+
+ecos-reader는 현재 **13개의 High-Level 지표 함수**를 제공하며, ECOS의 664개 통계표 중 약 2.0%를 구현했습니다.
+
+### 구현 완료 (v0.1.3)
+
+| 카테고리 | 구현 함수 | 개수 |
+|---------|----------|------|
+| **금리** | `get_base_rate()`, `get_treasury_yield()`, `get_yield_spread()` | 3개 |
+| **물가** | `get_cpi()`, `get_core_cpi()`, `get_ppi()` | 3개 |
+| **성장** | `get_gdp()`, `get_gdp_deflator()` | 2개 |
+| **통화** | `get_money_supply()`, `get_bank_lending()` | 2개 |
+
+### 다음 버전 계획
+
+- 🔴 **v0.2.x (Phase 3)**: 환율 및 국제수지 지표
+- 🟡 **v0.3.x (Phase 4)**: 실물경제 및 심리 지표
+- 🟢 **v0.4.x (Phase 5)**: 무역 및 고용 지표
+
+### 자세한 정보
+
+전체 구현 현황, 미구현 통계 목록, 개발 로드맵은 **[IMPLEMENTATION_STATUS.md](IMPLEMENTATION_STATUS.md)**를 참조하세요.
+
+새로운 지표를 직접 구현하고 싶다면 **[CONTRIBUTING.md](CONTRIBUTING.md)**의 가이드를 따라주세요.
+
+---
+
 ## 추가 리소스
 
+### 프로젝트 문서
+- **[구현 현황](IMPLEMENTATION_STATUS.md)**: ECOS 통계 구현 현황 및 로드맵
+- **[기여 가이드](CONTRIBUTING.md)**: 프로젝트 기여 방법
+- **[변경 이력](CHANGELOG.md)**: 버전별 변경사항
+
+### 외부 리소스
 - **ECOS Open API 공식 문서**: [https://ecos.bok.or.kr/api/](https://ecos.bok.or.kr/api/)
 - **GitHub 저장소**: [https://github.com/choo121600/ecos-reader](https://github.com/choo121600/ecos-reader)
 - **이슈 리포트**: [https://github.com/choo121600/ecos-reader/issues](https://github.com/choo121600/ecos-reader/issues)
-- **개발 로드맵**: 프로젝트 루트의 ROADMAP.md
 
 ---
 
-**문서 버전**: 2.0 (사용 가이드)
-**최종 업데이트**: 2025-12-23
-**라이브러리 버전**: 0.1.0
+**문서 버전**: 2.1 (사용 가이드 + 구현 현황)
+**최종 업데이트**: 2025-12-30
+**라이브러리 버전**: 0.1.3

ecos_reader-0.1.4/CHANGELOG.md

@@ -0,0 +1,153 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.4] - 2025-12-31
+
+### Added - 30개 신규 함수
+
+**재정 지표 (1개)**
+- `get_fiscal_balance()` - 통합재정수지
+
+**금융시장 지표 (5개)**
+- `get_stock_index(frequency)` - 주가지수 KOSPI (일별/월별)
+- `get_investor_trading()` - 투자자별 주식거래
+- `get_bond_yield(bond_type)` - 채권 수익률 (종류별/시장별)
+
+**금리 지표 (2개)**
+- `get_bank_deposit_rate(basis)` - 예금은행 수신금리 (신규/잔액)
+- `get_bank_lending_rate(basis)` - 예금은행 대출금리 (신규/잔액)
+
+**통화·금융 지표 (13개)**
+- `get_m1_variants(variant)` - M1 평잔/말잔, 계절조정/원계열
+- `get_m2_variants(variant)` - M2 평잔/말잔, 계절조정/원계열
+- `get_m2_by_holder(variant)` - M2 경제주체별
+- `get_household_credit(category)` - 가계신용 업권별/용도별
+- `get_household_lending_detail()` - 예금취급기관 가계대출 용도별
+- `get_borrower_loan(loan_type)` - 차주별 가계대출 신규/잔액
+
+**성장 지표 (9개)**
+- `get_gdp_growth_rate(frequency)` - 실질 GDP 성장률
+- `get_gdp_by_industry(basis, seasonal_adj, frequency)` - 산업별 GDP
+- `get_gdp_by_expenditure(basis, frequency)` - 지출항목별 GDP
+- `get_gdp_deflator_by_industry(frequency)` - 산업별 GDP 디플레이터
+
+### Changed
+- 모든 stat_code의 item_code를 ECOS API와 검증하여 수정
+- Constants 모듈 확장 (30개 새 stat_code 및 매핑 추가)
+
+### Fixed
+- 조건부 item_code 선택 구현 (일별/월별, 신규/잔액 등)
+
+## [0.1.3] - 2025-12-30
+
+### Fixed
+- **통계코드 및 항목코드 수정**: 실제 ECOS API와 일치하도록 모든 지표의 stat_code와 item_code 수정
+  - 근원 CPI: 항목코드 `AA0000` → `00`
+  - 생산자물가지수(PPI): 항목코드 `A00` → `*AA`
+  - 실질 GDP: 통계코드 `200Y001` → `200Y110`, 항목코드 `10101` → `10601`
+  - 명목 GDP: 통계코드 `200Y002` → `200Y109`, 항목코드 `10101` → `10601`
+  - GDP 디플레이터: 통계코드 `200Y004` → `200Y112`, 항목코드 `10101` → `10601`
+  - M1 통화량: 통계코드 `101Y018`/항목 `BBLS00` → `161Y004`/`BBKA00`
+  - M2 통화량: 별도 통계코드 `161Y008` 사용
+  - Lf 통화량: 별도 통계코드 `171Y002` 사용
+- **통화 지표 구조 개선**: 각 통화량 지표(M1, M2, Lf)가 올바른 통계코드를 사용하도록 수정
+- **은행 대출 함수 개선**: 가계대출 지원 추가, 기업대출은 별도 통계표 필요로 제거
+
+### Added
+- **E2E 테스트 확대**: 모든 High-Level 지표 함수에 대한 18개의 E2E 테스트 추가
+  - 금리 지표: 기준금리, 국고채 수익률, 장단기 금리차
+  - 물가 지표: CPI, 근원 CPI, PPI
+  - 성장 지표: GDP(분기/연간, 실질/명목), GDP 디플레이터
+  - 통화 지표: M1/M2/Lf, 은행 대출(전체/가계)
+  - 통합 워크플로우 및 캐시 기능 테스트
+
+### Changed
+- `constants.py`: 모든 통계코드와 항목코드를 실제 API 응답과 일치하도록 업데이트
+- `money.py`: 통화량 조회 시 지표별로 다른 통계코드를 사용하도록 리팩토링
+- `test_e2e_indicators.py`: 실제 API 응답에 맞춰 테스트 기대값 수정
+
+## [0.1.2] - 2025-12-30
+
+### Added
+- **완전한 ECOS API 지원**: 누락되었던 3개의 API 엔드포인트 추가
+  - `get_statistic_word()` - 통계용어사전 조회
+  - `get_key_statistic_list()` - 100대 통계지표 조회
+  - `get_statistic_meta()` - 통계메타DB 조회
+- **확장된 주기 지원**: 반년(S), 반월(SM) 주기 타입 추가
+- **향상된 날짜 파싱**: 모든 ECOS 날짜 형식 지원
+  - 연간 (YYYY)
+  - 반년 (YYYYSN)
+  - 분기 (YYYYQN)
+  - 월간 (YYYYMM)
+  - 반월 (YYYYMMSMN)
+  - 일간 (YYYYMMDD)
+- **포괄적인 E2E 테스트**: 실제 API를 사용한 13개의 통합 테스트 추가
+- **완전한 API 필드 매핑**: 모든 API 응답 필드에 대한 파서 지원
+
+### Changed
+- `EcosService` 타입에 `StatisticMeta` 추가
+- `Period` 타입 확장: `D`, `M`, `Q`, `A`, `S`, `SM` 모두 지원
+- 파서 컬럼 매핑 확장: StatisticWord, KeyStatisticList, StatisticMeta, StatisticTableList의 모든 필드 포함
+
+### Fixed
+- 공식 ECOS API 가이드와 완전히 일치하도록 코드 리팩토링
+- URL 구성 및 파라미터 처리 개선
+
+## [0.1.1] - 2025-12-30
+
+### Added
+- 완전한 MkDocs 문서 사이트
+  - 설치 가이드 및 빠른 시작
+  - 사용자 가이드 (기본 사용법, 금리/물가/성장/통화 지표, 고급 기능)
+  - API 레퍼런스 (클라이언트, 지표 함수, 예외 처리)
+  - 실전 예제 (기본 사용법, 거시경제 대시보드)
+  - 기여 가이드
+- GitHub Actions 워크플로우를 통한 문서 자동 배포
+- `docs` optional dependency 추가 (mkdocs, mkdocs-material)
+
+### Changed
+- README에 문서 링크 추가
+- pyproject.toml의 Documentation URL을 GitHub Pages로 업데이트
+
+## [0.1.0] - 2025-12-30
+
+### Added
+- 초기 릴리스
+- 한국은행 ECOS Open API 클라이언트 구현
+- 금리 지표 조회
+  - 한국은행 기준금리 (`get_base_rate`)
+  - 국고채 수익률 (`get_treasury_yield`)
+  - 장단기 금리차 (`get_yield_spread`)
+- 물가 지표 조회
+  - 소비자물가지수 (`get_cpi`)
+  - 근원 CPI (`get_core_cpi`)
+  - 생산자물가지수 (`get_ppi`)
+- 성장 지표 조회
+  - GDP (`get_gdp`)
+  - GDP 디플레이터 (`get_gdp_deflator`)
+- 통화 지표 조회
+  - 통화량 (`get_money_supply`)
+  - 은행 대출 (`get_bank_lending`)
+- API 키 설정 기능
+  - 환경 변수 지원
+  - `.env` 파일 지원
+  - 코드에서 직접 설정
+- 자동 캐싱 기능
+- 에러 처리
+  - `EcosConfigError` - 설정 오류
+  - `EcosNetworkError` - 네트워크 오류
+  - `EcosAPIError` - API 응답 오류
+- 로깅 지원
+- 타입 힌팅
+- 단위 테스트 및 커버리지
+- 예제 코드
+  - 기본 사용법 (`examples/basic_usage.py`)
+  - 거시경제 대시보드 (`examples/macro_dashboard.py`)
+
+[0.1.2]: https://github.com/choo121600/ecos-reader/compare/v0.1.1...v0.1.2
+[0.1.1]: https://github.com/choo121600/ecos-reader/compare/v0.1.0...v0.1.1
+[0.1.0]: https://github.com/choo121600/ecos-reader/releases/tag/v0.1.0