# googleapis/google-api-python-client architecture

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

- Interactive diagram: https://gitdiagram.com/googleapis/google-api-python-client
- Repository: https://github.com/googleapis/google-api-python-client

## Overview

Google API Python Client builds dynamic Python clients for Google’s discovery-based APIs. A developer supplies an API name/version and options to `discovery.build()`; the library obtains the discovery document, configures authentication and a request model, and returns callable service resources whose requests are executed over HTTP. HTTP support includes media transfer and batching, while channel support handles push notifications. The graph also includes discovery caching and the documented API-description utility. Source excerpts are partial; unsampled capability links are omitted or marked unverified.

Main entry points: [`googleapiclient/discovery.py`](https://github.com/googleapis/google-api-python-client/blob/main/googleapiclient/discovery.py) (Discovery builder), [`googleapiclient/http.py`](https://github.com/googleapis/google-api-python-client/blob/main/googleapiclient/http.py) (HTTP requests), [`apiclient/__init__.py`](https://github.com/googleapis/google-api-python-client/blob/main/apiclient/__init__.py) (Legacy import alias), [`googleapiclient/model.py`](https://github.com/googleapis/google-api-python-client/blob/main/googleapiclient/model.py) (Request models)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client construction"]
  node_discovery["Discovery builder<br/>[discovery.py]"]
  node_service["API service resources<br/>[discovery.py]"]
  node_auth["Authentication<br/>[_auth.py]"]
  node_cache_select["Cache selection<br/>[__init__.py]"]
  node_cache_base["Cache interface<br/>[base.py]"]
  node_file_cache[("File cache<br/>[file_cache.py]")]
  node_memcache[("App Engine cache")]
end

subgraph group_transport["Requests and transport"]
  node_http["HTTP requests<br/>[http.py]"]
  node_media["Media transfer<br/>[http.py]"]
  node_batch["Batch requests<br/>[http.py]"]
  node_channel["Push channels<br/>[channel.py]"]
end

subgraph group_support["Shared support"]
  node_model["Request models<br/>[model.py]"]
  node_mimeparse["MIME parsing<br/>[mimeparse.py]"]
  node_schema["Schema helpers<br/>[schema.py]"]
  node_errors["Error types<br/>[errors.py]"]
  node_helpers["Runtime helpers<br/>[_helpers.py]"]
  node_version["Version metadata<br/>[version.py]"]
end

subgraph group_auxiliary["Related utilities"]
  node_sample_tools["Sample utilities<br/>[sample_tools.py]"]
  node_describe["API description<br/>[describe.py]"]
  node_legacy_alias["Legacy import alias<br/>[__init__.py]"]
end

node_developer(("Developer"))
node_api{{"Google API"}}

node_developer -->|"builds client"| node_discovery
node_discovery -->|"loads documents"| node_cache_select
node_cache_select -->|"selects cache"| node_file_cache
node_cache_select -->|"selects cache"| node_memcache
node_file_cache -->|"implements"| node_cache_base
node_memcache -->|"implements"| node_cache_base
node_cache_select -->|"reads documents"| node_file_cache
node_discovery -->|"configures credentials"| node_auth
node_discovery -->|"selects model"| node_model
node_discovery -->|"uses parsing"| node_mimeparse
node_discovery -->|"uses schemas"| node_schema
node_discovery -->|"creates resources"| node_service
node_service -.->|"builds requests"| node_http
node_http -.->|"sends requests"| node_api
node_http -->|"applies credentials"| node_auth
node_http -->|"serializes payloads"| node_model
node_http -->|"raises errors"| node_errors
node_media -.->|"uses transport"| node_http
node_batch -.->|"uses transport"| node_http
node_channel -->|"uses helpers"| node_helpers
node_channel -->|"raises errors"| node_errors
node_model -->|"raises errors"| node_errors
node_model -->|"uses metadata"| node_version
node_schema -->|"uses helpers"| node_helpers
node_sample_tools -->|"builds services"| node_discovery
node_sample_tools -->|"uses transport"| node_http
node_describe -->|"builds service"| node_discovery
node_describe -->|"fetches documents"| node_http
node_legacy_alias -->|"aliases imports"| node_discovery
node_legacy_alias -->|"aliases imports"| node_channel
node_legacy_alias -->|"aliases imports"| node_http
node_legacy_alias -->|"aliases imports"| node_model
node_legacy_alias -->|"aliases imports"| node_schema
node_legacy_alias -->|"aliases imports"| node_mimeparse

click node_discovery "https://github.com/googleapis/google-api-python-client/blob/main/googleapiclient/discovery.py"
click node_service "https://github.com/googleapis/google-api-python-client/blob/main/googleapiclient/discovery.py"
click node_auth "https://github.com/googleapis/google-api-python-client/blob/main/googleapiclient/_auth.py"
click node_cache_select "https://github.com/googleapis/google-api-python-client/blob/main/googleapiclient/discovery_cache/__init__.py"
click node_cache_base "https://github.com/googleapis/google-api-python-client/blob/main/googleapiclient/discovery_cache/base.py"
click node_file_cache "https://github.com/googleapis/google-api-python-client/blob/main/googleapiclient/discovery_cache/file_cache.py"
click node_memcache "https://github.com/googleapis/google-api-python-client/blob/main/googleapiclient/discovery_cache/appengine_memcache.py"
click node_http "https://github.com/googleapis/google-api-python-client/blob/main/googleapiclient/http.py"
click node_media "https://github.com/googleapis/google-api-python-client/blob/main/googleapiclient/http.py"
click node_batch "https://github.com/googleapis/google-api-python-client/blob/main/googleapiclient/http.py"
click node_channel "https://github.com/googleapis/google-api-python-client/blob/main/googleapiclient/channel.py"
click node_model "https://github.com/googleapis/google-api-python-client/blob/main/googleapiclient/model.py"
click node_mimeparse "https://github.com/googleapis/google-api-python-client/blob/main/googleapiclient/mimeparse.py"
click node_schema "https://github.com/googleapis/google-api-python-client/blob/main/googleapiclient/schema.py"
click node_errors "https://github.com/googleapis/google-api-python-client/blob/main/googleapiclient/errors.py"
click node_helpers "https://github.com/googleapis/google-api-python-client/blob/main/googleapiclient/_helpers.py"
click node_version "https://github.com/googleapis/google-api-python-client/blob/main/googleapiclient/version.py"
click node_sample_tools "https://github.com/googleapis/google-api-python-client/blob/main/googleapiclient/sample_tools.py"
click node_describe "https://github.com/googleapis/google-api-python-client/blob/main/describe.py"
click node_legacy_alias "https://github.com/googleapis/google-api-python-client/blob/main/apiclient/__init__.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_discovery,node_service,node_auth,node_cache_select,node_cache_base,node_file_cache,node_memcache toneBlue
class node_http,node_media,node_batch,node_channel toneAmber
class node_model,node_mimeparse,node_schema,node_errors,node_helpers,node_version,node_api toneMint
class node_sample_tools,node_describe,node_legacy_alias toneRose
class node_developer toneIndigo
```

## Components

### Client construction

- [Discovery builder](https://github.com/googleapis/google-api-python-client/blob/main/googleapiclient/discovery.py): `googleapiclient/discovery.py`
- [API service resources](https://github.com/googleapis/google-api-python-client/blob/main/googleapiclient/discovery.py): `googleapiclient/discovery.py`
- [Authentication](https://github.com/googleapis/google-api-python-client/blob/main/googleapiclient/_auth.py): `googleapiclient/_auth.py`
- [Cache selection](https://github.com/googleapis/google-api-python-client/blob/main/googleapiclient/discovery_cache/__init__.py): `googleapiclient/discovery_cache/__init__.py`
- [Cache interface](https://github.com/googleapis/google-api-python-client/blob/main/googleapiclient/discovery_cache/base.py): `googleapiclient/discovery_cache/base.py`
- [File cache](https://github.com/googleapis/google-api-python-client/blob/main/googleapiclient/discovery_cache/file_cache.py): `googleapiclient/discovery_cache/file_cache.py`
- [App Engine cache](https://github.com/googleapis/google-api-python-client/blob/main/googleapiclient/discovery_cache/appengine_memcache.py): `googleapiclient/discovery_cache/appengine_memcache.py`

### Requests and transport

- [HTTP requests](https://github.com/googleapis/google-api-python-client/blob/main/googleapiclient/http.py): `googleapiclient/http.py`
- [Media transfer](https://github.com/googleapis/google-api-python-client/blob/main/googleapiclient/http.py): `googleapiclient/http.py`
- [Batch requests](https://github.com/googleapis/google-api-python-client/blob/main/googleapiclient/http.py): `googleapiclient/http.py`
- [Push channels](https://github.com/googleapis/google-api-python-client/blob/main/googleapiclient/channel.py): `googleapiclient/channel.py`

### Shared support

- [Request models](https://github.com/googleapis/google-api-python-client/blob/main/googleapiclient/model.py): `googleapiclient/model.py`
- [MIME parsing](https://github.com/googleapis/google-api-python-client/blob/main/googleapiclient/mimeparse.py): `googleapiclient/mimeparse.py`
- [Schema helpers](https://github.com/googleapis/google-api-python-client/blob/main/googleapiclient/schema.py): `googleapiclient/schema.py`
- [Error types](https://github.com/googleapis/google-api-python-client/blob/main/googleapiclient/errors.py): `googleapiclient/errors.py`
- [Runtime helpers](https://github.com/googleapis/google-api-python-client/blob/main/googleapiclient/_helpers.py): `googleapiclient/_helpers.py`
- [Version metadata](https://github.com/googleapis/google-api-python-client/blob/main/googleapiclient/version.py): `googleapiclient/version.py`

### Related utilities

- [Sample utilities](https://github.com/googleapis/google-api-python-client/blob/main/googleapiclient/sample_tools.py): `googleapiclient/sample_tools.py`
- [API description](https://github.com/googleapis/google-api-python-client/blob/main/describe.py): `describe.py`
- [Legacy import alias](https://github.com/googleapis/google-api-python-client/blob/main/apiclient/__init__.py): `apiclient/__init__.py`

### Other components

- **Developer**
- **Google API**

## Connections

- Developer → Discovery builder: builds client (evidence: `README.md`)
- Discovery builder → Cache selection: loads documents (evidence: `googleapiclient/discovery.py`)
- Cache selection → File cache: selects cache (evidence: `googleapiclient/discovery_cache/__init__.py`)
- Cache selection → App Engine cache: selects cache (evidence: `googleapiclient/discovery_cache/__init__.py`)
- File cache → Cache interface: implements (evidence: `googleapiclient/discovery_cache/file_cache.py`)
- App Engine cache → Cache interface: implements (evidence: `googleapiclient/discovery_cache/appengine_memcache.py`)
- Cache selection → File cache: reads documents (evidence: `googleapiclient/discovery_cache/__init__.py`)
- Discovery builder → Authentication: configures credentials (evidence: `googleapiclient/discovery.py`)
- Discovery builder → Request models: selects model (evidence: `googleapiclient/discovery.py`)
- Discovery builder → MIME parsing: uses parsing (evidence: `googleapiclient/discovery.py`)
- Discovery builder → Schema helpers: uses schemas (evidence: `googleapiclient/discovery.py`)
- Discovery builder → API service resources: creates resources (evidence: `googleapiclient/discovery.py`)
- API service resources → HTTP requests: builds requests (evidence: `googleapiclient/discovery.py`)
- HTTP requests → Google API: sends requests
- HTTP requests → Authentication: applies credentials (evidence: `googleapiclient/http.py`)
- HTTP requests → Request models: serializes payloads (evidence: `googleapiclient/http.py`)
- HTTP requests → Error types: raises errors (evidence: `googleapiclient/http.py`)
- Media transfer → HTTP requests: uses transport (evidence: `googleapiclient/http.py`)
- Batch requests → HTTP requests: uses transport (evidence: `googleapiclient/http.py`)
- Push channels → Runtime helpers: uses helpers (evidence: `googleapiclient/channel.py`)
- Push channels → Error types: raises errors (evidence: `googleapiclient/channel.py`)
- Request models → Error types: raises errors (evidence: `googleapiclient/model.py`)
- Request models → Version metadata: uses metadata (evidence: `googleapiclient/model.py`)
- Schema helpers → Runtime helpers: uses helpers (evidence: `googleapiclient/schema.py`)
- Sample utilities → Discovery builder: builds services (evidence: `googleapiclient/sample_tools.py`)
- Sample utilities → HTTP requests: uses transport (evidence: `googleapiclient/sample_tools.py`)
- API description → Discovery builder: builds service (evidence: `describe.py`)
- API description → HTTP requests: fetches documents (evidence: `describe.py`)
- Legacy import alias → Discovery builder: aliases imports (evidence: `apiclient/__init__.py`)
- Legacy import alias → Push channels: aliases imports (evidence: `apiclient/__init__.py`)
- Legacy import alias → HTTP requests: aliases imports (evidence: `apiclient/__init__.py`)
- Legacy import alias → Request models: aliases imports (evidence: `apiclient/__init__.py`)
- Legacy import alias → Schema helpers: aliases imports (evidence: `apiclient/__init__.py`)
- Legacy import alias → MIME parsing: aliases imports (evidence: `apiclient/__init__.py`)
