[CLI] Migrate models, datasets, spaces, papers to out singleton (#4026)

* Migrate models, datasets, spaces, papers to out singleton

* handle special case for papers ls

* rebase

* test: update cli output table tests

Co-authored-by: célina <hanouticelina@users.noreply.github.com>

* Apply suggestions from code review

Co-authored-by: célina <hanouticelina@gmail.com>

* fix `papers_ls` JSON output and preserve full `submitted_by` object

* fix `_format_table_value_human` treating 0 as empty cell

* address review comments

* Apply suggestions from code review

Co-authored-by: Lucain <lucainp@gmail.com>

* missing one

---------

Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Co-authored-by: célina <hanouticelina@users.noreply.github.com>
Co-authored-by: Lucain <lucainp@gmail.com>

Author: 3 people

docs/source/en/package_reference/cli.md

@@ -950,7 +950,7 @@ $ hf datasets [OPTIONS] COMMAND [ARGS]...
 
 ### `hf datasets info`
 
-Get info about a dataset on the Hub. Output is in JSON format.
+Get info about a dataset on the Hub.
 
 **Usage**:
 
@@ -966,6 +966,7 @@ $ hf datasets info [OPTIONS] DATASET_ID
 
 * `--revision TEXT`: Git revision id which can be a branch name, a tag, or a commit hash.
 * `--expand TEXT`: Comma-separated properties to return. When used, only the listed properties (and id) are returned. Example: '--expand=downloads,likes,tags'. Valid: author, cardData, citation, createdAt, description, disabled, downloads, downloadsAllTime, gated, lastModified, likes, paperswithcode_id, private, resourceGroup, sha, siblings, tags, trendingScore, usedStorage.
+* `--format [agent|auto|human|json|quiet]`: Output format.  [default: auto]
 * `--token TEXT`: A User Access Token generated from https://huggingface.co/settings/tokens.
 * `--help`: Show this message and exit.
 
@@ -996,8 +997,7 @@ $ hf datasets list [OPTIONS]
 * `--sort [created_at|downloads|last_modified|likes|trending_score]`: Sort results.
 * `--limit INTEGER`: Limit the number of results.  [default: 10]
 * `--expand TEXT`: Comma-separated properties to return. When used, only the listed properties (and id) are returned. Example: '--expand=downloads,likes,tags'. Valid: author, cardData, citation, createdAt, description, disabled, downloads, downloadsAllTime, gated, lastModified, likes, paperswithcode_id, private, resourceGroup, sha, siblings, tags, trendingScore, usedStorage.
-* `--format [table|json]`: Output format (table or json).  [default: table]
-* `-q, --quiet`: Print only IDs (one per line).
+* `--format [agent|auto|human|json|quiet]`: Output format.  [default: auto]
 * `--token TEXT`: A User Access Token generated from https://huggingface.co/settings/tokens.
 * `--help`: Show this message and exit.
 
@@ -1029,8 +1029,7 @@ $ hf datasets parquet [OPTIONS] DATASET_ID
 
 * `--subset TEXT`: Filter parquet entries by subset/config.
 * `--split TEXT`: Filter parquet entries by split.
-* `--format [table|json]`: Output format (table or json).  [default: table]
-* `-q, --quiet`: Print only IDs (one per line).
+* `--format [agent|auto|human|json|quiet]`: Output format.  [default: auto]
 * `--token TEXT`: A User Access Token generated from https://huggingface.co/settings/tokens.
 * `--help`: Show this message and exit.
 
@@ -1061,7 +1060,7 @@ $ hf datasets sql [OPTIONS] SQL
 
 **Options**:
 
-* `--format [table|json]`: Output format (table or json).  [default: table]
+* `--format [agent|auto|human|json|quiet]`: Output format.  [default: auto]
 * `--token TEXT`: A User Access Token generated from https://huggingface.co/settings/tokens.
 * `--help`: Show this message and exit.
 
@@ -2593,7 +2592,7 @@ $ hf models [OPTIONS] COMMAND [ARGS]...
 
 ### `hf models info`
 
-Get info about a model on the Hub. Output is in JSON format.
+Get info about a model on the Hub.
 
 **Usage**:
 
@@ -2609,6 +2608,7 @@ $ hf models info [OPTIONS] MODEL_ID
 
 * `--revision TEXT`: Git revision id which can be a branch name, a tag, or a commit hash.
 * `--expand TEXT`: Comma-separated properties to return. When used, only the listed properties (and id) are returned. Example: '--expand=downloads,likes,tags'. Valid: author, baseModels, cardData, childrenModelCount, config, createdAt, disabled, downloads, downloadsAllTime, evalResults, gated, gguf, inference, inferenceProviderMapping, lastModified, library_name, likes, mask_token, model-index, pipeline_tag, private, resourceGroup, safetensors, sha, siblings, spaces, tags, transformersInfo, trendingScore, usedStorage, widgetData.
+* `--format [agent|auto|human|json|quiet]`: Output format.  [default: auto]
 * `--token TEXT`: A User Access Token generated from https://huggingface.co/settings/tokens.
 * `--help`: Show this message and exit.
 
@@ -2640,8 +2640,7 @@ $ hf models list [OPTIONS]
 * `--sort [created_at|downloads|last_modified|likes|trending_score]`: Sort results.
 * `--limit INTEGER`: Limit the number of results.  [default: 10]
 * `--expand TEXT`: Comma-separated properties to return. When used, only the listed properties (and id) are returned. Example: '--expand=downloads,likes,tags'. Valid: author, baseModels, cardData, childrenModelCount, config, createdAt, disabled, downloads, downloadsAllTime, evalResults, gated, gguf, inference, inferenceProviderMapping, lastModified, library_name, likes, mask_token, model-index, pipeline_tag, private, resourceGroup, safetensors, sha, siblings, spaces, tags, transformersInfo, trendingScore, usedStorage, widgetData.
-* `--format [table|json]`: Output format (table or json).  [default: table]
-* `-q, --quiet`: Print only IDs (one per line).
+* `--format [agent|auto|human|json|quiet]`: Output format.  [default: auto]
 * `--token TEXT`: A User Access Token generated from https://huggingface.co/settings/tokens.
 * `--help`: Show this message and exit.
 
@@ -2678,7 +2677,7 @@ $ hf papers [OPTIONS] COMMAND [ARGS]...
 
 ### `hf papers info`
 
-Get info about a paper on the Hub. Output is in JSON format.
+Get info about a paper on the Hub.
 
 **Usage**:
 
@@ -2692,6 +2691,7 @@ $ hf papers info [OPTIONS] PAPER_ID
 
 **Options**:
 
+* `--format [agent|auto|human|json|quiet]`: Output format.  [default: auto]
 * `--token TEXT`: A User Access Token generated from https://huggingface.co/settings/tokens.
 * `--help`: Show this message and exit.
 
@@ -2721,8 +2721,7 @@ $ hf papers list [OPTIONS]
 * `--submitter TEXT`: Filter by username of the submitter.
 * `--sort [publishedAt|trending]`: Sort results.
 * `--limit INTEGER`: Limit the number of results.  [default: 50]
-* `--format [table|json]`: Output format (table or json).  [default: table]
-* `-q, --quiet`: Print only IDs (one per line).
+* `--format [agent|auto|human|json|quiet]`: Output format.  [default: auto]
 * `--token TEXT`: A User Access Token generated from https://huggingface.co/settings/tokens.
 * `--help`: Show this message and exit.
 
@@ -2783,8 +2782,7 @@ $ hf papers search [OPTIONS] QUERY
 **Options**:
 
 * `--limit INTEGER`: Limit the number of results.  [default: 20]
-* `--format [table|json]`: Output format (table or json).  [default: table]
-* `-q, --quiet`: Print only IDs (one per line).
+* `--format [agent|auto|human|json|quiet]`: Output format.  [default: auto]
 * `--token TEXT`: A User Access Token generated from https://huggingface.co/settings/tokens.
 * `--help`: Show this message and exit.
 
@@ -3434,7 +3432,7 @@ Learn more
 
 ### `hf spaces info`
 
-Get info about a space on the Hub. Output is in JSON format.
+Get info about a space on the Hub.
 
 **Usage**:
 
@@ -3450,6 +3448,7 @@ $ hf spaces info [OPTIONS] SPACE_ID
 
 * `--revision TEXT`: Git revision id which can be a branch name, a tag, or a commit hash.
 * `--expand TEXT`: Comma-separated properties to return. When used, only the listed properties (and id) are returned. Example: '--expand=likes,tags'. Valid: author, cardData, createdAt, datasets, disabled, lastModified, likes, models, private, resourceGroup, runtime, sdk, sha, siblings, subdomain, tags, trendingScore, usedStorage.
+* `--format [agent|auto|human|json|quiet]`: Output format.  [default: auto]
 * `--token TEXT`: A User Access Token generated from https://huggingface.co/settings/tokens.
 * `--help`: Show this message and exit.
 
@@ -3480,8 +3479,7 @@ $ hf spaces list [OPTIONS]
 * `--sort [created_at|last_modified|likes|trending_score]`: Sort results.
 * `--limit INTEGER`: Limit the number of results.  [default: 10]
 * `--expand TEXT`: Comma-separated properties to return. When used, only the listed properties (and id) are returned. Example: '--expand=likes,tags'. Valid: author, cardData, createdAt, datasets, disabled, lastModified, likes, models, private, resourceGroup, runtime, sdk, sha, siblings, subdomain, tags, trendingScore, usedStorage.
-* `--format [table|json]`: Output format (table or json).  [default: table]
-* `-q, --quiet`: Print only IDs (one per line).
+* `--format [agent|auto|human|json|quiet]`: Output format.  [default: auto]
 * `--token TEXT`: A User Access Token generated from https://huggingface.co/settings/tokens.
 * `--help`: Show this message and exit.
 

src/huggingface_hub/cli/_output.py

@@ -13,6 +13,7 @@
 # limitations under the License.
 """Output framework for the `hf` CLI."""
 
+import dataclasses
 import datetime
 import json
 import re
@@ -72,25 +73,33 @@ def text(self, msg: str | None = None, *, human: str | None = None, agent: str |
 
     def table(
         self,
-        headers: list[str],
-        rows: Sequence[list[Any]],
+        items: Sequence[dict[str, Any]],
+        *,
+        headers: list[str] | None = None,
+        id_key: str | None = None,
         alignments: dict[str, str] | None = None,
     ) -> None:
         """Print tabular data to stdout.
 
         Args:
-            headers: Column names.
-            rows: List of rows, each a list of raw values.
+            items: List of dicts. Headers are auto-detected from keys if not provided.
+            headers: Explicit column names. If None, derived from dict keys (all-None columns filtered).
+            id_key: Key to print in quiet mode. If None, uses the first header.
             alignments: Optional mapping of header name to "left" or "right". Defaults to "left".
         """
-        if not rows:
+        if not items:
             match self.mode:
                 case OutputFormatWithAuto.agent | OutputFormatWithAuto.human:
                     print("No results found.")
                 case OutputFormatWithAuto.json:
                     print("[]")
             return
 
+        if headers is None:
+            all_columns = list(items[0].keys())
+            headers = [col for col in all_columns if any(item.get(col) is not None for item in items)]
+        rows = [[item.get(h) for h in headers] for item in items]
+
         match self.mode:
             case OutputFormatWithAuto.human:  # padded table, truncated cells, SCREAMING_SNAKE headers
                 formatted_rows: list[list[str | int]] = [[_format_table_cell_human(v) for v in row] for row in rows]
@@ -102,14 +111,19 @@ def table(
                 for row in rows:
                     print("\t".join(_format_table_cell_agent(v) for v in row))
             case OutputFormatWithAuto.json:  # compact JSON array
-                items = [dict(zip(headers, row)) for row in rows]
-                print(json.dumps(items, default=str))
-            case OutputFormatWithAuto.quiet:  # first column only, one per line
-                for row in rows:
-                    print(row[0])
+                print(json.dumps(list(items), default=str))
+            case OutputFormatWithAuto.quiet:  # id_key column (or first column), one per line
+                quiet_key = id_key or headers[0]
+                for item in items:
+                    print(item.get(quiet_key, ""))
+
+    def dict(self, data: Any) -> None:
+        """Print structured data as JSON in all modes (indented for human, compact otherwise).
 
-    def dict(self, data: dict[str, Any]) -> None:
-        """Print structured data as JSON in all modes (indented for human, compact otherwise)."""
+        Accepts a dict or a dataclass.
+        """
+        if dataclasses.is_dataclass(data) and not isinstance(data, type):
+            data = _dataclass_to_dict(data)
         indent = 2 if self.mode == OutputFormatWithAuto.human else None
         print(json.dumps(data, indent=indent, default=str))
 
@@ -156,6 +170,23 @@ def hint(self, message: str) -> None:
 
 # HELPERS
 
+
+def _serialize_value(v: object) -> object:
+    """Recursively serialize a value to be JSON-compatible."""
+    if isinstance(v, datetime.datetime):
+        return v.isoformat()
+    elif isinstance(v, dict):
+        return {key: _serialize_value(val) for key, val in v.items() if val is not None}
+    elif isinstance(v, list):
+        return [_serialize_value(item) for item in v]
+    return v
+
+
+def _dataclass_to_dict(info: Any) -> dict[str, Any]:
+    """Convert a dataclass to a json-serializable dict."""
+    return {k: _serialize_value(v) for k, v in dataclasses.asdict(info).items() if v is not None}
+
+
 _ANSI_RE = re.compile(r"\033\[[0-9;]*m")
 _MAX_CELL_LENGTH = 35
 
@@ -172,7 +203,7 @@ def _to_header(name: str) -> str:
 
 def _format_table_value_human(value: Any) -> str:
     """Convert a value to string for terminal display."""
-    if not value:
+    if value is None:
         return ""
     if isinstance(value, bool):
         return "✔" if value else ""

src/huggingface_hub/cli/datasets.py

@@ -25,7 +25,6 @@
 """
 
 import enum
-import json
 from typing import Annotated, get_args
 
 import typer
@@ -37,19 +36,17 @@
 from ._cli_utils import (
     AuthorOpt,
     FilterOpt,
-    FormatOpt,
+    FormatWithAutoOpt,
     LimitOpt,
-    OutputFormat,
-    QuietOpt,
     RevisionOpt,
     SearchOpt,
     TokenOpt,
     api_object_to_dict,
     get_hf_api,
     make_expand_properties_parser,
-    print_list_output,
     typer_factory,
 )
+from ._output import OutputFormatWithAuto, out
 
 
 _EXPAND_PROPERTIES = sorted(get_args(ExpandDatasetProperty_T))
@@ -87,8 +84,7 @@ def datasets_ls(
     ] = None,
     limit: LimitOpt = 10,
     expand: ExpandOpt = None,
-    format: FormatOpt = OutputFormat.table,
-    quiet: QuietOpt = False,
+    format: FormatWithAutoOpt = OutputFormatWithAuto.auto,
     token: TokenOpt = None,
 ) -> None:
     """List datasets on the Hub."""
@@ -105,7 +101,7 @@ def datasets_ls(
             expand=expand,  # type: ignore
         )
     ]
-    print_list_output(results, format=format, quiet=quiet)
+    out.table(results)
 
 
 @datasets_cli.command(
@@ -119,17 +115,18 @@ def datasets_info(
     dataset_id: Annotated[str, typer.Argument(help="The dataset ID (e.g. `username/repo-name`).")],
     revision: RevisionOpt = None,
     expand: ExpandOpt = None,
+    format: FormatWithAutoOpt = OutputFormatWithAuto.auto,
     token: TokenOpt = None,
 ) -> None:
-    """Get info about a dataset on the Hub. Output is in JSON format."""
+    """Get info about a dataset on the Hub."""
     api = get_hf_api(token=token)
     try:
         info = api.dataset_info(repo_id=dataset_id, revision=revision, expand=expand)  # type: ignore
     except RepositoryNotFoundError as e:
         raise CLIError(f"Dataset '{dataset_id}' not found.") from e
     except RevisionNotFoundError as e:
         raise CLIError(f"Revision '{revision}' not found on '{dataset_id}'.") from e
-    print(json.dumps(api_object_to_dict(info), indent=2))
+    out.dict(info)
 
 
 @datasets_cli.command(
@@ -145,8 +142,7 @@ def datasets_parquet(
     dataset_id: Annotated[str, typer.Argument(help="The dataset ID (e.g. `username/repo-name`).")],
     subset: Annotated[str | None, typer.Option("--subset", help="Filter parquet entries by subset/config.")] = None,
     split: Annotated[str | None, typer.Option(help="Filter parquet entries by split.")] = None,
-    format: FormatOpt = OutputFormat.table,
-    quiet: QuietOpt = False,
+    format: FormatWithAutoOpt = OutputFormatWithAuto.auto,
     token: TokenOpt = None,
 ) -> None:
     """List parquet file URLs available for a dataset."""
@@ -156,7 +152,7 @@ def datasets_parquet(
     results = [
         {"subset": entry.config, "split": entry.split, "url": entry.url, "size": entry.size} for entry in filtered
     ]
-    print_list_output(results, format=format, quiet=quiet, id_key="url")
+    out.table(results, headers=["subset", "split", "url", "size"], id_key="url")
 
 
 @datasets_cli.command(
@@ -168,13 +164,12 @@ def datasets_parquet(
 )
 def datasets_sql(
     sql: Annotated[str, typer.Argument(help="Raw SQL query to execute.")],
-    format: FormatOpt = OutputFormat.table,
+    format: FormatWithAutoOpt = OutputFormatWithAuto.auto,
     token: TokenOpt = None,
 ) -> None:
     """Execute a raw SQL query with DuckDB against dataset parquet URLs."""
     try:
         result = execute_raw_sql_query(sql_query=sql, token=token)
     except ImportError as e:
         raise CLIError(str(e)) from e
-
-    print_list_output(result, format=format, quiet=False)
+    out.table(result)