✨ Programmatic API for the community tab (#930)

* ✨ WIP: programmatic API for the community tab * Layout the API * 📝 Autodoc data structures * 📝 Docstring (wip) * 💄 Code quality * 📝 Fix doc build & add parent attributes * ✨ Implement the API * 🚧 Placeholder guide * ✨ git_reference property * ✨ Comment edit history helpers * 💄 Code qualityyyy * ♻ refactor Pagination a bit * 🩹 Documentation + fix POST requests URL * 🩹 Fix GET requests URLs * ✨ Programmatically create_discussion * 💄 Code quality * 📝 how-to-community guide * Re-exports * ✅ Add tests * 📝 links and typo * 🚚 Rename how-to-community guide * ✨ create_pull_request convenience wrapper * Mention `create_commit` API in guide & docstrings * Use self._validate_or_retrieve_token * Apply suggestions from code review Co-authored-by: Omar Sanseviero <osanseviero@gmail.com> * 💄 Capitalize "Discussion" and "Pull Request" * Use Literal type hint * 💄 Fix typo * 🔊 Add warning when hiding a comment * 💚 CI fix * 🔥 Remove Pagination util * Update docs/source/how-to-discussions-and-pull-requests.mdx Co-authored-by: Julien Chaumond <julien@huggingface.co> * 📝 Documentation improvements * 🎨 Move ternary expressions out of the constructor call * 💄 Code quality * Update docs/source/how-to-discussions-and-pull-requests.mdx * Update docs/source/how-to-discussions-and-pull-requests.mdx * Update src/huggingface_hub/community.py * Update src/huggingface_hub/hf_api.py * Update src/huggingface_hub/hf_api.py * Update src/huggingface_hub/hf_api.py * Update src/huggingface_hub/hf_api.py * Update src/huggingface_hub/community.py * Update src/huggingface_hub/community.py Co-authored-by: Omar Sanseviero <osanseviero@gmail.com> Co-authored-by: Julien Chaumond <julien@huggingface.co> Co-authored-by: Lucain <lucainp@gmail.com>
huggingface · Aug 9, 2022 · 3fbc99e · 3fbc99e
1 parent f2e5c69
commit 3fbc99e
Show file tree

Hide file tree

Showing 8 changed files with 1,449 additions and 5 deletions.
diff --git a/docs/source/_toctree.yml b/docs/source/_toctree.yml
@@ -15,6 +15,8 @@
     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 
   title: "Guides"
 - sections:
     - local: package_reference/repository
@@ -29,4 +31,6 @@
       title: Inference API
     - local: package_reference/utilities
       title: Utilities
+    - local: package_reference/community
+      title: Discussions and Pull Requests
   title: "Reference"
diff --git a/docs/source/how-to-discussions-and-pull-requests.mdx b/docs/source/how-to-discussions-and-pull-requests.mdx
@@ -0,0 +1,129 @@
+# Interact with Discussions and Pull Requests 
+
+The `huggingface_hub` library provides a Python interface to interact with Pull Requests and Discussions on the Hub.
+Visit [the dedicated documentation page](https://huggingface.co/docs/hub/repositories-pull-requests-discussions)
+for a deeper view of what Discussions and Pull Requests on the Hub are, and how they work under the hood.
+
+## Retrieve Discussions and Pull Requests from the Hub
+
+The `HfApi` class allows you to retrieve Discussions and Pull Requests on a given repo:
+
+```python
+>>> from huggingface_hub import get_repo_discussions
+>>> for discussion in get_repo_discussions(repo_id="bigscience/bloom-1b3"):
+...     print(f"{discussion.num} - {discussion.title}, pr: {discussion.is_pull_request}")
+
+# 11 - Add Flax weights, pr: True
+# 10 - Update README.md, pr: True
+# 9 - Training languages in the model card, pr: True
+# 8 - Update tokenizer_config.json, pr: True
+# 7 - Slurm training script, pr: False
+[...]
+```
+
+`HfApi.get_repo_discussions` returns a [generator](https://docs.python.org/3.7/howto/functional.html#generators) that yields
+[`Discussion`] objects. To get all the Discussions in a single list, run:
+
+```python
+>>> from huggingface_hub import get_repo_discussions
+>>> discussions_list = list(get_repo_discussions(repo_id="bert-base-uncased"))
+```
+
+The [`Discussion`] object returned by [`HfApi.get_repo_discussions`] contains high-level overview of the
+Discussion or Pull Request. You can also get more detailed information using [`HfApi.get_discussion_details`]:
+
+```python
+>>> from huggingface_hub import get_discussion_details
+
+>>> get_discussion_details(
+...     repo_id="bigscience/bloom-1b3",
+...     discussion_num=2
+... )
+DiscussionWithDetails(
+    num=2,
+    author='cakiki',
+    title='Update VRAM memory for the V100s',
+    status='open',
+    is_pull_request=True,
+    events=[
+        DiscussionComment(type='comment', author='cakiki', ...),
+        DiscussionCommit(type='commit', author='cakiki', summary='Update VRAM memory for the V100s', oid='1256f9d9a33fa8887e1c1bf0e09b4713da96773a', ...),
+    ],
+    conflicting_files=[],
+    target_branch='refs/heads/main',
+    merge_commit_oid=None,
+    diff='diff --git a/README.md b/README.md\nindex a6ae3b9294edf8d0eda0d67c7780a10241242a7e..3a1814f212bc3f0d3cc8f74bdbd316de4ae7b9e3 100644\n--- a/README.md\n+++ b/README.md\n@@ -132,7 +132,7 [...]',
+)
+```
+
+[`HfApi.get_discussion_details`] returns a [`DiscussionWithDetails`] object, which is a subclass of [`Discussion`]
+with more detailed information about the Discussion or Pull Request. Information includes all the comments, status changes,
+and renames of the Discussion via [`DiscussionWithDetails.events`].
+
+In case of a Pull Request, you can retrieve the raw git diff with [`DiscussionWithDetails.diff`]. All the commits of the
+Pull Request are listed in [`DiscussionWithDetails.events`].
+
+
+## Create and edit a Discussion or Pull Request programmatically
+
+The [`HfApi`] class also offers ways to create and edit Discussions and Pull Requests.
+You will need an [access token](https://huggingface.co/docs/hub/security-tokens) to create and edit Discussions
+or Pull Requests.
+
+The simplest way to propose changes on a repo on the Hub is via the [`create_commit`] API: just 
+set the `create_pr` parameter to `True`. This parameter is also available on other methods that wrap [`create_commit`]:
+
+    * [`upload_file`]
+    * [`upload_folder`]
+    * [`delete_file`]
+    * [`metadata_update`]
+
+```python
+>>> from huggingface_hub import metadata_update
+
+>>> metadata_update(
+...     repo_id="username/repo_name",
+...     metadata={"tags": ["computer-vision", "awesome-model"]},
+...     create_pr=True,
+... )
+```
+
+You can also use [`HfApi.create_discussion`] (respectively [`HfApi.create_pull_request`]) to create a Discussion (respectively a Pull Request) on a repo.
+Opening a Pull Request this way can be useful if you need to work on changes locally. Pull Requests opened this way will be in `"draft"` mode.
+
+```python
+>>> from huggingface_hub import create_discussion, create_pull_request
+
+>>> create_discussion(
+...     repo_id="username/repo-name",
+...     title="Hi from the huggingface_hub library!",
+...     token="<insert your access token here>",
+... )
+DiscussionWithDetails(...)
+
+>>> create_pull_request(
+...     repo_id="username/repo-name",
+...     title="Hi from the huggingface_hub library!",
+...     token="<insert your access token here>",
+... )
+DiscussionWithDetails(..., is_pull_request=True)
+```
+
+Managing Pull Requests and Discussions can be done entirely with the [`HfApi`] class. For example:
+
+    * [`comment_discussion`] to add comments
+    * [`edit_discussion_comment`] to edit comments
+    * [`rename_discussion`] to rename a Discussion or Pull Request 
+    * [`change_discussion_status`] to open or close a Discussion / Pull Request 
+    * [`merge_pull_request`] to merge a Pull Request 
+
+
+Visit the [`HfApi`] documentation page for an exhaustive reference of all available methods.
+
+## Push changes to a Pull Request
+
+*Coming soon !*
+
+## See also
+
+For a more detailed reference, visit the [community](/source/package_reference/community) and the [hf_api](/source/package_reference/hf_api) documentation page.
diff --git a/docs/source/index.mdx b/docs/source/index.mdx
@@ -21,6 +21,7 @@ Keep reading to learn even more about how to:
 - [Search thousands of models and datasets on the Hub with specific filters and
   parameters to only return the best results](searching-the-hub).
 - [Access the Inference API for accelerated inference](how-to-inference).
+- [Interact with Discussions and Pull Requests ](how-to-discussions-and-pull-requests).
 
 ## Contribute
 

diff --git a/docs/source/package_reference/community.mdx b/docs/source/package_reference/community.mdx
@@ -0,0 +1,30 @@
+# Interacting with Discussions and Pull Requests
+
+Check the [`HfApi`] documentation page for the reference of methods enabling
+interaction with Pull Requests and Discussions on the Hub.
+
+- [`get_repo_discussions`]
+- [`get_discussion_details`]
+- [`create_discussion`]
+- [`create_pull_request`]
+- [`rename_discussion`]
+- [`comment_discussion`]
+- [`edit_discussion_comment`]
+- [`change_discussion_status`]
+- [`merge_pull_request`]
+
+## Data structures
+
+[[autodoc]] Discussion
+
+[[autodoc]] DiscussionWithDetails
+
+[[autodoc]] DiscussionEvent
+
+[[autodoc]] DiscussionComment
+
+[[autodoc]] DiscussionStatusChange
+
+[[autodoc]] DiscussionCommit
+
+[[autodoc]] DiscussionTitleChange
diff --git a/src/huggingface_hub/__init__.py b/src/huggingface_hub/__init__.py
@@ -150,22 +150,31 @@ def __dir__():
             "HfApi",
             "HfFolder",
             "ModelSearchArguments",
+            "change_discussion_status",
+            "comment_discussion",
             "create_commit",
+            "create_discussion",
+            "create_pull_request",
             "create_repo",
             "dataset_info",
             "delete_file",
             "delete_repo",
+            "edit_discussion_comment",
             "get_dataset_tags",
+            "get_discussion_details",
             "get_full_repo_name",
             "get_model_tags",
+            "get_repo_discussions",
             "list_datasets",
             "list_metrics",
             "list_models",
             "list_repo_files",
             "login",
             "logout",
+            "merge_pull_request",
             "model_info",
             "move_repo",
+            "rename_discussion",
             "repo_type_and_id_from_hf_id",
             "set_access_token",
             "space_info",
@@ -193,5 +202,14 @@ def __dir__():
             "metadata_save",
             "metadata_update",
         ],
+        "community": [
+            "Discussion",
+            "DiscussionWithDetails",
+            "DiscussionEvent",
+            "DiscussionComment",
+            "DiscussionStatusChange",
+            "DiscussionCommit",
+            "DiscussionTitleChange",
+        ],
     },
 )