Documentation updates.

Author: anthony-tuininga

doc/src/release_notes.rst

@@ -19,10 +19,11 @@ oracledb `3.4.0 <https://github.com/oracle/python-oracledb/compare/v3.3.0...v3.4
 Thin Mode Changes
 +++++++++++++++++
 
-#)  Fixed bug when setting values of type ``datetime.date`` on variables of
-    types :attr:`oracledb.DB_TYPE_TIMESTAMP`,
-    :attr:`oracledb.DB_TYPE_TIMESTAMP_TZ` and
-    :attr:`oracledb.DB_TYPE_TIMESTAMP_LTZ`.
+#)  Fixed bug when setting values of type ``datetime.date`` on variables (such
+    as created by :meth:`Cursor.var()` or implicitly by
+    :meth:`Cursor.setinputsizes()`) of types
+    :attr:`oracledb.DB_TYPE_TIMESTAMP`, :attr:`oracledb.DB_TYPE_TIMESTAMP_TZ`
+    and :attr:`oracledb.DB_TYPE_TIMESTAMP_LTZ`.
 #)  Fixed bug validating the database host during connection.
 #)  Internal change: refactor encoding of Oracle data types.
 #)  Internal change: small performance improvement sending bytes on the
@@ -39,9 +40,9 @@ Common Changes
 
 #)  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.
+    Previously only ``int64`` was supported.
 #)  Added ``fetch_lobs`` and ``fetch_decimals`` parameters where applicable to
-    the methods used for fetching rows or dataframes from the database. Note
+    the methods used for fetching rows or data frames from the database. Note
     that for the creation of pipeline operations, if these parameters are not
     specified then the values of
     :attr:`oracledb.defaults.fetch_lobs <Defaults.fetch_lobs>` and
@@ -53,10 +54,10 @@ Common Changes
     support and :ref:`Cloud Native Authentication <cloudnativemodules>`
     support
     (`issue 512 <https://github.com/oracle/python-oracledb/issues/512>`__).
-#)  Fixed bug when attempting to execute an empty statement
-    (`issue 525 <https://github.com/oracle/python-oracledb/issues/525>`__).
 #)  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
+    (`issue 525 <https://github.com/oracle/python-oracledb/issues/525>`__).
 #)  Fixed bug when attempting to convert an integer that cannot be represented
     as a native C ``int`` value to an Arrow data frame.
 #)  API documentation is now generated from the source code.

doc/src/user_guide/bind.rst

@@ -31,7 +31,7 @@ more than once with different data values.  If you do not use bind variables,
 Oracle must reparse and cache multiple statements.  When using bind variables,
 Oracle Database may be able to reuse the statement execution plan and context.
 
-.. warning::
+.. important::
 
     Never concatenate or interpolate user data into SQL statements:
 

doc/src/user_guide/connection_handling.rst

@@ -23,22 +23,32 @@ executed. Statements are executed using one of these methods
 This chapter discusses python-oracledb's synchronous methods. The asynchronous
 methods and pipelining functionality are discussed in detail in :ref:`asyncio`.
 
-PL/SQL statements are discussed in :ref:`plsqlexecution`.  Other chapters
-contain information on specific data types and features.  See :ref:`batchstmnt`,
-:ref:`lobdata`, :ref:`jsondatatype`, and :ref:`xmldatatype`.
+PL/SQL statements are discussed in :ref:`plsqlexecution`. The following
+chapters contain information on specific data types and features:
+
+- :ref:`batchstmnt`
+- :ref:`pipelining`
+- :ref:`lobdata`
+- :ref:`jsondatatype`
+-  :ref:`xmldatatype`
+
+**Executing SQL Scripts**
 
 Python-oracledb can be used to execute individual statements, one at a time.
 Once a statement has finished execution, only then will the next statement
 execute. If you try to execute statements concurrently in a single connection,
 the statements are queued and run consecutively in the order they are executed
-in the application code.
+in the application code. This includes :ref:`Pipelined statements
+<pipelining>`.
 
 Python-oracledb does not read SQL*Plus ".sql" files.  To read SQL files, use a
 technique like the one in ``run_sql_script()`` in `samples/sample_env.py
 <https://github.com/oracle/python-oracledb/blob/main/samples/sample_env.py>`__.
 
-SQL statements should not contain a trailing semicolon (";") or forward slash
-("/").  This will fail:
+**SQL Statement Syntax**
+
+SQL statements executed in python-oracledb should not contain a trailing
+semicolon (";") or forward slash ("/"). This will fail:
 
 .. code-block:: python
 
