Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,6 +48,8 @@ labelpull pull <PROJECT_ID> --from-export export.ndjson # offline: a UI "Export"
`--status` takes `ToLabel | InReview | InRework | Done`. Every run prints a
summary (rows, labelled count, feature kinds, latest label timestamp).

`--since` compares instants, including fractional seconds and UTC offsets. A date such as `2026-06-01` means midnight UTC; a datetime uses `YYYY-MM-DDTHH:MM:SS` (a space may replace `T`), optional dot/comma fractional seconds, and `Z` or a signed `HH:MM` offset such as `-05:00` (whole `:SS` offset seconds are also supported). Invalid values, out-of-range offset components, compact/reduced-time forms, datetimes without an offset, and fractional UTC offsets raise an error. Rows with no selected label timestamp are excluded by `--since`. Label selection uses the newest timestamp, keeping the first label for equal instants; if any label lacks a timestamp, it retains the last label in export order as a best-effort fallback. Timestamp strings in the output keep their original spelling.

If your project is a single-classification task and you want one row per item
instead of the long format, filter the CSV to your feature (e.g. keep
`feature_name == "Species"`), or write a 10-line `Adapter` (see below).
Expand Down
4 changes: 2 additions & 2 deletions pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -30,8 +30,8 @@ target-version = "py310"
select = ["E", "F", "I", "B", "UP", "SIM", "PL"]

[tool.ruff.lint.per-file-ignores]
# Typer expresses CLI args as call-defaults (B008) and wide signatures (PLR0913).
"src/labelpull/cli.py" = ["B008", "PLR0913"]
# Typer expresses CLI args as call-defaults (B008) and wide signatures (PLR0913/PLR0917).
"src/labelpull/cli.py" = ["B008", "PLR0913", "PLR0917"]
# Tests assert against literal expected values (PLR2004) and import lazily (PLC0415).
"tests/*" = ["PLR2004", "PLC0415", "E501"]

