Doc updates.

Author: anthony-tuininga

README.md

@@ -1,19 +1,24 @@
 # python-oracledb
 
-Python-oracledb is the widely used, 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 is used for executing SQL and PL/SQL; for working with data
-frames; for calling NoSQL-style document APIs; for receiving database
-notifications and messages; and for starting and stopping the database. It has
-features for fast data loading, high availability, and security. It is used by
-many Python frameworks, SQL generators, ORMs, and libraries.
-
-Synchronous and [concurrent][concurrent] coding styles are supported. Database
-operations can optionally be [pipelined][pipelining].
+The python-oracledb driver is the widely used, open-source [Python][python]
+extension module allowing Python programs to connect directly to [Oracle
+Database][oracledb] with no extra libraries needed. The module is built with
+Cython for safety and speed. It is lightweight and high-performance. It is
+stable, well tested, and has comprehensive [documentation][documentation]. The
+module is maintained by Oracle.
+
+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 used by many Python frameworks, SQL generators,
+ORMs, and libraries.
+
+Python-oracledb has a rich feature set which is easy to use. It gives you
+control over SQL and PL/SQL statement execution; for working with data frames;
+for fast data ingestion; for calling NoSQL-style document APIs; for message
+queueing; for receiving database notifications; and for starting and stopping
+the database. It also has high availability and security features. Synchronous
+and [concurrent][concurrent] coding styles are supported. Database operations
+can optionally be [pipelined][pipelining].
 
 Python-oracledb is the successor to the now obsolete cx_Oracle driver.
 
@@ -38,10 +43,10 @@ A basic example:
 import oracledb
 import getpass
 
-un = "scott"
-cs = "localhost/orclpdb"
-# cs = "localhost/freepdb1"   # for Oracle Database Free users
-# cs = "localhost/orclpdb1"   # some databases may have this service
+un = "scott"                  # Sample database username
+cs = "localhost/orclpdb"      # Sample database connection string
+# cs = "localhost/freepdb1"   # For Oracle Database Free users
+# cs = "localhost/orclpdb1"   # Some databases may have this service
 pw = getpass.getpass(f"Enter password for {un}@{cs}: ")
 
 with oracledb.connect(user=un, password=pw, dsn=cs) as connection:
@@ -79,7 +84,7 @@ with oracledb.connect(user=un, password=pw, dsn=cs) as connection:
   **Thick mode**: Oracle Database 9.2 (or later) is required, depending on the
   Oracle Client library version.  Oracle Database's standard client-server
   version interoperability allows connection to both older and newer
-  databases. For example when python-oracledb uses Oracle Client 19c libraries,
+  databases. For example when python-oracledb uses Oracle Client 19 libraries,
   then it can connect to Oracle Database 11.2 or later.
 
 ## Documentation

doc/src/index.rst

@@ -2,9 +2,10 @@ Welcome to python-oracledb's documentation
 ==========================================
 
 The python-oracledb driver is an open source Python module that enables access
-to Oracle Database. Python-oracledb is the renamed, major version successor to
-cx_Oracle 8.3. The cx_Oracle driver is obsolete and should not be used for new
-development.
+to Oracle Database with no extra libraries needed. The module is built with
+Cython for safety and speed. It is lightweight and high-performance. It is
+stable, well tested, and has comprehensive documentation. The module is
+maintained by Oracle.
 
 You can use assistive technology products, such as screen readers, while you
 work with the python-oracledb documentation. You can also use the keyboard

doc/src/release_notes.rst

@@ -51,18 +51,18 @@ Common Changes
     - Added parameter ``requested_schema`` to :meth:`Connection.fetch_df_all()`
       and :meth:`Connection.fetch_df_batches()` to support type mapping when
       querying.
-    - The large variants for strings and binary values that use 64-bit offsets
-      are now used by default in order to avoid the limits imposed by using
-      32-bit offsets. Use ``requested_schema`` if the smaller offset size is
-      desired
+    - The Apache Arrow data type "large" variants that have 64-bit offsets are
+      now used by default for strings and binary values in order to avoid the
+      limits imposed by using 32-bit offsets. Use ``requested_schema`` if the
+      smaller offset size is desired
       (`issue 536 <https://github.com/oracle/python-oracledb/issues/536>`__).
     - Added support for all of the signed and unsigned fixed width integer
       types when ingesting data frames supporting the Arrow PyCapsule
       interface. Previously only ``int64`` was supported.
     - Added support for types ``date32`` and ``date64`` when ingesting data
       frames supporting the Arrow PyCapsule interface as requested
       (`issue 535 <https://github.com/oracle/python-oracledb/issues/535>`__).
-    - Data frames with multiple chunks are now supported.
+    - Ingesting data frames with multiple chunks is now supported.
     - Error ``DPY-8002: Apach Arrow C Data structure overflow detected. A
       larger structure is needed.`` is now raised when an overflow is detected
       (`issue 536 <https://github.com/oracle/python-oracledb/issues/536>`__).
@@ -79,13 +79,14 @@ Common Changes
     specified then the values of
     :attr:`oracledb.defaults.fetch_lobs <Defaults.fetch_lobs>` and
     :attr:`oracledb.defaults.fetch_decimals <Defaults.fetch_decimals>` are now
