Doc improvements.

Author: anthony-tuininga

doc/src/api_manual/dataframe.rst

@@ -1,8 +1,8 @@
 .. _oracledataframe:
 
-****************
-API: Data Frames
-****************
+**********************
+API: DataFrame Objects
+**********************
 
 .. currentmodule:: oracledb
 
@@ -26,8 +26,10 @@ DataFrame Class
 .. autoclass:: DataFrame
 
     A DataFrame object is returned by the methods
-    :meth:`Connection.fetch_df_all()` and
-    :meth:`Connection.fetch_df_batches()`.
+    :meth:`Connection.fetch_df_all()`,
+    :meth:`Connection.fetch_df_batches()`,
+    :meth:`AsyncConnection.fetch_df_all()`, or
+    :meth:`AsyncConnection.fetch_df_batches()`.
 
     Each column in a DataFrame exposes an `Apache Arrow PyCapsule
     <https://arrow.apache.org/docs/format/CDataInterface/

doc/src/api_manual/module.rst

@@ -1643,14 +1643,14 @@ Other Types
 
 All of these types are extensions to the DB API definition.
 
-.. data:: ApiType
+.. autoclass:: ApiType
 
     This type object is the Python type of the database API type constants
     :data:`BINARY`, :data:`DATETIME`, :data:`NUMBER`, :data:`ROWID` and
     :data:`STRING`.
 
 
-.. data:: DbType
+.. autoclass:: DbType
 
     This type object is the Python type of the
     :ref:`database type constants <dbtypes>`.

doc/src/api_manual/pipeline.rst

@@ -34,66 +34,30 @@ Pipeline Methods
 
 .. automethod:: Pipeline.add_callfunc
 
-    :ref:`pipelineopattrs` can be used to examine the operation, if needed.
-
-    .. seealso::
-
-        :ref:`PipelineOp object <pipelineopobjs>` and
-        :ref:`PipelineOpResult object <pipelineopresultobjs>`
-
 .. automethod:: Pipeline.add_callproc
 
-    :ref:`pipelineopattrs` can be used to examine the operation, if needed.
-
-    .. seealso::
-
-        :ref:`PipelineOp object <pipelineopobjs>`
-
 .. automethod:: Pipeline.add_commit
 
 .. automethod:: Pipeline.add_execute
 
-    :ref:`pipelineopattrs` can be used to examine the operation, if needed.
-
-    .. seealso::
-
-        :ref:`PipelineOp object <pipelineopobjs>`
-
 .. automethod:: Pipeline.add_executemany
 
-    :ref:`pipelineopattrs` can be used to examine the operation, if needed.
-
     .. seealso::
 
-        :ref:`batchstmnt` and :ref:`PipelineOp object <pipelineopobjs>`
+        :ref:`batchstmnt`
 
 .. automethod:: Pipeline.add_fetchall
 
-    :ref:`pipelineopattrs` can be used to examine the operation, if needed.
-
-    .. seealso::
-
-        :ref:`PipelineOp object <pipelineopobjs>` and
-        :ref:`PipelineOpResult object <pipelineopresultobjs>`
-
 .. automethod:: Pipeline.add_fetchmany
 
-    :ref:`pipelineopattrs` can be used to examine the operation, if needed.
-
     .. seealso::
 
-        :ref:`PipelineOp object <pipelineopobjs>`,
-        :ref:`PipelineOpResult object <pipelineopresultobjs>`,
         :ref:`roundtrips`, and :ref:`rowlimit`
 
 .. automethod:: Pipeline.add_fetchone
 
-    :ref:`pipelineopattrs` can be used to examine the operation, if needed.
-
     .. seealso::
 
-        :ref:`PipelineOp object <pipelineopobjs>`,
-        :ref:`PipelineOpResult object <pipelineopresultobjs>`, and
         :ref:`rowlimit`
 
 Pipeline Attributes

doc/src/user_guide/dataframes.rst

@@ -16,8 +16,8 @@ as `Apache PyArrow <https://arrow.apache.org/docs/python/index.html>`__,
 <https://parquet.apache.org/>`__ format.
 
 Python-oracledb has a :ref:`DataFrame <oracledataframeobj>` object that exposes
