Doc updates.

Author: anthony-tuininga

README.md

@@ -30,7 +30,7 @@ Run:
 python -m pip install oracledb --upgrade
 ```
 
-See [python-oracledb Installation][installation] for details.
+See [Installing python-oracledb][installation] for details.
 
 ## Samples
 

doc/src/release_notes.rst

@@ -3048,8 +3048,7 @@ cx_Oracle 6.0 beta 1 (April 2017)
     :ref:`subscription objects <subscrobj>`. Use the qos attribute instead.
 #)  Dropped deprecated parameters cqqos and rowids from the
     :meth:`Connection.subscribe()` method. Use the qos parameter instead as
-    shown in this `sample <https://github.com/oracle/python-cx_Oracle/blob/
-    main/samples/cqn.py>`__.
+    shown in the cx_Oracle sample cqn.py.
 
 
 cx_Oracle 5.3 (March 2017)

doc/src/user_guide/appendix_c.rst

@@ -4,10 +4,10 @@
 Appendix C: The python-oracledb and cx_Oracle Drivers
 *****************************************************
 
-The python-oracledb driver is the renamed, major version successor to cx_Oracle
-8.3. The python-oracledb driver has many :ref:`new features <releasenotes>` and
-some :ref:`deprecations` compared with cx_Oracle. The cx_Oracle driver is
-obsolete and should not be used for new development.
+The python-oracledb driver is the renamed, successor to cx_Oracle. The
+python-oracledb driver has many :ref:`new features <releasenotes>` and some
+:ref:`deprecations` compared with cx_Oracle. The cx_Oracle driver is obsolete
+and should not be used for new development.
 
 .. _upgrading83:
 

doc/src/user_guide/authentication_methods.rst

@@ -149,8 +149,8 @@ Using an Oracle Wallet for External Authentication
 
 The following steps give an overview of using an Oracle Wallet.  Wallets should
 be kept securely.  Wallets can be managed with `Oracle Wallet Manager
-<https://www.oracle.com/pls/topic/lookup?ctx=dblatest&
-id=GUID-E3E16C82-E174-4814-98D5-EADF1BCB3C37>`__.
+<https://docs.oracle.com/en/database/oracle/oracle-database/21/dbimi/using-
+oracle-wallet-manager.html#GUID-E3E16C82-E174-4814-98D5-EADF1BCB3C37>`__.
 
 In this example the wallet is created for the ``myuser`` schema in the
 directory ``/home/oracle/wallet_dir``.  The ``mkstore`` command is available
@@ -690,8 +690,7 @@ the following table.
       - Description
       - Required or Optional
     * - ``auth_type``
-      - The authentication type. The value should be the string "ConfigFileAuthentication",
-        "InstancePrincipal", "SecurityToken", "SecurityTokenSimple" or "SimpleAuthentication".
+      - The authentication type. The value should be the string "ConfigFileAuthentication", "InstancePrincipal", "SecurityToken", "SecurityTokenSimple" or "SimpleAuthentication".
 
         With Configuration File Authentication, the location of a configuration file containing the necessary information must be provided. By default, this file is located at */home/username/.oci/config*, unless a custom location is specified during OCI IAM setup.
 
@@ -708,8 +707,7 @@ the following table.
     * - ``user``
       - The Oracle Cloud Identifier (OCID) of the user invoking the API. For example, *ocid1.user.oc1..<unique_ID>*.
 
-        This parameter can be specified when the value of the ``auth_type`` key is "SimpleAuthentication". This is not required when ``auth_type`` is
-        "SecurityToken" or "SecurityTokenSimple"
+        This parameter can be specified when the value of the ``auth_type`` key is "SimpleAuthentication". This is not required when ``auth_type`` is "SecurityToken" or "SecurityTokenSimple"
       - Required
     * - ``key_file``
       - The full path and filename of the private key.

doc/src/user_guide/batch_statement.rst

@@ -523,8 +523,12 @@ Depending on data sizes and business requirements, database changes such as
 temporarily disabling redo logging on the table, or disabling indexes may also
 be beneficial.
 
