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

{cloud_sql_python_connector-1.7.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.7.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.4) ; extra == 'pg8000'
+Requires-Dist: pg8000 (>=1.31.1) ; extra == 'pg8000'
 Provides-Extra: pymysql
 Requires-Dist: PyMySQL (>=1.1.0) ; extra == 'pymysql'
 Provides-Extra: pytds
@@ -222,7 +222,7 @@ from google.cloud.sql.connector import Connector, IPTypes
 
 # Note: all parameters below are optional
 connector = Connector(
-    ip_type=IPTypes.PUBLIC,
+    ip_type="public",  # can also be "private" or "psc"
     enable_iam_auth=False,
     timeout=30,
     credentials=custom_creds # google.auth.credentials.Credentials
@@ -295,18 +295,16 @@ using both public and private IP addresses, as well as
 with, set the `ip_type` keyword argument when initializing a `Connector()` or when
 calling `connector.connect()`.
 
-Possible values for `ip_type` are `IPTypes.PUBLIC` (default value),
-`IPTypes.PRIVATE`, and `IPTypes.PSC`.
+Possible values for `ip_type` are `"public"` (default value),
+`"private"`, and `"psc"`.
 
 Example:
 
 ```python
-from google.cloud.sql.connector import IPTypes
-
 conn = connector.connect(
     "project:region:instance",
     "pymysql",
-    ip_type=IPTypes.PRIVATE # use private IP
+    ip_type="private"  # use private IP
 ... insert other kwargs ...
 )
 ```
@@ -367,7 +365,7 @@ conn = connector.connect(
     db="my-db-name",
     active_directory_auth=True,
     server_name="private.[instance].[location].[project].cloudsql.[domain]",
-    ip_type=IPTypes.PRIVATE
+    ip_type="private"
 )
 ```
 
@@ -392,7 +390,7 @@ your web application through the following:
 ```python
 from flask import Flask
 from flask_sqlalchemy import SQLAlchemy
-from google.cloud.sql.connector import Connector, IPTypes
+from google.cloud.sql.connector import Connector
 
 
 # initialize Python Connector object
@@ -406,7 +404,7 @@ def getconn():
         user="my-user",
         password="my-password",
         db="my-database",
-        ip_type= IPTypes.PUBLIC  # IPTypes.PRIVATE for private IP
+        ip_type="public"  # "private" for private IP
     )
     return conn
 
@@ -441,7 +439,7 @@ from sqlalchemy import create_engine
 from sqlalchemy.engine import Engine
 from sqlalchemy.ext.declarative import declarative_base
 from sqlalchemy.orm import sessionmaker
-from google.cloud.sql.connector import Connector, IPTypes
+from google.cloud.sql.connector import Connector
 
 # helper function to return SQLAlchemy connection pool
 def init_connection_pool(connector: Connector) -> Engine:
@@ -453,7 +451,7 @@ def init_connection_pool(connector: Connector) -> Engine:
             user="my-user",
             password="my-password",
             db="my-database",
-            ip_type= IPTypes.PUBLIC  # IPTypes.PRIVATE for private IP
+            ip_type="public"  # "private" for private IP
         )
         return conn
 

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

@@ -1,9 +1,9 @@
 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=Us4Yw8B6bTvNHn8F89O8tj5b6RqMnW5XR8pSbPMnOhc,15636
+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=ZLOyMoqHm7dehgvTkO4ul9DORHxwePt78O6mYsnR0Z4,14432
+google/cloud/sql/connector/instance.py,sha256=G7-SCqsLjZiOYZ-Ds2RIErs6oaT0ewnAN683fs7EebI,14920
 google/cloud/sql/connector/pg8000.py,sha256=EZuO7XgCkG_Y79NQlh3Vv8Ff2w85BFJyFVO237hx1GM,1814
 google/cloud/sql/connector/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 google/cloud/sql/connector/pymysql.py,sha256=wldUgwDPlPa8Nj5F3JaipuP8hJyvzlgOAJbRnOoaB1U,2105
