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
orinclude
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:
- pydantic_v1 for generating Pydantic data classes
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
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
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
Algorithm | Hash digest | |
---|---|---|
SHA256 | 0dfa4566b5d4be32a4fcaad358bebe66f2e0898e7a489c5073dc55eac09d5ead |
|
MD5 | 42f530e787264877bd1211d385b6b2a2 |
|
BLAKE2b-256 | 214c0bc80f80feafd3c778b15b4eea86de2aa2078540a192d1c825e54a080bc1 |
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
Algorithm | Hash digest | |
---|---|---|
SHA256 | 23d7222eb4ed29be6268262a9ffea0c2e59046cc1a77b8374fac277515c36586 |
|
MD5 | 41396ced00e157f8826c21d86bd48efd |
|
BLAKE2b-256 | 8afcaaa1d7b8e9e3254d4b2542dc235510914ba376b9b08f4e404b4365754c3d |