docs: add docstrings for methods directly used methods

Author: Brooke-white

redshift_connector/__init__.py

@@ -121,7 +121,85 @@ def connect(
     role_session_name: typing.Optional[str] = None,
     role_arn: typing.Optional[str] = None,
 ) -> Connection:
+    """
+    Establishes a :class:`Connection` to an Amazon Redshift cluster. This function validates user input, optionally authenticates using an identity provider plugin, then constructs a :class:`Connection` object.
 
+    Parameters
+    ----------
+    user : str
+        The username to use for authentication with the Amazon Redshift cluster.
+    password : str
+        The password to use for authentication with the Amazon Redshift cluster.
+    database : str
+        The name of the database instance to connect to.
+    host : str
+        The hostname of the Amazon Redshift cluster.
+    port : int
+        The port number of the Amazon Redshift cluster. Default value is 5439.
+    source_address : typing.Optional[str]
+    unix_sock : Optional[str]
+    ssl : bool
+        Is SSL enabled. Default value is ``True``. SSL must be enabled when authenticating using IAM.
+    sslmode : str
+        The security of the connection to the Amazon Redshift cluster. 'verify-ca' and 'verify-full' are supported.
+    timeout : Optional[int]
+        The number of seconds before the connection to the server will timeout. By default there is no timeout.
+    max_prepared_statements : int
+    tcp_keepalive : Optional[bool]
+        Is `TCP keepalive <https://en.wikipedia.org/wiki/Keepalive#TCP_keepalive>`_ used. The default value is ``True``.
+    application_name : Optional[str]
+        Sets the application name. The default value is None.
+    replication : Optional[str]
+        Used to run in `streaming replication mode <https://www.postgresql.org/docs/12/protocol-replication.html>`_.
+    idp_host : Optional[str]
+        The hostname of the IdP.
+    db_user : str
+        The user ID to use with Amazon Redshift
+    app_id : Optional[str]
+    app_name : str
+        The name of the identity provider (IdP) application used for authentication.
+    preferred_role : str
+        The IAM role preferred for the current connection.
+    principal_arn : Optional[str]
+    credentials_provider : str
+        The class name of the IdP that will be used for authenticating with the Amazon Redshift cluster.
+    region : str
+        The AWS region where the Amazon Redshift cluster is located.
+    cluster_identifier : str
+        The cluster identifier of the Amazon Redshift cluster.
+    iam : bool
+        If IAM authentication is enabled. Default value is False. IAM must be True when authenticating using an IdP.
+    client_id : str
+        The client id from Azure IdP.
+    idp_tenant : str
+        The IdP tenant.
+    client_secret : str
+        The client secret from Azure IdP.
+    partner_sp_id : Optional[str]
+    idp_response_timeout : int
+        The timeout for retrieving SAML assertion from IdP. Default value is `120`.
+    listen_port : int
+        The listen port the IdP will send the SAML assertion to. Default value is `7890`.
+    login_url : str
+        The SSO url for the IdP.
+    auto_create :bool
+        Indicates whether the user should be created if they do not exist. Default value is `False`.
+    db_groups : str
+        A comma-separated list of existing database group names that the `db_user` joins for the current session.
+    force_lowercase :
+    allow_db_user_override : bool
+        Specifies if the driver uses the `db_user` value from the SAML assertion. TDefault value is `False`.
+    client_protocol_version : int
+         The requested server protocol version. The default value is 1 representing `EXTENDED_RESULT_METADATA`. If the requested server protocol cannot be satisfied, a warning will be displayed to the user.
+    database_metadata_current_db_only : bool
+        Is `datashare <https://docs.aws.amazon.com/redshift/latest/dg/datashare-overview.html>`_ disabled. Default value is True, implying datasharing will not be used.
+    ssl_insecure : bool
+        Specifies if IdP host's server certificate will be verified. Default value is True
+
+    Returns
+    -------
+    A Connection object associated with the specified Amazon Redshift cluster: :class:`Connection`
+    """
     info: RedshiftProperty = RedshiftProperty()
     IamHelper.set_iam_properties(
         info,
@@ -209,6 +287,9 @@ def connect(
 """
 
 paramstyle: str = "format"
+"""
+String property stating the type of parameter marker formatting expected by the interface; This value defaults to "format", in which parameters are marked in this format "WHERE name=%s"
+"""
 
 # I have no idea what this would be used for by a client app.  Should it be
 # TEXT, VARCHAR, CHAR?  It will only compare against row_description's
@@ -259,4 +340,5 @@ def connect(
     "PGTsvector",
     "PGText",
     "PGVarchar",
+    "__version__",
 ]

redshift_connector/core.py

@@ -366,7 +366,42 @@ def __init__(
         client_protocol_version: int = DEFAULT_PROTOCOL_VERSION,
         database_metadata_current_db_only: bool = True,
     ):
-
+        """
+        Creates a :class:`Connection` to an Amazon Redshift cluster. For more information on establishing a connection to an Amazon Redshift cluster using `federated API access <https://aws.amazon.com/blogs/big-data/federated-api-access-to-amazon-redshift-using-an-amazon-redshift-connector-for-python/>`_ see our examples page.
+        This is the underlying :class:`Connection` constructor called from :func:`redshift_connector.connect`.
+
+        Parameters
+        ----------
+        user : str
+            The username to use for authentication with the Amazon Redshift cluster.
+        password : str
+            The password to use for authentication with the Amazon Redshift cluster.
+        database : str
+            The name of the database instance to connect to.
+        host : str
+            The hostname of the Amazon Redshift cluster.
+        port : int
+            The port number of the Amazon Redshift cluster. Default value is 5439.
+        source_address : Optional[str]
+        unix_sock : Optional[str]
+        ssl : bool
+            Is SSL enabled. Default value is ``True``. SSL must be enabled when authenticating using IAM.
+        sslmode : str
+            The security of the connection to the Amazon Redshift cluster. 'verify-ca' and 'verify-full' are supported.
+        timeout : Optional[int]
+            The number of seconds before the connection to the server will timeout. By default there is no timeout.
+        max_prepared_statements : int
+        tcp_keepalive : Optional[bool]
+            Is `TCP keepalive <https://en.wikipedia.org/wiki/Keepalive#TCP_keepalive>`_ used. The default value is ``True``.
+        application_name : Optional[str]
+            Sets the application name. The default value is None.
+        replication : Optional[str]
+            Used to run in `streaming replication mode <https://www.postgresql.org/docs/12/protocol-replication.html>`_.
+        client_protocol_version : int
+            The requested server protocol version. The default value is 1 representing `EXTENDED_RESULT_METADATA`. If the requested server protocol cannot be satisfied, a warning will be displayed to the user.
+        database_metadata_current_db_only : bool
+            Is `datashare <https://docs.aws.amazon.com/redshift/latest/dg/datashare-overview.html>`_ disabled. Default value is True, implying datasharing will not be used.
+        """
         self.merge_socket_read = False
 
         _client_encoding = "utf8"
@@ -684,14 +719,25 @@ def cursor(self: "Connection") -> Cursor:
 
         This function is part of the `DBAPI 2.0 specification
         <http://www.python.org/dev/peps/pep-0249/>`_.
+
+        Returns
+        -------
+        A Cursor object associated with the current Connection: :class:`Cursor`
         """
         return Cursor(self)
 
     @property
     def description(self: "Connection") -> typing.Optional[typing.List]:
         return self._run_cursor._getDescription()
 
-    def run(self: "Connection", sql, stream=None, **params):
+    def run(self: "Connection", sql, stream=None, **params) -> typing.Tuple[typing.Any, ...]:
+        """
+        Executes an sql statement, and returns the results as a `tuple`.
+
+        Returns
+        -------
+        Result of executing an sql statement:tuple[Any, ...]
+        """
         self._run_cursor.execute(sql, params, stream=stream)
         return tuple(self._run_cursor._cached_rows)
 
@@ -700,6 +746,10 @@ def commit(self: "Connection") -> None:
 
         This function is part of the `DBAPI 2.0 specification
         <http://www.python.org/dev/peps/pep-0249/>`_.
+
+        Returns
+        -------
+        None:None
         """
         self.execute(self._cursor, "commit", None)
 
@@ -708,6 +758,10 @@ def rollback(self: "Connection") -> None:
 
         This function is part of the `DBAPI 2.0 specification
         <http://www.python.org/dev/peps/pep-0249/>`_.
+
+        Returns
+        -------
+        None:None
         """
         if not self.in_transaction:
             return
@@ -718,6 +772,10 @@ def close(self: "Connection") -> None:
 
         This function is part of the `DBAPI 2.0 specification
         <http://www.python.org/dev/peps/pep-0249/>`_.
+
+        Returns
+        -------
+        None:None
         """
         try:
             # Byte1('X') - Identifies the message as a terminate message.
@@ -908,6 +966,19 @@ def handle_ROW_DESCRIPTION(self: "Connection", data, cursor: Cursor) -> None:
             field["pg8000_fc"], field["func"] = pg_types[field["type_oid"]]
 
     def execute(self: "Connection", cursor: Cursor, operation: str, vals) -> None:
+        """
+        Executes a database operation. Parameters may be provided as a sequence, or as a mapping, depending upon the value of `redshift_connector.paramstyle`.
+
+        Parameters
+        ----------
+        cursor : :class:`Cursor`
+        operation : str The SQL statement to execute.
+        vals : If `redshift_connector.paramstyle` is `qmark`, `numeric`, or `format` this argument should be an array of parameters to bind into the statement. If `redshift_connector.paramstyle` is `named` the argument should be a `dict` mapping of parameters. If `redshift_connector.paramstyle` is `pyformat`, the argument value may be either an array or mapping.
+
+        Returns
+        -------
+        None:None
+        """
         if vals is None:
             vals = ()
 
@@ -1332,12 +1403,16 @@ def send_array(arr: typing.List) -> typing.Union[bytes, bytearray]:
 
         return (array_oid, fc, send_array)
 
-    def xid(self: "Connection", format_id, global_transaction_id, branch_qualifier):
+    def xid(self: "Connection", format_id, global_transaction_id, branch_qualifier) -> typing.Tuple:
         """Create a Transaction IDs (only global_transaction_id is used in pg)
         format_id and branch_qualifier are not used in postgres
         global_transaction_id may be any string identifier supported by
-        postgres returns a tuple
-        (format_id, global_transaction_id, branch_qualifier)"""
+        postgres.
+
+        Returns
+        -------
+        (format_id, global_transaction_id, branch_qualifier):typing.Tuple
+        """
         return (format_id, global_transaction_id, branch_qualifier)
 
     def tpc_begin(self: "Connection", xid) -> None:
@@ -1352,6 +1427,10 @@ def tpc_begin(self: "Connection", xid) -> None:
 
         This function is part of the `DBAPI 2.0 specification
         <http://www.python.org/dev/peps/pep-0249/>`_.
+
+        Returns
+        -------
+        None:None
         """
         self._xid = xid
         if self.autocommit:
@@ -1367,6 +1446,10 @@ def tpc_prepare(self: "Connection") -> None:
 
         This function is part of the `DBAPI 2.0 specification
         <http://www.python.org/dev/peps/pep-0249/>`_.
+
+        Returns
+        -------
+        None:None
         """
         if self._xid is None or len(self._xid) < 2:
             raise InterfaceError("Malformed Transaction Id")
@@ -1391,6 +1474,10 @@ def tpc_commit(self: "Connection", xid=None) -> None:
 
         This function is part of the `DBAPI 2.0 specification
         <http://www.python.org/dev/peps/pep-0249/>`_.
+
+        Returns
+        -------
+        None:None
         """
         if xid is None:
             xid = self._xid
@@ -1423,6 +1510,10 @@ def tpc_rollback(self: "Connection", xid=None) -> None:
 
         This function is part of the `DBAPI 2.0 specification
         <http://www.python.org/dev/peps/pep-0249/>`_.
+
+        Returns
+        -------
+        None:None
         """
         if xid is None:
             xid = self._xid
@@ -1443,12 +1534,16 @@ def tpc_rollback(self: "Connection", xid=None) -> None:
             self.autocommit = previous_autocommit_mode
         self._xid = None
 
-    def tpc_recover(self: "Connection"):
+    def tpc_recover(self: "Connection") -> typing.List[typing.Tuple[typing.Any, ...]]:
         """Returns a list of pending transaction IDs suitable for use with
         .tpc_commit(xid) or .tpc_rollback(xid).
 
         This function is part of the `DBAPI 2.0 specification
         <http://www.python.org/dev/peps/pep-0249/>`_.
+
+        Returns
+        -------
+        List of pending transaction IDs:List[tuple[Any, ...]]
         """
         try:
             previous_autocommit_mode: bool = self.autocommit