[CLI] Surface job runtime fields in ps + inspect by davanstrien · Pull Request #4211 · huggingface/huggingface_hub

davanstrien · 2026-05-08T13:15:55Z

Not blocked by the upcoming cli/jobs.py out.* migration; this could land first
since it's purely additive (new fields + new column).

Summary

Surfaces job runtime fields (startedAt, finishedAt, durations) in
hf jobs ps and hf jobs inspect. The server-side change that exposes these
fields in the jobs API response landed recently; this is the CLI counterpart.

_jobs_api.py: new JobDurations dataclass; three new fields on JobInfo
__init__.py: re-export JobDurations alongside the existing job dataclasses
cli/jobs.py: new RUNTIME column in ps (shows running_secs); inspect auto-surfaces via asdict
utils/_parsing.py: new format_duration helper (sibling of format_timesince)
Tests: parse tests + CLI render test + format_duration unit tests

Test plan

Parse tests (full / errored-before-start / terminal-no-finished-at payloads)
RUNTIME column render test
format_duration unit tests across all branches
Smoke-tested locally against real COMPLETED, RUNNING, SCHEDULING, CANCELED, ERROR jobs

🤖 Generated with Claude Code

Note

Medium Risk
Mostly additive, but extends the public Jobs API surface (JobStage enum and JobInfo fields) which could affect downstream code that assumes a fixed set of stages/fields or relies on dataclass serialization.

Overview
Surfaces server-provided job runtime metadata end-to-end by extending JobInfo with started_at, finished_at, and durations (new JobDurations dataclass) and adding the SCHEDULING stage to JobStage.

Updates hf jobs ps to include a RUNTIME column derived from durations.running_secs using a new format_duration helper, and re-exports JobDurations from huggingface_hub.__init__. Adds parsing/unit tests to cover full/partial/absent duration payloads and CLI table rendering.

^{Reviewed by Cursor Bugbot for commit f0644af. Bugbot is set up for automated code reviews on this repo. Configure here.}

Adds startedAt, finishedAt, and durations (schedulingSecs/runningSecs/totalSecs) to JobInfo, surfaces them in `hf jobs inspect`, and adds a DURATION column to `hf jobs ps`. The server-side change that exposes these fields in the jobs API response shipped recently; this is the CLI counterpart. Also adds a small `format_duration` helper to utils/_parsing.py (sibling of existing format_timesince) so the formatting logic stays reusable. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

bot-ci-comment · 2026-05-08T13:22:08Z

The docs for this PR live here. All of your documentation changes will be reflected on that endpoint. The docs are available until 30 days after the last update.

codecov · 2026-05-08T13:27:55Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 77.38%. Comparing base (1daa48b) to head (f0644af).
⚠️ Report is 349 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #4211      +/-   ##
==========================================
+ Coverage   75.00%   77.38%   +2.37%     
==========================================
  Files         145      171      +26     
  Lines       13978    19608    +5630     
==========================================
+ Hits        10484    15173    +4689     
- Misses       3494     4435     +941

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Matches the existing pattern for nested job dataclasses (JobOwner, JobStatus) which are re-exported from huggingface_hub.__init__, so users can type-annotate `job.durations` without reaching into the private _jobs_api module. Also brings the JobInfo docstring example up to date with the new started_at, finished_at, and durations fields. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 08a6f4b. Configure here.}

`kwargs.get(camel) or kwargs.get(snake)` collapses a legitimate `0` to `None` because `0` is falsy. Switch to `dict.get(camel, dict.get(snake))` so the fallback fires only when the camelCase key is missing. Defensive: the server-side API doesn't emit `0` in practice (observed minimum is ~4s of container scheduling overhead). Flagged by Cursor Bugbot review. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

@lhoestq

Aligns with `docker ps` / `kubectl get pods` conventions where DURATION means actual runtime. SCHEDULING jobs now show `--` instead of queue wait time, removing the surprising behaviour previously called out in the PR description. Per review feedback from @lhoestq. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

