Skip to main content

Code Generator for GraphQL Query and Fragment Data Classes

Project description

Fork of qenerate

You're probably not looking for this package. Original: https://github.com/app-sre/qenerate

Changes

  • Put DEFINITION in generated fragment files too
  • Allow fields with skip or include to be omitted from the query response

qenerate

qenerate is a pluggable code generator for GraphQL Query and Fragment Data Classes. It works hand in hand with GraphQL clients like gql. Clients like gql return nested untyped dictionaries as result to a query. qenerate generated classes easily transform these nested untyped dictionaries into concrete classes. qenerate itself is not a GraphQL client and solely focuses on generating code for transforming untyped dictionaries into concrete types.

Installation

Releases are published on pypi.

pip install qenerate

Usage

Introspection

In a first step we must obtain the GQL schema in the form of an introspection query:

qenerate introspection http://my-gql-instance:4000/graphql > introspection.json

The introspection.json is used in a next step to map concrete types to your queries and fragments.

Code Generation

qenerate code -i introspection.json dir/to/gql/files

An introspection.json and a (nested) directory holding all your *.gql files are given. qenerate then generates data classes for every *.gql file it encounters while traversing the given directory.

qenerate expects that a .gql file contains exactly one query, mutation or fragment definition.

Note, that the given directory and every gql. file in it share the same scope. I.e., within this scope fragment and query names must be unique. Further, you can freely use any fragment within queries, as long as the fragment is defined somewhere within the scope (directory).

Example for Single Query

Single query and its generated classes.

Example for Query using a Fragment

We define a re-usable fragment which results in the following generated re-usable data classes.

The fragment is used in a query and imported in the generated python file.

More Examples

qenerate is actively used in our qontract-reconcile project. There you can find a lot of examples on how generated classes look like in more detail.

Plugins

qenerate follows a plugin based approach. I.e., multiple code generators are supported. Choosing a code generator is done inside the query file, e.g., the following example will generate data classes using the pydantic_v1 plugin:

# qenerate: plugin=pydantic_v1
query {
    ...
}

By choosing a plugin based approach, qenerate can extent its feature set creating new plugins while at the same time keeping existing plugins stable and fully backwards compatible.

Currently available plugins are:

Feature Flags

qenerate leverages feature flags to configure the behavior of the generator. Feature flags are passed to the generator via comments in your .gql definition file.

Plugin

# qenerate: plugin=<plugin-id>

This feature flag tells qenerate which plugin it should use to generate the code for the given definition.

Custom Type Mapping

You can tell qenerate to map a primitive GQL type (a.k.a. Scalar) to something that you want. This can be handy if your codebase expects other primitive datatypes like, e.g., str instead of Json or datetime. This can be especially useful for custom GQL primitives.

# qenerate: map_gql_scalar=JSON -> str

The above will tell qenerate to map the GQL JSON type to str instead of pydantic's Json. You can also map multiple types, e.g.,

# qenerate: map_gql_scalar=JSON -> str
# qenerate: map_gql_scalar=DateTime -> str

Naming Collision Strategy

# qenerate: naming_collision_strategy=[PARENT_CONTEXT | ENUMERATE]

This feature flag tells qenerate how to deal with naming collisions in classes. In GraphQL it is easy to query the same object in a nested fashion, which results in re-definitions of the type. We call this naming collision. A naming collision strategy defines how to adjust recurring names to make them unique.

PARENT_CONTEXT

This is the default strategy if nothing else is specified. It uses the name of the parent node in the query as a prefix.

ENUMERATE

This strategy adds the number of occurrences of this name as a suffix.

However, in most cases it might be cleaner to define a re-usable fragment instead of relying on a collision strategy. Here are some fragment examples.

Limitations

Overlapping properties

As of now qenerate does not support operations with overlapping properties. E.g.,

fragment MyFragment on Namespace {
    b {
        e
        f
    }
}

query MyQuery {
    namespaces {
        a
        ... MyFragment
        b {
            c  # This overlapps with properties in MyFragment
        }
    }
}

The above is valid GQL syntax and will merge properties defined in MyFragment and b { c } into b {c,e,f}. However, currently qenerate will fail to deduce proper base classes for these overlapps. Work on this is being conducted in #77.

Development

CI

CI happens on an app-sre owned Jenkins instance.

Build and Dependency Management

qenerate uses poetry as build and dependency management system.

Formatting

qenerate uses ruff for code checking and formatting.

Generating setup.py

pip install poetry2setup
poetry2setup .

Architecture

The architecture is described in more detail in this document.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

qenerate_custom-0.6.5.tar.gz (20.0 kB view details)

Uploaded Source

Built Distribution

qenerate_custom-0.6.5-py3-none-any.whl (21.9 kB view details)

Uploaded Python 3

File details

Details for the file qenerate_custom-0.6.5.tar.gz.

File metadata

  • Download URL: qenerate_custom-0.6.5.tar.gz
  • Upload date:
  • Size: 20.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.8.3 CPython/3.10.12 Linux/5.15.0-107-generic

File hashes

Hashes for qenerate_custom-0.6.5.tar.gz
Algorithm Hash digest
SHA256 0dfa4566b5d4be32a4fcaad358bebe66f2e0898e7a489c5073dc55eac09d5ead
MD5 42f530e787264877bd1211d385b6b2a2
BLAKE2b-256 214c0bc80f80feafd3c778b15b4eea86de2aa2078540a192d1c825e54a080bc1

See more details on using hashes here.

File details

Details for the file qenerate_custom-0.6.5-py3-none-any.whl.

File metadata

  • Download URL: qenerate_custom-0.6.5-py3-none-any.whl
  • Upload date:
  • Size: 21.9 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.8.3 CPython/3.10.12 Linux/5.15.0-107-generic

File hashes

Hashes for qenerate_custom-0.6.5-py3-none-any.whl
Algorithm Hash digest
SHA256 23d7222eb4ed29be6268262a9ffea0c2e59046cc1a77b8374fac277515c36586
MD5 41396ced00e157f8826c21d86bd48efd
BLAKE2b-256 8afcaaa1d7b8e9e3254d4b2542dc235510914ba376b9b08f4e404b4365754c3d

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page