feat: add common resource helpers; expose client transport; remove gRPC send/recv limits

UPGRADING.MD

@@ -17,10 +17,10 @@ The 2.0.0 release requires Python 3.6+.
 
 Methods expect request objects. We provide a script that will convert most common use cases.
 
-* Install the library
+* Install the library and `libcst >= 0.2.5`.
 
 ```py
-python3 -m pip install google-cloud-webrisk
+python3 -m pip install google-cloud-webrisk libcst >= 0.2.5
 ```
 
 * The scripts `fixup_webrisk_v1_keywords.py` and  `fixup_webrisk_v1beta1_keywords.py` shipped with the library. It expects

docs/webrisk_v1/types.rst

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

docs/webrisk_v1beta1/types.rst

@@ -3,3 +3,4 @@ Types for Google Cloud Webrisk v1beta1 API
 
 .. automodule:: google.cloud.webrisk_v1beta1.types
     :members:
+    :show-inheritance:

google/cloud/webrisk_v1/services/web_risk_service/async_client.py

@@ -31,7 +31,7 @@
 from google.cloud.webrisk_v1.types import webrisk
 from google.protobuf import timestamp_pb2 as timestamp  # type: ignore
 
-from .transports.base import WebRiskServiceTransport
+from .transports.base import WebRiskServiceTransport, DEFAULT_CLIENT_INFO
 from .transports.grpc_asyncio import WebRiskServiceGrpcAsyncIOTransport
 from .client import WebRiskServiceClient
 
@@ -46,9 +46,47 @@ class WebRiskServiceAsyncClient:
     DEFAULT_ENDPOINT = WebRiskServiceClient.DEFAULT_ENDPOINT
     DEFAULT_MTLS_ENDPOINT = WebRiskServiceClient.DEFAULT_MTLS_ENDPOINT
 
+    common_billing_account_path = staticmethod(
+        WebRiskServiceClient.common_billing_account_path
+    )
+    parse_common_billing_account_path = staticmethod(
+        WebRiskServiceClient.parse_common_billing_account_path
+    )
+
+    common_folder_path = staticmethod(WebRiskServiceClient.common_folder_path)
+    parse_common_folder_path = staticmethod(
+        WebRiskServiceClient.parse_common_folder_path
+    )
+
+    common_organization_path = staticmethod(
+        WebRiskServiceClient.common_organization_path
+    )
+    parse_common_organization_path = staticmethod(
+        WebRiskServiceClient.parse_common_organization_path
+    )
+
+    common_project_path = staticmethod(WebRiskServiceClient.common_project_path)
+    parse_common_project_path = staticmethod(
+        WebRiskServiceClient.parse_common_project_path
+    )
+
+    common_location_path = staticmethod(WebRiskServiceClient.common_location_path)
+    parse_common_location_path = staticmethod(
+        WebRiskServiceClient.parse_common_location_path
+    )
+
     from_service_account_file = WebRiskServiceClient.from_service_account_file
     from_service_account_json = from_service_account_file
 
+    @property
+    def transport(self) -> WebRiskServiceTransport:
+        """Return the transport used by the client instance.
+
+        Returns:
+            WebRiskServiceTransport: The transport used by the client instance.
+        """
+        return self._client.transport
+
     get_transport_class = functools.partial(
         type(WebRiskServiceClient).get_transport_class, type(WebRiskServiceClient)
     )
