Deprecate library/tags/task/... filtering in list_models (#3318)

* Deprecate library/tags/task/... filtering in list_models

* adapt docs

* expect deprecation in tests

---------

Co-authored-by: Celina Hanouti <[email protected]>

Author: Wauplin

docs/source/en/guides/search.md

@@ -33,11 +33,7 @@ The list helpers have several attributes like:
 Let's see an example to get all models on the Hub that does image classification, have been trained on the imagenet dataset and that runs with PyTorch.
 
 ```py
-models = hf_api.list_models(
-	task="image-classification",
-	library="pytorch",
-	trained_dataset="imagenet",
-)
+models = hf_api.list_models(filter=["image-classification", "pytorch", "imagenet"])
 ```
 
 While filtering, you can also sort the models and take only the top results. For example,

src/huggingface_hub/hf_api.py

@@ -137,7 +137,7 @@
     _get_token_from_file,
     _get_token_from_google_colab,
 )
-from .utils._deprecation import _deprecate_method
+from .utils._deprecation import _deprecate_arguments, _deprecate_method
 from .utils._runtime import is_xet_available
 from .utils._typing import CallableT
 from .utils.endpoint_helpers import _is_emission_within_threshold
@@ -1855,6 +1855,9 @@ def get_dataset_tags(self) -> Dict:
         hf_raise_for_status(r)
         return r.json()
 
