Hub Python Library documentation

Interact with Discussions and Pull Requests

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v0.22.1).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

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 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:

>>> from huggingface_hub import get_repo_discussions
>>> for discussion in get_repo_discussions(repo_id="bigscience/bloom"):
...     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 supports filtering by author, type (Pull Request or Discussion) and status (open or closed):

>>> from huggingface_hub import get_repo_discussions
>>> for discussion in get_repo_discussions(
...    repo_id="bigscience/bloom",
...    author="ArthurZ",
...    discussion_type="pull_request",
...    discussion_status="open",
... ):
...     print(f"{discussion.num} - {discussion.title} by {discussion.author}, pr: {discussion.is_pull_request}")

# 19 - Add Flax weights by ArthurZ, pr: True

HfApi.get_repo_discussions returns a generator that yields Discussion objects. To get all the Discussions in a single list, run:

>>> 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():

>>> 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 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():

>>> 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.

>>> 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:

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 Discussions and Pull Requests and the hf_api documentation page.