Github GraphQL

The PyGithub project primarily accesses the Github REST API v3. However, Github has started to provide more functionality behind a separate GraphQL API. Further benefits of the GraphQL endpoint is that the caller has full control over the structure and complexity (or simplicity) of the response, hence can reduce both number of calls and size of transferred data.

PyGithub provides access to the GraphQL API while providing results using the usual object-oriented PyGithub objects hierarchy.

This documents the current support for the GraphQL API.

GraphQL Classes

Some PyGithub classes represent GraphQL schemas, where no equivalent Github REST API schema exists. GraphQL API data of those classes are translated (see as_rest_api_attributes(attributes) below) into REST API equivalent data and backed by ordinary PyGithub classes.

A good example is RepositoryDiscussion:

class RepositoryDiscussion(GraphQlObject, DiscussionBase):
    """
    This class represents GraphQL Discussion.

    The reference can be found here
    https://docs.github.com/en/graphql/reference/objects#discussion

    """

...

def _useAttributes(self, attributes: dict[str, Any]) -> None:
    # super class is a REST API GithubObject, attributes are coming from GraphQL
    super()._useAttributes(as_rest_api_attributes(attributes))
    if "answer" in attributes:  # pragma no branch
        self._answer = self._makeClassAttribute(
            github.RepositoryDiscussionComment.RepositoryDiscussionComment, attributes["answer"]
        )
    if "bodyText" in attributes:  # pragma no branch
        self._body_text = self._makeStringAttribute(attributes["bodyText"])
...

Query

GraphQL data can be retrieved by GraphQL queries. A good example can be found in github.Repository.Repository method get_discussion.

GraphQL queries can be sent to the Github GraphQL API via these methods:

Mutation

The GraphQL API can also be used to manipulate GraphQL data server-side. Example where GraphQL mutation is used can be found in:

GraphQL mutations can be sent to the Github GraphQL API via these methods:

Pagination

An example where GraphQL results are provided through pagination can be found in github.Repository.Repository method get_discussions.

The response has to contain a GraphQL pagination object for github.PaginatedList.PaginatedList() to be able to paginate through the results:

totalCount
pageInfo {
  startCursor
  endCursor
  hasNextPage
  hasPreviousPage
}