Small tweaks to the links for the oracledb.defaults attributes.

Author: anthony-tuininga

doc/src/api_manual/connect_params.rst

@@ -139,9 +139,10 @@ All properties are read only.
 .. autoproperty:: ConnectParams.driver_name
 
     This is an arbitrary value set by the user in the
-    :meth:`oracledb.ConnectParams()` method or the :attr:`defaults.driver_name`
-    attribute which is the default value. This is the value shown in the
-    CLIENT_DRIVER column of the V$SESSION_CONNECT_INFO view.
+    :meth:`oracledb.ConnectParams()` method or the
+    :attr:`oracledb.defaults.driver_name <Defaults.driver_name>` attribute
+    which is the default value. This is the value shown in the CLIENT_DRIVER
+    column of the V$SESSION_CONNECT_INFO view.
 
     This attribute is supported in both python-oracledb Thin and Thick modes.
 
@@ -193,9 +194,10 @@ All properties are read only.
 .. autoproperty:: ConnectParams.machine
 
     This is an arbitrary value set by the user in the
-    :meth:`oracledb.ConnectParams()` method or the :attr:`defaults.machine`
-    attribute which is the default value. This is the value shown in the
-    MACHINE column of the V$SESSION view.
+    :meth:`oracledb.ConnectParams()` method or the
+    :attr:`oracledb.defaults.machine <Defaults.machine>` attribute which is the
+    default value. This is the value shown in the MACHINE column of the
+    V$SESSION view.
 
     This attribute is only supported in python-oracledb Thin mode.
 
@@ -210,9 +212,10 @@ All properties are read only.
 .. autoproperty:: ConnectParams.osuser
 
     This is an arbitrary value set by the user in the
-    :meth:`oracledb.ConnectParams()` method or the :attr:`defaults.osuser`
-    attribute which is the default value. This is the value shown in the OSUSER
-    column of the V$SESSION view.
+    :meth:`oracledb.ConnectParams()` method or the
+    :attr:`oracledb.defaults.osuser <Defaults.osuser>` attribute which is the
+    default value. This is the value shown in the OSUSER column of the
+    V$SESSION view.
 
     This attribute is only supported in python-oracledb Thin mode.
 
@@ -249,9 +252,10 @@ All properties are read only.
 .. autoproperty:: ConnectParams.program
 
     This is an arbitrary value set by the user in the
-    :meth:`oracledb.ConnectParams()` method or the :attr:`defaults.program`
-    attribute which is the default value. This is the value shown in the
-    PROGRAM column of the V$SESSION view.
+    :meth:`oracledb.ConnectParams()` method or the
+    :attr:`oracledb.defaults.program <Defaults.program>` attribute which is the
+    default value. This is the value shown in the PROGRAM column of the
+    V$SESSION view.
 
     This attribute is supported in python-oracledb Thin mode.
 
@@ -350,23 +354,24 @@ All properties are read only.
         The default value of this attribute was changed from *60.0* seconds to
         *20.0* seconds.
 
-.. autoproperty:: ConnectParams.use_sni
-
-    This attribute is supported in both python-oracledb Thin and Thick modes.
-
-    .. versionadded:: 3.0.0
-
 .. autoproperty:: ConnectParams.terminal
 
     This is an arbitrary value set by the user in the
-    :meth:`oracledb.ConnectParams()` method or the :attr:`defaults.terminal`
-    attribute which is the default value. This is the value shown in the
-    TERMINAL column of the V$SESSION view.
+    :meth:`oracledb.ConnectParams()` method or the
+    :attr:`oracledb.defaults.terminal <Defaults.terminal>` attribute which is
+    the default value. This is the value shown in the TERMINAL column of the
+    V$SESSION view.
 
     This attribute is only supported in python-oracledb Thin mode.
 
     .. versionadded:: 2.5.0
 
+.. autoproperty:: ConnectParams.use_sni
+
+    This attribute is supported in both python-oracledb Thin and Thick modes.
+
+    .. versionadded:: 3.0.0
+
 .. autoproperty:: ConnectParams.thick_mode_dsn_passthrough
 
     This attribute is only supported in python-oracledb Thick mode.

doc/src/api_manual/defaults.rst

@@ -50,7 +50,7 @@ Defaults Attributes
         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
