Add comments for speech config options, + fix lint errors for new fla…

…ke8-import-order. (#429)

* Add comments for config options.

Some folks were tripping up on this.

* Fix lint for new flake8-import-order

appengine/standard/memcache/guestbook/main.py

@@ -20,8 +20,8 @@
 
 # [START all]
 
-import cgi
 import cStringIO
+import cgi
 import logging
 import urllib
 

speech/api/speech_async_grpc.py

@@ -59,8 +59,14 @@ def main(input_uri, encoding, sample_rate):
     # https://github.com/googleapis/googleapis/blob/master/google/cloud/speech/v1beta1/cloud_speech.proto
     response = service.AsyncRecognize(cloud_speech_pb2.AsyncRecognizeRequest(
         config=cloud_speech_pb2.RecognitionConfig(
-            encoding=encoding,
-            sample_rate=sample_rate,
+            # There are a bunch of config options you can specify. See
+            # https://goo.gl/A6xv5G for the full list.
+            encoding=encoding,  # one of LINEAR16, FLAC, MULAW, AMR, AMR_WB
+            sample_rate=sample_rate,  # the rate in hertz
+            # See
+            # https://g.co/cloud/speech/docs/best-practices#language_support
+            # for a list of supported languages.
+            language_code='en-US',  # a BCP-47 language tag
         ),
         audio=cloud_speech_pb2.RecognitionAudio(
             uri=input_uri,

speech/api/speech_async_rest.py

@@ -57,8 +57,12 @@ def main(speech_file):
     service_request = service.speech().asyncrecognize(
         body={
             'config': {
-                'encoding': 'LINEAR16',
-                'sampleRate': 16000
+                # There are a bunch of config options you can specify. See
+                # https://goo.gl/EPjAup for the full list.
+                'encoding': 'LINEAR16',  # raw 16-bit signed LE samples
+                'sampleRate': 16000,  # 16 khz
+                # See https://goo.gl/DPeVFW for a list of supported languages.
+                'languageCode': 'en-US',  # a BCP-47 language tag
             },
             'audio': {
                 'content': speech_content.decode('UTF-8')

speech/api/speech_grpc.py

@@ -56,8 +56,14 @@ def main(input_uri, encoding, sample_rate):
     # https://github.com/googleapis/googleapis/blob/master/google/cloud/speech/v1beta1/cloud_speech.proto
     response = service.SyncRecognize(cloud_speech.SyncRecognizeRequest(
         config=cloud_speech.RecognitionConfig(
-            encoding=encoding,
-            sample_rate=sample_rate,
+            # There are a bunch of config options you can specify. See
+            # https://goo.gl/A6xv5G for the full list.
+            encoding=encoding,  # one of LINEAR16, FLAC, MULAW, AMR, AMR_WB
+            sample_rate=sample_rate,  # the rate in hertz
+            # See
+            # https://g.co/cloud/speech/docs/best-practices#language_support
+            # for a list of supported languages.
+            language_code='en-US',  # a BCP-47 language tag
         ),
         audio=cloud_speech.RecognitionAudio(
             uri=input_uri,

speech/api/speech_rest.py

@@ -60,8 +60,12 @@ def main(speech_file):
     service_request = service.speech().syncrecognize(
         body={
             'config': {
-                'encoding': 'LINEAR16',
-                'sampleRate': 16000
+                # There are a bunch of config options you can specify. See
+                # https://goo.gl/EPjAup for the full list.
+                'encoding': 'LINEAR16',  # raw 16-bit signed LE samples
+                'sampleRate': 16000,  # 16 khz
+                # See https://goo.gl/DPeVFW for a list of supported languages.
+                'languageCode': 'en-US',  # a BCP-47 language tag
             },
             'audio': {
                 'content': speech_content.decode('UTF-8')

speech/api/speech_streaming.py

@@ -83,13 +83,21 @@ def request_stream(stop_audio, channels=CHANNELS, rate=RATE, chunk=CHUNK):
     Args:
         stop_audio: A threading.Event object stops the recording when set.
         channels: How many audio channels to record.
-        rate: The sampling rate.
+        rate: The sampling rate in hertz.
         chunk: Buffer audio into chunks of this size before sending to the api.
     """
     # The initial request must contain metadata about the stream, so the
     # server knows how to interpret it.
     recognition_config = cloud_speech.RecognitionConfig(
-        encoding='LINEAR16', sample_rate=rate)
+        # There are a bunch of config options you can specify. See
+        # https://goo.gl/A6xv5G for the full list.
+        encoding='LINEAR16',  # raw 16-bit signed LE samples
+        sample_rate=rate,  # the rate in hertz
+        # See
+        # https://g.co/cloud/speech/docs/best-practices#language_support
+        # for a list of supported languages.
+        language_code='en-US',  # a BCP-47 language tag
+    )
     streaming_config = cloud_speech.StreamingRecognitionConfig(
         config=recognition_config,
         # Note that setting interim_results to True means that you'll likely

vision/api/face_detection/faces.py

@@ -19,10 +19,10 @@
 import argparse
 import base64
 
-from googleapiclient import discovery
-from oauth2client.client import GoogleCredentials
 from PIL import Image
 from PIL import ImageDraw
+from googleapiclient import discovery
+from oauth2client.client import GoogleCredentials
 
 
 # [START get_vision_service]

vision/api/face_detection/faces_test.py

@@ -13,8 +13,8 @@
 
 import os
 
-from faces import main
 from PIL import Image
+from faces import main
 
 
 def test_main(resource, tmpdir):