kpubdata 0.2.1__tar.gz → 0.2.2__tar.gz

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

@@ -210,46 +210,26 @@ sequenceDiagram
 
 **핵심 메서드**: 모든 어댑터는 `_require_api_key()` → `self._config.require_provider_key("slug")` 패턴을 사용합니다.
 
-### 6.4 기관별 키 주입 방식
+## 7. 페이지네이션 전략 (Pagination Strategy)
 
-기관마다 키를 HTTP 요청에 넣는 위치와 파라미터 이름이 다릅니다.
+KPubData는 대량의 데이터를 효율적으로 가져오기 위해 두 가지 페이지네이션 전략을 사용합니다.
 
-| Provider | 파라미터 이름 | 주입 위치 | 예시 | 특이사항 |
-|---|---|---|---|---|
-| `datago` | `serviceKey` | Query parameter | `?serviceKey=KEY` | dataset별 `service_key_param` 메타데이터로 파라미터명 오버라이드 가능 |
-| `bok` | _(URL 경로)_ | URL path segment | `/{KEY}/json/{operation}/...` | 쿼리 파라미터가 아닌 **URL 경로**에 직접 삽입 |
-| `kosis` | `apiKey` | Query parameter | `?apiKey=KEY` | 표준적인 쿼리 파라미터 방식 |
-| `lofin` | `Key` | Query parameter | `?Key=KEY` | 대문자 `K` 필수. `Type=json`도 대문자 `T` 필수 |
+### 7.1 전략 종류
+- **오프셋 기반 (Offset-based)**: 페이지 번호를 이용해 데이터를 요청합니다. `next_page` 값이 반환됩니다.
+- **커서 기반 (Cursor-based)**: 특정 지점을 가리키는 포인터(커서)를 이용해 다음 데이터를 요청합니다. `next_cursor` 값이 반환됩니다.
 
-```text
-datago:  GET https://apis.data.go.kr/.../getVilageFcst?serviceKey=KEY&...
-bok:     GET https://ecos.bok.or.kr/api/KEY/json/StatisticSearch/...
-kosis:   GET https://kosis.kr/openapi/Idx/indikatorList.do?apiKey=KEY&...
-lofin:   GET https://www.lofin365.go.kr/lf/hub/AJGCF?Key=KEY&Type=json&...
-```
-
-### 6.5 새 어댑터 추가 시 인증 구현 가이드
-
-새로운 데이터 기관을 추가할 때, 인증 관련 구현은 다음 3단계를 따릅니다.
-
-**1단계**: `_require_api_key()` 메서드를 정의합니다.
-```python
-def _require_api_key(self) -> str:
-    return self._config.require_provider_key("your_provider_slug")
-```
+### 7.2 동작 원리 및 휴리스틱 (Heuristic)
+어댑터는 가용한 정보에 따라 다음과 같이 다음 페이지 존재 여부를 결정합니다.
+1. **정밀 계산**: `total_count` 정보를 알 수 있는 경우(예: bok, lofin), 현재까지 가져온 개수와 전체 개수를 비교해 `next_page`를 정확히 계산합니다.
+2. **Best-effort 휴리스틱**: 전체 개수 정보가 없는 경우(예: datago), `len(items) == page_size` 공식을 사용합니다.
+   - 현재 페이지의 아이템 개수가 요청한 페이지 크기와 같다면, 다음 페이지가 더 있을 것으로 가정합니다.
+   - 이 방식은 마지막 데이터가 딱 페이지 크기에 맞춰 끝날 경우, 실제로 데이터가 없는 다음 페이지를 한 번 더 호출하는 **추가 fetch(Extra empty fetch)**가 발생할 수 있습니다. 이는 문서화된 트레이드오프(trade-off)입니다.
 
-**2단계**: 요청 생성 시 키를 해당 기관의 방식에 맞게 주입합니다.
-```python
-# Query parameter 방식 (가장 일반적)
-params = {"apiKey": self._require_api_key(), ...}
-
-# URL path 방식 (bok처럼 경로에 넣는 경우)
-url = f"{base_url}/{self._require_api_key()}/json/{operation}"
-```
+### 7.3 list_all()의 처리
+사용자가 `list_all()` 메서드를 호출하면, KPubData는 어댑터가 반환하는 전략(`next_cursor` 우선, 없으면 `next_page`)을 자동으로 판단하여 모든 데이터를 순회합니다.
 
-**3단계**: `Client`의 `_BUILTIN_PROVIDERS` 튜플에 등록하면, `from_env()`가 자동으로 `KPUBDATA_{SLUG}_API_KEY` 환경변수를 스캔합니다.
+## 8. 자주 묻는 질문 (FAQ)
 