-    stored with the operation and used during pipeline execution.
-#)  Added optional dependencies [oci_config], [azure_config], [oci_auth] and
-    [azure_auth] to simplify installation of required packages for
-    :ref:`Centralized Configuration Provider <configprovidermodules>`
-    support and :ref:`Cloud Native Authentication <cloudnativemodules>`
-    support
-    (`issue 512 <https://github.com/oracle/python-oracledb/issues/512>`__).
+    stored with the operation and used during pipeline execution
+    (`issue 19 <https://github.com/oracle/python-oracledb/issues/19>`__).
+#)   Added optional dependencies `[oci_config]`, `[azure_config]`,
+     `[oci_auth]`, and `[azure_auth]` to simplify installation of required
+     packages for :ref:`Centralized Configuration Provider
+     <configprovidermodules>` support and :ref:`Cloud Native Authentication
+     <cloudnativemodules>` support
+     (`issue 512 <https://github.com/oracle/python-oracledb/issues/512>`__).
 #)  The x86_64 macOS and 32-bit Windows platforms are :ref:`deprecated
     <deprecations>`. They will be desupported in a future release before, or
     when, the `cryptography <https://pypi.org/project/cryptography/>`__ package
@@ -108,8 +109,8 @@ Common Changes
 #)  API documentation is now generated from the source code.
 #)  The test suite now uses `pytest <https://docs.pytest.org/>`__.
 #)  Internal change: the value of ``__module__`` for all classes is now left
-    untouched to avoid issues with ``inspect.getsource()`` but the
-    ``__repr__()`` now consistently shows the module as ``oracledb``.
+    untouched to avoid issues with ``inspect.getsource()`` but ``__repr__()``
+    now consistently shows the module as ``oracledb``.
 #)  Internal change: `typing_extensions <https://pypi.org/project/
     typing-extensions/>`__ is now a dependency.
 

doc/src/user_guide/dataframes.rst

@@ -360,18 +360,19 @@ fetched into the requested type INT16. Its name has also changed::
 
 **Supported Explicit Type Mapping**
 
-The following table shows the explicit type mappings that are supported. An
-error will occur if the database type or the data cannot be represented in the
-requested schema type.
+The following table shows the explicit type mappings that are supported. The
+Oracle Database types in each row can be converted to any of the Apache Arrow
+types in the same row. An error will occur if the database type or the data
+cannot be represented in the requested schema type.
 
   .. list-table-with-summary::
       :header-rows: 1
       :class: wy-table-responsive
       :widths: 1 1
       :align: left
-      :summary: The first column is the Oracle Database data type. The second column shows supported Apache Arrow data types.
+      :summary: The first column is the Oracle Database data types. The second column shows supported Apache Arrow data types.
 
-      * - Oracle Database Type
+      * - Oracle Database Types
         - Apache Arrow Data Types
       * - :attr:`DB_TYPE_NUMBER`
         - DECIMAL128(p, s)
@@ -381,7 +382,7 @@ requested schema type.
           INT16
           INT32
           INT64
-          UINT8,
+          UINT8
           UINT16
           UINT32
           UINT64

doc/src/user_guide/introduction.rst

@@ -6,12 +6,24 @@
 Introduction to the Python Driver for Oracle Database
 *****************************************************
 
-The python-oracledb driver is a Python module that enables access to Oracle
-Database. It conforms to the `Python Database API v2.0 Specification
+The python-oracledb driver is an :ref:`open source <license>` Python module
+that enables access to Oracle Database with no extra libraries needed. The
+module is built with Cython for safety and speed. It is lightweight and
+high-performance. It is stable, well tested, and has comprehensive
+documentation. The module is maintained by Oracle.
+
+The module conforms to the `Python Database API v2.0 Specification
 <https://www.python.org/dev/peps/pep-0249/>`__ with a considerable number of
-additions and a couple of exclusions. Synchronous and :ref:`concurrent
-<asyncio>` coding styles are supported.  It is distributed under an open-source
-:ref:`license <license>`.
+additions and a couple of minor exclusions. It is used by many Python
+frameworks, SQL generators, ORMs, and libraries.
+
+Python-oracledb has a rich feature set which is easy to use. It gives you
+control over SQL and PL/SQL statement execution; for working with data frames;
+for fast data ingestion; for calling NoSQL-style document APIs; for message
+queueing; for receiving database notifications; and for starting and stopping
+the database. It also has high availability and security features. Synchronous
+and concurrent coding styles are supported. Database operations can optionally
+be pipelined.
 
 The module is available from standard package repositories including `PyPI
 <https://pypi.org/project/oracledb/>`__, `conda-forge
@@ -24,12 +36,12 @@ This module is currently tested with Python 3.9, 3.10, 3.11, 3.12, 3.13, and
 3.14 against Oracle Database 23, 21, 19, 18, 12, and 11.2. Previous versions of
 python-oracledb supported older Python versions.
 
-Changes in python-oracledb
-releases can be found in the :ref:`release notes <releasenotes>`.
+Changes in python-oracledb releases can be found in the :ref:`release notes
+<releasenotes>`.
 
 The python-oracledb driver is the renamed, major version successor to cx_Oracle
-8.3.  For upgrade information, see :ref:`upgrading83`. The cx_Oracle driver is
-obsolete and should not be used for new development.
+8.3. The cx_Oracle driver is obsolete and should not be used for new
+development. For upgrade information, see :ref:`upgrading83`.
 
 Getting Started
 ===============