Doc and sample improvements.

Author: anthony-tuininga

doc/src/api_manual/async_connection.rst

@@ -44,9 +44,8 @@ AsyncConnection Methods
 .. method:: AsyncConnection.begin_sessionless_transaction(transaction_id=None, \
             timeout=60, defer_round_trip=False)
 
-    Begins a new sessionless transaction using the specified transaction
-    identifier. This method returns the transaction identifier specified by the
-    user or generated by python-oracledb.
+    Begins a new sessionless transaction. This method returns the transaction
+    identifier specified by the user or generated by python-oracledb.
 
     The ``transaction_id`` parameter should be of type string or bytes. If
     specified, it represents a unique identifier for the transaction. If a
@@ -59,7 +58,11 @@ AsyncConnection Methods
     exceed 64 bytes in length.
 
     The ``timeout`` parameter is the number of seconds that this transaction
-    can be resumed by a connection the next time that it is suspended. The
+    can stay suspended when
+    :meth:`AsyncConnection.suspend_sessionless_transaction()` is later called,
+    or if the transaction is automatically suspended when the
+    ``suspend_on_success`` parameter is set to to *True* in
+    :meth:`AsyncCursor.execute()` or :meth:`AsyncCursor.executemany()`. The
     default value is *60* seconds. If a transaction is not resumed within this
     specified duration, the transaction will be rolled back.
 
@@ -337,24 +340,20 @@ AsyncConnection Methods
 
     The ``timeout`` parameter is the number of seconds that the current
     connection waits to resume a transaction if another connection is using it.
-    This timeout is only effective when the transaction is in use by another
-    connection. In this case, the current connection waits for the transaction
-    to be suspended within this timeout period. When ``defer_round_trip`` is
-    set to *False*, the wait happens in the
+    When ``defer_round_trip`` is set to *False*, the wait happens in the
     ``resume_sessionless_transaction()`` call itself, and the function blocks
-    until the transaction becomes available or the timeout expires.
-    When ``defer_round_trip`` is set to *True*, the resume is deferred and the
-    wait occurs at the time of the next database operation instead. At the
-    start of the wait period, if the transaction is not in use by any other
-    connection, the resume happens immediately. If the transaction remains in
-    use by the other connection after the timeout period, the error `ORA-25351
+    until the transaction becomes available or the timeout expires.  When
+    ``defer_round_trip`` is set to *True*, the resume is deferred and the wait
+    occurs at the time of the next database operation instead. At the start of
+    the wait period, if the transaction is not in use by any other connection,
+    the resume happens immediately. If the transaction remains in use by the
+    other connection after the timeout period, the error `ORA-25351
     <https://docs.oracle.com/en/error-help/db/ora-25351>`__ is raised. If
     another connection completes the transaction, the error `ORA-24756
     <https://docs.oracle.com/en/error-help/db/ora-24756>`__ is raised. These
     error messages are only thrown for non-RAC instances. For information on
-    using Oracle RAC, see
-    :ref:`Sessionless Transactions with Oracle RAC <sessionlesstxnswithrac>`.
-    The default value is *60* seconds.
+    using Oracle RAC, see :ref:`Sessionless Transactions with Oracle RAC
+    <sessionlesstxnswithrac>`.  The default value is *60* seconds.
 
     The ``defer_round_trip`` parameter is a boolean that determines whether
     the request to resume a transaction is to be sent immediately or with the
@@ -404,9 +403,10 @@ AsyncConnection Methods
 
     This detaches the transaction from the connection, allowing it to be
     resumed later with the transaction identifier that was specified during
-    creation of the sessionless transaction. Also, the timeout value defined in
-    :meth:`AsyncConnection.begin_sessionless_transaction()` comes into effect
-    and determines how long the transaction can stay suspended.
+    creation of the sessionless transaction. The ``timeout`` previously passed
+    to :meth:`AsyncConnection.begin_sessionless_transaction()` determines how
+    long the transaction can stay suspended before it is automatically rolled
+    back.
 
     See :ref:`sessionlesstxns`.
 

doc/src/api_manual/connection.rst

@@ -49,9 +49,8 @@ Connection Methods
 .. method:: Connection.begin_sessionless_transaction(transaction_id=None, \
             timeout=60, defer_round_trip=False)
 
-    Begins a new sessionless transaction using the specified transaction
-    identifier. This method returns the transaction identifier specified by the
-    user or generated by python-oracledb.
+    Begins a new sessionless transaction. This method returns the transaction
+    identifier specified by the user or generated by python-oracledb.
 
     The ``transaction_id`` parameter should be of type string or bytes. If
     specified, it represents a unique identifier for the transaction. If a
