chore: show FutureWarning for LEP endpoints usage with use_regional_endpoints=True (#1432)

* chore: show `DeprecationWarning` for LEP endpoints usage

* fix mypy

* use custom bigframes warning as the default DeprecationWarning is disabled by default

* Revert "use custom bigframes warning as the default DeprecationWarning is disabled by default"

This reverts commit faa3050.

* revert custom warning, use FutureWarning instead for LEP deprecation

Author: shobsi

bigframes/constants.py

@@ -18,6 +18,7 @@
 """
 
 import datetime
+import textwrap
 
 DEFAULT_EXPIRATION = datetime.timedelta(days=7)
 
@@ -100,6 +101,25 @@
     ALL_BIGQUERY_LOCATIONS - REP_ENABLED_BIGQUERY_LOCATIONS
 )
 
+LEP_DEPRECATION_WARNING_MESSAGE = textwrap.dedent(
+    """
+    Support for regional endpoints is not yet available in the location
+    {location} for BigQuery and BigQuery Storage APIs. For the supported
+    locations and APIs see https://cloud.google.com/bigquery/docs/regional-endpoints.
+    For other locations and APIs, currently an older, now deprecated locational
+    endpoints are being used, which requires your project to be allowlisted. In
+    future version 2.0 onwards the locational endpoints will no longer be
+    supported automatically when you enable regional endpoints. However, if you
+    still need them, you will be able to override the endpoints directly by
+    doing the following:
+        bigframes.pandas.options.bigquery.client_endpoints_override = {{
+            "bqclient": "https://{location}-bigquery.googleapis.com",
+            "bqconnectionclient": "{location}-bigqueryconnection.googleapis.com",
+            "bqstoragereadclient": "{location}-bigquerystorage.googleapis.com"
+        }}
+    """
+).strip()
+
 # BigQuery default is 10000, leave 100 for overhead
 MAX_COLUMNS = 9900
 

bigframes/session/clients.py

@@ -17,6 +17,7 @@
 import os
 import typing
 from typing import Optional
+import warnings
 
 import google.api_core.client_info
 import google.api_core.client_options
@@ -94,8 +95,22 @@ def __init__(
             else _APPLICATION_NAME
         )
         self._project = project
+
+        if (
+            use_regional_endpoints
+            and location is not None
+            and location.lower()
+            not in bigframes.constants.REP_ENABLED_BIGQUERY_LOCATIONS
+        ):
+            warnings.warn(
+                bigframes.constants.LEP_DEPRECATION_WARNING_MESSAGE.format(
+                    location=location
+                ),
+                category=FutureWarning,
+            )
         self._location = location
         self._use_regional_endpoints = use_regional_endpoints
+
         self._credentials = credentials
         self._bq_kms_key_name = bq_kms_key_name
         self._client_endpoints_override = client_endpoints_override
@@ -117,20 +132,22 @@ def __init__(
 
     def _create_bigquery_client(self):
         bq_options = None
-        if self._use_regional_endpoints:
-            bq_options = google.api_core.client_options.ClientOptions(
-                api_endpoint=(
-                    _BIGQUERY_REGIONAL_ENDPOINT
-                    if self._location is not None
-                    and self._location.lower()
-                    in bigframes.constants.REP_ENABLED_BIGQUERY_LOCATIONS
-                    else _BIGQUERY_LOCATIONAL_ENDPOINT
-                ).format(location=self._location),
-            )
         if "bqclient" in self._client_endpoints_override:
             bq_options = google.api_core.client_options.ClientOptions(
                 api_endpoint=self._client_endpoints_override["bqclient"]
             )
+        elif self._use_regional_endpoints:
+            endpoint_template = _BIGQUERY_REGIONAL_ENDPOINT
+            if (
+                self._location is not None
+                and self._location.lower()
+                not in bigframes.constants.REP_ENABLED_BIGQUERY_LOCATIONS
+            ):
+                endpoint_template = _BIGQUERY_LOCATIONAL_ENDPOINT
+
+            bq_options = google.api_core.client_options.ClientOptions(
+                api_endpoint=endpoint_template.format(location=self._location)
+            )
 
         bq_info = google.api_core.client_info.ClientInfo(
             user_agent=self._application_name
@@ -172,16 +189,16 @@ def bqclient(self):
     def bqconnectionclient(self):
         if not self._bqconnectionclient:
             bqconnection_options = None
-            if self._use_regional_endpoints:
+            if "bqconnectionclient" in self._client_endpoints_override:
+                bqconnection_options = google.api_core.client_options.ClientOptions(
+                    api_endpoint=self._client_endpoints_override["bqconnectionclient"]
+                )
+            elif self._use_regional_endpoints:
                 bqconnection_options = google.api_core.client_options.ClientOptions(
                     api_endpoint=_BIGQUERYCONNECTION_LOCATIONAL_ENDPOINT.format(
                         location=self._location
                     )
                 )
-            if "bqconnectionclient" in self._client_endpoints_override:
-                bqconnection_options = google.api_core.client_options.ClientOptions(
-                    api_endpoint=self._client_endpoints_override["bqconnectionclient"]
-                )
 
             bqconnection_info = google.api_core.gapic_v1.client_info.ClientInfo(
                 user_agent=self._application_name
@@ -200,21 +217,23 @@ def bqconnectionclient(self):
     def bqstoragereadclient(self):
         if not self._bqstoragereadclient:
             bqstorage_options = None
-            if self._use_regional_endpoints:
+            if "bqstoragereadclient" in self._client_endpoints_override:
                 bqstorage_options = google.api_core.client_options.ClientOptions(
-                    api_endpoint=(
-                        _BIGQUERYSTORAGE_REGIONAL_ENDPOINT
-                        if self._location is not None
-                        and self._location.lower()
-                        in bigframes.constants.REP_ENABLED_BIGQUERY_LOCATIONS
-                        else _BIGQUERYSTORAGE_LOCATIONAL_ENDPOINT
-                    ).format(location=self._location),
+                    api_endpoint=self._client_endpoints_override["bqstoragereadclient"]
                 )
+            elif self._use_regional_endpoints:
+                endpoint_template = _BIGQUERYSTORAGE_REGIONAL_ENDPOINT
+                if (
+                    self._location is not None
+                    and self._location.lower()
+                    not in bigframes.constants.REP_ENABLED_BIGQUERY_LOCATIONS
+                ):
+                    endpoint_template = _BIGQUERYSTORAGE_LOCATIONAL_ENDPOINT
 
-            if "bqstoragereadclient" in self._client_endpoints_override:
                 bqstorage_options = google.api_core.client_options.ClientOptions(
-                    api_endpoint=self._client_endpoints_override["bqstoragereadclient"]
+                    api_endpoint=endpoint_template.format(location=self._location)
                 )
+
             bqstorage_info = google.api_core.gapic_v1.client_info.ClientInfo(
                 user_agent=self._application_name
             )

tests/system/large/test_location.py

@@ -13,6 +13,7 @@
 # limitations under the License.
 
 import typing
+import warnings
 
 from google.cloud import bigquery
 import pytest
@@ -118,12 +119,22 @@ def test_bq_location_non_canonical(set_location, resolved_location):
     sorted(bigframes.constants.REP_ENABLED_BIGQUERY_LOCATIONS),
 )
 def test_bq_rep_endpoints(bigquery_location):
-    session = bigframes.Session(
-        context=bigframes.BigQueryOptions(
-            location=bigquery_location, use_regional_endpoints=True
+    with warnings.catch_warnings(record=True) as record:
+        warnings.simplefilter("always")
+        session = bigframes.Session(
+            context=bigframes.BigQueryOptions(
+                location=bigquery_location, use_regional_endpoints=True
+            )
+        )
+        assert (
+            len([warn for warn in record if isinstance(warn.message, FutureWarning)])
+            == 0
         )
-    )
 
+    # Verify that location and endpoints are correctly set for the BigQuery API
+    # client
+    # TODO(shobs): Figure out if the same can be verified for the other API
+    # clients.
     assert session.bqclient.location == bigquery_location
     assert (
         session.bqclient._connection.API_BASE_URL
@@ -147,10 +158,21 @@ def test_bq_lep_endpoints(bigquery_location):
     # allowlisted for LEP access. We could hardcode one project which is
     # allowlisted but then not every open source developer will have access to
     # that. Let's rely on just creating the clients for LEP.
-    clients_provider = bigframes.session.clients.ClientsProvider(
-        location=bigquery_location, use_regional_endpoints=True
-    )
+    with pytest.warns(FutureWarning) as record:
+        clients_provider = bigframes.session.clients.ClientsProvider(
+            location=bigquery_location, use_regional_endpoints=True
+        )
+        assert len(record) == 1
+        assert typing.cast(Warning, record[0].message).args[
+            0
+        ] == bigframes.constants.LEP_DEPRECATION_WARNING_MESSAGE.format(
+            location=bigquery_location
+        )
 
+    # Verify that location and endpoints are correctly set for the BigQuery API
+    # client
+    # TODO(shobs): Figure out if the same can be verified for the other API
+    # clients.
     assert clients_provider.bqclient.location == bigquery_location
     assert (
         clients_provider.bqclient._connection.API_BASE_URL