Octokit (internals)

This part of the documentation covers all the octokit APIs.

RestRequest API

RestRequest is for all the Octokit APIs that require a REST interface with GitHub.

class ghastoolkit.RestRequest(repository: Repository | None = None, retries: Retry | None = None)

Class for making REST API requests to GitHub.

This class handles REST API requests to GitHub endpoints, including: - Making authenticated requests with rate limiting - Handling pagination of results - Error handling and response parsing

__init__(repository: Repository | None = None, retries: Retry | None = None) → None

Initialize a new RestRequest instance.

Parameters:

  • repository – Optional repository to use. If not provided, the GitHub.repository will be used.

  • retries – Optional retry configuration for failed requests.

static convert_list_to_octoitems(result: list, item_class: type) → list

Convert a list of dictionaries to a list of OctoItem instances.

Parameters:

  • result – List of dictionaries from API response

  • item_class – The OctoItem subclass to convert each item to

Returns:

List of converted OctoItem instances

static convert_to_return_type(result: Any, return_type: type) → Any

Convert API response data to the specified return type.

Handles conversion of raw dictionary data from API responses to appropriate typed objects such as OctoItem instances or collections.

Parameters:

  • result – The raw API response data (dict or list of dicts)

  • return_type – The target type to convert to

Returns:

The converted data, or None if no conversion was performed

Extract a cursor value from a GitHub API next link URL.

Parameters:

next_link – The URL from the ‘next’ relation in a Link header.

Returns:

Cursor string or None if no cursor found.

get(path: str, parameters: dict = {}, expected: int | None = 200, authenticated: bool = False, display_errors: bool = True, error_handler: Callable[[int, dict], Any] | None = None) → dict | list[dict]

Make a GET request to the GitHub REST API.

This method handles pagination automatically, combining results from multiple pages when applicable.

Parameters:

  • path – The API path with optional format placeholders.

  • parameters – Dictionary of parameters to substitute in the path or add as query params.

  • expected – Expected HTTP status code (or None to accept any status code).

  • authenticated – Whether the request requires authentication.

  • display_errors – Whether to log error messages.

  • error_handler – Optional callback function to handle error responses.

Returns:

Either a dictionary (for single-item responses) or list of dictionaries (for collection responses).

Raises:

  • GHASToolkitError – For various API errors.

  • GHASToolkitAuthenticationError – When authentication is required but not provided.

Parse a Link header from GitHub API response.

GitHub uses the Link header for pagination as described in: https://docs.github.com/en/rest/guides/traversing-with-pagination

Parameters:

link_header – The Link header string from a GitHub API response.

Returns:

Dictionary with keys like ‘next’, ‘prev’, ‘first’, ‘last’ and URL values. Returns empty dict if the header is empty or invalid.

static restGet(url: str, authenticated: bool = False)

Get Request Wrapper.

GraphQLRequest API

GraphQLRequest is for all the Octokit APIs that require a GraphQL interface with GitHub.

class ghastoolkit.GraphQLRequest(repository: Repository | None = None)

Class for making GraphQL requests to GitHub.

This class handles GraphQL queries to the GitHub GraphQL API, including: - Loading queries from files or predefined constants - Formatting queries with variables - Making authenticated requests with rate limiting - Handling pagination with cursors

__init__(repository: Repository | None = None) → None

Initialize a new GraphQLRequest instance.

Parameters:

repository – Optional repository to use. If not provided, the GitHub.repository will be used.

formatQuery(query: str, **options) → str

Format a GraphQL query by substituting variables.

Uses string.Template to substitute variables in the query string.

Parameters:

  • query – The GraphQL query template.

  • **options – Variables to substitute in the query.

Returns:

The formatted query with variables substituted.

loadQueries(paths: list[str])

Load GraphQL queries from files in the specified paths.

Parameters:

paths – List of directory paths to load GraphQL queries from. Only files with .graphql extension will be loaded.

query(name: str, options: dict[str, Any] = {}) → dict

Run a GraphQL query by name.

Executes a named query from the queries dictionary with the given options. Automatically handles cursors for pagination.

Parameters:

  • name – Name of the query to execute (must exist in self.queries).

  • options – Variables to substitute in the query.

Returns:

The parsed JSON response from the GraphQL API.

Raises:

GHASToolkitError – If the query doesn’t exist or the API call fails.

References

https://docs.github.com/en/graphql/overview/about-the-graphql-api https://docs.github.com/en/graphql/overview/rate-limits-and-node-limits-for-the-graphql-api

OctoItem Class

class ghastoolkit.octokit.octokit.OctoItem

Base class for GitHub API response items.

OctoItem provides a flexible way to access data from GitHub API responses. It stores all raw response data in the __data__ dictionary and allows accessing it either through direct attributes or dictionary-style access.

This class is meant to be subclassed with dataclass annotations for strongly-typed field access.

__getattr__(name: str) → Any

Get attribute from data dictionary if not found in class.

This magic method is called when an attribute is not found through normal attribute access.

Parameters:

name – The attribute name to retrieve.

Returns:

The value from the __data__ dictionary.

Raises:

AttributeError – If the attribute is not found in __data__.

get(name: str, default: Any = None) → Any

Get attribute or dictionary value with fallback default.

Parameters:

  • name – The attribute or key to retrieve.

  • default – The value to return if the attribute/key is not found.

Returns:

The attribute value, dictionary value, or default if not found.