@@ -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=5_sx8G8Z2yXRHtm-eIsT3EeQQ6YXb_CPOYOw5xgs-AM,597
-cloud_sql_python_connector-1.7.0.dist-info/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
-cloud_sql_python_connector-1.7.0.dist-info/METADATA,sha256=YKaK1VB25XvtfIwC0PqsBfxFP4YSYjfDdZuWhcXyEiQ,24195
-cloud_sql_python_connector-1.7.0.dist-info/WHEEL,sha256=bb2Ot9scclHKMOLDEHY6B2sicWOgugjFKaJsT7vwMQo,110
-cloud_sql_python_connector-1.7.0.dist-info/top_level.txt,sha256=_1QvSJIhFAGfxb79D6DhB7SUw2X6T4rwnz_LLrbcD3c,7
-cloud_sql_python_connector-1.7.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,59 +43,62 @@ 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: 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.
-    """
+    """Configure and create secure connections to Cloud SQL."""
 
     def __init__(
         self,
-        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,
     ) -> 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
@@ -130,36 +133,66 @@ class Connector:
         # set default params for connections
         self._timeout = timeout
         self._enable_iam_auth = enable_iam_auth
-        self._ip_type = ip_type
         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.
+
+        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.
 
-        :type instance_connection_string: str
-        :param instance_connection_string:
-            A string containing the GCP project name, region name, and instance
-            name separated by colons.
+        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"
 
-            Example: example-proj:example-region-us6:example-instance
+                Example: "my-project:us-central1:my-instance"
 
-        :type driver: str
-        :param: driver:
-            A string representing the driver to connect with. Supported drivers are
-            pymysql, pg8000, and pytds.
+            driver (str): A string representing the database driver to connect
+                with. Supported drivers are pymysql, pg8000, and pytds.
 
-        :param kwargs:
-            Pass in any driver-specific arguments needed to connect to the Cloud
-            SQL instance.
+            **kwargs: Any driver-specific arguments to pass to the underlying
+                driver .connect call.
 
-        :rtype: Connection
-        :returns:
+        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
@@ -181,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.
+
+        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.
 
-        :type instance_connection_string: str
-        :param instance_connection_string:
-            A string containing the GCP project name, region name, and instance
-            name separated by colons.
+        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"
 
-            Example: example-proj:example-region-us6:example-instance
+                Example: "my-project:us-central1:my-instance"
 
-        :type driver: str
-        :param: driver:
-            A string representing the driver to connect with. Supported drivers are
-            pymysql, pg8000, asyncpg, and pytds.
+            driver (str): A string representing the database driver to connect
+                with. Supported drivers are pymysql, asyncpg, pg8000, and pytds.
 
-        :param kwargs:
-            Pass in any driver-specific arguments needed to connect to the Cloud
-            SQL instance.
+            **kwargs: Any driver-specific arguments to pass to the underlying
+                driver .connect call.
 
-        :rtype: Connection
-        :returns:
+        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(
@@ -252,6 +287,9 @@ class Connector:
             raise KeyError(f"Driver '{driver}' is not supported.")
 
         ip_type = kwargs.pop("ip_type", self._ip_type)
+        # if ip_type is str, convert to IPTypes enum
+        if isinstance(ip_type, str):
+            ip_type = IPTypes._from_str(ip_type)
         kwargs["timeout"] = kwargs.get("timeout", self._timeout)
 
         # Host and ssl options come from the certificates and metadata, so we don't
@@ -357,41 +395,64 @@ 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: 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 loop: asyncio.AbstractEventLoop
-    :param loop
-        Event loop to run asyncio tasks, if not specified, defaults
-        to current thread's running event loop.
+    """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:
         loop = asyncio.get_running_loop()
-    return Connector(ip_type, enable_iam_auth, timeout, credentials, loop)
+    return Connector(
+        ip_type=ip_type,
+        enable_iam_auth=enable_iam_auth,
+        timeout=timeout,
+        credentials=credentials,
+        loop=loop,
+        quota_project=quota_project,
+        sqladmin_api_endpoint=sqladmin_api_endpoint,
+        user_agent=user_agent,
+    )

google/cloud/sql/connector/instance.py

@@ -64,6 +64,20 @@ class IPTypes(Enum):
     PRIVATE: str = "PRIVATE"
     PSC: str = "PSC"
 
+    @classmethod
+    def _missing_(cls, value: object) -> None:
+        raise ValueError(
+            f"Incorrect value for ip_type, got '{value}'. Want one of: "
+            f"{', '.join([repr(m.value) for m in cls])}, 'PUBLIC'."
+        )
+
+    @classmethod
+    def _from_str(cls, ip_type_str: str) -> IPTypes:
+        """Convert IP type from a str into IPTypes."""
+        if ip_type_str.upper() == "PUBLIC":
+            ip_type_str = "PRIMARY"
+        return cls(ip_type_str.upper())
+
 
 class ConnectionInfo:
     ip_addrs: Dict[str, Any]

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.7.0"
+__version__ = "1.9.0"