+        Thick mode, the value of :attr:`Defaults.config_dir` may get changed
         by python-oracledb.
 
 .. autoproperty:: Defaults.driver_name

doc/src/api_manual/module.rst

@@ -199,8 +199,9 @@ Oracledb Methods
 
     .. versionchanged:: 3.0.0
 
-        At completion of the method, the value of :attr:`defaults.config_dir`
-        may get changed by python-oracledb.
+        At completion of the method, the value of
+        :attr:`oracledb.defaults.config_dir <Defaults.config_dir>` may get
+        changed by python-oracledb.
 
     .. versionchanged:: 2.5.0
 
@@ -1905,7 +1906,8 @@ stored configuration information. Python-oracledb then uses this information to
 connect to Oracle Database.
 
 To use this plugin in python-oracledb Thick mode, you must set
-:attr:`defaults.thick_mode_dsn_passthrough` to *False*. Alternatively use
+:attr:`oracledb.defaults.thick_mode_dsn_passthrough
+<Defaults.thick_mode_dsn_passthrough>` to *False*. Alternatively use
 :meth:`ConnectParams.parse_connect_string()`, see :ref:`usingconnparams`.
 
 See :ref:`ociobjstorageprovider` for more information.
@@ -1930,7 +1932,8 @@ stored configuration information. Python-oracledb then uses this information to
 connect to Oracle Database.
 
 To use this plugin in python-oracledb Thick mode, you must set
-:attr:`defaults.thick_mode_dsn_passthrough` to *False*. Alternatively use
+:attr:`oracledb.defaults.thick_mode_dsn_passthrough
+<Defaults.thick_mode_dsn_passthrough>` to *False*. Alternatively use
 :meth:`ConnectParams.parse_connect_string()`, see :ref:`usingconnparams`.
 
 See :ref:`azureappstorageprovider` for more information.

doc/src/release_notes.rst

@@ -280,7 +280,9 @@ Common Changes
     - Added support for CLOB, BLOB, and RAW data types
     - Fixed support for BOOLEAN data type
     - Fixed bug when NUMBER data is fetched that does not have a precision or
-      scale specified and :attr:`defaults.fetch_decimals` is set to *True*.
+      scale specified and
+      :attr:`oracledb.defaults.fetch_decimals <Defaults.fetch_decimals>` is set
+      to *True*.
     - More efficient processing when a significant amount of data is duplicated
       from one row to the next
     - Avoid memory allocation/free cycles for decimal data
@@ -298,7 +300,8 @@ Common Changes
 #)  An error message that links to :ref:`documentation <ldapconnections>` on
     setting up a protocol hook function is now returned by default for LDAP and
     LDAPS URL connection strings in python-oracledb Thin mode, or when
-    :attr:`defaults.thick_mode_dsn_passthrough` is *False*.
+    :attr:`oracledb.defaults.thick_mode_dsn_passthrough
+    <Defaults.thick_mode_dsn_passthrough>` is *False*.
 #)  Error ``DPY-2062: payload cannot be enqueued since it does not match the
     payload type supported by the queue`` is now raised when the payload of a
     message being enqueued is not supported by the queue. Previously,
@@ -379,14 +382,16 @@ Thick Mode Changes
 ++++++++++++++++++
 
 #)  At successful completion of a call to :meth:`oracledb.init_oracle_client()`,
-    the value of :attr:`defaults.config_dir` may get set by python-oracledb in
-    some cases. For example it might be set to the configuration directory that
-    is relative to the loaded Oracle Client libraries.
+    the value of :attr:`oracledb.defaults.config_dir <Defaults.config_dir>` may
+    get set by python-oracledb in some cases. For example it might be set to
+    the configuration directory that is relative to the loaded Oracle Client
+    libraries.
 #)  Connect string parsing and :ref:`tnsnames.ora <optnetfiles>` file handling
     can be configured with the new parameter
-    :attr:`defaults.thick_mode_dsn_passthrough` which can be helpful for
-    application portability. When it is `False`, python-oracledb Thick mode
-    behaves similarly to Thin mode.
+    :attr:`oracledb.defaults.thick_mode_dsn_passthrough
+    <Defaults.thick_mode_dsn_passthrough>` which can be helpful for application
+    portability. When it is `False`, python-oracledb Thick mode behaves
+    similarly to Thin mode.
 #)  Fixed bug that caused :attr:`oracledb._Error.isrecoverable` to always be
     `False`.
 
