Python example using our API

Our API uses GraphQL, below is an example of how to leverage GraphQL’s automatic code generation to work with our services as if it were part of your application itself.

1. Start a new project and install dependencies

   uv is a modern Python package manager:

   #!/bin/bash
   mkdir example && cd example
   uv init
   uv add ariadne-codegen  # GraphQL codegen tool

2. Setup codegen configuration

   Update the pyproject.toml file to specify settings for autogenerated code.

   ./pyproject.toml

   [project]
   name = "example"
   version = "0.1.0"
   description = "Add your description here"
   readme = "README.md"
   requires-python = ">=3.13"
   dependencies = [
       "ariadne-codegen>=0.14.0",
   ]
   
    [tool.ariadne-codegen]
    target_package_path = "./client"
    queries_path = "./queries"
    remote_schema_url = "https://api.helioadditive.com/graphql"
    target_package_name = "graphql_client"
    async_client = true
    include_comments = "stable"
    convert_to_snake_case = true
    include_all_inputs = true
    include_all_emums = true

3. Create a graphql file to query data

   You choose what data you want to receive

   ./queries/Materials.graphql

   query ListMaterials($page: Int, $pageSize: Int, $filters: [MaterialFilter!]) {
     materials(page: $page, pageSize: $pageSize, filters: $filters) {
       pages
       pageInfo {
         hasPreviousPage
         hasNextPage
       }
       objects {
         ... on Material {
           id
           name
           brand {
             id
             name
           }
         }
       }
     }
   }

4. Autogenerate the code

   uv run ariadne-codegen --config pyproject.toml

   All generated code should now be generated in the ./client directory

5. Update the main.py to use the generated code

   Notice that there is no logic to handle the requests, that logic is already autogeneratd and baked into functions like materials

   ./main.py

   import asyncio
   import httpx
   from client.client import client
   
   headers = {"Authorization": "Bearer <helio_pat>"}
   graphql_client = Client(
       url="https://api.helioadditive.com/graphql",
       headers=headers,
       http_client=httpx.AsyncClient(headers=headers, timeout=60)
   )
   
   async def main():
       materials = await graphql_client.materials(page_size=20)
       for material in materials.objects:
           # The `material` object is fully type inferred
           material_id = material.id
           material_name = material.name
   
   if __name__ == "__main__":
       asyncio.run(main())

6. Next steps

   You can now add any .graphql files you need into the queries directory, re-run the codegen tool, and start using it directly in the code.