+    @_deprecate_arguments(
+        version="1.0", deprecated_args=["language", "library", "task", "tags"], custom_message="Use `filter` instead."
+    )
     @validate_hf_hub_args
     def list_models(
         self,
@@ -1865,12 +1868,8 @@ def list_models(
         gated: Optional[bool] = None,
         inference: Optional[Literal["warm"]] = None,
         inference_provider: Optional[Union[Literal["all"], "PROVIDER_T", List["PROVIDER_T"]]] = None,
-        library: Optional[Union[str, List[str]]] = None,
-        language: Optional[Union[str, List[str]]] = None,
         model_name: Optional[str] = None,
-        task: Optional[Union[str, List[str]]] = None,
         trained_dataset: Optional[Union[str, List[str]]] = None,
-        tags: Optional[Union[str, List[str]]] = None,
         search: Optional[str] = None,
         pipeline_tag: Optional[str] = None,
         emissions_thresholds: Optional[Tuple[float, float]] = None,
@@ -1884,13 +1883,19 @@ def list_models(
         cardData: bool = False,
         fetch_config: bool = False,
         token: Union[bool, str, None] = None,
+        # Deprecated arguments - use `filter` instead
+        language: Optional[Union[str, List[str]]] = None,
+        library: Optional[Union[str, List[str]]] = None,
+        tags: Optional[Union[str, List[str]]] = None,
+        task: Optional[Union[str, List[str]]] = None,
     ) -> Iterable[ModelInfo]:
         """
         List models hosted on the Huggingface Hub, given some filters.
 
         Args:
             filter (`str` or `Iterable[str]`, *optional*):
                 A string or list of string to filter models on the Hub.
+                Models can be filtered by library, language, task, tags, and more.
             author (`str`, *optional*):
                 A string which identify the author (user or organization) of the
                 returned models.
@@ -1904,23 +1909,19 @@ def list_models(
                 A string to filter models on the Hub that are served by a specific provider.
                 Pass `"all"` to get all models served by at least one provider.
             library (`str` or `List`, *optional*):
-                A string or list of strings of foundational libraries models were
-                originally trained from, such as pytorch, tensorflow, or allennlp.
+                Deprecated. Pass a library name in `filter` to filter models by library.
             language (`str` or `List`, *optional*):
-                A string or list of strings of languages, both by name and country
-                code, such as "en" or "English"
+                Deprecated. Pass a language in `filter` to filter models by language.
             model_name (`str`, *optional*):
                 A string that contain complete or partial names for models on the
                 Hub, such as "bert" or "bert-base-cased"
             task (`str` or `List`, *optional*):
-                A string or list of strings of tasks models were designed for, such
-                as: "fill-mask" or "automatic-speech-recognition"
+                Deprecated. Pass a task in `filter` to filter models by task.
             trained_dataset (`str` or `List`, *optional*):
                 A string tag or a list of string tags of the trained dataset for a
                 model on the Hub.
             tags (`str` or `List`, *optional*):
-                A string tag or a list of tags to filter models on the Hub by, such
-                as `text-generation` or `spacy`.
+                Deprecated. Pass tags in `filter` to filter models by tags.
             search (`str`, *optional*):
                 A string that will be contained in the returned model ids.
             pipeline_tag (`str`, *optional*):
@@ -1991,7 +1992,7 @@ def list_models(
         if expand and (full or cardData or fetch_config):
             raise ValueError("`expand` cannot be used if `full`, `cardData` or `fetch_config` are passed.")
 
-        if emissions_thresholds is not None and cardData is None:
+        if emissions_thresholds is not None and not cardData:
             raise ValueError("`emissions_thresholds` were passed without setting `cardData=True`.")
 
         path = f"{self.endpoint}/api/models"
@@ -2074,6 +2075,7 @@ def list_models(
             if emissions_thresholds is None or _is_emission_within_threshold(model_info, *emissions_thresholds):
                 yield model_info
 
+    @_deprecate_arguments(version="1.0", deprecated_args=["tags"], custom_message="Use `filter` instead.")
     @validate_hf_hub_args
     def list_datasets(
         self,
@@ -2088,7 +2090,6 @@ def list_datasets(
         language: Optional[Union[str, List[str]]] = None,
         multilinguality: Optional[Union[str, List[str]]] = None,
         size_categories: Optional[Union[str, List[str]]] = None,
-        tags: Optional[Union[str, List[str]]] = None,
         task_categories: Optional[Union[str, List[str]]] = None,
         task_ids: Optional[Union[str, List[str]]] = None,
         search: Optional[str] = None,
@@ -2100,6 +2101,8 @@ def list_datasets(
         expand: Optional[List[ExpandDatasetProperty_T]] = None,
         full: Optional[bool] = None,
         token: Union[bool, str, None] = None,
+        # Deprecated arguments - use `filter` instead
+        tags: Optional[Union[str, List[str]]] = None,
     ) -> Iterable[DatasetInfo]:
         """
         List datasets hosted on the Huggingface Hub, given some filters.
@@ -2134,7 +2137,7 @@ def list_datasets(
                 the Hub by the size of the dataset such as `100K<n<1M` or
                 `1M<n<10M`.
             tags (`str` or `List`, *optional*):
-                A string tag or a list of tags to filter datasets on the Hub.
+                Deprecated. Pass tags in `filter` to filter datasets by tags.
             task_categories (`str` or `List`, *optional*):
                 A string or list of strings that can be used to identify datasets on
                 the Hub by the designed task, such as `audio_classification` or

tests/test_hf_api.py

@@ -2168,6 +2168,7 @@ def test_filter_datasets_with_card_data(self):
         assert any(dataset.card_data is not None for dataset in self._api.list_datasets(full=True, limit=50))
         assert all(dataset.card_data is None for dataset in self._api.list_datasets(full=False, limit=50))
 
+    @expect_deprecation("list_datasets")
     def test_filter_datasets_by_tag(self):
         for dataset in self._api.list_datasets(tags="fiftyone", limit=5):
             assert "fiftyone" in dataset.tags
@@ -2278,13 +2279,15 @@ def test_failing_filter_models_by_author_and_model_name(self):
         models = list(self._api.list_models(author="muellerzr", model_name="testme"))
         assert len(models) == 0
 
+    @expect_deprecation("list_models")
     def test_filter_models_with_library(self):
         models = list(self._api.list_models(author="microsoft", model_name="wavlm-base-sd", library="tensorflow"))
         assert len(models) == 0
 
         models = list(self._api.list_models(author="microsoft", model_name="wavlm-base-sd", library="pytorch"))
         assert len(models) > 0
 
+    @expect_deprecation("list_models")
     def test_filter_models_with_task(self):
         models = list(self._api.list_models(task="fill-mask", model_name="albert-base-v2"))
         assert models[0].pipeline_tag == "fill-mask"
@@ -2295,11 +2298,13 @@ def test_filter_models_with_task(self):
         models = list(self._api.list_models(task="dummytask"))
         assert len(models) == 0
 
+    @expect_deprecation("list_models")
     def test_filter_models_by_language(self):
         for language in ["en", "fr", "zh"]:
             for model in self._api.list_models(language=language, limit=5):
                 assert language in model.tags
 
+    @expect_deprecation("list_models")
     def test_filter_models_with_tag(self):
         models = list(self._api.list_models(author="HuggingFaceBR4", tags=["tensorboard"]))
         assert models[0].id.startswith("HuggingFaceBR4/")