docs: docstrings edit (#185)

* edit complete

* code-check touchup

* Update connection.py

Co-authored-by: Eric Ford <[email protected]>

src/firebolt/async_db/_types.py

@@ -46,26 +46,26 @@ def parse_datetime(date_string: str) -> datetime:  # type: ignore
 
 
 def DateFromTicks(t: int) -> date:
-    """Convert ticks to date for firebolt db."""
+    """Convert `ticks` to `date` for Firebolt DB."""
     return datetime.fromtimestamp(t).date()
 
 
 def Time(hour: int, minute: int, second: int) -> None:
-    """Unsupported: construct time for firebolt db."""
-    raise NotSupportedError("time is not supported by Firebolt")
+    """Unsupported: Construct `time`, for Firebolt DB."""
+    raise NotSupportedError("The time construct is not supported by Firebolt")
 
 
 def TimeFromTicks(t: int) -> None:
-    """Unsupported: convert ticks to time for firebolt db."""
-    raise NotSupportedError("time is not supported by Firebolt")
+    """Unsupported: Convert `ticks` to `time` for Firebolt DB."""
+    raise NotSupportedError("The time construct is not supported by Firebolt")
 
 
 Timestamp = datetime
 TimestampFromTicks = datetime.fromtimestamp
 
 
 def Binary(value: str) -> str:
-    """Convert string to binary for firebolt db, does nothing."""
+    """Convert string to binary for Firebolt DB does nothing."""
     return value
 
 
@@ -89,7 +89,7 @@ def Binary(value: str) -> str:
 
 
 class ARRAY:
-    """Class for holding information about array column type in firebolt db."""
+    """Class for holding `array` column type information in Firebolt DB."""
 
     _prefix = "Array("
 
@@ -109,7 +109,7 @@ def __eq__(self, other: object) -> bool:
 
 
 class DECIMAL:
-    """Class for holding imformation about decimal value in firebolt db."""
+    """Class for holding `decimal` value information in Firebolt DB."""
 
     _prefix = "Decimal("
 
@@ -127,7 +127,7 @@ def __eq__(self, other: object) -> bool:
 
 
 class DATETIME64:
-    """Class for holding imformation about datetime64 value in firebolt db."""
+    """Class for holding `datetime64` value information in Firebolt DB."""
 
     _prefix = "DateTime64("
 
@@ -147,7 +147,7 @@ def __eq__(self, other: object) -> bool:
 
 
 class _InternalType(Enum):
-    """Enum of all internal firebolt types except for array."""
+    """Enum of all internal Firebolt types, except for `array`."""
 
     # INT, INTEGER
     Int8 = "Int8"
@@ -182,7 +182,7 @@ class _InternalType(Enum):
 
     @cached_property
     def python_type(self) -> type:
-        """Convert internal type to python type."""
+        """Convert internal type to Python type."""
         types = {
             _InternalType.Int8: int,
             _InternalType.UInt8: int,
@@ -205,7 +205,7 @@ def python_type(self) -> type:
 
 
 def parse_type(raw_type: str) -> Union[type, ARRAY, DECIMAL, DATETIME64]:
-    """Parse typename, provided by query metadata into python type."""
+    """Parse typename provided by query metadata into Python type."""
     if not isinstance(raw_type, str):
         raise DataError(f"Invalid typename {str(raw_type)}: str expected")
     # Handle arrays
@@ -244,7 +244,7 @@ def parse_value(
     value: RawColType,
     ctype: Union[type, ARRAY, DECIMAL, DATETIME64],
 ) -> ColType:
-    """Provided raw value and python type, parses first into python value."""
+    """Provided raw value, and Python type; parses first into Python value."""
     if value is None:
         return None
     if ctype in (int, str, float):
@@ -276,7 +276,7 @@ def parse_value(
 
 
 def format_value(value: ParameterType) -> str:
-    """For python value to be used in a SQL query"""
+    """For Python value to be used in a SQL query."""
     if isinstance(value, bool):
         return str(int(value))
     if isinstance(value, (int, float, Decimal)):
@@ -299,7 +299,7 @@ def format_value(value: ParameterType) -> str:
 
 def format_statement(statement: Statement, parameters: Sequence[ParameterType]) -> str:
     """
-    Substitute placeholders in a sqlparse statement with provided values.
+    Substitute placeholders in a `sqlparse` statement with provided values.
     """
     idx = 0
 
@@ -336,7 +336,10 @@ def process_token(token: Token) -> Token:
 
 
 def statement_to_set(statement: Statement) -> Optional[SetParameter]:
-    """Try to parse statement as a SET command. Return None if it's not a SET command"""
+    """
+    Try to parse `statement` as a `SET` command.
+    Return `None` if it's not a `SET` command.
+    """
     # Filter out meaningless tokens like Punctuation and Whitespaces
     tokens = [
         token
@@ -370,9 +373,8 @@ def split_format_sql(
     query: str, parameters: Sequence[Sequence[ParameterType]]
 ) -> List[Union[str, SetParameter]]:
     """
-    Split a query into separate statement, and format it with parameters
-    if it's a single statement
-    Trying to format a multi-statement query would result in NotSupportedError
+    Multi-statement query formatting will result in `NotSupportedError`.
+    Instead, split a query into a separate statement and format with parameters.
     """
     statements = parse_sql(query)
     if not statements:

src/firebolt/async_db/connection.py

@@ -30,8 +30,9 @@
 DEFAULT_TIMEOUT_SECONDS: int = 5
 KEEPALIVE_FLAG: int = 1
 KEEPIDLE_RATE: int = 60  # seconds
-AUTH_CREDENTIALS_DEPRECATION_MESSAGE = """ Passing connection credentials directly to `connect` function is deprecated.
- Please consider passing Auth object instead.
+AUTH_CREDENTIALS_DEPRECATION_MESSAGE = """ Passing connection credentials
+ directly to the `connect` function is deprecated.
+ Pass the `Auth` object instead.
  Examples:
   >>> from firebolt.client.auth import UsernamePassword
   >>> ...
@@ -128,29 +129,29 @@ def _get_auth(
     access_token: Optional[str],
     use_token_cache: bool,
 ) -> Auth:
-    """Create Auth class based on provided credentials.
+    """Create `Auth` class based on provided credentials.
 
-    If access_token is provided, it's used for Auth creation.
-    Username and password are used otherwise.
+    If `access_token` is provided, it's used for `Auth` creation.
+    Otherwise, username/password are used.
 
     Returns:
-        Auth: auth object
+        Auth: `auth object`
 
     Raises:
-        ConfigurationError: Invalid combination of credentials provided
+        `ConfigurationError`: Invalid combination of credentials provided
 
     """
     if not access_token:
         if not username or not password:
             raise ConfigurationError(
                 "Neither username/password nor access_token are provided. Provide one"
-                " to authenticate"
+                " to authenticate."
             )
         return UsernamePassword(username, password, use_token_cache)
     if username or password:
         raise ConfigurationError(
-            "Either username/password and access_token are provided. Provide only one"
-            " to authenticate"
+            "Username/password and access_token are both provided. Provide only one"
+            " to authenticate."
         )
     return Token(access_token)
 
@@ -172,24 +173,24 @@ async def connect_inner(
         """Connect to Firebolt database.
 
         Args:
-            database (str): Name of the database to connect
-            username (Optional[str]): User name to use for authentication (Deprecated)
-            password (Optional[str]): Password to use for authentication (Deprecated)
-            access_token (Optional[str]): Authentication token to use insead of
+            `database` (str): Name of the database to connect
+            `username` (Optional[str]): User name to use for authentication (Deprecated)
+            `password` (Optional[str]): Password to use for authentication (Deprecated)
+            `access_token` (Optional[str]): Authentication token to use instead of
                                           credentials (Deprecated)
-            auth (Auth)L Authentication object
-            engine_name (Optional[str]): The name of the engine to connect to
-            engine_url (Optional[str]): The engine endpoint to use
-            account_name (Optional[str]): For customers with multiple accounts;
-                                          if None uses default.
-            api_endpoint (str): Firebolt API endpoint. Used for authentication.
-            use_token_cache (bool): Cached authentication token in filesystem.
+            `auth` (Auth)L Authentication object.
+            `engine_name` (Optional[str]): Name of the engine to connect to
+            `engine_url` (Optional[str]): The engine endpoint to use
+            `account_name` (Optional[str]): For customers with multiple accounts;
+                                          if none, default is used
+            `api_endpoint` (str): Firebolt API endpoint. Used for authentication
+            `use_token_cache` (bool): Cached authentication token in filesystem
                                     Default: True
-            additional_parameters (Optional[Dict]): Dictionary of less widely-used
-                                    arguments for connection.
+            `additional_parameters` (Optional[Dict]): Dictionary of less widely-used
+                                    arguments for connection
 
         Note:
-            Providing both `engine_name` and `engine_url` would result in an error.
+            Providing both `engine_name` and `engine_url` will result in an error
 
         """
         # These parameters are optional in function signature
@@ -251,11 +252,12 @@ async def connect_inner(
 
 class OverriddenHttpBackend(AutoBackend):
     """
-    This class is a short-term solution for TCP keep-alive issue:
+    `OverriddenHttpBackend` is a short-term solution for the TCP
+    connection idle timeout issue described in the following article:
     https://docs.aws.amazon.com/elasticloadbalancing/latest/network/network-load-balancers.html#connection-idle-timeout
-    Since httpx creates a connection right before executing a request
-    backend has to be overridden in order to set the socket KEEPALIVE
-    and KEEPIDLE settings.
+    Since httpx creates a connection right before executing a request, the
+    backend must be overridden to set the socket to `KEEPALIVE`
+    and `KEEPIDLE` settings.
     """
 
     async def connect_tcp(
@@ -330,7 +332,7 @@ def _cursor(self, **kwargs: Any) -> BaseCursor:
         """
 
         if self.closed:
-            raise ConnectionClosedError("Unable to create cursor: connection closed")
+            raise ConnectionClosedError("Unable to create cursor: connection closed.")
 
         c = self.cursor_class(self._client, self, **kwargs)
         self._cursors.append(c)
@@ -354,7 +356,7 @@ async def _aclose(self) -> None:
 
     @property
     def closed(self) -> bool:
-        """True if connection is closed, False otherwise."""
+        """`True if connection is closed; False otherwise."""
         return self._is_closed
 
     def _remove_cursor(self, cursor: Cursor) -> None:
@@ -365,28 +367,28 @@ def _remove_cursor(self, cursor: Cursor) -> None:
             pass
 
     def commit(self) -> None:
-        """Does nothing since Firebolt doesn't have transactions"""
+        """Does nothing since Firebolt doesn't have transactions."""
 
         if self.closed:
-            raise ConnectionClosedError("Unable to commit: connection closed")
+            raise ConnectionClosedError("Unable to commit: Connection closed.")
 
 
 class Connection(BaseConnection):
     """
-    Firebolt asyncronous database connection class. Implements `PEP 249`_.
+    Firebolt asynchronous database connection class. Implements `PEP 249`_.
 
     Args:
-        engine_url: Firebolt database engine REST API url
-        database: Firebolt database name
-        username: Firebolt account username
-        password: Firebolt account password
-        api_endpoint: Optional. Firebolt API endpoint. Used for authentication.
-        connector_versions: Optional. Tuple of connector name and version or
-            list of tuples of your connector stack. Useful for tracking custom
+        `engine_url`: Firebolt database engine REST API url
+        `database`: Firebolt database name
+        `username`: Firebolt account username
+        `password`: Firebolt account password
+        `api_endpoint`: Optional. Firebolt API endpoint used for authentication
+        `connector_versions`: Optional. Tuple of connector name and version, or
+            a list of tuples of your connector stack. Useful for tracking custom
             connector usage.
 
     Note:
-        Firebolt currenly doesn't support transactions
+        Firebolt does not support transactions,
         so commit and rollback methods are not implemented.
 
     .. _PEP 249:
@@ -406,7 +408,7 @@ def cursor(self) -> Cursor:
     # Context manager support
     async def __aenter__(self) -> Connection:
         if self.closed:
-            raise ConnectionClosedError("Connection is already closed")
+            raise ConnectionClosedError("Connection is already closed.")
         return self
 
     async def __aexit__(