+The PyArrow package's CSV methods may be more efficient than the default CSV
+module.
+
 See `samples/load_csv.py <https://github.com/oracle/python-oracledb/tree/main/
-samples/load_csv.py>`__ for a runnable example.
+samples/load_csv.py>`__ for a runnable example showing both the CSV module and
+PyArrow's CSV functionality.
 
 You should also review whether Oracle's specialized data loading tools and
 features suit your environment. These can be faster than using Python. See

doc/src/user_guide/connection_handling.rst

@@ -3958,6 +3958,8 @@ its own directory.  For each connection use different connection string
 file.  It is recommended to use Oracle Client libraries 19.17 (or later) when
 using :ref:`multiple wallets <connmultiwallets>`.
 
+If you are behind a firewall, see :ref:`firewallproxy`.
+
 Using the Easy Connect Syntax with Oracle Autonomous Database
 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 

doc/src/user_guide/extending.rst

@@ -137,16 +137,15 @@ packages, you can create a `namespace package <https://packaging.python.org/en
 can distribute plugin packages either internally within your organization, or
 on a package repository such as `PyPI <https://pypi.org/>`__.
 
+**Example 1**
+
 The following example creates a plugin that uses a :ref:`connection protocol
 hook function <registerprotocolhook>` to do special processing of connection
 strings prefixed with "myprefix://".
 
-1. In a terminal or IDE, create a working directory, for example ``myplugin``.
-   Inside the working directory create the subdirectory hierarchy
-   ``src/oracledb/plugins/``::
+1. In a terminal or IDE, create a working directory, for example ``myplugin``::
 
     mkdir myplugin
-    mkdir -p myplugin/src/oracledb/plugins
 
 2. In the ``myplugin`` directory, create the following files:
 
@@ -181,7 +180,14 @@ strings prefixed with "myprefix://".
            [options.packages.find]
            where = src
 
-3. Create the plugin code in ``myplugin/src/oracledb/plugins/myplugin.py``:
+3. In the ``myplugin`` directory, create the subdirectory hierarchy
+   ``src/oracledb/plugins/``:
+
+   .. code-block:: shell
+
+        mkdir -p src/oracledb/plugins
+
+4. Create the plugin's code in ``myplugin/src/oracledb/plugins/myplugin.py``:
 
   .. code-block:: python
 
@@ -193,18 +199,25 @@ strings prefixed with "myprefix://".
 
         oracledb.register_protocol("myprefix", myhookfunc)
 
+5. In the ``myplugin`` directory, build the sample package:
 
-4. Build the sample package::
+   .. code-block:: shell
 
-        cd myplugin
         python -m pip install build
         python -m build
 
-5. Install the sample package::
+   This creates your plugin package wheel in the ``dist`` subdirectory with a
+   name like ``myplugin-1.0.0-py3-none-any.whl``. You can distribute and
+   install this package.
+
+6. Install the sample package:
+
+   .. code-block:: shell
 
         python -m pip install dist/myplugin-1.0.0-py3-none-any.whl
 
-6. To show the plugin being used, create an application file containing:
+7. To show the plugin in use, create an application file in a working directory
+   containing:
 
    .. code-block:: python
 
@@ -223,14 +236,18 @@ strings prefixed with "myprefix://".
         In myhookfunc: protocol=myprefix arg=localhost/orclpdb
         host=localhost, port=1521, service name=orclpdb
 
-7. To uninstall the plugin, simply remove the package::
+8. To uninstall the plugin, remove the package:
+
+   .. code-block:: shell
 
        python -m pip uninstall myplugin
 
-Another sample plugin shows how all connection creations can be logged,
+**Example 2**
+
+The following sample plugin shows how all connection creations can be logged,
 regardless of the connection string. If the plugin
-``myplugin/src/oracledb/plugins/myplugin.py`` registers a :ref:`connection
-parameter hook <paramshook>`:
+``myplugin/src/oracledb/plugins/myplugin.py`` created above contained code to
+register a :ref:`connection parameter hook <paramshook>`:
 
 .. code-block:: python
 

doc/src/user_guide/globalization.rst

@@ -66,8 +66,11 @@ Time Zone Files
 This section applies to python-oracledb Thick mode.
 
 Oracle Client libraries and the Oracle Database use time zone files for date
-operations.  The files are versioned, but do not always have to be the same
-version on the database and client.
+operations. The files are versioned, but do not always have to be the same
+version on the database and client. However, if you use the TIMESTAMP WITH
+TIMEZONE data type and have a named time zone, you will get the error `ORA-1805
+<https://docs.oracle.com/en/error-help/db/ora-01805/>`__ when the database and
+the client time zone file versions differ.
 
 Finding the Time Zone Files in Use
 ----------------------------------
