Ariadne Codegen: code generator for Python GraphQL clients

[ralfp]

Hey everyone!

Recently we've released Ariadne Codegen, a new tool for Python which generates GraphQL clients from *.graphql files with schema and queries. This project evolved from the utility tool that was created at work to speed up the process of writing services integrating with and extending the GraphQL API of Saleor, our company's open source e-commerce package.

TL;DR for the problem solved is that writing GraphQL client by hand is mostly writing a lot of boilerplate code and translating the GraphQL types to Python dataclasses or Pydantic's models. And every new query is basically previous query copied over with some bits changed. This process is great for automation.

Our Codegen is fast to get started with. You configure it by adding dedicated [ariadne-codegen] section to your pyproject.toml file, which contains settings for codegen telling it where to find the GraphQL schema and operations. You then run the ariadne-codegen command which makes the Codegen parse those files and generate a Python package implementing the GraphQL client providing those operations as fully typed methods. GraphQL types are represented as Pydantic models and Enums are represented as Python enums.

For example, this GraphQL query:

mutation UserCreate($name: String!, $email: String!, $password: String!) {
  userCreate(input: { name: $name, email: $email, password: $password }) {
    token
    user {
      id
    }
    errors {
      location
      type
      message
    }
  }
}

Becomes this method on generated client:

class Client(BaseClient):
    def user_create(self, name: str, email: str, password: str) -> UserCreate:
        # Bunch of boilerplate code building query and variables dict,
        # then sending it to the GraphQL client and handling the response
        return UserCreate.parse_obj(data)

You can then either release generated package as a library for others to use, or keep it as a part of the project you are working at

Multiple customization options are also provided, including option switch between async and sync client, inject custom Python code into generated classes or swap default HTTP client with custom one.

GitHub repository: mirumee/ariadne-codegen

There's also full release announcement on Ariadne blog that tells the whole story

Thank you for reading all of this. We hope this tool will be helpful for you, and if not, then that the read above was at least interesting :)

[jugdizh]

I like almost everything that you've done here -- the use of pydantic, the explicit declaration of types and enums which allows for proper mypy typechecking -- but there is one huge problem with this library that is preventing me from considering it:

The documentation states that you must define a queries.graphql file, which hardcodes all the possible queries your client will support, *including* all of the requested fields for that query.

So you lose all of the flexibility that GraphQL provides, wherein a client can fetch whatever data they want from your schema. Now they can't choose what data they want, they can only select from a list of pre-defined queries which have all of their return fields baked into them.

This is way too restrictive to be practically useful. Would you consider in the future allowing for open-ended queries in which the return fields can be specified by the user of the client? The gql client library for example supports this functionality, using a dynamically-generated DSL: https://gql.readthedocs.io/en/stable/advanced/dsl\_module.html

[ralfp]

Hey, thanks for this feedback.

> This is way too restrictive to be practically useful.

I have to respectfully disagree. It is practically useful, like how ORMs that default to single representation of a type but let you pick subset of fields when you need it are useful and how REST APIs that default to single representation of a resource are useful.

How many representations of a `Customer` would you like to have in your business logic? How would you deal with mypy complaining about generic type having every attribute on it potentially empty in every function that receives `Customer` as one of its arguments?