Doc tweaks.

Author: anthony-tuininga

README.md

@@ -1,21 +1,23 @@
 # python-oracledb
 
-Python-oracledb is a [Python programming language][python] extension module
-allowing Python programs to connect to [Oracle Database][oracledb].
-Python-oracledb is the new name for the obsolete cx_Oracle driver.
+Python-oracledb is an open-source [Python][python] extension module allowing
+Python programs to connect to [Oracle Database][oracledb]. The module conforms
+to the [Python Database API 2.0 specification][pep249] with a considerable
+number of additions and a couple of minor exclusions, see the [feature
+list][features]. It is maintained by Oracle.
 
-Python-oracledb uses the same Python DB API as cx_Oracle, and has many new
-features.
+Python-oracledb is used for executing SQL and PL/SQL; for calling NoSQL-style
+document APIs; for working with data frames; for receiving database
+notifications and messages; and for starting and stopping the database. It has
+features for high availability and security. It is used by many Python
+Frameworks, SQL Generators, ORMs, and libraries.
 
-The module conforms to the [Python Database API 2.0 specification][pep249] with
-a considerable number of additions and a couple of minor exclusions, see the
-[feature list][features].
+Synchronous and [concurrent][concurrent] coding styles are supported. Database
+operations can optionally be [pipelined][pipelining].
 
-Synchronous and [concurrent][concurrent] coding styles are supported.
+Python-oracledb is the successor to the now obsolete cx_Oracle driver.
 
-Python-oracledb is available under an open source license, see below.
-
-## Installation
+## Python-oracledb Installation
 
 Run:
 
@@ -127,4 +129,5 @@ See [LICENSE][license], [THIRD_PARTY_LICENSES][tplicense], and
 [installation]: https://python-oracledb.readthedocs.io/en/latest/user_guide/installation.html
 [features]: https://oracle.github.io/python-oracledb/#features
 [concurrent]: https://python-oracledb.readthedocs.io/en/latest/user_guide/asyncio.html
+[pipelining]: https://python-oracledb.readthedocs.io/en/latest/user_guide/asyncio.html#pipelining-database-operations
 [pypi]: https://pypi.org/project/oracledb

doc/src/index.rst

@@ -31,21 +31,23 @@ User Guide
     user_guide/json_data_type.rst
     user_guide/xml_data_type.rst
     user_guide/vector_data_type.rst
+    user_guide/dataframes.rst
     user_guide/soda.rst
     user_guide/aq.rst
     user_guide/cqn.rst
     user_guide/two_phase_commit.rst
     user_guide/startup.rst
     user_guide/ha.rst
-    user_guide/globalization.rst
     user_guide/asyncio.rst
+    user_guide/globalization.rst
     user_guide/exception_handling.rst
     user_guide/tracing.rst
     user_guide/extending.rst
     user_guide/troubleshooting.rst
     user_guide/appendix_a.rst
     user_guide/appendix_b.rst
     user_guide/appendix_c.rst
+    user_guide/appendix_d.rst
 
 API Manual
 ==========

doc/src/release_notes.rst

@@ -1619,16 +1619,16 @@ Common Changes
 oracledb 1.0.0 (May 2022)
 -------------------------
 
-#)  Renamed cx_Oracle to python-oracledb.  See :ref:`upgradecomparison`.
+#)  Renamed cx_Oracle to python-oracledb. See :ref:`upgrading83`.
 #)  Python-oracledb is a 'Thin' driver by default that connects directly
     to Oracle Database.  Optional use of Oracle Client libraries enables a
     :ref:`'Thick' mode <enablingthick>` with some additional functionality.
     Both modes support the Python Database API v2.0 Specification.
 #)  Added a :attr:`Connection.thin` attribute which shows whether the
     connection was established in the python-oracledb Thin mode or Thick mode.
