# gitpod-io/gitpod-sdk-python architecture

> Architecture diagram of the GitHub repository gitpod-io/gitpod-sdk-python, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gitpod-io/gitpod-sdk-python
- Repository: https://github.com/gitpod-io/gitpod-sdk-python

## Overview

Gitpod Python API library is a typed synchronous/asynchronous client for the Gitpod REST API. A caller creates a client, invokes a resource operation, and receives a parsed response; list operations can paginate automatically. The graph preserves major API domains visible in the tree, plus the shared request, response, and pagination layers. Resource implementations beyond the sampled host-token module are not inspected, so their detailed internal call relationships are omitted; documented client usage and sampled request behavior ground the main workflow.

Main entry points: [`src/gitpod/_base_client.py`](https://github.com/gitpod-io/gitpod-sdk-python/blob/main/src/gitpod/_base_client.py) (Request engine), [`src/gitpod/_client.py`](https://github.com/gitpod-io/gitpod-sdk-python/blob/main/src/gitpod/_client.py) (Sync and async clients), [`src/gitpod/_models.py`](https://github.com/gitpod-io/gitpod-sdk-python/blob/main/src/gitpod/_models.py) (Typed API models), [`src/gitpod/resources/runners/configurations/host_authentication_tokens.py`](https://github.com/gitpod-io/gitpod-sdk-python/blob/main/src/gitpod/resources/runners/configurations/host_authentication_tokens.py) (Runners and auth)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client and requests"]
  node_sdk["Sync and async clients<br/>[_client.py]"]
  node_request["Request engine<br/>[_base_client.py]"]
  node_resourcebase["Resource base<br/>[_resource.py]"]
  node_query["Query encoding<br/>[_qs.py]"]
  node_files["File uploads<br/>[_files.py]"]
  node_response["Response handling<br/>[_response.py]"]
  node_streams["Streaming<br/>[_streaming.py]"]
  node_errors["Errors and retries<br/>[_exceptions.py]"]
end

subgraph group_domain["API resources"]
  node_identity["Identity<br/>[identity.py]"]
  node_environments["Environments<br/>[environments.py]"]
  node_projects["Projects<br/>[projects.py]"]
  node_automation["Automations<br/>[automations.py]"]
  node_organizations["Organizations<br/>[organizations.py]"]
  node_groups["Groups<br/>[groups.py]"]
  node_runners["Runners and auth"]
  node_billing["Billing and usage<br/>[billing.py]"]
end

subgraph group_models["Types and responses"]
  node_models["Typed API models<br/>[_models.py]"]
  node_types["Request and response types"]
  node_hosttoken["Host token types"]
end

subgraph group_paging["Pagination"]
  node_pagination["Page iterators<br/>[pagination.py]"]
end

node_caller(("Python application"))
node_api{{"Gitpod REST API"}}

node_caller -->|"creates and calls"| node_sdk
node_sdk -->|"exposes operation"| node_identity
node_sdk -.->|"uses requests"| node_request
node_identity -.->|"calls REST API"| node_api
node_environments -.->|"calls REST API"| node_api
node_projects -.->|"calls REST API"| node_api
node_automation -.->|"calls REST API"| node_api
node_organizations -.->|"calls REST API"| node_api
node_groups -.->|"calls REST API"| node_api
node_runners -->|"posts operations"| node_api
node_billing -.->|"calls REST API"| node_api
node_request -->|"parses response"| node_response
node_request -.->|"raises API errors"| node_errors
node_request -->|"handles streams"| node_streams
node_request -.->|"encodes query"| node_query
node_request -.->|"sends uploads"| node_files
node_response -.->|"parses into models"| node_models
node_models -.->|"uses generated types"| node_types
node_hosttoken -->|"extends base model"| node_models
node_runners -->|"returns paged results"| node_pagination
node_pagination -.->|"fetches next pages"| node_request

click node_sdk "https://github.com/gitpod-io/gitpod-sdk-python/blob/main/src/gitpod/_client.py"
click node_request "https://github.com/gitpod-io/gitpod-sdk-python/blob/main/src/gitpod/_base_client.py"
click node_resourcebase "https://github.com/gitpod-io/gitpod-sdk-python/blob/main/src/gitpod/_resource.py"
click node_query "https://github.com/gitpod-io/gitpod-sdk-python/blob/main/src/gitpod/_qs.py"
click node_files "https://github.com/gitpod-io/gitpod-sdk-python/blob/main/src/gitpod/_files.py"
click node_response "https://github.com/gitpod-io/gitpod-sdk-python/blob/main/src/gitpod/_response.py"
click node_streams "https://github.com/gitpod-io/gitpod-sdk-python/blob/main/src/gitpod/_streaming.py"
click node_errors "https://github.com/gitpod-io/gitpod-sdk-python/blob/main/src/gitpod/_exceptions.py"
click node_identity "https://github.com/gitpod-io/gitpod-sdk-python/blob/main/src/gitpod/resources/identity.py"
click node_environments "https://github.com/gitpod-io/gitpod-sdk-python/blob/main/src/gitpod/resources/environments/environments.py"
click node_projects "https://github.com/gitpod-io/gitpod-sdk-python/blob/main/src/gitpod/resources/projects/projects.py"
click node_automation "https://github.com/gitpod-io/gitpod-sdk-python/blob/main/src/gitpod/resources/automations.py"
click node_organizations "https://github.com/gitpod-io/gitpod-sdk-python/blob/main/src/gitpod/resources/organizations/organizations.py"
click node_groups "https://github.com/gitpod-io/gitpod-sdk-python/blob/main/src/gitpod/resources/groups/groups.py"
click node_runners "https://github.com/gitpod-io/gitpod-sdk-python/blob/main/src/gitpod/resources/runners/configurations/host_authentication_tokens.py"
click node_billing "https://github.com/gitpod-io/gitpod-sdk-python/blob/main/src/gitpod/resources/billing.py"
click node_models "https://github.com/gitpod-io/gitpod-sdk-python/blob/main/src/gitpod/_models.py"
click node_types "https://github.com/gitpod-io/gitpod-sdk-python/tree/main/src/gitpod/types"
click node_hosttoken "https://github.com/gitpod-io/gitpod-sdk-python/blob/main/src/gitpod/types/runners/configurations/host_authentication_token.py"
click node_pagination "https://github.com/gitpod-io/gitpod-sdk-python/blob/main/src/gitpod/pagination.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_sdk,node_request,node_resourcebase,node_query,node_files,node_response,node_streams,node_errors toneBlue
class node_identity,node_environments,node_projects,node_automation,node_organizations,node_groups,node_runners,node_billing toneAmber
class node_models,node_types,node_hosttoken,node_api toneMint
class node_pagination toneRose
class node_caller toneIndigo
```

## Components

### Client and requests

- [Sync and async clients](https://github.com/gitpod-io/gitpod-sdk-python/blob/main/src/gitpod/_client.py): `src/gitpod/_client.py`
- [Request engine](https://github.com/gitpod-io/gitpod-sdk-python/blob/main/src/gitpod/_base_client.py): `src/gitpod/_base_client.py`
- [Resource base](https://github.com/gitpod-io/gitpod-sdk-python/blob/main/src/gitpod/_resource.py): `src/gitpod/_resource.py`
- [Query encoding](https://github.com/gitpod-io/gitpod-sdk-python/blob/main/src/gitpod/_qs.py): `src/gitpod/_qs.py`
- [File uploads](https://github.com/gitpod-io/gitpod-sdk-python/blob/main/src/gitpod/_files.py): `src/gitpod/_files.py`
- [Response handling](https://github.com/gitpod-io/gitpod-sdk-python/blob/main/src/gitpod/_response.py): `src/gitpod/_response.py`
- [Streaming](https://github.com/gitpod-io/gitpod-sdk-python/blob/main/src/gitpod/_streaming.py): `src/gitpod/_streaming.py`
- [Errors and retries](https://github.com/gitpod-io/gitpod-sdk-python/blob/main/src/gitpod/_exceptions.py): `src/gitpod/_exceptions.py`

### API resources

- [Identity](https://github.com/gitpod-io/gitpod-sdk-python/blob/main/src/gitpod/resources/identity.py): `src/gitpod/resources/identity.py`
- [Environments](https://github.com/gitpod-io/gitpod-sdk-python/blob/main/src/gitpod/resources/environments/environments.py): `src/gitpod/resources/environments/environments.py`
- [Projects](https://github.com/gitpod-io/gitpod-sdk-python/blob/main/src/gitpod/resources/projects/projects.py): `src/gitpod/resources/projects/projects.py`
- [Automations](https://github.com/gitpod-io/gitpod-sdk-python/blob/main/src/gitpod/resources/automations.py): `src/gitpod/resources/automations.py`
- [Organizations](https://github.com/gitpod-io/gitpod-sdk-python/blob/main/src/gitpod/resources/organizations/organizations.py): `src/gitpod/resources/organizations/organizations.py`
- [Groups](https://github.com/gitpod-io/gitpod-sdk-python/blob/main/src/gitpod/resources/groups/groups.py): `src/gitpod/resources/groups/groups.py`
- [Runners and auth](https://github.com/gitpod-io/gitpod-sdk-python/blob/main/src/gitpod/resources/runners/configurations/host_authentication_tokens.py): `src/gitpod/resources/runners/configurations/host_authentication_tokens.py`
- [Billing and usage](https://github.com/gitpod-io/gitpod-sdk-python/blob/main/src/gitpod/resources/billing.py): `src/gitpod/resources/billing.py`

### Types and responses

- [Typed API models](https://github.com/gitpod-io/gitpod-sdk-python/blob/main/src/gitpod/_models.py): `src/gitpod/_models.py`
- [Request and response types](https://github.com/gitpod-io/gitpod-sdk-python/tree/main/src/gitpod/types): `src/gitpod/types`
- [Host token types](https://github.com/gitpod-io/gitpod-sdk-python/blob/main/src/gitpod/types/runners/configurations/host_authentication_token.py): `src/gitpod/types/runners/configurations/host_authentication_token.py`

### Pagination

- [Page iterators](https://github.com/gitpod-io/gitpod-sdk-python/blob/main/src/gitpod/pagination.py): `src/gitpod/pagination.py`

### Other components

- **Python application**
- **Gitpod REST API**

## Connections

- Python application → Sync and async clients: creates and calls (evidence: `README.md`)
- Sync and async clients → Identity: exposes operation (evidence: `README.md`)
- Sync and async clients → Request engine: uses requests
- Identity → Gitpod REST API: calls REST API
- Environments → Gitpod REST API: calls REST API
- Projects → Gitpod REST API: calls REST API
- Automations → Gitpod REST API: calls REST API
- Organizations → Gitpod REST API: calls REST API
- Groups → Gitpod REST API: calls REST API
- Runners and auth → Gitpod REST API: posts operations (evidence: `src/gitpod/resources/runners/configurations/host_authentication_tokens.py`)
- Billing and usage → Gitpod REST API: calls REST API
- Request engine → Response handling: parses response (evidence: `src/gitpod/_base_client.py`)
- Request engine → Errors and retries: raises API errors (evidence: `src/gitpod/_base_client.py`)
- Request engine → Streaming: handles streams (evidence: `src/gitpod/_base_client.py`)
- Request engine → Query encoding: encodes query (evidence: `src/gitpod/_base_client.py`)
- Request engine → File uploads: sends uploads (evidence: `src/gitpod/_base_client.py`)
- Response handling → Typed API models: parses into models
- Typed API models → Request and response types: uses generated types (evidence: `src/gitpod/types/environments/automations/service_retrieve_response.py`)
- Host token types → Typed API models: extends base model (evidence: `src/gitpod/types/runners/configurations/host_authentication_token_retrieve_response.py`)
- Runners and auth → Page iterators: returns paged results (evidence: `src/gitpod/resources/runners/configurations/host_authentication_tokens.py`)
- Page iterators → Request engine: fetches next pages