Expand Down
16 changes: 8 additions & 8 deletions src/labelpull/cli.py
Original file line number Diff line number Diff line change
Expand Up @@ -18,8 +18,8 @@
WORKFLOW_STATUSES,
FeatureRow,
JsonDict,
_created_at,
_select_project,
_row_since,
_timestamp_key,
flatten,
read_export_file,
summarize,
Expand Down Expand Up @@ -64,13 +64,17 @@ def pull(
raise typer.BadParameter(f"--status must be one of {', '.join(WORKFLOW_STATUSES)}")
if schema not in ADAPTERS:
raise typer.BadParameter(f"unknown schema {schema!r}; choose from {sorted(ADAPTERS)}")
try:
cutoff = _timestamp_key(since, field="since") if since is not None else None
except ValueError as exc:
raise typer.BadParameter(str(exc), param_hint="--since") from exc
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)]
if cutoff is not None:
rows = [r for r in rows if _row_since(r, project_id, cutoff)]
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))
Expand All @@ -82,10 +86,6 @@ def pull(
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(
Expand Down
84 changes: 75 additions & 9 deletions src/labelpull/core.py
Original file line number Diff line number Diff line change
Expand Up @@ -21,14 +21,24 @@

import json
import os
import re
from collections.abc import Iterable, Iterator
from dataclasses import dataclass
from datetime import datetime, timezone
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]

# Retain sub-microsecond digits rather than letting datetime truncate them.
_TimestampKey = tuple[datetime, str]
_TIMESTAMP = re.compile(
r"\d{4}-\d{2}-\d{2}(?:[T ]\d{2}:\d{2}:\d{2}(?:[.,]\d+)?"
r"(?P<offset>Z|[+-](?P<hours>\d{2}):(?P<minutes>\d{2})(?::(?P<seconds>\d{2}))?))?",
re.ASCII,
)

# The task-queue stages ``project.export(filters={"workflow_status": ...})`` accepts.
WORKFLOW_STATUSES = ("ToLabel", "InReview", "InRework", "Done")

Expand Down Expand Up @@ -72,10 +82,13 @@ def export(

``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``.
date/datetime string. Dates mean UTC midnight; datetimes need an explicit
UTC offset. Missing timestamps do not pass a cutoff; invalid or naive
timestamps raise ``ValueError``. 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``.
"""
cutoff = _timestamp_key(since, field="since") if since is not None else None
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
Expand All @@ -86,7 +99,7 @@ def export(
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:
if cutoff is None or _row_since(dr, project_id, cutoff):
yield dr


Expand Down Expand Up @@ -192,12 +205,15 @@ def summarize(rows: Iterable[JsonDict], features: Iterable[FeatureRow]) -> Summa
names: dict[str, int] = {}
statuses: dict[str, int] = {}
latest: str | None = None
latest_key: _TimestampKey | 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
if f.created_at:
timestamp = _timestamp_key(f.created_at)
if latest_key is None or timestamp > latest_key:
latest, latest_key = f.created_at, timestamp
continue
kinds[f.feature_kind] = kinds.get(f.feature_kind, 0) + 1
if f.feature_name:
Expand Down Expand Up @@ -251,7 +267,8 @@ def _latest_label(proj: JsonDict) -> JsonDict | None:

Selection rules:
- If ALL labels have a non-empty ``created_at``, return the one with the
maximum (newest) timestamp.
maximum (newest) timestamp. Equivalent instants keep the first label.
Invalid or timezone-naive datetimes raise ``ValueError``.
- Otherwise, at least one label is missing a timestamp. Fall back to export
order and return ``labels[-1]``. Export order is last-in-newest by
Labelbox convention, so this is a best-effort approximation when
Expand All @@ -263,8 +280,12 @@ def _latest_label(proj: JsonDict) -> JsonDict | None:
# Fall back to export order when any label is missing a timestamp.
# (Export order: last-in == newest; deliberate best-effort fallback.)
if not all(_created_at_of_label(lbl) for lbl in labels):
return cast("JsonDict", labels[-1])
return cast("JsonDict", max(labels, key=_created_at_of_label))
selected = cast("JsonDict", labels[-1])
timestamp = _created_at_of_label(selected)
if timestamp:
_timestamp_key(timestamp)
return selected
return cast("JsonDict", max(labels, key=lambda lbl: _timestamp_key(_created_at_of_label(lbl))))


def _created_at_of_label(label: JsonDict) -> str:
Expand All @@ -276,6 +297,51 @@ def _created_at(proj: JsonDict) -> str:
return _created_at_of_label(label) if label else ""


def _timestamp_key(value: str, *, field: str = "created_at") -> _TimestampKey:
"""Compare ISO timestamps as instants, retaining arbitrary fractional seconds.

Date-only values mean UTC midnight. Datetimes require an explicit offset;
guessing local time would make offline and live results machine-dependent.
"""
error = (
f"{field} must be YYYY-MM-DD or an extended datetime with seconds and a UTC offset, "
f"got {value!r}"
)
if not isinstance(value, str) or not value:
raise ValueError(error)
# fromisoformat can discard a fractional offset when its whole seconds are zero.
if re.search(r"[+-]\d{2}(?::?\d{2}){0,2}[.,]", value):
raise ValueError(f"{field} does not support fractional UTC offsets, got {value!r}")
match = _TIMESTAMP.fullmatch(value)
if match is None or any(
int(match[name] or 0) >= limit
for name, limit in (("hours", 24), ("minutes", 60), ("seconds", 60))
):
raise ValueError(error)
normalized = value.removesuffix("Z") + "+00:00" if value.endswith("Z") else value
remainder = ""
fraction = re.fullmatch(r"(.{19})[.,](\d+)(.*)", normalized)
if fraction is not None:
digits = fraction[2]
# Python 3.10 accepts 3 or 6 fractional digits, and no Z suffix.
normalized = f"{fraction[1]}.{digits[:6].ljust(6, '0')}{fraction[3]}"
remainder = digits[6:].rstrip("0")
try:
timestamp = datetime.fromisoformat(normalized)
except ValueError as exc:
raise ValueError(error) from exc
if timestamp.tzinfo is None:
if len(value) != len("YYYY-MM-DD"):
raise ValueError(error)
timestamp = timestamp.replace(tzinfo=timezone.utc)
return timestamp, remainder


def _row_since(dr: JsonDict, project_id: str, cutoff: _TimestampKey) -> bool:
created_at = _created_at(_select_project(dr, project_id))
return bool(created_at) and _timestamp_key(created_at) >= cutoff


def _workflow_status(proj: JsonDict) -> str | None:
details = proj.get("project_details") or {}
status = details.get("workflow_status")
Expand Down
Loading
Loading