Feature: switch visibility with update_repo_settings #2537

docs/source/en/guides/repository.md

@@ -146,18 +146,20 @@ an organization). In this section, we will see the settings that you can also co
 
 Some settings are specific to Spaces (hardware, environment variables,...). To configure those, please refer to our [Manage your Spaces](../guides/manage-spaces) guide.
 
-### Update visibility
+### Update Visibility
 
 A repository can be public or private. A private repository is only visible to you or members of the organization in which the repository is located. Change a repository to private as shown in the following:
 
 ```py
->>> from huggingface_hub import update_repo_visibility
->>> update_repo_visibility(repo_id=repo_id, private=True)
+>>> from huggingface_hub import HfApi
+
+>>> api = HfApi()
+>>> api.update_repo_settings(repo_id=repo_id, private=True)
 ```
 
 ### Setup gated access
 
-To give more control over how repos are used, the Hub allows repo authors to enable **access requests** for their repos. User must agree to share their contact information (username and email address) with the repo authors to access the files when enabled. A repo with access requests enabled is called a **gated repo**.
+To give more control over how repos are used, the Hub allows repo authors to enable access requests for their repos. User must agree to share their contact information (username and email address) with the repo authors to access the files when enabled. A repo with access requests enabled is called a gated repo.
 
 You can set a repo as gated using [`update_repo_settings`]:
 

src/huggingface_hub/hf_api.py

@@ -3524,6 +3524,7 @@ def delete_repo(
             if not missing_ok:
                 raise
 
+    @_deprecate_method(version="0.29", message="Please use `update_repo_settings` instead.")
     @validate_hf_hub_args
     def update_repo_visibility(
         self,
@@ -3535,6 +3536,8 @@ def update_repo_visibility(
     ) -> Dict[str, bool]:
         """Update the visibility setting of a repository.
 
+        Deprecated. Use `update_repo_settings` instead.
+
         Args:
             repo_id (`str`, *optional*):
                 A namespace (user or an organization) and a repo name separated by a `/`.
@@ -3581,13 +3584,16 @@ def update_repo_settings(
         self,
         repo_id: str,
         *,
-        gated: Literal["auto", "manual", False] = False,
+        gated: Optional[Literal["auto", "manual", False]] = None,
+        private: Optional[bool] = None,
         token: Union[str, bool, None] = None,
         repo_type: Optional[str] = None,
     ) -> None:
         """
-        Update the gated settings of a repository.
-        To give more control over how repos are used, the Hub allows repo authors to enable **access requests** for their repos.
+        Update the settings of a repository, including gated access and visibility.
+
+        To give more control over how repos are used, the Hub allows repo authors to enable
+        access requests for their repos, and also to set the visibility of the repo to private.
 
         Args:
             repo_id (`str`):
@@ -3596,14 +3602,16 @@ def update_repo_settings(
                 The gated release status for the repository.
                 * "auto": The repository is gated, and access requests are automatically approved or denied based on predefined criteria.
                 * "manual": The repository is gated, and access requests require manual approval.
-                * False (default): The repository is not gated, and anyone can access it.
+                * False : The gated status for the repository. If set to `None` (default), the `gated` setting of the repository won't be updated.
+            private (`bool`, *optional*):
+                Whether the model repo should be private.
             token (`Union[str, bool, None]`, *optional*):
                 A valid user access token (string). Defaults to the locally saved token,
                 which is the recommended method for authentication (see
                 https://huggingface.co/docs/huggingface_hub/quick-start#authentication).
                 To disable authentication, pass False.
             repo_type (`str`, *optional*):
-                The type of the repository to update settings from (`"model"`, `"dataset"` or `"space"`.
+                The type of the repository to update settings from (`"model"`, `"dataset"` or `"space"`).
                 Defaults to `"model"`.
 
         Raises:
@@ -3613,22 +3621,38 @@ def update_repo_settings(
                 If repo_type is not one of the values in constants.REPO_TYPES.
             [`~utils.HfHubHTTPError`]:
                 If the request to the Hugging Face Hub API fails.
+            [`~utils.RepositoryNotFoundError`]
+                If the repository to download from cannot be found. This may be because it doesn't exist,
+                or because it is set to `private` and you do not have access.
         """
-        if gated not in ["auto", "manual", False]:
-            raise ValueError(f"Invalid gated status, must be one of 'auto', 'manual', or False. Got '{gated}'.")
 
         if repo_type not in constants.REPO_TYPES:
             raise ValueError(f"Invalid repo type, must be one of {constants.REPO_TYPES}")
         if repo_type is None:
             repo_type = constants.REPO_TYPE_MODEL  # default repo type
 
+        # Check if both gated and private are None
+        if gated is None and private is None:
+            raise ValueError("At least one of 'gated' or 'private' must be provided.")
+
         # Build headers
         headers = self._build_hf_headers(token=token)
 
+        # Prepare the JSON payload for the PUT request
+        payload: Dict = {}
+
+        if gated is not None:
+            if gated not in ["auto", "manual", False]:
+                raise ValueError(f"Invalid gated status, must be one of 'auto', 'manual', or False. Got '{gated}'.")
+            payload["gated"] = gated
+
+        if private is not None:
+            payload["private"] = private
+
         r = get_session().put(
             url=f"{self.endpoint}/api/{repo_type}s/{repo_id}/settings",
             headers=headers,
-            json={"gated": gated},
+            json=payload,
         )
         hf_raise_for_status(r)
 

tests/test_file_download.py

@@ -161,6 +161,7 @@ def test_download_from_a_gated_repo_with_hf_hub_download(self, repo_url: RepoUrl
                     repo_id=repo_url.repo_id, filename=".gitattributes", token=OTHER_TOKEN, cache_dir=tmpdir
                 )
 
+    @expect_deprecation("update_repo_visibility")
     @use_tmp_repo()
     def test_download_regular_file_from_private_renamed_repo(self, repo_url: RepoUrl) -> None:
         """Regression test for #1999.

tests/test_hf_api.py

@@ -93,6 +93,7 @@
     DUMMY_MODEL_ID_REVISION_ONE_SPECIFIC_COMMIT,
     ENDPOINT_PRODUCTION,
     SAMPLE_DATASET_IDENTIFIER,
+    expect_deprecation,
     repo_name,
     require_git_lfs,
     rmtree_with_retry,
@@ -124,6 +125,7 @@ def setUpClass(cls):
         cls._api = HfApi(endpoint=ENDPOINT_STAGING, token=TOKEN)
 
 
+@expect_deprecation("update_repo_visibility")
 def test_repo_id_no_warning():
     # tests that passing repo_id as positional arg doesn't raise any warnings
     # for {create, delete}_repo and update_repo_visibility
@@ -210,6 +212,7 @@ def test_delete_repo_error_message(self):
     def test_delete_repo_missing_ok(self) -> None:
         self._api.delete_repo("repo-that-does-not-exist", missing_ok=True)
 
+    @expect_deprecation("update_repo_visibility")
     def test_create_update_and_delete_repo(self):
         repo_id = self._api.create_repo(repo_id=repo_name()).repo_id
         res = self._api.update_repo_visibility(repo_id=repo_id, private=True)
@@ -218,6 +221,7 @@ def test_create_update_and_delete_repo(self):
         assert not res["private"]
         self._api.delete_repo(repo_id=repo_id)
 
+    @expect_deprecation("update_repo_visibility")
     def test_create_update_and_delete_model_repo(self):
         repo_id = self._api.create_repo(repo_id=repo_name(), repo_type=constants.REPO_TYPE_MODEL).repo_id
         res = self._api.update_repo_visibility(repo_id=repo_id, private=True, repo_type=constants.REPO_TYPE_MODEL)
@@ -226,6 +230,7 @@ def test_create_update_and_delete_model_repo(self):
         assert not res["private"]
         self._api.delete_repo(repo_id=repo_id, repo_type=constants.REPO_TYPE_MODEL)
 
+    @expect_deprecation("update_repo_visibility")
     def test_create_update_and_delete_dataset_repo(self):
         repo_id = self._api.create_repo(repo_id=repo_name(), repo_type=constants.REPO_TYPE_DATASET).repo_id
         res = self._api.update_repo_visibility(repo_id=repo_id, private=True, repo_type=constants.REPO_TYPE_DATASET)
@@ -234,6 +239,7 @@ def test_create_update_and_delete_dataset_repo(self):
         assert not res["private"]
         self._api.delete_repo(repo_id=repo_id, repo_type=constants.REPO_TYPE_DATASET)
 
+    @expect_deprecation("update_repo_visibility")
     def test_create_update_and_delete_space_repo(self):
         with pytest.raises(ValueError, match=r"No space_sdk provided.*"):
             self._api.create_repo(repo_id=repo_name(), repo_type=constants.REPO_TYPE_SPACE, space_sdk=None)
@@ -286,19 +292,25 @@ def test_update_repo_settings(self, repo_url: RepoUrl):
         repo_id = repo_url.repo_id
 
         for gated_value in ["auto", "manual", False]:
-            self._api.update_repo_settings(repo_id=repo_id, gated=gated_value)
-            info = self._api.model_info(repo_id, expand="gated")
-            assert info.gated == gated_value
+            for private_value in [True, False]:  # Test both private and public settings
+                self._api.update_repo_settings(repo_id=repo_id, gated=gated_value, private=private_value)
+                info = self._api.model_info(repo_id)
+                assert info.gated == gated_value
+                assert info.private == private_value  # Verify the private setting
 
     @use_tmp_repo(repo_type="dataset")
     def test_update_dataset_repo_settings(self, repo_url: RepoUrl):
         repo_id = repo_url.repo_id
         repo_type = repo_url.repo_type
 
         for gated_value in ["auto", "manual", False]:
-            self._api.update_repo_settings(repo_id=repo_id, repo_type=repo_type, gated=gated_value)
-            info = self._api.dataset_info(repo_id, expand="gated")
-            assert info.gated == gated_value
+            for private_value in [True, False]:
+                self._api.update_repo_settings(
+                    repo_id=repo_id, repo_type=repo_type, gated=gated_value, private=private_value
+                )
+                info = self._api.dataset_info(repo_id)
+                assert info.gated == gated_value
+                assert info.private == private_value
 
 
 class CommitApiTest(HfApiCommonTest):

tests/test_snapshot_download.py

@@ -8,7 +8,7 @@
 from huggingface_hub.utils import SoftTemporaryDirectory
 
 from .testing_constants import TOKEN
-from .testing_utils import OfflineSimulationMode, offline, repo_name
+from .testing_utils import OfflineSimulationMode, expect_deprecation, offline, repo_name
 
 
 class SnapshotDownloadTests(unittest.TestCase):
@@ -95,6 +95,7 @@ def test_download_model(self):
             # folder name contains the revision's commit sha.
             self.assertTrue(self.first_commit_hash in storage_folder)
 
+    @expect_deprecation("update_repo_visibility")
     def test_download_private_model(self):
         self.api.update_repo_visibility(repo_id=self.repo_id, private=True)