statwrapper 0.1.0__py3-none-any.whl

statwrapper/statwrapper.py

@@ -0,0 +1,103 @@
+from __future__ import annotations
+
+import asyncio
+import logging
+import uuid
+from pathlib import Path
+from typing import Any
+
+from .http import RateLimitedSession
+from .models import DiscoveredDataset, Provider, ResolvedDatasetMetadata
+from .provider_registry import create_wrapper, get_provider, load_providers
+
+
+class StatWrapper:
+    def __init__(
+        self,
+        *,
+        providers_path: str | Path | None = None,
+        session: RateLimitedSession | None = None,
+        logger: logging.Logger | None = None,
+    ) -> None:
+        self.providers_path = providers_path
+        self.providers = load_providers(providers_path)
+        self.provider_map = {
+            provider.provider_code: provider for provider in self.providers
+        }
+        self.logger = logger or logging.getLogger(__name__)
+        self.session = session or RateLimitedSession(
+            default_rate=1.0,
+            host_rates={
+                provider.base_api_url or provider.provider_code: (
+                    1.0 / provider.rate_limit if provider.rate_limit > 0 else 1.0
+                )
+                for provider in self.providers
+            },
+        )
+
+    def get_provider(self, provider_code: str) -> Provider:
+        return get_provider(provider_code, self.providers)
+
+    def get_wrapper(self, provider_code: str, language: str):
+        provider = self.get_provider(provider_code)
+        return create_wrapper(
+            provider,
+            language=language,
+            json_request_handler=self.session.get_json,
+            text_request_handler=self.session.get_text,
+            bytes_request_handler=self.session.get_bytes,
+            logger=self.logger,
+        )
+
+    async def discover_datasets(
+        self,
+        provider_code: str,
+        language: str,
+        *,
+        task_id: uuid.UUID | None = None,
+    ) -> list[DiscoveredDataset]:
+        wrapper = self.get_wrapper(provider_code, language)
+        return await wrapper.discover_datasets(task_id or uuid.uuid4())
+
+    async def resolve_dataset_metadata(
+        self,
+        discovered: DiscoveredDataset,
+        *,
+        task_id: uuid.UUID | None = None,
+    ) -> ResolvedDatasetMetadata:
+        wrapper = self.get_wrapper(discovered.provider_code, discovered.language)
+        return await wrapper.resolve_dataset_metadata(discovered, task_id=task_id)
+
+
+async def discover_provider_datasets(
+    provider_code: str,
+    language: str,
+    *,
+    providers_path: str | Path | None = None,
+) -> list[DiscoveredDataset]:
+    wrapper = StatWrapper(providers_path=providers_path)
+    return await wrapper.discover_datasets(provider_code, language)
+
+
+async def resolve_dataset_metadata(
+    discovered: DiscoveredDataset,
+    *,
+    providers_path: str | Path | None = None,
+) -> ResolvedDatasetMetadata:
+    wrapper = StatWrapper(providers_path=providers_path)
+    return await wrapper.resolve_dataset_metadata(discovered)
+
+
+def get_datasets(
+    provider_code: str,
+    language: str,
+    *,
+    providers_path: str | Path | None = None,
+) -> list[dict[str, Any]]:
+    async def _run() -> list[dict[str, Any]]:
+        wrapper = StatWrapper(providers_path=providers_path)
+        discovered = await wrapper.discover_datasets(provider_code, language)
+        resolved = [await wrapper.resolve_dataset_metadata(item) for item in discovered]
+        return [item.__dict__ for item in resolved]
+
+    return asyncio.run(_run())

statwrapper/utils.py

@@ -0,0 +1,134 @@
+from __future__ import annotations
+
+import re
+from datetime import datetime, timezone
+from typing import Any
+
+TIME_LABEL_PATTERNS: dict[str, re.Pattern[str]] = {
+    "Annual": re.compile(r"^(1[5-9][0-9]{2}|2[0-9]{3}|3000)$"),
+    "Quarterly": re.compile(r"^(1[5-9][0-9]{2}|2[0-9]{3}|3000)[QK][1-4]$"),
+    "Monthly": re.compile(
+        r"^(1[5-9][0-9]{2}|2[0-9]{3}|3000)(M0?[1-9]|M1[0-2]|0?[1-9]|1[0-2])$"
+    ),
+    "Weekly": re.compile(
+        r"^(1[5-9][0-9]{2}|2[0-9]{3}|3000)(W0?[1-9]|W[1-4][0-9]|W5[0-3])$"
+    ),
+    "Other": re.compile(
+        r"^(1[5-9][0-9]{2}|2[0-9]{3}|3000)(W0?[1-9]|W[1-4][0-9]|W5[0-3]|V0?[1-9]|V[1-4][0-9]|V5[0-3])$"
+    ),
+}
+
+TIME_ALTERNATIVES = {
+    "time",
+    "tid",
+    "year",
+    "quarter",
+    "month",
+    "week",
+    "period",
+    "time period",
+}
+GEO_ALTERNATIVES = {
+    "geo",
+    "region",
+    "country",
+    "municipality",
+    "county",
+    "location",
+    "area",
+}
+METRIC_ALTERNATIVES = {
+    "unit",
+    "contents",
+    "measure",
+    "metric",
+    "value",
+    "content",
+    "contentscode",
+}
+
+
+def determine_time_unit(first_period: str | None, last_period: str | None) -> str:
+    if not first_period or not last_period:
+        return "Other"
+    for time_format, pattern in TIME_LABEL_PATTERNS.items():
+        if pattern.match(first_period) and pattern.match(last_period):
+            return time_format
+    return "Other"
+
+
+def detect_role(code: str, label: str, is_time: bool = False) -> str | None:
+    if is_time:
+        return "time"
+
+    norm_code = code.strip().lower()
+    norm_label = label.strip().lower()
+    if norm_code == "contentscode" or norm_code in METRIC_ALTERNATIVES:
+        return "metric"
+    if norm_label in METRIC_ALTERNATIVES:
+        return "metric"
+    if norm_code in GEO_ALTERNATIVES or norm_label in GEO_ALTERNATIVES:
+        return "geo"
+    if norm_code in TIME_ALTERNATIVES or norm_label in TIME_ALTERNATIVES:
+        return "time"
+    return None
+
+
+def parse_dt(value: str | datetime | None) -> datetime | None:
+    if value is None:
+        return None
+    if isinstance(value, datetime):
+        return (
+            value.astimezone(timezone.utc)
+            if value.tzinfo
+            else value.replace(tzinfo=timezone.utc)
+        )
+    if isinstance(value, str):
+        raw = value.strip()
+        if not raw:
+            return None
+        normalized = raw.replace("Z", "+00:00")
+        try:
+            parsed = datetime.fromisoformat(normalized)
+        except ValueError:
+            return None
+        return (
+            parsed.astimezone(timezone.utc)
+            if parsed.tzinfo
+            else parsed.replace(tzinfo=timezone.utc)
+        )
+    return None
+
+
+def normalize_note(value: Any) -> list[str] | None:
+    if value is None:
+        return None
+    if isinstance(value, str):
+        cleaned = value.strip()
+        return [cleaned] if cleaned else None
+    if isinstance(value, list):
+        notes = [str(item).strip() for item in value if str(item).strip()]
+        return notes or None
+    if isinstance(value, dict):
+        text = str(value.get("text") or "").strip()
+        return [text] if text else None
+    return None
+
+
+def normalize_contact(raw_contact: Any) -> dict[str, Any] | None:
+    if raw_contact is None:
+        return None
+    if isinstance(raw_contact, dict):
+        return raw_contact
+    if isinstance(raw_contact, list):
+        contacts = [item for item in raw_contact if isinstance(item, dict)]
+        if contacts:
+            return {"contacts": contacts}
+        values = [str(item).strip() for item in raw_contact if str(item).strip()]
+        return {"values": values} if values else None
+    value = str(raw_contact).strip()
+    return {"value": value} if value else None
+
+
+def ensure_datetime(value: datetime | None, fallback: datetime) -> datetime:
+    return value if value is not None else fallback

statwrapper-0.1.0.dist-info/METADATA

