Skip to content

Commit b0829c3

Browse files
docs: add guidelines around imports and initializing GAPIC objects (#6582)
* docs: add guidelines around imports and initializing GAPIC objects * Apply suggestions from code review Co-authored-by: Leah E. Cole <6719667+leahecole@users.noreply.github.com>
1 parent fde487c commit b0829c3

File tree

1 file changed

+78
-0
lines changed

1 file changed

+78
-0
lines changed

AUTHORING_GUIDE.md

+78
Original file line numberDiff line numberDiff line change
@@ -171,6 +171,84 @@ comments and docstrings only as needed to further clarify the code’s intent.
171171
Always introduce functions and variables before they are used. Prefer less
172172
indirection. Prefer imperative programming as it is easier to understand.
173173

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+
174252
### Functions and Classes
175253

176254
Very few samples will require authoring classes. Prefer functions whenever

0 commit comments

Comments
 (0)