kpubdata 0.1.1__tar.gz → 0.2.2__tar.gz

kpubdata-0.2.2/.sisyphus/remove-get-record-plan.md

@@ -0,0 +1,18 @@
+## Scope
+- Remove `get_record` from the provider protocol, registry validation, dataset binding, tests, and docs.
+
+## Touched modules
+- `src/kpubdata/core/protocol.py`
+- `src/kpubdata/core/dataset.py`
+- `src/kpubdata/registry.py`
+- affected unit/integration/contract tests
+- API and architecture docs describing removed single-record access
+
+## Risks
+- Public `Dataset.get()` removal can leave stale docs/tests behind.
+- Registry validation and protocol changes can break fake adapters in tests.
+
+## Validation steps
+- Run LSP diagnostics on changed source and test files.
+- Run `uv run pytest`.
+- Run `uv run mypy src`.

{kpubdata-0.1.1 → kpubdata-0.2.2}/API_SPEC.md

@@ -43,12 +43,21 @@ dataset = client.dataset("molit.apartment_trades")
 result = dataset.list(lawd_code="11680", deal_ym="202503")
 ```
 
-### Single record
+`list()` returns exactly one page of results. When another page is available,
+the returned `RecordBatch.next_page` is set.
+
+### List all pages
 
 ```python
-record = dataset.get(id="...")
+dataset = client.dataset("molit.apartment_trades")
+for batch in dataset.list_all(lawd_code="11680", deal_ym="202503"):
+    for item in batch.items:
+        print(item)
 ```
 
+`list_all()` yields one `RecordBatch` per page and follows `next_page`
+automatically until pagination is exhausted.
+
 ### Schema
 
 ```python
@@ -82,9 +91,9 @@ Rules:
 
 Returns `RecordBatch`.
 
-### `get()`
+### `list_all()`
 
-Returns one normalized record or `None`.
+Returns a generator of `RecordBatch` values, one per page.
 
 ### `schema()`
 
@@ -101,7 +110,7 @@ KPubData promises stability for:
 - `Client`
 - `Client.from_env()`
 - dataset discovery methods
-- `Dataset.list/get/schema/call_raw`
+- `Dataset.list/list_all/schema/call_raw`
 - canonical model classes
 - canonical error types
 
