dhis2w-core 0.5.1__tar.gz

dhis2w_core-0.5.1/PKG-INFO

@@ -0,0 +1,23 @@
+Metadata-Version: 2.3
+Name: dhis2w-core
+Version: 0.5.1
+Summary: Shared DHIS2 tooling runtime: profile discovery, plugin registry, auth factory, token store, first-party plugins.
+Author: Morten Hansen
+Author-email: Morten Hansen <morten@winterop.com>
+Requires-Dist: dhis2w-client>=0.5.0,<0.6
+Requires-Dist: pydantic>=2.13
+Requires-Dist: pydantic-settings>=2.13
+Requires-Dist: tomli-w>=1.2
+Requires-Dist: typer>=0.24
+Requires-Dist: rich>=15
+Requires-Dist: fastmcp>=3.2
+Requires-Dist: sqlalchemy[asyncio]>=2.0
+Requires-Dist: aiosqlite>=0.22
+Requires-Dist: alembic>=1.18
+Requires-Dist: fastapi>=0.115
+Requires-Dist: uvicorn>=0.32
+Requires-Dist: bcrypt>=5.0.0
+Requires-Dist: questionary>=2.1.1
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+

dhis2w_core-0.5.1/pyproject.toml

@@ -0,0 +1,27 @@
+[project]
+name = "dhis2w-core"
+version = "0.5.1"
+description = "Shared DHIS2 tooling runtime: profile discovery, plugin registry, auth factory, token store, first-party plugins."
+readme = "README.md"
+authors = [{ name = "Morten Hansen", email = "morten@winterop.com" }]
+requires-python = ">=3.13"
+dependencies = [
+  "dhis2w-client>=0.5.0,<0.6",
+  "pydantic>=2.13",
+  "pydantic-settings>=2.13",
+  "tomli-w>=1.2",
+  "typer>=0.24",
+  "rich>=15",
+  "fastmcp>=3.2",
+  "sqlalchemy[asyncio]>=2.0",
+  "aiosqlite>=0.22",
+  "alembic>=1.18",
+  "fastapi>=0.115",
+  "uvicorn>=0.32",
+  "bcrypt>=5.0.0",
+  "questionary>=2.1.1",
+]
+
+[build-system]
+requires = ["uv_build>=0.11.7,<0.12.0"]
+build-backend = "uv_build"

dhis2w_core-0.5.1/src/dhis2w_core/__init__.py

@@ -0,0 +1 @@
+"""Shared DHIS2 tooling runtime: profile discovery, plugin registry, auth factory, first-party plugins."""

dhis2w_core-0.5.1/src/dhis2w_core/cli_errors.py

@@ -0,0 +1,144 @@
+"""Clean-error rendering for CLI commands.
+
+Expected user-facing errors get printed as a one-line message (in red, on
+stderr) plus a short hint block, then exit 1. Programming bugs (AssertionError,
+KeyError, etc.) still propagate and show a full traceback so they can be
+triaged.
+"""
+
+from __future__ import annotations
+
+import sys
+from typing import NoReturn
+
+import typer
+from dhis2w_client.envelopes import WebMessageResponse
+from dhis2w_client.errors import AuthenticationError, Dhis2ApiError, Dhis2ClientError, OAuth2FlowError
+
+from dhis2w_core.plugins.profile.service import ProfileAlreadyExistsError
+from dhis2w_core.profile import (
+    InvalidProfileNameError,
+    NoProfileError,
+    UnknownProfileError,
+)
+
+_NO_PROFILE_HINT = [
+    "run `dhis2 profile --help` for setup options, or try:",
+    "  dhis2 profile list                             # see what's configured",
+    "  dhis2 profile add <name> --scope global \\",
+    "      --url https://dhis2.example.org \\",
+    "      --auth pat --token d2p_... --default",
+    "  dhis2 profile verify <name>                    # confirm auth works",
+]
+
+_UNKNOWN_PROFILE_HINT = [
+    "run `dhis2 profile list` to see available profiles",
+    "or `dhis2 profile add <name> ...` to create one",
+]
+
+_INVALID_NAME_HINT = [
+    "profile names must start with a letter and contain only letters,",
+    "digits, and underscores (e.g. 'local', 'prod_eu', 'laohis42').",
+]
+
+_AUTH_HINT = [
+    "run `dhis2 profile verify <name>` to confirm auth",
+    "or `dhis2 profile show <name>` to inspect the stored credentials",
+]
+
+_ALREADY_EXISTS_HINT = [
+    "run `dhis2 profile list` to see existing profiles",
+    "or `dhis2 profile remove <name>` first to free the name",
+]
+
+_OAUTH2_HINT = [
+    "run `dhis2 profile login <name>` to re-authorise the OAuth2 flow",
+    "or `dhis2 profile verify <name>` to confirm the current state",
+]
+
+
+def run_app(app: typer.Typer) -> NoReturn:
+    """Invoke a Typer app with clean error rendering for known exceptions."""
+    try:
+        app()
+    except NoProfileError as exc:
+        _render("error", str(exc), _NO_PROFILE_HINT)
+    except UnknownProfileError as exc:
+        _render("error", str(exc), _UNKNOWN_PROFILE_HINT)
+    except InvalidProfileNameError as exc:
+        _render("error", str(exc), _INVALID_NAME_HINT)
+    except ProfileAlreadyExistsError as exc:
+        _render("error", str(exc), _ALREADY_EXISTS_HINT)
+    except AuthenticationError as exc:
+        _render("auth error", str(exc), _AUTH_HINT)
+    except OAuth2FlowError as exc:
+        _render("oauth2 error", str(exc), _OAUTH2_HINT)
+    except Dhis2ApiError as exc:
+        _render_api_error(exc)
+    except Dhis2ClientError as exc:
+        _render("DHIS2 error", str(exc))
+    except LookupError as exc:
+        _render("error", str(exc))
+    sys.exit(0)
+
+
+def _render_api_error(exc: Dhis2ApiError) -> NoReturn:
+    """Render a Dhis2ApiError — extract the WebMessage envelope when DHIS2 ships one."""
+    envelope = exc.web_message
+    detail = exc.message or ""
+    body_msg = envelope.message if envelope and envelope.message else _extract_body_message(exc.body)
+    if body_msg:
+        detail = f"{detail}: {body_msg}" if detail else body_msg
+    extras = _webmessage_detail_lines(envelope) if envelope else []
+    # Render the Rich conflict table BEFORE calling `_render` — the latter is
+    # a `NoReturn` sys.exit wrapper, so nothing after it executes.
+    if envelope:
+        rows = envelope.conflict_rows()
+        if rows:
+            from dhis2w_core.cli_output import render_conflicts  # noqa: PLC0415 — lazy for the cheap-happy-path
+
+            render_conflicts(rows)
+    _render(f"DHIS2 API error ({exc.status_code})", detail or "(no further detail)", extras=extras)
+
+
+def _webmessage_detail_lines(envelope: WebMessageResponse) -> list[str]:
+    """Format the import-count + rejected-indexes summary lines for end-user output.
+
+    Conflicts themselves render separately as a Rich table via
+    `render_conflicts(envelope.conflict_rows())` — this function handles
+    only the one-line summary bits DHIS2 tucks under `response.*`.
+    """
+    lines: list[str] = []
+    counts = envelope.import_count()
+    if counts is not None and any((counts.imported, counts.updated, counts.ignored, counts.deleted)):
+        lines.append(
+            f"import_count: imported={counts.imported} updated={counts.updated} "
+            f"ignored={counts.ignored} deleted={counts.deleted}"
+        )
+    rejected = envelope.rejected_indexes()
+    if rejected:
+        lines.append(f"rejected_indexes: {rejected}")
+    return lines
+
+
+def _render(label: str, message: str, hint: list[str] | None = None, extras: list[str] | None = None) -> NoReturn:
+    """Print `label: message` + optional extras + optional hint block to stderr and exit 1."""
+    typer.secho(f"{label}: {message}", err=True, fg=typer.colors.RED)
+    if extras:
+        for line in extras:
+            typer.echo(line, err=True)
+    if hint:
+        typer.echo("", err=True)
+        typer.echo("hint:", err=True)
+        for line in hint:
+            typer.echo(f"  {line}", err=True)
+    sys.exit(1)
+
+
+def _extract_body_message(body: object) -> str | None:
+    """Pull a useful error message out of the DHIS2 JSON body, if present."""
+    if isinstance(body, dict):
+        message = body.get("message")
+        if isinstance(message, str) and message:
+            return message
+    return None

