0
# Google API Core
1

2
A comprehensive Python library providing common helpers, utilities, and components used by all Google API client libraries. It serves as the foundational layer for Google's Python client libraries, offering shared functionality for authentication, retry logic, operations management, exception handling, and API communication patterns.
3

4
## Package Information
5

6
- **Package Name**: google-api-core
7
- **Language**: Python
8
- **Installation**: `pip install google-api-core`
9

10
## Core Imports
11

12
```python
13
import google.api_core
14
```
15

16
Common import patterns for specific functionality:
17

18
```python
19
from google.api_core import exceptions
20
from google.api_core import retry
21
from google.api_core import timeout
22
from google.api_core import operation
23
from google.api_core import client_options
24
```
25

26
## Basic Usage
27

28
```python
29
from google.api_core import retry
30
from google.api_core import exceptions
31
from google.api_core import timeout
32
import requests
33

34
# Configure retry behavior with exponential backoff
35
retry_config = retry.Retry(
36
    initial=1.0,
37
    maximum=60.0,
38
    multiplier=2.0,
39
    predicate=retry.if_exception_type(
40
        exceptions.InternalServerError,
41
        exceptions.ServiceUnavailable
42
    )
43
)
44

45
# Apply retry decorator to a function
46
@retry_config
47
def make_api_call():
48
    response = requests.get("https://api.example.com/data")
49
    if response.status_code >= 500:
50
        raise exceptions.InternalServerError("Server error")
51
    return response.json()
52

53
# Use timeout decorators
54
timeout_config = timeout.TimeToDeadlineTimeout(deadline=30.0)
55

56
@timeout_config
57
def timed_operation():
58
    # Operation that should complete within deadline
59
    return make_api_call()
60
```
61

62
## Architecture
63

64
Google API Core follows a modular design with distinct functional areas:
65

66
- **Exception Hierarchy**: Comprehensive error mapping between HTTP/gRPC status codes and Python exceptions
67
- **Retry Framework**: Configurable retry mechanisms with exponential backoff and custom predicates
68
- **Operation Management**: Long-running operation polling and management for both sync and async
69
- **Page Iteration**: Standardized pagination patterns for list operations
70
- **Protocol Buffer Helpers**: Utilities for working with Google's protobuf-based APIs
71
- **Transport Abstractions**: Common patterns for gRPC and REST API communication
72
- **Authentication Integration**: Seamless integration with Google Auth libraries
73

74
This architecture ensures consistency across all Google Cloud client libraries while providing maximum flexibility for different API patterns and use cases.
75

76
## Capabilities
77

78
### Exception Handling
79

80
Comprehensive exception hierarchy mapping HTTP and gRPC status codes to specific Python exceptions, with utilities for error conversion and handling across different transport protocols.
81

82
```python { .api }
83
class GoogleAPIError(Exception): ...
84
class GoogleAPICallError(GoogleAPIError): ...
85
class RetryError(GoogleAPIError): ...
86

87
# HTTP Status Exceptions
88
class ClientError(GoogleAPICallError): ...
89
class BadRequest(ClientError): ...
90
class Unauthorized(ClientError): ...
91
class Forbidden(ClientError): ...
92
class NotFound(ClientError): ...
93

94
class ServerError(GoogleAPICallError): ...
95
class InternalServerError(ServerError): ...
96
class ServiceUnavailable(ServerError): ...
97

98
def from_http_status(status_code, message, **kwargs): ...
99
def from_grpc_error(rpc_exc): ...
100
```
101

102
[Exception Handling](./exceptions.md)
103

104
### Retry Logic
105

106
Configurable retry mechanisms with exponential backoff, custom predicates, and support for both synchronous and asynchronous operations including streaming.
107

108
```python { .api }
109
class Retry:
110
    def __init__(self, predicate=None, initial=1.0, maximum=60.0, multiplier=2.0, deadline=120.0): ...
111

112
class AsyncRetry:
113
    def __init__(self, predicate=None, initial=1.0, maximum=60.0, multiplier=2.0, deadline=120.0): ...
114

115
def retry_target(target, predicate, sleep_generator, deadline=None, on_error=None): ...
116
def if_exception_type(*exception_types): ...
117
def if_transient_error(exception): ...
118
```
119

120
[Retry Logic](./retry.md)
121

122
### Long-Running Operations
123

124
Management of Google API long-running operations with polling, cancellation, and both synchronous and asynchronous support.
125

126
```python { .api }
127
class Operation:
128
    def __init__(self, operation, refresh, cancel, result_type=None, metadata_type=None, retry=None): ...
129
    def done(self): ...
130
    def result(self, timeout=None): ...
131
    def cancel(self): ...
132

133
class AsyncOperation:
134
    def __init__(self, operation, refresh, cancel, result_type=None, metadata_type=None, retry=None): ...
135
    async def done(self): ...
136
    async def result(self, timeout=None): ...
137
    async def cancel(self): ...
138
```
139

140
[Operations](./operations.md)
141

142
### Page Iteration
143

144
Standardized pagination patterns for list operations with support for both HTTP/JSON and gRPC APIs, including async variants.
145

146
```python { .api }
147
class Iterator:
148
    def __init__(self, client, item_to_value, page_token=None, max_results=None): ...
149

150
class HTTPIterator(Iterator):
151
    def __init__(self, client, api_request, path, item_to_value, page_token=None, max_results=None): ...
152

153
class GRPCIterator(Iterator):
154
    def __init__(self, client, method, request, items_field, request_token_field="page_token"): ...
155

156
class AsyncIterator:
157
    def __init__(self, client, item_to_value, page_token=None, max_results=None): ...
158
```
159

160
[Page Iteration](./page-iteration.md)
161

162
### Protocol Buffer Utilities
163

