diff --git a/google/cloud/sql/connector/asyncpg.py b/google/cloud/sql/connector/asyncpg.py index 47d34895f..2fbc30273 100644 --- a/google/cloud/sql/connector/asyncpg.py +++ b/google/cloud/sql/connector/asyncpg.py @@ -28,21 +28,22 @@ async def connect( ) -> "asyncpg.Connection": """Helper function to create an asyncpg DB-API connection object. - :type ip_address: str - :param ip_address: A string containing an IP address for the Cloud SQL - instance. + Args: + ip_address (str): A string containing an IP address for the Cloud SQL + instance. + ctx (ssl.SSLContext): An SSLContext object created from the Cloud SQL + server CA cert and ephemeral cert. + server CA cert and ephemeral cert. + kwargs: Keyword arguments for establishing asyncpg connection + object to Cloud SQL instance. - :type ctx: ssl.SSLContext - :param ctx: An SSLContext object created from the Cloud SQL server CA - cert and ephemeral cert. - - :type kwargs: Any - :param kwargs: Keyword arguments for establishing asyncpg connection - object to Cloud SQL instance. - - :rtype: asyncpg.Connection - :returns: An asyncpg.Connection object to a Cloud SQL instance. + Returns: + asyncpg.Connection: An asyncpg connection to the Cloud SQL + instance. + Raises: + ImportError: The asyncpg module cannot be imported. """ + try: import asyncpg except ImportError: diff --git a/google/cloud/sql/connector/client.py b/google/cloud/sql/connector/client.py index 556a01bde..11508ce17 100644 --- a/google/cloud/sql/connector/client.py +++ b/google/cloud/sql/connector/client.py @@ -59,8 +59,7 @@ def __init__( driver: Optional[str] = None, user_agent: Optional[str] = None, ) -> None: - """ - Establish the client to be used for Cloud SQL Admin API requests. + """Establishes the client to be used for Cloud SQL Admin API requests. Args: sqladmin_api_endpoint (str): Base URL to use when calling @@ -100,24 +99,22 @@ async def _get_metadata( 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. + """Requests metadata from the Cloud SQL Instance and returns a dictionary + containing the IP addresses and certificate authority of the Cloud SQL + Instance. - :type region: str - :param region : A string representing the name of the region. + Args: + project (str): A string representing the name of the project. + region (str): A string representing the name of the region. + instance (str): A string representing the name of the instance. - :type instance: str - :param instance: A string representing the name of the instance. + Returns: + A dictionary containing a dictionary of all IP addresses + and their type and a string representing the certificate authority. - :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. + Raises: + ValueError: Provided region does not match the region of the + Cloud SQL instance. """ headers = { @@ -189,23 +186,17 @@ async def _get_ephemeral( ) -> 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. + Args: + project (str): A string representing the name of the project. + instance (str): string representing the name of the instance. + pub_key (str): A string representing PEM-encoded RSA public key. + enable_iam_auth (bool): 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. + Returns: + A tuple containing an ephemeral certificate from + the Cloud SQL instance as well as a datetime object + representing the expiration time of the certificate. """ headers = { "Authorization": f"Bearer {self._credentials.token}", diff --git a/google/cloud/sql/connector/pg8000.py b/google/cloud/sql/connector/pg8000.py index baaee6615..5a43ad319 100644 --- a/google/cloud/sql/connector/pg8000.py +++ b/google/cloud/sql/connector/pg8000.py @@ -26,17 +26,19 @@ def connect( ) -> "pg8000.dbapi.Connection": """Helper function to create a pg8000 DB-API connection object. - :type ip_address: str - :param ip_address: A string containing an IP address for the Cloud SQL - instance. - - :type sock: ssl.SSLSocket - :param sock: An SSLSocket object created from the Cloud SQL server CA - cert and ephemeral cert. - - - :rtype: pg8000.dbapi.Connection - :returns: A pg8000 Connection object for the Cloud SQL instance. + Args: + ip_address (str): A string containing an IP address for the Cloud SQL + instance. + sock (ssl.SSLSocket): An SSLSocket object created from the Cloud SQL + server CA cert and ephemeral cert. + kwargs: Additional arguments to pass to the pg8000 connect method. + + Returns: + pg8000.dbapi.Connection: A pg8000 connection to the Cloud SQL + instance. + + Raises: + ImportError: The pg8000 module cannot be imported. """ try: import pg8000 diff --git a/google/cloud/sql/connector/pymysql.py b/google/cloud/sql/connector/pymysql.py index f83f7076c..e01cfed08 100644 --- a/google/cloud/sql/connector/pymysql.py +++ b/google/cloud/sql/connector/pymysql.py @@ -26,16 +26,18 @@ def connect( ) -> "pymysql.connections.Connection": """Helper function to create a pymysql DB-API connection object. - :type ip_address: str - :param ip_address: A string containing an IP address for the Cloud SQL - instance. - - :type sock: ssl.SSLSocket - :param sock: An SSLSocket object created from the Cloud SQL server CA - cert and ephemeral cert. - - :rtype: pymysql.Connection - :returns: A PyMySQL Connection object for the Cloud SQL instance. + Args: + ip_address (str): A string containing an IP address for the Cloud SQL + instance. + sock (ssl.SSLSocket): An SSLSocket object created from the Cloud SQL + server CA cert and ephemeral cert. + + Returns: + pymysql.connections.Connection: A pymysql connection to the Cloud SQL + instance. + + Raises: + ImportError: The pymysql module cannot be imported. """ try: import pymysql diff --git a/google/cloud/sql/connector/pytds.py b/google/cloud/sql/connector/pytds.py index 3128fdb6a..6cc3c0934 100644 --- a/google/cloud/sql/connector/pytds.py +++ b/google/cloud/sql/connector/pytds.py @@ -27,17 +27,18 @@ def connect(ip_address: str, sock: ssl.SSLSocket, **kwargs: Any) -> "pytds.Connection": """Helper function to create a pytds DB-API connection object. - :type ip_address: str - :param ip_address: A string containing an IP address for the Cloud SQL - instance. + Args: + ip_address (str): A string containing an IP address for the Cloud SQL + instance. + sock (ssl.SSLSocket): An SSLSocket object created from the Cloud SQL + server CA cert and ephemeral cert. - :type sock: ssl.SSLSocket - :param sock: An SSLSocket object created from the Cloud SQL server CA - cert and ephemeral cert. + Returns: + pytds.Connection: A pytds connection to the Cloud SQL + instance. - - :rtype: pytds.Connection - :returns: A pytds Connection object for the Cloud SQL instance. + Raises: + ImportError: The pytds module cannot be imported. """ try: import pytds diff --git a/google/cloud/sql/connector/rate_limiter.py b/google/cloud/sql/connector/rate_limiter.py index 38e7b94bc..be9c68c64 100644 --- a/google/cloud/sql/connector/rate_limiter.py +++ b/google/cloud/sql/connector/rate_limiter.py @@ -19,24 +19,16 @@ class AsyncRateLimiter(object): - """ - An asyncio-compatible rate limiter which uses the Token Bucket algorithm - (https://en.wikipedia.org/wiki/Token_bucket) to limit the number of function calls over a time interval using an event queue. - - :type max_capacity: int - :param: max_capacity: - The maximum capacity of tokens the bucket will store at any one time. - Default: 1 - - :type rate: float - :param: rate: - The number of tokens that should be added per second. - - :type loop: asyncio.AbstractEventLoop - :param: loop: - The event loop to use. If not provided, the default event loop will be used. - + """An asyncio-compatible rate limiter which uses the Token Bucket algorithm + (https://en.wikipedia.org/wiki/Token_bucket) to limit the number + of function calls over a time interval using an event queue. + Args: + max_capacity (int): The maximum capacity of tokens the bucket + will store at any one time. Default: 1 + rate (float): The number of tokens that should be added per second. + loop (asyncio.AbstractEventLoop): The event loop to use. + If not provided, the default event loop will be used. """ def __init__( diff --git a/google/cloud/sql/connector/refresh_utils.py b/google/cloud/sql/connector/refresh_utils.py index 173f0d2ee..a90d40536 100644 --- a/google/cloud/sql/connector/refresh_utils.py +++ b/google/cloud/sql/connector/refresh_utils.py @@ -44,8 +44,11 @@ def _seconds_until_refresh( Usually the duration will be half of the time until certificate expiration. - :rtype: int - :returns: Time in seconds to wait before performing next refresh. + Args: + expiration (datetime.datetime): The expiration time of the certificate. + + Returns: + int: Time in seconds to wait before performing next refresh. """ duration = int( @@ -81,16 +84,14 @@ def _downscope_credentials( ) -> Credentials: """Generate a down-scoped credential. - :type credentials: google.auth.credentials.Credentials - :param credentials - Credentials object used to generate down-scoped credentials. - - :type scopes: list[str] - :param scopes - List of Google scopes to include in down-scoped credentials object. + Args: + credentials (google.auth.credentials.Credentials): + Credentials object used to generate down-scoped credentials. + scopes (list[str]): List of Google scopes to + include in down-scoped credentials object. - :rtype: google.auth.credentials.Credentials - :returns: Down-scoped credentials object. + Returns: + google.auth.credentials.Credentials: Down-scoped credentials object. """ # credentials sourced from a service account or metadata are children of # Scoped class and are capable of being re-scoped diff --git a/google/cloud/sql/connector/utils.py b/google/cloud/sql/connector/utils.py index 8caa73af6..dd0aec344 100755 --- a/google/cloud/sql/connector/utils.py +++ b/google/cloud/sql/connector/utils.py @@ -79,16 +79,14 @@ async def write_to_file( def format_database_user(database_version: str, user: str) -> str: - """ - Format database `user` param for Cloud SQL automatic IAM authentication. + """Format database `user` param for Cloud SQL automatic IAM authentication. - :type database_version: str - :param database_version - Cloud SQL database version. (i.e. POSTGRES_14, MYSQL8_0, etc.) + Args: + database_version (str): Cloud SQL database version. + user (str): Database username to connect to Cloud SQL database with. - :type user: str - :param user - Database username to connect to Cloud SQL database with. + Returns: + str: Formatted database username. """ # remove suffix for Postgres service accounts if database_version.startswith("POSTGRES"):