Deprecate model_name in favor of search in list_models (#4112)

* Deprecate list_models(..., model_name='...')

* seriously?

* use search

Author: Wauplin

src/huggingface_hub/hf_api.py

@@ -2327,6 +2327,7 @@ def get_dataset_tags(self) -> dict:
         hf_raise_for_status(r)
         return r.json()
 
+    @_deprecate_arguments(version="2.0", deprecated_args=["model_name"], custom_message="Use `search` instead.")
     @validate_hf_hub_args
     def list_models(
         self,
@@ -2376,9 +2377,6 @@ def list_models(
             inference_provider (`Literal["all"]` or `str`, *optional*):
                 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.
-            model_name (`str`, *optional*):
-                A string that contain complete or partial names for models on the
-                Hub, such as "bert" or "bert-base-cased"
             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.
@@ -2418,7 +2416,8 @@ def list_models(
                 token, which is the recommended method for authentication (see
                 https://huggingface.co/docs/huggingface_hub/quick-start#authentication).
                 To disable authentication, pass `False`.
-
+            model_name (`str`, *optional*):
+                (deprecated). Use `search` instead.
 
         Returns:
             `Iterable[ModelInfo]`: an iterable of [`huggingface_hub.hf_api.ModelInfo`] objects.
@@ -2490,7 +2489,7 @@ def list_models(
         if num_parameters is not None:
             params["num_parameters"] = num_parameters
         search_list = []
-        if model_name:
+        if model_name:  # deprecated
             search_list.append(model_name)
         if search:
             search_list.append(search)

tests/test_hf_api.py

@@ -2424,23 +2424,23 @@ def test_filter_models_by_author(self):
 
     def test_filter_models_by_author_and_name(self):
         # Test we can search by an author and a name, but the model is not found
-        models = list(self._api.list_models(author="facebook", model_name="bart-base"))
+        models = list(self._api.list_models(author="facebook", search="bart-base"))
         assert "facebook/bart-base" in models[0].id
 
-    def test_failing_filter_models_by_author_and_model_name(self):
+    def test_failing_filter_models_by_author_and_search(self):
         # Test we can search by an author and a name, but the model is not found
-        models = list(self._api.list_models(author="muellerzr", model_name="testme"))
+        models = list(self._api.list_models(author="muellerzr", search="testme"))
         assert len(models) == 0
 
     def test_filter_models_with_library(self):
-        models = list(self._api.list_models(author="microsoft", model_name="wavlm-base-sd", filter="tensorflow"))
+        models = list(self._api.list_models(author="microsoft", search="wavlm-base-sd", filter="tensorflow"))
         assert len(models) == 0
 
-        models = list(self._api.list_models(author="microsoft", model_name="wavlm-base-sd", filter="pytorch"))
+        models = list(self._api.list_models(author="microsoft", search="wavlm-base-sd", filter="pytorch"))
         assert len(models) > 0
 
     def test_filter_models_with_task(self):
-        models = list(self._api.list_models(filter="fill-mask", model_name="albert-base-v2"))
+        models = list(self._api.list_models(filter="fill-mask", search="albert-base-v2"))
         assert models[0].pipeline_tag == "fill-mask"
         assert "albert" in models[0].id
         assert "base" in models[0].id