-#)  Creating connections or connection pools now requires :ref:`keyword
-    parameters <connectdiffs>` be passed.  This brings python-oracledb into
-    compliance with the Python Database API specification PEP 249.
+#)  Creating connections or connection pools now requires keyword parameters be
+    passed. This brings python-oracledb into compliance with the Python
+    Database API specification PEP 249.
 #)  Threaded mode is now always enabled for standalone connections (Thick
     mode).
 #)  The function :func:`oracledb.init_oracle_client()` must now always be

doc/src/user_guide/appendix_a.rst

@@ -15,7 +15,7 @@ enable Thick mode.
 
 The following table summarizes the Oracle Database features supported by
 python-oracledb Thin and Thick modes, and by the obsolete cx_Oracle driver.
-For more details see :ref:`driverdiff` and :ref:`compatibility`.
+For more details see :ref:`driverdiff` and :ref:`upgrading83`.
 
 .. list-table-with-summary::  Features Supported by python-oracledb and cx_Oracle 8.3
     :header-rows: 1
@@ -369,137 +369,140 @@ example when binding numeric values.
     :header-rows: 1
     :class: wy-table-responsive
     :align: center
-    :summary: The first column displays the database data type. The second column displays the python-oracledb constant Name. The third column contains notes.  The fourth column shows Python types that can be used.
+    :summary: The first column displays the database data type. The second column displays the python-oracledb constant Name. The third column shows Python types that can be used. The fourth column contains notes.
 
     * - Oracle Database Type
       - python-oracledb Constant Name
-      - Notes
       - Supported Python Types
+      - Notes
     * - VARCHAR2
       - :data:`~oracledb.DB_TYPE_VARCHAR`
-      - No relevant notes
       - bytes, str
+      - No relevant notes
     * - NVARCHAR2
       - :data:`~oracledb.DB_TYPE_NVARCHAR`
-      - No relevant notes
       - bytes, str
+      - No relevant notes
     * - NUMBER, FLOAT
       - :data:`~oracledb.DB_TYPE_NUMBER`
-      - No relevant notes
       - bool, int, float, decimal.Decimal
+      - No relevant notes
     * - DATE
       - :data:`~oracledb.DB_TYPE_DATE`
-      - No relevant notes
       - datetime.date, datetime.datetime
+      - No relevant notes
     * - BOOLEAN (PL/SQL and Oracle Database 23ai SQL)
       - :data:`~oracledb.DB_TYPE_BOOLEAN`
-      - No relevant notes
       - Any type convertible to bool
+      - No relevant notes
     * - BINARY_DOUBLE
       - :data:`~oracledb.DB_TYPE_BINARY_DOUBLE`
-      - No relevant notes
       - bool, int, float, decimal.Decimal
+      - No relevant notes
     * - BINARY_FLOAT
       - :data:`~oracledb.DB_TYPE_BINARY_FLOAT`
-      - No relevant notes
       - bool, int, float, decimal.Decimal
+      - No relevant notes
     * - TIMESTAMP
       - :data:`~oracledb.DB_TYPE_TIMESTAMP`
-      - No relevant notes
       - datetime.date, datetime.datetime
+      - No relevant notes
     * - TIMESTAMP WITH TIME ZONE
       - :data:`~oracledb.DB_TYPE_TIMESTAMP_TZ`
-      - No relevant notes
       - datetime.date, datetime.datetime
+      - No relevant notes
     * - TIMESTAMP WITH LOCAL TIME ZONE
       - :data:`~oracledb.DB_TYPE_TIMESTAMP_LTZ`
-      - No relevant notes
       - datetime.date, datetime.datetime
+      - No relevant notes
     * - INTERVAL YEAR TO MONTH
       - :data:`~oracledb.DB_TYPE_INTERVAL_YM`
-      - No relevant notes
       - :ref:`oracledb.IntervalYM <interval_ym>`
+      - No relevant notes
     * - INTERVAL DAY TO SECOND
       - :data:`~oracledb.DB_TYPE_INTERVAL_DS`
-      - No relevant notes
       - datetime.timedelta
+      - No relevant notes
     * - RAW
       - :data:`~oracledb.DB_TYPE_RAW`
-      - No relevant notes
       - bytes, str
+      - No relevant notes
     * - LONG
       - :data:`~oracledb.DB_TYPE_LONG`
-      - No relevant notes
       - bytes, str
+      - No relevant notes
     * - LONG RAW
       - :data:`~oracledb.DB_TYPE_LONG_RAW`
-      - No relevant notes
       - bytes, str
+      - No relevant notes
     * - ROWID
       - :data:`~oracledb.DB_TYPE_ROWID`
-      - No relevant notes
       - bytes, str
+      - No relevant notes
     * - UROWID
       - :data:`~oracledb.DB_TYPE_ROWID`, :data:`~oracledb.DB_TYPE_UROWID` (only supported in python-oracledb Thin mode)
-      - May show :data:`~oracledb.DB_TYPE_UROWID` in metadata. See :ref:`Query Metadata Differences <querymetadatadiff>`.
       - bytes, str
+      - May show :data:`~oracledb.DB_TYPE_UROWID` in metadata. See :ref:`Query Metadata Differences <querymetadatadiff>`.
     * - CHAR
       - :data:`~oracledb.DB_TYPE_CHAR`
-      - No relevant notes
       - bytes, str
+      - No relevant notes
     * - BLOB
       - :data:`~oracledb.DB_TYPE_BLOB`
-      - No relevant notes
       - :ref:`oracledb.LOB <lobobj>`, bytes, str
+      - No relevant notes
     * - CLOB
       - :data:`~oracledb.DB_TYPE_CLOB`
-      - No relevant notes
       - :ref:`oracledb.LOB <lobobj>`, bytes, str
+      - No relevant notes
     * - NCHAR
       - :data:`~oracledb.DB_TYPE_NCHAR`
-      - No relevant notes
       - bytes, str
+      - No relevant notes
     * - NCLOB
       - :data:`~oracledb.DB_TYPE_NCLOB`, :data:`~oracledb.DB_TYPE_LONG_NVARCHAR` (if fetching NCLOB as a string)
-      - No relevant notes
       - :ref:`oracledb.LOB <lobobj>`, bytes, str
+      - No relevant notes
     * - BFILE
       - :data:`~oracledb.DB_TYPE_BFILE`
-      - Can fetch a BFILE object and insert that object in a table. Cannot create BFILE objects.
       - :ref:`oracledb.LOB <lobobj>`, bytes
+      - Can fetch a BFILE object and insert that object in a table. Cannot create BFILE objects.
     * - JSON
       - :data:`~oracledb.DB_TYPE_JSON`
-      - No relevant notes
       - Any type convertible to Oracle JSON
+      - No relevant notes
     * - REF CURSOR (PL/SQL OR nested cursor)
       - :data:`~oracledb.DB_TYPE_CURSOR`
-      - No relevant notes
       - :ref:`oracledb.Cursor <cursorobj>`
+      - No relevant notes
     * - PLS_INTEGER
       - :data:`~oracledb.DB_TYPE_BINARY_INTEGER`
-      - No relevant notes
       - bool, int, float, decimal.Decimal
+      - No relevant notes
     * - BINARY_INTEGER
       - :data:`~oracledb.DB_TYPE_BINARY_INTEGER`
-      - No relevant notes
       - bool, int, float, decimal.Decimal
+      - No relevant notes
     * - REF
       - n/a
-      - Not supported in python-oracledb Thin mode
       - n/a
+      - Not supported in python-oracledb Thin mode
     * - XMLType
       - :data:`~oracledb.DB_TYPE_XMLTYPE`
-      - May need to use ``xmltype.getclobval()`` to fetch in python-oracledb Thick mode. See :ref:`xmldatatype`
       - bytes, str
+      - May need to use ``xmltype.getclobval()`` to fetch in python-oracledb Thick mode. See :ref:`xmldatatype`
     * - User-defined types (object type, VARRAY, records, collections, SDO_*types)
       - :data:`~oracledb.DB_TYPE_OBJECT`
-      - No relevant notes
       - OBJECT of specific type
+      - No relevant notes
     * - VECTOR
       - :data:`~oracledb.DB_TYPE_VECTOR`
-      - No relevant notes
       - array.array
+      - No relevant notes
 
 Binding of contiguous PL/SQL Index-by BINARY_INTEGER arrays of string, number, and date are
 supported in python-oracledb Thin and Thick modes. Use :meth:`Cursor.arrayvar()` to build
 these arrays.
+
+When fetching :ref:`data frames <dataframeformat>`, see :ref:`Data Frame Type
+Mapping <dftypemapping>` for type information.