Unified login/logout methods (#1111)

* Unified login/logout methods * docstring * documentation * arrange imports * add login reference * fix * disable codecov checks in diff page * make interpreter_login official + doc
huggingface · Oct 17, 2022 · 62a5ead · 62a5ead
1 parent c91a99b
commit 62a5ead
Show file tree

Hide file tree

Showing 17 changed files with 414 additions and 222 deletions.
diff --git a/codecov.yml b/codecov.yml
@@ -2,4 +2,7 @@ comment:
   # https://docs.codecov.com/docs/pull-request-comments#requiring-changes
   require_changes: true
   # https://docs.codecov.com/docs/pull-request-comments#after_n_builds
-  after_n_builds: 11
+  after_n_builds: 11
+
+github_checks:
+  annotations: false
diff --git a/docs/source/_toctree.yml b/docs/source/_toctree.yml
@@ -1,28 +1,30 @@
 - sections:
-  - local: index
-    title: Home
-  - local: quick-start
-    title: Quick start
+    - local: index
+      title: Home
+    - local: quick-start
+      title: Quick start
   title: "Get started"
 - sections:
-  - local: how-to-manage
-    title: Create and manage repositories
-  - local: how-to-downstream
-    title: Download files from the Hub
-  - local: how-to-upstream
-    title: Upload files to the Hub
-  - local: searching-the-hub
-    title: Searching the Hub
-  - local: how-to-inference
-    title: Access the Inference API
-  - local: how-to-discussions-and-pull-requests
-    title: Interact with Discussions and Pull Requests
-  - local: how-to-cache
-    title: Manage the Cache
-  - local: how-to-model-cards
-    title: Create and Share Model Cards
+    - local: how-to-manage
+      title: Create and manage repositories
+    - local: how-to-downstream
+      title: Download files from the Hub
+    - local: how-to-upstream
+      title: Upload files to the Hub
+    - local: searching-the-hub
+      title: Searching the Hub
+    - local: how-to-inference
+      title: Access the Inference API
+    - local: how-to-discussions-and-pull-requests
+      title: Interact with Discussions and Pull Requests
+    - local: how-to-cache
+      title: Manage the Cache
+    - local: how-to-model-cards
+      title: Create and Share Model Cards
   title: "Guides"
 - sections:
+    - local: package_reference/login
+      title: Login and logout
     - local: package_reference/repository
       title: Managing local and online repositories
     - local: package_reference/hf_api
@@ -41,4 +43,4 @@
       title: Cache-system reference
     - local: package_reference/cards
       title: Repo Cards and Repo Card Data
-  title: "Reference"
+  title: "Reference"
diff --git a/docs/source/how-to-manage.mdx b/docs/source/how-to-manage.mdx
@@ -14,14 +14,21 @@ If you want to create a repository on the Hub, you need to log in to your Huggin
    huggingface-cli login
    ```
 
-2. Alternatively, if you prefer working from a Jupyter or Colaboratory notebook, login with [`notebook_login`]:
+2. Alternatively, you can programmatically login using [`login`] in a notebook or a script:
 
    ```python
-   >>> from huggingface_hub import notebook_login
-   >>> notebook_login()
+   >>> from huggingface_hub import login
+   >>> login()
    ```
 
-   [`notebook_login`] will launch a widget in your notebook from which you can enter your Hugging Face credentials.
+   If ran in a Jupyter or Colaboratory notebook, [`login`] will launch a widget from
+   which you can enter your Hugging Face access token. Otherwise, a message will be
+   prompted in the terminal.
+
+   It is also possible to login programmatically without the widget by directly passing
+   the token to [`login`]. If you do so, be careful when sharing your notebook. It is
+   best practice to load the token from a secure vault instead of saving it in plain in
+   your Colaboratory notebook.
 
 ## Create a repository
 

diff --git a/docs/source/how-to-model-cards.mdx b/docs/source/how-to-model-cards.mdx
@@ -179,7 +179,7 @@ print(card)
 
 ## Sharing Model Cards
 
-If you're authenticated with the Hugging Face Hub (either by using `huggingface-cli login` or `huggingface_hub.notebook_login()`), you can push cards to the Hub by simply calling [`ModelCard.push_to_hub`]. Let's take a look at how to do that...
+If you're authenticated with the Hugging Face Hub (either by using `huggingface-cli login` or [`login`]), you can push cards to the Hub by simply calling [`ModelCard.push_to_hub`]. Let's take a look at how to do that...
 
 First, we'll create a new repo called 'hf-hub-modelcards-pr-test' under the authenticated user's namespace:
 

diff --git a/docs/source/how-to-upstream.mdx b/docs/source/how-to-upstream.mdx
@@ -15,14 +15,21 @@ Whenever you want to upload files to the Hub, you need to log in to your Hugging
    huggingface-cli login
    ```
 
-- Alternatively, if you prefer working from a Jupyter or Colaboratory notebook, log in with [`notebook_login`]:
+- Alternatively, you can programmatically login using [`login`] in a notebook or a script:
 
    ```python
-   >>> from huggingface_hub import notebook_login
-   >>> notebook_login()
+   >>> from huggingface_hub import login
+   >>> login()
    ```
 
-   [`notebook_login`] launches a widget in your notebook from which you can enter your Hugging Face credentials.
+   If ran in a Jupyter or Colaboratory notebook, [`login`] will launch a widget from
+   which you can enter your Hugging Face access token. Otherwise, a message will be
+   prompted in the terminal.
+
+   It is also possible to login programmatically without the widget by directly passing
+   the token to [`login`]. If you do so, be careful when sharing your notebook. It is
+   best practice to load the token from a secure vault instead of saving it in plain in
+   your Colaboratory notebook.
 
 ## Push files without Git
 

diff --git a/docs/source/package_reference/login.mdx b/docs/source/package_reference/login.mdx
@@ -0,0 +1,20 @@
+# Login and logout
+
+The `huggingface_hub` library allows users to programmatically login and logout the
+machine to the Hub.
+
+## login
+
+[[autodoc]] login
+
+## interpreter_login
+
+[[autodoc]] interpreter_login
+
+## notebook_login
+
+[[autodoc]] notebook_login
+
+## logout
+
+[[autodoc]] logout
diff --git a/docs/source/quick-start.mdx b/docs/source/quick-start.mdx
@@ -69,12 +69,11 @@ Once you have your User Access Token, run the following command in your terminal
 huggingface-cli login
 ```
 
-Or if you prefer to work from a Jupyter or Colaboratory notebook, then login with
-[`notebook_login`]:
+Or if you prefer to work from a Jupyter or Colaboratory notebook, then use [`login`]:
 
 ```py
->>> from huggingface_hub import notebook_login
->>> notebook_login()
+>>> from huggingface_hub import login
+>>> login()
 ```
 
 <Tip>

diff --git a/src/huggingface_hub/__init__.py b/src/huggingface_hub/__init__.py
@@ -52,12 +52,15 @@
 # WARNING: any comment added in this dictionary definition will be lost when
 # re-generating the file !
 _SUBMOD_ATTRS = {
+    "_login": [
+        "interpreter_login",
+        "login",
+        "logout",
+        "notebook_login",
+    ],
     "_snapshot_download": [
         "snapshot_download",
     ],
-    "commands.user": [
-        "notebook_login",
-    ],
     "community": [
         "Discussion",
         "DiscussionComment",
@@ -282,8 +285,11 @@ def __dir__():
 # make style
 # ```
 if TYPE_CHECKING:  # pragma: no cover
+    from ._login import interpreter_login  # noqa: F401
+    from ._login import login  # noqa: F401
+    from ._login import logout  # noqa: F401
+    from ._login import notebook_login  # noqa: F401
     from ._snapshot_download import snapshot_download  # noqa: F401
-    from .commands.user import notebook_login  # noqa: F401
     from .community import Discussion  # noqa: F401
     from .community import DiscussionComment  # noqa: F401
     from .community import DiscussionCommit  # noqa: F401