labelpull 0.1.0__py3-none-any.whl

labelpull/__init__.py

@@ -0,0 +1,44 @@
+"""labelpull: pull the latest Labelbox annotations into a tidy table.
+
+The Labelbox SDK exports a project's labels as nested, ontology-shaped JSON.
+labelpull is the thin layer the SDK lacks: a generic flattener
+(:func:`~labelpull.core.flatten`) plus the correctness logic (latest-label
+selection, status normalization) and a one-command CLI on top.
+"""
+
+from __future__ import annotations
+
+from labelpull.adapters import (
+    ADAPTERS,
+    Adapter,
+    GenericAdapter,
+    SpeciesAdapter,
+    write_csv,
+)
+from labelpull.core import (
+    WORKFLOW_STATUSES,
+    FeatureRow,
+    Summary,
+    export,
+    flatten,
+    read_export_file,
+    summarize,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "ADAPTERS",
+    "WORKFLOW_STATUSES",
+    "Adapter",
+    "FeatureRow",
+    "GenericAdapter",
+    "SpeciesAdapter",
+    "Summary",
+    "__version__",
+    "export",
+    "flatten",
+    "read_export_file",
+    "summarize",
+    "write_csv",
+]

labelpull/adapters.py

@@ -0,0 +1,110 @@
+"""Adapters: collapse ontology-agnostic :class:`FeatureRow` rows into a shape.
+
+The generic path writes ``FeatureRow`` rows straight to a long-format CSV that
+any project can read. An adapter narrows that to a project-specific wide record.
+:class:`SpeciesAdapter` is the reference implementation, reproducing
+speciesfirst's ``global_key,taxon,organs,labeled_by,workflow_status`` pull CSV
+from the generic rows, so the engine has exactly one parser.
+"""
+
+from __future__ import annotations
+
+import csv
+from collections import OrderedDict
+from collections.abc import Iterable, Sequence
+from pathlib import Path
+from typing import Protocol, runtime_checkable
+
+from labelpull.core import FeatureRow
+
+
+@runtime_checkable
+class Adapter(Protocol):
+    """Map flattened features to named columns plus the rows to write."""
+
+    columns: Sequence[str]
+
+    def rows(self, features: Iterable[FeatureRow]) -> Iterable[Sequence[str]]: ...
+
+
+class GenericAdapter:
+    """One CSV row per feature: the ontology-agnostic long format."""
+
+    columns: Sequence[str] = (
+        "global_key",
+        "data_row_id",
+        "feature_kind",
+        "feature_name",
+        "value",
+        "workflow_status",
+        "labeled_by",
+        "created_at",
+        "parent_feature_id",
+    )
+
+    def rows(self, features: Iterable[FeatureRow]) -> Iterable[Sequence[str]]:
+        for f in features:
+            yield (
+                f.global_key,
+                f.data_row_id,
+                f.feature_kind,
+                f.feature_name,
+                f.value,
+                f.workflow_status or "",
+                f.labeled_by or "",
+                f.created_at or "",
+                f.parent_feature_id,
+            )
+
+
+class SpeciesAdapter:
+    """One row per ``global_key``: reproduces speciesfirst's pull CSV.
+
+    ``taxon`` is the ``Taxon`` single-select radio; ``organs`` is the ``Organs``
+    checklist (``;``-joined). A reached-and-labelled row with neither still
+    appears (seeded by the ``label`` sentinel), matching speciesfirst's "reached
+    but unlabelled yields ``taxon=''``" behaviour. Insertion order follows the
+    export stream.
+    """
+
+    columns: Sequence[str] = ("global_key", "taxon", "organs", "labeled_by", "workflow_status")
+    taxon_feature = "Taxon"
+    organs_feature = "Organs"
+
+    def rows(self, features: Iterable[FeatureRow]) -> Iterable[Sequence[str]]:
+        by_key: OrderedDict[str, dict[str, str]] = OrderedDict()
+        for f in features:
+            rec = by_key.setdefault(
+                f.global_key,
+                {"taxon": "", "organs": "", "labeled_by": "", "workflow_status": ""},
+            )
+            if f.labeled_by:
+                rec["labeled_by"] = f.labeled_by
+            if f.workflow_status:
+                rec["workflow_status"] = f.workflow_status
+            if f.feature_kind == "radio" and f.feature_name == self.taxon_feature and f.value:
+                rec["taxon"] = f.value
+            elif f.feature_kind == "checklist" and f.feature_name == self.organs_feature:
+                rec["organs"] = f.value
+        for global_key, rec in by_key.items():
+            yield (
+                global_key,
+                rec["taxon"],
+                rec["organs"],
+                rec["labeled_by"],
+                rec["workflow_status"],
+            )
+
+
+ADAPTERS: dict[str, type] = {"generic": GenericAdapter, "species": SpeciesAdapter}
+
+
+def write_csv(path: str | Path, adapter: Adapter, features: Iterable[FeatureRow]) -> Path:
+    """Write ``features`` through ``adapter`` to ``path`` (parents created)."""
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("w", newline="") as f:
+        writer = csv.writer(f)
+        writer.writerow(adapter.columns)
+        writer.writerows(adapter.rows(features))
+    return path

labelpull/cli.py

@@ -0,0 +1,101 @@
+"""``labelpull`` CLI: pull the latest Labelbox annotations to a tidy CSV.
+
+labelpull pull PROJECT_ID -o labels.csv
+labelpull pull PROJECT_ID --status Done --since 2026-06-01
+labelpull pull PROJECT_ID --schema species -o taxa.csv
+labelpull pull PROJECT_ID --from-export export.ndjson   # offline, no API key
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+
+from labelpull import __version__
+from labelpull.adapters import ADAPTERS, write_csv
+from labelpull.core import (
+    FeatureRow,
+    JsonDict,
+    _created_at,
+    _select_project,
+    flatten,
+    read_export_file,
+    summarize,
+)
+from labelpull.core import export as live_export
+
+app = typer.Typer(add_completion=False, help="Pull the latest Labelbox annotations to CSV.")
+
+
+@app.callback()
+def _main() -> None:
+    """labelpull: pull the latest Labelbox annotations into a tidy table."""
+
+
+@app.command()
+def pull(
+    project_id: str = typer.Argument(..., help="Labelbox project id to export from."),
+    out: Path = typer.Option(
+        Path("pulled_labels.csv"), "--out", "-o", help="Where to write the CSV."
+    ),
+    schema: str = typer.Option(
+        "generic",
+        help="generic = one row per feature (any ontology); "
+        "species = speciesfirst Taxon/Organs wide CSV.",
+    ),
+    status: str | None = typer.Option(
+        None, help="Filter by task-queue stage: ToLabel | InReview | InRework | Done."
+    ),
+    since: str | None = typer.Option(
+        None, help="Keep only rows whose newest label was created on/after this ISO date/time."
+    ),
+    from_export: Path | None = typer.Option(
+        None,
+        exists=True,
+        dir_okay=False,
+        help="Flatten a saved export (JSON/NDJSON) offline instead of the live API.",
+    ),
+    api_key: str | None = typer.Option(None, help="Labelbox API key (else LABELBOX_API_KEY)."),
+) -> None:
+    """Export the latest annotations and flatten them to CSV, with a summary."""
+    if schema not in ADAPTERS:
+        raise typer.BadParameter(f"unknown schema {schema!r}; choose from {sorted(ADAPTERS)}")
+    adapter = ADAPTERS[schema]()
+
+    typer.echo(f"labelpull v{__version__}")
+    if from_export is not None:
+        rows = read_export_file(from_export)
+        if since is not None:
+            rows = [r for r in rows if _row_since(r, project_id, since)]
+        typer.echo(f"  read {len(rows)} rows from {from_export}")
+    else:
+        rows = list(live_export(project_id, status=status, since=since, api_key=api_key))
+        typer.echo(f"  exported {len(rows)} rows from project {project_id}")
+
+    features = [f for r in rows for f in flatten(r, project_id)]
+    _print_summary(rows, features)
+    write_csv(out, adapter, features)
+    typer.echo(f"wrote {schema} CSV: {out}")
+
+
+def _row_since(dr: JsonDict, project_id: str, since: str) -> bool:
+    return _created_at(_select_project(dr, project_id)) >= since
+
+
+def _print_summary(rows: list[JsonDict], features: list[FeatureRow]) -> None:
+    s = summarize(rows, features)
+    typer.echo(
+        f"  {s.n_labelled} labelled / {s.n_data_rows} rows "
+        f"({s.n_reached_unlabelled} reached unlabelled)"
+    )
+    if s.statuses:
+        typer.echo("  status: " + ", ".join(f"{k}={v}" for k, v in sorted(s.statuses.items())))
+    if s.feature_kinds:
+        typer.echo("  kinds:  " + ", ".join(f"{k}={v}" for k, v in sorted(s.feature_kinds.items())))
+    if s.latest_created_at:
+        typer.echo(f"  latest label: {s.latest_created_at}")
+
+
+if __name__ == "__main__":  # pragma: no cover
+    app()

labelpull/core.py

@@ -0,0 +1,285 @@
+"""Ontology-agnostic Labelbox export + flatten.
+
+The Labelbox SDK already exports a project's labels and streams them as deeply
+nested, ontology-shaped JSON. What it does *not* give you is a tabular view, the
+correctness logic to pick the right label when a row was reviewed, or a workflow
+status that is always populated. This module is exactly that thin layer:
+
+* :func:`export` wraps ``project.export(...)`` + ``wait_till_done()`` +
+  ``get_buffered_stream()`` (SDK lazy-imported, so it is optional) and adds a
+  ``since`` filter for "only the latest annotations".
+* :func:`flatten` turns one export row into :class:`FeatureRow` long-format rows,
+  covering *every* feature kind (classifications AND objects) without assuming a
+  particular ontology. It encodes the two traps a hand-written parser gets wrong:
+  selecting the most-recently-created label (a QC-reviewed row carries both the
+  annotator's and the reviewer's label) and normalizing the workflow status.
+* :func:`read_export_file` parses a saved export (UI download or a prior pull) so
+  the same flattener runs offline, no API key required.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from collections.abc import Iterable, Iterator
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, cast
+
+# One export row (and its nested blocks) is arbitrary JSON; alias it for brevity.
+JsonDict = dict[str, Any]
+
+# The task-queue stages ``project.export(filters={"workflow_status": ...})`` accepts.
+WORKFLOW_STATUSES = ("ToLabel", "InReview", "InRework", "Done")
+
+# Geometry keys a localized object may carry in the v7 export, in probe order.
+_GEOMETRY_KINDS = ("bounding_box", "polygon", "line", "point", "mask")
+
+
+@dataclass(frozen=True)
+class FeatureRow:
+    """One ``(label, feature)`` pair from an export row, ontology-agnostic.
+
+    A classification answer or a localized object. An object's nested
+    classifications become their own rows, linked to the object via
+    :attr:`parent_feature_id`. Each labelled data row also yields one
+    ``feature_kind="label"`` sentinel row (no feature, ``value=""``) so that a
+    reached-and-labelled row is always represented even when empty.
+    """
+
+    global_key: str
+    data_row_id: str
+    # one of: label, radio, checklist, text, bounding_box, polygon,
+    # line, point, mask, relationship, unknown
+    feature_kind: str
+    feature_name: str
+    value: str  # answer value(s) / compact geometry; "" when none
+    workflow_status: str | None
+    labeled_by: str | None
+    created_at: str | None
+    parent_feature_id: str  # "" for top-level features
+
+
+def export(
+    project_id: str,
+    *,
+    status: str | None = None,
+    since: str | None = None,
+    api_key: str | None = None,
+    client: Any | None = None,
+) -> Iterator[JsonDict]:
+    """Stream export rows (one dict per data row) for ``project_id``.
+
+    ``status`` filters by task-queue stage (see :data:`WORKFLOW_STATUSES`).
+    ``since`` keeps only rows whose newest label was created on/after an ISO
+    date/datetime string (lexicographic compare on the ISO timestamp). Pass
+    ``client`` to inject a stub; otherwise the ``labelbox`` SDK is imported
+    lazily and a client is built from ``api_key`` or ``LABELBOX_API_KEY``.
+    """
+    cl = client if client is not None else _make_client(api_key)
+    project = cl.get_project(project_id)
+    filters = {"workflow_status": status} if status else None
+    task = project.export(
+        params={"data_row_details": True, "label_details": True, "project_details": True},
+        filters=filters,
+    )
+    task.wait_till_done()
+    for row in task.get_buffered_stream():
+        dr = row.json
+        if since is None or _created_at(_select_project(dr, project_id)) >= since:
+            yield dr
+
+
+def read_export_file(path: str | Path) -> list[JsonDict]:
+    """Load a saved export (JSON array or NDJSON) for offline flattening."""
+    text = Path(path).read_text().strip()
+    if not text:
+        return []
+    try:
+        loaded = json.loads(text)
+        return loaded if isinstance(loaded, list) else [loaded]
+    except json.JSONDecodeError:
+        return [json.loads(line) for line in text.splitlines() if line.strip()]
+
+
+def flatten(dr: JsonDict, project_id: str | None = None) -> list[FeatureRow]:
+    """Flatten one export row into :class:`FeatureRow` rows (every feature).
+
+    ``project_id`` selects which project's labels to read; ``None`` uses the only
+    project present (the common single-project export) and returns nothing if the
+    row is ambiguous (multiple projects) so a caller never silently mixes them.
+    An unreached or unlabelled row yields ``[]``.
+    """
+    data_row = dr.get("data_row") or {}
+    global_key = data_row.get("global_key") or ""
+    data_row_id = data_row.get("id") or global_key
+    proj = _select_project(dr, project_id)
+    label = _latest_label(proj)
+    if not global_key or label is None:
+        return []
+
+    status = _workflow_status(proj)
+    details = label.get("label_details") or {}
+    labeled_by = details.get("created_by")
+    created_at = details.get("created_at")
+    ann = label.get("annotations") or {}
+    rows: list[FeatureRow] = []
+
+    def emit(kind: str, name: str | None, value: str, parent: str = "") -> None:
+        rows.append(
+            FeatureRow(
+                global_key,
+                data_row_id,
+                kind,
+                name or "",
+                value,
+                status,
+                labeled_by,
+                created_at,
+                parent,
+            )
+        )
+
+    # Sentinel: this row was reached and labelled (carries who/when even if empty).
+    emit("label", "", "")
+
+    for cls in ann.get("classifications") or []:
+        kind, value = _classification_value(cls)
+        emit(kind, cls.get("name"), value)
+
+    for obj in ann.get("objects") or []:
+        kind, value = _object_geometry(obj)
+        feature_id = obj.get("feature_id") or obj.get("feature_schema_id") or ""
+        emit(kind, obj.get("name"), value)
+        for cls in obj.get("classifications") or []:
+            ckind, cvalue = _classification_value(cls)
+            emit(ckind, cls.get("name"), cvalue, parent=feature_id)
+
+    for rel in ann.get("relationships") or []:
+        value = json.dumps(rel.get("relationship") or {}, sort_keys=True)
+        emit("relationship", rel.get("name"), value)
+
+    return rows
+
+
+@dataclass(frozen=True)
+class Summary:
+    """Triage view of a pull: how much came back, of what kind, how fresh."""
+
+    n_data_rows: int
+    n_labelled: int
+    n_reached_unlabelled: int
+    feature_kinds: dict[str, int]
+    feature_names: dict[str, int]
+    statuses: dict[str, int]
+    latest_created_at: str | None
+
+
+def summarize(rows: Iterable[JsonDict], features: Iterable[FeatureRow]) -> Summary:
+    """Count data rows, labelled rows, and per-kind/name/status breakdowns."""
+    rows = list(rows)
+    features = list(features)
+    labelled_keys = {f.global_key for f in features}
+    kinds: dict[str, int] = {}
+    names: dict[str, int] = {}
+    statuses: dict[str, int] = {}
+    latest: str | None = None
+    for f in features:
+        if f.feature_kind == "label":
+            if f.workflow_status:
+                statuses[f.workflow_status] = statuses.get(f.workflow_status, 0) + 1
+            if f.created_at and (latest is None or f.created_at > latest):
+                latest = f.created_at
+            continue
+        kinds[f.feature_kind] = kinds.get(f.feature_kind, 0) + 1
+        if f.feature_name:
+            names[f.feature_name] = names.get(f.feature_name, 0) + 1
+    n_data_rows = len(rows)
+    n_labelled = len(labelled_keys)
+    return Summary(
+        n_data_rows=n_data_rows,
+        n_labelled=n_labelled,
+        n_reached_unlabelled=max(n_data_rows - n_labelled, 0),
+        feature_kinds=kinds,
+        feature_names=names,
+        statuses=statuses,
+        latest_created_at=latest,
+    )
+
+
+# --- internals -------------------------------------------------------------
+
+
+def _make_client(api_key: str | None) -> Any:
+    try:
+        import labelbox as lb  # noqa: PLC0415 (optional dep, imported only for live pulls)
+    except ImportError as exc:  # pragma: no cover - exercised only without the SDK
+        raise RuntimeError(
+            "a live pull needs the Labelbox SDK: pip install 'labelpull[live]'"
+        ) from exc
+    key = api_key or os.environ.get("LABELBOX_API_KEY")
+    if not key:
+        raise RuntimeError(
+            "no Labelbox API key: pass api_key=... or set LABELBOX_API_KEY "
+            "(or use a saved export with read_export_file)"
+        )
+    return lb.Client(api_key=key)
+
+
+def _select_project(dr: JsonDict, project_id: str | None) -> JsonDict:
+    projects = dr.get("projects") or {}
+    if project_id is not None:
+        return projects.get(project_id) or {}
+    if len(projects) == 1:
+        return next(iter(projects.values()))
+    return {}  # ambiguous: caller must name the project
+
+
+def _latest_label(proj: JsonDict) -> JsonDict | None:
+    # A QC-reviewed row carries the annotator's label *and* the reviewer's; the
+    # verified answer is the most recently created, not labels[0].
+    labels = proj.get("labels") or []
+    if not labels:
+        return None
+    return cast("JsonDict", max(labels, key=_created_at_of_label))
+
+
+def _created_at_of_label(label: JsonDict) -> str:
+    return (label.get("label_details") or {}).get("created_at") or ""
+
+
+def _created_at(proj: JsonDict) -> str:
+    label = _latest_label(proj)
+    return _created_at_of_label(label) if label else ""
+
+
+def _workflow_status(proj: JsonDict) -> str | None:
+    details = proj.get("project_details") or {}
+    status = details.get("workflow_status")
+    if status is None:
+        queue = details.get("task_queue_name") or details.get("task_queue_status")
+        status = "Done" if queue == "Done" else queue
+    return status
+
+
+def _classification_value(cls: JsonDict) -> tuple[str, str]:
+    if cls.get("radio_answer"):
+        answer = cls["radio_answer"]
+        return "radio", answer.get("value") or answer.get("name") or ""
+    if cls.get("checklist_answers") is not None:
+        values = [a.get("value") or a.get("name") or "" for a in cls["checklist_answers"]]
+        return "checklist", ";".join(v for v in values if v)
+    if cls.get("text_answer") is not None:
+        return "text", (cls["text_answer"] or {}).get("content") or ""
+    return "unknown", ""
+
+
+def _object_geometry(obj: JsonDict) -> tuple[str, str]:
+    for kind in _GEOMETRY_KINDS:
+        geom = obj.get(kind)
+        if geom is None:
+            continue
+        if kind == "mask":
+            return "mask", (geom or {}).get("url") or ""
+        return kind, json.dumps(geom, sort_keys=True)
+    return "unknown", ""

