Fixed type delaration for the "connectiontype" parameter to

oracledb.create_pool_async().

Author: anthony-tuininga

doc/src/release_notes.rst

@@ -35,6 +35,8 @@ Thin Mode Changes
 #)  Fixed bug when connecting to a database using listener redirects when using
     :ref:`asyncio <asyncio>`
     (`issue 285 <https://github.com/oracle/python-oracledb/issues/285>`__).
+#)  Fixed type declaration for the `connectiontype` parameter to
+    :meth:`oracledb.create_pool_async()`.
 
 
 Thick Mode Changes

src/oracledb/pool.py

@@ -672,8 +672,8 @@ def create_pool(
       whenever a new connection needs to be created (default: 1)
 
     - connectiontype: the class of the connection that should be returned
-      during calls to pool.acquire(). It must be Connection or a subclass of
-      Connection (default: None)
+      during calls to pool.acquire(). It must be oracledb.Connection or a
+      subclass of oracledb.Connection (default: None)
 
     - getmode: how pool.acquire() will behave. One of the constants
       oracledb.POOL_GETMODE_WAIT, oracledb.POOL_GETMODE_NOWAIT,
@@ -980,7 +980,7 @@ def create_pool_async(
     min: int = 1,
     max: int = 2,
     increment: int = 1,
-    connectiontype: Type["oracledb.Connection"] = None,
+    connectiontype: Type["oracledb.AsyncConnection"] = None,
     getmode: int = oracledb.POOL_GETMODE_WAIT,
     homogeneous: bool = True,
     timeout: int = 0,
@@ -1067,8 +1067,8 @@ def create_pool_async(
       whenever a new connection needs to be created (default: 1)
 
     - connectiontype: the class of the connection that should be returned
-      during calls to pool.acquire(). It must be Connection or a subclass of
-      Connection (default: None)
+      during calls to pool.acquire(). It must be oracledb.AsyncConnection or a
+      subclass of oracledb.AsyncConnection (default: None)
 
     - getmode: how pool.acquire() will behave. One of the constants
       oracledb.POOL_GETMODE_WAIT, oracledb.POOL_GETMODE_NOWAIT,

src/oracledb/pool_params.py

@@ -122,8 +122,8 @@ def __init__(
           whenever a new connection needs to be created (default: 1)
 
         - connectiontype: the class of the connection that should be returned
-          during calls to pool.acquire(). It must be Connection or a subclass
-          of Connection (default: None)
+          during calls to pool.acquire(). It must be oracledb.Connection or a
+          subclass of oracledb.Connection (default: None)
 
         - getmode: how pool.acquire() will behave. One of the constants
           oracledb.POOL_GETMODE_WAIT, oracledb.POOL_GETMODE_NOWAIT,
@@ -383,7 +383,8 @@ def __repr__(self):
     def connectiontype(self) -> Type["oracledb.Connection"]:
         """
         The class of the connection that should be returned during calls to
-        pool.acquire(). It must be Connection or a subclass of Connection.
+        pool.acquire(). It must be oracledb.Connection or a subclass of
+        oracledb.Connection.
         """
         return self._impl.connectiontype
 
@@ -567,8 +568,8 @@ def set(
           whenever a new connection needs to be created
 
         - connectiontype: the class of the connection that should be returned
-          during calls to pool.acquire(). It must be Connection or a subclass
-          of Connection
+          during calls to pool.acquire(). It must be oracledb.Connection or a
+          subclass of oracledb.Connection
 
         - getmode: how pool.acquire() will behave. One of the constants
           oracledb.POOL_GETMODE_WAIT, oracledb.POOL_GETMODE_NOWAIT,

utils/build_from_template.py

@@ -31,10 +31,14 @@
 #
 #   # {{ args_help_with_defaults }}
 #       is replaced by the arguments help string with field defaults
+#   # {{ async_args_help_with_defaults }}
+#       is replaced by the arguments help string with field defaults (async)
 #   # {{ args_help_without_defaults }}
 #       is replaced by the arguments help string without field defaults
 #   # {{ args_with_defaults }}
 #       is replaced by the arguments with field defaults included
+#   # {{ async_args_with_defaults }}
+#       is replaced by the arguments with field defaults included (async)
 #   # {{ generated_notice }}
 #       is replaced by a notice that the file is generated and should not be
 #       modified directly
@@ -72,6 +76,18 @@ class Field:
     description: str = ""
     decorator: str = None
 
+    @property
+    def async_description(self):
+        return self.description.replace(
+            "oracledb.Connection", "oracledb.AsyncConnection"
+        )
+
+    @property
+    def async_typ(self):
+        return self.typ.replace(
+            "oracledb.Connection", "oracledb.AsyncConnection"
+        )
+
 
 # parse command line
 parser = argparse.ArgumentParser(description="build module from template")
@@ -174,6 +190,36 @@ def args_with_defaults_content(indent):
     return args_joiner.join(args)
 
 
+def async_args_help_with_defaults_content(indent):
+    """
+    Generates the content for the async_args_help_with_defaults template tag.
+    """
+    raw_descriptions = [
+        f"- {f.name}: {f.async_description} (default: {f.default})"
+        for f in fields
+        if f.description
+    ]
+    descriptions = [
+        textwrap.fill(
+            d,
+            initial_indent=indent,
+            subsequent_indent=indent + "  ",
+            width=TEXT_WIDTH,
+        )
+        for d in raw_descriptions
+    ]
+    return "\n\n".join(descriptions).strip()
+
+
+def async_args_with_defaults_content(indent):
+    """
+    Generates the content for the async_args_with_defaults template tag.
+    """
+    args_joiner = "\n" + indent
+    args = [f"{f.name}: {f.async_typ} = {f.default}," for f in fields]
+    return args_joiner.join(args)
+
+
 def generated_notice_content(indent):
     """
     Generates the content for the generated_notice template tag.
@@ -270,8 +316,12 @@ def params_setter_args_content(indent):
 
 # replace generated_notice template tag
 replace_tag("args_help_with_defaults", args_help_with_defaults_content)
+replace_tag(
+    "async_args_help_with_defaults", async_args_help_with_defaults_content
+)
 replace_tag("args_help_without_defaults", args_help_without_defaults_content)
 replace_tag("args_with_defaults", args_with_defaults_content)
+replace_tag("async_args_with_defaults", async_args_with_defaults_content)
 replace_tag("generated_notice", generated_notice_content)
 replace_tag("params_constructor_args", params_constructor_args_content)
 replace_tag("params_properties", params_properties_content)

utils/fields.cfg

@@ -57,7 +57,8 @@ type = Type["oracledb.Connection"]
 pool_only: True
 description =
     the class of the connection that should be returned during calls to
-    pool.acquire(). It must be Connection or a subclass of Connection
+    pool.acquire(). It must be oracledb.Connection or a subclass of
+    oracledb.Connection
 
 [getmode]
 type = int

utils/templates/pool.py

@@ -721,7 +721,7 @@ def create_pool_async(
     *,
     pool_class: Type[ConnectionPool] = AsyncConnectionPool,
     params: PoolParams = None,
-    # {{ args_with_defaults }}
+    # {{ async_args_with_defaults }}
 ) -> AsyncConnectionPool:
     """
     Creates a connection pool with the supplied parameters and returns it.
@@ -749,6 +749,6 @@ def create_pool_async(
     The following parameters are all optional. A brief description of each
     parameter follows:
 
-    # {{ args_help_with_defaults }}
+    # {{ async_args_help_with_defaults }}
     """
     pass