pydantic-graphql 1.0.0

non intrusive python graphql client library wrapped around pydantic

ql (in development)

Graphql client library, wrapped around pydantic classes for type validation, provide simple, safe and pythonic way to query data from a graphql api.

using pydantic for creating python objects from rest api is common, it is easy and it has type validation, so why not make it easy also for graphql apis?

features:

• python objects to valid graphql string
• http send and recv information
• scalar query responses

TOC

• install
• what can it do
• how does it handle http
• configure my pydantic model
• querying
  • what if my class name is different from my query name?
  • what if my field name is different from my query name?
• query operations
  • arguments
  • inline fragments
• http
• query examples
  • simple query
  • smart implements w nested query w inline fragment
  • query with http
  • query and scalar response
• api
  • model
    • query_fields_nt
  • query

install

pip3 install pydantic-graphql

what can it do

at the time of writing, the ql library supports only querying data and scalarazing it to the pydantic models, no extra code is required to make your pydantic model compatible with the library.

to get a better image you can take a look at the #query examples

how does it handle http?

http can be different from implementation to implementation, most implementation of graphql are very simple, a single POST request with basic authentication, there is no need for that to be controlled by the library, the whole point of this library is to make it easy to work with pydantic and graphql apis, for how configure http read #http

configure my pydantic model

it is simple, you can just configure your pydantic model like so

import ql
from pydantic import BaseModel

@ql.model
class MyModel(BaseModel):
  ...

querying

querying is the most common operation in any api, we read data more then we mutate it, we will use this simple model for our example

import ql
from pydantic import BaseModel

@ql.model
class Point(BaseModel):
  x: int
  y: int

if we want to query this model from graphql, our request probably will look like this

query {
  Point {
    x,
    y
  }
}

with the ql library it will look like so

import ql 

# define the `Point` model

query_str = ql.query(
  (Point, (
    ql._(Point).x,
    ql._(Point).y
  ))
)

what the heck is the _ function? read here about the function

this python code will convert the python tuple to a valid graphql query that we can use to send graphql, we can print it

print(query_str)
# query{Point{x,y,__typename}}

by default, all query functions will add the __typename field, we can prevent that with passing the query function argument include_typename=False, but we won't do that for now.

the basic structure of a python query tuple is this

(<model>, (
  <field_a>,
  <field_b>,
  ...
))

now how do you deal with nested models?

import ql
from pydantic import BaseModel

@ql.model
class Owner(BaseModel):
  name: str
  age: int

@ql.model
class Shop(BaseModel):
  owner: Owner
  items_count: int

we want to query shop with the owner data, our graphql query will look like so

query {
  Shop {
    items_count,
    owner {
      name
      age
    }
  }
}

our python query will look like so

query_str = ql.query(
  (Shop, (
    ql._(Shop).items_count,
    (ql._(owner), (
      ql._(Owner).name,
      ql._(Owner).age
    ))
  ))
)

you see the pattern? for sub fields we use the same structured tuple, but instead of a model, we give it a field, it this nesting can continue as much as we want.

(<model>, (
  <field_a>,
  <field_b>,
  (<field_c>, (
    <c_model_field_a>,
    <c_model_field_b>
    ...
  ))
))

what if my class name is different from my query name?

by default when you decorate your model with ql.model, the used name in the query is the class name, but lets say we have this case

import ql
from pydantic import BaseModel

@ql.model
class Human(BaseModel):
  name: str

but our query should look like this

query {
  person {    # we need the name `person` instead of human
    name
  }
}

for that ql.model can take the argument query_name which will be used when we query that model

@ql.model(query_name="person")
class Human(BaseModel):
  ...

and we can query regularlly

query_str = ql.query(
  (Human, (
    ql._(Human).name
  ))
)
print(query_str)
# query{person{name, __typename}}

what if my field name is different from my query name?

in case we have this case:

import ql
from pydantic import BaseModel

@ql.model
class Human(BaseModel):
  first_name: str
  middle_name: str
  last_name: str

but our query should look like so

query {
  Human {
    name,  # first_name
    middle,  # middle_name
    last  # last_name
  }
}

we can attach metadata to our field that tells ql, that this field has different query name

...
from typing import Annotated

@ql.model
class Human(BaseModel):
  first_name: Annotated[str, ql.metadata(query_name="first")]
  middle_name: Annotated[str, ql.metadata(query_name="middle")]
  last_name: Annotated[str, ql.metadata(query_name="last")]

we can query regularly and we get our expected results

query_str = ql.query(
  (Human, (
    ql._(Human).first_name,
    ql._(Human).middle_name,
    ql._(Human).last_name
  ))
)
print(query_str)
# query{Human{first,middle,last,__typename}}

query operations

in graphql we have couple of operations that we can use when we query our data

raw query

send a simple query string and get response dict

response = ql.raw_query_response("""
  query {
    Person(name: "bob") {
      name,
      age
    }
  }
""")

scalar response

scalar given graphql response, note that the response must contain the __typename field for any type, thats how the scalar knows which model should be used

arguments

graphql supports arguments when querying, ql supports it too

import ql
from pydantic import BaseModel

@ql.model
class Human(BaseModel):
  name: str
  age: int

query_str = ql.query(
  (ql.arguments(Human, filter="age <= 50"), (
    ql._(Human).name,
    ql._(Human).age
  ))
)
print(query_str)
# query{Human(filter: "age <= 50"){name,age,__typename}}

it is simple as just wrapping our model with ql.arguments

inline fragments

graphql supports inline fragments, this happens when a type can return multiple different types with different fields, ql supports that too

import ql
from pydantic import BaseModel

@ql.model
class Human(BaseModel):
  name: str

@ql.model
class Male(Human):
  working: bool

@ql.model
class Female(Human):
  pregnant: bool

query_str = ql.query(
  (Human, (
    ql._(Human).name,
    (ql.on(Male), (
      ql._(Male).working,
    )),
    (ql.on(Female), (
      ql._(Female).pregnant,
    ))
  ))
)
print(query_str)
# query{Human{name, ...on Male{working,__typename}, ...on Female{pregnant,__typename},__typename}}

http

todo

Query examples

simple query

import ql
from pydantic import BaseModel


@ql.model
class Point(BaseModel):
  x: int
  y: int


q = ql.query(
  (Point, (
    ql._(Point).x,
    ql._(Point).y
  ))
)
print(q)

---

query{Point{x,y}}

smart implements w nested query w inline fragment

import ql
from pydantic import BaseModel

@ql.model
class Human(BaseModel):
  first_name: str
  last_name: str

@ql.model
class Female(Human):
  pregnant: bool

@ql.model
class Male(Human):
  pass

print(ql.implements(Human))  # what does `Human` implement
q = ql.query(
    (Human, (
        ql._(Human).first_name,
        (ql.on(Female), (
            ql._(Female).pregnant,
        ))
    ))
)
print(q)

---

frozenset({<class '__main__.Human'>})
query{Human{first_name,...on Female{pregnant,__typename},__typename}}

query with http

import ql
import requests
from pydantic import BaseModel

ql.http.set_request_func(lambda q: requests.get(...).json())

# define models ...

response = ql.query_response(
  (Point, (
     ql._(Point).x,
     ql._(Point).y
  ))
)
print(response)

---

{"data": {"point": "x": 50, "y": -50}}

query and scalar response

import ql
import requests
from pydantic import BaseModel

ql.http.set_request_func(lambda q: requests.get(...).json())

@ql.model
class Point(BaseModel):
  x: int
  y: int

scalared = ql.query_response_scalar(
 (Point, (
   ql._(Point).x,
   ql._(Point).y
  ))
)
print(scalared)

---

{"point": Point(x=50, y=-50)}

api

model

query_fields_nt

returns a namedtuple with the model queryable fields, which maps between the model field name, to the defined field query_name.

import ql 
from typing import Annotated
from pydantic import BaseModel

@ql.model
class Human(BaseMode):
  first_name: Annotated[str, ql.metadata(query_name="name")]
  last_name: Annotated[str, ql.metadata(query_name="family_name")]
  age: int

print(ql.query_fields_nt(Human).first_name)  # name
print(ql.query_fields_nt(Human).last_name)   # family_name
print(ql.query_fields_nt(Human).age)  # age

NOTE: because this function is common when querying, there is a function alias _ which just wraps the query_fields_nt, so calling _ is actually calling query_fields_nt

query

query

todo

query_response

todo

query_response_scalar