Skip to main content

pygqlc

Python client for graphql APIs

Scope

This is an open source project, please feel free to fork it and PR to contribute with the community! Repo for the project: https://github.com/valiot/pygqlc

Features

  • Fast and efficient GraphQL client
  • Support for queries, mutations, and subscriptions
  • Async capabilities for modern Python applications
  • Connection pooling for better performance
  • IPv4/IPv6 network flexibility
  • Intelligent error handling and reporting
  • Easy-to-use API with minimal boilerplate
  • Optional structured logging with valiotlogging

Installation

Requirements:

  • Python 3.9+
  • Pipenv

Install directly from pypi:

$ cd <my-project-dir>
$ pipenv --python 3.7 # or 3.6
$ pipenv shell
$ pipenv install pygqlc
$ python
$ >> import pygqlc
$ >> print(pygqlc.name)

If you get "pygqlc" printed in the python repl, the installation succeded!

Optional: Enhanced Logging with valiotlogging

If you're using this library in a Valiot project, you can install it with the valiotlogging dependency for enhanced structured logging:

pip install pygqlc[valiotlogging]

Or in your pyproject.toml:

[tool.poetry.dependencies]
pygqlc = {version = "^3.5.3", extras = ["valiotlogging"]}

[[tool.poetry.source]]
name = "valiot"
url = "https://pypi.valiot.io/"
priority = "supplemental"

The library will automatically use valiotlogging if available, and will fall back to standard logging if not.

Usage

import os
from pygqlc import GraphQLClient
gql = GraphQLClient()
gql.addEnvironment(
    'dev',
    url=os.environ.get('API'), # should be an https url
    wss=os.environ.get('WSS'), # should be an ws/wss url
    headers={'Authorization': f"Bearer {os.environ.get('TOKEN')}"},
    ipv4_only=False,  # Set to True to force IPv4 connections (useful for environments with problematic IPv6)
    default=True)

From now on, you can access to the main API:

gql.query, gql.mutate, gql.subscribe

For queries:

query = '''
query{
  authors{
    name
  }
}
'''
data, errors = gql.query( query )

For mutations:

create_author = '''
mutation {
  createAuthor(){
    successful
    messages{field message}
    result{id insertedAt}
  }
}
'''
data, errors = gql.mutate( create_author )

For subscriptions:

def on_auth_created(message):
  print(message)

sub_author_created = '''
subscription{
  authorCreated{
    successful
    messages{field message}
    result{id insertedAt}
  }
}
'''
# unsub may be None if subscription fails (no internet connection, host unreachable, bad subscription doc, etc)
unsub = gql.subscribe(sub_author_created, callback=on_auth_created)
...
# when finishing the subscription:
unsub()
# when finishing all subscriptions:
gql.close()

Exception Handling

You can directly import the GQLResponseException for better error handling:

from pygqlc import GraphQLClient, GQLResponseException

gql = GraphQLClient()
# ... configure client ...

try:
    data, errors = gql.query('{ invalidQuery }')
    # Process data if no errors
except GQLResponseException as e:
    print(f"GraphQL error: {e.message}, Status: {e.status_code}")
    # Handle the exception appropriately

The subscribe method, returns an unsubscribe function, this allows to stop subscriptions whenever needed.

After finishing all subscriptions, the method GraphQLClient.close() should be called to close correctly the open GQL/websocket connections.

To reset all subscriptions and websocket connection use the method GraphQLClient.resetSubsConnection().

To be noted:

All main methods from the API accept a variables param. it is a dictionary type and may include variables from your queries or mutations:

query_with_vars = '''
query CommentsFromAuthor(
  $authorName: String!
  $limit: Int
){
  author(
    findBy:{ name: $authorName }
  ){
    id
    name
    comments(
      orderBy:{desc: ID}
      limit: $limit
    ){
      id
      blogPost{name}
      body
    }
  }
}
'''

data, errors = gql.query(
  query=query_with_vars,
  variables={
    "authorName": "Baruc",
    "limit": 10
  }
)

There is also an optional parameter flatten that simplifies the response format:

# From this:
response = {
  'data': {
    'authors': [
      { 'name': 'Baruc' },
      { 'name': 'Juan' },
      { 'name': 'Gerardo' }
    ]
  }
}
# To this:
authors = [
  { 'name': 'Baruc' },
  { 'name': 'Juan' },
  { 'name': 'Gerardo' }
]

Simplifying the data access from this:

response['data']['authors'][0]['name']

to this:

authors[0]['name']

It is query(query, variables, flatten=True) by default, to avoid writing it down everytime

The (_, errors) part of the response, is the combination of GraphQL errors, and communication errors, simplifying validations, it has this form:

errors = [
  {"field": <value>, "message":<msg>},
  {"field": <value>, "message":<msg>},
  {"field": <value>, "message":<msg>},
  ...
]

The field Attribute it's only available for GraphQL errors, when it is included in the response, so it's suggested that every mutation has at least this parameters in the response:

mutation{
  myMutation(<mutationParams>){
    successful
    messages{
      field
      message
    }
    result{
      <data of interest>
    }
  }
}

Post timeout:

You can set a post timeout to avoid an inactive process.

Use gql.setPostTimeout(seconds), or directly in the environment gql.addEnvironment(post_timeout=seconds). Default port_timeout is 60 seconds

Websocket timeout:

You can set a websocket timeout to keep subscriptions alive.

Use gql.setTimeoutWebsocket(seconds), or directly in the environment gql.addEnvironment(timeoutWebsocket=seconds). Default timeoutWebsocket is 60 seconds

IPv4 Only Connections

In some network environments, particularly on Linux systems, IPv6 connectivity issues can cause slow requests. To force the client to use IPv4 connections only, you can set the ipv4_only parameter when adding an environment:

gql.addEnvironment(
    'dev',
    url="https://api.example.com/graphql",
    ipv4_only=True  # Force IPv4 connections
)

This can resolve connectivity issues in networks with suboptimal IPv6 configurations.

Custom Logging

You can customize the logging behavior of pygqlc by using the set_logger function:

from pygqlc.logging import set_logger, LogLevel

# Example: Create a custom logger that writes to a file
def my_custom_logger(level, message, extra=None):
    with open('pygqlc.log', 'a') as f:
        f.write(f"[{level.value}] {message}\n")

# Set the custom logger
set_logger(my_custom_logger)

The default logger will use valiotlogging if available, otherwise it will use a simple print-based logger.

for mantainers:

Initial configuration

first of all, ensure you have configured poetry repositories correctly: poetry config repositories.valiot https://pypi.valiot.io/

and their credentials:

For private valiot's pypi:

poetry config http-basic.valiot <username> <password>

(ask adrian to send you the proper username and password for this step)

And for public pypi:

poetry config pypi-token.pypi <pypi-token>

(ask adrian or baruc to generate a token for you)

then,

regular publish steps (after initial configuration)

deploy using:

poetry version <patch | minor | major>

then publish to valiot's private pypi:

poetry publish --build -r valiot # build and PUBLISH TO PRIVATE VALIOTs PYPI

or:

poetry publish -r valiot

(if you already built the package)

then publish to public pypi:

poetry publish

After release, publish to github:

cat pygqlc/__version__.py

gh release create

gh release upload v<#.#.#> ./dist/pygqlc-<#.#.#>-py3-none-any.whl

and don't forget to keep the CHANGELOG.md updated!

Async Usage

Python 3.10+ supports async/await syntax for asynchronous programming. The GraphQLClient class provides async versions of the main methods:

import asyncio
from pygqlc import GraphQLClient

async def main():
    client = GraphQLClient()
    client.addEnvironment('dev', "https://api.example.com/graphql")

    # Async query
    data, errors = await client.async_query('''
        query {
            users {
                id
                name
            }
        }
    ''')

    if not errors:
        print("Users:", data)

    # Async mutation
    data, errors = await client.async_mutate('''
        mutation {
            createUser(input: {name: "John Doe"}) {
                user {
                    id
                    name
                }
            }
        }
    ''')

    if not errors:
        print("Created user:", data)

if __name__ == "__main__":
    asyncio.run(main())

The async methods are:

  • async_execute: Low-level method to execute GraphQL operations
  • async_query: For GraphQL queries
  • async_query_one: For queries that return a single item
  • async_mutate: For GraphQL mutations

These methods can be used with await in async functions and provide the same functionality as their synchronous counterparts, but with the benefits of asynchronous execution.

Metadata

Release files for pygqlc 3.9.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pygqlc 3.9.2
File Size Uploaded Provenance Actions
pygqlc-3.9.2.tar.gz 134.8 kB Without provenance Details for pygqlc-3.9.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for pygqlc 3.9.2
File Interpreter ABI Platform Actions
pygqlc-3.9.2-py3-none-any.whl Python 3 none any Details for pygqlc-3.9.2-py3-none-any.whl

Total release size: 160.0 kB

Release files / pygqlc-3.9.2.tar.gz

Download URL pygqlc-3.9.2.tar.gz
Size 134.8 kB
Tags Source
SHA-256 checksum
How to use checksums
cf691afcb3f2dc9b46652ede0836f233e5f74e7c0397f7b1d03b3a6c89e623b2
BLAKE2b-256 checksum
How to use checksums
d6aa1080f3e024da8e4b6ad338539ae771fffac3fc1bc9191a82a7b648b85b87
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.12.23 {"installer":{"name":"uv","version":"0.12.23","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / pygqlc-3.9.2-py3-none-any.whl

Download URL pygqlc-3.9.2-py3-none-any.whl
Size 25.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
a91bf8daae2beb7163ffea14133e8b1ab74b1aeb7d58981960fc5bbd9d1c18ad
BLAKE2b-256 checksum
How to use checksums
0f6dec2052ac051cb97afdc2aaadd60a33a51b10dfd091792318061e8d7b41c9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.12.23 {"installer":{"name":"uv","version":"0.12.23","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for pygqlc 3.9.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

3.9.2 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page