-an Apache Arrow PyCapsule Interface. This enables zero-copy data interchanges
-to the data frame objects of other libraries.
+an Apache Arrow ArrowArrayStream PyCapsule Interface. This enables zero-copy
+data interchanges to the data frame objects of other libraries.
 
 .. note::
 
@@ -29,28 +29,30 @@ to the data frame objects of other libraries.
 Fetching Data Frames
 ====================
 
-Data frames can be fetched by using a standard SQL query.
+Data frames can be fetched by using a standard SQL query with :ref:`Connection
+<connobj>` or :ref:`AsyncConnection <asyncconnobj>` methods.
 
 Data Frame Queries
 ------------------
 
-Python-oracledb has two methods for fetching rows into data frames:
+The python-oracledb methods for fetching rows into data frames are:
 
 - :meth:`Connection.fetch_df_all()` fetches all rows from a query
 - :meth:`Connection.fetch_df_batches()` implements an iterator for fetching
   batches of rows
 
-The methods return python-oracledb :ref:`DataFrame <oracledataframeobj>`
-objects.
+These methods can also be called from :ref:`AsyncConnection
+<asyncconnobj>`. The methods all return python-oracledb :ref:`DataFrame
+<oracledataframeobj>` objects.
 
 For example, to fetch all rows from a query and print some information about
 the results:
 
 .. code-block:: python
 
-    sql = "select * from departments"
+    sql = "select * from departments where department_id > :1"
     # Adjust arraysize to tune the query fetch performance
-    odf = connection.fetch_df_all(statement=sql, arraysize=100)
+    odf = connection.fetch_df_all(statement=sql, parameters=[100], arraysize=100)
 
     print(odf.column_names())
     print(f"{odf.num_columns()} columns")
@@ -60,20 +62,20 @@ With Oracle Database's standard DEPARTMENTS table, this would display::
 
     ['DEPARTMENT_ID', 'DEPARTMENT_NAME', 'MANAGER_ID', 'LOCATION_ID']
     4 columns
-    27 rows
+    17 rows
 
 To fetch in batches, use an iterator:
 
 .. code-block:: python
 
     import pyarrow
 
-    sql = "select * from departments where department_id < 80"
+    sql = "select * from departments where department_id < :1"
     # Adjust "size" to tune the query fetch performance
     # Here it is small to show iteration
-    for odf in connection.fetch_df_batches(statement=sql, size=4):
-        pdf = pyarrow.table(odf).to_pandas()
-        print(pdf)
+    for odf in connection.fetch_df_batches(statement=sql, parameters=[80], size=4):
+        df = pyarrow.table(odf).to_pandas()
+        print(df)
 
 With Oracle Database's standard DEPARTMENTS table, this would display::
 
@@ -90,6 +92,24 @@ With Oracle Database's standard DEPARTMENTS table, this would display::
 Converting to other data frame formats is :ref:`shown later <convertingodf>` in
 this chapter.
 
+**Asynchronous Data Frame Queries**
+
+With :ref:`asynchronous programming <asyncio>`, use the appropriate syntax. For
+example, to fetch all rows at once:
+
+.. code-block:: python
+
+    connection = await oracledb.connect_async(...)
+    odf = await connection.fetch_df_all(sql="select ...", parameters=..., arraysize=...)
+
+Or to iterate:
+
+.. code-block:: python
+
+    connection = await oracledb.connect_async(...)
+    async for odf in connection.fetch_df_batches(sql="select ...", parameters=..., size=...):
+        do_something(odf)
+
 .. _dftypemapping:
 
 Data Frame Type Mapping

src/oracledb/__init__.py

@@ -43,6 +43,9 @@
 from . import base_impl, thick_impl, thin_impl
 
 from .base_impl import (
+    # type classes
+    ApiType as ApiType,
+    DbType as DbType,
     # database types
     DB_TYPE_BFILE as DB_TYPE_BFILE,
     DB_TYPE_BINARY_DOUBLE as DB_TYPE_BINARY_DOUBLE,