pbs-client 0.1.0__py3-none-any.whl

pbs_client/__init__.py

@@ -0,0 +1,5 @@
+"""Offline-first client and local mirror for the PBS Public Data API v3."""
+
+from pbs_client.config import PBSClientConfig, PBSSettings, get_pbs_context
+
+__all__ = ["PBSClientConfig", "PBSSettings", "get_pbs_context"]

pbs_client/cli/__init__.py

@@ -0,0 +1,6 @@
+"""pbs-client command line entry point."""
+
+from pbs_client.cli.main import app, main
+
+__all__ = ["app", "main"]
+

pbs_client/cli/main.py

@@ -0,0 +1,127 @@
+"""Thin Typer command line interface over the library layers."""
+
+from __future__ import annotations
+
+from sqlalchemy.engine import Engine
+import typer
+
+from pbs_client.config import PBSSettings, get_pbs_context
+from pbs_client.db import init_db, make_engine, make_session_factory
+from pbs_client.errors import PBSSyncError, PBSTransportError
+from pbs_client.http import PBSClient
+from pbs_client.sync import SyncOrchestrator, mirror_status
+
+app = typer.Typer(help="Maintain a local offline mirror of the PBS Public Data API v3.")
+
+
+def _runtime(db_path: str | None) -> tuple[PBSSettings, Engine, str]:
+    """Resolve shared config, with ``--db-path`` retained as a local override."""
+
+    if db_path is not None:
+        settings = PBSSettings.from_env()
+        return settings, make_engine(db_path), db_path
+
+    config, database = get_pbs_context()
+    return PBSSettings.from_config(config), database.create_engine(future=True), config.pbs_db
+
+
+def _find_transport_error(error: BaseException) -> PBSTransportError | None:
+    """Find a transport failure retained in a wrapped sync exception."""
+
+    current: BaseException | None = error
+    while current is not None:
+        if isinstance(current, PBSTransportError):
+            return current
+        current = current.__cause__
+    return None
+
+
+def _report_sync_failure(error: PBSSyncError) -> None:
+    """Print an actionable, traceback-free message for a failed CLI sync."""
+
+    resource = error.resource or "the current resource"
+    transport = _find_transport_error(error)
+    typer.echo(f"PBS sync paused on {resource}.", err=True)
+    if transport is not None and transport.timed_out:
+        typer.echo(
+            "The PBS API did not respond before the request timeout after "
+            f"{transport.attempts} attempts.",
+            err=True,
+        )
+        typer.echo(
+            "Try a smaller page size if the response is large; completed "
+            "resources are already saved.",
+            err=True,
+        )
+        limit = " --limit 1000"
+    else:
+        typer.echo(str(error), err=True)
+        typer.echo("Completed resources are already saved and can be resumed.", err=True)
+        limit = ""
+    typer.echo("Resume with:", err=True)
+    typer.echo(
+        f"  uv run pbs-client sync --resource {resource} --resume-only{limit}",
+        err=True,
+    )
+
+
+@app.command("init-db")
+def init_db_command(
+    db_path: str | None = typer.Option(None, "--db-path", help="SQLite path or SQLAlchemy URL."),
+) -> None:
+    """Create the local schema without making any network request."""
+
+    _, engine, database_name = _runtime(db_path)
+    init_db(engine)
+    typer.echo(f"Initialized PBS database {database_name!r}")
+
+
+@app.command("sync")
+def sync_command(
+    resource: str | None = typer.Option(None, help="Only sync one resource, e.g. Item."),
+    db_path: str | None = typer.Option(None, "--db-path", help="SQLite path or SQLAlchemy URL."),
+    refresh: bool = typer.Option(
+        True, "--refresh/--resume-only", help="Refresh completed resources."
+    ),
+    limit: int = typer.Option(100_000, min=1, help="API page size."),
+) -> None:
+    """Synchronize all PBS resources, or one resource, into the local mirror."""
+
+    settings, engine, _ = _runtime(db_path)
+    init_db(engine)
+    sessions = make_session_factory(engine)
+    try:
+        results = SyncOrchestrator(PBSClient(settings), sessions).run(
+            resource=resource,
+            limit=limit,
+            refresh_completed=refresh,
+        )
+    except PBSSyncError as exc:
+        _report_sync_failure(exc)
+        raise typer.Exit(code=1) from None
+    for result in results:
+        typer.echo(
+            f"{result.resource}: {result.status}; pages={result.pages}; "
+            f"records={result.records_written}"
+        )
+
+
+@app.command()
+def status(
+    db_path: str | None = typer.Option(None, "--db-path", help="SQLite path or SQLAlchemy URL."),
+) -> None:
+    """Show checkpoint status and local row counts for every resource."""
+
+    _, engine, _ = _runtime(db_path)
+    init_db(engine)
+    with make_session_factory(engine)() as session:
+        for row in mirror_status(session):
+            completed = row["completed_at"].isoformat() if row["completed_at"] else "-"
+            typer.echo(
+                f"{row['resource']}: {row['status']}; rows={row['rows']}; "
+                f"page={row['page']}; completed={completed}"
+            )
+
+
+def main() -> None:
+    app()

