Repository navigation
🔍 Examples of Generated Samples for Code Review [DO NOT MERGE] - #9514
beccasaurus wants to merge 1 commit into
Conversation
googlebot
added
the
cla: yes
|
|
||
| parser = argparse.ArgumentParser() | ||
| parser.add_argument( | ||
| "--local_file_path", type=str, default="resources/brooklyn_bridge.raw" |
There was a problem hiding this comment.
Will this resource file be added alongside the sample?
busunkim96
added
api: language
|
/cc @googleapis/samplegen |
| Transcribe a long audio file using asynchronous speech recognition | ||
|
|
||
| Args: | ||
| local_file_path Path to local audio file, e.g. /path/audio.wav |
There was a problem hiding this comment.
Small nit
| local_file_path Path to local audio file, e.g. /path/audio.wav | |
| local_file_path (str): Path to local audio file, e.g. /path/audio.wav |
This is the docstring style used in the client libraries.
If it's tricky to get the type it would still be nice to have the : between the arg name and description. 😄
gguuss
left a comment
gguuss
left a comment
There was a problem hiding this comment.
A few nits on this style, I have become used to single-quote strings in Python and in general prefer to avoid comprehensively documenting arguments over giving variables meaningful names.
| """ | ||
| Analyzing Sentiment in a String | ||
|
|
||
| Args: |
There was a problem hiding this comment.
IIRC we generally have not been putting ARGS in python sample code.
To quote the Authoring GUIDE:
Generally, however, it's rarely necessary to exhaustively document the parameters this way. Lean towards unsurprising arguments with descriptive names, as having to resort to this kind of docstring might be extremely accurate but it comes at the cost of high redundancy, signal-to-noise ratio, and increased cognitive load.
There was a problem hiding this comment.
Personally, I'd go one step further and say we can have the function definition for ease-of-testing, but when I see the snippet embedded in the docs, it's more a distraction than anything. I'd love to see the imports and region tags all inside the function definition.
| import argparse | ||
|
|
||
| parser = argparse.ArgumentParser() | ||
| parser.add_argument("--text_content", type=str, default="I am so happy and joyful.") |
There was a problem hiding this comment.
As per the style guide:
Beyond PEP8, there are several idioms and style nits we prefer.
Use single quotes (') except for docstrings (which use """).
This is a hill I will die on, I have become very used to authoring Python strings preferring single-quotes over double-quotes and it is a convention both highlighted in our authoring guide as well as in older versions of the Google Python style guide (although they recently have loosened up this to just be consistent).
There was a problem hiding this comment.
We use black to format the code in all our library repos, which uses double-quotes unless the string contains a double-quote character.
At some point, I think we should start using black everywhere because I hate manually trying to format code to pass flake8.
|
|
||
| # [START speech_transcribe_async] | ||
| from google.cloud import speech_v1 | ||
| from google.cloud.speech_v1 import enums |
There was a problem hiding this comment.
From the Authoring Guide:
Beyond PEP8, there are several idioms and style nits we prefer.
from gcloud import datastore
instead of
from gcloud.datastore import Client
But use your best judgement here, I am not too picky on this one.
There was a problem hiding this comment.
I think enums is a module, so this does match the Authoring Guide.
| # usage: python3 samples/v1/language_sentiment_text.py [--text_content "I am so happy and joyful."] | ||
|
|
||
| # [START language_sentiment_text] | ||
| from google.cloud import language_v1 |
There was a problem hiding this comment.
from google.cloud import language_v1 --> from google.cloud import language_v1 as language
Makes it a lot easier to perform updates
|
301 Redirect => #9970 (which shows additional types of samples!) |
This Pull Request contains two code samples which were generated using the GAPIC generator:
language_sentiment_text) (config YAML)speech_transcribe_async) (config YAML)These code samples demonstrate a few features of the code sample generator:
You can find the existing, published hand-written versions of these code samples here:
For Python, existing hand-written code samples can be found in the
python-docs-samplesrepo.The goal is for these generated code samples to meet the expectations of hand-written samples.
Language experts, please TAL! 🧐
/cc @busunkim96 @crwilcox @tswast
This is one of seven Pull Requests being sent for code review of rendered generated sample syntax.