Python client models should be automatically derived from the GraphQL schema

[andy-sweet]

The model classes in the Python client are manually maintained in _models.py.

The class and field names are almost entirely defined in the GraphQL schema, which is also in this repository.

Maintaining this manually has created documentation errors in the past, and may lead to bigger issues in the future when the schema changes.

The goal here is to automatically derive these model classes from the GraphQL schema.

Some customization of the classes may be needed to handle functionality like Tomogram.download_mrcfile.

[andy-sweet]

For context, this issue came up during a conversation between me, @justinelarsen, and @jgadling .

Since there are some upcoming expected changes to the schema, it seemed like a good time to fix this.

Some ideas about solutions.

• Using a code generation tool to go from the GraphQL schema definition to Python data classes (e.g. https://koxudaxi.github.io/datamodel-code-generator/).
• Use a different GraphQL client library that can automatically define Python data classes from the schema at run-time (e.g. https://github.com/profusion/sgqlc)

If we decide to use platformics to generate the GraphQL schema in the future, we might consider automatically defining the Python GraphQL client and related data classes earlier since there are likely existing related Python data classes at that point (e.g. from SQLAlchemy, Pydantic, Strawberry).

[andy-sweet]

TLDR: the best first approach is to use graphql-core (which the current gql client depends on, and is the de-facto Python port of GraphQL.js), to parse the schema then write our own simple code generator to selectively generate the classes and fields we need.

I looked at a few options and made some rough notes.

sgqlc

• https://github.com/profusion/sgqlc
• not much customization of output (e.g. docstrings, aliases)
• output (without further processing) requires switching to using the sgqlc client, which is an option but more change

datamodel-code-generator

• https://koxudaxi.github.io/datamodel-code-generator/
• more customizable output than sgqlc
• output alone can't be used with current client and fields, would need further wrapping processing (maybe possible with templating, but my sense is that won't handle the custom fields we have)
• also provides parser that might be useful for our own codegen

ariadne-codegen

• https://github.com/mirumee/ariadne-codegen
• related to the wider ariadne project (mostly used for schema first definition of graphql server with ability to easily add custom python logic)
• well documented, but also needs to use the custom client generated, and looks like we'd need to add some logic on top

gql

• https://github.com/graphql-python/gql
• this is the client we currently use (with some customization)
• this depends on graphql-core, which we can use to build a GraphQLSchema document (using build_schema with the DSL string), which we could then use to write our own code generator
• can also get the same schema from the client instance (client.schema)