@@ -50,17 +60,6 @@ This is correct:
 
     cursor.execute("select * from MyTable")
 
-
-SQL Queries
-===========
-
-Queries (statements beginning with SELECT or WITH) can be executed using the
-method :meth:`Cursor.execute()`.  Rows can then be iterated over, or can be
-fetched using one of the methods :meth:`Cursor.fetchone()`,
-:meth:`Cursor.fetchmany()` or :meth:`Cursor.fetchall()`.  There is a
-:ref:`default type mapping <defaultfetchtypes>` to Python types that can be
-optionally :ref:`overridden <outputtypehandlers>`.
-
 .. IMPORTANT::
 
     Interpolating or concatenating user data with SQL statements, for example
@@ -69,6 +68,18 @@ optionally :ref:`overridden <outputtypehandlers>`.
     instead, for example ``cursor.execute("SELECT * FROM mytab WHERE mycol =
     :mybv", mybv=myvar)``.
 
+
+SQL Queries
+===========
+
+Queries (statements beginning with SELECT or WITH) can be executed using the
+method :meth:`Cursor.execute()`.  Rows can then be iterated over, or can be
+fetched using one of the methods :meth:`Cursor.fetchone()`,
+:meth:`Cursor.fetchmany()` or :meth:`Cursor.fetchall()`. This lets you handle
+rows directly or stream them if needed. There is a :ref:`default type mapping
+<defaultfetchtypes>` to Python types that can be optionally :ref:`overridden
+<outputtypehandlers>`.
+
 .. _fetching:
 
 Fetch Methods
@@ -98,9 +109,10 @@ Rows can be fetched in various ways.
               break
           print(row)
 
-- If rows need to be processed in batches, the method :meth:`Cursor.fetchmany()`
-  can be used. The size of the batch is controlled by the ``size`` parameter,
-  which defaults to the value of :attr:`Cursor.arraysize`.
+- If rows need to be streamed or processed in batches, the method
+  :meth:`Cursor.fetchmany()` can be used. The size of the batch is controlled
+  by the ``size`` parameter, which defaults to the value of
+  :attr:`Cursor.arraysize`.
 
   .. code-block:: python
 
@@ -116,8 +128,9 @@ Rows can be fetched in various ways.
 
   Note the ``size`` parameter only affects the number of rows returned to the
   application, not to the internal buffer size used for tuning fetch
-  performance.  That internal buffer size is controlled only by changing
-  :attr:`Cursor.arraysize`, see :ref:`tuningfetch`.
+  performance. That internal buffer size is controlled only by changing
+  :attr:`Cursor.arraysize` or :attr:`oracledb.defaults.arraysize
+  <Defaults.arraysize>`, see :ref:`tuningfetch`.
 
 - If all of the rows need to be fetched and can be contained in memory, the
   method :meth:`Cursor.fetchall()` can be used.

doc/src/user_guide/installation.rst

@@ -279,7 +279,7 @@ Changing Prefetchrows and Arraysize for Re-executed Statements
 In python-oracledb, the :attr:`~Cursor.prefetchrows` and
 :attr:`~Cursor.arraysize` values are only examined when a statement is executed
 the first time.  To change the values for a re-executed statement, create a new
-cursor.  For example, to change :attr:`~Cursor.arraysize``:
+cursor.  For example, to change :attr:`~Cursor.arraysize`:
 
 .. code-block:: python
 

doc/src/user_guide/sql_execution.rst

@@ -649,7 +649,9 @@ def sdu(self) -> int:
         (SDU) that is being used by the connection. The value will be the
         lesser of the requested python-oracledb size and the maximum size
         allowed by the database network configuration. It is available only in
-        python-oracledb Thin mode.
+        python-oracledb Thin mode. To set the SDU in Thick mode, use a
+        connection string SDU parameter or set a value for DEFAULT_SDU_SIZE in
+        a sqlnet.ora configuration file.
         """
         self._verify_connected()
         return self._impl.get_sdu()

doc/src/user_guide/tuning.rst

@@ -647,7 +647,9 @@ def sdu(self) -> int:
         (SDU) that is being used by the connection. The value will be the
         lesser of the requested python-oracledb size and the maximum size
         allowed by the database network configuration. It is available only in
-        python-oracledb Thin mode.
+        python-oracledb Thin mode. To set the SDU in Thick mode, use a
+        connection string SDU parameter or set a value for DEFAULT_SDU_SIZE in
+        a sqlnet.ora configuration file.
         """
         self._verify_connected()
         return self._impl.get_sdu()