Main class: GitHubGQL

class githubgql.Client.GitHubGQL(pat: str | None = None, *, default_page_size: int = 100, auto_fit_quotas=True, inject_default_fields=True, cleanup_query=True)

Construct a GitHub GraphQL client.

Parameters:

pat – A Personal Access Token issued by GitHub that has all the privileges required for the queries the user intends to execute. Default: look up token via git config --get user.password.
default_page_size – How many items will be requested from collections per GraphQL call, unless overridden on a per-query basis. Many calls may be required to fulfill a complicated request. Default: 100 (GitHub maximum)
auto_fit_quotas – Automatically adjust the default page size to be between 1-100, and proportionally auto-adjust all page sizes to keep the total query <= 500,000 nodes. Default: True
inject_default_fields – Automatically inject fields into nodes that GitHubGQL has determined are commonly used to identify that type, such as id, url, or number. Fields necessary to disambiguate and merge paged lists will be injected regardless of this argument. Default: True
cleanup_query – Automatically detect and correct common mistakes in query construction. Override to fail loudly and do your own corrections. Default: True

Callback

A function that can be passed into execute_callback for page-by-page processing.

alias of Callable[[dict[str, dict | list | str]], bool]

Iterator

An iterator used to loop through pages as they arrive.

alias of Paginator

Merger = <githubgql.Merger.Merger object>: A deep merger for handling the data structures in a result object.

ResultPage

The type of one page of execution results.

alias of dict[str, dict | list | str]

execute_all(query: str, *, variables: dict[str, str] = None) → ResultPage

Execute the provided query to completion, with as many calls as necessary.

Parameters:

query – The query to execute. This can be standard GraphQL as described by online documentation, or a simplified, GitHub-only version with auto-pagination as described above.
variables – The variables to substitute into the query.

Returns:

A dictionary containing the results of the query executed. If a simplified query was provided for auto-pagination, the results do not include pageInfo data.

Example:

results = client.execute_all(query, variables, 5)

execute_callback(callback: Callable[[dict[str, dict | list | str]], bool], query: str, *, variables: dict[str, str] | None = None) → None

Execute the query page by page, calling callback for each page.

Parameters:

callback – A function to call for each page. The page results are sent, and the function may operate on each as required. The iterator stops when all data is consumed, the callback returns False, or an exception is raised.
query – The query to execute. This can be standard GraphQL as described by online documentation, or a simplified, GitHub-only version with auto-pagination as described above.
variables – The variables to substitute into the query.

Returns:

Nothing

Example:

merged_results = {}

def callback(result):
    Client.Merger.merge(merged_results, result)
    if next((x for x in result['viewer']['repositories'] if x['name'] == 'bgm-nerdrock']), False):
        # Got what we need
        return False
    return True

client.execute_callback(callback)

execute_iter(query: str, *, variables: dict[str, str] = None) → Iterator

Return an iterator for the provided query.

Parameters:

query – The query to execute. This can be standard GraphQL as described by online documentation, or a simplified, GitHub-only version with auto-pagination as described above.
variables – The variables to substitute into the query.

Returns:

An iterator allowing the client to control their own merging and/or other operations

Example:

merged_results = {}
for result in client.execute_iter():
    Client.Merger.merge(merged_results, result)
    if next((x for x in result['viewer']['repositories'] if x['name'] == 'bgm-nerdrock']), False):
        # Got what we need
        break