dhis2w_core-0.5.1/src/dhis2w_core/cli_output.py

@@ -0,0 +1,339 @@
+"""Shared CLI output helpers.
+
+Two layers:
+
+- **WebMessage rendering** — `render_webmessage` picks the right one-liner
+  for every DHIS2 write response (ImportSummary, ObjectReport,
+  JobConfiguration). Same hook across every plugin's write commands.
+- **Detail / list rendering** — `render_detail` and `render_list` are the
+  standard shapes every `get` / `list` output uses. Single source of truth
+  for Rich styling, reference formatting, and truthy cells so every
+  plugin's output looks and feels the same.
+
+Convention across all plugins:
+
+- Default output is a Rich table — bold title, bold-cyan labels, plain
+  values. References render as `"name (id)"` via `format_ref`; lists
+  render as `", ".join(format_ref(x) for x in values)` via `format_reflist`
+  with a "... +N more" tail past the preview limit.
+- Raw JSON is a global mode — the root CLI accepts `--json` once
+  (`dhis2 --json metadata get ...`) and stores it in `JSON_OUTPUT`.
+  Every plugin checks `is_json_output()` to decide whether to emit
+  `model_dump_json(indent=2, exclude_none=True)` instead of a Rich table.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable
+from contextvars import ContextVar
+from typing import Any
+
+import typer
+from dhis2w_client import ConflictRow, WebMessageResponse
+from pydantic import BaseModel, ConfigDict
+from rich.console import Console
+from rich.table import Table
+
+_console = Console()
+
+
+JSON_OUTPUT: ContextVar[bool] = ContextVar("dhis2_json_output", default=False)
+"""Global toggle set by the CLI root callback when `--json` is passed.
+
+Plugins read it via `is_json_output()` instead of declaring a per-command
+flag. ContextVar (rather than a module global) so test fixtures can scope
+the toggle with `JSON_OUTPUT.set(True)` + reset tokens without leaking
+across tests.
+"""
+
+
+def is_json_output() -> bool:
+    """True when the current invocation was launched with `--json`."""
+    return JSON_OUTPUT.get()
+
+
+def render_webmessage(
+    envelope: WebMessageResponse,
+    *,
+    as_json: bool | None = None,
+    action: str = "",
+    max_conflicts: int = 25,
+) -> None:
+    """Print one line describing `envelope`, or the full JSON when `--json` is set.
+
+    `action` labels the user intent (`created`, `updated`, `deleted`, `set`,
+    `pushed`). For kickoff envelopes (job configs) the action is ignored —
+    the summary names the job type. For import-summary envelopes the action
+    prefixes the import-count line (`pushed: imported=1 updated=0 ...`).
+
+    When the envelope carries conflicts / error reports (either
+    `response.conflicts[]` from data-value imports or
+    `response.typeReports[*].objectReports[*].errorReports[*]` from
+    metadata imports), renders a Rich table of the first `max_conflicts`
+    rows grouped by resource + errorCode. Pass `max_conflicts=0` to suppress
+    the table (for callers that render elsewhere).
+
+    `as_json` is normally `None` — the helper reads the global `JSON_OUTPUT`
+    contextvar set by the CLI root callback. Pass an explicit `bool` only
+    when a caller needs to override the global (e.g. a refresh-status action
+    that always renders human output regardless of the user's `--json`).
+    """
+    if is_json_output() if as_json is None else as_json:
+        typer.echo(envelope.model_dump_json(indent=2, exclude_none=True))
+        return
+
+    ref = envelope.task_ref()
+    if ref is not None:
+        job_type, task_uid = ref
+        typer.echo(f"kicked off {job_type} (task={task_uid})")
+        typer.echo(f"  poll:  dhis2 maintenance task watch {job_type} {task_uid}")
+        typer.echo("  or re-run with --watch / -w to stream progress")
+        return
+
+    counts = envelope.import_count()
+    if counts is not None and any((counts.imported, counts.updated, counts.ignored, counts.deleted)):
+        prefix = f"{action}: " if action else ""
+        typer.echo(
+            f"{prefix}imported={counts.imported} updated={counts.updated} "
+            f"ignored={counts.ignored} deleted={counts.deleted}"
+        )
+    else:
+        uid = envelope.created_uid
+        if uid:
+            verb = action or "ok"
+            typer.echo(f"{verb} {uid}")
+        else:
+            message = envelope.message or envelope.httpStatus or "ok"
+            typer.echo(f"{action or 'ok'}: {message}" if action else message)
+
+    if max_conflicts > 0:
+        rows = envelope.conflict_rows()
+        if rows:
+            render_conflicts(rows, limit=max_conflicts)
+
+
+def render_conflicts(rows: list[ConflictRow], *, limit: int = 25, console: Console | None = None) -> None:
+    """Render a list of `ConflictRow` as a Rich table grouped by resource + errorCode.
+
+    Useful both on metadata imports (each `ErrorReport` becomes a row) and
+    on data-value / tracker imports (each `conflicts[]` entry becomes a row).
+    Caller gets one scannable table regardless of where DHIS2 tucked the
+    errors on the wire.
+
+    `limit` caps the rendered rows — conflicts past the cap render as a
+    `... +N more` footer line so the terminal doesn't drown on 500-conflict
+    imports. Pass `limit=0` for "show everything".
+    """
+    if not rows:
+        return
+    target = console or _console
+    total = len(rows)
+    # Newest information first: show rows with an errorCode / resource before
+    # the "bare message" ones, then stable-sort so same-resource + same-code
+    # rows cluster together.
+    rows = sorted(rows, key=lambda r: (r.resource or "~", r.error_code or "~", r.property or "", r.uid or ""))
+    visible = rows if limit <= 0 else rows[:limit]
+
+    table = Table(
+        title=f"[red]conflicts[/red] ({total})",
+        title_style="bold",
+        pad_edge=False,
+        expand=False,
+    )
+    table.add_column("resource", style="cyan", overflow="fold")
+    table.add_column("uid", style="dim", overflow="fold")
+    table.add_column("property", overflow="fold")
+    table.add_column("value", overflow="fold")
+    table.add_column("code", style="yellow", overflow="fold")
+    table.add_column("message", overflow="fold")
+
+    for row in visible:
+        table.add_row(
+            row.resource or "-",
+            row.uid or "-",
+            row.property or "-",
+            (row.value or "-")[:80],
+            row.error_code or "-",
+            (row.message or "-")[:120],
+        )
+    target.print(table)
+    if limit > 0 and total > limit:
+        target.print(f"[dim]... +{total - limit} more conflict{'s' if total - limit != 1 else ''}[/dim]")
+
+
+# ---------------------------------------------------------------------------
+# Detail + list rendering
+# ---------------------------------------------------------------------------
+
+
+_REF_ID_KEYS = ("id", "uid")
+_REF_LABEL_KEYS = ("displayName", "name", "code", "username")
+
+
+def format_ref(value: Any) -> str:
+    """Render any DHIS2-style reference as the best human form.
+
+    Precedence:
+      1. `"name (id)"` when both name-ish and id-ish are present.
+      2. Just the name.
+      3. Just the UID.
+      4. `str(value)` fallback.
+      5. `'-'` on None.
+
+    Accepts pydantic models, plain dicts, and bare strings. Strings pass
+    through unchanged (they're already "name" or already a UID).
+    """
+    if value is None:
+        return "-"
+    if isinstance(value, str):
+        return value or "-"
+    if isinstance(value, dict):
+        label = next((value[k] for k in _REF_LABEL_KEYS if value.get(k)), None)
+        uid = next((value[k] for k in _REF_ID_KEYS if value.get(k)), None)
+    else:
+        label = next((getattr(value, k, None) for k in _REF_LABEL_KEYS if getattr(value, k, None)), None)
+        uid = next((getattr(value, k, None) for k in _REF_ID_KEYS if getattr(value, k, None)), None)
+    if label and uid:
+        return f"{label} [dim]({uid})[/dim]"
+    if label:
+        return str(label)
+    if uid:
+        return str(uid)
+    return str(value)
+
+
+def format_reflist(values: Iterable[Any] | None, *, limit: int = 10, separator: str = ", ") -> str:
+    """Render a list of references as comma-separated `name (id)` with a `+N more` tail."""
+    if not values:
+        return "-"
+    items = list(values)
+    preview = [format_ref(v) for v in items[:limit]]
+    tail = f" [dim]+{len(items) - limit} more[/dim]" if len(items) > limit else ""
+    return separator.join(preview) + tail
+
+
+def format_bool(value: Any, *, true_label: str = "yes", false_label: str = "no") -> str:
+    """Render a boolean as a plain label; `None` collapses to `-`."""
+    if value is None:
+        return "-"
+    return true_label if bool(value) else false_label
+
+
+def format_disabled(value: Any) -> str:
+    """`disabled`-style booleans: red when true, dim when false, `-` when None."""
+    if value is None:
+        return "-"
+    return "[red]yes[/red]" if value else "[green]no[/green]"
+
+
+def format_access_string(access: str | None) -> str:
+    """Render an 8-char DHIS2 access string — highlight the meaningful chars."""
+    if not access:
+        return "[dim]--------[/dim]"
+    return f"[bold]{access}[/bold]"
+
+
+class DetailRow(BaseModel):
+    """One line of a key/value detail table."""
+
+    model_config = ConfigDict(frozen=True)
+
+    label: str
+    value: str
+    label_style: str = "bold cyan"
+
+    def __init__(self, label: str, value: str, *, label_style: str = "bold cyan") -> None:
+        """Accept positional `(label, value)` for terse call sites in plugin CLIs."""
+        super().__init__(label=label, value=value, label_style=label_style)
+
+
+def render_detail(title: str, rows: Iterable[DetailRow | tuple[str, Any]], *, console: Console | None = None) -> None:
+    """Render a two-column key/value detail table.
+
+    Rows are either `DetailRow` or `(label, value)` tuples. Value is
+    stringified as-is (already-formatted Rich markup passes through); wrap
+    your own values with `format_ref` / `format_reflist` / `format_bool`
+    etc. before passing them in.
+    """
+    table = Table(title=title, show_header=False, title_style="bold", pad_edge=False, expand=False)
+    table.add_column("field", style="bold cyan", no_wrap=True)
+    table.add_column("value", overflow="fold")
+    for row in rows:
+        if isinstance(row, DetailRow):
+            table.add_row(row.label, row.value)
+        else:
+            label, value = row
+            table.add_row(label, _coerce_cell(value))
+    (console or _console).print(table)
+
+
+class ColumnSpec(BaseModel):
+    """Declarative spec for a list-table column.
+
+    `key` is the dict key to pull from each row. `formatter` optionally
+    transforms the raw cell value into the displayed string (defaults to
+    `format_ref`). `style` sets a rich style (e.g. `'cyan'` for an ID
+    column, `'dim'` for timestamps).
+    """
+
+    model_config = ConfigDict(frozen=True, arbitrary_types_allowed=True)
+
+    label: str
+    key: str
+    formatter: Callable[[Any], str] | None = None
+    style: str | None = None
+    no_wrap: bool = False
+
+    def __init__(
+        self,
+        label: str,
+        key: str,
+        *,
+        formatter: Callable[[Any], str] | None = None,
+        style: str | None = None,
+        no_wrap: bool = False,
+    ) -> None:
+        """Accept positional `(label, key)` for terse call sites in plugin CLIs."""
+        super().__init__(label=label, key=key, formatter=formatter, style=style, no_wrap=no_wrap)
+
+
+def render_list(
+    title: str,
+    rows: Iterable[dict[str, Any]],
+    columns: Iterable[ColumnSpec],
+    *,
+    console: Console | None = None,
+) -> None:
+    """Render a list of rows as a rich Table with typed column formatting.
+
+    Every column's value passes through `format_ref` by default so references
+    (dicts with `id`/`name` etc.) render cleanly, not as raw JSON blobs.
+    """
+    rows_list = list(rows)
+    cols = list(columns)
+    table = Table(title=f"{title} ({len(rows_list)})", title_style="bold", pad_edge=False, expand=False)
+    for spec in cols:
+        table.add_column(spec.label, style=spec.style, no_wrap=spec.no_wrap, overflow="fold")
+    for row in rows_list:
+        cells = []
+        for spec in cols:
+            raw = row.get(spec.key)
+            formatter = spec.formatter or format_ref
+            cells.append(formatter(raw))
+        table.add_row(*cells)
+    (console or _console).print(table)
+
+
+def _coerce_cell(value: Any) -> str:
+    """Best-effort stringifier used by `render_detail`."""
+    if value is None:
+        return "-"
+    if isinstance(value, bool):
+        return format_bool(value)
+    if isinstance(value, str):
+        return value or "-"
+    if isinstance(value, (list, tuple)):
+        return format_reflist(value)
+    if isinstance(value, dict):
+        return format_ref(value)
+    return str(value)

dhis2w_core-0.5.1/src/dhis2w_core/cli_task_watch.py

@@ -0,0 +1,63 @@
+"""Shared CLI helper — render a DHIS2 background-task's notifications with Rich.
+
+Used by every `--watch` flag across plugins (analytics refresh, maintenance
+dataintegrity run, future async ops). Pointed at one `(job_type, task_uid)`,
+reads the `/api/system/tasks/{type}/{uid}` feed via
+`maintenance.service.watch_task` and renders each notification as a coloured
+line (by level) above an animated spinner showing total elapsed time.
+Writes to stderr so stdout stays usable for piping the job-kickoff JSON.
+Exits on the first `completed=true` row; raises `TimeoutError` if `timeout`
+elapses first.
+"""
+
+from __future__ import annotations
+
+from rich.progress import Progress, SpinnerColumn, TextColumn, TimeElapsedColumn
+
+from dhis2w_core.plugins.maintenance import service as maintenance_service
+from dhis2w_core.profile import Profile
+from dhis2w_core.rich_console import STDERR_CONSOLE
+
+_LEVEL_STYLE: dict[str, str] = {
+    "INFO": "cyan",
+    "WARN": "yellow",
+    "WARNING": "yellow",
+    "ERROR": "red bold",
+    "LOOP": "magenta",
+    "DEBUG": "dim",
+}
+
+
+async def stream_task_to_stdout(
+    profile: Profile,
+    job_type: str,
+    task_uid: str,
+    *,
+    interval: float = 2.0,
+    timeout: float | None = 600.0,
+) -> None:
+    """Poll `/api/system/tasks/{job_type}/{task_uid}` and render with Rich."""
+    STDERR_CONSOLE.print(f"[bold cyan]watching[/] [bold]{job_type}/{task_uid}[/]  [dim]interval={interval}s[/]")
+    final_message: str | None = None
+    with Progress(
+        SpinnerColumn(),
+        TextColumn("[progress.description]{task.description}"),
+        TimeElapsedColumn(),
+        console=STDERR_CONSOLE,
+        transient=True,
+    ) as progress:
+        task_row = progress.add_task("polling...", total=None)
+        async for notification in maintenance_service.watch_task(
+            profile, job_type, task_uid, interval=interval, timeout=timeout
+        ):
+            level = (notification.level or "INFO").upper()
+            style = _LEVEL_STYLE.get(level, "white")
+            marker = "[x]" if notification.completed else "[ ]"
+            message = notification.message or "-"
+            progress.console.print(f"  {level:<5} {marker} {message}", style=style, markup=False)
+            progress.update(task_row, description=message)
+            if notification.completed:
+                final_message = message
+                break
+    summary = final_message or "task completed"
+    STDERR_CONSOLE.print(f"[bold green]done[/]  [dim]{job_type}/{task_uid}[/]  {summary}")