Documentation improvements.

Author: anthony-tuininga

doc/src/api_manual/defaults.rst

@@ -11,107 +11,80 @@ Defaults Class
 
 .. autoclass:: Defaults
 
-    A Defaults object contains attributes that can be used to adjust the
-    behavior of the python-oracledb driver.
+    See :ref:`settingdefaults`.
 
-An example of changing a default value is:
-
-.. code-block:: python
-
-    import oracledb
-
-    oracledb.defaults.fetch_lobs = False  # return LOBs directly as strings or bytes
+.. _defaultsattributes:
 
 Defaults Attributes
 ===================
 
 .. autoproperty:: Defaults.arraysize
 
-    This is an attribute for tuning the performance of fetching rows from
-    Oracle Database. It does not affect data insertion. See :ref:`Tuning Fetch
-    Performance <tuningfetch>`.
+    See :ref:`Tuning Fetch Performance <tuningfetch>`.
 
 .. autoproperty:: Defaults.config_dir
 
-    At time of ``import oracledb`` the value of
-    ``oracledb.defaults.config_dir`` will be set to (first one wins):
-
-    - the value of ``$TNS_ADMIN``, if ``TNS_ADMIN`` is set.
-
-    - ``$ORACLE_HOME/network/admin``, if ``$ORACLE_HOME`` is set.
-
-    Otherwise, ``oracledb.defaults.config_dir`` will not be set.
-
     See :ref:`optnetfiles`.
 
     .. versionchanged:: 3.0.0
 
         The directory ``$ORACLE_HOME/network/admin`` was added to the
         heuristic.
 
-        At completion of a call to :meth:`oracledb.init_oracle_client()` in
-        Thick mode, the value of :attr:`Defaults.config_dir` may get changed
-        by python-oracledb.
-
 .. autoproperty:: Defaults.driver_name
 
-    See :ref:`otherinit`.
+    See :ref:`otherinit` and :ref:`dbviews`.
 
     .. versionadded:: 2.5.0
 
 .. autoproperty:: Defaults.fetch_decimals
 
-    An output type handler such as previously required in the obsolete
-    cx_Oracle driver can alternatively be used to adjust the returned type.  If
-    a type handler exists and returns a variable (that is,
-    ``cursor.var(...)``), then that return variable is used.  If the type
-    handler returns *None*, then the value of
-    ``oracledb.defaults.fetch_decimals`` is used to determine whether to return
-    ``decimal.Decimal`` values.
+    See `decimal.Decimal <https://docs.python.org
+    /3/library/decimal.html#decimal-objects>`__.
 
 .. autoproperty:: Defaults.fetch_lobs
 
     See :ref:`lobdata`.
 
-    An output type handler such as the one previously required in the obsolete
-    cx_Oracle driver can alternatively be used to adjust the returned type.  If
-    a type handler exists and returns a variable (that is, `cursor.var(...)`),
-    then that return variable is used. If the type handler returns *None*, then
-    the value of ``oracledb.defaults.fetch_lobs`` is used.
-
 .. autoproperty:: Defaults.machine
 
+    See :ref:`dbviews`.
+
     .. versionadded:: 2.5.0
 
 .. autoproperty:: Defaults.osuser
 
+    See :ref:`dbviews`.
+
     .. versionadded:: 2.5.0
 
 .. autoproperty:: Defaults.prefetchrows
 
-    This is an attribute for tuning the performance of fetching rows from
-    Oracle Database. It does not affect data insertion. See :ref:`Tuning Fetch
-    Performance <tuningfetch>`.
+    See :ref:`tuningfetch`.
 
 .. autoproperty:: Defaults.program
 
+    See :ref:`dbviews`.
+
     .. versionadded:: 2.5.0
 
 .. autoproperty:: Defaults.stmtcachesize
 
-    This is a tuning attribute, see :ref:`stmtcache`.
+    See :ref:`stmtcache`.
 
 .. autoproperty:: Defaults.terminal
 
+    See :ref:`dbviews`.
+
     .. versionadded:: 2.5.0
 
 .. autoproperty:: Defaults.thick_mode_dsn_passthrough
 
     When ``thick_mode_dsn_passthrough`` is the default value `True`, the
-    behavior of python-oracledb 2.5 and earlier versions occurs: Thick mode
-    passes connect strings unchanged to the Oracle Client libraries to
-    handle. Those libraries have their own heuristics for locating the optional
-    :ref:`tnsnames.ora <optnetfiles>`, if used.
+    behavior of python-oracledb 2.5 and earlier versions occurs:
+    python-oracledb Thick mode passes connect strings unchanged to the Oracle
+    Client libraries to handle. Those libraries have their own heuristics for
+    locating the optional :ref:`tnsnames.ora <optnetfiles>`, if used.
 
     When ``thick_mode_dsn_passthrough`` is `False`, python-oracledb Thick mode
     behaves similarly to Thin mode, which can be helpful for applications that

doc/src/api_manual/module.rst

@@ -267,77 +267,51 @@ Oracledb Methods
     .. versionadded:: 3.0.0
 
 
-.. _interval_ym:
-
-Oracledb IntervalYM Class
-=========================
+.. _moduleattributes:
 
-Objects of this class are returned for columns of type INTERVAL YEAR TO MONTH
-and can be passed to variables of type :data:`oracledb.DB_TYPE_INTERVAL_YM`
-The class is a `collections.namedtuple()
-<https://docs.python.org/3/library/collections.html#collections.namedtuple>`__
-class with two integer attributes, ``years`` and ``months``.
-
-.. versionadded:: 2.2.0
-
-
-.. _jsonid:
-
-Oracledb JsonId Class
-=====================
-
-Objects of this class are returned by :ref:`SODA <soda>` in the ``_id``
-attribute of documents stored in native collections when using Oracle Database
-23.4 (and later). It is a subclass of the `bytes <https://docs.python.org/3/
-library/stdtypes.html#bytes>`__ class.
-
-.. versionadded:: 2.1.0
-
-
-.. _futureobj:
-
-Oracledb __future__ Object
-==========================
-
-Special object that contains attributes which control the behavior of
-python-oracledb, allowing for opting in for new features.
-
-.. dbapimethodextension::
-
-.. _constants:
+Oracledb Attributes
+===================
 
-Oracledb Constants
-==================
+.. data:: apilevel
 
-General
--------
+    A string constant stating the Python DB API level supported by
+    python-oracledb. Currently "2.0".
 
-.. data:: apilevel
+.. data:: defaults
 
-    String constant stating the supported DB API level. Currently '2.0'.
+   The :ref:`Defaults <defaults>` object for setting default behaviors of
+   python-oracledb.
 
+   See :ref:`settingdefaults`.
 
 .. data:: paramstyle
 
-    String constant stating the type of parameter marker formatting expected by
-    the interface. Currently 'named' as in 'where name = :name'.
+    A string constant stating the type of parameter marker formatting expected
+    by the interface. Currently 'named' as in 'where name = :name'.
 
 
 .. data:: threadsafety
 
-    Integer constant stating the level of thread safety that the interface
-    supports.  Currently 2, which means that threads may share the module and
+    An integer constant stating the level of thread safety that python-oracledb
+    supports. Currently 2, which means that threads may share the module and
     connections, but not cursors. Sharing means that a thread may use a
     resource without wrapping it using a mutex semaphore to implement resource
     locking.
 
 .. data:: version
+
+    A string constant stating the version of the module. Currently '|release|'.
+
 .. data:: __version__
 
-    String constant stating the version of the module. Currently '|release|'.
+    A string constant stating the version of the module. Currently '|release|'.
 
     .. dbapiattributeextension::
 
+.. _constants:
+
+Oracledb Constants
+==================
 
 Advanced Queuing: Delivery Modes
 --------------------------------
@@ -1869,6 +1843,14 @@ See :ref:`exception` for usage information.
 
     See :ref:`tg` for more information.
 
+.. _futureobj:
+
+Oracledb __future__ Object
+==========================
+
+A special object that contains attributes which control the behavior of
+python-oracledb, allowing for opting in for new features.
+
 .. _oracledbplugins:
 
 Oracledb Plugins
@@ -1979,3 +1961,30 @@ Python-oracledb then uses these tokens to connect to Oracle Database.
 See :ref:`cloudnativeauthoauth` for more information.
 
 .. versionadded:: 3.0.0
+
+.. _interval_ym:
+
+Oracledb IntervalYM Class
+=========================
+
+Objects of this class are returned for columns of type INTERVAL YEAR TO MONTH
+and can be passed to variables of type :data:`oracledb.DB_TYPE_INTERVAL_YM`
+The class is a `collections.namedtuple()
+<https://docs.python.org/3/library/collections.html#collections.namedtuple>`__
+class with two integer attributes, ``years`` and ``months``.
+
+.. versionadded:: 2.2.0
+
+.. _jsonid:
+
+Oracledb JsonId Class
+=====================
+
+Objects of this class are returned by :ref:`SODA <soda>` in the ``_id``
+attribute of documents stored in native collections when using Oracle Database
+23.4 (and later). It is a subclass of the `bytes <https://docs.python.org/3/
+library/stdtypes.html#bytes>`__ class.
+
+.. versionadded:: 2.1.0
+
+.. dbapimethodextension::

doc/src/api_manual/variable.rst

@@ -11,7 +11,7 @@ Variable Class
 
 .. autoclass:: Var
 
-    An Var object should be created with :meth:`Cursor.var()` or
+    A Var object should be created with :meth:`Cursor.var()` or
     :meth:`Cursor.arrayvar()`.
 
     .. dbapiobjectextension::

doc/src/user_guide/connection_handling.rst

@@ -2468,10 +2468,10 @@ immediately return an available connection.  Some users set larger
 ``increment`` values even for fixed-size pools because it can help a pool
 re-establish itself if all connections become invalid, for example after a
 network dropout.  In the common case of Thin mode with the default ``getmode``
-of ``POOL_GETMODE_WAIT``, any :meth:`~ConnectionPool.acquire()` call that
-initiates pool growth will return after the first new connection is created,
-regardless of how big ``increment`` is.  The pool will then continue to
-re-establish connections in a background thread.
+of :data:`oracledb.POOL_GETMODE_WAIT`, any :meth:`~ConnectionPool.acquire()`
+call that initiates pool growth will return after the first new connection is
+created, regardless of how big ``increment`` is.  The pool will then continue
+to re-establish connections in a background thread.
 
 A connection pool can shrink back to its minimum size ``min`` when connections
 opened by the pool are not used by the application. This frees up database

doc/src/user_guide/initialization.rst

@@ -704,3 +704,23 @@ V$SESSION_CONNECT_INFO and verifying if the value of the column begins with the
 text ``python-oracledb thn``. See :ref:`vsessconinfo`.
 
 Note all connections in a python-oracledb application must use the same mode.
+
+.. _settingdefaults:
+
+Changing python-oracledb Default Settings
+=========================================
+
+Python-oracledb has a singleton :ref:`Defaults <defaults>` object with
+attributes that set default behaviors of the driver. The object is accessed
+using the :data:`defaults` attribute of the imported driver.
+
+For example, to return queried LOB columns directly as strings or bytes:
+
+.. code-block:: python
+
+    import oracledb
+
+    oracledb.defaults.fetch_lobs = False
+
+
+See :ref:`defaultsattributes` for the attributes that can be set.