164
Helper functions for working with Google's protocol buffer messages, including type conversion, field manipulation, and message introspection.
165

166
```python { .api }
167
def from_any_pb(pb_type, any_pb): ...
168
def check_oneof(**kwargs): ...
169
def get_messages(module): ...
170
def get(msg_or_dict, key, default=None): ...
171
def set(msg_or_dict, key, value): ...
172
def field_mask(original, modified): ...
173
```
174

175
[Protocol Buffer Helpers](./protobuf-helpers.md)
176

177
### Transport Helpers
178

179
Utilities for gRPC and REST transport protocols, including channel creation, method wrapping, and streaming support.
180

181
```python { .api }
182
def create_channel(target, credentials=None, scopes=None, ssl_credentials=None, **kwargs): ...
183
def wrap_method(func, default_retry=None, default_timeout=None, client_info=None): ...
184

185
class GrpcStream:
186
    def __init__(self, wrapped): ...
187
```
188

189
[Transport Helpers](./transport.md)
190

191
### Client Configuration
192

193
Configuration classes for customizing Google API client behavior, including authentication, endpoints, and transport options.
194

195
```python { .api }
196
class ClientOptions:
197
    def __init__(self, api_endpoint=None, client_cert_source=None, client_encrypted_cert_source=None, **kwargs): ...
198

199
class ClientInfo:
200
    def __init__(self, client_library_name=None, client_library_version=None, **kwargs): ...
201

202
def from_dict(options): ...
203
```
204

205
[Client Configuration](./client-config.md)
206

207
### Date/Time Utilities
208

209
Utilities for handling datetime objects in Google APIs, including RFC3339 formatting, timezone handling, and high-precision timestamps.
210

211
```python { .api }
212
class DatetimeWithNanoseconds(datetime.datetime):
213
    def __new__(cls, year, month, day, hour=0, minute=0, second=0, microsecond=0, nanosecond=0, **kwargs): ...
214

215
def utcnow(): ...
216
def from_rfc3339(value): ...
217
def to_rfc3339(value, ignore_zone=True): ...
218
def from_microseconds(value): ...
219
def to_microseconds(value): ...
220
```
221

222
[Date/Time Utilities](./datetime.md)
223

224
### Path Templates
225

226
URI template expansion and validation for Google API resource paths, supporting variable substitution and path parameter extraction.
227

228
```python { .api }
229
def expand(tmpl, *args, **kwargs): ...
230
def validate(tmpl, path): ...
231
def get_field(request, field): ...
232
def delete_field(request, field): ...
233
def transcode(http_options, message=None, **request_kwargs): ...
234
```
235

236
[Path Templates](./path-templates.md)
237

238
### Timeout Management
239

240
Timeout decorators and utilities for managing operation deadlines with various timeout strategies.
241

242
```python { .api }
243
class TimeToDeadlineTimeout:
244
    def __init__(self, deadline): ...
245

246
class ConstantTimeout:
247
    def __init__(self, timeout): ...
248

249
class ExponentialTimeout:
250
    def __init__(self, initial_timeout, max_timeout, multiplier): ...
251
```
252

253
[Timeout Management](./timeout.md)
254

255
### Bidirectional Streaming
256

257
Support for bidirectional streaming gRPC operations with queue-based request generation, background consumers, and resumable streams.
258

259
```python { .api }
260
class BidiRpc:
261
    def __init__(self, start_rpc, should_recover=None): ...
262

263
class ResumableBidiRpc(BidiRpc):
264
    def __init__(self, start_rpc, should_recover=None, should_terminate=None, throttle_reopen=None): ...
265

266
class BackgroundConsumer:
267
    def __init__(self, rpc, should_recover=None): ...
268
```
269

270
[Bidirectional Streaming](./bidirectional-streaming.md)
271

272
### IAM Policy Management
273

274
Non-API-specific IAM policy definitions for managing roles, permissions, and conditional bindings across Google Cloud resources.
275

276
```python { .api }
277
class Policy:
278
    def __init__(self, bindings=None, etag=None, version=None): ...
279

280
class InvalidOperationException(ValueError): ...
281

282
# Policy binding format
283
def from_api_repr(resource): ...
284
def to_api_repr(policy): ...
285
```
286

287
[IAM Policy Management](./iam-policies.md)
288

289
### GAPIC Framework
290

291
Generated API client (GAPIC) infrastructure providing method wrapping, configuration parsing, and routing header generation for Google API clients.
292

293
```python { .api }
294
def wrap_method(func, default_retry=None, default_timeout=None, client_info=None): ...
295
def wrap_async_method(func, default_retry=None, default_timeout=None, client_info=None): ...
296

297
def parse_method_configs(interface_config, client_config=None): ...
298
def to_routing_header(params): ...
299
def to_grpc_metadata(routing_header): ...
300
```
301

302
[GAPIC Framework](./gapic-framework.md)
303

304
### Universe Domain Support
305

306
Universe domain configuration and validation for multi-environment Google Cloud deployments supporting custom endpoints and domain validation.
307

308
```python { .api }
309
DEFAULT_UNIVERSE = "googleapis.com"
310

311
class EmptyUniverseError(ValueError): ...
312
class UniverseMismatchError(ValueError): ...
313

314
def determine_domain(client_universe_domain, universe_domain_env): ...
315
def get_universe_domain(client_universe_domain=None, universe_domain_env=None): ...
316
```
317

318
[Universe Domain Support](./universe-domain.md)
319

320
## Types
321

322
```python { .api }
323
# Core type aliases
324
import typing
325
from typing import Any, Callable, Dict, List, Optional, Union
326

327
# Common type definitions used across modules
328
Predicate = Callable[[Exception], bool]
329
SleepGenerator = typing.Generator[float, None, None]
330
```