cloud-sql-python-connector 1.6.0__tar.gz → 1.8.0__tar.gz

{cloud-sql-python-connector-1.6.0 → cloud-sql-python-connector-1.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: cloud-sql-python-connector
-Version: 1.6.0
+Version: 1.8.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
@@ -15,6 +15,7 @@ Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 Provides-Extra: pymysql
@@ -136,7 +137,7 @@ format "project:region:instance".
 ### How to use this Connector
 
 To connect to Cloud SQL using the connector, inititalize a `Connector`
-object and call it's `connect` method with the proper input parameters.
+object and call its `connect` method with the proper input parameters.
 
 The `Connector` itself creates connection objects by calling its `connect` method but does not manage database connection pooling. For this reason, it is recommended to use the connector alongside a library that can create connection pools, such as [SQLAlchemy](https://www.sqlalchemy.org/). This will allow for connections to remain open and be reused, reducing connection overhead and the number of connections needed.
 
@@ -192,7 +193,7 @@ with pool.connect() as db_conn:
         print(row)
 ```
 
-To close the `Connector` object's background resources, call it's `close()` method as follows:
+To close the `Connector` object's background resources, call its `close()` method as follows:
 
 ```python
 connector.close()
@@ -213,7 +214,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
@@ -286,18 +287,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 ...
 )
 ```
@@ -358,7 +357,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"
 )
 ```
 
@@ -383,7 +382,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
@@ -397,7 +396,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
 
@@ -432,7 +431,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:
@@ -444,7 +443,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.6.0 → cloud-sql-python-connector-1.8.0}/README.md

@@ -111,7 +111,7 @@ format "project:region:instance".
 ### How to use this Connector
 
 To connect to Cloud SQL using the connector, inititalize a `Connector`
-object and call it's `connect` method with the proper input parameters.
+object and call its `connect` method with the proper input parameters.
 
 The `Connector` itself creates connection objects by calling its `connect` method but does not manage database connection pooling. For this reason, it is recommended to use the connector alongside a library that can create connection pools, such as [SQLAlchemy](https://www.sqlalchemy.org/). This will allow for connections to remain open and be reused, reducing connection overhead and the number of connections needed.
 
@@ -167,7 +167,7 @@ with pool.connect() as db_conn:
         print(row)
 ```
 
-To close the `Connector` object's background resources, call it's `close()` method as follows:
+To close the `Connector` object's background resources, call its `close()` method as follows:
 
 ```python
 connector.close()
@@ -188,7 +188,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
@@ -261,18 +261,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 ...
 )
 ```
@@ -333,7 +331,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"
 )
 ```
 
@@ -358,7 +356,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
@@ -372,7 +370,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
 
@@ -407,7 +405,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:
@@ -419,7 +417,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.6.0 → cloud-sql-python-connector-1.8.0}/cloud_sql_python_connector.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: cloud-sql-python-connector
-Version: 1.6.0
+Version: 1.8.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
@@ -15,6 +15,7 @@ Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 Provides-Extra: pymysql
@@ -136,7 +137,7 @@ format "project:region:instance".
 ### How to use this Connector
 
 To connect to Cloud SQL using the connector, inititalize a `Connector`
-object and call it's `connect` method with the proper input parameters.
+object and call its `connect` method with the proper input parameters.
 
 The `Connector` itself creates connection objects by calling its `connect` method but does not manage database connection pooling. For this reason, it is recommended to use the connector alongside a library that can create connection pools, such as [SQLAlchemy](https://www.sqlalchemy.org/). This will allow for connections to remain open and be reused, reducing connection overhead and the number of connections needed.
 
@@ -192,7 +193,7 @@ with pool.connect() as db_conn:
         print(row)
 ```
 
-To close the `Connector` object's background resources, call it's `close()` method as follows:
+To close the `Connector` object's background resources, call its `close()` method as follows:
 
 ```python
 connector.close()
@@ -213,7 +214,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
@@ -286,18 +287,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 ...
 )
 ```
@@ -358,7 +357,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"
 )
 ```
 
@@ -383,7 +382,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
@@ -397,7 +396,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
 
@@ -432,7 +431,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:
@@ -444,7 +443,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.6.0 → cloud-sql-python-connector-1.8.0}/cloud_sql_python_connector.egg-info/SOURCES.txt

