feat: incorporate upstream changes (#73)

* feat: Support MULAW audio encoding
* feat: Support MP3_64_KBPS audio encoding
* feat: Support timepointing via SSML tag
* feat: Support quota_project_id
* docs: generate and upload docfx yaml files
* testing: add docs-presubmit build

.flake8

@@ -16,7 +16,7 @@
 
 # Generated by synthtool. DO NOT EDIT!
 [flake8]
-ignore = E203, E266, E501, W503, F401, F841
+ignore = E203, E266, E501, W503
 exclude =
   # Exclude generated code.
   **/proto/**

.kokoro/docker/docs/fetch_gpg_keys.sh

@@ -14,6 +14,8 @@
 # limitations under the License.
 
 # A script to fetch gpg keys with retry.
+# Avoid jinja parsing the file.
+# 
 
 function retry {
     if [[ "${#}" -le 1 ]]; then
@@ -39,3 +41,5 @@ retry 3 gpg --keyserver ha.pool.sks-keyservers.net --recv-keys \
 # 3.8.0 (Łukasz Langa)
 retry 3 gpg --keyserver ha.pool.sks-keyservers.net --recv-keys \
       E3FF2839C048B25C084DEBE9B26995E310250568
+
+# 

.kokoro/docs/common.cfg

@@ -18,7 +18,6 @@ env_vars: {
     key: "TRAMPOLINE_IMAGE"
     value: "gcr.io/cloud-devrel-kokoro-resources/python-lib-docs"
 }
-
 env_vars: {
     key: "TRAMPOLINE_BUILD_FILE"
     value: "github/python-texttospeech/.kokoro/publish-docs.sh"

.kokoro/publish-docs.sh

@@ -56,8 +56,7 @@ python3 -m docuploader create-metadata \
   --distribution-name=$(python3 setup.py --name) \
   --product-page=$(jq --raw-output '.product_documentation // empty' .repo-metadata.json) \
   --github-repository=$(jq --raw-output '.repo // empty' .repo-metadata.json) \
-  --issue-tracker=$(jq --raw-output '.issue_tracker // empty' .repo-metadata.json) \
-  --serving-path="/python/docs/reference/$(jq --raw-output '.name // empty' .repo-metadata.json)/$(jq --raw-output '.distribution_name // empty' .repo-metadata.json)/latest"
+  --issue-tracker=$(jq --raw-output '.issue_tracker // empty' .repo-metadata.json)
 
 cat docs.metadata
 

docs/_templates/layout.html

@@ -21,8 +21,8 @@
 
           <div class="body" role="main">
           	<div class="admonition" id="python2-eol"> 
-          	 On January 1, 2020 this library will no longer support Python 2 on the latest released version. 
-          	 Previously released library versions will continue to be available. For more information please
+          	 As of January 1, 2020 this library no longer supports Python 2 on the latest released version. 
+          	 Library versions released prior to that date will continue to be available. For more information please
           	 visit <a href="https://cloud.google.com/python/docs/python2-sunset/">Python 2 support on Google Cloud</a>.
           	</div>
             {% block body %} {% endblock %}

docs/conf.py

@@ -23,7 +23,6 @@
 # For plugins that can not read conf.py.
 sys.path.insert(0, os.path.abspath("."))
 
-
 __version__ = ""
 
 # -- General configuration ------------------------------------------------
@@ -341,7 +340,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),
 }
 

google/cloud/texttospeech_v1/services/text_to_speech/__init__.py

@@ -18,4 +18,7 @@
 from .client import TextToSpeechClient
 from .async_client import TextToSpeechAsyncClient
 
-__all__ = ("TextToSpeechClient", "TextToSpeechAsyncClient")
+__all__ = (
+    "TextToSpeechClient",
+    "TextToSpeechAsyncClient",
+)

google/cloud/texttospeech_v1/services/text_to_speech/async_client.py

@@ -88,7 +88,7 @@ def __init__(
         """
 
         self._client = TextToSpeechClient(
-            credentials=credentials, transport=transport, client_options=client_options
+            credentials=credentials, transport=transport, client_options=client_options,
         )
 
     async def list_voices(
@@ -113,9 +113,9 @@ async def list_voices(
                 only return voices that can be used to synthesize this
                 language_code. E.g. when specifying "en-NZ", you will
                 get supported "en-\*" voices; when specifying "no", you
-                will get supported "no-\*" (Norwegian) and "nb-*"
+                will get supported "no-\*" (Norwegian) and "nb-\*"
                 (Norwegian Bokmal) voices; specifying "zh" will also get
-                supported "cmn-*" voices; specifying "zh-hk" will also
+                supported "cmn-\*" voices; specifying "zh-hk" will also
                 get supported "yue-\*" voices.
                 This corresponds to the ``language_code`` field
                 on the ``request`` instance; if ``request`` is provided, this
@@ -159,7 +159,7 @@ async def list_voices(
         )
 
         # Send the request.
-        response = await rpc(request, retry=retry, timeout=timeout, metadata=metadata)
+        response = await rpc(request, retry=retry, timeout=timeout, metadata=metadata,)
 
         # Done; return the response.
         return response
@@ -243,7 +243,7 @@ async def synthesize_speech(
         )
 
         # Send the request.
-        response = await rpc(request, retry=retry, timeout=timeout, metadata=metadata)
+        response = await rpc(request, retry=retry, timeout=timeout, metadata=metadata,)
 
         # Done; return the response.
         return response
@@ -252,8 +252,8 @@ async def synthesize_speech(
 try:
     _client_info = gapic_v1.client_info.ClientInfo(
         gapic_version=pkg_resources.get_distribution(
-            "google-cloud-texttospeech"
-        ).version
+            "google-cloud-texttospeech",
+        ).version,
     )
 except pkg_resources.DistributionNotFound:
     _client_info = gapic_v1.client_info.ClientInfo()

google/cloud/texttospeech_v1/services/text_to_speech/client.py

@@ -49,7 +49,7 @@ class TextToSpeechClientMeta(type):
     _transport_registry["grpc"] = TextToSpeechGrpcTransport
     _transport_registry["grpc_asyncio"] = TextToSpeechGrpcAsyncIOTransport
 
-    def get_transport_class(cls, label: str = None) -> Type[TextToSpeechTransport]:
+    def get_transport_class(cls, label: str = None,) -> Type[TextToSpeechTransport]:
         """Return an appropriate transport class.
 
         Args:
@@ -192,19 +192,27 @@ def __init__(
         # instance provides an extensibility point for unusual situations.
         if isinstance(transport, TextToSpeechTransport):
             # transport is a TextToSpeechTransport instance.
-            if credentials:
+            if credentials or client_options.credentials_file:
                 raise ValueError(
                     "When providing a transport instance, "
                     "provide its credentials directly."
                 )
+            if client_options.scopes:
+                raise ValueError(
+                    "When providing a transport instance, "
+                    "provide its scopes directly."
+                )
             self._transport = transport
         else:
             Transport = type(self).get_transport_class(transport)
             self._transport = Transport(
                 credentials=credentials,
+                credentials_file=client_options.credentials_file,
                 host=client_options.api_endpoint,
+                scopes=client_options.scopes,
                 api_mtls_endpoint=client_options.api_endpoint,
                 client_cert_source=client_options.client_cert_source,
+                quota_project_id=client_options.quota_project_id,
             )
 
     def list_voices(
@@ -229,9 +237,9 @@ def list_voices(
                 only return voices that can be used to synthesize this
                 language_code. E.g. when specifying "en-NZ", you will
                 get supported "en-\*" voices; when specifying "no", you
-                will get supported "no-\*" (Norwegian) and "nb-*"
+                will get supported "no-\*" (Norwegian) and "nb-\*"
                 (Norwegian Bokmal) voices; specifying "zh" will also get
-                supported "cmn-*" voices; specifying "zh-hk" will also
+                supported "cmn-\*" voices; specifying "zh-hk" will also
                 get supported "yue-\*" voices.
                 This corresponds to the ``language_code`` field
                 on the ``request`` instance; if ``request`` is provided, this
@@ -252,28 +260,32 @@ def list_voices(
         # Create or coerce a protobuf request object.
         # Sanity check: If we got a request object, we should *not* have
         # gotten any keyword arguments that map to the request.
-        if request is not None and any([language_code]):
+        has_flattened_params = any([language_code])
+        if request is not None and has_flattened_params:
             raise ValueError(
                 "If the `request` argument is set, then none of "
                 "the individual field arguments should be set."
             )
 
-        request = cloud_tts.ListVoicesRequest(request)
+        # Minor optimization to avoid making a copy if the user passes
+        # in a cloud_tts.ListVoicesRequest.
+        # There's no risk of modifying the input as we've already verified
+        # there are no flattened fields.
+        if not isinstance(request, cloud_tts.ListVoicesRequest):
+            request = cloud_tts.ListVoicesRequest(request)
 
-        # If we have keyword arguments corresponding to fields on the
-        # request, apply these.
+            # If we have keyword arguments corresponding to fields on the
+            # request, apply these.
 
-        if language_code is not None:
-            request.language_code = language_code
+            if language_code is not None:
+                request.language_code = language_code
 
         # Wrap the RPC method; this adds retry and timeout information,
         # and friendly error handling.
-        rpc = gapic_v1.method.wrap_method(
-            self._transport.list_voices, default_timeout=None, client_info=_client_info
-        )
+        rpc = self._transport._wrapped_methods[self._transport.list_voices]
 
         # Send the request.
-        response = rpc(request, retry=retry, timeout=timeout, metadata=metadata)
+        response = rpc(request, retry=retry, timeout=timeout, metadata=metadata,)
 
         # Done; return the response.
         return response
@@ -330,34 +342,36 @@ def synthesize_speech(
         # Create or coerce a protobuf request object.
         # Sanity check: If we got a request object, we should *not* have
         # gotten any keyword arguments that map to the request.
-        if request is not None and any([input, voice, audio_config]):
+        has_flattened_params = any([input, voice, audio_config])
+        if request is not None and has_flattened_params:
             raise ValueError(
                 "If the `request` argument is set, then none of "
                 "the individual field arguments should be set."
             )
 
-        request = cloud_tts.SynthesizeSpeechRequest(request)
+        # Minor optimization to avoid making a copy if the user passes
+        # in a cloud_tts.SynthesizeSpeechRequest.
+        # There's no risk of modifying the input as we've already verified
+        # there are no flattened fields.
+        if not isinstance(request, cloud_tts.SynthesizeSpeechRequest):
+            request = cloud_tts.SynthesizeSpeechRequest(request)
 
-        # If we have keyword arguments corresponding to fields on the
-        # request, apply these.
+            # If we have keyword arguments corresponding to fields on the
+            # request, apply these.
 
-        if input is not None:
-            request.input = input
-        if voice is not None:
-            request.voice = voice
-        if audio_config is not None:
-            request.audio_config = audio_config
+            if input is not None:
+                request.input = input
+            if voice is not None:
+                request.voice = voice
+            if audio_config is not None:
+                request.audio_config = audio_config
 
         # Wrap the RPC method; this adds retry and timeout information,
         # and friendly error handling.
-        rpc = gapic_v1.method.wrap_method(
-            self._transport.synthesize_speech,
-            default_timeout=None,
-            client_info=_client_info,
-        )
+        rpc = self._transport._wrapped_methods[self._transport.synthesize_speech]
 
         # Send the request.
-        response = rpc(request, retry=retry, timeout=timeout, metadata=metadata)
+        response = rpc(request, retry=retry, timeout=timeout, metadata=metadata,)
 
         # Done; return the response.
         return response
@@ -366,8 +380,8 @@ def synthesize_speech(
 try:
     _client_info = gapic_v1.client_info.ClientInfo(
         gapic_version=pkg_resources.get_distribution(
-            "google-cloud-texttospeech"
-        ).version
+            "google-cloud-texttospeech",
+        ).version,
     )
 except pkg_resources.DistributionNotFound:
     _client_info = gapic_v1.client_info.ClientInfo()

google/cloud/texttospeech_v1/services/text_to_speech/transports/base.py

@@ -17,13 +17,27 @@
 
 import abc
 import typing
+import pkg_resources
 
 from google import auth
+from google.api_core import exceptions  # type: ignore
+from google.api_core import gapic_v1  # type: ignore
+from google.api_core import retry as retries  # type: ignore
 from google.auth import credentials  # type: ignore
 
 from google.cloud.texttospeech_v1.types import cloud_tts
 
 
+try:
+    _client_info = gapic_v1.client_info.ClientInfo(
+        gapic_version=pkg_resources.get_distribution(
+            "google-cloud-texttospeech",
+        ).version,
+    )
+except pkg_resources.DistributionNotFound:
+    _client_info = gapic_v1.client_info.ClientInfo()
+
+
 class TextToSpeechTransport(abc.ABC):
     """Abstract transport class for TextToSpeech."""
 
@@ -34,6 +48,9 @@ def __init__(
         *,
         host: str = "texttospeech.googleapis.com",
         credentials: credentials.Credentials = None,
+        credentials_file: typing.Optional[str] = None,
+        scopes: typing.Optional[typing.Sequence[str]] = AUTH_SCOPES,
+        quota_project_id: typing.Optional[str] = None,
         **kwargs,
     ) -> None:
         """Instantiate the transport.
@@ -45,6 +62,12 @@ def __init__(
                 credentials identify the application to the service; if none
                 are specified, the client will attempt to ascertain the
                 credentials from the environment.
+            credentials_file (Optional[str]): A file with credentials that can
+                be loaded with :func:`google.auth.load_credentials_from_file`.
+                This argument is mutually exclusive with credentials.
+            scope (Optional[Sequence[str]]): A list of scopes.
+            quota_project_id (Optional[str]): An optional project to use for billing
+                and quota.
         """
         # Save the hostname. Default to port 443 (HTTPS) if none is specified.
         if ":" not in host:
@@ -53,15 +76,41 @@ def __init__(
 
         # If no credentials are provided, then determine the appropriate
         # defaults.
-        if credentials is None:
-            credentials, _ = auth.default(scopes=self.AUTH_SCOPES)
+        if credentials and credentials_file:
+            raise exceptions.DuplicateCredentialArgs(
+                "'credentials_file' and 'credentials' are mutually exclusive"
+            )
+
+        if credentials_file is not None:
+            credentials, _ = auth.load_credentials_from_file(
+                credentials_file, scopes=scopes, quota_project_id=quota_project_id
+            )
+
+        elif credentials is None:
+            credentials, _ = auth.default(
+                scopes=scopes, quota_project_id=quota_project_id
+            )
 
         # Save the credentials.
         self._credentials = credentials
 
+        # Lifted into its own function so it can be stubbed out during tests.
+        self._prep_wrapped_messages()
+
+    def _prep_wrapped_messages(self):
+        # Precompute the wrapped methods.
+        self._wrapped_methods = {
+            self.list_voices: gapic_v1.method.wrap_method(
+                self.list_voices, default_timeout=None, client_info=_client_info,
+            ),
+            self.synthesize_speech: gapic_v1.method.wrap_method(
+                self.synthesize_speech, default_timeout=None, client_info=_client_info,
+            ),
+        }
+
     @property
     def list_voices(
-        self
+        self,
     ) -> typing.Callable[
         [cloud_tts.ListVoicesRequest],
         typing.Union[
@@ -72,7 +121,7 @@ def list_voices(
 
     @property
     def synthesize_speech(
-        self
+        self,
     ) -> typing.Callable[
         [cloud_tts.SynthesizeSpeechRequest],
         typing.Union[