feat: add speech adaptation, phrase sets and custom classes; update d…

…efault retry configs (#35)
googleapis · Jun 25, 2020 · dba9b3a · dba9b3a
1 parent e2349f4
commit dba9b3a
Show file tree

Hide file tree

Showing 39 changed files with 2,515 additions and 859 deletions.
diff --git a/packages/google-cloud-python-speech/.coveragerc b/packages/google-cloud-python-speech/.coveragerc
@@ -1,3 +1,19 @@
+# -*- coding: utf-8 -*-
+#
+# Copyright 2020 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
 # Generated by synthtool. DO NOT EDIT!
 [run]
 branch = True

diff --git a/packages/google-cloud-python-speech/.flake8 b/packages/google-cloud-python-speech/.flake8
@@ -1,10 +1,28 @@
+# -*- coding: utf-8 -*-
+#
+# Copyright 2020 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
 # Generated by synthtool. DO NOT EDIT!
 [flake8]
 ignore = E203, E266, E501, W503
 exclude =
   # Exclude generated code.
   **/proto/**
   **/gapic/**
+  **/services/**
+  **/types/**
   *_pb2.py
 
   # Standard linting exemptions.

diff --git a/packages/google-cloud-python-speech/.gitignore b/packages/google-cloud-python-speech/.gitignore
@@ -10,6 +10,7 @@
 dist
 build
 eggs
+.eggs
 parts
 bin
 var
@@ -49,6 +50,7 @@ bigquery/docs/generated
 # Virtual environment
 env/
 coverage.xml
+sponge_log.xml
 
 # System test environment variables.
 system_tests/local_test_setup

diff --git a/packages/google-cloud-python-speech/CONTRIBUTING.rst b/packages/google-cloud-python-speech/CONTRIBUTING.rst
@@ -22,7 +22,7 @@ In order to add a feature:
   documentation.
 
 - The feature must work fully on the following CPython versions:  2.7,
-  3.5, 3.6, and 3.7 on both UNIX and Windows.
+  3.5, 3.6, 3.7 and 3.8 on both UNIX and Windows.
 
 - The feature must not add unnecessary dependencies (where
   "unnecessary" is of course subjective, but new dependencies should
@@ -214,26 +214,18 @@ We support:
 -  `Python 3.5`_
 -  `Python 3.6`_
 -  `Python 3.7`_
+-  `Python 3.8`_
 
 .. _Python 3.5: https://docs.python.org/3.5/
 .. _Python 3.6: https://docs.python.org/3.6/
 .. _Python 3.7: https://docs.python.org/3.7/
+.. _Python 3.8: https://docs.python.org/3.8/
 
 
 Supported versions can be found in our ``noxfile.py`` `config`_.
 
 .. _config: https://github.com/googleapis/python-speech/blob/master/noxfile.py
 
-We explicitly decided not to support `Python 2.5`_ due to `decreased usage`_
-and lack of continuous integration `support`_.
-
-.. _Python 2.5: https://docs.python.org/2.5/
-.. _decreased usage: https://caremad.io/2013/10/a-look-at-pypi-downloads/
-.. _support: https://blog.travis-ci.com/2013-11-18-upcoming-build-environment-updates/
-
-We have `dropped 2.6`_ as a supported version as well since Python 2.6 is no
-longer supported by the core development team.
-
 Python 2.7 support is deprecated. All code changes should maintain Python 2.7 compatibility until January 1, 2020.
 
 We also explicitly decided to support Python 3 beginning with version
@@ -247,7 +239,6 @@ We also explicitly decided to support Python 3 beginning with version
 .. _prominent: https://docs.djangoproject.com/en/1.9/faq/install/#what-python-version-can-i-use-with-django
 .. _projects: http://flask.pocoo.org/docs/0.10/python3/
 .. _Unicode literal support: https://www.python.org/dev/peps/pep-0414/
-.. _dropped 2.6: https://github.com/googleapis/google-cloud-python/issues/995
 
 **********
 Versioning

diff --git a/packages/google-cloud-python-speech/MANIFEST.in b/packages/google-cloud-python-speech/MANIFEST.in
@@ -1,6 +1,25 @@
+# -*- coding: utf-8 -*-
+#
+# Copyright 2020 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
 # Generated by synthtool. DO NOT EDIT!
 include README.rst LICENSE
 recursive-include google *.json *.proto
 recursive-include tests *
 global-exclude *.py[co]
 global-exclude __pycache__
+
+# Exclude scripts for samples readmegen
+prune scripts/readme-gen
diff --git a/packages/google-cloud-python-speech/docs/conf.py b/packages/google-cloud-python-speech/docs/conf.py
@@ -38,21 +38,18 @@
     "sphinx.ext.napoleon",
     "sphinx.ext.todo",
     "sphinx.ext.viewcode",
+    "recommonmark",
 ]
 
 # autodoc/autosummary flags
 autoclass_content = "both"
-autodoc_default_flags = ["members"]
+autodoc_default_options = {"members": True}
 autosummary_generate = True
 
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 
-# Allow markdown includes (so releases.md can include CHANGLEOG.md)
-# http://www.sphinx-doc.org/en/master/markdown.html
-source_parsers = {".md": "recommonmark.parser.CommonMarkParser"}
-
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
 # source_suffix = ['.rst', '.md']
@@ -340,7 +337,7 @@
 intersphinx_mapping = {
     "python": ("http://python.readthedocs.org/en/latest/", None),
     "google-auth": ("https://google-auth.readthedocs.io/en/stable", None),
-    "google.api_core": ("https://googleapis.dev/python/google-api-core/latest/", None),
+    "google.api_core": ("https://googleapis.dev/python/google-api-core/latest/", None,),
     "grpc": ("https://grpc.io/grpc/python/", None),
 }
 

diff --git a/packages/google-cloud-python-speech/docs/index.rst b/packages/google-cloud-python-speech/docs/index.rst
@@ -1,5 +1,7 @@
 .. include:: README.rst
 
+.. include:: multiprocessing.rst
+
 Using the Library
 -----------------
 

diff --git a/packages/google-cloud-python-speech/docs/multiprocessing.rst b/packages/google-cloud-python-speech/docs/multiprocessing.rst
@@ -0,0 +1,7 @@
+.. note::
+
+   Because this client uses :mod:`grpcio` library, it is safe to
+   share instances across threads. In multiprocessing scenarios, the best
+   practice is to create client instances *after* the invocation of
+   :func:`os.fork` by :class:`multiprocessing.Pool` or
+   :class:`multiprocessing.Process`.
diff --git a/packages/google-cloud-python-speech/google/cloud/speech.py b/packages/google-cloud-python-speech/google/cloud/speech.py
@@ -22,4 +22,8 @@
 from google.cloud.speech_v1 import types
 
 
-__all__ = ("enums", "types", "SpeechClient")
+__all__ = (
+    "enums",
+    "types",
+    "SpeechClient",
+)
diff --git a/packages/google-cloud-python-speech/google/cloud/speech_v1/gapic/enums.py b/packages/google-cloud-python-speech/google/cloud/speech_v1/gapic/enums.py
@@ -49,20 +49,21 @@ class AudioEncoding(enum.IntEnum):
         Attributes:
           ENCODING_UNSPECIFIED (int): Not specified.
           LINEAR16 (int): Uncompressed 16-bit signed little-endian samples (Linear PCM).
-          FLAC (int): ``FLAC`` (Free Lossless Audio Codec) is the recommended encoding because
-          it is lossless--therefore recognition is not compromised--and requires
-          only about half the bandwidth of ``LINEAR16``. ``FLAC`` stream encoding
-          supports 16-bit and 24-bit samples, however, not all fields in
+          FLAC (int): ``FLAC`` (Free Lossless Audio Codec) is the recommended encoding
+          because it is lossless--therefore recognition is not compromised--and
+          requires only about half the bandwidth of ``LINEAR16``. ``FLAC`` stream
+          encoding supports 16-bit and 24-bit samples, however, not all fields in
           ``STREAMINFO`` are supported.
           MULAW (int): 8-bit samples that compand 14-bit audio samples using G.711 PCMU/mu-law.
           AMR (int): Adaptive Multi-Rate Narrowband codec. ``sample_rate_hertz`` must be
           8000.
-          AMR_WB (int): Adaptive Multi-Rate Wideband codec. ``sample_rate_hertz`` must be 16000.
+          AMR_WB (int): Adaptive Multi-Rate Wideband codec. ``sample_rate_hertz`` must be
+          16000.
           OGG_OPUS (int): Opus encoded audio frames in Ogg container
           (`OggOpus <https://wiki.xiph.org/OggOpus>`__). ``sample_rate_hertz``
           must be one of 8000, 12000, 16000, 24000, or 48000.
-          SPEEX_WITH_HEADER_BYTE (int): Although the use of lossy encodings is not recommended, if a very low
-          bitrate encoding is required, ``OGG_OPUS`` is highly preferred over
+          SPEEX_WITH_HEADER_BYTE (int): Although the use of lossy encodings is not recommended, if a very
+          low bitrate encoding is required, ``OGG_OPUS`` is highly preferred over
           Speex encoding. The `Speex <https://speex.org/>`__ encoding supported by
           Cloud Speech API has a header byte in each block, as in MIME type
           ``audio/x-speex-with-header-byte``. It is a variant of the RTP Speex
@@ -97,7 +98,7 @@ class InteractionType(enum.IntEnum):
           DISCUSSION (int): Multiple people in a conversation or discussion. For example in a
           meeting with two or more people actively participating. Typically all
           the primary people speaking would be in the same room (if not, see
-          PHONE\_CALL)
+          PHONE_CALL)
           PRESENTATION (int): One or more persons lecturing or presenting to others, mostly
           uninterrupted.
           PHONE_CALL (int): A phone-call or video-conference in which two or more people, who are
@@ -182,11 +183,11 @@ class SpeechEventType(enum.IntEnum):
 
         Attributes:
           SPEECH_EVENT_UNSPECIFIED (int): No speech event specified.
-          END_OF_SINGLE_UTTERANCE (int): This event indicates that the server has detected the end of the user's
-          speech utterance and expects no additional speech. Therefore, the server
-          will not process additional audio (although it may subsequently return
-          additional results). The client should stop sending additional audio
-          data, half-close the gRPC connection, and wait for any additional
+          END_OF_SINGLE_UTTERANCE (int): This event indicates that the server has detected the end of the
+          user's speech utterance and expects no additional speech. Therefore, the
+          server will not process additional audio (although it may subsequently
+          return additional results). The client should stop sending additional
+          audio data, half-close the gRPC connection, and wait for any additional
           results until the server closes the gRPC connection. This event is only
           sent if ``single_utterance`` was set to ``true``, and is not used
           otherwise.

diff --git a/packages/google-cloud-python-speech/google/cloud/speech_v1/gapic/speech_client.py b/packages/google-cloud-python-speech/google/cloud/speech_v1/gapic/speech_client.py
@@ -38,7 +38,7 @@
 from google.longrunning import operations_pb2
 
 
-_GAPIC_LIBRARY_VERSION = pkg_resources.get_distribution("google-cloud-speech").version
+_GAPIC_LIBRARY_VERSION = pkg_resources.get_distribution("google-cloud-speech",).version
 
 
 class SpeechClient(object):
@@ -158,12 +158,12 @@ def __init__(
                 self.transport = transport
         else:
             self.transport = speech_grpc_transport.SpeechGrpcTransport(
-                address=api_endpoint, channel=channel, credentials=credentials
+                address=api_endpoint, channel=channel, credentials=credentials,
             )
 
         if client_info is None:
             client_info = google.api_core.gapic_v1.client_info.ClientInfo(
-                gapic_version=_GAPIC_LIBRARY_VERSION
+                gapic_version=_GAPIC_LIBRARY_VERSION,
             )
         else:
             client_info.gapic_version = _GAPIC_LIBRARY_VERSION
@@ -174,7 +174,7 @@ def __init__(
         # (Ordinarily, these are the defaults specified in the `*_config.py`
         # file next to this one.)
         self._method_configs = google.api_core.gapic_v1.config.parse_method_configs(
-            client_config["interfaces"][self._INTERFACE_NAME]
+            client_config["interfaces"][self._INTERFACE_NAME],
         )
 
         # Save a dictionary of cached API call functions.
@@ -251,7 +251,7 @@ def recognize(
                 client_info=self._client_info,
             )
 
-        request = cloud_speech_pb2.RecognizeRequest(config=config, audio=audio)
+        request = cloud_speech_pb2.RecognizeRequest(config=config, audio=audio,)
         return self._inner_api_calls["recognize"](
             request, retry=retry, timeout=timeout, metadata=metadata
         )
@@ -337,7 +337,7 @@ def long_running_recognize(
             )
 
         request = cloud_speech_pb2.LongRunningRecognizeRequest(
-            config=config, audio=audio
+            config=config, audio=audio,
         )
         operation = self._inner_api_calls["long_running_recognize"](
             request, retry=retry, timeout=timeout, metadata=metadata
@@ -360,8 +360,6 @@ def streaming_recognize(
         Performs bidirectional streaming speech recognition: receive results while
         sending audio. This method is only available via the gRPC API (not REST).
 
-        EXPERIMENTAL: This method interface might change in the future.
-
         Example:
             >>> from google.cloud import speech_v1
             >>>

diff --git a/packages/google-cloud-python-speech/google/cloud/speech_v1/gapic/speech_client_config.py b/packages/google-cloud-python-speech/google/cloud/speech_v1/gapic/speech_client_config.py
@@ -2,35 +2,54 @@
     "interfaces": {
         "google.cloud.speech.v1.Speech": {
             "retry_codes": {
-                "idempotent": ["DEADLINE_EXCEEDED", "UNAVAILABLE"],
-                "non_idempotent": [],
+                "retry_policy_1_codes": ["UNAVAILABLE", "DEADLINE_EXCEEDED"],
+                "no_retry_codes": [],
+                "no_retry_1_codes": [],
             },
             "retry_params": {
-                "default": {
+                "retry_policy_1_params": {
                     "initial_retry_delay_millis": 100,
                     "retry_delay_multiplier": 1.3,
                     "max_retry_delay_millis": 60000,
-                    "initial_rpc_timeout_millis": 1000000,
+                    "initial_rpc_timeout_millis": 5000000,
                     "rpc_timeout_multiplier": 1.0,
-                    "max_rpc_timeout_millis": 1000000,
+                    "max_rpc_timeout_millis": 5000000,
                     "total_timeout_millis": 5000000,
-                }
+                },
+                "no_retry_params": {
+                    "initial_retry_delay_millis": 0,
+                    "retry_delay_multiplier": 0.0,
+                    "max_retry_delay_millis": 0,
+                    "initial_rpc_timeout_millis": 0,
+                    "rpc_timeout_multiplier": 1.0,
+                    "max_rpc_timeout_millis": 0,
+                    "total_timeout_millis": 0,
+                },
+                "no_retry_1_params": {
+                    "initial_retry_delay_millis": 0,
+                    "retry_delay_multiplier": 0.0,
+                    "max_retry_delay_millis": 0,
+                    "initial_rpc_timeout_millis": 5000000,
+                    "rpc_timeout_multiplier": 1.0,
+                    "max_rpc_timeout_millis": 5000000,
+                    "total_timeout_millis": 5000000,
+                },
             },
             "methods": {
                 "Recognize": {
-                    "timeout_millis": 60000,
-                    "retry_codes_name": "idempotent",
-                    "retry_params_name": "default",
+                    "timeout_millis": 5000000,
+                    "retry_codes_name": "retry_policy_1_codes",
+                    "retry_params_name": "retry_policy_1_params",
                 },
                 "LongRunningRecognize": {
-                    "timeout_millis": 60000,
-                    "retry_codes_name": "non_idempotent",
-                    "retry_params_name": "default",
+                    "timeout_millis": 5000000,
+                    "retry_codes_name": "no_retry_1_codes",
+                    "retry_params_name": "no_retry_1_params",
                 },
                 "StreamingRecognize": {
-                    "timeout_millis": 60000,
-                    "retry_codes_name": "non_idempotent",
-                    "retry_params_name": "default",
+                    "timeout_millis": 5000000,
+                    "retry_codes_name": "retry_policy_1_codes",
+                    "retry_params_name": "retry_policy_1_params",
                 },
             },
         }