Samll documentation changes.

Author: anthony-tuininga

NOTICE.txt

@@ -1 +1 @@
-Copyright (c) 2016, 2024, Oracle and/or its affiliates.
+Copyright (c) 2016, 2025, Oracle and/or its affiliates.

doc/src/api_manual/deprecations.rst

@@ -15,6 +15,17 @@ python-oracledb. The relevant functionality may be removed in a future version
 of python-oracledb. The cx_Oracle driver itself is obsolete and should not be
 used for new development.
 
+.. list-table-with-summary:: Deprecated in python-oracledb 3.4
+    :header-rows: 1
+    :class: wy-table-responsive
+    :summary: The first column, Name, displays the deprecated feature. The second column, Comments, includes information about the deprecation and the replacement to use, if applicable.
+    :name: _deprecations_3_4
+
+    * - Name
+      - Comments
+    * - The x86_64 macOS and 32-bit Windows platforms are deprecated. They will be desupported when the `cryptography <https://pypi.org/project/cryptography/>`__ package desupports them, see the `cryptography deprecation announcement <https://mail.python.org/archives/list/python-announce-list@python.org/thread/R4BZNC36MSFLKULA74KILLFY6GP3VCPA/>`__.
+      - Use arm64 macOS or 64-bit Windows instead.
+
 .. list-table-with-summary:: Deprecated in python-oracledb 3.0
     :header-rows: 1
     :class: wy-table-responsive
@@ -24,8 +35,7 @@ used for new development.
     * - Name
       - Comments
     * - Parameter ``pool`` of :meth:`oracledb.connect()` and :meth:`oracledb.connect_async()`
-      - Use :meth:`ConnectionPool.acquire()`, or make use of the
-        :ref:`connection pool cache <connpoolcache>` instead
+      - Use :meth:`ConnectionPool.acquire()`, or make use of the :ref:`connection pool cache <connpoolcache>` instead
 
 .. list-table-with-summary:: Desupported in python-oracledb 2.0
     :header-rows: 1
@@ -36,33 +46,21 @@ used for new development.
     * - Name
       - Comments
     * - ``oracledb.__future__.old_json_col_as_obj``
-      - VARCHAR2 and LOB columns created with the ``IS JSON`` check constraint
-        are now always fetched as JSON.  Use an :ref:`output type handler
-        <outputtypehandlers>` if the old behavior is required.
-    * - Parameters ``encoding`` and ``nencoding`` of :func:`oracledb.connect()`
-        and :func:`oracledb.create_pool()`, and the related attributes on the
-        objects created
-      - The driver encodings are always UTF-8. Remove uses of ``encoding`` and
-        ``nencoding`` from your code.
-    * - Parameter ``threaded`` of :func:`oracledb.connect()` and
-        :func:`oracledb.create_pool()`
+      - VARCHAR2 and LOB columns created with the ``IS JSON`` check constraint are now always fetched as JSON.  Use an :ref:`output type handler <outputtypehandlers>` if the old behavior is required.
+    * - Parameters ``encoding`` and ``nencoding`` of :func:`oracledb.connect()` and :func:`oracledb.create_pool()`, and the related attributes on the objects created
+      - The driver encodings are always UTF-8. Remove uses of ``encoding`` and ``nencoding`` from your code.
+    * - Parameter ``threaded`` of :func:`oracledb.connect()` and :func:`oracledb.create_pool()`
       - Threading is always used. Remove uses of ``threaded`` from your code.
-    * - Parameter ``waitTimeout`` of :func:`oracledb.create_pool()` and
-        ``oracledb.SessionPool()``
+    * - Parameter ``waitTimeout`` of :func:`oracledb.create_pool()` and ``oracledb.SessionPool()``
       - Replace with parameter ``wait_timeout``
-    * - Parameter ``maxLifetimeSession`` of :func:`oracledb.create_pool()` and
-        ``oracledb.SessionPool()``
+    * - Parameter ``maxLifetimeSession`` of :func:`oracledb.create_pool()` and ``oracledb.SessionPool()``
       - Replace with parameter ``max_lifetime_session``
-    * - Parameter ``sessionCallback`` of :func:`oracledb.create_pool()` and
-        ``oracledb.SessionPool()``
+    * - Parameter ``sessionCallback`` of :func:`oracledb.create_pool()` and ``oracledb.SessionPool()``
       - Replace with parameter ``session_callback``
-    * - Parameter ``maxSessionsPerShard`` of :func:`oracledb.create_pool()` and
-        ``oracledb.SessionPool()``
+    * - Parameter ``maxSessionsPerShard`` of :func:`oracledb.create_pool()` and ``oracledb.SessionPool()``
       - Replace with parameter ``max_sessions_per_shard``
-    * - Attribute ``maxBytesPerCharacter`` of the :ref:`Connection object
-        <connobj>`
-      - The driver encodings are always UTF-8 so this attribute can be replaced by
-        the constant value 4
+    * - Attribute ``maxBytesPerCharacter`` of the :ref:`Connection object <connobj>`
+      - The driver encodings are always UTF-8 so this attribute can be replaced by the constant value 4
     * - ``Connection.tnsentry``
       - Replace with :attr:`Connection.dsn`
     * - ``SessionPool.tnsentry``
@@ -76,16 +74,11 @@ used for new development.
 
     * - Name
       - Comments
-    * - Calling :meth:`Variable.setvalue()` with a string value when the
-        variable type is one of :data:`oracledb.DB_TYPE_BLOB`,
+    * - Calling :meth:`Variable.setvalue()` with a string value when the variable type is one of :data:`oracledb.DB_TYPE_BLOB`,
         :data:`oracledb.DB_TYPE_CLOB` or :data:`oracledb.DB_TYPE_NCLOB`.
-      - Call :meth:`Connection.createlob()` with the value instead and pass the
-        result to :meth:`Variable.setvalue()`.
-    * - Setting an attribute of type :data:`oracledb.DB_TYPE_BLOB`,
-        :data:`oracledb.DB_TYPE_CLOB` or :data:`oracledb.DB_TYPE_NCLOB` on a
-        database object to a string value.
-      - Call :meth:`Connection.createlob()` with the value instead and set the
-        attribute with the result.
+      - Call :meth:`Connection.createlob()` with the value instead and pass the result to :meth:`Variable.setvalue()`.
+    * - Setting an attribute of type :data:`oracledb.DB_TYPE_BLOB`, :data:`oracledb.DB_TYPE_CLOB` or :data:`oracledb.DB_TYPE_NCLOB` on a database object to a string value.
+      - Call :meth:`Connection.createlob()` with the value instead and set the attribute with the result.
 
 .. list-table-with-summary:: Deprecated in python-oracledb 1.4
     :header-rows: 1
@@ -95,10 +88,8 @@ used for new development.
 
     * - Name
       - Comments
-    * - Output type handler with arguments
-        ``handler(cursor, name, default_type, length, precision, scale)``
-      - Replace with ``handler(cursor, metadata)``. See
-        :ref:`outputtypehandlers`.
+    * - Output type handler with arguments ``handler(cursor, name, default_type, length, precision, scale)``
+      - Replace with ``handler(cursor, metadata)``. See :ref:`outputtypehandlers`.
 
 .. list-table-with-summary:: Deprecated in python-oracledb 1.0
     :header-rows: 1

doc/src/release_notes.rst

@@ -60,6 +60,12 @@ Common Changes
     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 when the `cryptography
+    <https://pypi.org/project/cryptography/>`__ package desupports them, see
+    the `cryptography deprecation announcement <https://mail.python.org/
+    archives/list/python-announce-list@python.org/thread/
+    R4BZNC36MSFLKULA74KILLFY6GP3VCPA/>`__.
 #)  Pin Cython to 3.1.x instead of 3.1.0 as requested
     (`issue 530 <https://github.com/oracle/python-oracledb/issues/530>`__).
 #)  Fixed bug when attempting to execute an empty statement
@@ -69,7 +75,8 @@ Common Changes
 #)  Fixed bug when attempting to append an element to a
     :ref:`DbObject <dbobjecttype>` which is not actually a collection.
 #)  API documentation is now generated from the source code.
-#)  Internal change: typing_extensions is now a dependency.
+#)  Internal change: `typing_extensions <https://pypi.org/project/
+    typing-extensions/>`__ is now a dependency.
 
 
 oracledb `3.3.0 <https://github.com/oracle/python-oracledb/compare/v3.2.0...v3.3.0>`__ (July 2025)

doc/src/user_guide/batch_statement.rst

@@ -494,6 +494,14 @@ be beneficial.
 See `samples/load_csv.py <https://github.com/oracle/python-oracledb/tree/main/
 samples/load_csv.py>`__ for a runnable example.
 
+You should also review whether Oracle's specialized data loading tools and
+features suit your environment. These can be faster than using Python. See
+`SQL*Loader <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=
+GUID-DD843EE2-1FAB-4E72-A115-21D97A501ECC>`__ and `External Tables
+<https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=
+GUID-44323E01-7D72-45EC-915A-99E596769D9E>`__.
+
+
 Creating CSV Files from Oracle Database
 ---------------------------------------
 

doc/src/user_guide/initialization.rst

@@ -106,13 +106,13 @@ More details and options are shown in the later sections:
   use Thin mode. The features supported by Thin mode can be found in
   :ref:`featuresummary`.
 
-- On any operating system, if you set ``lib_dir`` to the library directory of a
-  full database or full client installation (such as from running
-  ``runInstaller``), you will need to have previously set the Oracle environment,
-  for example by setting the ``ORACLE_HOME`` environment variable. Otherwise you
-  will get errors like ``ORA-1804``. You should set this variable, and other
-  Oracle environment variables, before starting Python, as shown in :ref:`Oracle
-  Environment Variables <envset>`.
+- On any operating system, if you set the ``lib_dir`` parameter to the library
+  directory of a full database or full client installation (such as from
+  running ``runInstaller``), you will need to have previously set the Oracle
+  environment, for example by setting the ``ORACLE_HOME`` environment
+  variable. Otherwise you will get errors like ``ORA-1804``. You should set
+  this variable, and other Oracle environment variables, before starting
+  Python, as shown in :ref:`Oracle Environment Variables <envset>`.
 
 - The :meth:`~oracledb.init_oracle_client()` function may be called multiple
   times in your application but must always pass the same arguments.

doc/src/user_guide/installation.rst

@@ -526,8 +526,8 @@ architecture. Note Oracle Database 23ai 32-bit clients are not available on any
 platform, however you can use older 32-bit clients to connect to Oracle
 Database 23ai.
 
-1. Set required Oracle environment variables by running the Oracle environment
-   script. For example:
+1. Set required Oracle environment variables, such as ``ORACLE_HOME``, by
+   running the Oracle environment script. For example:
 
    .. code-block:: shell
 

doc/src/user_guide/sql_execution.rst

@@ -494,11 +494,60 @@ Changing Query Results with Rowfactories
 Python-oracledb "rowfactories" are methods called for each row retrieved from
 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.
+can convert the tuple to a different value or representation.
+
+A rowfactory should be set on a cursor after a call to :meth:`Cursor.execute()`
+before fetching data from the cursor. Calling :meth:`~Cursor.execute()` again
+will clear any previous rowfactory.
+
+**Fetching Rows using a Data Class**
+
+Python `Data Classes <https://docs.python.org/3/library/dataclasses.html>`__
+provide a simple way to encapsulate data. An example of using them with a query
+rowfactory is:
+
+.. code-block:: python
+
+    import dataclasses
+    import datetime
+
+    . . .
+
+    @dataclasses.dataclass
+    class MyRow:
+        employee_id: int
+        last_name: str
+        hire_date: datetime.datetime
+
+    cursor.execute(
+        """select employee_id, last_name, hire_date
+           from employees
+           where employee_id < 105
+           order by employee_id""")
+
+    cursor.rowfactory = MyRow
+
+    for row in cursor:
+        print("Number:", row.employee_id)
+        print("Name:", row.last_name)
+        print("Hire Date:", row.hire_date)
+
+The output is::
+
+    Number: 100
+    Name: King
+    Hire Date: 2003-06-17 00:00:00
+    Number: 101
+    Name: Kochhar
+    Hire Date: 2005-09-21 00:00:00
+    Number: 102
+    Name: De Haan
+    Hire Date: 2001-01-13 00:00:00
 
 **Fetching Rows as Dictionaries**
 
-For example, to fetch each row of a query as a dictionary:
+To fetch each row of a query as a dictionary, you can use
+:meth:`Cursor.rowfactory` like:
 
 .. code-block:: python
 
@@ -515,7 +564,8 @@ The output is::
     'POSTAL_CODE': '00989', 'CITY': 'Roma', 'STATE_PROVINCE': None,
     'COUNTRY_ID': 'IT'}
 
-Also see how ``JSON_OBJECT`` is used in :ref:`jsondatatype`.
+Also see how ``JSON_OBJECT`` is used in :ref:`jsondatatype`, since querying
+directly as JSON may be preferable.
 
 If you join tables where the same column name occurs in both tables with
 different meanings or values, then use a column alias in the query.  Otherwise,

src/oracledb/cursor.py

@@ -455,6 +455,9 @@ def rowfactory(self) -> Callable:
         each row but if this attribute is set, the method is called with the
         tuple that would normally be returned, and the result of the method is
         returned instead.
+
+        The ``rowfactory`` attribute should be set after each statement
+        execution before data is fetched from the cursor.
         """
         self._verify_open()
         return self._impl.rowfactory