this library is wrapped around pydantic for easy modeling, typechecking and +because it is pydantic, it is well known package, no need to reinvent the wheel here.
+ql over other libraries++At the time of writing this library does NOT support
+mutation, onlyquery.
this library was written because when I searched for graphql client libraries, I couldn't
+find easy/well written libraries for graphql, most of the libraries are small wrappers around requests,
+or they are trying to reinvent the wheel, and they just feel awkward...
simplicity - it is simple to query data, you can provide a query string, or generate a
+query string with python objects.
pydantic - working with a well known library doesn't requires you to learn a lot of new things, also typechecking
scalar - unlike other libraries, where there is no scalarize ability, or sometimes they require you to
+create a Schema, ql library takes use of the __typename field from graphql for scalarize functionality, which means,
+you don't need to create Schema classes, and it can scalar from any given graphql response as long it includes the __typename
+field for sub types
exceptions are only raised in scalar requests, when we convert graphql
+response to python objects it make sense to convert graphql errors to python exceptions.
graphql errors are always the same, if it returned an error you have a problem +with your query.
+an exception class that is raised when scalar function +gets error response from graphql +
+| Name | +Type | +Description | +
|---|---|---|
errors |
+list[QueryErrorDict] |
+list of graphql errors | +
import ql
+
+try:
+ _ = ql.scalar_query_response({
+ "errors": [
+ {"message": "example for error", "locations": {"line": 0, "column": 0}},
+ {"message": "I have another error in my query!", "locations": {"line": 0, "column": 0}},
+ ],
+ "data": None
+ })
+except ql.QLErrorResponseException:
+ print("damn... my graphql query failed...")
+propertyreturns a list of QLErrorDetails.
class used to map each error detail to python object +
+| Name | +Type | +Description | +
|---|---|---|
message |
+str |
+the message field from the graphql error | +
locations |
+list[QueryErrorLocationDict] |
+list of locations where the error occurse | +
this library does not implement http communication with graphql server since API can be
+different from implementation to implementation. the library http client accept a request function
+that takes a graphql query string, and returns the json response parsed as dict, this allows
+the flexability to implement error handlers in the passed request function instead
+of wrapping each query request with try...except.
set request function for the ql client
+
| Name | +Type | +Description | +
|---|---|---|
request_func |
+GraphqlRequestFunc |
+callable function that accepts a string and returns dict | +
import ql
+import requests
+
+def request_graphql(query: str) -> dict:
+ response = requests.post("...", json={"query": query})
+ response.raise_for_status() # can handle errors here in one place
+ return response.json()
+
+ql.http.set_request_func(request_graphql)
+send request query with given request function +
+| Name | +Type | +Description | +
|---|---|---|
query |
+str |
+the query request that will be passed to the function | +
returns a dict mapping between all registered models and thier +registered typename
+ +returns the model configured typename, if model is not registered
+with ql.model then return None
| Name | +Type | +Description | +
|---|---|---|
model |
+type[BaseModel] |
+the model we want the typename for | +
returns all child models, that the given model implements
+ +| Name | +Type | +Description | +
|---|---|---|
cls |
+type[BaseModel] |
+the model we want to take implementations from | +
import ql
+from pydantic import BaseModel
+
+
+@lq.model
+class Human(BaseModel):
+ first_name: str
+ last_name: str
+
+
+@ql.model
+class Male(Human):
+ pass
+
+
+@ql.model
+class Female(Human):
+ pass
+
+
+print(ql.implements(Human))
+# (<class '__main__.Male'>, <class '__main__.Female'>)
+returns a namedtuple of all queryable fields in the given model, mapping between +the model field name to the query name.
+Info
+this function is also aliased as ql._ because it is common
| Name | +Type | +Description | +
|---|---|---|
cls |
+type[BaseModel] |
+the model we want the namedtuple from | +
import ql
+from typing import Annotated
+from pydantic import BaseModel
+
+
+@ql.model
+class Article(BaseModel):
+ name: Annotated[str, ql.metadata(query_name="title")]
+ description: str
+
+ foo: Annotated[str, ql.metadata(queryable=False)]
+
+print(ql.query_fields_nt(Article).name) # "title"
+print(ql.query_fields_nt(Article).description) # "description"
+print(ql.query_fields_nt(Article).foo) # exception
+reading data from apis is the most common operation we do, that's why ql makes it
+easy to query data from your graphql endpoint and provide variety of query methods.
takes python ql query structure and returns a valid graphql query string. +
def query(
+ *query_models: _QueryModelType,
+ fragments: Optional[_QueryFragmentType] = None,
+ include_typename: bool = True,
+) -> str:
+| Name | +Type | +Description | +
|---|---|---|
query_models |
+*_QueryModelType |
+python ql structured query | +
fragments |
+Optional[_QueryFragmentType] |
+dict mapping between ql.fragment to the python ql structured query |
+
include_typename |
+bool |
+if include __typename field when querying sub types |
+
import ql
+from pydantic import BaseModel
+
+@ql.model
+class Point(BaseModel):
+ x: int
+ y: int
+
+query_str = ql.query(
+ (Point, (
+ ql._(Point).x,
+ ql._(Point).y
+ ))
+)
+serializes the ql query structure, send it via http and returns the response as dict.
+
def query_response(
+ *query_models: _QueryModelType,
+ fragments: Optional[_QueryFragmentType] = {},
+ include_typename: bool = True,
+) -> QueryResponseDict:
+http request function must be set to make this function work, click here to view.
+serializes the ql query structure to a valid graphql query, send it via http, takes the response
+and returns a scalared dict with the defined models, this function will also raise
+graphql errors if the query responsed with errors field
+