dlboard-client 0.2.0__py3-none-any.whl

dlboard/__init__.py

@@ -0,0 +1 @@
+"""DLBoard main entrypoint."""

dlboard/_batching.py

@@ -0,0 +1,153 @@
+"""
+Drain a queue into batches and ship each one somewhere that can fail.
+
+Shared by the client's metric/artifact shipping processes (`dlboard_logger.py`) and every blob
+artifact store's ref-ingest thread (`plugins/data_stores/_blob_store.py`) -- both batch items off a
+queue towards a destination that can fail transiently (a server, a locked database), and both must
+never lose a batch to a failure that a retry would have survived.
+"""
+
+from __future__ import annotations
+
+import logging
+import random
+import time
+from queue import Empty
+from typing import TYPE_CHECKING, NamedTuple, Protocol, TypeVar
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+    from multiprocessing.synchronize import Event as MPEvent
+
+_log = logging.getLogger(__name__)
+
+T = TypeVar("T")
+"""Pre-3.12 `TypeVar` style (the client's floor is 3.10): the kind of item `ship_batches` moves."""
+
+_T_co = TypeVar("_T_co", covariant=True)
+"""`Receiver`'s own type parameter -- covariant, since it only ever appears in a return position."""
+
+_MAX_BACKOFF_FACTOR: int = 6
+"""Caps retry backoff at `wait_sec * 2**6` (64x) -- a dead server shouldn't make the next retry wait
+arbitrarily long, just long enough to stop hammering it."""
+
+_JITTER_FRACTION: float = 0.25
+"""+/- this fraction of the computed backoff, so many shipping processes retrying the same outage
+don't all land on the server in lockstep."""
+
+
+class BatchParams(NamedTuple):
+    """How `ship_batches` batches, plus the events it reports through."""
+
+    flush_size: int
+    wait_sec: float
+    ready: MPEvent
+    flushed: MPEvent
+
+
+class Receiver(Protocol[_T_co]):
+    """The one queue method `ship_batches` needs -- both `multiprocessing` and `queue` queues have it."""
+
+    def get(self, block: bool = True, timeout: float | None = None) -> _T_co: ...  # noqa: FBT001, FBT002
+
+
+def _split_oversized(
+    ship: Callable[[list[T]], None],
+    batch: list[T],
+    *,
+    is_permanent: Callable[[Exception], bool],
+    is_oversized: Callable[[Exception], bool],
+) -> list[T]:
+    """
+    Ship `batch` in two halves, recursing into a half that's still too large, down to one item each.
+
+    Returns whatever's left unshipped: a permanently-rejected chunk is dropped (and so absent from
+    the result), but one that fails for some other transient reason comes back in it, for
+    `ship_batches` to retry (at its own pace, with backoff) on a later pass -- never lost, and never
+    re-sent on top of a chunk that already landed. A chunk of exactly one item that's still too
+    large has nothing left to split into, so it's treated as permanent either way: resending the
+    same single oversized item can never succeed.
+    """
+    mid = len(batch) // 2
+    leftover: list[T] = []
+    for chunk in (batch[:mid], batch[mid:]):
+        try:
+            ship(chunk)
+        except Exception as exc:  # noqa: BLE001 -- nothing may kill the shipping loop
+            if is_oversized(exc) and len(chunk) > 1:
+                leftover.extend(
+                    _split_oversized(ship, chunk, is_permanent=is_permanent, is_oversized=is_oversized)
+                )
+            elif is_permanent(exc):
+                _log.exception("A sub-batch of %s was rejected, dropping it", len(chunk))
+            else:
+                leftover.extend(chunk)  # transient; retry (with backoff) on a later pass
+    return leftover
+
+
+def ship_batches(
+    q: Receiver[T | None],
+    ship: Callable[[list[T]], None],
+    params: BatchParams,
+    *,
+    is_permanent: Callable[[Exception], bool],
+    is_oversized: Callable[[Exception], bool] = lambda _exc: False,
+) -> None:
+    """
+    Forever drain `q` into batches, shipping one once it's full, `wait_sec` old, or a flush asks for it.
+
+    A batch whose failure `is_permanent` is dropped: resending it can never succeed, and keeping it
+    would wedge every later item behind it. A batch whose failure `is_oversized` is instead split in
+    half and each half attempted once right away (`_split_oversized`) -- resending the exact same
+    oversized batch could never succeed either, but a batch that only grew this large because the
+    server was briefly unreachable shouldn't be dropped just because it doesn't fit in one request
+    once it's reachable again. Any other failure is transient -- the batch is kept, keeps growing
+    with whatever arrives meanwhile, and is retried after an exponentially growing backoff (reset
+    the moment a batch ships successfully) rather than hammering a server that's still down. A
+    `None` queued in place of an item requests a flush, acknowledged (`params.flushed`) only once
+    everything queued before it is gone. Returns once `q` itself is closed (e.g. at interpreter
+    shutdown) -- nothing more can ever arrive through it.
+    """
+    params.ready.set()
+    batch: list[T] = []
+    flush_requested = False
+    last_attempt = time.perf_counter()
+    consecutive_failures = 0
+    while True:
+        try:
+            item = q.get(timeout=params.wait_sec / 10)
+            if item is None:
+                flush_requested = True
+            else:
+                batch.append(item)
+        except Empty:
+            pass
+        except (OSError, ValueError):  # a closed `multiprocessing` queue raises one or the other
+            return
+        due = flush_requested or len(batch) >= params.flush_size
+        if batch and (due or time.perf_counter() - last_attempt > params.wait_sec):
+            try:
+                ship(batch)
+                batch = []
+                consecutive_failures = 0
+            except Exception as exc:  # noqa: BLE001 -- nothing may kill the shipping loop
+                if is_oversized(exc) and len(batch) > 1:
+                    _log.warning("A batch of %s was too large for one request, splitting it", len(batch))
+                    batch = _split_oversized(
+                        ship, batch, is_permanent=is_permanent, is_oversized=is_oversized
+                    )
+                    consecutive_failures = 0
+                elif is_permanent(exc):
+                    _log.exception("A batch of %s was rejected, dropping it", len(batch))
+                    batch = []
+                    consecutive_failures = 0
+                else:
+                    _log.exception("Failed to ship a batch of %s, retrying", len(batch))
+                    backoff = params.wait_sec * 2 ** min(consecutive_failures, _MAX_BACKOFF_FACTOR)
+                    jitter = backoff * _JITTER_FRACTION
+                    time.sleep(backoff + random.uniform(-jitter, jitter))
+                    consecutive_failures += 1
+            last_attempt = time.perf_counter()
+        if flush_requested and not batch:
+            flush_requested = False
+            params.flushed.set()

