Skip to content

Commit e74348b

Browse files
colinchambachancolinchambachan
authored
refactor: update to Google style docstrings (GoogleCloudPlatform#1258)
This PR is intended to continue refactoring the Python Connector library over to Google style docstrings.
1 parent 6ecf894 commit e74348b

File tree

8 files changed

+100
-112
lines changed

8 files changed

+100
-112
lines changed

‎google/cloud/sql/connector/asyncpg.py‎

Lines changed: 14 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -28,21 +28,22 @@ async def connect(
2828
) -> "asyncpg.Connection":
2929
"""Helper function to create an asyncpg DB-API connection object.
3030
31-
:type ip_address: str
32-
:param ip_address: A string containing an IP address for the Cloud SQL
33-
instance.
31+
Args:
32+
ip_address (str): A string containing an IP address for the Cloud SQL
33+
instance.
34+
ctx (ssl.SSLContext): An SSLContext object created from the Cloud SQL
35+
server CA cert and ephemeral cert.
36+
server CA cert and ephemeral cert.
37+
kwargs: Keyword arguments for establishing asyncpg connection
38+
object to Cloud SQL instance.
3439
35-
:type ctx: ssl.SSLContext
36-
:param ctx: An SSLContext object created from the Cloud SQL server CA
37-
cert and ephemeral cert.
38-
39-
:type kwargs: Any
40-
:param kwargs: Keyword arguments for establishing asyncpg connection
41-
object to Cloud SQL instance.
42-
43-
:rtype: asyncpg.Connection
44-
:returns: An asyncpg.Connection object to a Cloud SQL instance.
40+
Returns:
41+
asyncpg.Connection: An asyncpg connection to the Cloud SQL
42+
instance.
43+
Raises:
44+
ImportError: The asyncpg module cannot be imported.
4545
"""
46+
4647
try:
4748
import asyncpg
4849
except ImportError:

‎google/cloud/sql/connector/client.py‎

Lines changed: 24 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -59,8 +59,7 @@ def __init__(
5959
driver: Optional[str] = None,
6060
user_agent: Optional[str] = None,
6161
) -> None:
62-
"""
63-
Establish the client to be used for Cloud SQL Admin API requests.
62+
"""Establishes the client to be used for Cloud SQL Admin API requests.
6463
6564
Args:
6665
sqladmin_api_endpoint (str): Base URL to use when calling
@@ -100,24 +99,22 @@ async def _get_metadata(
10099
region: str,
101100
instance: str,
102101
) -> dict[str, Any]:
103-
"""Requests metadata from the Cloud SQL Instance
104-
and returns a dictionary containing the IP addresses and certificate
105-
authority of the Cloud SQL Instance.
106-
107-
:type project: str
108-
:param project:
109-
A string representing the name of the project.
102+
"""Requests metadata from the Cloud SQL Instance and returns a dictionary
103+
containing the IP addresses and certificate authority of the Cloud SQL
104+
Instance.
110105
111-
:type region: str
112-
:param region : A string representing the name of the region.
106+
Args:
107+
project (str): A string representing the name of the project.
108+
region (str): A string representing the name of the region.
109+
instance (str): A string representing the name of the instance.
113110
114-
:type instance: str
115-
:param instance: A string representing the name of the instance.
111+
Returns:
112+
A dictionary containing a dictionary of all IP addresses
113+
and their type and a string representing the certificate authority.
116114
117-
:rtype: dict[str: Union[dict, str]]
118-
:returns: Returns a dictionary containing a dictionary of all IP
119-
addresses and their type and a string representing the
120-
certificate authority.
115+
Raises:
116+
ValueError: Provided region does not match the region of the
117+
Cloud SQL instance.
121118
"""
122119

123120
headers = {
@@ -189,23 +186,17 @@ async def _get_ephemeral(
189186
) -> tuple[str, datetime.datetime]:
190187
"""Asynchronously requests an ephemeral certificate from the Cloud SQL Instance.
191188
192-
:type project: str
193-
:param project : A string representing the name of the project.
194-
195-
:type instance: str
196-
:param instance: A string representing the name of the instance.
197-
198-
:type pub_key:
199-
:param str: A string representing PEM-encoded RSA public key.
200-
201-
:type enable_iam_auth: bool
202-
:param enable_iam_auth
203-
Enables automatic IAM database authentication for Postgres or MySQL
204-
instances.
189+
Args:
190+
project (str): A string representing the name of the project.
191+
instance (str): string representing the name of the instance.
192+
pub_key (str): A string representing PEM-encoded RSA public key.
193+
enable_iam_auth (bool): Enables automatic IAM database
194+
authentication for Postgres or MySQL instances.
205195
206-
:rtype: str
207-
:returns: An ephemeral certificate from the Cloud SQL instance that allows
208-
authorized connections to the instance.
196+
Returns:
197+
A tuple containing an ephemeral certificate from
198+
the Cloud SQL instance as well as a datetime object
199+
representing the expiration time of the certificate.
209200
"""
210201
headers = {
211202
"Authorization": f"Bearer {self._credentials.token}",

‎google/cloud/sql/connector/pg8000.py‎

Lines changed: 13 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -26,17 +26,19 @@ def connect(
2626
) -> "pg8000.dbapi.Connection":
2727
"""Helper function to create a pg8000 DB-API connection object.
2828
29-
:type ip_address: str
30-
:param ip_address: A string containing an IP address for the Cloud SQL
31-
instance.
32-
33-
:type sock: ssl.SSLSocket
34-
:param sock: An SSLSocket object created from the Cloud SQL server CA
35-
cert and ephemeral cert.
36-
37-
38-
:rtype: pg8000.dbapi.Connection
39-
:returns: A pg8000 Connection object for the Cloud SQL instance.
29+
Args:
30+
ip_address (str): A string containing an IP address for the Cloud SQL
31+
instance.
32+
sock (ssl.SSLSocket): An SSLSocket object created from the Cloud SQL
33+
server CA cert and ephemeral cert.
34+
kwargs: Additional arguments to pass to the pg8000 connect method.
35+
36+
Returns:
37+
pg8000.dbapi.Connection: A pg8000 connection to the Cloud SQL
38+
instance.
39+
40+
Raises:
41+
ImportError: The pg8000 module cannot be imported.
4042
"""
4143
try:
4244
import pg8000

‎google/cloud/sql/connector/pymysql.py‎

Lines changed: 12 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -26,16 +26,18 @@ def connect(
2626
) -> "pymysql.connections.Connection":
2727
"""Helper function to create a pymysql DB-API connection object.
2828
29-
:type ip_address: str
30-
:param ip_address: A string containing an IP address for the Cloud SQL
31-
instance.
32-
33-
:type sock: ssl.SSLSocket
34-
:param sock: An SSLSocket object created from the Cloud SQL server CA
35-
cert and ephemeral cert.
36-
37-
:rtype: pymysql.Connection
38-
:returns: A PyMySQL Connection object for the Cloud SQL instance.
29+
Args:
30+
ip_address (str): A string containing an IP address for the Cloud SQL
31+
instance.
32+
sock (ssl.SSLSocket): An SSLSocket object created from the Cloud SQL
33+
server CA cert and ephemeral cert.
34+
35+
Returns:
36+
pymysql.connections.Connection: A pymysql connection to the Cloud SQL
37+
instance.
38+
39+
Raises:
40+
ImportError: The pymysql module cannot be imported.
3941
"""
4042
try:
4143
import pymysql

‎google/cloud/sql/connector/pytds.py‎

Lines changed: 10 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -27,17 +27,18 @@
2727
def connect(ip_address: str, sock: ssl.SSLSocket, **kwargs: Any) -> "pytds.Connection":
2828
"""Helper function to create a pytds DB-API connection object.
2929
30-
:type ip_address: str
31-
:param ip_address: A string containing an IP address for the Cloud SQL
32-
instance.
30+
Args:
31+
ip_address (str): A string containing an IP address for the Cloud SQL
32+
instance.
33+
sock (ssl.SSLSocket): An SSLSocket object created from the Cloud SQL
34+
server CA cert and ephemeral cert.
3335
34-
:type sock: ssl.SSLSocket
35-
:param sock: An SSLSocket object created from the Cloud SQL server CA
36-
cert and ephemeral cert.
36+
Returns:
37+
pytds.Connection: A pytds connection to the Cloud SQL
38+
instance.
3739
38-
39-
:rtype: pytds.Connection
40-
:returns: A pytds Connection object for the Cloud SQL instance.
40+
Raises:
41+
ImportError: The pytds module cannot be imported.
4142
"""
4243
try:
4344
import pytds

‎google/cloud/sql/connector/rate_limiter.py‎

Lines changed: 9 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -19,24 +19,16 @@
1919

2020

2121
class AsyncRateLimiter(object):
22-
"""
23-
An asyncio-compatible rate limiter which uses the Token Bucket algorithm
24-
(https://en.wikipedia.org/wiki/Token_bucket) to limit the number of function calls over a time interval using an event queue.
25-
26-
:type max_capacity: int
27-
:param: max_capacity:
28-
The maximum capacity of tokens the bucket will store at any one time.
29-
Default: 1
30-
31-
:type rate: float
32-
:param: rate:
33-
The number of tokens that should be added per second.
34-
35-
:type loop: asyncio.AbstractEventLoop
36-
:param: loop:
37-
The event loop to use. If not provided, the default event loop will be used.
38-
22+
"""An asyncio-compatible rate limiter which uses the Token Bucket algorithm
23+
(https://en.wikipedia.org/wiki/Token_bucket) to limit the number
24+
of function calls over a time interval using an event queue.
3925
26+
Args:
27+
max_capacity (int): The maximum capacity of tokens the bucket
28+
will store at any one time. Default: 1
29+
rate (float): The number of tokens that should be added per second.
30+
loop (asyncio.AbstractEventLoop): The event loop to use.
31+
If not provided, the default event loop will be used.
4032
"""
4133

4234
def __init__(

‎google/cloud/sql/connector/refresh_utils.py‎

Lines changed: 12 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -44,8 +44,11 @@ def _seconds_until_refresh(
4444
Usually the duration will be half of the time until certificate
4545
expiration.
4646
47-
:rtype: int
48-
:returns: Time in seconds to wait before performing next refresh.
47+
Args:
48+
expiration (datetime.datetime): The expiration time of the certificate.
49+
50+
Returns:
51+
int: Time in seconds to wait before performing next refresh.
4952
"""
5053

5154
duration = int(
@@ -81,16 +84,14 @@ def _downscope_credentials(
8184
) -> Credentials:
8285
"""Generate a down-scoped credential.
8386
84-
:type credentials: google.auth.credentials.Credentials
85-
:param credentials
86-
Credentials object used to generate down-scoped credentials.
87-
88-
:type scopes: list[str]
89-
:param scopes
90-
List of Google scopes to include in down-scoped credentials object.
87+
Args:
88+
credentials (google.auth.credentials.Credentials):
89+
Credentials object used to generate down-scoped credentials.
90+
scopes (list[str]): List of Google scopes to
91+
include in down-scoped credentials object.
9192
92-
:rtype: google.auth.credentials.Credentials
93-
:returns: Down-scoped credentials object.
93+
Returns:
94+
google.auth.credentials.Credentials: Down-scoped credentials object.
9495
"""
9596
# credentials sourced from a service account or metadata are children of
9697
# Scoped class and are capable of being re-scoped

‎google/cloud/sql/connector/utils.py‎

Lines changed: 6 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -79,16 +79,14 @@ async def write_to_file(
7979

8080

8181
def format_database_user(database_version: str, user: str) -> str:
82-
"""
83-
Format database `user` param for Cloud SQL automatic IAM authentication.
82+
"""Format database `user` param for Cloud SQL automatic IAM authentication.
8483
85-
:type database_version: str
86-
:param database_version
87-
Cloud SQL database version. (i.e. POSTGRES_14, MYSQL8_0, etc.)
84+
Args:
85+
database_version (str): Cloud SQL database version.
86+
user (str): Database username to connect to Cloud SQL database with.
8887
89-
:type user: str
90-
:param user
91-
Database username to connect to Cloud SQL database with.
88+
Returns:
89+
str: Formatted database username.
9290
"""
9391
# remove suffix for Postgres service accounts
9492
if database_version.startswith("POSTGRES"):

0 commit comments

Comments
 (0)