From 21f436aee07a16759a51c489af961d3bf46baa71 Mon Sep 17 00:00:00 2001 From: Lucain Pouget Date: Thu, 1 Dec 2022 12:11:51 +0100 Subject: [PATCH] Integrate osanviero's feedback --- docs/source/installation.mdx | 18 +++---- .../environment_variables.mdx | 49 +++++++------------ src/huggingface_hub/utils/_git_credential.py | 6 +-- 3 files changed, 31 insertions(+), 42 deletions(-) diff --git a/docs/source/installation.mdx b/docs/source/installation.mdx index 0e7161980d..d9d0cfb4f4 100644 --- a/docs/source/installation.mdx +++ b/docs/source/installation.mdx @@ -2,11 +2,11 @@ Before you start, you will need to setup your environment by installing the appropriate packages. -🤗 `huggingface_hub` is tested on **Python 3.7+**. +`huggingface_hub` is tested on **Python 3.7+**. ## Install with pip -It is highly recommended to install 🤗 `huggingface_hub` in a [virtual environment](https://docs.python.org/3/library/venv.html). +It is highly recommended to install `huggingface_hub` in a [virtual environment](https://docs.python.org/3/library/venv.html). If you are unfamiliar with Python virtual environments, take a look at this [guide](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/). A virtual environment makes it easier to manage different projects, and avoid compatibility issues between dependencies. @@ -28,7 +28,7 @@ Activate virtual environment on Windows: .env/Scripts/activate ``` -Now you're ready to install 🤗 `huggingface_hub` [from the PyPi registry](https://pypi.org/project/huggingface-hub/): +Now you're ready to install `huggingface_hub` [from the PyPi registry](https://pypi.org/project/huggingface-hub/): ```bash pip install --upgrade huggingface_hub @@ -52,14 +52,14 @@ pip install 'huggingface_hub[cli,torch]' Here is the list of optional dependencies in `huggingface_hub`: - `cli`: provide a more convenient CLI interface for `huggingface_hub`. -- `fastai`, `torch`, `tensorflow`: dependencies to run library specific features. +- `fastai`, `torch`, `tensorflow`: dependencies to run framework-specific features. - `dev`: dependencies to contribute to the lib. Includes `testing` (to run tests), `typing` (to run type checker) and `quality` (to run linters). ### Install from source -In some cases, it is interesting to install 🤗 `huggingface_hub` directly from source. +In some cases, it is interesting to install `huggingface_hub` directly from source. This allows you to use the bleeding edge `main` version rather than the latest stable version. The `main` version is useful for staying up-to-date with the latest developments, for instance if a bug has been fixed since the last official release but a new release hasn't been rolled out yet. @@ -85,7 +85,7 @@ Once done, [check installation](#check-installation) is working correctly. ### Editable install Installing from source allows you to setup an [editable install](https://pip.pypa.io/en/stable/topics/local-project-installs/#editable-installs). -This is a more advanced installation if you plan to contribute to 🤗 `huggingface_hub` +This is a more advanced installation if you plan to contribute to `huggingface_hub` and need to test changes in the code. You need to clone a local copy of `huggingface_hub` on your machine. @@ -105,7 +105,7 @@ Python will also search the folder you cloned `./huggingface_hub/`. ## Install with conda -If you are more familiar with it, you can install 🤗 `huggingface_hub` using the [conda-forge channel](https://anaconda.org/conda-forge/huggingface_hub): +If you are more familiar with it, you can install `huggingface_hub` using the [conda-forge channel](https://anaconda.org/conda-forge/huggingface_hub): ```bash @@ -116,7 +116,7 @@ Once done, [check installation](#check-installation) is working correctly. ## Check installation -Once installed, check that 🤗 `huggingface_hub` works properly by running the following command: +Once installed, check that `huggingface_hub` works properly by running the following command: ```bash python -c "from huggingface_hub import model_info; print(model_info('gpt2'))" @@ -133,5 +133,5 @@ Task: text-generation ## Next steps -Once 🤗 `huggingface_hub` is properly installed on your machine, you might want +Once `huggingface_hub` is properly installed on your machine, you might want [configure environment variables](package_reference/environment_variables) or [check one of our guides](guides/overview) to get started. \ No newline at end of file diff --git a/docs/source/package_reference/environment_variables.mdx b/docs/source/package_reference/environment_variables.mdx index 01f2ae4614..3444ac1e5a 100644 --- a/docs/source/package_reference/environment_variables.mdx +++ b/docs/source/package_reference/environment_variables.mdx @@ -1,9 +1,9 @@ # Environment variables -🤗 `huggingface_hub` can be configured using environment variables. +`huggingface_hub` can be configured using environment variables. If you are unfamiliar with environment variable, here are generic articles about them -[on MacOS and Linux](https://linuxize.com/post/how-to-set-and-list-environment-variables-in-linux/) +[on macOS and Linux](https://linuxize.com/post/how-to-set-and-list-environment-variables-in-linux/) and on [Windows](https://phoenixnap.com/kb/windows-set-environment-variable). This page will guide you through all environment variables specific to `huggingface_hub` @@ -13,15 +13,15 @@ and their meaning. ### HF_ENDPOINT -To configure the 🤗 Hub base url. You might want to set this variable if your organization +To configure the Hub base url. You might want to set this variable if your organization is using a [Private Hub](https://huggingface.co/platform). Defaults to `"https://huggingface.co"`. ### HF_HOME -to configure where `huggingface_hub` will store data. In particular the cache will be stored -in this folder. +To configure where `huggingface_hub` will locally store data. In particular, your token +and the cache will be stored in this folder. Defaults to `"~/.cache/huggingface"` unless [XDG_CACHE_HOME](#xdgcachehome) is set. @@ -47,6 +47,15 @@ overwrite the token stored on the machine (under `"~/huggingface/token"`). See [login reference](package_reference/login) for more details. +### HUGGINGFACE_HUB_VERBOSITY + +Set the verbosity level of the `huggingface_hub`'s logger. Must be one of +`{"debug", "info", "warning", "error", "critical"}`. + +Defaults to `"warning"`. + +For more details, see [logging reference](package_reference/utilities#huggingface_hub.utils.logging.get_verbosity). + ## Boolean values The following environment variables expect a boolean value. The variable will be considered @@ -66,15 +75,15 @@ skip this call which speeds up your loading time. ### HF_HUB_DISABLE_IMPLICIT_TOKEN Authentication is not mandatory for every requests to the Hub. For instance, requesting -details about `"gpt2"` model does not require to be authenticated. However if a user is +details about `"gpt2"` model does not require to be authenticated. However, if a user is [logged in](package_reference/login), the default behavior will be to always send the token -is order to ease user experience (never get a HTTP 401 Unauthorized). For privacy, you can -choose to disable this behavior by setting `HF_HUB_DISABLE_IMPLICIT_TOKEN=1`. In this case, -token will be sent only for "write-access" calls (example: create a commit). +in order to ease user experience (never get a HTTP 401 Unauthorized) when accessing private or gated repositories. For privacy, you can +disable this behavior by setting `HF_HUB_DISABLE_IMPLICIT_TOKEN=1`. In this case, +the token will be sent only for "write-access" calls (example: create a commit). **Note:** disabling implicit sending of token can have weird side effects. For example, if you want to list all models on the Hub, your private models will not be listed. You -would need to explicitly set pass `token=True` argument in your script. +would need to explicitly pass `token=True` argument in your script. ### HF_HUB_DISABLE_PROGRESS_BARS @@ -92,26 +101,6 @@ to disable this warning. For more details, see [cache limitations](how-to-cache#limitations). -## Advanced - -Environment variables listed in this section are less often used. They are still documented -for reference. - -### HUGGINGFACE_CO_STAGING - -Boolean value. If set, `huggingface_hub` will interact with the staging environment. -To be used only when running tests locally. Staging environment should never be considered -as stable or reliable to store your models. - -### HUGGINGFACE_HUB_VERBOSITY - -Set the verbosity level of the `huggingface_hub`'s logger. Must be one of -`{"debug", "info", "warning", "error", "critical"}`. - -Defaults to `"warning"`. - -For more details, see [logging reference](package_reference/utilities#huggingface_hub.utils.logging.get_verbosity). - ## From external tools Some environment variables are not specific to `huggingface_hub` but still taken into account diff --git a/src/huggingface_hub/utils/_git_credential.py b/src/huggingface_hub/utils/_git_credential.py index 1c5239d7ff..1cc5a2d061 100644 --- a/src/huggingface_hub/utils/_git_credential.py +++ b/src/huggingface_hub/utils/_git_credential.py @@ -26,7 +26,7 @@ def list_credential_helpers(folder: Optional[str] = None) -> List[str]: See https://git-scm.com/docs/gitcredentials. - Credentials are saved in all configured helpers (store, cache, macos keychain,...). + Credentials are saved in all configured helpers (store, cache, macOS keychain,...). Calls "`git credential approve`" internally. See https://git-scm.com/docs/git-credential. Args: @@ -54,7 +54,7 @@ def set_git_credential( ) -> None: """Save a username/token pair in git credential for HF Hub registry. - Credentials are saved in all configured helpers (store, cache, macos keychain,...). + Credentials are saved in all configured helpers (store, cache, macOS keychain,...). Calls "`git credential approve`" internally. See https://git-scm.com/docs/git-credential. Args: @@ -81,7 +81,7 @@ def unset_git_credential( ) -> None: """Erase credentials from git credential for HF Hub registry. - Credentials are erased from the configured helpers (store, cache, macos + Credentials are erased from the configured helpers (store, cache, macOS keychain,...), if any. If `username` is not provided, any credential configured for HF Hub endpoint is erased. Calls "`git credential erase`" internally. See https://git-scm.com/docs/git-credential.