pbs_client/config.py

@@ -0,0 +1,107 @@
+"""PBS client settings and oa-configurator integration."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Annotated, ClassVar
+
+from oa_configurator import (
+    GenericDatabaseConfig,
+    PackageConfigBase,
+    RefTo,
+    ResolvedDatabase,
+    Resolver,
+    Sensitive,
+    load_stack_config,
+)
+from pydantic import Field
+
+
+DEFAULT_BASE_URL = "https://data-api.health.gov.au/pbs/api/v3"
+DEFAULT_PUBLIC_KEY = "2384af7c667342ceb5a736fe29f1dc6b"
+DEFAULT_RATE_LIMIT_SECONDS = 20.0
+
+
+class PBSClientConfig(PackageConfigBase):
+    """Typed ``[tools.pbs_client]`` configuration for the PBS mirror.
+
+    The database is a named generic database rather than a package-local path,
+    so another package—eventually Groundworkers—can resolve and use the same
+    persisted PBS mirror through oa-configurator.
+    """
+
+    tool_name: ClassVar[str] = "pbs_client"
+
+    pbs_db: Annotated[str, RefTo(GenericDatabaseConfig)] = Field(
+        default="pbs_db",
+        description="Name of the generic database that stores the PBS mirror.",
+    )
+    subscription_key: Annotated[str, Sensitive()] = Field(
+        default=DEFAULT_PUBLIC_KEY,
+        description="PBS Public Data API subscription key.",
+    )
+    base_url: str = Field(
+        default=DEFAULT_BASE_URL,
+        description="PBS Public Data API v3 base URL.",
+    )
+    rate_limit_seconds: float = Field(
+        default=DEFAULT_RATE_LIMIT_SECONDS,
+        gt=0,
+        description="Minimum delay between PBS API requests in seconds.",
+    )
+
+
+def get_pbs_context() -> tuple[PBSClientConfig, ResolvedDatabase]:
+    """Load the configured PBS client and resolve its mirror database.
+
+    Raises
+    ------
+    RuntimeError
+        If the shared oa-configurator stack file has not been created yet.
+    """
+
+    try:
+        stack = load_stack_config()
+    except FileNotFoundError as exc:
+        raise RuntimeError(
+            "No pbs-client configuration found. "
+            "Run `omop-config configure pbs_client` to set it up."
+        ) from exc
+    resolver = Resolver(stack)
+    config = resolver.resolve_package_config(PBSClientConfig)
+    database = resolver.resolve_database(config.pbs_db)
+    return config, database
+
+
+@dataclass(frozen=True, slots=True)
+class PBSSettings:
+    """Configuration used by the HTTP, database, and CLI layers."""
+
+    subscription_key: str = DEFAULT_PUBLIC_KEY
+    db_path: Path = Path("pbs_client.db")
+    base_url: str = DEFAULT_BASE_URL
+    rate_limit_seconds: float = DEFAULT_RATE_LIMIT_SECONDS
+
+    @classmethod
+    def from_config(cls, config: PBSClientConfig) -> PBSSettings:
+        """Build HTTP settings from the resolved package configuration."""
+
+        return cls(
+            subscription_key=config.subscription_key,
+            base_url=config.base_url.rstrip("/"),
+            rate_limit_seconds=config.rate_limit_seconds,
+        )
+
+    @classmethod
+    def from_env(cls) -> PBSSettings:
+        """Build settings from the documented ``PBS_CLIENT_*`` variables."""
+
+        rate = os.getenv("PBS_CLIENT_RATE_LIMIT_SECONDS")
+        return cls(
+            subscription_key=os.getenv("PBS_CLIENT_SUBSCRIPTION_KEY", DEFAULT_PUBLIC_KEY),
+            db_path=Path(os.getenv("PBS_CLIENT_DB_PATH", "./pbs_client.db")),
+            base_url=os.getenv("PBS_CLIENT_BASE_URL", DEFAULT_BASE_URL).rstrip("/"),
+            rate_limit_seconds=float(rate) if rate else DEFAULT_RATE_LIMIT_SECONDS,
+        )

pbs_client/db/__init__.py

@@ -0,0 +1,27 @@
+"""Local SQLAlchemy mirror for PBS API resources."""
+
+from pbs_client.db.engine import database_url, init_db, make_engine, make_session_factory
+from pbs_client.db.model import Base
+from pbs_client.db.schema import (
+    RESOURCE_BY_ENDPOINT,
+    RESOURCE_BY_NAME,
+    RESOURCE_SPECS,
+    SYNC_ORDER,
+)
+from pbs_client.db.state import SyncState
+
+MODEL_BY_NAME = {spec.name: spec.model for spec in RESOURCE_SPECS}
+
+__all__ = [
+    "MODEL_BY_NAME",
+    "RESOURCE_BY_ENDPOINT",
+    "RESOURCE_BY_NAME",
+    "RESOURCE_SPECS",
+    "SYNC_ORDER",
+    "Base",
+    "SyncState",
+    "database_url",
+    "init_db",
+    "make_engine",
+    "make_session_factory",
+]

pbs_client/db/engine.py

@@ -0,0 +1,37 @@
+"""Database engine and schema helpers."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from sqlalchemy import Engine, create_engine
+from sqlalchemy.orm import sessionmaker
+
+from pbs_client.db.model import Base
+
+
+def database_url(path_or_url: str | Path) -> str:
+    """Return a SQLAlchemy URL for a filesystem path or an explicit URL."""
+
+    value = str(path_or_url)
+    if "://" in value:
+        return value
+    return f"sqlite:///{Path(value).expanduser()}"
+
+
+def make_engine(path_or_url: str | Path = "pbs_client.db") -> Engine:
+    """Construct an engine without connecting or making network requests."""
+
+    return create_engine(database_url(path_or_url), future=True)
+
+
+def make_session_factory(engine: Engine):
+    """Return a configured SQLAlchemy session factory."""
+
+    return sessionmaker(bind=engine, expire_on_commit=False, future=True)
+
+
+def init_db(engine: Engine) -> None:
+    """Create the complete local mirror schema if it does not exist."""
+
+    Base.metadata.create_all(engine)