-## 7. 자주 묻는 질문 (FAQ)
 
 **Q: 새 데이터셋을 추가하려면 어디를 수정하나요?**
 A: 해당 기관의 어댑터(`providers/<provider>/adapter.py`)와 데이터 목록 파일(`catalogue.json`)을 수정하면 됩니다.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kpubdata
-Version: 0.2.1
+Version: 0.2.2
 Summary: Dialect-inspired Python access framework for Korean public data
 Author: Yeongseon Choe
 License: MIT

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

@@ -167,7 +167,15 @@ classDiagram
     }
 ```
 
-## 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`

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

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

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

@@ -135,8 +135,13 @@ class Dataset:
         page_kwargs = dict(kwargs)
         batch = self.list(**page_kwargs)
         yield batch
-        while batch.next_page is not None:
-            page_kwargs["page"] = batch.next_page
+        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
 

{kpubdata-0.2.1 → kpubdata-0.2.2}/tests/unit/core/test_dataset.py

@@ -76,6 +76,12 @@ class TestDataset:
         with pytest.raises(UnsupportedCapabilityError, match="list"):
             _ = ds.list()
 
+    def test_list_all_unsupported(self) -> None:
+        adapter = MockAdapter()
+        ds = Dataset(ref=_ref(frozenset({Operation.RAW})), adapter=adapter)
+        with pytest.raises(UnsupportedCapabilityError, match="list"):
+            _ = list(ds.list_all())
+
     def test_call_raw(self) -> None:
         adapter = MockAdapter()
         ds = Dataset(ref=_ref(), adapter=adapter)
@@ -170,3 +176,34 @@ class TestDataset:
 
         assert len(batches) == 1
         assert batches[0].items == [{"page": 1}]
+
+    def test_list_all_cursor_pagination(self) -> None:
+        adapter = MockAdapter()
+        dataset_ref = _ref()
+        adapter.batches = [
+            RecordBatch(items=[{"cursor": "a"}], dataset=dataset_ref, next_cursor="abc"),
+            RecordBatch(items=[{"cursor": "b"}], dataset=dataset_ref, next_cursor="def"),
+            RecordBatch(items=[{"cursor": "c"}], dataset=dataset_ref, next_cursor=None),
+        ]
+        ds = Dataset(ref=dataset_ref, adapter=adapter)
+
+        batches = list(ds.list_all(region="서울"))
+
+        assert [batch.items[0]["cursor"] for batch in batches] == ["a", "b", "c"]
+        assert adapter.last_query is not None
+        assert adapter.last_query.cursor == "def"
+        assert adapter.last_query.page is None
+        assert adapter.last_query.filters == {"region": "서울"}
+
+    def test_list_all_cursor_single_page(self) -> None:
+        adapter = MockAdapter()
+        dataset_ref = _ref()
+        adapter.batches = [
+            RecordBatch(items=[{"cursor": "a"}], dataset=dataset_ref, next_cursor=None)
+        ]
+        ds = Dataset(ref=dataset_ref, adapter=adapter)
+
+        batches = list(ds.list_all())
+
+        assert len(batches) == 1
+        assert batches[0].items == [{"cursor": "a"}]

{kpubdata-0.2.1 → kpubdata-0.2.2}/tests/unit/core/test_to_pandas.py

@@ -34,7 +34,7 @@ class _FakeDataFrame:
 
 
 class _FakePandasModule(ModuleType):
-    DataFrame: type[_FakeDataFrame]
+    DataFrame: type[_FakeDataFrame] = _FakeDataFrame
 
 
 def _fake_pandas_module() -> _FakePandasModule:
@@ -80,3 +80,31 @@ def test_to_pandas_import_error() -> None:
         pytest.raises(ImportError, match=r"pandas is required for to_pandas\(\)"),
     ):
         _ = batch.to_pandas()
+
+
+def test_to_pandas_real_pandas_if_available() -> None:
+    from typing import Protocol, cast
+
+    class _DataFrameLike(Protocol):
+        shape: tuple[int, int]
+        columns: list[str]
+
+    class _PandasModule(Protocol):
+        DataFrame: type[_DataFrameLike]
+
+    pd = cast(_PandasModule, pytest.importorskip("pandas"))
+
+    batch = RecordBatch(
+        items=[
+            {"name": "Alice", "age": 30},
+            {"name": "Bob", "age": 31},
+            {"name": "Carol", "age": 32},
+        ],
+        dataset=_dataset_ref(),
+    )
+
+    df = batch.to_pandas()
+
+    assert isinstance(df, pd.DataFrame)
+    assert df.shape == (3, 2)
+    assert list(df.columns) == ["name", "age"]

{kpubdata-0.2.1 → kpubdata-0.2.2}/uv.lock

@@ -462,7 +462,7 @@ wheels = [
 
 [[package]]
 name = "kpubdata"
-version = "0.2.1"
+version = "0.2.2"
 source = { editable = "." }
 dependencies = [
     { name = "httpx" },