0
# Google APIs Common Protos
1

2
Common protocol buffer definitions used across Google APIs and client libraries. This package provides Python-generated protobuf classes for core Google API concepts including authentication, billing, logging, monitoring, quotas, and resource management, serving as foundational types for the Google Cloud ecosystem.
3

4
## Package Information
5

6
- **Package Name**: googleapis-common-protos
7
- **Language**: Python
8
- **Installation**: `pip install googleapis-common-protos`
9
- **Optional gRPC Support**: `pip install googleapis-common-protos[grpc]`
10

11
## Core Imports
12

13
```python
14
# Import specific message types
15
from google.api import field_behavior_pb2
16
from google.api import resource_pb2
17
from google.rpc import status_pb2
18
from google.type import money_pb2
19
```
20

21
Module-specific imports:
22
```python
23
# API framework types
24
from google.api.field_behavior_pb2 import FieldBehavior
25
from google.api.resource_pb2 import ResourceDescriptor, ResourceReference
26

27
# RPC status and error handling
28
from google.rpc.status_pb2 import Status
29
from google.rpc.code_pb2 import Code
30
from google.rpc.error_details_pb2 import ErrorInfo, RetryInfo
31

32
# Common data types
33
from google.type.money_pb2 import Money
34
from google.type.date_pb2 import Date
35
from google.type.latlng_pb2 import LatLng
36

37
# Long-running operations
38
from google.longrunning.operations_proto_pb2 import Operation, GetOperationRequest
39

40
# Logging types
41
from google.logging.type.log_severity_pb2 import LogSeverity
42
from google.logging.type.http_request_pb2 import HttpRequest
43

44
# API maturity levels
45
from google.api.launch_stage_pb2 import LaunchStage
46
```
47

48
## Basic Usage
49

50
```python
51
from google.api.field_behavior_pb2 import FieldBehavior
52
from google.rpc.status_pb2 import Status
53
from google.rpc.code_pb2 import Code
54
from google.type.money_pb2 import Money
55

56
# Working with field behavior annotations
57
field_behavior = FieldBehavior.REQUIRED
58

59
# Creating status messages for error handling
60
status = Status()
61
status.code = Code.INVALID_ARGUMENT
62
status.message = "Required field is missing"
63

64
# Working with monetary values
65
price = Money()
66
price.currency_code = "USD"
67
price.units = 29
68
price.nanos = 990000000  # $29.99
69
```
70

71
## Architecture
72

73
The googleapis-common-protos package is organized into seven main namespaces:
74

75
- **google.api**: API framework definitions for service configuration, authentication, resource management, and client generation
76
- **google.rpc**: RPC framework types for status codes, error details, and request context  
77
- **google.type**: Common data types for temporal, geographic, financial, and contact information
78
- **google.longrunning**: Support for asynchronous long-running operations
79
- **google.cloud**: Cloud-specific extensions for location services and operations
80
- **google.gapic**: Client generation metadata for automatic library creation
81
- **google.logging**: Logging-specific types for structured log entries and severity levels
82

83
All message classes inherit from `google.protobuf.message.Message` and provide full type safety through comprehensive `.pyi` type stub files. The package serves as the foundational layer for the entire Google Cloud client library ecosystem.
84

85
## Capabilities
86

87
### API Framework Types
88

89
Core infrastructure for Google API definition including field behaviors, resource patterns, authentication, HTTP mapping, and client library configuration. These types enable consistent API design and automatic client generation across Google services.
90

91
```python { .api }
92
# Field behavior annotations
93
class FieldBehavior(enum.Enum):
94
    FIELD_BEHAVIOR_UNSPECIFIED = 0
95
    OPTIONAL = 1
96
    REQUIRED = 2
97
    OUTPUT_ONLY = 3
98
    INPUT_ONLY = 4
99
    IMMUTABLE = 5
100
    UNORDERED_LIST = 6
101
    NON_EMPTY_DEFAULT = 7
102
    IDENTIFIER = 8
103

104
# Resource descriptors for API resources
105
class ResourceDescriptor(message.Message):
106
    type: str
107
    pattern: list[str]
108
    name_field: str
109
    history: ResourceDescriptor.History
110
    plural: str
111
    singular: str
112
    style: list[ResourceDescriptor.Style]
113

114
# HTTP rule mapping for gRPC services
115
class HttpRule(message.Message):
116
    selector: str
117
    get: str
118
    put: str
119
    post: str
120
    delete: str
121
    patch: str
122
    custom: CustomHttpPattern
123
    body: str
124
    response_body: str
125
    additional_bindings: list[HttpRule]
126

127
# API maturity levels
128
class LaunchStage(enum.Enum):
129
    LAUNCH_STAGE_UNSPECIFIED = 0
130
    UNIMPLEMENTED = 1
131
    PRELAUNCH = 2
132
    EARLY_ACCESS = 3
133
    ALPHA = 4
134
    BETA = 5
135
    GA = 6
136
    DEPRECATED = 7
137
```
138

139
[API Framework Types](./api-framework.md)
140

141
### RPC Status and Error Handling
142

143
Standard RPC status codes, error details, and context information for robust error handling across Google services. Provides structured error reporting with detailed failure information.
144