@@ -10,6 +10,7 @@ cloud_sql_python_connector.egg-info/requires.txt
 cloud_sql_python_connector.egg-info/top_level.txt
 google/cloud/sql/connector/__init__.py
 google/cloud/sql/connector/asyncpg.py
+google/cloud/sql/connector/client.py
 google/cloud/sql/connector/connector.py
 google/cloud/sql/connector/exceptions.py
 google/cloud/sql/connector/instance.py

{cloud-sql-python-connector-1.6.0 → cloud-sql-python-connector-1.8.0}/cloud_sql_python_connector.egg-info/requires.txt

@@ -1,5 +1,5 @@
 aiohttp
-cryptography>=38.0.3
+cryptography>=42.0.0
 Requests
 google-auth
 
@@ -7,10 +7,10 @@ google-auth
 asyncpg>=0.29.0
 
 [pg8000]
-pg8000>=1.30.4
+pg8000>=1.30.5
 
 [pymysql]
 PyMySQL>=1.1.0
 
 [pytds]
-python-tds>=1.13.0
+python-tds>=1.15.0

cloud-sql-python-connector-1.8.0/google/cloud/sql/connector/client.py

@@ -0,0 +1,221 @@
+# Copyright 2024 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import annotations
+
+import datetime
+import logging
+from typing import Any, Dict, Optional, Tuple, TYPE_CHECKING
+
+import aiohttp
+from cryptography.hazmat.backends import default_backend
+from cryptography.x509 import load_pem_x509_certificate
+import google.auth.transport.requests
+
+from google.cloud.sql.connector.refresh_utils import _downscope_credentials
+from google.cloud.sql.connector.version import __version__ as version
+
+if TYPE_CHECKING:
+    from google.auth.credentials import Credentials
+
+USER_AGENT: str = f"cloud-sql-python-connector/{version}"
+API_VERSION: str = "v1beta4"
+
+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:
+        agent = f"{agent} {custom}"
+    return agent
+
+
+class CloudSQLClient:
+    def __init__(
+        self,
+        sqladmin_api_endpoint: str,
+        quota_project: Optional[str],
+        credentials: Credentials,
+        client: Optional[aiohttp.ClientSession] = None,
+        driver: Optional[str] = None,
+        user_agent: Optional[str] = None,
+    ) -> None:
+        """
+        Establish the client to be used for Cloud SQL Admin API requests.
+
+        Args:
+            sqladmin_api_endpoint (str): Base URL to use when calling
+                the Cloud SQL Admin API endpoints.
+            quota_project (str): The Project ID for an existing Google Cloud
+                project. The project specified is used for quota and
+                billing purposes.
+            credentials (google.auth.credentials.Credentials):
+                A credentials object created from the google-auth Python library.
+                Must have the Cloud SQL Admin scopes. For more info check out
+                https://google-auth.readthedocs.io/en/latest/.
+            client (aiohttp.ClientSession): Async client used to make requests to
+                Cloud SQL Admin APIs.
+                Optional, defaults to None and creates new client.
+            driver (str): Database driver to be used by the client.
+        """
+        user_agent = _format_user_agent(driver, user_agent)
+        headers = {
+            "x-goog-api-client": user_agent,
+            "User-Agent": user_agent,
+            "Content-Type": "application/json",
+        }
+        if quota_project:
+            headers["x-goog-user-project"] = quota_project
+
+        self._client = client if client else aiohttp.ClientSession(headers=headers)
+        self._credentials = credentials
+        self._sqladmin_api_endpoint = sqladmin_api_endpoint
+        self._user_agent = user_agent
+
+    async def _get_metadata(
+        self,
+        project: str,
+        region: str,
+        instance: str,
+    ) -> Dict[str, Any]:
+        """Requests metadata from the Cloud SQL Instance
+        and returns a dictionary containing the IP addresses and certificate
+        authority of the Cloud SQL Instance.
+
+        :type project: str
+        :param project:
+            A string representing the name of the project.
+
+        :type region: str
+        :param region : A string representing the name of the region.
+
+        :type instance: str
+        :param instance: A string representing the name of the instance.
+
+        :rtype: Dict[str: Union[Dict, str]]
+        :returns: Returns a dictionary containing a dictionary of all IP
+            addresses and their type and a string representing the
+            certificate authority.
+        """
+        if not self._credentials.valid:
+            request = google.auth.transport.requests.Request()
+            self._credentials.refresh(request)
+
+        headers = {
+            "Authorization": f"Bearer {self._credentials.token}",
+        }
+
+        url = f"{self._sqladmin_api_endpoint}/sql/{API_VERSION}/projects/{project}/instances/{instance}/connectSettings"
+
+        logger.debug(f"['{instance}']: Requesting metadata")
+
+        resp = await self._client.get(url, headers=headers, raise_for_status=True)
+        ret_dict = await resp.json()
+
+        if ret_dict["region"] != region:
+            raise ValueError(
+                f'[{project}:{region}:{instance}]: Provided region was mismatched - got region {region}, expected {ret_dict["region"]}.'
+            )
+
+        ip_addresses = (
+            {ip["type"]: ip["ipAddress"] for ip in ret_dict["ipAddresses"]}
+            if "ipAddresses" in ret_dict
+            else {}
+        )
+        if "dnsName" in ret_dict:
+            ip_addresses["PSC"] = ret_dict["dnsName"]
+
+        return {
+            "ip_addresses": ip_addresses,
+            "server_ca_cert": ret_dict["serverCaCert"]["cert"],
+            "database_version": ret_dict["databaseVersion"],
+        }
+
+    async def _get_ephemeral(
+        self,
+        project: str,
+        instance: str,
+        pub_key: str,
+        enable_iam_auth: bool = False,
+    ) -> Tuple[str, datetime.datetime]:
+        """Asynchronously requests an ephemeral certificate from the Cloud SQL Instance.
+
+        :type project: str
+        :param project : A string representing the name of the project.
+
+        :type instance: str
+        :param instance: A string representing the name of the instance.
+
+        :type pub_key:
+        :param str: A string representing PEM-encoded RSA public key.
+
+        :type enable_iam_auth: bool
+        :param enable_iam_auth
+            Enables automatic IAM database authentication for Postgres or MySQL
+            instances.
+
+        :rtype: str
+        :returns: An ephemeral certificate from the Cloud SQL instance that allows
+            authorized connections to the instance.
+        """
+
+        logger.debug(f"['{instance}']: Requesting ephemeral certificate")
+
+        if not self._credentials.valid:
+            request = google.auth.transport.requests.Request()
+            self._credentials.refresh(request)
+
+        headers = {
+            "Authorization": f"Bearer {self._credentials.token}",
+        }
+
+        url = f"{self._sqladmin_api_endpoint}/sql/{API_VERSION}/projects/{project}/instances/{instance}:generateEphemeralCert"
+
+        data = {"public_key": pub_key}
+
+        if enable_iam_auth:
+            # down-scope credentials with only IAM login scope (refreshes them too)
+            login_creds = _downscope_credentials(self._credentials)
+            data["access_token"] = login_creds.token
+
+        resp = await self._client.post(
+            url, headers=headers, json=data, raise_for_status=True
+        )
+
+        ret_dict = await resp.json()
+
+        ephemeral_cert: str = ret_dict["ephemeralCert"]["cert"]
+
+        # decode cert to read expiration
+        x509 = load_pem_x509_certificate(
+            ephemeral_cert.encode("UTF-8"), default_backend()
+        )
+        expiration = x509.not_valid_after_utc
+        # for IAM authentication OAuth2 token is embedded in cert so it
+        # must still be valid for successful connection
+        if enable_iam_auth:
+            token_expiration: datetime.datetime = login_creds.expiry
+            # google.auth library strips timezone info for backwards compatibality
+            # reasons with Python 2. Add it back to allow timezone aware datetimes.
+            # Ref: https://github.com/googleapis/google-auth-library-python/blob/49a5ff7411a2ae4d32a7d11700f9f961c55406a9/google/auth/_helpers.py#L93-L99
+            token_expiration = token_expiration.replace(tzinfo=datetime.timezone.utc)
+
+            if expiration > token_expiration:
+                expiration = token_expiration
+        return ephemeral_cert, expiration
+
+    async def close(self) -> None:
+        """Close CloudSQLClient gracefully."""
+        await self._client.close()