Other Classes

class githubgql.Clock.Clock(msg: str)

A simple class to time blocks of code via with statements

  • Turn on/off via the clock_on key in config.yml

  • The time value on the left is the total time since first use of Clock (it may be useful to trigger at application start to initialize the start time).

  • The time value on the right is the specific time for this step.

Usage:

with Clock("Doing a thing I want to optimize"):
    do_the_thing()

Output:

(0.000s) >> Doing a thing I want to optimize… done (0.147s)
class githubgql.Config.Config

Access to config.yml data

Usage:

Config.get().github_graphql_schema  # the Github GraphQL schema filename
class githubgql.Merger.Merger

A merger designed to work properly with results from the GitHub GraphQL API

class githubgql.Paginator.Paginator(gql_client: Client, query_str: str, vars: dict[str, str], *, page_size=100, auto_fit_quotas=True, inject_default_fields=True, cleanup_query=True)

Iterator that coordinates the pagination among Client, Query, and Result

class githubgql.PathKey.PathKey(iterable: Iterable[str] = [])

A list of strings that can be used as a dictionary key

class githubgql.Query.Query(query: str, *, default_page_size: int = 100, auto_fit_quotas=True, inject_default_fields=True, cleanup_query=True)

The magic that allows a simple query to represent a full, complex GQL query

Options to simplify your query definition:

  1. Remove the pagination arguments, unless you wish to control the page size and/or direction of paging (use first/last: n for size, after/before: null for direction, or both).

  2. Remove edges/node and nodes levels, unless you need to specify info at those levels. The Query class will inject them for you.

  3. Omit common id fields and let Query inject them for you.

  4. Cleanup common authoring errors, such as empty bracket scopes.

Useful case for this class by itself:

Check the traditional query that your simplified query would be equivalent to:

from githubgql.Query import Query
from graphql import print_ast
query = """
query myQuerySpec {
    # your query spec here
}
"""
ast = Query(query).get_doc()
print_ast(ast)
class githubgql.Results.Results(result: ResultNode)

Transformer for results from the GitHub GraphQL API

Simplifications to the query results:

  1. Build pagination updates and apply them back to the query for the next page request.

  2. Remove the pagination information from results comunicated back to the client.

  3. Remove auto-injected edges/node levels from the result, leaving only those that were specified manually in the original query.

class githubgql.Schema.Schema

Efficiently access and manage the Github GraphQL schema

It takes an unacceptable amount of time (0.59s on my Apple M1 laptop) to load and parse the GitHub GraphQL schema, so do it only once and save the in-memory representation to use for every query. But we can also do better than that. By writing it back out in binary with dill (standard pickle fails on the lambda functions in the graphql library), all future reads can get the data in less than half the time (0.21s).

I’d prefer to prep the binary file on install, but python does not support arbitrary code execution at install time. So we try to load the .bin and fail over to parsing and writing it out async.

For now I’m not messing around with flock stuff and trying to make sure some other process doesn’t kick off and load right as the first one is writing. The second __SHOULD__ throw an exception when it gets incomplete dill data and trigger the text load/parse flow. Then when it goes to write, it’ll either get a PermissionError if the first proc still has it open, or else open it up and re-write the same data over. Either way, we should be functionally correct. Optimization at this point would be premature.