cloud-sql-python-connector 1.8.0__py2.py3-none-any.whl → 1.9.0__py2.py3-none-any.whl

{cloud_sql_python_connector-1.8.0.dist-info → cloud_sql_python_connector-1.9.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: cloud-sql-python-connector
-Version: 1.8.0
+Version: 1.9.0
 Summary: The Cloud SQL Python Connector is a library that can be used alongside a database driver to allow users with sufficient permissions to connect to a Cloud SQL database without having to manually allowlist IPs or manage SSL certificates.
 Home-page: https://github.com/GoogleCloudPlatform/cloud-sql-python-connector
 Author: Google LLC
@@ -26,7 +26,7 @@ Requires-Dist: google-auth
 Provides-Extra: asyncpg
 Requires-Dist: asyncpg (>=0.29.0) ; extra == 'asyncpg'
 Provides-Extra: pg8000
-Requires-Dist: pg8000 (>=1.30.5) ; extra == 'pg8000'
+Requires-Dist: pg8000 (>=1.31.1) ; extra == 'pg8000'
 Provides-Extra: pymysql
 Requires-Dist: PyMySQL (>=1.1.0) ; extra == 'pymysql'
 Provides-Extra: pytds

{cloud_sql_python_connector-1.8.0.dist-info → cloud_sql_python_connector-1.9.0.dist-info}/RECORD

@@ -1,7 +1,7 @@
 google/cloud/sql/connector/__init__.py,sha256=Z3AkPOQwjNF1ogo2DR18GN-CnYvI4MTmhsCe8hURKUo,883
 google/cloud/sql/connector/asyncpg.py,sha256=c4lAlvEgGf_eBq0G8MVNPRAJQQvo6DcwybiXDW36qkU,1838
-google/cloud/sql/connector/client.py,sha256=n1v6xxtfuvNZYCUfNUWY6FdNw9uvgOnmFxpSE0NmN5M,8263
-google/cloud/sql/connector/connector.py,sha256=nx5SVEJUF6pJt3VAmjw3-XBpWKFdWHJDEABM_pPzsvc,16867
+google/cloud/sql/connector/client.py,sha256=NZZnPqE_f13S04tpRCs0UGF-RxR4EL-_vH7ebQBXTaA,8494
+google/cloud/sql/connector/connector.py,sha256=WYWP5zUqGSgxWNARaVHO1720REVX-EdD5D4rmBw0Mbw,19188
 google/cloud/sql/connector/exceptions.py,sha256=rTBtbCoiZ3U5IFVsyXPw5baHbCODixx2hPDQeXUzgzs,1524
 google/cloud/sql/connector/instance.py,sha256=G7-SCqsLjZiOYZ-Ds2RIErs6oaT0ewnAN683fs7EebI,14920
 google/cloud/sql/connector/pg8000.py,sha256=EZuO7XgCkG_Y79NQlh3Vv8Ff2w85BFJyFVO237hx1GM,1814
@@ -11,9 +11,9 @@ google/cloud/sql/connector/pytds.py,sha256=vKJoE7E2P0GrhZojg8bGZkqCMLc8dgKAcXE4e
 google/cloud/sql/connector/rate_limiter.py,sha256=bPTupfM4f5QRSCmCAWMqjQylEB7bUM-50plVBU3W2CA,2993
 google/cloud/sql/connector/refresh_utils.py,sha256=P2ye3qDymdK1iOlGCXby4VIaqwvHdc9GEmuUsMcufxY,3680
 google/cloud/sql/connector/utils.py,sha256=FQs7RgoViJLIFgJIynVT-_DwAVWnpyXIKu5WZ4m10Ts,3448
-google/cloud/sql/connector/version.py,sha256=uFu1vr_bHDmu9LzGZmYfAmD9Cb7yvaTRwh3jChsfq0g,597
-cloud_sql_python_connector-1.8.0.dist-info/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
-cloud_sql_python_connector-1.8.0.dist-info/METADATA,sha256=FUIl4XRA6VgxpVcTI0sNtdIxch7MtBumAsGZ1TwdvFA,24102
-cloud_sql_python_connector-1.8.0.dist-info/WHEEL,sha256=bb2Ot9scclHKMOLDEHY6B2sicWOgugjFKaJsT7vwMQo,110
-cloud_sql_python_connector-1.8.0.dist-info/top_level.txt,sha256=_1QvSJIhFAGfxb79D6DhB7SUw2X6T4rwnz_LLrbcD3c,7
-cloud_sql_python_connector-1.8.0.dist-info/RECORD,,
+google/cloud/sql/connector/version.py,sha256=YbELZlL2XCm9DhI5YdFuGTTRXdNla7msYYRyECFExSQ,597
+cloud_sql_python_connector-1.9.0.dist-info/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+cloud_sql_python_connector-1.9.0.dist-info/METADATA,sha256=20TIdOSzRhkL8LmlNEH8pFpqv2EXtwUxoJKBEudmwps,24102
+cloud_sql_python_connector-1.9.0.dist-info/WHEEL,sha256=bb2Ot9scclHKMOLDEHY6B2sicWOgugjFKaJsT7vwMQo,110
+cloud_sql_python_connector-1.9.0.dist-info/top_level.txt,sha256=_1QvSJIhFAGfxb79D6DhB7SUw2X6T4rwnz_LLrbcD3c,7
+cloud_sql_python_connector-1.9.0.dist-info/RECORD,,

google/cloud/sql/connector/client.py

@@ -31,13 +31,14 @@ if TYPE_CHECKING:
 
 USER_AGENT: str = f"cloud-sql-python-connector/{version}"
 API_VERSION: str = "v1beta4"
+DEFAULT_SERVICE_ENDPOINT: str = "https://sqladmin.googleapis.com"
 
 logger = logging.getLogger(name=__name__)
 
 
 def _format_user_agent(driver: Optional[str], custom: Optional[str]) -> str:
     agent = f"{USER_AGENT}+{driver}" if driver else USER_AGENT
-    if custom:
+    if custom and isinstance(custom, str):
         agent = f"{agent} {custom}"
     return agent
 
@@ -45,7 +46,7 @@ def _format_user_agent(driver: Optional[str], custom: Optional[str]) -> str:
 class CloudSQLClient:
     def __init__(
         self,
-        sqladmin_api_endpoint: str,
+        sqladmin_api_endpoint: Optional[str],
         quota_project: Optional[str],
         credentials: Credentials,
         client: Optional[aiohttp.ClientSession] = None,
@@ -81,7 +82,10 @@ class CloudSQLClient:
 
         self._client = client if client else aiohttp.ClientSession(headers=headers)
         self._credentials = credentials
-        self._sqladmin_api_endpoint = sqladmin_api_endpoint
+        if sqladmin_api_endpoint is None:
+            self._sqladmin_api_endpoint = DEFAULT_SERVICE_ENDPOINT
+        else:
+            self._sqladmin_api_endpoint = sqladmin_api_endpoint
         self._user_agent = user_agent
 
     async def _get_metadata(

google/cloud/sql/connector/connector.py

@@ -43,47 +43,13 @@ from google.cloud.sql.connector.utils import generate_keys
 logger = logging.getLogger(name=__name__)
 
 ASYNC_DRIVERS = ["asyncpg"]
+_DEFAULT_SCHEME = "https://"
+_DEFAULT_UNIVERSE_DOMAIN = "googleapis.com"
+_SQLADMIN_HOST_TEMPLATE = "sqladmin.{universe_domain}"
 
 
 class Connector:
-    """A class to configure and create connections to Cloud SQL instances.
-
-    :type ip_type: str | IPTypes
-    :param ip_type
-        The IP type used to connect. IP types can be either IPTypes.PUBLIC
-        ("PUBLIC"), IPTypes.PRIVATE ("PRIVATE"), or IPTypes.PSC ("PSC").
-
-    :type enable_iam_auth: bool
-    :param enable_iam_auth
-        Enables automatic IAM database authentication for Postgres or MySQL
-        instances.
-
-    :type timeout: int
-    :param timeout
-        The time limit for a connection before raising a TimeoutError.
-
-    :type credentials: google.auth.credentials.Credentials
-    :param credentials
-        Credentials object used to authenticate connections to Cloud SQL server.
-        If not specified, Application Default Credentials are used.
-
-    :type quota_project: str
-    :param quota_project
-        The Project ID for an existing Google Cloud project. The project specified
-        is used for quota and billing purposes. If not specified, defaults to
-        project sourced from environment.
-
-    :type loop: asyncio.AbstractEventLoop
-    :param loop
-        Event loop to run asyncio tasks, if not specified, defaults to
-        creating new event loop on background thread.
-
-    :type sqladmin_api_endpoint: str
-    :param sqladmin_api_endpoint:
-        Base URL to use when calling the Cloud SQL Admin API endpoint.
-        Defaults to "https://sqladmin.googleapis.com", this argument should
-        only be used in development.
-    """
+    """Configure and create secure connections to Cloud SQL."""
 
     def __init__(
         self,
@@ -93,9 +59,46 @@ class Connector:
         credentials: Optional[Credentials] = None,
         loop: Optional[asyncio.AbstractEventLoop] = None,
         quota_project: Optional[str] = None,
-        sqladmin_api_endpoint: str = "https://sqladmin.googleapis.com",
+        sqladmin_api_endpoint: Optional[str] = None,
         user_agent: Optional[str] = None,
+        universe_domain: Optional[str] = None,
     ) -> None:
+        """Initializes a Connector instance.
+
+        Args:
+            ip_type (str | IPTypes): The default IP address type used to connect to
+                Cloud SQL instances. Can be one of the following:
+                IPTypes.PUBLIC ("PUBLIC"), IPTypes.PRIVATE ("PRIVATE"), or
+                IPTypes.PSC ("PSC"). Default: IPTypes.PUBLIC
+
+            enable_iam_auth (bool): Enables automatic IAM database authentication
+                (Postgres and MySQL) as the default authentication method for all
+                connections.
+
+            timeout (int): The default time limit in seconds for a connection before
+                raising a TimeoutError.
+
+            credentials (google.auth.credentials.Credentials): A credentials object
+                created from the google-auth Python library to be used.
+                If not specified, Application Default Credentials (ADC) are used.
+
+            quota_project (str): The Project ID for an existing Google Cloud
+                project. The project specified is used for quota and billing
+                purposes. If not specified, defaults to project sourced from
+                environment.
+
+            loop (asyncio.AbstractEventLoop): Event loop to run asyncio tasks, if
+                not specified, defaults to creating new event loop on background
+                thread.
+
+            sqladmin_api_endpoint (str): Base URL to use when calling the Cloud SQL
+                Admin API endpoint. Defaults to "https://sqladmin.googleapis.com",
+                this argument should only be used in development.
+
+            universe_domain (str): The universe domain for Cloud SQL API calls.
+                Default: "googleapis.com".
+
+        """
         # if event loop is given, use for background tasks
         if loop:
             self._loop: asyncio.AbstractEventLoop = loop
@@ -131,38 +134,65 @@ class Connector:
         self._timeout = timeout
         self._enable_iam_auth = enable_iam_auth
         self._quota_project = quota_project
-        self._sqladmin_api_endpoint = sqladmin_api_endpoint
         self._user_agent = user_agent
         # if ip_type is str, convert to IPTypes enum
         if isinstance(ip_type, str):
             ip_type = IPTypes._from_str(ip_type)
         self._ip_type = ip_type
+        self._universe_domain = universe_domain
+        # construct service endpoint for Cloud SQL Admin API calls
+        if not sqladmin_api_endpoint:
+            self._sqladmin_api_endpoint = (
+                _DEFAULT_SCHEME
+                + _SQLADMIN_HOST_TEMPLATE.format(universe_domain=self.universe_domain)
+            )
+        # otherwise if endpoint override is passed in use it
+        else:
+            self._sqladmin_api_endpoint = sqladmin_api_endpoint
+
+        # validate that the universe domain of the credentials matches the
+        # universe domain of the service endpoint
+        if self._credentials.universe_domain != self.universe_domain:
+            raise ValueError(
+                f"The configured universe domain ({self.universe_domain}) does "
+                "not match the universe domain found in the credentials "
+                f"({self._credentials.universe_domain}). If you haven't "
+                "configured the universe domain explicitly, `googleapis.com` "
+                "is the default."
+            )
+
+    @property
+    def universe_domain(self) -> str:
+        return self._universe_domain or _DEFAULT_UNIVERSE_DOMAIN
 
     def connect(
         self, instance_connection_string: str, driver: str, **kwargs: Any
     ) -> Any:
-        """Prepares and returns a database connection object and starts a
-        background task to refresh the certificates and metadata.
+        """Connect to a Cloud SQL instance.
 
-        :type instance_connection_string: str
-        :param instance_connection_string:
-            A string containing the GCP project name, region name, and instance
-            name separated by colons.
+        Prepares and returns a database connection object connected to a Cloud
+        SQL instance using SSL/TLS. Starts a background refresh to periodically
+        retrieve up-to-date ephemeral certificate and instance metadata.
 
-            Example: example-proj:example-region-us6:example-instance
+        Args:
+            instance_connection_string (str): The instance connection name of the
+                Cloud SQL instance to connect to. Takes the form of
+                "project-id:region:instance-name"
 
-        :type driver: str
-        :param: driver:
-            A string representing the driver to connect with. Supported drivers are
-            pymysql, pg8000, and pytds.
+                Example: "my-project:us-central1:my-instance"
 
-        :param kwargs:
-            Pass in any driver-specific arguments needed to connect to the Cloud
-            SQL instance.
+            driver (str): A string representing the database driver to connect
+                with. Supported drivers are pymysql, pg8000, and pytds.
 
-        :rtype: Connection
-        :returns:
+            **kwargs: Any driver-specific arguments to pass to the underlying
+                driver .connect call.
+
+        Returns:
             A DB-API connection to the specified Cloud SQL instance.
+
+        Raises:
+            ConnectorLoopError: Event loop for background refresh is running in
+                current thread. Error instead of hanging indefinitely.
         """
         try:
             # check if event loop is running in current thread
@@ -184,35 +214,37 @@ class Connector:
     async def connect_async(
         self, instance_connection_string: str, driver: str, **kwargs: Any
     ) -> Any:
-        """Prepares and returns a database connection object and starts a
-        background task to refresh the certificates and metadata.
+        """Connect asynchronously to a Cloud SQL instance.
 
-        :type instance_connection_string: str
-        :param instance_connection_string:
-            A string containing the GCP project name, region name, and instance
-            name separated by colons.
+        Prepares and returns a database connection object connected to a Cloud
+        SQL instance using SSL/TLS. Schedules a refresh to periodically
+        retrieve up-to-date ephemeral certificate and instance metadata. Async
+        version of Connector.connect.
 
-            Example: example-proj:example-region-us6:example-instance
+        Args:
+            instance_connection_string (str): The instance connection name of the
+                Cloud SQL instance to connect to. Takes the form of
+                "project-id:region:instance-name"
 
-        :type driver: str
-        :param: driver:
-            A string representing the driver to connect with. Supported drivers are
-            pymysql, pg8000, asyncpg, and pytds.
+                Example: "my-project:us-central1:my-instance"
 
-        :param kwargs:
-            Pass in any driver-specific arguments needed to connect to the Cloud
-            SQL instance.
+            driver (str): A string representing the database driver to connect
+                with. Supported drivers are pymysql, asyncpg, pg8000, and pytds.
 
-        :rtype: Connection
-        :returns:
+            **kwargs: Any driver-specific arguments to pass to the underlying
+                driver .connect call.
+
+        Returns:
             A DB-API connection to the specified Cloud SQL instance.
+
+        Raises:
+            ValueError: Connection attempt with built-in database authentication
+                and then subsequent attempt with IAM database authentication.
+            KeyError: Unsupported database driver Must be one of pymysql, asyncpg,
+                pg8000, and pytds.
+            DnsNameResolutionError: Could not resolve PSC IP address from DNS
+                host name.
         """
-        # Create an Instance object from the connection string.
-        # The Instance should verify arguments.
-        #
-        # Use the Instance to establish an SSL Connection.
-        #
-        # Return a DBAPI connection
         if self._client is None:
             # lazy init client as it has to be initialized in async context
             self._client = CloudSQLClient(
@@ -363,54 +395,53 @@ class Connector:
 
 
 async def create_async_connector(
-    ip_type: IPTypes = IPTypes.PUBLIC,
+    ip_type: str | IPTypes = IPTypes.PUBLIC,
     enable_iam_auth: bool = False,
     timeout: int = 30,
     credentials: Optional[Credentials] = None,
     loop: Optional[asyncio.AbstractEventLoop] = None,
     quota_project: Optional[str] = None,
-    sqladmin_api_endpoint: str = "https://sqladmin.googleapis.com",
+    sqladmin_api_endpoint: Optional[str] = None,
     user_agent: Optional[str] = None,
+    universe_domain: Optional[str] = None,
 ) -> Connector:
-    """
-     Create Connector object for asyncio connections that can auto-detect
-     and use current thread's running event loop.
-
-    :type ip_type: IPTypes
-     :param ip_type
-         The IP type (public or private)  used to connect. IP types
-         can be either IPTypes.PUBLIC or IPTypes.PRIVATE.
-
-     :type enable_iam_auth: bool
-     :param enable_iam_auth
-         Enables automatic IAM database authentication for Postgres or MySQL
-         instances.
-
-     :type timeout: int
-     :param timeout
-         The time limit for a connection before raising a TimeoutError.
-
-     :type credentials: google.auth.credentials.Credentials
-     :param credentials
-         Credentials object used to authenticate connections to Cloud SQL server.
-         If not specified, Application Default Credentials are used.
-
-     :type quota_project: str
-     :param quota_project
-         The Project ID for an existing Google Cloud project. The project specified
-         is used for quota and billing purposes. If not specified, defaults to
-         project sourced from environment.
-
-     :type loop: asyncio.AbstractEventLoop
-     :param loop
-         Event loop to run asyncio tasks, if not specified, defaults to
-         creating new event loop on background thread.
-
-     :type sqladmin_api_endpoint: str
-     :param sqladmin_api_endpoint:
-         Base URL to use when calling the Cloud SQL Admin API endpoint.
-         Defaults to "https://sqladmin.googleapis.com", this argument should
-         only be used in development.
+    """Helper function to create Connector object for asyncio connections.
+
+    Force use of Connector in an asyncio context. Auto-detect and use current
+    thread's running event loop.
+
+    Args:
+        ip_type (str | IPTypes): The default IP address type used to connect to
+            Cloud SQL instances. Can be one of the following:
+            IPTypes.PUBLIC ("PUBLIC"), IPTypes.PRIVATE ("PRIVATE"), or
+            IPTypes.PSC ("PSC"). Default: IPTypes.PUBLIC
+
+        enable_iam_auth (bool): Enables automatic IAM database authentication
+            (Postgres and MySQL) as the default authentication method for all
+            connections.
+
+        timeout (int): The default time limit in seconds for a connection before
+            raising a TimeoutError.
+
+        credentials (google.auth.credentials.Credentials): A credentials object
+            created from the google-auth Python library to be used.
+            If not specified, Application Default Credentials (ADC) are used.
+
+        quota_project (str): The Project ID for an existing Google Cloud
+            project. The project specified is used for quota and billing
+            purposes. If not specified, defaults to project sourced from
+            environment.
+
+        loop (asyncio.AbstractEventLoop): Event loop to run asyncio tasks, if
+            not specified, defaults to creating new event loop on background
+            thread.
+
+        sqladmin_api_endpoint (str): Base URL to use when calling the Cloud SQL
+            Admin API endpoint. Defaults to "https://sqladmin.googleapis.com",
+            this argument should only be used in development.
+
+    Returns:
+        A Connector instance configured with running event loop.
     """
     # if no loop given, automatically detect running event loop
     if loop is None:

google/cloud/sql/connector/version.py

@@ -12,4 +12,4 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-__version__ = "1.8.0"
+__version__ = "1.9.0"