Client¶

The primary entry point for interacting with the GPP API.

The GPPClient provides:

Authenticated GraphQL and REST clients
Environment-aware configuration
Access to domain-specific interfaces for GPP resources

Quick Example¶

from gpp_client import GPPClient

async with GPPClient() as client:
   programs = await client.program.get_all()

Overview¶

The client initializes:

A GraphQL client for generated operations
A REST client for non-GraphQL endpoints
Domain interfaces for working with GPP resources

Each resource is accessed through a domain:

await client.program.get_by_id("p-123")
await client.observation.get_by_id("o-456")

Note

All domain methods are asynchronous and must be used within an event loop.

Authentication¶

Authentication is resolved automatically based on the active environment.

Development environment → requires GPP_DEVELOPMENT_TOKEN
Production environment → requires GPP_TOKEN

export GPP_DEVELOPMENT_TOKEN=...
export GPP_TOKEN=...

You may also pass a token explicitly:

client = GPPClient(token="my-token")

Note

The provided token is applied to the active environment automatically.

Creating a Client¶

Basic usage:

client = GPPClient()

Enable debug logging:

client = GPPClient(debug=True)

The client will automatically resolve:

The correct API endpoints
The appropriate authentication token

Available Domains¶

The following domains are available:

scheduler
program
observation
target
workflow_state
atom
attachment
goats
site_status

Each domain provides operations specific to its resource.

Connectivity¶

Use ping() to verify connectivity and authentication:

ok, error = await client.ping()

if ok:
   print("Connected")
else:
   print("Failed:", error)

Lifecycle Management¶

The client manages network resources and should be closed when no longer needed.

await client.close()

The client also supports async context management:

async with GPPClient() as client:
   ...

Underlying Clients¶

Advanced users may access the underlying transport clients directly.

GraphQL Client¶

The generated GraphQL client is available via:

graphql

REST Client¶

The REST client is available via:

rest

Warning

Direct use of the REST client is considered advanced usage and is rarely necessary. Prefer using domain interfaces whenever possible.

API Reference¶

class gpp_client.GPPClient(*, token: str | None = None, debug: bool | None = None)[source]¶

Bases: object

Main entry point for interacting with the GPP GraphQL API.

Parameters:

token (str, optional) – GPP API token to use for authentication. If not provided, the client will attempt to resolve a token from environment variables or other configuration sources.
debug (bool, optional) – Whether to enable debug logging for the client. If not provided, defaults to False.

atom: AtomDomain¶: Domain client for atom digest operations.

attachment: AttachmentDomain¶: Domain client for attachment upload, download, and management operations.

async close() → None[source]¶: Close any underlying connections held by the client.

goats: GOATSDomain¶: Domain client for GOATS-specific queries.

property graphql: GraphQLClient¶

Access the GraphQL client for making GraphQL requests.

Returns:: The GraphQL client instance.
Return type:: GraphQLClient

observation: ObservationDomain¶: Domain client for observation-related operations.

async ping() → tuple[bool, str | None][source]¶

Check if the GPP GraphQL endpoint is reachable and authenticated.

Returns:

bool – True if the connection and authentication succeed, False otherwise.
str, optional – The error message if the connection failed.

program: ProgramDomain¶: Domain client for program-related operations.

property rest: RESTClient¶

Access the REST client for making non-GraphQL requests.

Returns:: The REST client instance.
Return type:: RESTClient

scheduler: SchedulerDomain¶: Domain client for scheduler-related operations.

property settings: GPPSettings¶

Access the effective runtime settings of the client.

Returns:: The client’s runtime settings.
Return type:: GPPSettings

site_status: SiteStatusDomain¶: Domain client for Gemini site status information.

target: TargetDomain¶: Domain client for target-related operations.

workflow_state: WorkflowStateDomain¶: Domain client for workflow state operations.