diff --git a/README.md b/README.md index 23f093b..ca7a878 100644 --- a/README.md +++ b/README.md @@ -48,6 +48,8 @@ labelpull pull --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). diff --git a/pyproject.toml b/pyproject.toml index 969241c..9dd05eb 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -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"] diff --git a/src/labelpull/cli.py b/src/labelpull/cli.py index 1f587f6..3df4741 100644 --- a/src/labelpull/cli.py +++ b/src/labelpull/cli.py @@ -18,8 +18,8 @@ WORKFLOW_STATUSES, FeatureRow, JsonDict, - _created_at, - _select_project, + _row_since, + _timestamp_key, flatten, read_export_file, summarize, @@ -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)) @@ -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( diff --git a/src/labelpull/core.py b/src/labelpull/core.py index 388de7b..dddfce8 100644 --- a/src/labelpull/core.py +++ b/src/labelpull/core.py @@ -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"(?PZ|[+-](?P\d{2}):(?P\d{2})(?::(?P\d{2}))?))?", + re.ASCII, +) + # The task-queue stages ``project.export(filters={"workflow_status": ...})`` accepts. WORKFLOW_STATUSES = ("ToLabel", "InReview", "InRework", "Done") @@ -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 @@ -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 @@ -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: @@ -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 @@ -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: @@ -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") diff --git a/tests/test_timestamps.py b/tests/test_timestamps.py new file mode 100644 index 0000000..15efcdf --- /dev/null +++ b/tests/test_timestamps.py @@ -0,0 +1,272 @@ +"""Chronological contracts exercised through public callers, without the SDK.""" + +from __future__ import annotations + +import csv +import json +from datetime import datetime, timezone +from pathlib import Path +from types import SimpleNamespace + +import pytest +from typer.testing import CliRunner + +from labelpull import export, flatten, summarize +from labelpull.cli import app + + +def _row(key: str, timestamps: list[str | None]) -> dict: + return { + "data_row": {"id": key, "global_key": key}, + "projects": { + "p": { + "labels": [ + {"label_details": {"created_at": timestamp}, "annotations": {}} + for timestamp in timestamps + ] + } + }, + } + + +class _Client: + def __init__(self, rows: list[dict]) -> None: + self.rows = rows + self.requested = False + + def get_project(self, project_id: str) -> SimpleNamespace: + self.requested = True + task = SimpleNamespace( + wait_till_done=lambda: None, + get_buffered_stream=lambda: [SimpleNamespace(json=row) for row in self.rows], + ) + return SimpleNamespace(export=lambda **kwargs: task) + + +def _oracle(timestamp: str) -> datetime: + """Independent stdlib parser, deliberately uses strptime rather than fromisoformat.""" + if len(timestamp) == 10: + return datetime.strptime(timestamp, "%Y-%m-%d").replace(tzinfo=timezone.utc) + pattern = "%Y-%m-%dT%H:%M:%S.%f%z" if "." in timestamp else "%Y-%m-%dT%H:%M:%S%z" + return datetime.strptime(timestamp, pattern).astimezone(timezone.utc) + + +@pytest.mark.parametrize( + "timestamps", + [ + ["2026-06-01T12:00:00Z", "2026-06-01T12:00:00.100Z"], + ["2026-06-01T12:00:00.100000Z", "2026-06-01T12:00:00.100001Z"], + ["2026-06-01T12:00:00.12Z", "2026-06-01T12:00:00.12345Z"], + ["2026-06-01T13:00:00+02:00", "2026-06-01T12:00:00Z"], + ["2026-06-02T00:30:00+02:00", "2026-06-01T23:00:00Z"], + ], +) +def test_latest_label_matches_datetime_oracle(timestamps: list[str]) -> None: + expected = max(timestamps, key=_oracle) + # Changing the export order must not change the chronological winner. + for order in (timestamps, list(reversed(timestamps))): + assert flatten(_row("g", order), "p")[0].created_at == expected + + +@pytest.mark.parametrize( + "timestamps", + [ + ["2026-06-01T12:00:00Z", "2026-06-01T07:00:00-05:00"], + ["2026-06-01T12:00:00.1Z", "2026-06-01T12:00:00.100000Z"], + ["2026-06-01", "2026-06-01T00:00:00Z"], + ], +) +def test_same_instant_ties_preserve_first_label(timestamps: list[str]) -> None: + assert _oracle(timestamps[0]) == _oracle(timestamps[1]) + for order in (timestamps, list(reversed(timestamps))): + assert flatten(_row("g", order), "p")[0].created_at == order[0] + + +@pytest.mark.parametrize("missing", [None, ""]) +def test_missing_timestamp_preserves_export_order_fallback(missing: str | None) -> None: + timestamp = "2026-06-01T12:00:00Z" + for timestamps in ([timestamp, missing], [missing, timestamp]): + assert flatten(_row("g", timestamps), "p")[0].created_at == timestamps[-1] + + +_TIMESTAMPS = [ + "2026-05-31T23:59:59.999999Z", + "2026-06-01T00:00:00Z", + "2026-06-01T01:00:00+02:00", + "2026-05-31T19:00:00-05:00", + "2026-06-01T12:00:00Z", + "2026-06-01T12:00:00.1Z", + "2026-06-01T12:00:00.100001Z", + "2026-06-01T07:00:00.100000-05:00", + "2026-06-01T14:00:00.100001+02:00", + "2026-06-01", +] + + +@pytest.mark.parametrize( + "since", + [ + "2026-06-01", + "2026-06-01T12:00:00Z", + "2026-06-01T07:00:00-05:00", + "2026-06-01T12:00:00.1Z", + "2026-06-01T12:00:00.100001Z", + ], +) +def test_live_and_offline_since_match_datetime_oracle(tmp_path: Path, since: str) -> None: + rows = [_row(str(i), [timestamp]) for i, timestamp in enumerate(_TIMESTAMPS)] + rows += [_row("missing", [None]), _row("empty", [""]), _row("unlabelled", [])] + # Also force filtering to choose among multiple labels before comparing the cutoff. + rows.append(_row("reviewed", ["2026-06-01T12:00:00Z", "2026-06-01T12:00:00.1Z"])) + expected = [str(i) for i, value in enumerate(_TIMESTAMPS) if _oracle(value) >= _oracle(since)] + if _oracle("2026-06-01T12:00:00.1Z") >= _oracle(since): + expected.append("reviewed") + actual = list(export("p", since=since, client=_Client(rows))) + assert [row["data_row"]["global_key"] for row in actual] == expected + + source = tmp_path / "input.json" + source.write_text(json.dumps(rows)) + out = tmp_path / "out.csv" + result = CliRunner().invoke( + app, ["pull", "p", "--from-export", str(source), "--since", since, "-o", str(out)] + ) + assert result.exit_code == 0, result.output + with out.open(newline="") as stream: + assert [row["global_key"] for row in csv.DictReader(stream)] == expected + + +@pytest.mark.parametrize( + "since", + [ + "", + "nonsense", + "2026-02-30", + "2026-06-01T12:00:00", + "2026-06-01T12:00:00+00:99", + "2026-06-01T12:00:00+01:00:99", + "2026-06-01T12:00:00+24:00", + "20260601T120000.1234561Z", + "2026-06-01T12:00.1234561Z", + "2026-06-01T12:00:00.123456١Z", + ], +) +@pytest.mark.parametrize("rows", [[], [_row("missing", [None])]]) +def test_invalid_cutoff_fails_before_live_request_or_offline_output( + tmp_path: Path, since: str, rows: list[dict] +) -> None: + client = _Client(rows) + with pytest.raises(ValueError, match="since"): + list(export("p", since=since, client=client)) + assert not client.requested + source = tmp_path / "input.json" + source.write_text(json.dumps(rows)) + out = tmp_path / "out.csv" + result = CliRunner().invoke( + app, ["pull", "p", "--from-export", str(source), "--since", since, "-o", str(out)] + ) + assert result.exit_code != 0 + assert "Invalid value" in result.output and "since" in result.output + assert not out.exists() + + +@pytest.mark.parametrize( + "timestamp", + [ + "nonsense", + "2026-02-30", + "2026-06-01T12:00:00", + "2026-06-01T12:00:00+00:00:00.123456", + "2026-06-01T12:00:00.1234561+00:00:00.0000001", + "2026-06-01T12:00:00+00:00.123456", + "2026-06-01T12:00:00+05:30.1", + "2026-06-01T12:00:00+05.123456", + "2026-06-01T12:00:00+00:99", + "2026-06-01T12:00:00+01:00:99", + "2026-06-01T12:00:00+24:00", + "20260601T120000.1234561Z", + "2026-06-01T12:00.1234561Z", + ], +) +@pytest.mark.parametrize("missing_prefix", [False, True]) +def test_invalid_label_timestamp_fails_instead_of_guessing( + timestamp: str, tmp_path: Path, missing_prefix: bool +) -> None: + row = _row("g", [None, timestamp] if missing_prefix else [timestamp]) + with pytest.raises(ValueError, match="created_at"): + flatten(row, "p") + with pytest.raises(ValueError, match="created_at"): + list(export("p", since="2026-06-01", client=_Client([row]))) + source = tmp_path / "input.json" + source.write_text(json.dumps([row])) + result = CliRunner().invoke( + app, ["pull", "p", "--from-export", str(source), "--since", "2026-06-01"] + ) + assert result.exit_code != 0 + assert "created_at" in str(result.exception) + + +def test_summary_latest_timestamp_is_chronological_and_keeps_original_spelling() -> None: + rows = [_row(str(i), [timestamp]) for i, timestamp in enumerate(_TIMESTAMPS)] + features = [feature for row in rows for feature in flatten(row, "p")] + expected = max(_TIMESTAMPS, key=_oracle) + assert summarize(rows, features).latest_created_at == expected + + +@pytest.mark.parametrize( + ("earlier", "later"), + [ + ("2026-06-01T12:00:00.12345601Z", "2026-06-01T12:00:00.1234561Z"), + ("2026-06-01T07:00:00.1234561-05:00", "2026-06-01T12:00:00.1234562Z"), + ("2026-06-01T12:00:00.00000000000000001Z", "2026-06-01T12:00:00.0000000000000001Z"), + ], +) +def test_sub_microsecond_precision_is_never_truncated( + earlier: str, later: str, tmp_path: Path +) -> None: + assert flatten(_row("g", [later, earlier]), "p")[0].created_at == later + rows = [_row("early", [earlier]), _row("late", [later])] + assert list(export("p", since=later, client=_Client(rows))) == [rows[1]] + assert summarize(rows, [f for r in rows for f in flatten(r, "p")]).latest_created_at == later + source = tmp_path / "input.json" + source.write_text(json.dumps(rows)) + out = tmp_path / "out.csv" + result = CliRunner().invoke( + app, ["pull", "p", "--from-export", str(source), "--since", later, "-o", str(out)] + ) + assert result.exit_code == 0, result.output + with out.open(newline="") as stream: + assert [row["global_key"] for row in csv.DictReader(stream)] == ["late"] + + +def test_sub_microsecond_trailing_zeros_and_offsets_are_same_instant() -> None: + first = "2026-06-01T12:00:00.1234561Z" + second = "2026-06-01T07:00:00.1234561000-05:00" + for order in ([first, second], [second, first]): + row = _row("g", order) + assert flatten(row, "p")[0].created_at == order[0] + assert list(export("p", since=first, client=_Client([row]))) == [row] + assert list(export("p", since=second, client=_Client([row]))) == [row] + + +@pytest.mark.parametrize( + "timestamp", + [ + "2026-06-01 12:00:00,1234561Z", + "2026-06-01T12:00:30.1234561+00:00:30", + "2026-06-01T11:59:30.1234561-00:00:30", + ], +) +def test_documented_extended_forms_keep_exact_instants(timestamp: str) -> None: + reference = "2026-06-01T12:00:00.1234561Z" + for order in ([reference, timestamp], [timestamp, reference]): + item = _row("g", order) + assert flatten(item, "p")[0].created_at == order[0] + assert list(export("p", since=reference, client=_Client([item]))) == [item] + assert list(export("p", since=timestamp, client=_Client([item]))) == [item] + + +def test_year_boundaries_do_not_require_unrepresentable_utc_conversion() -> None: + minimum = ["0001-01-01T00:00:00+01:00", "0001-01-01T00:00:00Z"] + maximum = ["9999-12-31T23:59:59-01:00", "9999-12-31T23:59:59Z"] + assert flatten(_row("g", minimum), "p")[0].created_at == minimum[1] + assert flatten(_row("g", maximum), "p")[0].created_at == maximum[0]