@@ -59,6 +97,7 @@ def __init__(
         credentials: credentials.Credentials = None,
         transport: Union[str, WebRiskServiceTransport] = "grpc_asyncio",
         client_options: ClientOptions = None,
+        client_info: gapic_v1.client_info.ClientInfo = DEFAULT_CLIENT_INFO,
     ) -> None:
         """Instantiate the web risk service client.
 
@@ -74,24 +113,30 @@ def __init__(
             client_options (ClientOptions): Custom options for the client. It
                 won't take effect if a ``transport`` instance is provided.
                 (1) The ``api_endpoint`` property can be used to override the
-                default endpoint provided by the client. GOOGLE_API_USE_MTLS
+                default endpoint provided by the client. GOOGLE_API_USE_MTLS_ENDPOINT
                 environment variable can also be used to override the endpoint:
                 "always" (always use the default mTLS endpoint), "never" (always
-                use the default regular endpoint, this is the default value for
-                the environment variable) and "auto" (auto switch to the default
-                mTLS endpoint if client SSL credentials is present). However,
-                the ``api_endpoint`` property takes precedence if provided.
-                (2) The ``client_cert_source`` property is used to provide client
-                SSL credentials for mutual TLS transport. If not provided, the
-                default SSL credentials will be used if present.
+                use the default regular endpoint) and "auto" (auto switch to the
+                default mTLS endpoint if client certificate is present, this is
+                the default value). However, the ``api_endpoint`` property takes
+                precedence if provided.
+                (2) If GOOGLE_API_USE_CLIENT_CERTIFICATE environment variable
+                is "true", then the ``client_cert_source`` property can be used
+                to provide client certificate for mutual TLS transport. If
+                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.
 
         Raises:
             google.auth.exceptions.MutualTlsChannelError: If mutual TLS transport
                 creation failed for any reason.
         """
 
         self._client = WebRiskServiceClient(
-            credentials=credentials, transport=transport, client_options=client_options,
+            credentials=credentials,
+            transport=transport,
+            client_options=client_options,
+            client_info=client_info,
         )
 
     async def compute_threat_list_diff(
@@ -157,7 +202,8 @@ async def compute_threat_list_diff(
         # 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([threat_type, version_token, constraints]):
+        has_flattened_params = any([threat_type, version_token, constraints])
+        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."
@@ -179,8 +225,16 @@ async def compute_threat_list_diff(
         # and friendly error handling.
         rpc = gapic_v1.method_async.wrap_method(
             self._client._transport.compute_threat_list_diff,
-            default_timeout=None,
-            client_info=_client_info,
+            default_retry=retries.Retry(
+                initial=0.1,
+                maximum=60.0,
+                multiplier=1.3,
+                predicate=retries.if_exception_type(
+                    exceptions.DeadlineExceeded, exceptions.ServiceUnavailable,
+                ),
+            ),
+            default_timeout=600.0,
+            client_info=DEFAULT_CLIENT_INFO,
         )
 
         # Send the request.
@@ -237,7 +291,8 @@ async def search_uris(
         # 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([uri, threat_types]):
+        has_flattened_params = any([uri, threat_types])
+        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."
@@ -250,15 +305,24 @@ async def search_uris(
 
         if uri is not None:
             request.uri = uri
-        if threat_types is not None:
-            request.threat_types = threat_types
+
+        if threat_types:
+            request.threat_types.extend(threat_types)
 
         # Wrap the RPC method; this adds retry and timeout information,
         # and friendly error handling.
         rpc = gapic_v1.method_async.wrap_method(
             self._client._transport.search_uris,
-            default_timeout=None,
-            client_info=_client_info,
+            default_retry=retries.Retry(
+                initial=0.1,
+                maximum=60.0,
+                multiplier=1.3,
+                predicate=retries.if_exception_type(
+                    exceptions.DeadlineExceeded, exceptions.ServiceUnavailable,
+                ),
+            ),
+            default_timeout=600.0,
+            client_info=DEFAULT_CLIENT_INFO,
         )
 
         # Send the request.
@@ -317,7 +381,8 @@ async def search_hashes(
         # 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([hash_prefix, threat_types]):
+        has_flattened_params = any([hash_prefix, threat_types])
+        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."
@@ -330,15 +395,24 @@ async def search_hashes(
 
         if hash_prefix is not None:
             request.hash_prefix = hash_prefix
-        if threat_types is not None:
-            request.threat_types = threat_types
+
+        if threat_types:
+            request.threat_types.extend(threat_types)
 
         # Wrap the RPC method; this adds retry and timeout information,
         # and friendly error handling.
         rpc = gapic_v1.method_async.wrap_method(
             self._client._transport.search_hashes,
-            default_timeout=None,
-            client_info=_client_info,
+            default_retry=retries.Retry(
+                initial=0.1,
+                maximum=60.0,
+                multiplier=1.3,
+                predicate=retries.if_exception_type(
+                    exceptions.DeadlineExceeded, exceptions.ServiceUnavailable,
+                ),
+            ),
+            default_timeout=600.0,
+            client_info=DEFAULT_CLIENT_INFO,
         )
 
         # Send the request.
@@ -400,7 +474,8 @@ async def create_submission(
         # 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([parent, submission]):
+        has_flattened_params = any([parent, submission])
+        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."
@@ -420,8 +495,8 @@ async def create_submission(
         # and friendly error handling.
         rpc = gapic_v1.method_async.wrap_method(
             self._client._transport.create_submission,
-            default_timeout=None,
-            client_info=_client_info,
+            default_timeout=60.0,
+            client_info=DEFAULT_CLIENT_INFO,
         )
 
         # Certain fields should be provided within the metadata header;
@@ -438,11 +513,11 @@ async def create_submission(
 
 
 try:
-    _client_info = gapic_v1.client_info.ClientInfo(
+    DEFAULT_CLIENT_INFO = gapic_v1.client_info.ClientInfo(
         gapic_version=pkg_resources.get_distribution("google-cloud-webrisk",).version,
     )
 except pkg_resources.DistributionNotFound:
-    _client_info = gapic_v1.client_info.ClientInfo()
+    DEFAULT_CLIENT_INFO = gapic_v1.client_info.ClientInfo()
 
 
 __all__ = ("WebRiskServiceAsyncClient",)