pbs_client/db/model/__init__.py

@@ -0,0 +1,83 @@
+"""PBS resource model package."""
+
+from pbs_client.db.model.base import Base, PBSRecordMixin
+from pbs_client.db.model.core import (
+    ATC,
+    ApiChangelog,
+    Container,
+    Copayment,
+    Criteria,
+    DispensingRule,
+    ExtemporaneousPreparation,
+    Fee,
+    Indication,
+    Organisation,
+    Parameter,
+    PrescribingTxt,
+    Program,
+    ProgramDispensingRules,
+    RestrictionText,
+    Schedule,
+)
+from pbs_client.db.model.items import (
+    ExtemporaneousDrugTariff,
+    ExtemporaneousIngredient,
+    Item,
+    ItemAmt,
+    ItemOverview,
+    Prescriber,
+    StandardFormulaPreparations,
+)
+from pbs_client.db.model.pricing import MarkupBand, SummaryOfChanges
+from pbs_client.db.model.relationships import (
+    ContainerWholesalerRltd,
+    CriteriaParameterRltd,
+    ExPrepSfpRltd,
+    ItemAtcRltd,
+    ItemDispensingRuleRltd,
+    ItemOrganisationRltd,
+    ItemPrescribingTxtRltd,
+    ItemPricingEvent,
+    ItemRestrictionRltd,
+    RstrctnPrscrbngTxtRltd,
+)
+
+__all__ = [
+    "ATC",
+    "ApiChangelog",
+    "Base",
+    "Container",
+    "ContainerWholesalerRltd",
+    "Copayment",
+    "Criteria",
+    "CriteriaParameterRltd",
+    "DispensingRule",
+    "ExPrepSfpRltd",
+    "ExtemporaneousDrugTariff",
+    "ExtemporaneousIngredient",
+    "ExtemporaneousPreparation",
+    "Fee",
+    "Indication",
+    "Item",
+    "ItemAmt",
+    "ItemAtcRltd",
+    "ItemDispensingRuleRltd",
+    "ItemOrganisationRltd",
+    "ItemOverview",
+    "ItemPrescribingTxtRltd",
+    "ItemPricingEvent",
+    "ItemRestrictionRltd",
+    "MarkupBand",
+    "Organisation",
+    "PBSRecordMixin",
+    "Parameter",
+    "Prescriber",
+    "PrescribingTxt",
+    "Program",
+    "ProgramDispensingRules",
+    "RestrictionText",
+    "RstrctnPrscrbngTxtRltd",
+    "Schedule",
+    "StandardFormulaPreparations",
+    "SummaryOfChanges",
+]

pbs_client/db/model/base.py

@@ -0,0 +1,18 @@
+"""Declarative base and shared PBS model concerns."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import sqlalchemy as sa
+import sqlalchemy.orm as so
+
+
+class Base(so.DeclarativeBase):
+    """Declarative registry for the local PBS mirror."""
+
+
+class PBSRecordMixin:
+    """Retain the original API object for forward-compatible fields."""
+
+    raw_payload: so.Mapped[dict[str, Any]] = so.mapped_column(sa.JSON, nullable=False, default=dict)