@@ -428,9 +433,9 @@ Common Changes
     :attr:`DbObjectAttribute.scale`, and :attr:`DbObjectAttribute.max_size` that
     provide additional metadata about
     :ref:`database object attributes <dbobjectattr>`.
-#)  The attribute :attr:`defaults.config_dir` is now set to
-    ``$ORACLE_HOME/network/admin`` if the environment variable ``ORACLE_HOME``
-    is set and ``TNS_ADMIN`` is *not* set.
+#)  The attribute :attr:`oracledb.defaults.config_dir <Defaults.config_dir>` is
+    now set to ``$ORACLE_HOME/network/admin`` if the environment variable
+    ``ORACLE_HOME`` is set and ``TNS_ADMIN`` is *not* set.
 #)  All connect strings are parsed by the driver if the new parameter
     ``thick_mode_dsn_passthrough`` is set to *True*. Previously, only Thin
     mode parsed all connect strings and Thick mode passed the connect string
@@ -451,8 +456,9 @@ Common Changes
     :meth:`oracledb.connect_async()`, :meth:`oracledb.create_pool()` and
     :meth:`oracledb.create_pool_async()`
     (`issue 438 <https://github.com/oracle/python-oracledb/issues/438>`__).
-#)  Fix typing issues with setters for :attr:`defaults.fetch_lobs` and
-    :attr:`defaults.fetch_decimals`
+#)  Fix typing issues with setters for
+    :attr:`oracledb.defaults.fetch_lobs <Defaults.fetch_lobs>` and
+    :attr:`oracledb.defaults.fetch_decimals <Defaults.fetch_decimals>`
     (`issue 458 <https://github.com/oracle/python-oracledb/issues/458>`__).
 #)  Error ``DPY-2053: python-oracledb thin mode cannot be used because thick
     mode has already been enabled`` is now raised when attempting to use
@@ -520,11 +526,11 @@ Thin Mode Changes
     :attr:`Connection.serial_num` that provide information about the session
     identifier and session serial number associated with a connection.
 #)  Added attributes
-    :attr:`oracledb.defaults.driver_name <defaults.driver_name>`,
-    :attr:`oracledb.defaults.machine <defaults.machine>`,
-    :attr:`oracledb.defaults.osuser <defaults.osuser>`,
-    :attr:`oracledb.defaults.program <defaults.program>`, and
-    :attr:`oracledb.defaults.terminal <defaults.terminal>` to set
+    :attr:`oracledb.defaults.driver_name <Defaults.driver_name>`,
+    :attr:`oracledb.defaults.machine <Defaults.machine>`,
+    :attr:`oracledb.defaults.osuser <Defaults.osuser>`,
+    :attr:`oracledb.defaults.program <Defaults.program>`, and
+    :attr:`oracledb.defaults.terminal <Defaults.terminal>` to set
     information about the driver name, machine name, operating system user,
     program name, and terminal name respectively. The ``driver_name``,
     ``machine``, ``osuser``, ``program``, and ``terminal`` parameters were also
@@ -1677,7 +1683,8 @@ Thin Mode Changes
 #)  Fixed bug with handling of redirect data returned by some SCAN listeners
     (`issue 39 <https://github.com/oracle/python-oracledb/issues/39>`__).
 #)  Fixed bug with re-execution of SQL that requires a define, such as occurs
-    when setting `oracledb.defaults.fetch_lobs` to the value `False`
+    when setting :attr:`oracledb.defaults.fetch_lobs <Defaults.fetch_lobs>` to
+    the value `False`
     (`issue 41 <https://github.com/oracle/python-oracledb/issues/41>`__).
 #)  Fixed bug that prevented cursors from implicit results sets from being
     closed.

doc/src/user_guide/appendix_c.rst

@@ -349,7 +349,8 @@ need to be made in addition to the common :ref:`commonupgrade`:
    python-oracledb Thick mode.
 
 2. If the ``config_dir`` parameter of :func:`~oracledb.init_oracle_client` had
-   been used, then set the new :attr:`defaults.config_dir` attribute to the
+   been used, then set the new
+   :attr:`oracledb.defaults.config_dir <Defaults.config_dir>` attribute to the
    desired value or set the ``config_dir`` parameter in your connection or pool
    creation method call.  For example:
 
@@ -368,8 +369,9 @@ need to be made in addition to the common :ref:`commonupgrade`:
    Also, see :ref:`sqlnetclientconfig`.
 
 3. If the ``driver_name`` parameter of :func:`~oracledb.init_oracle_client` had
-   been used, then set the new :attr:`defaults.driver_name` attribute to the
-   desired value or set the ``driver_name`` parameter when connecting.  The
+   been used, then set the new
+   :attr:`oracledb.defaults.driver_name <Defaults.driver_name>` attribute to
+   the desired value or set the ``driver_name`` parameter when connecting.  The
    convention for this parameter is to separate the product name from the
    product version by a colon and single blank characters. For example:
 
@@ -390,7 +392,8 @@ need to be made in addition to the common :ref:`commonupgrade`:
 5. To connect using a :ref:`TNS Alias <netservice>` from a ``tnsnames.ora``
    file (see :ref:`optnetfiles`) in python-oracledb Thin mode, you should
    explicitly set the environment variable ``TNS_ADMIN`` to the directory
-   containing the file, or set :attr:`defaults.config_dir`, or set the
+   containing the file, or set
+   :attr:`oracledb.defaults.config_dir <Defaults.config_dir>`, or set the
    ``config_dir`` parameter when connecting.
 
    A ``tnsnames.ora`` file in a "default" location such as the Instant Client

doc/src/user_guide/asyncio.rst

@@ -445,7 +445,8 @@ To limit the time for a pipeline, use an `asyncio timeout
 from Python 3.11.
 
 To tune fetching of rows with :meth:`Pipeline.add_fetchall()`, set
-:attr:`defaults.arraysize` or pass the ``arraysize`` parameter.
+:attr:`oracledb.defaults.arraysize <Defaults.arraysize>` or pass the
+``arraysize`` parameter.
 
 Pipelining Examples
 +++++++++++++++++++

doc/src/user_guide/connection_handling.rst

@@ -480,11 +480,13 @@ In python-oracledb Thin mode, an additional :ref:`connection protocol hook
 function <registerprotocolhook>` is required to handle this connection
 protocol, see :ref:`ldapconnections`. A connection protocol hook function is
 also required in python-oracledb Thick mode if
-:attr:`defaults.thick_mode_dsn_passthrough` is *False*.
+:attr:`oracledb.defaults.thick_mode_dsn_passthrough
+<Defaults.thick_mode_dsn_passthrough>` is *False*.
 
 To use LDAP URLs in python-oracledb Thick mode applications when
-:attr:`defaults.thick_mode_dsn_passthrough` is *True*, the Oracle Client
-libraries must be 23.4, or later.
+:attr:`oracledb.defaults.thick_mode_dsn_passthrough
+<Defaults.thick_mode_dsn_passthrough>` is *True*, the Oracle Client libraries
+must be 23.4, or later.
 
 
 .. _configproviderurl:
@@ -631,11 +633,13 @@ you in python-oracledb, then you can alter the connection string to include a
 protocol such as ``tcp://hostname``, or a port number such as
 ``hostname:1521``.
 
-In python-oracledb Thick mode, when :attr:`defaults.thick_mode_dsn_passthrough`
-is *False*, any ``DESCRIPTION``, ``CONNECT_DATA`` and ``SECURITY`` parameters
-of a full connect descriptor that are unrecognized by python-oracledb are
-passed to the database unchanged. Any Easy Connect parameters that are not
-known to python-oracledb are discarded and not passed to the database.
+In python-oracledb Thick mode, when
+:attr:`oracledb.defaults.thick_mode_dsn_passthrough
+<Defaults.thick_mode_dsn_passthrough>` is *False*, any ``DESCRIPTION``,
+``CONNECT_DATA`` and ``SECURITY`` parameters of a full connect descriptor that
+are unrecognized by python-oracledb are passed to the database unchanged. Any
+Easy Connect parameters that are not known to python-oracledb are discarded and
+not passed to the database.
 
 .. _pyoparams:
 
@@ -922,16 +926,17 @@ The following configuration providers are supported by python-oracledb:
 
 To use python-oracledb :ref:`Centralized Configuration Provider
 <configurationproviders>` functionality in Thick mode, you should set
-:attr:`defaults.thick_mode_dsn_passthrough` to *False*. Alternatively use
+:attr:`oracledb.defaults.thick_mode_dsn_passthrough
+<Defaults.thick_mode_dsn_passthrough>` to *False*. Alternatively use
 :meth:`ConnectParams.parse_connect_string()`, see :ref:`usingconnparams`.
 
-Note: In Thick mode, when :attr:`defaults.thick_mode_dsn_passthrough` is
-*True*, it is the Oracle Client libraries that access the configuration
-provider when python-oracledb connection or pool creation methods are
-invoked. Any python-oracledb parameter section will be ignored. Any Oracle
-Client Interface parameter section should be *removed* from the configuration
-because its values may be different to those that python-oracledb assumes, and
-will cause undefined behavior.
+Note: In Thick mode, when :attr:`oracledb.defaults.thick_mode_dsn_passthrough
+<Defaults.thick_mode_dsn_passthrough>` is *True*, it is the Oracle Client
+libraries that access the configuration provider when python-oracledb
+connection or pool creation methods are invoked. Any python-oracledb parameter
+section will be ignored. Any Oracle Client Interface parameter section should
+be *removed* from the configuration because its values may be different to
+those that python-oracledb assumes, and will cause undefined behavior.
 
 **Precedence of Attributes**
 
@@ -1036,11 +1041,20 @@ The elements of the ``dsn`` parameter are detailed in the table below.
     * - Parameter
       - Description
     * - ``config-file``
-      - Indicates that the centralized configuration provider is a file in your local system.
+      - Indicates that the centralized configuration provider is a file in your
+        local system.
     * - <file-name>
-      - The file path and name of the JSON file that contains the configuration information. For relative paths, python-oracledb will use the connection or pool creation ``config_dir`` parameter, or :attr:`defaults.config_dir` value, to create an absolute path.
+      - The file path and name of the JSON file that contains the configuration
+        information. For relative paths, python-oracledb will use the
+        connection or pool creation ``config_dir`` parameter, or
+        :attr:`oracledb.defaults.config_dir <Defaults.config_dir>` value, to
+        create an absolute path.
     * - ``key``
-      - The connection key name used to identify a specific configuration. If this parameter is specified, the file is assumed to contain multiple configurations that are indexed by the key value. If not specified, the file is assumed to contain a single configuration. See the example further below.
+      - The connection key name used to identify a specific configuration. If
+        this parameter is specified, the file is assumed to contain multiple
+        configurations that are indexed by the key value. If not specified, the
+        file is assumed to contain a single configuration. See the example
+        further below.
 
 **File Configuration Provider Examples**
 
@@ -1696,9 +1710,9 @@ hook function is expected to construct valid connection details, which
 python-oracledb will use to complete the connection or pool creation.
 
 You can also make use of a protocol hook function in python-oracledb Thick mode
-connection calls by setting :attr:`defaults.thick_mode_dsn_passthrough` to
-*False*. Alternatively use :meth:`ConnectParams.parse_connect_string()`, see
-:ref:`usingconnparams`.
+connection calls by setting :attr:`oracledb.defaults.thick_mode_dsn_passthrough
+<Defaults.thick_mode_dsn_passthrough>` to *False*. Alternatively use
+:meth:`ConnectParams.parse_connect_string()`, see :ref:`usingconnparams`.
 
 For example, the following hook function handles connection strings prefixed
 with the ``tcp://`` protocol. When :func:`oracledb.connect()` is called, the
@@ -1932,9 +1946,10 @@ connect with an LDAP URL. For example:
     connection = oracledb.connect(user="scott", password=pw, dsn=ldapurl)
 
 To use an LDAP URL in python-oracledb Thick mode when
-:attr:`defaults.thick_mode_dsn_passthrough` is *False*, a connection hook
-function is required as shown below for Thin mode. This lets LDAP URLs be
-utilized when python-oracledb uses any supported Oracle Client library version.
+:attr:`oracledb.defaults.thick_mode_dsn_passthrough
+<Defaults.thick_mode_dsn_passthrough>` is *False*, a connection hook function
+is required as shown below for Thin mode. This lets LDAP URLs be utilized when
+python-oracledb uses any supported Oracle Client library version.
 
 **Python-oracledb Thin Mode LDAP URLs**