ecos-reader 0.2.2__tar.gz → 0.3.0__tar.gz

{ecos_reader-0.2.2 → ecos_reader-0.3.0}/CHANGELOG.md

@@ -5,6 +5,30 @@ 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.3.0] - 2026-05-31
+
+> Epic #56(Partial-coverage 재설계)의 **BREAKING** 릴리스. 함수명이 전체 시리즈를
+> 시사하지만 단일 ECOS 항목만 반환하던 함수들을 전체 시리즈 long-format +
+> `sub_category` 선택으로 재설계했습니다. 마이그레이션: 사용자 가이드 > v0.3.0 마이그레이션.
+
+### Changed (BREAKING)
+- partial-coverage 함수들의 기본 반환이 **단일 시계열 → 전체 분류 long-format**
+  (`date, category_value, value, unit`)으로 변경. 단일 시계열은 `sub_category` 로 선택.
+  - `get_gdp_by_industry` / `get_gdp_by_expenditure` / `get_gdp_deflator_by_industry` — PR #85 (#59)
+  - `get_stock_index(monthly)`(item_code 1010000 회사수 → 1070000 KOSPI 종가 정정) /
+    `get_investor_trading`(`action`·`metric` 인자 추가) — PR #86 (#60)
+  - `get_cpi_monthly` — PR #87 (#61)
+  - `get_household_lending_detail` — PR #88 (#62)
+  - `get_bond_yield`(`measure` 인자 추가, 종류별/시장별 분류) — PR #89 (#63)
+- 공통 헬퍼 `select_subcategory` 도입(규약: 개발 > Partial-coverage 재설계 규약). PR #68 (#58).
+
+### Removed (BREAKING)
+- `EcosPartialCoverageWarning` 클래스 및 내부 `ecos.indicators._deprecations` 모듈 제거.
+  모든 partial-coverage 함수가 재설계되어 더 이상 경고를 내지 않습니다. (#64)
+
+### Added
+- v0.3.0 마이그레이션 가이드(사용자 가이드). (#64)
+
 ## [0.2.2] - 2026-05-30
 
 > Epic #3(Extensibility & Long-term Design)의 하위 작업을 정리한 릴리스.
@@ -296,6 +320,7 @@ v0.1.6 라이브 e2e 검증에서 드러난 follow-up(#2 Reliability epic)을
   - 기본 사용법 (`examples/basic_usage.py`)
   - 거시경제 대시보드 (`examples/macro_dashboard.py`)
 
+[0.3.0]: https://github.com/choo121600/ecos-reader/compare/v0.2.2...v0.3.0
 [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

{ecos_reader-0.2.2 → ecos_reader-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ecos-reader
-Version: 0.2.2
+Version: 0.3.0
 Summary: 한국은행 ECOS Open API Python 클라이언트
 Project-URL: Homepage, https://github.com/choo121600/ecos-reader
 Project-URL: Documentation, https://choo121600.github.io/ecos-reader/
@@ -169,7 +169,7 @@ print(df)
 | 함수 | 설명 | 주기 |
 |-----|------|-----|
 | `get_household_credit(category)` | 가계신용 (업권별/용도별) | 분기 |
-| `get_household_lending_detail()` | 예금취급기관 가계대출 (용도별) | 월 |
+| `get_household_lending_detail(sub_category)` | 예금취급기관 가계대출 (용도별) | 월 |
 | `get_borrower_loan(loan_type, category)` | 차주별 가계대출 (신규/잔액) | 분기 |
 
 ### 재정·금융시장 지표
@@ -177,23 +177,17 @@ print(df)
 | 함수 | 설명 | 주기 |
 |-----|------|-----|
 | `get_fiscal_balance()` | 통합재정수지 | 월 |
-| `get_stock_index(frequency)` | 주가지수 KOSPI (일별/월별) | 일/월 |
-| `get_investor_trading()` | 투자자별 주식거래 | 월 |
-| `get_bond_yield(bond_type)` | 채권 수익률 (종류별/시장별) | 월 |
-
-> ⚠️ 다음 함수들은 v0.1.6 기준 단일 ECOS item만 반환하며 호출 시
-> `ecos.EcosPartialCoverageWarning`(`UserWarning` 서브클래스, 기본 필터로도 표시)이
-> 발생합니다. v0.3.0에서 시그니처가 변경됩니다: `get_gdp_by_industry`,
-> `get_gdp_by_expenditure`, `get_gdp_deflator_by_industry`,
-> `get_stock_index(monthly)`, `get_investor_trading`, `get_bond_yield`,
-> `get_household_lending_detail`, `get_borrower_loan`, `get_cpi_monthly`.
-> 자세한 내용은 이슈 #8.
->
-> 경고를 끄려면:
-> ```python
-> import warnings, ecos
-> warnings.simplefilter("ignore", ecos.EcosPartialCoverageWarning)
-> ```
+| `get_stock_index(frequency, sub_category)` | 주가지수 KOSPI (일별/월별) | 일/월 |
+| `get_investor_trading(action, metric, sub_category)` | 투자자별 주식거래 | 월 |
+| `get_bond_yield(bond_type, measure, sub_category)` | 채권 거래 (종류별/시장별) | 월 |
+
+> ℹ️ v0.3.0(#59~#63)에서 과거 단일 ECOS item만 반환하던 함수들이 모두 전체 시리즈
+> long-format + `sub_category` 선택으로 재설계되었습니다:
+> `get_gdp_by_industry`, `get_gdp_by_expenditure`, `get_gdp_deflator_by_industry`,
+> `get_stock_index(monthly)`, `get_investor_trading`, `get_cpi_monthly`,
+> `get_household_lending_detail`, `get_bond_yield`, `get_borrower_loan`(v0.2.0 #29).
+> 과거의 `EcosPartialCoverageWarning`은 제거되었습니다(#64). 자세한 변경·마이그레이션은
+> [v0.3.0 마이그레이션 가이드](docs/user-guide/migration-v0.3.0.md)를 참고하세요.
 
 ## 상세 사용법
 

{ecos_reader-0.2.2 → ecos_reader-0.3.0}/README.md

@@ -125,7 +125,7 @@ print(df)
 | 함수 | 설명 | 주기 |
 |-----|------|-----|
 | `get_household_credit(category)` | 가계신용 (업권별/용도별) | 분기 |
-| `get_household_lending_detail()` | 예금취급기관 가계대출 (용도별) | 월 |
+| `get_household_lending_detail(sub_category)` | 예금취급기관 가계대출 (용도별) | 월 |
 | `get_borrower_loan(loan_type, category)` | 차주별 가계대출 (신규/잔액) | 분기 |
 
 ### 재정·금융시장 지표
@@ -133,23 +133,17 @@ print(df)
 | 함수 | 설명 | 주기 |
 |-----|------|-----|
 | `get_fiscal_balance()` | 통합재정수지 | 월 |
-| `get_stock_index(frequency)` | 주가지수 KOSPI (일별/월별) | 일/월 |
-| `get_investor_trading()` | 투자자별 주식거래 | 월 |
-| `get_bond_yield(bond_type)` | 채권 수익률 (종류별/시장별) | 월 |
-
-> ⚠️ 다음 함수들은 v0.1.6 기준 단일 ECOS item만 반환하며 호출 시
-> `ecos.EcosPartialCoverageWarning`(`UserWarning` 서브클래스, 기본 필터로도 표시)이
-> 발생합니다. v0.3.0에서 시그니처가 변경됩니다: `get_gdp_by_industry`,
-> `get_gdp_by_expenditure`, `get_gdp_deflator_by_industry`,
-> `get_stock_index(monthly)`, `get_investor_trading`, `get_bond_yield`,
-> `get_household_lending_detail`, `get_borrower_loan`, `get_cpi_monthly`.
-> 자세한 내용은 이슈 #8.
->
-> 경고를 끄려면:
-> ```python
-> import warnings, ecos
-> warnings.simplefilter("ignore", ecos.EcosPartialCoverageWarning)
-> ```
+| `get_stock_index(frequency, sub_category)` | 주가지수 KOSPI (일별/월별) | 일/월 |
+| `get_investor_trading(action, metric, sub_category)` | 투자자별 주식거래 | 월 |
+| `get_bond_yield(bond_type, measure, sub_category)` | 채권 거래 (종류별/시장별) | 월 |
+
+> ℹ️ v0.3.0(#59~#63)에서 과거 단일 ECOS item만 반환하던 함수들이 모두 전체 시리즈
+> long-format + `sub_category` 선택으로 재설계되었습니다:
+> `get_gdp_by_industry`, `get_gdp_by_expenditure`, `get_gdp_deflator_by_industry`,
+> `get_stock_index(monthly)`, `get_investor_trading`, `get_cpi_monthly`,
+> `get_household_lending_detail`, `get_bond_yield`, `get_borrower_loan`(v0.2.0 #29).
+> 과거의 `EcosPartialCoverageWarning`은 제거되었습니다(#64). 자세한 변경·마이그레이션은
+> [v0.3.0 마이그레이션 가이드](docs/user-guide/migration-v0.3.0.md)를 참고하세요.
 
 ## 상세 사용법
 

{ecos_reader-0.2.2 → ecos_reader-0.3.0}/docs/api-reference/exceptions.md

@@ -29,7 +29,3 @@ ecos-reader가 발생시키는 예외 및 경고 클래스의 자동 생성 API
 ::: ecos.EcosValidationError
     options:
       heading_level: 2
-
-::: ecos.EcosPartialCoverageWarning
-    options:
-      heading_level: 2

ecos_reader-0.3.0/docs/development/partial-coverage-redesign.md

@@ -0,0 +1,69 @@
+# Partial-coverage 재설계 규약
+
+> v0.3.0 마일스톤(epic [#56](https://github.com/choo121600/ecos-reader/issues/56))의 공통 설계 규약입니다. 카테고리별 하위 이슈(#59~#63)는 모두 이 규약을 따릅니다.
+
+## 배경
+
+일부 지표 함수는 함수명이 **전체 시리즈**(예: "산업별 GDP", "투자자별 거래")를 시사하지만, v0.2.x 까지는 실제로 ECOS `item_code1` 단일 항목만 조회해 반환했습니다. 이들은 한동안 `EcosPartialCoverageWarning`([#8](https://github.com/choo121600/ecos-reader/issues/8))과 함께 동작했고, v0.3.0([#56](https://github.com/choo121600/ecos-reader/issues/56))에서 함수 시그니처를 바꿔 전체 시리즈 또는 sub-category 선택을 제공하도록 재설계되었습니다. 재설계 완료 후 경고 클래스는 [#64](https://github.com/choo121600/ecos-reader/issues/64)에서 제거되었습니다.
+
+레퍼런스는 v0.2.0 의 [`get_borrower_loan`](https://github.com/choo121600/ecos-reader/pull/29) 재설계입니다. 이 규약은 그 패턴을 일반화한 것입니다.
+
+## 핵심 사실: ECOS `item_code1` 은 정확 일치 필터
+
+ECOS 의 한 통계표(`stat_code`)는 여러 세부 항목을 `item_code1` 으로 묶어 제공합니다. 분류축(연령·지역·업권 등)은 별도 `stat_code` 가 아니라 `item_code1` **prefix** 로 표현되는 경우가 많습니다.
+
+ECOS API 의 `item_code1` 파라미터는 *정확 일치* 만 지원하므로 prefix 조회가 불가능합니다. 따라서 재설계 함수는 **`item_code1` 필터 없이 통계표 전량을 받아 client-side 에서 분류축을 필터링**합니다.
+
+## 규약
+
+1. **입력 검증** — 허용되지 않는 인자는 사용 가능 목록과 함께 `ValueError`. 검증은 네트워크 호출 전에 수행합니다.
+2. **전량 조회** — `client.get_statistic_search(...)` 를 `item_code1` 없이 호출합니다.
+3. **분류축 필터 + 형식 결정** — `parse_response` 결과를 [`select_subcategory`](#select_subcategory)에 넘깁니다.
+    - `sub_category` **미지정**: 분류축 전체를 long-format(`date, category_value, value, unit`)으로 반환하며 `category_value` 컬럼에 세부 항목명을 담습니다.
+    - `sub_category` **지정**: 해당 세부 항목 단일 시계열(`date, value, unit`)만 반환합니다. 항목명(`item_name1`)과 `item_code1` 둘 다 허용합니다.
+4. **친절한 에러** — 존재하지 않는 `sub_category` 는 **사용 가능한 항목 목록과 함께** `ValueError` 를 던집니다.
+
+## `select_subcategory`
+
+공통 선택 로직은 `ecos.indicators._subcategory.select_subcategory` 에 있습니다.
+
+```python
+from ecos.indicators._subcategory import select_subcategory
+
+def get_something(sub_category=None, start_date=None, end_date=None):
+    # 1) 입력 검증 + 기본 날짜 (생략)
+    client = get_client()
+    response = client.get_statistic_search(
+        stat_code=STAT_SOMETHING,
+        period=PERIOD_MONTHLY,
+        start_date=start_date,
+        end_date=end_date,
+    )  # item_code1 미지정 → 전량 수신
+    df = parse_response(response)
+    return select_subcategory(
+        df,
+        prefix=PREFIX,    # 분류축 item_code1 prefix
+        exact=False,      # 단일 코드 정확 일치가 필요하면 True
+        sub_category=sub_category,
+        context="<함수 맥락 설명>",  # ValueError 메시지에 포함
+    )
+```
+
+| 인자 | 의미 |
+| --- | --- |
+| `prefix` | 분류축 `item_code1` prefix (또는 `exact=True` 일 때 정확코드) |
+| `exact` | `True` → `item_code1 == prefix` 정확 일치 / `False` → `startswith` 매칭 |
+| `sub_category` | 세부 항목명 또는 `item_code1`. 미지정 시 long-format |
+| `context` | `ValueError` 메시지에 포함할 호출 맥락 (예: `"category='연령별'"`) |
+
+분류축 메타데이터(`{분류축: prefix}` 매핑 등)는 함수가 속한 카테고리 모듈 또는 `constants.py` 에 선언합니다. 레퍼런스: `constants.BORROWER_LOAN_CATEGORY_PREFIX`.
+
+### 경계 동작 (하위 이슈가 지켜야 할 계약)
+
+- **빈 결과**: 매칭되는 항목이 없으면 빈 DataFrame 을 반환합니다. 컬럼 구성은 보장하지 않으므로 호출자는 `.empty` 로 판별합니다.
+- **항목명 중복**: `item_name1` 은 분류축 내에서 유일하지 않을 수 있습니다. 이름이 겹치는 통계표라면 사용자가 `item_code1` 으로 단일 시계열을 선택할 수 있도록 안내하고, 가능하면 docstring 의 사용 가능 항목 예시에 코드를 함께 노출합니다.
+- **항목명 결측**: `item_name1` 이 결측인 행은 long-format 의 `category_value` 가 결측으로 남습니다. 그대로 두는 것이 기본이며, 결측이 잦은 통계표는 함수 단에서 보정합니다.
+
+## 마이그레이션 영향
+
+이 재설계는 **BREAKING** 변경입니다. 단일 시계열을 반환하던 함수가 기본적으로 long-format 을 반환하게 됩니다. 기존 동작을 원하는 호출자는 `sub_category` 를 명시하거나 `EcosClient.get_statistic_search` 를 직접 사용해야 합니다. 함수별 변경 내역과 마이그레이션 방법은 [v0.3.0 마이그레이션 가이드](../user-guide/migration-v0.3.0.md)를 참고하세요.