hanouticelina

Thanks!

@hanouticelina

Per review feedback from @hanouticelina: - Rename the `hf jobs ps` column DURATION→RUNTIME so the header matches what the value shows (`running_secs`). - Rewrite the JobDurations / JobInfo.durations docstrings. The previous "`None` while the Job is still scheduling" framing was wrong: per the server-side rule in `compute_job_durations`, SCHEDULING returns `Some({totalSecs})` and `durations` is `None` only for some terminal jobs missing a `finished_at` timestamp. - Rename the partial-durations test to use the real `{totalSecs}` only shape (not the keys-present-with-null fixture, which never appears in production), and align the runtime-fields-default-none test fixture stage with its docstring. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

davanstrien · 2026-05-15T14:10:55Z

Updated PR description to reflect post-review state:

DURATION → RUNTIME throughout (summary + test plan)
Dropped the "Open questions for reviewers" section
Refreshed test plan bullets to match the renamed tests

hanouticelina

Thank you, looks good to me 👍 ok to merge when the comment and merge conflicts are addressed!

Resolve JobInfo conflict from huggingface#4212 (initiator) by keeping both the runtime fields (started_at/finished_at/durations + JobDurations) and the new initiator field/dataclass. Add JobStage.SCHEDULING (+ docstring) per review — fixtures rely on it. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

huggingface-hub-bot · 2026-05-21T12:26:35Z

This PR has been shipped as part of the v1.16.0 release.

davanstrien mentioned this pull request May 8, 2026

[CLI] Parse initiator field on jobs API responses #4212

Merged

3 tasks

davanstrien marked this pull request as ready for review May 11, 2026 13:24

cursor Bot reviewed May 11, 2026

View reviewed changes

Comment thread src/huggingface_hub/_jobs_api.py Outdated

davanstrien requested review from hanouticelina and lhoestq May 11, 2026 13:45

lhoestq reviewed May 11, 2026

View reviewed changes

Comment thread src/huggingface_hub/cli/jobs.py Outdated

hanouticelina reviewed May 15, 2026

View reviewed changes

Comment thread src/huggingface_hub/cli/jobs.py Outdated

Comment thread src/huggingface_hub/_jobs_api.py Outdated

davanstrien and others added 2 commits May 15, 2026 15:00

Merge branch 'main' into cli-jobs-runtime-fields

72c758e

hanouticelina approved these changes May 19, 2026

View reviewed changes

Comment thread tests/test_cli.py

davanstrien and others added 2 commits May 20, 2026 10:31

Merge branch 'main' into cli-jobs-runtime-fields

f0644af

hanouticelina merged commit 2618a54 into huggingface:main May 21, 2026
17 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[CLI] Surface job runtime fields in ps + inspect#4211

[CLI] Surface job runtime fields in ps + inspect#4211
hanouticelina merged 8 commits into
huggingface:mainfrom
davanstrien:cli-jobs-runtime-fields

davanstrien commented May 8, 2026 •

edited by cursor Bot

Loading

Uh oh!

bot-ci-comment Bot commented May 8, 2026

Uh oh!

codecov Bot commented May 8, 2026 •

edited

Loading

Uh oh!

cursor Bot left a comment

Uh oh!

Uh oh!

Uh oh!

hanouticelina left a comment

Uh oh!

Uh oh!

Uh oh!

davanstrien commented May 15, 2026

Uh oh!

hanouticelina left a comment

Uh oh!

Uh oh!

Uh oh!

huggingface-hub-bot Bot commented May 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

davanstrien commented May 8, 2026 • edited by cursor Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test plan

Uh oh!

bot-ci-comment Bot commented May 8, 2026

Uh oh!

codecov Bot commented May 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

hanouticelina left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

davanstrien commented May 15, 2026

Uh oh!

hanouticelina left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

huggingface-hub-bot Bot commented May 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

davanstrien commented May 8, 2026 •

edited by cursor Bot

Loading

codecov Bot commented May 8, 2026 •

edited

Loading