labelpull-0.1.0.dist-info/METADATA

@@ -0,0 +1,69 @@
+Metadata-Version: 2.4
+Name: labelpull
+Version: 0.1.0
+Summary: Pull the latest Labelbox annotations into a tidy, ontology-agnostic table.
+Author-email: Wietze Suijker <wietze.suijker@gmail.com>
+License-Expression: MIT
+Requires-Python: >=3.10
+Requires-Dist: typer>=0.9
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1; extra == 'dev'
+Requires-Dist: pytest>=7.4; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: live
+Requires-Dist: labelbox>=7.0; extra == 'live'
+Description-Content-Type: text/markdown
+
+# labelpull
+
+Pull the latest Labelbox annotations into a tidy, ontology-agnostic table.
+
+The Labelbox SDK already exports a project's labels and streams them. What it
+doesn't give you is a *tabular* view of that deeply nested JSON, the correctness
+logic to pick the right label when a row was reviewed, or a workflow status that
+is always populated. `labelpull` is exactly that thin layer on top of the SDK.
+
+## Install
+
+```bash
+pip install labelpull            # offline parsing + CLI
+pip install 'labelpull[live]'    # + the Labelbox SDK for live pulls
+```
+
+## CLI
+
+```bash
+export LABELBOX_API_KEY=...
+labelpull pull <PROJECT_ID> -o labels.csv               # generic long CSV (any ontology)
+labelpull pull <PROJECT_ID> --status Done               # only verified rows
+labelpull pull <PROJECT_ID> --since 2026-06-01          # only the latest labels
+labelpull pull <PROJECT_ID> --from-export export.ndjson # offline, no API key
+labelpull pull <PROJECT_ID> --schema species -o taxa.csv # speciesfirst Taxon/Organs wide CSV
+```
+
+`--schema generic` (default) writes one row per feature — every classification
+and object, any ontology:
+
+```
+global_key,data_row_id,feature_kind,feature_name,value,workflow_status,labeled_by,created_at,parent_feature_id
+```
+
+## Library
+
+```python
+import labelpull
+
+rows = list(labelpull.export("proj_id", status="Done"))   # or read_export_file("export.ndjson")
+features = [f for r in rows for f in labelpull.flatten(r, "proj_id")]
+labelpull.write_csv("labels.csv", labelpull.GenericAdapter(), features)
+print(labelpull.summarize(rows, features))
+```
+
+`flatten()` handles radio / checklist / text classifications and bbox / polygon /
+line / point / mask objects (with nested classifications linked to their parent),
+and always selects the most recently created label so a QC-reviewed row reports
+the reviewer's answer, not the annotator's.
+
+Write your own `Adapter` to collapse features into a project-specific wide table;
+`SpeciesAdapter` is the reference implementation.

labelpull-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+labelpull/__init__.py,sha256=J8P7ntqvXjksIW6zE4l2nJf8w3As9B5_ekxdIT6NvvA,929
+labelpull/adapters.py,sha256=5nIpl7NI13BfkQtn7eQ_eyD7maOmCkePXk7F8V9qHOc,3834
+labelpull/cli.py,sha256=042bOraQpPAaRtATC-I0UUqKf1I8DR1ASb0opT21ZjQ,3536
+labelpull/core.py,sha256=VGPRMcd2pQLo16KGuHKWGnJ2iyoUxWCq5Y53DdLIXtM,10765
+labelpull/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+labelpull-0.1.0.dist-info/METADATA,sha256=H2Onwo9BL_7J-3gKtgpd8JKl8DyKh3ff0FlTmaf8kwI,2572
+labelpull-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+labelpull-0.1.0.dist-info/entry_points.txt,sha256=vCh16Czaiyg87c3851QSoQTVIjIV55vK0vQ6xWZEbZI,48
+labelpull-0.1.0.dist-info/RECORD,,

labelpull-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

labelpull-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+labelpull = labelpull.cli:app