Small doc updates.

Author: anthony-tuininga

doc/src/index.rst

@@ -2,7 +2,9 @@ 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 new name for the cx_Oracle driver.
+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.
 
 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/user_guide/appendix_a.rst

@@ -9,8 +9,9 @@ Oracle Database.  This mode does not need Oracle Client libraries.  However,
 some additional functionality is available when python-oracledb uses them.
 Python-oracledb is said to be in 'Thick' mode when Oracle Client libraries are
 used.  Both modes have comprehensive functionality supporting the Python
-Database API v2.0 Specification.  See :ref:`initialization` for how to enable
-Thick mode.
+Database API v2.0 Specification `PEP 249
+<https://peps.python.org/pep-0249/>`__.  See :ref:`initialization` for how to
+enable Thick mode.
 
 The following table summarizes the Oracle Database features supported by
 python-oracledb Thin and Thick modes, and by cx_Oracle 8.3.  For more details
@@ -26,10 +27,6 @@ see :ref:`driverdiff` and :ref:`compatibility`.
       - python-oracledb Thin Mode
       - python-oracledb Thick Mode
       - cx_Oracle 8.3
-    * - Python Database API Support (see `PEP 249 <https://peps.python.org/pep-0249/>`__)
-      - Yes - a couple of features are not feasible. Many extensions.
-      - Yes - a couple of features are not feasible. Many extensions.
-      - Yes - a couple of features are not feasible. Many extensions.
     * - Oracle Client version
       - Not applicable
       - Release 11.2 and later

doc/src/user_guide/appendix_c.rst

@@ -7,6 +7,7 @@ Appendix C: The python-oracledb and cx_Oracle Drivers
 The python-oracledb driver is the renamed, major version successor to cx_Oracle
 8.3. As a major release, the python-oracledb driver has :ref:`new features
 <releasenotes>` and some :ref:`deprecations`.  Also see :ref:`upgrading83`.
+The cx_Oracle driver is obsolete and should not be used for new development.
 
 .. _compatibility:
 

doc/src/user_guide/installation.rst

@@ -7,9 +7,9 @@ Installing python-oracledb
 The python-oracledb driver allows Python 3 applications to connect to Oracle
 Database.
 
-Python-oracledb is the new name for the Python `cx_Oracle driver
-<https://oracle.github.io/python-cx_Oracle/>`__.  If you are upgrading from
-cx_Oracle, see :ref:`upgrading83`.
+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.
 
 .. figure:: /images/python-oracledb-thin-arch.png
    :alt: architecture of the python-oracledb driver

doc/src/user_guide/introduction.rst

@@ -26,7 +26,8 @@ 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`.
+8.3.  For upgrade information, see :ref:`upgrading83`. The cx_Oracle driver is
+obsolete and should not be used for new development.
 
 Getting Started
 ===============

doc/src/user_guide/sql_execution.rst

@@ -180,7 +180,7 @@ To extract the column names from a query you can use code like:
 
     with connection.cursor() as cursor:
         cursor.execute("select * from locations")
-        columns = [col[0] for col in cursor.description]
+        columns = [col.name for col in cursor.description]
         print(columns)
         for r in cursor:
             print(r)
@@ -192,6 +192,22 @@ This will print::
     (1100, '93091 Calle della Testa', '10934', 'Venice', None, 'IT')
     . . .
 
+**Changing Column Names to Lowercase**
+
+To change all column names to lowercase you could do:
+
+.. code-block:: python
+
+    cursor.execute("select * from locations where location_id = 1000")
+
+    columns = [col.name.lower() for col in cursor.description]
+    print(columns)
+
+The output is::
+
+    ['location_id', 'street_address', 'postal_code', 'city', 'state_province',
+    'country_id']
+
 .. _defaultfetchtypes:
 
 Fetch Data Types
@@ -452,13 +468,15 @@ the database. The :meth:`Cursor.rowfactory` method is called with the tuple
 fetched from the database before it is returned to the application.  The method
 can convert the tuple to a different value.
 
+**Fetching Rows as Dictionaries**
+
 For example, to fetch each row of a query as a dictionary:
 
 .. code-block:: python
 
     cursor.execute("select * from locations where location_id = 1000")
 
-    columns = [col[0] for col in cursor.description]
+    columns = [col.name for col in cursor.description]
     cursor.rowfactory = lambda *args: dict(zip(columns, args))
     data = cursor.fetchone()
     print(data)
@@ -484,8 +502,11 @@ only one of the similarly named columns will be included in the dictionary:
         dogs.color
     from cats, dogs
 
+**Example with an Output Type Handler, Outconverter, and Row Factory**
+
 An example showing an :ref:`output type handler <outputtypehandlers>`, an
-:ref:`outconverter <outconverters>`, and a row factory is:
+:ref:`outconverter <outconverters>`, and a :ref:`row factory <rowfactories>`
+is:
 
 .. code-block:: python
 
@@ -505,17 +526,17 @@ An example showing an :ref:`output type handler <outputtypehandlers>`, an
 
     cursor.execute("select 123 as col1, 'abc' as col2 from dual")
 
-    columns = [col[0] for col in cursor.description]
+    columns = [col.name.lower() for col in cursor.description]
     cursor.rowfactory = lambda *args: dict(zip(columns, args))
     for r in cursor.fetchall():
         print(r)
 
 The database converts the number to a string before it is returned to
-python-oracledb.  The outconverter appends "was a string" to this value.
-Finally the row factory changes the complete row to a dictionary.  The output
-is::
+python-oracledb. The outconverter appends "was a string" to this value. The
+column names are converted to lowercase. Finally, the row factory changes the
+complete row to a dictionary. The output is::
 
-    {'COL1': '123 was a string', 'COL2': 'abc'}
+    {'col1': '123 was a string', 'col2': 'abc'}
 
 .. _numberprecision: