📦 ptal‑api Repository Documentation

tl;dr This repository provides a Python client library (ptal_api) for interacting with the Talisman GraphQL APIs, along with a generator script that automatically creates type‑safe client code from GraphQL schemas.

Table of Contents

1. What the repository contains
2. Prerequisites
3. Installation (as a library)
4. Project layout
5. Generating API client code
6. Using the generated client
7. Example snippets
8. Testing
9. Code Style

What the repository contains

Prerequisites

Install everything with Poetry:

poetry install

Or, if you prefer plain pip:

pip install ariadne-codegen ruff httpx keycloak websockets

Installation (as a library)

Once the generated schemas exist (see the Generating API client code section), you can install the package locally for development:

# From the repository root
poetry build
poetry install

Or use it directly from the source tree:

pip install -e .

Project layout

ptal-api/
│
├─ ptal_api/
│   ├─ __init__.py
│   ├─ client.py                # High‑level GraphQL client wrapper
│   ├─ auth_provider.py         # Abstract authentication base class
│   ├─ keycloak_provider.py     # Keycloak‑based auth implementation
│   ├─ no_auth_provider.py      # No‑auth placeholder
│   ├─ schemas/                 # ← generated GraphQL modules
│   │   ├─ mesh_schema/
│   │   └─ system_utils_schema/
│   └─ ...                      # Additional utilities
│
├─ generator_script/
│   ├─ async_base_client.py     # Shared async client base class
│   ├─ generate_script.py       # Main generation entry point
│   └─ toml_configs/
│       ├─ mesh.toml
│       └─ system_utils.toml
│
├─ examples/
│   ├─ adapter_usage.py
│   ├─ cancel_job.py
│   ├─ get_periodic_job.py
│   └─ raw_execute.py
│
├─ tests/                       # pytest test suite
│
├─ .gitlab-ci.yml               # CI pipeline definition
├─ pyproject.toml               # Poetry project definition
├─ poetry.lock
└─ README.md                    # (this file)

Key modules

Generating API client code

The repository ships a generator script that automates the entire workflow for the two GraphQL APIs (mesh and system_utils). The script:

1. Validates that it runs from the correct directory.
2. Calls ariadne‑codegen with the appropriate TOML configuration.
3. Moves the generated package into ptal_api/schemas/.
4. Patches imports so they point to the shared ptal_api package (ptal_api.base_model, ptal_api.base_operation, etc.).
5. Runs Ruff to format the code and fix lint issues.

How to run it

cd ptal-api/generator_script
python generate_script.py

The script will output progress messages such as:

Generating mesh_schema
Ended generating mesh_schema
...
Generating system_utils_schema
Ended generating system_utils_schema

... (ruff output) ...

When it finishes, you’ll find the generated Python modules under:

ptal_api/schemas/mesh_schema/
ptal_api/schemas/system_utils_schema/

Note – If you add a new schema, create a matching *.toml file in generator_script/toml_configs/ and extend the apis tuple in generate_script.py.

Using the generated client

Below is a minimal example that shows how to set up a client with Keycloak authentication and execute a simple query.

import os
import asyncio

from ptal_api.client import Client
from ptal_api.auth_providers import KeycloakAuthProvider
from ptal_api.schemas.mesh_schema.custom_queries import Query as MeshQuery
from ptal_api.schemas.mesh_schema.custom_fields import DocumentFields


async def main() -> None:
    auth = KeycloakAuthProvider(
        auth_url=os.getenv("KEYCLOAK_URL"),
        realm=os.getenv("KEYCLOAK_REALM"),
        client_id=os.getenv("KEYCLOAK_CLIENT_ID"),
        client_secret=os.getenv("KEYCLOAK_CLIENT_SECRET"),
        user=os.getenv("KEYCLOAK_USER"),
        password=os.getenv("KEYCLOAK_PASSWORD"),
    )

    client = Client(url=os.getenv("GRAPHQL_URL"), auth_provider=auth)

    # Example: fetch a document by ID
    document_query = MeshQuery.document(id="12345")
    document_query.fields(
        DocumentFields.id,
        DocumentFields.title,
        DocumentFields.document_content_type,
    )

    response = await client.query(document_query, operation_name="GetDocument")
    print(response)


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

Quick tips

Example snippets

The examples/ directory contains ready‑to‑run scripts that illustrate common patterns:

You can run any example with:

cd examples
poetry run python <example_name>.py

Remember to set the required environment variables (GRAPHQL_URL, KEYCLOAK_*, etc.) beforehand.

Testing

The repository ships a pytest‑based test suite under tests/. To execute it locally:

poetry run pytest

The CI pipeline (see next section) runs the same command on every merge request, ensuring that new changes keep the library stable.

Code Style

• Follow the existing formatting (auto‑formatted by Ruff).
• Keep import statements absolute (from ptal_api.base_model import …).
• Prefer async functions and await wherever possible.