@@ -113,6 +116,18 @@ The Oracle Database documentation contains more information about time zone
 files, see `Choosing a Time Zone File <https://www.oracle.com/pls/topic/
 lookup?ctx=dblatest&id=GUID-805AB986-DE12-4FEA-AF56-5AABCD2132DF>`__.
 
+Changing the Oracle Database Time Zone File
+-------------------------------------------
+
+To control the database time zone file in on-premise databases, use the
+`DBMS_DST <https://www.oracle.com/pls/topic/lookup?ctx=
+dblatest&id=GUID-55300506-481A-4957-A67D-0183D3D986DF>`__ package.
+
+For Oracle Autonomous Database, use ``AUTO_DST_UPGRADE`` and
+``AUTO_DST_UPGRADE_EXCL_DATA`` as shown in the documentation `Manage Time Zone
+File Updates on Autonomous AI Database <https://www.oracle.com/pls/topic/
+lookup?ctx=dblatest&id=GUID-BACC9C4A-C0FA-4912-862A-1A2A24D6A0C2>`__.
+
 Changing the Oracle Client Time Zone File
 -----------------------------------------
 

doc/src/user_guide/initialization.rst

@@ -13,6 +13,15 @@ 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.
 
+Most applications can use python-oracledb Thin mode. The common reasons to use
+Thick mode are:
+
+- Your Oracle Database is version 11, or older
+- Your database connections require :ref:`Native Network Encryption (NNE) or
+  checksumming <nne>`
+- You desire to use :ref:`Application Continuity (AC) or Transparent
+  Application Continuity (TAC) <appcont>`
+
 All connections in an application use the same mode.  See :ref:`vsessconinfo`
 to verify which mode is in use.
 
@@ -622,7 +631,7 @@ The common environment variables listed below are supported in python-oracledb.
     * - NLS_LANG
       - Determines the 'national language support' globalization options for python-oracledb.
 
-        Note that from cx_Oracle 8, the character set component is ignored and only the language and territory components of ``NLS_LANG`` are used. The character set can instead be specified during connection or connection pool creation. See :ref:`globalization`.
+        Note that the character set component is ignored and only the language and territory components of ``NLS_LANG`` are used. The character set can instead be specified during connection or connection pool creation. See :ref:`globalization`.
       - Thick
     * - ORA_SDTZ
       - The default session time zone.

doc/src/user_guide/installation.rst

@@ -7,11 +7,7 @@ Installing python-oracledb
 ***************************
 
 The python-oracledb driver allows Python applications to connect to Oracle
-Database.
-
-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.
+Database with no extra libraries needed.
 
 .. figure:: /images/python-oracledb-thin-arch.png
    :alt: architecture of the python-oracledb driver
@@ -31,9 +27,10 @@ Specification.
 Quick Start python-oracledb Installation
 ========================================
 
-Python-oracledb is typically installed from Python's package repository
-`PyPI <https://pypi.org/project/oracledb/>`__ using `pip
-<https://pip.pypa.io/en/latest/installation/>`__.
+Python-oracledb is typically installed from Python's package repository `PyPI
+<https://pypi.org/project/oracledb/>`__ using `pip
+<https://pip.pypa.io/en/latest/installation/>`__ or `uv
+<https://pypi.org/project/uv/>`__.
 
 1. Install `Python 3 <https://www.python.org/downloads>`__ if it is not already
    available.
@@ -208,22 +205,14 @@ resulting binary installed.  Compiling python-oracledb requires the
 this file is in the ``python-devel`` package or equivalent.
 
 On some platforms the Python binary may be called ``python3`` instead of
-``python``.  For example, to use the default Python 3.6 installation on Oracle
-Linux 8, install with:
-
-.. code-block:: shell
-
-    python3 -m pip install oracledb --upgrade
-
-Note it is recommended to use a more recent version Python, see `Python for
-Oracle Linux <https://yum.oracle.com/oracle-linux-python.html>`__.
+``python``.
 
 The installation ``--user`` option is useful when you do not have permission to
 write to system directories:
 
 .. code-block:: shell
 
-    python3 -m pip install oracledb --upgrade --user
+    python -m pip install oracledb --upgrade --user
 
 If you are behind a proxy, use the ``--proxy`` option. For example: