feat: add common resource helper methods; expose client transport (#55)

autosynth cannot find the source of changes triggered by earlier changes in this
        repository, or by version upgrades to tools such as linters.

docs/language_v1/types.rst

@@ -3,3 +3,4 @@ Types for Google Cloud Language v1 API
 
 .. automodule:: google.cloud.language_v1.types
     :members:
+    :show-inheritance:

docs/language_v1beta2/types.rst

@@ -3,3 +3,4 @@ Types for Google Cloud Language v1beta2 API
 
 .. automodule:: google.cloud.language_v1beta2.types
     :members:
+    :show-inheritance:

google/cloud/language_v1/proto/language_service.proto

@@ -100,7 +100,7 @@ service LanguageService {
   }
 }
 
-// ################################################################ #
+
 //
 // Represents the input to API methods.
 message Document {

google/cloud/language_v1/services/language_service/async_client.py

@@ -45,9 +45,47 @@ class LanguageServiceAsyncClient:
     DEFAULT_ENDPOINT = LanguageServiceClient.DEFAULT_ENDPOINT
     DEFAULT_MTLS_ENDPOINT = LanguageServiceClient.DEFAULT_MTLS_ENDPOINT
 
+    common_billing_account_path = staticmethod(
+        LanguageServiceClient.common_billing_account_path
+    )
+    parse_common_billing_account_path = staticmethod(
+        LanguageServiceClient.parse_common_billing_account_path
+    )
+
+    common_folder_path = staticmethod(LanguageServiceClient.common_folder_path)
+    parse_common_folder_path = staticmethod(
+        LanguageServiceClient.parse_common_folder_path
+    )
+
+    common_organization_path = staticmethod(
+        LanguageServiceClient.common_organization_path
+    )
+    parse_common_organization_path = staticmethod(
+        LanguageServiceClient.parse_common_organization_path
+    )
+
+    common_project_path = staticmethod(LanguageServiceClient.common_project_path)
+    parse_common_project_path = staticmethod(
+        LanguageServiceClient.parse_common_project_path
+    )
+
+    common_location_path = staticmethod(LanguageServiceClient.common_location_path)
+    parse_common_location_path = staticmethod(
+        LanguageServiceClient.parse_common_location_path
+    )
+
     from_service_account_file = LanguageServiceClient.from_service_account_file
     from_service_account_json = from_service_account_file
 
+    @property
+    def transport(self) -> LanguageServiceTransport:
+        """Return the transport used by the client instance.
+
+        Returns:
+            LanguageServiceTransport: The transport used by the client instance.
+        """
+        return self._client.transport
+
     get_transport_class = functools.partial(
         type(LanguageServiceClient).get_transport_class, type(LanguageServiceClient)
     )
@@ -143,7 +181,8 @@ async def analyze_sentiment(
         # 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([document, encoding_type]):
+        has_flattened_params = any([document, encoding_type])
+        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."
@@ -168,7 +207,7 @@ async def analyze_sentiment(
                 maximum=60.0,
                 multiplier=1.3,
                 predicate=retries.if_exception_type(
-                    exceptions.ServiceUnavailable, exceptions.DeadlineExceeded,
+                    exceptions.DeadlineExceeded, exceptions.ServiceUnavailable,
                 ),
             ),
             default_timeout=600.0,
@@ -224,7 +263,8 @@ async def analyze_entities(
         # 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([document, encoding_type]):
+        has_flattened_params = any([document, encoding_type])
+        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."
@@ -249,7 +289,7 @@ async def analyze_entities(
                 maximum=60.0,
                 multiplier=1.3,
                 predicate=retries.if_exception_type(
-                    exceptions.ServiceUnavailable, exceptions.DeadlineExceeded,
+                    exceptions.DeadlineExceeded, exceptions.ServiceUnavailable,
                 ),
             ),
             default_timeout=600.0,
@@ -308,7 +348,8 @@ async def analyze_entity_sentiment(
         # 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([document, encoding_type]):
+        has_flattened_params = any([document, encoding_type])
+        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."
@@ -333,7 +374,7 @@ async def analyze_entity_sentiment(
                 maximum=60.0,
                 multiplier=1.3,
                 predicate=retries.if_exception_type(
-                    exceptions.ServiceUnavailable, exceptions.DeadlineExceeded,
+                    exceptions.DeadlineExceeded, exceptions.ServiceUnavailable,
                 ),
             ),
             default_timeout=600.0,
@@ -388,7 +429,8 @@ async def analyze_syntax(
         # 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([document, encoding_type]):
+        has_flattened_params = any([document, encoding_type])
+        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."
@@ -413,7 +455,7 @@ async def analyze_syntax(
                 maximum=60.0,
                 multiplier=1.3,
                 predicate=retries.if_exception_type(
-                    exceptions.ServiceUnavailable, exceptions.DeadlineExceeded,
+                    exceptions.DeadlineExceeded, exceptions.ServiceUnavailable,
                 ),
             ),
             default_timeout=600.0,
@@ -462,7 +504,8 @@ async def classify_text(
         # 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([document]):
+        has_flattened_params = any([document])
+        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."
@@ -485,7 +528,7 @@ async def classify_text(
                 maximum=60.0,
                 multiplier=1.3,
                 predicate=retries.if_exception_type(
-                    exceptions.ServiceUnavailable, exceptions.DeadlineExceeded,
+                    exceptions.DeadlineExceeded, exceptions.ServiceUnavailable,
                 ),
             ),
             default_timeout=600.0,
@@ -550,7 +593,8 @@ async def annotate_text(
         # 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([document, features, encoding_type]):
+        has_flattened_params = any([document, features, encoding_type])
+        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."
@@ -577,7 +621,7 @@ async def annotate_text(
                 maximum=60.0,
                 multiplier=1.3,
                 predicate=retries.if_exception_type(
-                    exceptions.ServiceUnavailable, exceptions.DeadlineExceeded,
+                    exceptions.DeadlineExceeded, exceptions.ServiceUnavailable,
                 ),
             ),
             default_timeout=600.0,

google/cloud/language_v1/services/language_service/client.py

@@ -131,6 +131,74 @@ def from_service_account_file(cls, filename: str, *args, **kwargs):
 
     from_service_account_json = from_service_account_file
 
+    @property
+    def transport(self) -> LanguageServiceTransport:
+        """Return the transport used by the client instance.
+
+        Returns:
+            LanguageServiceTransport: The transport used by the client instance.
+        """
+        return self._transport
+
+    @staticmethod
+    def common_billing_account_path(billing_account: str,) -> str:
+        """Return a fully-qualified billing_account string."""
+        return "billingAccounts/{billing_account}".format(
+            billing_account=billing_account,
+        )
+
+    @staticmethod
+    def parse_common_billing_account_path(path: str) -> Dict[str, str]:
+        """Parse a billing_account path into its component segments."""
+        m = re.match(r"^billingAccounts/(?P<billing_account>.+?)$", path)
+        return m.groupdict() if m else {}
+
+    @staticmethod
+    def common_folder_path(folder: str,) -> str:
+        """Return a fully-qualified folder string."""
+        return "folders/{folder}".format(folder=folder,)
+
+    @staticmethod
+    def parse_common_folder_path(path: str) -> Dict[str, str]:
+        """Parse a folder path into its component segments."""
+        m = re.match(r"^folders/(?P<folder>.+?)$", path)
+        return m.groupdict() if m else {}
+
+    @staticmethod
+    def common_organization_path(organization: str,) -> str:
+        """Return a fully-qualified organization string."""
+        return "organizations/{organization}".format(organization=organization,)
+
+    @staticmethod
+    def parse_common_organization_path(path: str) -> Dict[str, str]:
+        """Parse a organization path into its component segments."""
+        m = re.match(r"^organizations/(?P<organization>.+?)$", path)
+        return m.groupdict() if m else {}
+
+    @staticmethod
+    def common_project_path(project: str,) -> str:
+        """Return a fully-qualified project string."""
+        return "projects/{project}".format(project=project,)
+
+    @staticmethod
+    def parse_common_project_path(path: str) -> Dict[str, str]:
+        """Parse a project path into its component segments."""
+        m = re.match(r"^projects/(?P<project>.+?)$", path)
+        return m.groupdict() if m else {}
+
+    @staticmethod
+    def common_location_path(project: str, location: str,) -> str:
+        """Return a fully-qualified location string."""
+        return "projects/{project}/locations/{location}".format(
+            project=project, location=location,
+        )
+
+    @staticmethod
+    def parse_common_location_path(path: str) -> Dict[str, str]:
+        """Parse a location path into its component segments."""
+        m = re.match(r"^projects/(?P<project>.+?)/locations/(?P<location>.+?)$", path)
+        return m.groupdict() if m else {}
+
     def __init__(
         self,
         *,
@@ -166,10 +234,10 @@ def __init__(
                 not provided, the default SSL client certificate will be used if
                 present. If GOOGLE_API_USE_CLIENT_CERTIFICATE is "false" or not
                 set, no client certificate will be used.
-            client_info (google.api_core.gapic_v1.client_info.ClientInfo):	
-                The client info used to send a user-agent string along with	
-                API requests. If ``None``, then default info will be used.	
-                Generally, you only need to set this if you're developing	
+            client_info (google.api_core.gapic_v1.client_info.ClientInfo):
+                The client info used to send a user-agent string along with
+                API requests. If ``None``, then default info will be used.
+                Generally, you only need to set this if you're developing
                 your own client library.
 
         Raises:

google/cloud/language_v1/services/language_service/transports/base.py

@@ -114,7 +114,7 @@ def _prep_wrapped_messages(self, client_info):
                     maximum=60.0,
                     multiplier=1.3,
                     predicate=retries.if_exception_type(
-                        exceptions.ServiceUnavailable, exceptions.DeadlineExceeded,
+                        exceptions.DeadlineExceeded, exceptions.ServiceUnavailable,
                     ),
                 ),
                 default_timeout=600.0,
@@ -127,7 +127,7 @@ def _prep_wrapped_messages(self, client_info):
                     maximum=60.0,
                     multiplier=1.3,
                     predicate=retries.if_exception_type(
-                        exceptions.ServiceUnavailable, exceptions.DeadlineExceeded,
+                        exceptions.DeadlineExceeded, exceptions.ServiceUnavailable,
                     ),
                 ),
                 default_timeout=600.0,
@@ -140,7 +140,7 @@ def _prep_wrapped_messages(self, client_info):
                     maximum=60.0,
                     multiplier=1.3,
                     predicate=retries.if_exception_type(
-                        exceptions.ServiceUnavailable, exceptions.DeadlineExceeded,
+                        exceptions.DeadlineExceeded, exceptions.ServiceUnavailable,
                     ),
                 ),
                 default_timeout=600.0,
@@ -153,7 +153,7 @@ def _prep_wrapped_messages(self, client_info):
                     maximum=60.0,
                     multiplier=1.3,
                     predicate=retries.if_exception_type(
-                        exceptions.ServiceUnavailable, exceptions.DeadlineExceeded,
+                        exceptions.DeadlineExceeded, exceptions.ServiceUnavailable,
                     ),
                 ),
                 default_timeout=600.0,
@@ -166,7 +166,7 @@ def _prep_wrapped_messages(self, client_info):
                     maximum=60.0,
                     multiplier=1.3,
                     predicate=retries.if_exception_type(
-                        exceptions.ServiceUnavailable, exceptions.DeadlineExceeded,
+                        exceptions.DeadlineExceeded, exceptions.ServiceUnavailable,
                     ),
                 ),
                 default_timeout=600.0,
@@ -179,7 +179,7 @@ def _prep_wrapped_messages(self, client_info):
                     maximum=60.0,
                     multiplier=1.3,
                     predicate=retries.if_exception_type(
-                        exceptions.ServiceUnavailable, exceptions.DeadlineExceeded,
+                        exceptions.DeadlineExceeded, exceptions.ServiceUnavailable,
                     ),
                 ),
                 default_timeout=600.0,

google/cloud/language_v1/services/language_service/transports/grpc.py

@@ -90,10 +90,10 @@ def __init__(
                 for grpc channel. It is ignored if ``channel`` is provided.
             quota_project_id (Optional[str]): An optional project to use for billing
                 and quota.
-            client_info (google.api_core.gapic_v1.client_info.ClientInfo):	
-                The client info used to send a user-agent string along with	
-                API requests. If ``None``, then default info will be used.	
-                Generally, you only need to set this if you're developing	
+            client_info (google.api_core.gapic_v1.client_info.ClientInfo):
+                The client info used to send a user-agent string along with
+                API requests. If ``None``, then default info will be used.
+                Generally, you only need to set this if you're developing
                 your own client library.
 
         Raises:
@@ -102,13 +102,16 @@ def __init__(
           google.api_core.exceptions.DuplicateCredentialArgs: If both ``credentials``
               and ``credentials_file`` are passed.
         """
+        self._ssl_channel_credentials = ssl_channel_credentials
+
         if channel:
             # Sanity check: Ensure that channel and credentials are not both
             # provided.
             credentials = False
 
             # If a channel was explicitly provided, set it.
             self._grpc_channel = channel
+            self._ssl_channel_credentials = None
         elif api_mtls_endpoint:
             warnings.warn(
                 "api_mtls_endpoint and client_cert_source are deprecated",
@@ -145,6 +148,7 @@ def __init__(
                 scopes=scopes or self.AUTH_SCOPES,
                 quota_project_id=quota_project_id,
             )
+            self._ssl_channel_credentials = ssl_credentials
         else:
             host = host if ":" in host else host + ":443"
 
@@ -222,12 +226,8 @@ def create_channel(
 
     @property
     def grpc_channel(self) -> grpc.Channel:
-        """Create the channel designed to connect to this service.
-
-        This property caches on the instance; repeated calls return
-        the same channel.
+        """Return the channel designed to connect to this service.
         """
-        # Return the channel from cache.
         return self._grpc_channel
 
     @property