@@ -0,0 +1,123 @@
+Metadata-Version: 2.4
+Name: statwrapper
+Version: 0.1.0
+Summary: A completely dependency-free unified wrapper around common statistical api types
+Author-email: Nordic Intel <info@nordicintel.com>
+License-Expression: Apache-2.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: pytest>=8.3.5; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.26.0; extra == "dev"
+Requires-Dist: build>=1.2.2; extra == "dev"
+Requires-Dist: ruff>=0.11.0; extra == "dev"
+
+# statwrapper
+
+`statwrapper` is a dependency-free Python library that provides a unified interface for common statistical API families. It currently ships wrapper support for:
+
+- `pxweb`
+- `pxweb2`
+- `dst`
+- `eurostat`
+
+The package standardizes three operations across providers:
+
+- health checks
+- dataset discovery
+- dataset metadata resolution
+
+## Installation
+
+```bash
+pip install statwrapper
+```
+
+## Quick Start
+
+```python
+import asyncio
+
+from statwrapper import StatWrapper
+
+
+async def main() -> None:
+    wrapper = StatWrapper()
+
+    discovered = await wrapper.discover_datasets("scb", "en")
+    first = discovered[0]
+
+    metadata = await wrapper.resolve_dataset_metadata(first)
+    print(metadata.label)
+    print(metadata.dimension_ids)
+
+
+asyncio.run(main())
+```
+
+## Public API
+
+### `StatWrapper`
+
+```python
+from statwrapper import StatWrapper
+
+wrapper = StatWrapper()
+```
+
+Methods:
+
+- `await wrapper.discover_datasets(provider_code, language, task_id=None)`
+- `await wrapper.resolve_dataset_metadata(discovered, task_id=None)`
+- `wrapper.get_provider(provider_code)`
+- `wrapper.get_wrapper(provider_code, language)`
+
+### Convenience Functions
+
+```python
+from statwrapper import discover_provider_datasets, get_datasets
+```
+
+- `await discover_provider_datasets(provider_code, language)`
+- `get_datasets(provider_code, language)`
+
+## Request Layer
+
+The default request layer is a stdlib-backed async helper:
+
+```python
+from statwrapper import RateLimitedSession
+```
+
+`StatWrapper` uses `RateLimitedSession` automatically, but you can inject your own session object if it exposes:
+
+- `async def get_json(url, **kwargs)`
+- `async def get_text(url, **kwargs)`
+- `async def get_bytes(url, **kwargs)`
+
+## Provider Registry
+
+Provider metadata is loaded from `PROVIDERS.json`. During development, the package reads the repository file. In built distributions, the same data is bundled inside the package.
+
+## Development
+
+Run tests:
+
+```bash
+python -m pytest tests/unit tests/integration -q
+```
+
+Build locally:
+
+```bash
+python -m build
+```
+
+## Publishing
+
+PyPI publishing is handled by GitHub Actions through `.github/workflows/pypi_publish.yml` and the repository secret `PYPI_API_TOKEN`.

statwrapper-0.1.0.dist-info/RECORD

@@ -0,0 +1,19 @@
+statwrapper/__init__.py,sha256=CdE6EEri0RV7rS3j7P0UqG--gA0zh2_xKD84WI8ua6w,717
+statwrapper/base_api_client.py,sha256=yRdQFqVivspndudmqV3BObdKYsOLu3cO9Obt7UAgcns,2753
+statwrapper/exceptions.py,sha256=c4RQ64Y09qy0iSMuEmN44IlQ6ovGs3EvL5oru_QDAzE,696
+statwrapper/http.py,sha256=2clxVis_pe_OztivWztEkQEriBG4C0PdNp0YZosCVMM,3992
+statwrapper/models.py,sha256=XCmzxoTL63aQeYNKVgfY5TT9rKVMVRkdEpWk8DYg8uw,3043
+statwrapper/parsers.py,sha256=UT18AsV7c4iGhOieTlh6pA-_eTA6RgHmeCUeo0vC-s4,9098
+statwrapper/provider_registry.py,sha256=mszPwnLzDJZgy5IEa5Bt_AvMJqEtfrIBx5CHot4JlF4,2129
+statwrapper/providers.json,sha256=szqdqRg0KmHxzoIZn3GC0391FksaeSgTJP0QNOMDC6M,17391
+statwrapper/statwrapper.py,sha256=lDmpdSPyIsKYWsUAB81H10o0J_ay_1zFwOHa2ZF2pdk,3426
+statwrapper/utils.py,sha256=2TcyI4wvN2G9xOkBcYv2xd4UPzfgh1m-1zWA4HAkmS8,3867
+statwrapper/api_clients/__init__.py,sha256=E6yujDDgv8nRfrjquS_isWQaHa55Pw-zRmYX5AV1ajE,249
+statwrapper/api_clients/dst_client.py,sha256=iJj3OHWbNYpHPRp3CG5dAG_BGLfBUyot3o-9aWlJkzA,11368
+statwrapper/api_clients/eurostat_client.py,sha256=7O6-e5HVoGhPaxbm9xVkgJNPsqhyKs53wYcSjt3Z2Tg,15164
+statwrapper/api_clients/pxweb2_client.py,sha256=eIK4Ebia8uxlombk7jmbf7_NGz-D9TF2VaBllDdacB4,7256
+statwrapper/api_clients/pxweb_client.py,sha256=J1vdvJBaakEF8I8Qn5OoLaPbccnemWfGfq9oheJEhs0,10522
+statwrapper-0.1.0.dist-info/METADATA,sha256=BHruDjBAveNPcjB2tfbmXEGw9VZ2B9puqkCA2wg_Z4c,2928
+statwrapper-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+statwrapper-0.1.0.dist-info/top_level.txt,sha256=8UiAVmS9MtJZrYmiJgBWYpgoCQ1jvW-Y8YN9E4Pm96E,12
+statwrapper-0.1.0.dist-info/RECORD,,

statwrapper-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

statwrapper-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+statwrapper