@@ -157,4 +166,3 @@ client.call_provider_endpoint("seoul", "SearchSTNTimeTableByIDService", ...)
 | :--- | :--- | :--- |
 | [kpubdata-builder](https://github.com/yeongseon/kpubdata-builder) | [API_CONTRACT.md](https://github.com/yeongseon/kpubdata-builder/blob/main/API_CONTRACT.md) | Builder API 규약 |
 | [kpubdata-studio](https://github.com/yeongseon/kpubdata-studio) | [API_CONTRACT.md](https://github.com/yeongseon/kpubdata-studio/blob/main/API_CONTRACT.md) | Studio API 규약 |
-

{kpubdata-0.1.1 → kpubdata-0.2.2}/ARCHITECTURE.md

@@ -144,7 +144,92 @@ KPubData는 이 모든 은행을 대신 처리해주는 **"통합 키오스크"*
 5.  **5단계: 결과 반환 (Return)**
     - 최종적으로 예쁘게 포장된 `RecordBatch` 객체가 사용자에게 전달됩니다.
 
-## 6. 자주 묻는 질문 (FAQ)
+## 6. 인증 흐름 (Authentication Flow)
+
+### 6.1 개요
+
+공공데이터 API를 사용하려면 각 기관에서 발급한 **인증키(API Key)**가 필요합니다. KPubData는 이 키를 사용자로부터 받아 각 기관이 요구하는 방식으로 HTTP 요청에 주입합니다.
+
+핵심 설계 원칙:
+- **키 저장은 `KPubDataConfig`에 집중**: 모든 기관의 키를 한 곳에서 관리합니다.
+- **키 주입은 각 어댑터에 위임**: 기관마다 키를 넣는 위치와 파라미터 이름이 다르므로, 이 로직은 어댑터가 담당합니다.
+- **환경변수 우선 해석**: 명시적으로 전달된 키 → `KPUBDATA_*` 환경변수 → fallback 환경변수 순으로 탐색합니다.
+
+### 6.2 키 해석 우선순위
+
+```mermaid
+flowchart TD
+    Start[키 요청: require_provider_key] --> E1{명시적으로 전달된 키?}
+    E1 -- 있음 --> Use[키 반환]
+    E1 -- 없음 --> E2{KPUBDATA_{PROVIDER}_API_KEY 환경변수?}
+    E2 -- 있음 --> Use
+    E2 -- 없음 --> E3{"{PROVIDER}_API_KEY" 환경변수?}
+    E3 -- 있음 --> Use
+    E3 -- 없음 --> Err[ConfigError 발생]
+```
+
+```python
+# 1순위: 명시적 전달
+client = Client(provider_keys={"datago": "MY_KEY"})
+
+# 2순위: KPUBDATA_ 접두사 환경변수
+# export KPUBDATA_DATAGO_API_KEY="MY_KEY"
+client = Client.from_env()
+
+# 3순위: 접두사 없는 환경변수 (fallback)
+# export DATAGO_API_KEY="MY_KEY"
+client = Client.from_env()
+```
+
+**관련 코드**: `src/kpubdata/config.py` → `KPubDataConfig.get_provider_key()`, `require_provider_key()`
+
+### 6.3 키의 내부 전달 경로
+
+```mermaid
+sequenceDiagram
+    participant U as 사용자
+    participant C as Client
+    participant Cfg as KPubDataConfig
+    participant A as ProviderAdapter
+    participant T as HttpTransport
+    participant P as 공공 API
+
+    U->>C: Client(provider_keys={"datago": "KEY"})
+    C->>Cfg: KPubDataConfig(provider_keys={...})
+    Note over Cfg: 키를 dict에 보관
+
+    U->>C: dataset("datago.village_fcst").list(...)
+    C->>A: query_records(dataset_ref, query)
+    A->>Cfg: require_provider_key("datago")
+    Cfg-->>A: "KEY" 반환
+    A->>A: _build_params()에서 키를 HTTP 파라미터에 주입
+    A->>T: HTTP 요청 (키 포함)
+    T->>P: GET https://apis.data.go.kr/...?serviceKey=KEY
+    P-->>T: 응답
+```
+
+**핵심 메서드**: 모든 어댑터는 `_require_api_key()` → `self._config.require_provider_key("slug")` 패턴을 사용합니다.
+
+## 7. 페이지네이션 전략 (Pagination Strategy)
+
+KPubData는 대량의 데이터를 효율적으로 가져오기 위해 두 가지 페이지네이션 전략을 사용합니다.
+
+### 7.1 전략 종류
+- **오프셋 기반 (Offset-based)**: 페이지 번호를 이용해 데이터를 요청합니다. `next_page` 값이 반환됩니다.
+- **커서 기반 (Cursor-based)**: 특정 지점을 가리키는 포인터(커서)를 이용해 다음 데이터를 요청합니다. `next_cursor` 값이 반환됩니다.
+
+### 7.2 동작 원리 및 휴리스틱 (Heuristic)
+어댑터는 가용한 정보에 따라 다음과 같이 다음 페이지 존재 여부를 결정합니다.
+1. **정밀 계산**: `total_count` 정보를 알 수 있는 경우(예: bok, lofin), 현재까지 가져온 개수와 전체 개수를 비교해 `next_page`를 정확히 계산합니다.
+2. **Best-effort 휴리스틱**: 전체 개수 정보가 없는 경우(예: datago), `len(items) == page_size` 공식을 사용합니다.
+   - 현재 페이지의 아이템 개수가 요청한 페이지 크기와 같다면, 다음 페이지가 더 있을 것으로 가정합니다.
+   - 이 방식은 마지막 데이터가 딱 페이지 크기에 맞춰 끝날 경우, 실제로 데이터가 없는 다음 페이지를 한 번 더 호출하는 **추가 fetch(Extra empty fetch)**가 발생할 수 있습니다. 이는 문서화된 트레이드오프(trade-off)입니다.
+
+### 7.3 list_all()의 처리
+사용자가 `list_all()` 메서드를 호출하면, KPubData는 어댑터가 반환하는 전략(`next_cursor` 우선, 없으면 `next_page`)을 자동으로 판단하여 모든 데이터를 순회합니다.
+
+## 8. 자주 묻는 질문 (FAQ)
+
 
 **Q: 새 데이터셋을 추가하려면 어디를 수정하나요?**
 A: 해당 기관의 어댑터(`providers/<provider>/adapter.py`)와 데이터 목록 파일(`catalogue.json`)을 수정하면 됩니다.

{kpubdata-0.1.1 → kpubdata-0.2.2}/CANONICAL_MODEL.md

@@ -312,7 +312,6 @@ class Dataset:
     ref: DatasetRef
 
     def list(self, **filters) -> RecordBatch: ...
-    def get(self, **key) -> dict[str, object] | None: ...
     def schema(self) -> SchemaDescriptor | None: ...
     def call_raw(self, operation: str, **params) -> object: ...
 ```
@@ -352,4 +351,3 @@ Do not erase provider-native detail.
 | [PROVIDER_ADAPTER_CONTRACT.md](./PROVIDER_ADAPTER_CONTRACT.md) | 어댑터 구현 규약 |
 | [API_SPEC.md](./API_SPEC.md) | 파이썬 API 명세 |
 | [VALIDATION.md](./VALIDATION.md) | 아키텍처 타당성 검증 |
-

{kpubdata-0.1.1 → kpubdata-0.2.2}/CHANGELOG.md

@@ -7,6 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.0] - 2025-04-17
+
+### Added
+- Single-page pagination contract for all adapters (datago, bok, lofin, kosis)
+- `Dataset.list_all()` generator for automatic multi-page iteration
+- `RecordBatch.to_pandas()` for pandas DataFrame conversion (optional `pandas` dependency)
+- Unit tests for BOK and LOFIN adapters
+
+### Changed
+- Default `page_size` increased from 10 to 100
+- **Breaking**: `query_records()` now returns a single page instead of auto-draining all pages
+
+### Removed
+- Unreachable single-record adapter stubs
+- Single-record access from the provider and dataset public APIs
+
+## [0.1.0] - 2025-04-10
+
 ### Added
 
 - Core framework: `Client`, `Dataset`, `Catalog`, `Query`, `RecordBatch` public API

{kpubdata-0.1.1 → kpubdata-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kpubdata
-Version: 0.1.1
+Version: 0.2.2
 Summary: Dialect-inspired Python access framework for Korean public data
 Author: Yeongseon Choe
 License: MIT
@@ -297,6 +297,37 @@ for item in result.items[:5]:
 # ...
 ```
 
+### 9. 전체 페이지 자동 조회 (list_all)
+
+대량의 데이터를 페이지 단위로 자동 순회하려면 `list_all()`을 사용합니다.
+
+```python
+ds = client.dataset("lofin.expenditure_budget")
+
+# 모든 페이지를 자동으로 순회하며 RecordBatch를 반환
+for batch in ds.list_all(fyr="2024"):
+    print(f"이번 페이지: {len(batch.items)}건")
+    for item in batch.items:
+        print(item)
+```
+
+### 10. pandas DataFrame 변환
+
+조회 결과를 pandas DataFrame으로 변환하여 분석할 수 있습니다.
+
+```bash
+pip install kpubdata[pandas]
+```
+
+```python
+ds = client.dataset("bok.base_rate")
+result = ds.list(start_date="202401", end_date="202412")
+
+# pandas DataFrame으로 변환
+df = result.to_pandas()
+print(df.head())
+```
+
 ## 지원 중인 공공데이터
 
 현재 지원 현황의 상세 정보와 진행 예정 항목은 [SUPPORTED_DATA.md](./SUPPORTED_DATA.md)에서 확인할 수 있습니다.
@@ -316,6 +347,9 @@ for item in result.items[:5]:
 | 지방재정365 (`lofin`) | 기능별세출 (`expenditure_function`) | 지원 |
 | 지방재정365 (`lofin`) | 채무비율현황 (`debt_ratio`) | 지원 |
 | 지방재정365 (`lofin`) | 재정자립도현황 (`fiscal_independence`) | 지원 |
+| 지방재정365 (`lofin`) | 재원별 세입결산 (`revenue_by_source`) | 지원 |
+
+> 검증 수준 및 실API 최종 검증일 등 상세 정보는 [SUPPORTED_DATA.md](./SUPPORTED_DATA.md)를 참고하세요.
 
 ## 문서 가이드 (Document Guide)
 
@@ -378,3 +412,4 @@ KPubData의 설계 철학과 사용 방법을 안내하는 문서 목록입니
 
 ### v0.3
 - 표준 코어를 기반으로 한 경량 [MCP](https://modelcontextprotocol.io/)(Model Context Protocol — AI 모델이 외부 도구를 사용하는 표준 규약) 어댑터 지원
+

{kpubdata-0.1.1 → kpubdata-0.2.2}/PRD.md

@@ -157,16 +157,7 @@ Acceptance:
 - includes `raw`
 - includes metadata about pagination and provider
 
-### FR-6. Single-record access
-
-Supported datasets may expose a single-record get operation.
-
-Acceptance:
-
-- `dataset.get(...)`
-- unsupported datasets raise `UnsupportedCapabilityError`
-
-### FR-7. Schema/metadata access
+### FR-6. Schema/metadata access
 
 Datasets may expose schema or field metadata.
 
@@ -175,7 +166,7 @@ Acceptance:
 - `dataset.schema()`
 - returns `SchemaDescriptor | None`
 
-### FR-8. Raw access
+### FR-7. Raw access
 
 Every provider adapter must expose a raw-call path.
 
@@ -303,4 +294,3 @@ client.getRTMSDataSvcAptTradeDev(...)
 | :--- | :--- | :--- |
 | [kpubdata-builder](https://github.com/yeongseon/kpubdata-builder) | [PRD.md](https://github.com/yeongseon/kpubdata-builder/blob/main/PRD.md) | Builder 제품 요구사항 |
 | [kpubdata-studio](https://github.com/yeongseon/kpubdata-studio) | [PRD.md](https://github.com/yeongseon/kpubdata-studio/blob/main/PRD.md) | Studio 제품 요구사항 |
-

{kpubdata-0.1.1 → kpubdata-0.2.2}/PROVIDER_ADAPTER_CONTRACT.md

@@ -149,7 +149,6 @@ class ProviderAdapter(Protocol):
     def search_datasets(self, text: str) -> list[DatasetRef]: ...
     def get_dataset(self, dataset_id: str) -> DatasetRef: ...
     def query_records(self, dataset: DatasetRef, query: Query) -> RecordBatch: ...
-    def get_record(self, dataset: DatasetRef, key: dict[str, object]) -> dict[str, object] | None: ...
     def get_schema(self, dataset: DatasetRef) -> SchemaDescriptor | None: ...
     def call_raw(self, dataset: DatasetRef, operation: str, params: dict[str, object]) -> object: ...
 ```
@@ -163,13 +162,20 @@ classDiagram
         +search_datasets(text: str) list~DatasetRef~
         +get_dataset(dataset_id: str) DatasetRef
         +query_records(dataset: DatasetRef, query: Query) RecordBatch
-        +get_record(dataset: DatasetRef, key: dict) dict
         +get_schema(dataset: DatasetRef) SchemaDescriptor
         +call_raw(dataset: DatasetRef, op: str, params: dict) object
     }
 ```
 
-## 4. Capability rules
+## 4. 페이지네이션 반환 규약 (Pagination Return Contract)
+
+어댑터는 `query_records` 결과로 반환되는 `RecordBatch`에 다음 페이지 정보를 포함해야 합니다.
+
+- **`next_page` 또는 `next_cursor` 반환**: 어댑터는 반드시 둘 중 하나를 반환하거나, 마지막 페이지인 경우 둘 다 `None`을 반환해야 합니다.
+- **우선순위**: `list_all()`은 `next_cursor`가 존재할 경우 이를 우선적으로 사용하며, 없을 경우 `next_page`를 사용합니다.
+- **권장 방식**: 가급적 `total_count` 기반의 정밀한 계산 방식을 선호합니다. 하지만 전체 개수 정보를 알 수 없는 경우 `len(items) == page_size` 휴리스틱을 사용하는 것도 허용됩니다.
+
+## 5. Capability rules
 
 - declare only what the adapter truly supports
 - if an operation is unavailable, raise `UnsupportedCapabilityError`
@@ -248,4 +254,3 @@ Otherwise, keep the complexity local to the adapter.
 | [API_SPEC.md](./API_SPEC.md) | 파이썬 API 명세 |
 | [VALIDATION.md](./VALIDATION.md) | 아키텍처 타당성 검증 |
 | [AGENTS.md](./AGENTS.md) | 어댑터 개발 가이드 및 에이전트 규칙 |
-

{kpubdata-0.1.1 → kpubdata-0.2.2}/README.md

@@ -260,6 +260,37 @@ for item in result.items[:5]:
 # ...
 ```
 
+### 9. 전체 페이지 자동 조회 (list_all)
+
+대량의 데이터를 페이지 단위로 자동 순회하려면 `list_all()`을 사용합니다.
+
+```python
+ds = client.dataset("lofin.expenditure_budget")
+
+# 모든 페이지를 자동으로 순회하며 RecordBatch를 반환
+for batch in ds.list_all(fyr="2024"):
+    print(f"이번 페이지: {len(batch.items)}건")
+    for item in batch.items:
+        print(item)
+```
+
+### 10. pandas DataFrame 변환
+
+조회 결과를 pandas DataFrame으로 변환하여 분석할 수 있습니다.
+
+```bash
+pip install kpubdata[pandas]
+```
+
+```python
+ds = client.dataset("bok.base_rate")
+result = ds.list(start_date="202401", end_date="202412")
+
+# pandas DataFrame으로 변환
+df = result.to_pandas()
+print(df.head())
+```
+
 ## 지원 중인 공공데이터
 
 현재 지원 현황의 상세 정보와 진행 예정 항목은 [SUPPORTED_DATA.md](./SUPPORTED_DATA.md)에서 확인할 수 있습니다.
@@ -279,6 +310,9 @@ for item in result.items[:5]:
 | 지방재정365 (`lofin`) | 기능별세출 (`expenditure_function`) | 지원 |
 | 지방재정365 (`lofin`) | 채무비율현황 (`debt_ratio`) | 지원 |
 | 지방재정365 (`lofin`) | 재정자립도현황 (`fiscal_independence`) | 지원 |
+| 지방재정365 (`lofin`) | 재원별 세입결산 (`revenue_by_source`) | 지원 |
+
+> 검증 수준 및 실API 최종 검증일 등 상세 정보는 [SUPPORTED_DATA.md](./SUPPORTED_DATA.md)를 참고하세요.
 
 ## 문서 가이드 (Document Guide)
 
@@ -341,3 +375,4 @@ KPubData의 설계 철학과 사용 방법을 안내하는 문서 목록입니
 
 ### v0.3
 - 표준 코어를 기반으로 한 경량 [MCP](https://modelcontextprotocol.io/)(Model Context Protocol — AI 모델이 외부 도구를 사용하는 표준 규약) 어댑터 지원
+

kpubdata-0.2.2/SUPPORTED_DATA.md

@@ -0,0 +1,56 @@
+# 지원 공공데이터 현황
+
+이 문서는 KPubData가 지원하는 공공데이터 목록과 진행 현황을 관리하는 기준 문서입니다.
+
+> **상태 정의**
+>
+> - 지원: 구현 완료 + fixture/unit/contract 테스트 통과
+> - 진행 중: 구현 중이지만 아직 테스트가 완료되지 않음
+> - 예정: 후보 단계 (이슈 등록 또는 아이디어)
+>
+> **검증 정의**
+>
+> - 테스트 검증: fixture 기반 unit 테스트 + contract 테스트 통과
+> - 실API 검증: 위 조건 + 실 API integration 테스트 통과 ([#80](https://github.com/yeongseon/kpubdata/issues/80))
+>
+> **실API 최종 검증일**
+>
+> - 실API 검증을 마지막으로 성공한 날짜 (`YYYY-MM-DD`). 테스트 검증만 완료된 데이터셋은 `-`로 표기합니다.
+> - 검증일이 90일을 초과한 데이터셋은 재검증을 권장합니다.
+
+## 현재 지원
+
+| 상태 | 검증 | 실API 최종 검증일 | Provider | Dataset ID | 데이터셋명 | 인증 | 공식 문서 | 비고 |
+|---|---|---|---|---|---|---|---|---|
+| 지원 | 테스트 검증 | - | 공공데이터포털 (`datago`) | `apt_trade` | 아파트매매 실거래가 | [공공데이터포털](https://www.data.go.kr) 서비스키 | [data.go.kr](https://www.data.go.kr) | 국토교통부 제공 |
+| 지원 | 테스트 검증 | - | 공공데이터포털 (`datago`) | `village_fcst` | 단기예보 조회서비스 | [공공데이터포털](https://www.data.go.kr) 서비스키 | [data.go.kr](https://www.data.go.kr) | 기상청 제공 |
+| 지원 | 테스트 검증 | - | 공공데이터포털 (`datago`) | `ultra_srt_ncst` | 초단기실황 조회서비스 | [공공데이터포털](https://www.data.go.kr) 서비스키 | [data.go.kr](https://www.data.go.kr) | 기상청 제공 |
+| 지원 | 테스트 검증 | - | 공공데이터포털 (`datago`) | `air_quality` | 대기오염정보 조회서비스 | [공공데이터포털](https://www.data.go.kr) 서비스키 | [data.go.kr](https://www.data.go.kr) | |
+| 지원 | 테스트 검증 | - | 공공데이터포털 (`datago`) | `bus_arrival` | 경기도 버스도착정보 조회서비스 | [공공데이터포털](https://www.data.go.kr) 서비스키 | [data.go.kr](https://www.data.go.kr) | |
+| 지원 | 테스트 검증 | - | 공공데이터포털 (`datago`) | `hospital_info` | 병원정보서비스 | [공공데이터포털](https://www.data.go.kr) 서비스키 | [data.go.kr](https://www.data.go.kr) | |
+| 지원 | 실API 검증 | 2025-04-15 | 한국은행 ECOS (`bok`) | `base_rate` | 한국은행 기준금리 | [ECOS](https://ecos.bok.or.kr/api/) 인증키 | [ecos.bok.or.kr](https://ecos.bok.or.kr/api/) | |
+| 지원 | 실API 검증 | 2025-04-15 | 통계청 KOSIS (`kosis`) | `population_migration` | 시도별 이동자수 | [KOSIS](https://kosis.kr/openapi/index/index.jsp) 인증키 | [kosis.kr](https://kosis.kr/openapi/index/index.jsp) | |
+| 지원 | 실API 검증 | 2025-04-16 | 지방재정365 (`lofin`) | `expenditure_budget` | 세출결산총괄 | [지방재정365](https://www.lofin365.go.kr) 인증키 | [lofin365.go.kr](https://www.lofin365.go.kr) | API 코드: AJGCF |
+| 지원 | 실API 검증 | 2025-04-16 | 지방재정365 (`lofin`) | `revenue_budget` | 세입결산총괄 | [지방재정365](https://www.lofin365.go.kr) 인증키 | [lofin365.go.kr](https://www.lofin365.go.kr) | API 코드: IIBBH |
+| 지원 | 실API 검증 | 2025-04-16 | 지방재정365 (`lofin`) | `expenditure_function` | 기능별세출 | [지방재정365](https://www.lofin365.go.kr) 인증키 | [lofin365.go.kr](https://www.lofin365.go.kr) | API 코드: GGNSE |
+| 지원 | 실API 검증 | 2025-04-16 | 지방재정365 (`lofin`) | `debt_ratio` | 채무비율현황 | [지방재정365](https://www.lofin365.go.kr) 인증키 | [lofin365.go.kr](https://www.lofin365.go.kr) | API 코드: HEDFC |
+| 지원 | 실API 검증 | 2025-04-16 | 지방재정365 (`lofin`) | `fiscal_independence` | 재정자립도현황 | [지방재정365](https://www.lofin365.go.kr) 인증키 | [lofin365.go.kr](https://www.lofin365.go.kr) | API 코드: JFIED |
+| 지원 | 실API 검증 | 2025-04-17 | 지방재정365 (`lofin`) | `revenue_by_source` | 재원별 회계별 세입결산 | [지방재정365](https://www.lofin365.go.kr) 인증키 | [lofin365.go.kr](https://www.lofin365.go.kr) | API 코드: FIACRV |
+
+## 진행 예정 / 진행 중
+
+| 상태 | Provider | Dataset ID | 데이터셋명 | 메모 |
+|---|---|---|---|---|
+| 예정 | 공공데이터포털 (`datago`) | `apt_rent` | 아파트 전월세 실거래가 | `apt_trade`와 인접한 확장 후보 |
+| 예정 | 기상청 | `weather_forecast` | 동네예보 | provider/adapter 구조 확정 후 착수 |
+
+## 갱신 규칙
+
+새로운 adapter를 추가할 때는 아래 절차에 따라 이 문서를 함께 업데이트합니다.
+
+1. **기획 단계**: `진행 예정 / 진행 중` 표에 `예정`으로 추가
+2. **구현 시작**: fixture 수집 또는 adapter skeleton이 생기면 `진행 중`으로 변경
+3. **지원 전환**: fixture + unit test + contract test + 문서가 모두 포함된 PR이 merge되면 `현재 지원` 표로 이동하고 `지원`으로 표시
+4. **README 동기화**: `지원` 항목만 [README.md](./README.md)의 요약 표에 추가
+5. **명칭 규칙**: provider slug와 dataset id는 코드의 실제 이름과 정확히 일치시킬 것
+6. **PR 포함**: adapter 추가/상태 변경 PR에는 이 문서의 업데이트를 반드시 포함

{kpubdata-0.1.1 → kpubdata-0.2.2}/VALIDATION.md

@@ -39,7 +39,6 @@ That means these should be standardized:
 
 - `client.dataset(id)`
 - `dataset.list(...)`
-- `dataset.get(...)`
 - `dataset.schema()`
 - `dataset.call_raw(...)`
 

{kpubdata-0.1.1 → kpubdata-0.2.2}/docs/architecture-diagrams.md

@@ -218,7 +218,6 @@ classDiagram
         +search_datasets()
         +get_dataset()
         +query_records()
-        +get_record()
         +get_schema()
         +call_raw()
     }
@@ -227,7 +226,6 @@ classDiagram
         +search_datasets()
         +get_dataset()
         +query_records()
-        +get_record()
         +get_schema()
         +call_raw()
     }
@@ -244,7 +242,6 @@ classDiagram
     }
     class Dataset {
         +list()
-        +get()
         +schema()
         +call_raw()
     }
@@ -418,9 +415,8 @@ graph TB
         M2["search_datasets(text) -> list[DatasetRef]"]
         M3["get_dataset(key) -> DatasetRef"]
         M4["query_records(dataset, query) -> RecordBatch"]
-        M5["get_record(dataset, key) -> dict"]
-        M6["get_schema(dataset) -> SchemaDescriptor"]
-        M7["call_raw(dataset, operation, params) -> object"]
+        M5["get_schema(dataset) -> SchemaDescriptor"]
+        M6["call_raw(dataset, operation, params) -> object"]
     end
 
     Protocol --- Implementation

{kpubdata-0.1.1 → kpubdata-0.2.2}/docs/datago-api-reference.md

@@ -207,9 +207,9 @@ codes (most responses return HTTP 200 even on error).
 6. **`call_raw`** — pass through arbitrary params and return the
    **minimally processed** provider response dict. Do not flatten or
    canonicalize — this preserves the raw escape hatch.
-7. **Unsupported capabilities** — `get_record` and `get_schema` are
-   **not supported** by default unless dataset metadata explicitly
-   proves otherwise. Do not mark these as supported.
+7. **Unsupported capabilities** — `get_schema` is **not supported** by
+   default unless dataset metadata explicitly proves otherwise. Do not
+   mark it as supported.
 8. **Item normalization** — always coerce `items.item` to `list[dict]`
    as described in §4.3.
 

{kpubdata-0.1.1 → kpubdata-0.2.2}/docs/quickstart.md

@@ -146,6 +146,29 @@ kosis.population_migration — 시도별 이동자수 (Population Migration)
 - 공공데이터포털(datago): [datago API 키 발급 가이드](./providers/datago.md)
 - 통계청 KOSIS: [KOSIS API 키 발급 가이드](./providers/kosis.md)
 
+## Step 8: 전체 페이지 자동 조회
+
+데이터가 많을 때 `list_all()`을 사용하면 모든 페이지를 자동으로 순회합니다.
+
+```python
+ds = client.dataset("bok.base_rate")
+
+for batch in ds.list_all(start_date="202401", end_date="202412"):
+    print(f"{len(batch.items)}건 조회")
+```
+
+## Step 9: pandas로 데이터 분석하기
+
+```bash
+pip install kpubdata[pandas]
+```
+
+```python
+result = ds.list(start_date="202401", end_date="202412")
+df = result.to_pandas()
+print(df)
+```
+
 ## 다음 단계
 - 각 Provider별 상세 사용법: [docs/providers/](./providers/) 폴더
 - 프로젝트에 기여하기: [CONTRIBUTING.md](../CONTRIBUTING.md)

{kpubdata-0.1.1 → kpubdata-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "kpubdata"
-version = "0.1.1"
+version = "0.2.2"
 description = "Dialect-inspired Python access framework for Korean public data"
 readme = "README.md"
 requires-python = ">=3.10"

{kpubdata-0.1.1 → kpubdata-0.2.2}/src/kpubdata/core/dataset.py

@@ -2,6 +2,11 @@
 
 from __future__ import annotations
 
+from collections.abc import Generator
+from typing import cast
+
+from typing_extensions import override
+
 from kpubdata.core.capability import Operation
 from kpubdata.core.models import DatasetRef, Query, RecordBatch, SchemaDescriptor
 from kpubdata.core.protocol import ProviderAdapter
@@ -18,8 +23,8 @@ class Dataset:
     def __init__(self, ref: DatasetRef, adapter: ProviderAdapter) -> None:
         """Initialize a dataset bound to its canonical ref and adapter."""
 
-        self._ref = ref
-        self._adapter = adapter
+        self._ref: DatasetRef = ref
+        self._adapter: ProviderAdapter = adapter
 
     @property
     def ref(self) -> DatasetRef:
@@ -91,10 +96,18 @@ class Dataset:
                 start_date = value
             elif key == "end_date" and isinstance(value, str):
                 end_date = value
-            elif key == "fields" and isinstance(value, list):
-                fields_list = value
-            elif key == "sort" and isinstance(value, list):
-                sort_list = value
+            elif (
+                key == "fields"
+                and isinstance(value, list)
+                and all(isinstance(item, str) for item in cast(list[object], value))
+            ):
+                fields_list = cast(list[str], value)
+            elif (
+                key == "sort"
+                and isinstance(value, list)
+                and all(isinstance(item, str) for item in cast(list[object], value))
+            ):
+                sort_list = cast(list[str], value)
             else:
                 filters[key] = value
 
@@ -110,24 +123,27 @@ class Dataset:
         )
         return self._adapter.query_records(self._ref, query)
 
-    def get(self, **key: object) -> dict[str, object] | None:
-        """Return a single record matching the provided key fields.
-
-        Return ``None`` when no matching record is found.
-
-        Raises:
-            UnsupportedCapabilityError: If this dataset does not support ``get``.
-        """
-
-        if Operation.GET not in self._ref.operations:
+    def list_all(self, **kwargs: object) -> Generator[RecordBatch, None, None]:
+        if Operation.LIST not in self._ref.operations:
             raise UnsupportedCapabilityError(
-                f"Dataset does not support get: {self._ref.id}",
+                f"Dataset does not support list: {self._ref.id}",
                 provider=self._ref.provider,
                 dataset_id=self._ref.id,
-                operation=Operation.GET.value,
+                operation=Operation.LIST.value,
             )
-        key_payload: dict[str, object] = {k: v for k, v in key.items()}
-        return self._adapter.get_record(self._ref, key_payload)
+
+        page_kwargs = dict(kwargs)
+        batch = self.list(**page_kwargs)
+        yield batch
+        while batch.next_page is not None or batch.next_cursor is not None:
+            if batch.next_cursor is not None:
+                page_kwargs["cursor"] = batch.next_cursor
+                _ = page_kwargs.pop("page", None)
+            else:
+                page_kwargs["page"] = batch.next_page
+                _ = page_kwargs.pop("cursor", None)
+            batch = self.list(**page_kwargs)
+            yield batch
 
     def schema(self) -> SchemaDescriptor | None:
         """Return canonical schema metadata when the provider exposes it."""
@@ -144,6 +160,7 @@ class Dataset:
         payload: dict[str, object] = {k: v for k, v in params.items()}
         return self._adapter.call_raw(self._ref, operation, payload)
 
+    @override
     def __repr__(self) -> str:
         """Return concise debug representation."""
 

{kpubdata-0.1.1 → kpubdata-0.2.2}/src/kpubdata/core/models.py

@@ -117,6 +117,23 @@ class RecordBatch:
     def __bool__(self) -> bool:
         return bool(self.items)
 
+    def to_pandas(self) -> object:
+        """Convert items to a pandas ``DataFrame``.
+
+        Requires the ``pandas`` optional dependency.
+        Install with: ``pip install kpubdata[pandas]``
+
+        Returns:
+            A ``pandas.DataFrame`` built from :attr:`items`.
+        """
+        try:
+            import pandas as pd  # type: ignore[import-untyped]
+        except ImportError:
+            raise ImportError(
+                "pandas is required for to_pandas(). Install with: pip install kpubdata[pandas]"
+            ) from None
+        return pd.DataFrame(self.items)
+
 
 @_dataclass(slots=True)
 class FieldDescriptor: