huggingface-hub 0.12.1__py3-none-any.whl → 0.13.0rc0__py3-none-any.whl

huggingface_hub/hub_mixin.py

@@ -1,7 +1,8 @@
 import json
 import os
+import warnings
 from pathlib import Path
-from typing import Dict, List, Optional, Union
+from typing import Dict, List, Optional, Type, TypeVar, Union
 
 import requests
 
@@ -9,6 +10,7 @@ from .constants import CONFIG_NAME, PYTORCH_WEIGHTS_NAME
 from .file_download import hf_hub_download, is_torch_available
 from .hf_api import HfApi
 from .utils import SoftTemporaryDirectory, logging, validate_hf_hub_args
+from .utils._deprecation import _deprecate_positional_args
 
 
 if is_torch_available():
@@ -16,149 +18,131 @@ if is_torch_available():
 
 logger = logging.get_logger(__name__)
 
+# Generic variable that is either ModelHubMixin or a subclass thereof
+T = TypeVar("T", bound="ModelHubMixin")
+
 
 class ModelHubMixin:
     """
-    A generic Hub mixin for machine learning models. Define your own mixin for
-    any framework by inheriting from this class and overwriting the
-    [`_from_pretrained`] and [`_save_pretrained`] methods to define custom logic
-    for saving and loading your classes. See [`PyTorchModelHubMixin`] for an
-    example.
+    A generic mixin to integrate ANY machine learning framework with the Hub.
+
+    To integrate your framework, your model class must inherit from this class. Custom logic for saving/loading models
+    have to be overwritten in  [`_from_pretrained`] and [`_save_pretrained`]. [`PyTorchModelHubMixin`] is a good example
+    of mixin integration with the Hub. Check out our [integration guide](../guides/integrations) for more instructions.
     """
 
+    @_deprecate_positional_args(version="0.16")
     def save_pretrained(
         self,
         save_directory: Union[str, Path],
+        *,
         config: Optional[dict] = None,
+        repo_id: Optional[str] = None,
         push_to_hub: bool = False,
         **kwargs,
-    ):
+    ) -> Optional[str]:
         """
         Save weights in local directory.
 
-        Parameters:
+        Args:
             save_directory (`str` or `Path`):
-                Specify directory in which you want to save weights.
+                Path to directory in which the model weights and configuration will be saved.
             config (`dict`, *optional*):
-                Specify config (must be dict) in case you want to save
-                it.
+                Model configuration specified as a key/value dictionary.
             push_to_hub (`bool`, *optional*, defaults to `False`):
-                Whether or not to push your model to the Hugging Face Hub after
-                saving it. You can specify the repository you want to push to with
-                `repo_id` (will default to the name of `save_directory` in your
-                namespace).
+                Whether or not to push your model to the Huggingface Hub after saving it.
+            repo_id (`str`, *optional*):
+                ID of your repository on the Hub. Used only if `push_to_hub=True`. Will default to the folder name if
+                not provided.
             kwargs:
-                Additional key word arguments passed along to the
-                [`~utils.PushToHubMixin.push_to_hub`] method.
+                Additional key word arguments passed along to the [`~ModelHubMixin._from_pretrained`] method.
         """
-        os.makedirs(save_directory, exist_ok=True)
+        save_directory = Path(save_directory)
+        save_directory.mkdir(parents=True, exist_ok=True)
 
         # saving model weights/files
         self._save_pretrained(save_directory)
 
         # saving config
         if isinstance(config, dict):
-            path = os.path.join(save_directory, CONFIG_NAME)
-            with open(path, "w") as f:
-                json.dump(config, f)
+            (save_directory / CONFIG_NAME).write_text(json.dumps(config))
 
         if push_to_hub:
             kwargs = kwargs.copy()  # soft-copy to avoid mutating input
             if config is not None:  # kwarg for `push_to_hub`
                 kwargs["config"] = config
+            if repo_id is None:
+                repo_id = save_directory.name  # Defaults to `save_directory` name
+            return self.push_to_hub(repo_id=repo_id, **kwargs)
+        return None
 
-            if kwargs.get("repo_id") is None:
-                # Repo name defaults to `save_directory` name
-                kwargs["repo_id"] = Path(save_directory).name
-
-            return self.push_to_hub(**kwargs)
-
-    def _save_pretrained(self, save_directory: Union[str, Path]):
+    def _save_pretrained(self, save_directory: Path) -> None:
         """
         Overwrite this method in subclass to define how to save your model.
+        Check out our [integration guide](../guides/integrations) for instructions.
+
+        Args:
+            save_directory (`str` or `Path`):
+                Path to directory in which the model weights and configuration will be saved.
         """
         raise NotImplementedError
 
     @classmethod
     @validate_hf_hub_args
+    @_deprecate_positional_args(version="0.16")
     def from_pretrained(
-        cls,
-        pretrained_model_name_or_path: str,
+        cls: Type[T],
+        pretrained_model_name_or_path: Union[str, Path],
+        *,
         force_download: bool = False,
         resume_download: bool = False,
         proxies: Optional[Dict] = None,
         token: Optional[Union[str, bool]] = None,
-        cache_dir: Optional[str] = None,
+        cache_dir: Optional[Union[str, Path]] = None,
         local_files_only: bool = False,
+        revision: Optional[str] = None,
         **model_kwargs,
-    ):
-        r"""
-        Download and instantiate a model from the Hugging Face Hub.
-
-                Parameters:
-                    pretrained_model_name_or_path (`str` or `os.PathLike`):
-                        Can be either:
-                            - A string, the `model id` of a pretrained model
-                              hosted inside a model repo on huggingface.co.
-                              Valid model ids can be located at the root-level,
-                              like `bert-base-uncased`, or namespaced under a
-                              user or organization name, like
-                              `dbmdz/bert-base-german-cased`.
-                            - You can add `revision` by appending `@` at the end
-                              of model_id simply like this:
-                              `dbmdz/bert-base-german-cased@main` Revision is
-                              the specific model version to use. It can be a
-                              branch name, a tag name, or a commit id, since we
-                              use a git-based system for storing models and
-                              other artifacts on huggingface.co, so `revision`
-                              can be any identifier allowed by git.
-                            - A path to a `directory` containing model weights
-                              saved using
-                              [`~transformers.PreTrainedModel.save_pretrained`],
-                              e.g., `./my_model_directory/`.
-                            - `None` if you are both providing the configuration
-                              and state dictionary (resp. with keyword arguments
-                              `config` and `state_dict`).
-                    force_download (`bool`, *optional*, defaults to `False`):
-                        Whether to force the (re-)download of the model weights
-                        and configuration files, overriding the cached versions
-                        if they exist.
-                    resume_download (`bool`, *optional*, defaults to `False`):
-                        Whether to delete incompletely received files. Will
-                        attempt to resume the download if such a file exists.
-                    proxies (`Dict[str, str]`, *optional*):
-                        A dictionary of proxy servers to use by protocol or
-                        endpoint, e.g., `{'http': 'foo.bar:3128',
-                        'http://hostname': 'foo.bar:4012'}`. The proxies are
-                        used on each request.
-                    token (`str` or `bool`, *optional*):
-                        The token to use as HTTP bearer authorization for remote
-                        files. If `True`, will use the token generated when
-                        running `transformers-cli login` (stored in
-                        `~/.huggingface`).
-                    cache_dir (`Union[str, os.PathLike]`, *optional*):
-                        Path to a directory in which a downloaded pretrained
-                        model configuration should be cached if the standard
-                        cache should not be used.
-                    local_files_only(`bool`, *optional*, defaults to `False`):
-                        Whether to only look at local files (i.e., do not try to
-                        download the model).
-                    model_kwargs (`Dict`, *optional*):
-                        model_kwargs will be passed to the model during
-                        initialization
-
-                <Tip>
-
-                Passing `token=True` is required when you want to use a
-                private model.
-
-                </Tip>
+    ) -> T:
+        """
+        Download a model from the Huggingface Hub and instantiate it.
+
+        Args:
+            pretrained_model_name_or_path (`str`, `Path`):
+                - Either the `model_id` (string) of a model hosted on the Hub, e.g. `bigscience/bloom`.
+                - Or a path to a `directory` containing model weights saved using
+                    [`~transformers.PreTrainedModel.save_pretrained`], e.g., `../path/to/my_model_directory/`.
+            revision (`str`, *optional*):
+                Revision of the model on the Hub. Can be a branch name, a git tag or any commit id.
+                Defaults to the latest commit on `main` branch.
+            force_download (`bool`, *optional*, defaults to `False`):
+                Whether to force (re-)downloading the model weights and configuration files from the Hub, overriding
+                the existing cache.
+            resume_download (`bool`, *optional*, defaults to `False`):
+                Whether to delete incompletely received files. Will attempt to resume the download if such a file exists.
+            proxies (`Dict[str, str]`, *optional*):
+                A dictionary of proxy servers to use by protocol or endpoint, e.g., `{'http': 'foo.bar:3128',
+                'http://hostname': 'foo.bar:4012'}`. The proxies are used on every request.
+            token (`str` or `bool`, *optional*):
+                The token to use as HTTP bearer authorization for remote files. By default, it will use the token
+                cached when running `huggingface-cli login`.
+            cache_dir (`str`, `Path`, *optional*):
+                Path to the folder where cached files are stored.
+            local_files_only (`bool`, *optional*, defaults to `False`):
+                If `True`, avoid downloading the file and return the path to the local cached file if it exists.
+            model_kwargs (`Dict`, *optional*):
+                Additional kwargs to pass to the model during initialization.
         """
-
         model_id = pretrained_model_name_or_path
 
-        revision = None
-        if len(model_id.split("@")) == 2:
+        if isinstance(model_id, str) and len(model_id.split("@")) == 2:
+            warnings.warn(
+                (
+                    "Passing a revision using 'namespace/model_id@revision' pattern is"
+                    " deprecated and will be removed in version v0.16. Please pass"
+                    " 'revision=...' as argument."
+                ),
+                FutureWarning,
+            )
             model_id, revision = model_id.split("@")
 
         config_file: Optional[str] = None
@@ -167,10 +151,10 @@ class ModelHubMixin:
                 config_file = os.path.join(model_id, CONFIG_NAME)
             else:
                 logger.warning(f"{CONFIG_NAME} not found in {Path(model_id).resolve()}")
-        else:
+        elif isinstance(model_id, str):
             try:
                 config_file = hf_hub_download(
-                    repo_id=model_id,
+                    repo_id=str(model_id),
                     filename=CONFIG_NAME,
                     revision=revision,
                     cache_dir=cache_dir,
@@ -181,7 +165,7 @@ class ModelHubMixin:
                     local_files_only=local_files_only,
                 )
             except requests.exceptions.RequestException:
-                logger.warning(f"{CONFIG_NAME} not found in HuggingFace Hub")
+                logger.warning(f"{CONFIG_NAME} not found in HuggingFace Hub.")
 
         if config_file is not None:
             with open(config_file, "r", encoding="utf-8") as f:
@@ -189,32 +173,65 @@ class ModelHubMixin:
             model_kwargs.update({"config": config})
 
         return cls._from_pretrained(
-            model_id,
-            revision,
-            cache_dir,
-            force_download,
-            proxies,
-            resume_download,
-            local_files_only,
-            token,
+            model_id=model_id,
+            revision=revision,
+            cache_dir=cache_dir,
+            force_download=force_download,
+            proxies=proxies,
+            resume_download=resume_download,
+            local_files_only=local_files_only,
+            token=token,
             **model_kwargs,
         )
 
     @classmethod
+    @_deprecate_positional_args(version="0.16")
     def _from_pretrained(
-        cls,
-        model_id,
-        revision,
-        cache_dir,
-        force_download,
-        proxies,
-        resume_download,
-        local_files_only,
-        token,
+        cls: Type[T],
+        *,
+        model_id: str,
+        revision: Optional[str],
+        cache_dir: Optional[Union[str, Path]],
+        force_download: bool,
+        proxies: Optional[Dict],
+        resume_download: bool,
+        local_files_only: bool,
+        token: Optional[Union[str, bool]],
         **model_kwargs,
-    ):
-        """Overwrite this method in subclass to define how to load your model from
-        pretrained"""
+    ) -> T:
+        """Overwrite this method in subclass to define how to load your model from pretrained.
+
+        Use [`hf_hub_download`] or [`snapshot_download`] to download files from the Hub before loading them. Most
+        args taken as input can be directly passed to those 2 methods. If needed, you can add more arguments to this
+        method using "model_kwargs". For example [`PyTorchModelHubMixin._from_pretrained`] takes as input a `map_location`
+        parameter to set on which device the model should be loaded.
+
+        Check out our [integration guide](../guides/integrations) for more instructions.
+
+        Args:
+            model_id (`str`):
+                ID of the model to load from the Huggingface Hub (e.g. `bigscience/bloom`).
+            revision (`str`, *optional*):
+                Revision of the model on the Hub. Can be a branch name, a git tag or any commit id. Defaults to the
+                latest commit on `main` branch.
+            force_download (`bool`, *optional*, defaults to `False`):
+                Whether to force (re-)downloading the model weights and configuration files from the Hub, overriding
+                the existing cache.
+            resume_download (`bool`, *optional*, defaults to `False`):
+                Whether to delete incompletely received files. Will attempt to resume the download if such a file exists.
+            proxies (`Dict[str, str]`, *optional*):
+                A dictionary of proxy servers to use by protocol or endpoint (e.g., `{'http': 'foo.bar:3128',
+                'http://hostname': 'foo.bar:4012'}`).
+            token (`str` or `bool`, *optional*):
+                The token to use as HTTP bearer authorization for remote files. By default, it will use the token
+                cached when running `huggingface-cli login`.
+            cache_dir (`str`, `Path`, *optional*):
+                Path to the folder where cached files are stored.
+            local_files_only (`bool`, *optional*, defaults to `False`):
+                If `True`, avoid downloading the file and return the path to the local cached file if it exists.
+            model_kwargs:
+                Additional keyword arguments passed along to the [`~ModelHubMixin._from_pretrained`] method.
+        """
         raise NotImplementedError
 
     @validate_hf_hub_args
@@ -231,15 +248,18 @@ class ModelHubMixin:
         create_pr: Optional[bool] = None,
         allow_patterns: Optional[Union[List[str], str]] = None,
         ignore_patterns: Optional[Union[List[str], str]] = None,
+        delete_patterns: Optional[Union[List[str], str]] = None,
     ) -> str:
         """
         Upload model checkpoint to the Hub.
 
-        Use `allow_patterns` and `ignore_patterns` to precisely filter which files
-        should be pushed to the hub. See [`upload_folder`] reference for more details.
+        Use `allow_patterns` and `ignore_patterns` to precisely filter which files should be pushed to the hub. Use
+        `delete_patterns` to delete existing remote files in the same commit. See [`upload_folder`] reference for more
+        details.
 
-        Parameters:
-            repo_id (`str`, *optional*):
+
+        Args:
+            repo_id (`str`):
                 Repository name to which push.
             config (`dict`, *optional*):
                 Configuration object to be saved alongside the model weights.
@@ -250,32 +270,24 @@ class ModelHubMixin:
             api_endpoint (`str`, *optional*):
                 The API endpoint to use when pushing the model to the hub.
             token (`str`, *optional*):
-                The token to use as HTTP bearer authorization for remote files.
-                If not set, will use the token set when logging in with
-                `transformers-cli login` (stored in `~/.huggingface`).
+                The token to use as HTTP bearer authorization for remote files. By default, it will use the token
+                cached when running `huggingface-cli login`.
             branch (`str`, *optional*):
-                The git branch on which to push the model. This defaults to
-                the default branch as specified in your repository, which
-                defaults to `"main"`.
+                The git branch on which to push the model. This defaults to `"main"`.
             create_pr (`boolean`, *optional*):
-                Whether or not to create a Pull Request from `branch` with that commit.
-                Defaults to `False`.
+                Whether or not to create a Pull Request from `branch` with that commit. Defaults to `False`.
             allow_patterns (`List[str]` or `str`, *optional*):
                 If provided, only files matching at least one pattern are pushed.
             ignore_patterns (`List[str]` or `str`, *optional*):
                 If provided, files matching any of the patterns are not pushed.
+            delete_patterns (`List[str]` or `str`, *optional*):
+                If provided, remote files matching any of the patterns will be deleted from the repo.
 
         Returns:
             The url of the commit of your model in the given repository.
         """
-        api = HfApi(endpoint=api_endpoint)
-        api.create_repo(
-            repo_id=repo_id,
-            repo_type="model",
-            token=token,
-            private=private,
-            exist_ok=True,
-        )
+        api = HfApi(endpoint=api_endpoint, token=token)
+        repo_id = api.create_repo(repo_id=repo_id, private=private, exist_ok=True).repo_id
 
         # Push the files to the repo in a single commit
         with SoftTemporaryDirectory() as tmp:
@@ -284,23 +296,21 @@ class ModelHubMixin:
             return api.upload_folder(
                 repo_id=repo_id,
                 repo_type="model",
-                token=token,
                 folder_path=saved_path,
                 commit_message=commit_message,
                 revision=branch,
                 create_pr=create_pr,
                 allow_patterns=allow_patterns,
                 ignore_patterns=ignore_patterns,
+                delete_patterns=delete_patterns,
             )
 
 
 class PyTorchModelHubMixin(ModelHubMixin):
     """
-    Implementation of [`ModelHubMixin`] to provide model Hub upload/download
-    capabilities to PyTorch models. The model is set in evaluation mode by
-    default using `model.eval()` (dropout modules are deactivated). To train
-    the model, you should first set it back in training mode with
-    `model.train()`.
+    Implementation of [`ModelHubMixin`] to provide model Hub upload/download capabilities to PyTorch models. The model
+    is set in evaluation mode by default using `model.eval()` (dropout modules are deactivated). To train the model,
+    you should first set it back in training mode with `model.train()`.
 
     Example:
 
