refactor: update to Google style docstrings (#1258)

colinchambachan · web-flow · commit e74348b3c0d9 · 2025-03-30T21:04:43.000-04:00
This PR is intended to continue refactoring the Python Connector library over to Google style docstrings.
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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"):
