From 82b0b8bc008793f94a3e135f0c590126cb01fe12 Mon Sep 17 00:00:00 2001 From: Wietze Date: Wed, 14 Oct 2026 20:23:27 -0400 Subject: [PATCH] fix(timestamps): compare label creation times chronologically Share exact timestamp comparisons across latest-label selection, live and offline cutoffs, and summaries. Preserve date-only UTC cutoffs, missing-label fallback and deterministic ties while rejecting malformed offsets and unsupported timestamp forms consistently on Python 3.10. Verify configured lint, format, strict mypy, tests on Python 3.10 through 3.14, build and Twine checks. Independent datetime and exact-fraction oracles, adversarial refutation and Crownfirst adapter compatibility pass. No pre-commit configuration exists in this repository; configured checks were run explicitly. --- README.md | 2 + pyproject.toml | 4 +- src/labelpull/cli.py | 16 +-- src/labelpull/core.py | 84 ++++++++++-- tests/test_timestamps.py | 272 +++++++++++++++++++++++++++++++++++++++ 5 files changed, 359 insertions(+), 19 deletions(-) create mode 100644 tests/test_timestamps.py 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]