@@ -64,9 +63,13 @@ Connection Methods
     64 bytes in length.
 
     The ``timeout`` parameter is the number of seconds that this transaction
-    can be resumed by a connection the next time that it is suspended. The
-    default value is *60* seconds. If a transaction is not resumed within this
-    specified duration, the transaction will be rolled back.
+    can stay suspended when
+    :meth:`Connection.suspend_sessionless_transaction()` is later called, or if
+    the transaction is automatically suspended when the ``suspend_on_success``
+    parameter is set to to *True* in :meth:`Cursor.execute()` or
+    :meth:`Cursor.executemany()`. The default value is *60* seconds. If a
+    transaction is not resumed within this specified duration, the transaction
+    will be rolled back.
 
     The ``defer_round_trip`` parameter is a boolean that determines whether
     the request to start a transaction is to be sent immediately or with the
@@ -322,24 +325,20 @@ Connection Methods
 
     The ``timeout`` parameter is the number of seconds that the current
     connection waits to resume a transaction if another connection is using it.
-    This timeout is only effective when the transaction is in use by another
-    connection. In this case, the current connection waits for the transaction
-    to be suspended within this timeout period. When ``defer_round_trip`` is
-    set to *False*, the wait happens in the
+    When ``defer_round_trip`` is set to *False*, the wait happens in the
     ``resume_sessionless_transaction()`` call itself, and the function blocks
-    until the transaction becomes available or the timeout expires.
-    When ``defer_round_trip`` is set to *True*, the resume is deferred and the
-    wait occurs at the time of the next database operation instead. At the
-    start of the wait period, if the transaction is not in use by any other
-    connection, the resume happens immediately. If the transaction remains in
-    use by the other connection after the timeout period, the error `ORA-25351
+    until the transaction becomes available or the timeout expires.  When
+    ``defer_round_trip`` is set to *True*, the resume is deferred and the wait
+    occurs at the time of the next database operation instead. At the start of
+    the wait period, if the transaction is not in use by any other connection,
+    the resume happens immediately. If the transaction remains in use by the
+    other connection after the timeout period, the error `ORA-25351
     <https://docs.oracle.com/en/error-help/db/ora-25351>`__ is raised. If
     another connection completes the transaction, the error `ORA-24756
     <https://docs.oracle.com/en/error-help/db/ora-24756>`__ is raised. These
     error messages are only thrown for non-RAC instances. For information on
-    using Oracle RAC, see
-    :ref:`Sessionless Transactions with Oracle RAC <sessionlesstxnswithrac>`.
-    The default value is *60* seconds.
+    using Oracle RAC, see :ref:`Sessionless Transactions with Oracle RAC
+    <sessionlesstxnswithrac>`.  The default value is *60* seconds.
 
     The ``defer_round_trip`` parameter is a boolean that determines whether
     the request to resume a transaction is to be sent immediately or with the
@@ -499,9 +498,9 @@ Connection Methods
 
     This detaches the transaction from the connection, allowing it to be
     resumed later with the transaction identifier that was specified during
-    creation of the sessionless transaction. Also, the timeout value defined in
-    :meth:`Connection.begin_sessionless_transaction()` comes into effect and
-    determines how long the transaction can stay suspended.
+    creation of the sessionless transaction. The ``timeout`` previously passed
+    to :meth:`Connection.begin_sessionless_transaction()` determines how long
+    the transaction can stay suspended before it is automatically rolled back.
 
     See :ref:`sessionlesstxns`.
 

doc/src/api_manual/module.rst

@@ -2322,14 +2322,15 @@ Oracledb Methods
 
 .. function:: is_thin_mode()
 
-    Returns a boolean indicating if Thin mode is in use.
+    Returns a boolean indicating if python-oracledb is in Thin mode.
 
     Immediately after python-oracledb is imported, this function will return
-    *True* indicating that python-oracledb defaults to Thin mode. If
-    :func:`oracledb.init_oracle_client()` is called, then a subsequent call to
-    ``is_thin_mode()`` will return False indicating that Thick mode is
-    enabled. Once the first standalone connection or connection pool is
-    created, or a call to ``oracledb.init_oracle_client()`` is made, then
+    *True* indicating that python-oracledb defaults to Thin mode. If a call to
+    :func:`oracledb.init_oracle_client()` returns successfully, then a
+    subsequent call to ``is_thin_mode()`` will return False indicating that
+    Thick mode is enabled. Once the first standalone connection or connection
+    pool is created, or a successful call to ``oracledb.init_oracle_client()``
+    is made, or :meth:`oracledb.enable_thin_mode()` is called, then
     python-oracledb’s mode is fixed and the value returned by
     ``is_thin_mode()`` will never change for the lifetime of the process.
 

