kpubdata 0.1.0__py3-none-any.whl

kpubdata/providers/lofin/adapter.py

@@ -0,0 +1,329 @@
+from __future__ import annotations
+
+import logging
+import ssl
+from collections.abc import Mapping, Sequence
+from typing import NoReturn, cast
+
+from kpubdata.config import KPubDataConfig
+from kpubdata.core.models import DatasetRef, Query, RecordBatch, SchemaDescriptor
+from kpubdata.exceptions import (
+    AuthError,
+    DatasetNotFoundError,
+    ParseError,
+    ProviderResponseError,
+)
+from kpubdata.providers._common import build_schema_from_metadata, coerce_int, load_catalogue
+from kpubdata.transport.decode import decode_json
+from kpubdata.transport.http import HttpTransport, TransportConfig
+
+logger = logging.getLogger("kpubdata.provider.lofin")
+
+
+class LofinAdapter:
+    def __init__(
+        self,
+        *,
+        config: KPubDataConfig | None = None,
+        transport: HttpTransport | None = None,
+        catalogue: Sequence[DatasetRef] | None = None,
+    ) -> None:
+        self._config: KPubDataConfig = config or KPubDataConfig()
+        if transport is not None and not isinstance(transport, HttpTransport):
+            self._transport: HttpTransport = transport
+        else:
+            ssl_ctx = ssl.create_default_context()
+            ssl_ctx.check_hostname = False
+            ssl_ctx.verify_mode = ssl.CERT_NONE
+            ssl_ctx.set_ciphers("DEFAULT:@SECLEVEL=1")
+            transport_config = TransportConfig(
+                timeout=self._config.timeout,
+                max_retries=self._config.max_retries,
+                ssl_context=ssl_ctx,
+            )
+            self._transport = HttpTransport(transport_config)
+
+        datasets = tuple(catalogue) if catalogue is not None else self._load_default_catalogue()
+        self._datasets: tuple[DatasetRef, ...] = datasets
+        self._datasets_by_key: dict[str, DatasetRef] = {
+            dataset.dataset_key: dataset for dataset in self._datasets
+        }
+
+    @property
+    def name(self) -> str:
+        return "lofin"
+
+    def list_datasets(self) -> list[DatasetRef]:
+        return list(self._datasets)
+
+    def search_datasets(self, text: str) -> list[DatasetRef]:
+        needle = text.casefold()
+        return [
+            dataset
+            for dataset in self._datasets
+            if needle in dataset.id.casefold() or needle in dataset.name.casefold()
+        ]
+
+    def get_dataset(self, dataset_key: str) -> DatasetRef:
+        dataset = self._datasets_by_key.get(dataset_key)
+        if dataset is not None:
+            return dataset
+
+        raise DatasetNotFoundError(
+            f"Dataset not found: lofin.{dataset_key}",
+            provider="lofin",
+            dataset_id=f"lofin.{dataset_key}",
+        )
+
+    def query_records(self, dataset: DatasetRef, query: Query) -> RecordBatch:
+        page = query.page or 1
+        page_size = query.page_size or 10
+
+        all_items: list[dict[str, object]] = []
+        raw_pages: list[dict[str, object]] = []
+        total_count: int | None = None
+
+        while True:
+            url = self._build_request_url(
+                dataset, page=page, page_size=page_size, filters=query.filters
+            )
+            payload = self._request_and_decode(url, dataset.id)
+            raw_pages.append(payload)
+
+            body, items = self._validate_envelope(payload, dataset)
+            all_items.extend(items)
+
+            total_count = coerce_int(body.get("list_total_count"), 0)
+            if not items:
+                break
+            if len(items) < page_size:
+                break
+            if len(all_items) >= total_count:
+                break
+
+            page += 1
+
+        return RecordBatch(
+            items=all_items,
+            dataset=dataset,
+            total_count=total_count,
+            next_page=None,
+            raw=raw_pages,
+        )
+
+    def get_record(self, _dataset: DatasetRef, _key: dict[str, object]) -> dict[str, object] | None:
+        raise NotImplementedError("TODO: implement lofin get_record")
+
+    def get_schema(self, dataset: DatasetRef) -> SchemaDescriptor | None:
+        return build_schema_from_metadata(dataset)
+
+    def call_raw(self, dataset: DatasetRef, operation: str, params: dict[str, object]) -> object:
+        _ = operation
+        page = self._int_param(params, "pIndex", self._int_param(params, "page", 1))
+        page_size = self._int_param(params, "pSize", self._int_param(params, "page_size", 10))
+        extra_keys = {"pIndex", "page", "pSize", "page_size"}
+        filters = {k: v for k, v in params.items() if k not in extra_keys}
+
+        url = self._build_request_url(dataset, page=page, page_size=page_size, filters=filters)
+        payload = self._request_and_decode(url, dataset.id)
+        _ = self._validate_envelope(payload, dataset)
+        return payload
+
+    def _require_api_key(self) -> str:
+        return self._config.require_provider_key("lofin")
+
+    def _build_request_url(
+        self,
+        dataset: DatasetRef,
+        *,
+        page: int,
+        page_size: int,
+        filters: dict[str, object] | None = None,
+    ) -> str:
+        base_url_raw = dataset.raw_metadata.get("base_url")
+        if not isinstance(base_url_raw, str) or not base_url_raw:
+            raise ProviderResponseError(
+                "Dataset metadata missing base_url",
+                provider="lofin",
+                dataset_id=dataset.id,
+            )
+
+        dataset_code = self._require_dataset_metadata(dataset, "api_code")
+        api_key = self._require_api_key()
+        safe_page = page if page > 0 else 1
+        safe_page_size = page_size if page_size > 0 else 10
+        url = (
+            f"{base_url_raw}/{dataset_code}"
+            f"?Key={api_key}&Type=json&pIndex={safe_page}&pSize={safe_page_size}"
+        )
+        if filters:
+            for key, value in filters.items():
+                url += f"&{key}={value}"
+        return url
+
+    def _request_and_decode(self, url: str, dataset_id: str = "") -> dict[str, object]:
+        response = self._transport.request("GET", url)
+
+        try:
+            decoded_obj: object = decode_json(response.content)
+        except ValueError as exc:
+            raise ParseError("Failed to parse LOFIN response", provider="lofin") from exc
+
+        if isinstance(decoded_obj, dict):
+            payload = cast(dict[str, object], decoded_obj)
+            self._raise_for_top_level_result(payload, dataset_id)
+            return payload
+
+        raise ParseError("Decoded payload is not an object", provider="lofin")
+
+    def _validate_envelope(
+        self, payload: dict[str, object], dataset: DatasetRef
+    ) -> tuple[dict[str, object], list[dict[str, object]]]:
+        dataset_code = self._require_dataset_metadata(dataset, "api_code")
+        body_obj = payload.get(dataset_code)
+        if not isinstance(body_obj, list) or not body_obj:
+            raise ProviderResponseError(
+                f"Malformed response envelope: missing {dataset_code}",
+                provider="lofin",
+                dataset_id=dataset.id,
+            )
+
+        body_list = cast(list[object], body_obj)
+        first_entry = body_list[0]
+        if not isinstance(first_entry, dict):
+            raise ProviderResponseError(
+                f"Malformed response envelope: invalid {dataset_code} body",
+                provider="lofin",
+                dataset_id=dataset.id,
+            )
+
+        head_entry = cast(dict[str, object], first_entry)
+        head_obj = head_entry.get("head")
+        if not isinstance(head_obj, list) or not head_obj:
+            legacy_body = cast(dict[str, object], first_entry)
+            self._raise_for_result(legacy_body, dataset.id)
+            items = self._normalize_rows(legacy_body.get("row"))
+            return legacy_body, items
+
+        head_items = cast(list[object], head_obj)
+        metadata: dict[str, object] = {}
+        result_payload: Mapping[str, object] | None = None
+        for head_item in head_items:
+            if not isinstance(head_item, dict):
+                continue
+            head_dict = cast(dict[str, object], head_item)
+            if "list_total_count" in head_dict:
+                metadata["list_total_count"] = head_dict.get("list_total_count")
+            if "RESULT" in head_dict:
+                result_obj = head_dict.get("RESULT")
+                if isinstance(result_obj, Mapping):
+                    result_payload = cast(Mapping[str, object], result_obj)
+
+        if result_payload is None:
+            raise ProviderResponseError(
+                f"Malformed response envelope: missing {dataset_code} RESULT",
+                provider="lofin",
+                dataset_id=dataset.id,
+            )
+
+        self._raise_for_result({"RESULT": dict(result_payload)}, dataset.id)
+
+        rows_entry = body_list[1] if len(body_list) > 1 else None
+        rows_wrapper: object = None
+        if isinstance(rows_entry, dict):
+            rows_dict = cast(dict[str, object], rows_entry)
+            rows_wrapper = rows_dict.get("row")
+
+        items = self._normalize_rows(rows_wrapper)
+        return metadata, items
+
+    def _raise_for_top_level_result(self, payload: Mapping[str, object], dataset_id: str) -> None:
+        result_obj = payload.get("RESULT")
+        if not isinstance(result_obj, list):
+            return
+
+        result_list = cast(list[object], result_obj)
+        if not result_list:
+            return
+
+        first_result = result_list[0]
+        if not isinstance(first_result, Mapping):
+            return
+
+        self._raise_for_result(
+            {"RESULT": dict(cast(Mapping[str, object], first_result))}, dataset_id
+        )
+
+    def _raise_for_result(self, payload: Mapping[str, object], dataset_id: str) -> None:
+        result_obj = payload.get("RESULT")
+        if not isinstance(result_obj, dict):
+            return
+
+        result_dict = cast(dict[str, object], result_obj)
+        code_raw = result_dict.get("CODE")
+        message_raw = result_dict.get("MESSAGE")
+        code = code_raw if isinstance(code_raw, str) else "ERROR-000"
+        message = message_raw if isinstance(message_raw, str) else "Provider returned error"
+        logger.debug(
+            "LOFIN result",
+            extra={"result_code": code, "result_msg": message, "dataset_id": dataset_id},
+        )
+
+        if code == "INFO-000":
+            return
+        if code == "INFO-200":
+            return
+
+        self._raise_for_result_code(code, message, dataset_id)
+
+    def _raise_for_result_code(self, code: str, msg: str, dataset_id: str) -> NoReturn:
+        if code in {"ERROR-290", "ERROR-300"}:
+            raise AuthError(
+                msg, provider="lofin", provider_code=code, dataset_id=dataset_id or None
+            )
+        if code.startswith("ERROR-"):
+            raise ProviderResponseError(
+                msg,
+                provider="lofin",
+                provider_code=code,
+                dataset_id=dataset_id or None,
+            )
+        raise ProviderResponseError(
+            msg,
+            provider="lofin",
+            provider_code=code,
+            dataset_id=dataset_id or None,
+        )
+
+    def _require_dataset_metadata(self, dataset: DatasetRef, key: str) -> str:
+        value = dataset.raw_metadata.get(key)
+        if isinstance(value, str) and value:
+            return value
+        raise ProviderResponseError(
+            f"Dataset metadata missing {key}",
+            provider="lofin",
+            dataset_id=dataset.id,
+        )
+
+    def _normalize_rows(self, rows_wrapper: object) -> list[dict[str, object]]:
+        if rows_wrapper is None:
+            return []
+        if isinstance(rows_wrapper, list):
+            rows = cast(list[object], rows_wrapper)
+            return [cast(dict[str, object], item) for item in rows if isinstance(item, dict)]
+        if isinstance(rows_wrapper, dict):
+            return [cast(dict[str, object], rows_wrapper)]
+        return []
+
+    @classmethod
+    def _int_param(cls, params: Mapping[str, object], key: str, default: int) -> int:
+        value = params.get(key)
+        coerced = coerce_int(value, default)
+        return coerced if coerced > 0 else default
+
+    @staticmethod
+    def _load_default_catalogue() -> tuple[DatasetRef, ...]:
+        return load_catalogue("kpubdata.providers.lofin", "lofin")
+
+
+__all__ = ["LofinAdapter"]

kpubdata/providers/lofin/catalogue.json

@@ -0,0 +1,127 @@
+[
+  {
+    "dataset_key": "expenditure_budget",
+    "name": "지방재정 세출결산총괄 (LOFIN Expenditure Budget Summary)",
+    "api_code": "AJGCF",
+    "base_url": "https://www.lofin365.go.kr/lf/hub",
+    "representation": "api_json",
+    "default_operation": "list",
+    "operations": ["list", "raw"],
+    "query_support": {
+      "pagination": "offset",
+      "max_page_size": 1000
+    },
+    "fields": [
+      {"name": "fyr", "title": "회계연도", "type": "string"},
+      {"name": "wa_laf_cd", "title": "광역자치단체코드", "type": "string"},
+      {"name": "wa_laf_hg_nm", "title": "광역자치단체명", "type": "string"},
+      {"name": "laf_cd", "title": "자치단체코드", "type": "string"},
+      {"name": "laf_hg_nm", "title": "자치단체명", "type": "string"},
+      {"name": "tot_pfa_amt", "title": "세출결산총액", "type": "string"},
+      {"name": "pfa_amt1", "title": "세출결산금액1", "type": "string"},
+      {"name": "pfa_amt2", "title": "세출결산금액2", "type": "string"},
+      {"name": "pfa_amt3", "title": "세출결산금액3", "type": "string"},
+      {"name": "pfa_amt4", "title": "세출결산금액4", "type": "string"}
+    ]
+  },
+  {
+    "dataset_key": "expenditure_function",
+    "name": "지방재정 기능별세출 (LOFIN Expenditure by Function)",
+    "api_code": "GGNSE",
+    "base_url": "https://www.lofin365.go.kr/lf/hub",
+    "representation": "api_json",
+    "default_operation": "list",
+    "operations": ["list", "raw"],
+    "query_support": {
+      "pagination": "offset",
+      "max_page_size": 1000
+    },
+    "fields": [
+      {"name": "fyr", "title": "회계연도", "type": "string"},
+      {"name": "wa_laf_cd", "title": "광역자치단체코드", "type": "string"},
+      {"name": "wa_laf_hg_nm", "title": "광역자치단체명", "type": "string"},
+      {"name": "laf_cd", "title": "자치단체코드", "type": "string"},
+      {"name": "laf_hg_nm", "title": "자치단체명", "type": "string"},
+      {"name": "fld_cd", "title": "분야코드", "type": "string"},
+      {"name": "fld_nm", "title": "분야명", "type": "string"},
+      {"name": "pol_bizct", "title": "정책사업", "type": "string"},
+      {"name": "fin_acv_amt", "title": "최종실적액", "type": "string"},
+      {"name": "padm_oper_exps", "title": "행정운영경비", "type": "string"},
+      {"name": "rgstr_dt", "title": "등록일시", "type": "string"},
+      {"name": "rgstr_usr_id", "title": "등록사용자ID", "type": "string"}
+    ]
+  },
+  {
+    "dataset_key": "revenue_budget",
+    "name": "지방재정 세입결산총괄 (LOFIN Revenue Budget Summary)",
+    "api_code": "IIBBH",
+    "base_url": "https://www.lofin365.go.kr/lf/hub",
+    "representation": "api_json",
+    "default_operation": "list",
+    "operations": ["list", "raw"],
+    "query_support": {
+      "pagination": "offset",
+      "max_page_size": 1000
+    },
+    "fields": [
+      {"name": "fyr", "title": "회계연도", "type": "string"},
+      {"name": "wa_laf_cd", "title": "광역자치단체코드", "type": "string"},
+      {"name": "wa_laf_hg_nm", "title": "광역자치단체명", "type": "string"},
+      {"name": "laf_cd", "title": "자치단체코드", "type": "string"},
+      {"name": "laf_hg_nm", "title": "자치단체명", "type": "string"},
+      {"name": "total", "title": "세입결산총액", "type": "string"},
+      {"name": "pfa_amt1", "title": "세입결산금액1", "type": "string"},
+      {"name": "pfa_amt2", "title": "세입결산금액2", "type": "string"},
+      {"name": "pfa_amt3", "title": "세입결산금액3", "type": "string"},
+      {"name": "pfa_amt4", "title": "세입결산금액4", "type": "string"}
+    ]
+  },
+  {
+    "dataset_key": "debt_ratio",
+    "name": "지방재정 채무비율현황 (LOFIN Debt Ratio Status)",
+    "api_code": "HEDFC",
+    "base_url": "https://www.lofin365.go.kr/lf/hub",
+    "representation": "api_json",
+    "default_operation": "list",
+    "operations": ["list", "raw"],
+    "query_support": {
+      "pagination": "offset",
+      "max_page_size": 1000
+    },
+    "fields": [
+      {"name": "fyr", "title": "회계연도", "type": "string"},
+      {"name": "wa_laf_cd", "title": "광역자치단체코드", "type": "string"},
+      {"name": "wa_laf_hg_nm", "title": "광역자치단체명", "type": "string"},
+      {"name": "laf_cd", "title": "자치단체코드", "type": "string"},
+      {"name": "laf_hg_nm", "title": "자치단체명", "type": "string"},
+      {"name": "pfa_amt1", "title": "채무액", "type": "string"},
+      {"name": "pfa_amt2", "title": "예산규모", "type": "string"},
+      {"name": "rate", "title": "채무비율", "type": "string"}
+    ]
+  },
+  {
+    "dataset_key": "fiscal_independence",
+    "name": "지방재정 재정자립도현황 (LOFIN Fiscal Independence)",
+    "api_code": "JFIED",
+    "base_url": "https://www.lofin365.go.kr/lf/hub",
+    "representation": "api_json",
+    "default_operation": "list",
+    "operations": ["list", "raw"],
+    "query_support": {
+      "pagination": "offset",
+      "max_page_size": 1000
+    },
+    "fields": [
+      {"name": "fyr", "title": "회계연도", "type": "string"},
+      {"name": "wa_laf_cd", "title": "광역자치단체코드", "type": "string"},
+      {"name": "wa_laf_hg_nm", "title": "광역자치단체명", "type": "string"},
+      {"name": "laf_cd", "title": "자치단체코드", "type": "string"},
+      {"name": "laf_hg_nm", "title": "자치단체명", "type": "string"},
+      {"name": "pfa_amt1", "title": "자주재원", "type": "string"},
+      {"name": "pfa_amt2", "title": "일반회계규모", "type": "string"},
+      {"name": "rate1", "title": "재정자립도", "type": "string"},
+      {"name": "pfa_amt3", "title": "자체수입", "type": "string"},
+      {"name": "rate2", "title": "자체수입비율", "type": "string"}
+    ]
+  }
+]

kpubdata/registry.py

@@ -0,0 +1,135 @@
+"""Provider adapter registry with registration-time validation.
+
+Validates that registered adapters conform to the ProviderAdapter protocol
+at registration time, not at call time.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from threading import RLock
+from typing import Any
+
+from kpubdata.exceptions import ProviderNotRegisteredError
+
+_REQUIRED_METHODS = (
+    "list_datasets",
+    "search_datasets",
+    "get_dataset",
+    "query_records",
+    "get_record",
+    "get_schema",
+    "call_raw",
+)
+
+
+class ProviderRegistry:
+    """Thread-safe registry for provider adapters."""
+
+    def __init__(self) -> None:
+        """Initialize empty eager/lazy adapter registries."""
+        self._adapters: dict[str, Any] = {}
+        self._lazy: dict[str, Any] = {}
+        self._lock = RLock()
+
+    def __repr__(self) -> str:
+        """Return concise debug representation."""
+        with self._lock:
+            eager_names = sorted(self._adapters.keys())
+            lazy_names = sorted(self._lazy.keys())
+        return f"ProviderRegistry(eager={eager_names}, lazy={lazy_names})"
+
+    def register(self, adapter: Any) -> None:
+        """Register an adapter instance. Validates protocol conformance."""
+        self._validate_adapter(adapter)
+        provider_name = str(adapter.name).strip().lower()
+
+        with self._lock:
+            if provider_name in self._adapters or provider_name in self._lazy:
+                raise ValueError(f"Provider '{provider_name}' is already registered")
+            self._adapters[provider_name] = adapter
+
+    def register_lazy(self, name: str, factory: Any, *, skip_if_exists: bool = False) -> None:
+        """Register a lazy-loaded adapter via callable factory.
+
+        When ``skip_if_exists`` is True, silently skip registration if the
+        provider name is already registered (eager or lazy).  This is used
+        by ``Client`` to register built-in providers without conflicting
+        with user-registered adapters.
+        """
+        normalized_name = name.strip().lower()
+        if not normalized_name:
+            msg = "Provider name cannot be empty"
+            raise ValueError(msg)
+        if not callable(factory):
+            msg = "Lazy adapter factory must be callable"
+            raise TypeError(msg)
+
+        with self._lock:
+            if normalized_name in self._adapters or normalized_name in self._lazy:
+                if skip_if_exists:
+                    return
+                raise ValueError(f"Provider '{normalized_name}' is already registered")
+            self._lazy[normalized_name] = factory
+
+    def get(self, name: str) -> Any:
+        """Retrieve adapter by provider name."""
+        normalized_name = name.strip().lower()
+        with self._lock:
+            adapter = self._adapters.get(normalized_name)
+            if adapter is not None:
+                return adapter
+
+            factory = self._lazy.pop(normalized_name, None)
+
+        if factory is None:
+            raise ProviderNotRegisteredError(f"Provider '{name}' is not registered")
+
+        lazy_adapter = factory()
+        self._validate_adapter(lazy_adapter)
+        adapter_name = str(lazy_adapter.name).strip().lower()
+        if adapter_name != normalized_name:
+            raise TypeError(
+                f"Lazy adapter name mismatch: expected '{normalized_name}', got '{adapter_name}'"
+            )
+
+        with self._lock:
+            self._adapters[normalized_name] = lazy_adapter
+        return lazy_adapter
+
+    def __contains__(self, name: str) -> bool:
+        """Return True if adapter is registered eagerly or lazily."""
+        normalized_name = name.strip().lower()
+        with self._lock:
+            return normalized_name in self._adapters or normalized_name in self._lazy
+
+    def __iter__(self) -> Iterator[str]:
+        """Iterate provider names currently known to the registry."""
+        with self._lock:
+            names = set(self._adapters.keys()) | set(self._lazy.keys())
+        return iter(sorted(names))
+
+    @staticmethod
+    def _validate_adapter(adapter: Any) -> None:
+        """Check that adapter has required protocol methods."""
+        name = getattr(adapter, "name", None)
+        if not isinstance(name, str) or not name.strip():
+            msg = "Adapter must define a non-empty string attribute 'name'"
+            raise TypeError(msg)
+
+        missing = [
+            method_name for method_name in _REQUIRED_METHODS if not hasattr(adapter, method_name)
+        ]
+        if missing:
+            raise TypeError(f"Adapter '{name}' is missing required methods: {missing}")
+
+        non_callable = [
+            method_name
+            for method_name in _REQUIRED_METHODS
+            if not callable(getattr(adapter, method_name, None))
+        ]
+        if non_callable:
+            raise TypeError(f"Adapter '{name}' has non-callable required methods: {non_callable}")
+
+
+__all__ = ["ProviderRegistry"]

kpubdata/transport/__init__.py

@@ -0,0 +1,16 @@
+"""Transport utilities for HTTP, retries, and content decoding."""
+
+from __future__ import annotations
+
+from kpubdata.transport.decode import decode_json, decode_xml, detect_content_type
+from kpubdata.transport.http import HttpTransport, TransportConfig
+from kpubdata.transport.retry import with_retry
+
+__all__ = [
+    "HttpTransport",
+    "TransportConfig",
+    "decode_json",
+    "decode_xml",
+    "detect_content_type",
+    "with_retry",
+]

kpubdata/transport/decode.py

@@ -0,0 +1,74 @@
+"""Response decoding utilities — content-type detection, JSON/XML helpers."""
+
+from __future__ import annotations
+
+import json
+from importlib import import_module
+
+import httpx
+
+from ..exceptions import ParseError
+
+
+def detect_content_type(response: httpx.Response) -> str:
+    """Detect whether response is JSON, XML, or other based on content-type header."""
+    header_value_obj = response.headers.get("content-type", "")
+    content_type = str(header_value_obj).lower()
+    if "json" in content_type:
+        return "json"
+    if "xml" in content_type:
+        return "xml"
+    return "other"
+
+
+def decode_json(data: str | bytes) -> object:
+    """Decode JSON with clear error on failure."""
+    try:
+        payload = data.decode("utf-8") if isinstance(data, bytes) else data
+    except UnicodeDecodeError as exc:
+        msg = "Failed to decode JSON bytes as UTF-8"
+        raise ParseError(msg) from exc
+
+    try:
+        return json.loads(payload)
+    except json.JSONDecodeError as exc:
+        msg = "Failed to decode JSON payload"
+        raise ParseError(msg) from exc
+
+
+def decode_xml(data: str | bytes) -> dict[str, object]:
+    """Decode XML to dict.
+
+    Raises:
+        ImportError: If ``xmltodict`` is not installed.
+        ParseError: If parsing fails.
+    """
+    try:
+        xmltodict = import_module("xmltodict")
+    except ImportError as exc:
+        msg = (
+            "decode_xml requires optional dependency 'xmltodict'. Install with: "
+            "pip install kpubdata[xml]"
+        )
+        raise ImportError(msg) from exc
+
+    try:
+        payload = data.decode("utf-8") if isinstance(data, bytes) else data
+    except UnicodeDecodeError as exc:
+        msg = "Failed to decode XML bytes as UTF-8"
+        raise ParseError(msg) from exc
+
+    try:
+        parsed: object = xmltodict.parse(payload)
+    except Exception as exc:  # noqa: BLE001
+        msg = "Failed to decode XML payload"
+        raise ParseError(msg) from exc
+
+    if isinstance(parsed, dict):
+        return parsed
+
+    msg = "XML payload did not decode into a dictionary"
+    raise ParseError(msg)
+
+
+__all__ = ["decode_json", "decode_xml", "detect_content_type"]