A fast and modern graphql client library designed with simplicity in mind.
Project description
Qlient: Python GraphQL Client
A fast and modern graphql client library designed with simplicity in mind.
Getting Started
Installing
pip install python-qlient
Usage
This example shows a simple query
from qlient import Client
client = Client("https://countries.trevorblades.com/")
response = client.query.countries(select=["name"])
Documentation
The Documentation covers the following points:
Query
Queries are the A and O of graphql and are as easy as:
from qlient import Client
client = Client("https://countries.trevorblades.com/")
response = client.query.country(select=["name", "capital"], where={"code": "CH"})
Which will make a request to the server and return the name and capital of the country switzerland.
But what if you want to make a more complex query with fields within fields? Don't need to worry, we got you covered:
from qlient import Client, fields
client = Client("https://countries.trevorblades.com/")
response = client.query.country(select=fields("name", "capital", languages=fields("name")), where={"code": "CH"})
Using the fields method from qlient
you can simply use *args
and **kwargs
for making deeper selections.
By the way, you could stack this like forever.
Last but not least, what if you don't know the fields you could select?
Yup, we got you somewhat covered as well. The thing is, that due to performance issues,
this package is not able to completely create a query that retrieves all fields for a Query.
I have set the max depth to 2 (Can be changed via Settings). This allows to still send a query without selecting any fields
but you won't get them all. If you want all, use the fields
function defined above.
from qlient import Client
client = Client("https://countries.trevorblades.com/")
response = client.query.country(where={"code": "CH"})
Mutation
I haven't found a real world example for making mutations without being authenticated, so here's a hypothetical one.
from qlient import Client
client = Client("https://some-host.com/authentication")
response = client.mutation.register(data={"email": "foo@bar.com", "password": "987654321"}, select=["userId"])
Subscription
Sometimes you want to execute things when something - an action - happened on the server.
In those cases, you can subscribe to an event.
For subscribing to an endpoint, I am using the asyncio websockets
library.
So have a look at their documentation for clarification.
Here is a basic example
import asyncio
from qlient import Client
client = Client("http://your-host:8080") # remains the same
def on_event(data: dict):
# ... do something with the data
print(data)
asyncio.run(client.subscription.my_subscription(handle=on_event)) # the asyncio.run() function is important!
Different Websocket endpoint
If no websocket endpoint was specified, it gets adapted based on the given request host.
for example http://localhost:3000
becomes ws://localhost:3000
.
Same goes for secured connections: https
becomes wss
.
But it may be, that you have different endpoints. Therefor you can specify the websocket endpoint
manually.
from qlient import Client
client = Client("http://your-host:8080", ws_endpoint="wss://your-other-host:3000")
Transporter
For making requests, we use a transporter. (Irrelevant for Websockets.)
If none is given, a new one will be created.
Sometimes you want your own custom session to be used for making requests. For example if you need to authenticate yourself with some sort of an api key. Therefor, you can pass it directly to the transporter.
import requests
from qlient import Client, Transporter
my_session = requests.sessions.session()
my_session.headers["Authorization"] = "Bearer some-api-token"
client = Client("https://foo.bar/", transporter=Transporter(session=my_session))
AsyncTransporter
And an AsyncTransporter:
import asyncio
from qlient import Client, AsyncTransporter
client = Client("https://countries.trevorblades.com/", transporter=AsyncTransporter())
async def request_data():
return await client.query.country(select=["name", "capital"], where={"code": "CH"})
asyncio.run(request_data())
Settings
Most things can be adjusted using the settings. When no settings are passed by to a client, the default values will be used instead
max_recursion_depth
The max_recursion_depth can be used for changing the max depth for deeper automatic selection lookup. Default is 2.
from qlient import Client, Settings
settings = Settings(max_recursion_depth=5) # Due to performance reasons I do not recommend to go any higher than that.
client = Client("https://countries.trevorblades.com/", settings=settings)
base_response_key
The base_response_key can be changed for setting the base key that is being used to get the data from the server. Default is "data".
from qlient import Client, Settings
settings = Settings(base_response_key="my_custom_data_key")
client = Client("https://countries.trevorblades.com/", settings=settings)
base_payload_key
The base_payload_key can be changed for setting the base key that is being used to read the data from the websocket response. Default is "payload".
from qlient import Client, Settings
settings = Settings(base_payload_key="my_custom_payload_key")
client = Client("https://countries.trevorblades.com/", settings=settings)
return_requests_response
The return_requests_response can be set to True if you want the whole request back instead of just the json. Default is False.
from qlient import Client, Settings
settings = Settings(return_requests_response=True)
client = Client("https://countries.trevorblades.com/", settings=settings)
disable_selection_lookup
The disable_selection_lookup can be set to True if you want to disable the automatic selection lookup. Default is False.
from qlient import Client, Settings
settings = Settings(disable_selection_lookup=True)
client = Client("https://countries.trevorblades.com/", settings=settings)
return_full_subscription_body
The return_full_subscription_body can be set to True if you want to get the full websocket response instead of only the data.
from qlient import Client, Settings
settings = Settings(return_full_subscription_body=True)
client = Client("https://countries.trevorblades.com/", settings=settings)
CLI
Qlient also provides a CLI for inspecting a schema.
qlient --inspect "https://countries.trevorblades.com/"
# or short:
# qlient -i "https://countries.trevorblades.com/"
Authors
- Daniel Seifert - Initial work - Lab9
Acknowledgments
- Heavily inspired by Zeep
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
Hashes for python_qlient-1.0.2-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 355ea7a587ca44923757fba8ee10fb55d711023ae79ad5d37bba65cfbefa39d5 |
|
MD5 | ea6697bf3a7732f5fc3d92d17ed9fe5f |
|
BLAKE2b-256 | 4aa6e01dc19f55eb42096b088be2a3f9be81318c5e48b7ab4c62b1d239ba6eb4 |