doc/src/release_notes.rst

@@ -30,7 +30,7 @@ Thin Mode Changes
     bind variable immediately following a query that returned multiple
     duplicate rows.
 #)  Fixed bug with connect strings containing ``SOURCE_ROUTE=YES`` where the
-    second host is unresolvable by the client.
+    second host is unresolvable by the host running python-oracledb.
 
 Thick Mode Changes
 ++++++++++++++++++
@@ -53,22 +53,27 @@ Common Changes
       :ref:`dfinsert`.
     - Added internal support for the ArrowArrayStream PyCapsule interface to
       simplify :ref:`DataFrame <oracledataframeobj>` use.
-    - Remove use of the DataFrame Interchange Protocol in python-oracledb
+    - Removed use of the DataFrame Interchange Protocol in python-oracledb
       :ref:`DataFrame <oracledataframeobj>` objects.
+    - Removed the prefix "Oracle" from the data frame object names. They are
+      now called :ref:`DataFrame <oracledataframeobj>` and :ref:`ArrowArray
+      <oraclearrowarrayobj>`.
     - Documentation on methods and attributes of the :ref:`DataFrame
       <oracledataframeobj>` and :ref:`ArrowArray <oraclearrowarrayobj>` objects
       is now available when using IDE introspection.
     - Upgraded Arrow C Data (nanoarrow) API version to 0.7.0.
-    - Ensure that the GIL is held when releasing references to :ref:`ArrowArray
+    - Ensured that the `Python GIL
+      <https://docs.python.org/3/glossary.html#term-global-interpreter-lock>`__
+      is held when releasing references to :ref:`ArrowArray
       <oraclearrowarrayobj>` objects when exported Arrow buffers are released
       by the consumer. This avoids a segfault seen in some circumstances.
-    - Fixed bug when deciding Arrow datatype for numeric expressions
+    - Fixed bug when deciding Arrow datatype for numeric expressions.
       (`issue 510 <https://github.com/oracle/python-oracledb/issues/510>`__)
     - Fixed bug when fetching numeric data that has no decimal point but the
-      Arrow array has scale > 0
-    - Fixed bug when fetching dates that are in the year 2038 or later
+      Arrow array has scale > 0.
+    - Fixed bug when fetching dates that are in the year 2038 or later.
     - Fixed bug when fetching numeric data with precision that exceeds 38 as
-      decimal data
+      decimal data.
 
     Note the data frame support in python-oracledb 3.3 is a pre-release, and
     may change in a future version.

doc/src/user_guide/dataframes.rst

@@ -664,7 +664,8 @@ For general information about fast data ingestion, and discussion of
 :meth:`Cursor.executemany()` and :meth:`AsyncCursor.executemany()` options, see
 :ref:`batchstmnt`.
 
-**Explicit Conversion to DataFrame or ArrowArray**
+Explicit Conversion to DataFrame or ArrowArray
+==============================================
 
 Data frames that support the Apache Arrow PyCapsule Interface can be explicitly
 converted to :ref:`DataFrame <oracledataframeobj>` and :ref:`ArrowArray

doc/src/user_guide/txn_management.rst

@@ -196,10 +196,13 @@ You can pass the following parameters to
   :meth:`~Connection.begin_sessionless_transaction`. An example is
   "36b8f84d-df4e-4d49-b662-bcde71a8764f".
 
-- ``timeout``: This parameter determines the duration that this transaction
-  can be resumed by a connection the next time that it is suspended. The
-  default value is *60* seconds. If the transaction is not resumed within
-  the specified duration, the transaction will be rolled back.
+- ``timeout``: This parameter is the number of seconds this transaction can
+  stay suspended when :meth:`Connection.suspend_sessionless_transaction()` is
+  later called, or if the transaction is automatically suspended when the
+  ``suspend_on_success`` parameter is set to to *True* in
+  :meth:`Cursor.execute()` or :meth:`Cursor.executemany()`. The default value
+  is *60* seconds. If the transaction is not resumed within the specified
+  duration, the transaction will be rolled back.
 
 - ``defer_round_trip``: This parameter determines whether the request to start
   a sessionless transaction should be sent immediately or with the next

samples/sessionless_transactions.py

@@ -0,0 +1,157 @@
+# -----------------------------------------------------------------------------
+# Copyright (c) 2025 Oracle and/or its affiliates.
+#
+# This software is dual-licensed to you under the Universal Permissive License
+# (UPL) 1.0 as shown at https://oss.oracle.com/licenses/upl and Apache License
+# 2.0 as shown at http://www.apache.org/licenses/LICENSE-2.0. You may choose
+# either license.
+#
+# If you elect to accept the software under the Apache License, Version 2.0,
+# the following applies:
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# -----------------------------------------------------------------------------
+
+# -----------------------------------------------------------------------------
+# sessionless_transactions.py
+#
+# Show Oracle Database 23ai Sessionless Transactions
+# -----------------------------------------------------------------------------
+
+import sys
+
+import oracledb
+import sample_env
+
+# determine whether to use python-oracledb thin mode or thick mode
+if not sample_env.get_is_thin():
+    oracledb.init_oracle_client(lib_dir=sample_env.get_oracle_client())
+
+# this script only works with Oracle Database 23.6 or later
+if sample_env.get_server_version() < (23, 6):
+    sys.exit("This example requires Oracle Database 23.6 or later.")
+
+# this script works with thin mode, or with thick mode using Oracle Client
+# 23.6 or later
+if not oracledb.is_thin_mode() and oracledb.clientversion()[:2] < (23, 6):
+    sys.exit(
+        "This example requires python-oracledb thin mode, or Oracle Client"
+        " 23.6 or later"
+    )
+
+TXN_ID = b"my_transaction_id"
+
+pool = oracledb.create_pool(
+    user=sample_env.get_main_user(),
+    password=sample_env.get_main_password(),
+    dsn=sample_env.get_connect_string(),
+    params=sample_env.get_pool_params(),
+)
+
+# -----------------------------------------------------------------------------
+# Basic Sessionless Transaction example
+
+print("Example 1:")
+
+# Start and suspend a transaction
+with pool.acquire() as connection1:
+
+    # Immediately begin the transaction
+    connection1.begin_sessionless_transaction(transaction_id=TXN_ID)
+
+    with connection1.cursor() as cursor1:
+        cursor1.execute(
+            "insert into mytab(id, data) values (:i, :d)", [1, "Sessionless 1"]
+        )
+    connection1.suspend_sessionless_transaction()
+
+    # Since the transaction is suspended, there will be no rows
+    print("1st query")
+    with connection1.cursor() as cursor1b:
+        for r in cursor1b.execute("select * from mytab"):
+            print(r)
+
+# Resume and complete the transaction in a different connection
+with pool.acquire() as connection2:
+
+    # Immediately resume the transaction
+    connection2.resume_sessionless_transaction(transaction_id=TXN_ID)
+
+    with connection2.cursor() as cursor2:
+        cursor2.execute(
+            "insert into mytab(id, data) values (:i, :d)", [2, "Sessionless 2"]
+        )
+
+        # The query will show both rows inserted
+        print("2nd query")
+        for r in cursor2.execute("select * from mytab order by id"):
+            print(r)
+
+    # Rollback so the example can be run multiple times.
+    # This concludes the Sessionless Transaction
+    connection2.rollback()
+
+# -----------------------------------------------------------------------------
+# Sessionless Transaction example with custom timeouts and round-trip
+# optimizations
+
+print("Example 2:")
+
+# Start and suspend a transaction
+with pool.acquire() as connection3:
+
+    connection3.begin_sessionless_transaction(
+        transaction_id=TXN_ID,
+        # The transaction can only ever be suspended for 15 seconds before it
+        # is automatically rolled back
+        timeout=15,
+        # Only start the transaction when the next DB operation is performed
+        defer_round_trip=True,
+    )
+    with connection3.cursor() as cursor3:
+        cursor3.execute(
+            "insert into mytab(id, data) values (:i, :d)",
+            [3, "Sessionless 3"],
+            suspend_on_success=True,  # automatically suspend on success
+        )
+
+    # Since the transaction is suspended, there will be no rows
+    print("1st query")
+    with connection3.cursor() as cursor3b:
+        for r in cursor3b.execute("select * from mytab"):
+            print(r)
+
+# Resume and complete the transaction in a different connection
+with pool.acquire() as connection4:
+    connection4.resume_sessionless_transaction(
+        transaction_id=TXN_ID,
+        # Only wait 20 seconds if someone else is using the transaction
+        timeout=20,
+        # Only initiate resuming the transaction when the next DB operation is
+        # performed
+        defer_round_trip=True,
+    )
+
+    with connection4.cursor() as cursor4:
+        cursor4.execute(
+            "insert into mytab(id, data) values (:i, :d)", [4, "Sessionless 4"]
+        )
+
+        # The query will show both rows inserted
+        print("2nd query")
+        for r in cursor4.execute("select * from mytab order by id"):
+            print(r)
+
+    # Rollback so the example can be run multiple times.
+    # This concludes the Sessionless Transaction
+    connection4.rollback()