dlboard/_compat.py

@@ -0,0 +1,31 @@
+"""
+Backports for stdlib `typing`/`enum` members not available on the client's floor (Python 3.10).
+
+Nothing here is dlboard-specific; it exists only because the client supports 3.10+ while the
+syntax/stdlib members below landed later. Every model/client module that needs one of these
+imports it from here instead of `enum` directly, so there's exactly one place that cares which
+Python version is actually running.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    # Pyright always sees the real `enum.StrEnum` -- this repo's own dev/CI env always has 3.12+.
+    # The try/except below is the runtime-only fallback, for an actual 3.10/3.11 interpreter.
+    from enum import StrEnum
+else:
+    try:
+        from enum import StrEnum
+    except ImportError:  # Python < 3.11 (PEP 663 landed in 3.11)
+        from enum import Enum
+
+        class StrEnum(str, Enum):
+            """A `str`-valued `Enum` whose `str()` is its value, not `ClassName.MEMBER`."""
+
+            def __str__(self) -> str:
+                return str(self.value)
+
+
+__all__ = ["StrEnum"]

dlboard/_identity.py

@@ -0,0 +1,48 @@
+"""
+Best-effort resolution of "who is running this" for attribution purposes.
+
+This is an identity helper, not authentication -- nothing here is a security boundary, and nothing
+here proves a caller actually is who they claim. It exists so a local, single-user dlboard install
+can attribute projects/experiments/runs to *someone* with zero configuration, the same way `git`
+picks up `user.name` from the environment. Used by both the client (`dlboard.client`, to label
+what it logs) and the server (schema migrations, to pick a name for the one-time bootstrap admin).
+"""
+
+from __future__ import annotations
+
+import getpass
+
+from pydantic_settings import BaseSettings
+from structlog.stdlib import get_logger
+
+_log = get_logger(__name__)
+
+ANONYMOUS: str = "anonymous"
+
+
+class _IdentitySettings(BaseSettings):
+    """Reads the `DLBOARD_USER` env var `resolve_username` checks first."""
+
+    dlboard_user: str = ""
+
+
+def resolve_username() -> str:
+    """
+    Resolve a username via a best-effort chain: the `DLBOARD_USER` env var, then the OS login name, then `"anonymous"`.
+
+    Every step is wrapped so a failure (e.g. `getpass.getuser()` raising in a sandboxed container
+    with no passwd entry) falls through to the next step instead of raising.
+    """
+    env_value = _IdentitySettings().dlboard_user.strip()
+    if env_value:
+        return env_value
+
+    try:
+        os_username = getpass.getuser().strip()
+    except Exception:  # noqa: BLE001
+        _log.debug("Could not resolve an OS username, falling back to %s", ANONYMOUS)
+    else:
+        if os_username:
+            return os_username
+
+    return ANONYMOUS

dlboard/_mp_context.py

@@ -0,0 +1,15 @@
+"""
+Shared multiprocessing context for dlboard's background worker processes.
+
+`DLBoardLogger` (client-side metric/artifact shipping) and `BlobArtifactStore` (server-side blob
+writes) each spawn a worker process off a `multiprocessing.Queue`; both need the same "spawn"
+context (never "fork", which can deadlock a process that already has threads running -- both of
+these do, e.g. Flask's/Dash's request-handling threads on the server side). Sharing one context
+instance keeps that choice in exactly one place instead of two independent literal `"spawn"` calls.
+"""
+
+from __future__ import annotations
+
+from multiprocessing import get_context
+
+SPAWN_CONTEXT = get_context("spawn")

dlboard/_version.py

@@ -0,0 +1,17 @@
+"""
+The single source of dlboard's version.
+
+Both `client/pyproject.toml` and `server/pyproject.toml` read `__version__` from here via hatch's
+dynamic `[tool.hatch.version]` (see their own `path` setting), instead of each hardcoding its own
+`version` field -- which is how the two distributions drifted out of lockstep before this existed:
+nothing kept `dlboard-client`'s version and `dlboard`'s `dlboard-client==...` pin pointed at the same
+release. Bump this one file to cut a release; neither `pyproject.toml`'s `version` is ever edited
+directly.
+
+Also read at runtime -- `Identity.server_version` (see `dlboard._wire`) is what a client's `whoami`
+handshake actually sees.
+"""
+
+# No type annotation -- hatchling's default `regex` version source (`[tool.hatch.version]` in both
+# `pyproject.toml`s) matches `__version__ *= *"..."` literally and wouldn't see this past a `: str`.
+__version__ = "0.2.0"

dlboard/_wire.py

@@ -0,0 +1,111 @@
+"""
+The REST wire contract: path shapes and request/response bodies, shared by client and server.
+
+Neither `dlboard.client` nor `dlboard.plugins.backend.basic_rest_backend` (the server side) is a
+parent package of the other, so this lives at the top level rather than inside either -- importing
+a submodule always runs its parent package's `__init__.py` first, and the server importing
+anything nested under `dlboard.client` would mean importing the server needs whatever
+`dlboard/client/__init__.py` eagerly imports (`DLBoardLogger`, and so `torch`), for a module that
+never actually touches either. Pure `pydantic`/`typing` -- no heavy dependency on either side.
+"""
+
+from __future__ import annotations
+
+from typing import Final
+
+from pydantic import BaseModel
+
+from dlboard import models
+from dlboard._compat import StrEnum
+
+API_VERSION: Final = 1
+"""
+The REST API major this version of dlboard speaks (see `Identity.api_version`). Bumped only for a
+breaking change to an existing path's request/response shape or status-code semantics -- an
+additive change (a new optional field, a new path) doesn't need one, since `extra="ignore"` on
+every model here is what makes those safe to skip across.
+"""
+
+API_PREFIX: Final = f"api/v{API_VERSION}"
+"""Every REST path lives under this, so a path never again depends on a Python class's `__name__`
+the way it used to -- see `Resource`."""
+
+METADATA_PART_SUFFIX: Final = ".json"
+"""Appended to an artifact file's multipart part name to name the part carrying its `NewArtifact` JSON."""
+
+WHOAMI_PATH: Final = f"{API_PREFIX}/whoami"
+
+DLBOARD_USER_HEADER: Final = "X-Dlboard-User"
+"""Carries the client's best-effort identity (see `dlboard._identity.resolve_username`).
+
+Never trusted blindly -- a missing/blank header falls back to the same best-effort resolution the
+client itself falls back to. This is attribution, not authentication: nothing here proves a caller
+actually is who the header claims. Read server-side by `dlboard.plugins.auth.anonymous`, the one
+provider that doesn't verify identity another way.
+"""
+
+DLBOARD_CLIENT_VERSION_HEADER: Final = "X-Dlboard-Client-Version"
+"""The installed `dlboard` client distribution's version -- attribution only, like `DLBOARD_USER_HEADER`;
+the server doesn't gate on it. See `Identity.server_version`/`api_version` for the direction a
+client actually acts on."""
+
+
+class Resource(StrEnum):
+    """
+    Every REST resource's path segment under `API_PREFIX`.
+
+    The plural noun shared by a resource's "create" path (`.../<resource>`) and its "one existing
+    entity" path (`.../<resource>/<id>`). Spelled out as literal strings, not derived from a
+    model's `__name__`: a path changing because a model got renamed in a refactor would be a
+    breaking change nobody intended.
+    """
+
+    PROJECTS = "projects"
+    EXPERIMENTS = "experiments"
+    RUNS = "runs"
+    ARTIFACTS = "artifacts"
+    ARTIFACT_LINKS = "artifact-links"
+    METRICS = "metrics"
+    HYPERPARAMS = "hyperparams"
+
+
+def create_path(resource: Resource, base_url: str = "/") -> str:
+    """The REST path to create a new `resource`, e.g. `api/v1/projects`."""
+    return f"{base_url}/{API_PREFIX}/{resource}".strip("/")
+
+
+def entity_path(resource: Resource, entity_id: str = "<int:entity_id>", base_url: str = "/") -> str:
+    """The REST path for an action on one existing `resource`, e.g. `api/v1/projects/<id>`."""
+    return f"{base_url}/{API_PREFIX}/{resource}/{entity_id}".strip("/")
+
+
+def get_or_create_path(resource: Resource, base_url: str = "/") -> str:
+    """The REST path for the get-or-create-by-name idiom, e.g. `api/v1/projects/get-or-create`."""
+    return f"{base_url}/{API_PREFIX}/{resource}/get-or-create".strip("/")
+
+
+class Identity(BaseModel, frozen=True, extra="ignore"):
+    """Who the server authenticated a request as, plus enough to let a client self-diagnose -- what `whoami` returns."""
+
+    id: int
+    username: str
+    server_version: str
+    """The running server's `dlboard` version -- e.g. for an error message, never parsed by the client."""
+    api_version: int = API_VERSION
+    """The REST API major this server speaks. A client that doesn't recognize it should refuse to
+    proceed rather than guess -- see `DLBoardLogger.__init__`."""
+
+
+class GetOrCreateProject(BaseModel, frozen=True, extra="ignore"):
+    """Request body: find a project by name, creating it (with `description`) if it's missing."""
+
+    name: str
+    description: str = ""
+
+
+class GetOrCreateExperiment(BaseModel, frozen=True, extra="ignore"):
+    """Request body: find an experiment by name within a project, creating it if it's missing."""
+
+    project_id: int
+    name: str = "default"
+    source: models.ExperimentSource | None = None

dlboard/client/__init__.py

@@ -0,0 +1,10 @@
+"""
+Client-side objects in dlboard for use with training.
+
+No re-exports here on purpose: `dlboard_logger.py` needs `pytorch_lightning` (the `[lightning]`
+extra) at import time, to subclass its `Logger`. Re-exporting `DLBoardLogger` from this package's
+own `__init__.py` would mean every client install needs lightning just to reach anything else
+under `dlboard.client` (or `dlboard.client.artifacts`) -- importing any submodule always runs its
+parent's `__init__.py` first. Import it from its own module instead:
+`from dlboard.client.dlboard_logger import DLBoardLogger`.
+"""