@@ -171,6 +171,84 @@ comments and docstrings only as needed to further clarify the code’s intent.
171
171
Always introduce functions and variables before they are used. Prefer less
172
172
indirection. Prefer imperative programming as it is easier to understand.
173
173
174
+
175
+ ### Importing Google Cloud Libraries
176
+
177
+ Follow this style for importing Google Cloud libraries:
178
+
179
+ ``` py
180
+ from google.cloud import texttospeech_v1
181
+ ```
182
+
183
+ All commonly used clients and types are exposed under ` texttospeech_v1 ` .
184
+
185
+ ``` py
186
+ from google.cloud import texttospeech_v1
187
+
188
+ client = texttospeech_v1.TextToSpeechClient()
189
+
190
+ audio_config = texttospeech.AudioConfig(
191
+ audio_encoding = texttospeech.AudioEncoding.MP3
192
+ )
193
+ ```
194
+
195
+
196
+ ### Creating Request Objects for GAPICs
197
+
198
+ GAPIC libraries are generated from [ protos] ( https://github.com/googleapis/googleapis )
199
+ that define the API surface via a [ generator] ( https://github.com/googleapis/gapic-generator-python ) .
200
+ GAPIC libraries have library type ` GAPIC_AUTO ` in ` .repo-metadata.json `
201
+ located in the root of the repository. Some ` GAPIC_COMBO ` libraries will
202
+ also expose [ ` proto-plus ` ] ( https://github.com/googleapis/proto-plus-python/ ) types.
203
+
204
+ Because they are generated, GAPIC libraries share a common interface.
205
+ All API proto messages are exposed as ` proto-plus ` message classes.
206
+
207
+ ` proto-plus ` provides a [ few ways to create objects] ( https://proto-plus-python.readthedocs.io/en/latest/messages.html#usage ) .
208
+
209
+ Strongly prefer instantiating library types through the constructor
210
+ or by instantiating an empty object and initializing individual attributes.
211
+ The dictionary construction method is discouraged as it is harder to use
212
+ type checking and IDEs are not able to offer intellisense.
213
+
214
+ ``` py
215
+ # To try this sample yourself, install `google-cloud-tasks==2.5.1`
216
+ from google.cloud import tasks_v2
217
+
218
+
219
+ # 1. Generated types via constructor
220
+ task_from_constructor = tasks_v2.Task(
221
+ http_request = tasks_v2.HttpRequest(
222
+ http_method = tasks_v2.HttpMethod.POST ,
223
+ url = " https://pubsub.googleapis.com/v1/projects/my-project/topics/testtopic:publish" ,
224
+ body = b " eyJtZXNzYWdlcyI6IFt7ImRhdGEiOiAiVkdocGN5QnBjeUJoSUhSbGMzUUsifV19Cg==" ,
225
+ oauth_token = tasks_v2.OAuthToken(
226
+ service_account_email = ' my-svc-acct@my-project.iam.gserviceaccount.com'
227
+ )
228
+ )
229
+ )
230
+
231
+ # 2. Instantiate object and then set attributes
232
+ http_request = tasks_v2.HttpRequest()
233
+ http_request.http_method = tasks_v2.HttpMethod.POST
234
+ http_request.url = " https://pubsub.googleapis.com/v1/projects/my-project/topics/testtopic:publish"
235
+ http_request.body = b " eyJtZXNzYWdlcyI6IFt7ImRhdGEiOiAiVkdocGN5QnBjeUJoSUhSbGMzUUsifV19Cg==" ,
236
+ http_request.oauth_token.service_account_email = " my-svc-acct@my-project.iam.gserviceaccount.com"
237
+
238
+ task = tasks_v2.Task()
239
+ task.http_request = http_request
240
+
241
+ # 2. Dictionary (NOT RECOMMENDED)
242
+ task_from_dict = {
243
+ " http_request" : {
244
+ " http_method" : " POST" ,
245
+ " url" : " https://pubsub.googleapis.com/v1/projects/my-project/topics/testtopic:publish" ,
246
+ " body" : b " eyJtZXNzYWdlcyI6IFt7ImRhdGEiOiAiVkdocGN5QnBjeUJoSUhSbGMzUUsifV19Cg==" ,
247
+ " oauth_token" : {" service_account_email" :" my-svc-acct@my-project.iam.gserviceaccount.com" },
248
+ }
249
+ }
250
+ ```
251
+
174
252
### Functions and Classes
175
253
176
254
Very few samples will require authoring classes. Prefer functions whenever
0 commit comments