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

…efault retry configs (#35)

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

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.

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

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

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

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),
 }
 

packages/google-cloud-python-speech/docs/index.rst

@@ -1,5 +1,7 @@
 .. include:: README.rst
 
+.. include:: multiprocessing.rst
+
 Using the Library
 -----------------
 

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`.

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",
+)

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.

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
  >>>

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",
  },
  },
  }