145
```python { .api }
146
# RPC status representation
147
class Status(message.Message):
148
    code: int
149
    message: str
150
    details: list[Any]
151

152
# Standard gRPC status codes
153
class Code(enum.Enum):
154
    OK = 0
155
    CANCELLED = 1
156
    UNKNOWN = 2
157
    INVALID_ARGUMENT = 3
158
    DEADLINE_EXCEEDED = 4
159
    NOT_FOUND = 5
160
    ALREADY_EXISTS = 6
161
    PERMISSION_DENIED = 7
162
    UNAUTHENTICATED = 16
163
    RESOURCE_EXHAUSTED = 8
164
    FAILED_PRECONDITION = 9
165
    ABORTED = 10
166
    OUT_OF_RANGE = 11
167
    UNIMPLEMENTED = 12
168
    INTERNAL = 13
169
    UNAVAILABLE = 14
170
    DATA_LOSS = 15
171

172
# Detailed error information
173
class ErrorInfo(message.Message):
174
    reason: str
175
    domain: str
176
    metadata: dict[str, str]
177

178
class RetryInfo(message.Message):
179
    retry_delay: Duration
180
```
181

182
[RPC Status and Error Handling](./rpc-status.md)
183

184
### Common Data Types
185

186
Fundamental data types for temporal, geographic, financial, and contact information used across Google APIs. Includes types for dates, money, coordinates, phone numbers, and postal addresses.
187

188
```python { .api }
189
# Monetary amounts with currency
190
class Money(message.Message):
191
    currency_code: str
192
    units: int
193
    nanos: int
194

195
# Calendar dates
196
class Date(message.Message):
197
    year: int
198
    month: int
199
    day: int
200

201
# Geographic coordinates
202
class LatLng(message.Message):
203
    latitude: float
204
    longitude: float
205

206
# Phone number representation
207
class PhoneNumber(message.Message):
208
    e164_number: str
209
    short_code: PhoneNumber.ShortCode
210
    extension: str
211

212
# Postal addresses
213
class PostalAddress(message.Message):
214
    revision: int
215
    region_code: str
216
    postal_code: str
217
    administrative_area: str
218
    locality: str
219
    address_lines: list[str]
220
```
221

222
[Common Data Types](./common-types.md)
223

224
### Long-Running Operations
225

226
Support for asynchronous operations that may take significant time to complete. Provides standard patterns for operation management, polling, and result retrieval.
227

228
```python { .api }
229
# Operation representation
230
class Operation(message.Message):
231
    name: str
232
    metadata: Any
233
    done: bool
234
    error: Status
235
    response: Any
236

237
# Operation management requests
238
class GetOperationRequest(message.Message):
239
    name: str
240

241
class ListOperationsRequest(message.Message):
242
    name: str
243
    filter: str
244
    page_size: int
245
    page_token: str
246

247
class CancelOperationRequest(message.Message):
248
    name: str
249
```
250

251
[Long-Running Operations](./operations.md)
252

253
### Monitoring and Observability
254

255
Types for metrics, distributions, monitored resources, and logging. Enables comprehensive observability and monitoring of Google services with structured data collection.
256

257
```python { .api }
258
# Metric definitions
259
class MetricDescriptor(message.Message):
260
    name: str
261
    type: str
262
    labels: list[LabelDescriptor]
263
    metric_kind: MetricDescriptor.MetricKind
264
    value_type: MetricDescriptor.ValueType
265
    unit: str
266
    description: str
267

268
# Statistical distributions
269
class Distribution(message.Message):
270
    count: int
271
    mean: float
272
    sum_of_squared_deviation: float
273
    range: Distribution.Range
274
    bucket_options: Distribution.BucketOptions
275
    bucket_counts: list[int]
276

277
# Monitored resource descriptors
278
class MonitoredResourceDescriptor(message.Message):
279
    name: str
280
    type: str
281
    display_name: str
282
    description: str
283
    labels: list[LabelDescriptor]
284
```
285

286
[Monitoring and Observability](./monitoring.md)
287

288
### Cloud Services Integration
289

290
Cloud-specific extensions for location services, extended operations, and Google Cloud Platform integration. Provides types for multi-region services and cloud resource management.
291

292
```python { .api }
293
# Cloud location representation
294
class Location(message.Message):
295
    name: str
296
    location_id: str
297
    display_name: str
298
    labels: dict[str, str]
299
    metadata: Any
300

301
# Location service requests
302
class ListLocationsRequest(message.Message):
303
    name: str
304
    filter: str
305
    page_size: int
306
    page_token: str
307

308
class GetLocationRequest(message.Message):
309
    name: str
310
```
311

312
[Cloud Services Integration](./cloud-services.md)
313

314
### Logging Framework
315

316
Types for structured logging with severity levels and HTTP request information.
317

318
```python { .api }
319
# Log severity levels
320
class LogSeverity(enum.Enum):
321
    DEFAULT = 0
322
    DEBUG = 100
323
    INFO = 200
324
    NOTICE = 300
325
    WARNING = 400
326
    ERROR = 500
327
    CRITICAL = 600
328
    ALERT = 700
329
    EMERGENCY = 800
330

331
# HTTP request information for logging
332
class HttpRequest(message.Message):
333
    request_method: str
334
    request_url: str
335
    request_size: int
336
    status: int
337
    response_size: int
338
    user_agent: str
339
    remote_ip: str
340
    server_ip: str
341
    referer: str
342
    latency: Duration
343
    cache_lookup: bool
344
    cache_hit: bool
345
    cache_validated_with_origin_server: bool
346
    cache_fill_bytes: int
347
    protocol: str
348
```
349

350
## Type System
351

352
All protobuf message classes provide:
353

354
- **Type Safety**: Full typing support with `.pyi` stub files
355
- **Field Access**: Direct attribute access with validation
356
- **Serialization**: Standard protobuf serialization/deserialization  
357
- **Memory Efficiency**: `__slots__` optimization for all classes
358
- **Field Numbers**: `FIELD_NUMBER` constants for each field
359
- **Nested Types**: Support for nested messages and enums
360
- **Optional Fields**: Constructor parameters are optional by default
361
- **Container Types**: Specialized containers for repeated fields and maps