@@ -318,47 +328,42 @@ class PyTorchModelHubMixin(ModelHubMixin):
 
     ...     def forward(self, x):
     ...         return self.linear(x + self.param)
-
-
     >>> model = MyModel()
-    >>> # Save model weights to local directory
+
+    # Save model weights to local directory
     >>> model.save_pretrained("my-awesome-model")
-    >>> # Push model weights to the Hub
+
+    # Push model weights to the Hub
     >>> model.push_to_hub("my-awesome-model")
-    >>> # Download and initialize weights from the Hub
+
+    # Download and initialize weights from the Hub
     >>> model = MyModel.from_pretrained("username/my-awesome-model")
     ```
     """
 
-    def _save_pretrained(self, save_directory):
-        """
-        Overwrite this method if you wish to save specific layers instead of the
-        complete model.
-        """
-        path = os.path.join(save_directory, PYTORCH_WEIGHTS_NAME)
-        model_to_save = self.module if hasattr(self, "module") else self
-        torch.save(model_to_save.state_dict(), path)
+    def _save_pretrained(self, save_directory: Path) -> None:
+        """Save weights from a Pytorch model to a local directory."""
+        model_to_save = self.module if hasattr(self, "module") else self  # type: ignore
+        torch.save(model_to_save.state_dict(), save_directory / PYTORCH_WEIGHTS_NAME)
 
     @classmethod
+    @_deprecate_positional_args(version="0.16")
     def _from_pretrained(
         cls,
-        model_id,
-        revision,
-        cache_dir,
-        force_download,
-        proxies,
-        resume_download,
-        local_files_only,
-        token,
-        map_location="cpu",
-        strict=False,
+        *,
+        model_id: str,
+        revision: str,
+        cache_dir: str,
+        force_download: bool,
+        proxies: Optional[Dict],
+        resume_download: bool,
+        local_files_only: bool,
+        token: Union[str, bool, None],
+        map_location: str = "cpu",
+        strict: bool = False,
         **model_kwargs,
     ):
-        """
-        Overwrite this method to initialize your model in a different way.
-        """
-        map_location = torch.device(map_location)
-
+        """Load Pytorch pretrained weights and return the loaded model."""
         if os.path.isdir(model_id):
             print("Loading weights from local directory")
             model_file = os.path.join(model_id, PYTORCH_WEIGHTS_NAME)
@@ -376,8 +381,8 @@ class PyTorchModelHubMixin(ModelHubMixin):
             )
         model = cls(**model_kwargs)
 
-        state_dict = torch.load(model_file, map_location=map_location)
-        model.load_state_dict(state_dict, strict=strict)
-        model.eval()
+        state_dict = torch.load(model_file, map_location=torch.device(map_location))
+        model.load_state_dict(state_dict, strict=strict)  # type: ignore
+        model.eval()  # type: ignore
 
         return model

huggingface_hub/inference_api.py

@@ -3,6 +3,7 @@ from typing import Any, Dict, List, Optional, Union
 
 import requests
 
+from .constants import INFERENCE_ENDPOINT
 from .hf_api import HfApi
 from .utils import build_hf_headers, is_pillow_available, logging, validate_hf_hub_args
 
@@ -10,8 +11,6 @@ from .utils import build_hf_headers, is_pillow_available, logging, validate_hf_h
 logger = logging.get_logger(__name__)
 
 
-ENDPOINT = "https://api-inference.huggingface.co"
-
 ALL_TASKS = [
     # NLP
     "text-classification",
@@ -142,14 +141,11 @@ class InferenceApi:
             assert model_info.pipeline_tag is not None, "Pipeline tag cannot be None"
             self.task = model_info.pipeline_tag
 
-        self.api_url = f"{ENDPOINT}/pipeline/{self.task}/{repo_id}"
+        self.api_url = f"{INFERENCE_ENDPOINT}/pipeline/{self.task}/{repo_id}"
 
     def __repr__(self):
         # Do not add headers to repr to avoid leaking token.
-        return (
-            f"InferenceAPI(api_url='{self.api_url}', task='{self.task}',"
-            f" options={self.options})"
-        )
+        return f"InferenceAPI(api_url='{self.api_url}', task='{self.task}', options={self.options})"
 
     def __call__(
         self,
@@ -183,9 +179,7 @@ class InferenceApi:
             payload["parameters"] = params
 
         # Make API call
-        response = requests.post(
-            self.api_url, headers=self.headers, json=payload, data=data
-        )
+        response = requests.post(self.api_url, headers=self.headers, json=payload, data=data)
 
         # Let the user handle the response
         if raw_response: