Client¶

The main entry point for interacting with the GPP GraphQL API.

The GPPClient class manages:

Transport and authentication
Environment and credential resolution
Schema introspection
Access to high-level, resource-specific managers for executing GraphQL queries and mutations

Each resource is exposed through a manager accessible as an attribute on the client. These managers encapsulate the GraphQL operations for their domain and provide asynchronous methods such as create, get_by_id, get_batch, and update_by_id.

Note

All manager methods are asynchronous. Ensure calls run inside an event loop (for example using asyncio.run).

Environment and Credential Resolution¶

The client resolves connection details automatically using a strict priority order:

Explicit parameters (env=, token=)
Environment variables (e.g., GPP_PRODUCTION_TOKEN, GPP_DEVELOPMENT_TOKEN)
Local configuration file (~/.config/gpp-client/config.toml)
The default environment (PRODUCTION)

This ensures you can write:

client = GPPClient()

and the client will automatically select the active environment and token.

Note

For advanced credential setup—including disabling environment variable resolution, configuring per-environment tokens, and managing the active environment—see Configuration.

Available Managers¶

The following managers are available as attributes on the client:

Note

SiteStatusManager does not use the GraphQL client and is initialized without a network connection.

Creating a Client¶

By default, credentials and the active environment come from environment variables or the local configuration file:

from gpp_client import GPPClient

client = GPPClient()

Specify an environment explicitly:

client = GPPClient(env="DEVELOPMENT")

or with the enum:

from gpp_client.config import GPPEnvironment
client = GPPClient(env=GPPEnvironment.STAGING)

Pass an explicit token:

client = GPPClient(
    env="DEVELOPMENT",
    token="my-token"
)

Storing Credentials¶

Use set_credentials() to store tokens locally:

from gpp_client import GPPClient
from gpp_client.config import GPPEnvironment

GPPClient.set_credentials(
    env=GPPEnvironment.DEVELOPMENT,
    token="my-dev-token",
    activate=True,
)

or by passing in the GPPConfig instance when creating the client:

from gpp_client import GPPClient
from gpp_client.config import GPPConfig, GPPEnvironment

config = GPPConfig()
config.set_credentials(
    env=GPPEnvironment.DEVELOPMENT,
    token="my-dev-token",
    activate=True,
)
config.save_to_file()

client = GPPClient(config=config)

Note

For advanced credential setup—including disabling environment variable resolution, configuring per-environment tokens, and managing the active environment—see Configuration.

Checking Connectivity¶

Use is_reachable() to verify the endpoint and token:

ok, error = await client.is_reachable()
if ok:
    print("Connected.")
else:
    print("Failed:", error)

API Reference¶

class gpp_client.GPPClient(*, env: GPPEnvironment | str | None = None, token: str | None = None, config: GPPConfig | None = None, _debug: bool = True)[source]¶

Bases: object

Main entry point for interacting with the GPP GraphQL API.

This client provides access to all supported resource managers, including programs, targets, observations, and more. It handles authentication, configuration, and connection setup automatically.

Parameters:

env (GPPEnvironment | str, optional) – The GPP environment to connect to (e.g., DEVELOPMENT, STAGING, PRODUCTION). If not provided, it will be loaded from the local configuration file or defaults to PRODUCTION.
token (str, optional) – The bearer token used for authentication. If not provided, it will be loaded from the GPP_TOKEN environment variable or the local configuration file.
config (GPPConfig, optional) – An optional GPPConfig instance to use for configuration management. If not provided, a new instance will be created and loaded from the default path.
_debug (bool, default=True) – If True, enables debug-level console logging for development purposes.

config¶

Interface to read and write local GPP configuration settings.

Type:: GPPConfig

program_note¶

Manager for program notes (e.g., create, update, list).

Type:: ProgramNoteManager

target¶

Manager for targets in proposals or observations.

Type:: TargetManager

program¶

Manager for proposals and observing programs.

Type:: ProgramManager

call_for_proposals¶

Manager for open Calls for Proposals (CFPs).

Type:: CallForProposalsManager

observation¶

Manager for observations submitted under proposals.

Type:: ObservationManager

site_status¶

Manager for current status of Gemini North and South.

Type:: SiteStatusManager

group¶

Manager for groups.

Type:: GroupManager

configuration_request¶

Manager for configuration requests.

Type:: ConfigurationRequestManager

workflow_state¶

Manager for observation workflow states.

Type:: WorkflowStateManager

attachment¶

Manager for attachments associated with proposals and observations.

Type:: AttachmentManager

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

async is_reachable() → 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.

static set_credentials(env: GPPEnvironment | str, token: str, activate: bool = False, save: bool = True) → None[source]¶

Helper to set the token for a given environment and optionally activate it. This gets around having to create a GPPConfig instance manually.

Parameters:

env (GPPEnvironment | str) – The environment to store the token for.
token (str) – The bearer token.
activate (bool, optional) – Whether to set the given environment as active. Default is False.
save (bool, optional) – Whether to save the configuration to disk immediately. Default is True.