Documentation improvements.

Author: anthony-tuininga

doc/src/api_manual/connect_param.rst

@@ -98,6 +98,8 @@ ConnectParams Attributes
     `tracing <https://www.oracle.com/pls/topic/lookup?
     ctx=dblatest&id=GUID-B0FC69F9-2EBC-44E8-ACB2-62FBA14ABD5C>`__.
 
+    .. versionadded:: 1.4.0
+
 .. attribute:: ConnectParams.debug_jdwp
 
     This read-only attribute is a string with the format

doc/src/api_manual/connection.rst

@@ -689,6 +689,8 @@ Connection Attributes
     associated with the connection. It is the same value as the SQL expression
     ``sys_context('userenv', 'instance_name')``.
 
+    .. versionadded:: 1.4.0
+
     .. note::
 
         This attribute is an extension to the DB API definition.

doc/src/api_manual/cursor.rst

@@ -442,7 +442,7 @@ Cursor Methods
     meaning that python-oracledb does not do any decoding. See :ref:`Fetching raw
     data <fetching-raw-data>` for more information.
 
-    The ``convert_nulls`` parameter, if specified, should be passed a boolean
+    The ``convert_nulls`` parameter, if specified, should be passed as a boolean
     value. Passing the value ``True`` causes the ``outconverter`` to be called
     when a null value is fetched from the database; otherwise, the
     ``outconverter`` is only called when non-null values are fetched from the
@@ -452,7 +452,7 @@ Cursor Methods
     parameter `encodingErrors` was renamed to `encoding_errors`. The old
     name will continue to work as a keyword parameter for a period of time.
 
-    .. versionchanged:: 1.4
+    .. versionchanged:: 1.4.0
 
         The ``convert_nulls`` parameter was added.
 
@@ -511,6 +511,12 @@ Cursor Attributes
     or if the cursor has not had an operation invoked via the
     :meth:`~Cursor.execute()` method yet.
 
+    .. versionchanged:: 1.4.0
+
+        Previously, this attribute was a sequence of 7-item sequences.  Each
+        of these sequences contained information describing one result column:
+        (name, type, display_size, internal_size, precision, scale, null_ok).
+
 .. attribute:: Cursor.fetchvars
 
     This read-only attribute specifies the list of variables created for the
@@ -554,7 +560,7 @@ Cursor Attributes
 
     See :ref:`outputtypehandlers`.
 
-    .. versionchanged:: 1.4
+    .. versionchanged:: 1.4.0
 
         The method signature was changed. The previous signature
         handler(cursor, name, default_type, length, precision, scale) will

doc/src/api_manual/fetch_info.rst

@@ -12,6 +12,8 @@ attributes ``name``, ``type_code``, ``display_size``, ``internal_size``,
 ``fetch_info`` is of type FetchInfo, then ``fetch_info[2]`` is the same as
 ``fetch_info.display_size``.
 
+.. versionadded:: 1.4.0
+
 .. note::
 
     This object is an extension the DB API.

doc/src/api_manual/module.rst

@@ -11,18 +11,6 @@ API: python-oracledb Module
 Oracledb Methods
 ================
 
-.. data:: __future__
-
-    Special object which contains attributes which control the behavior of
-    python-oracledb, allowing for opting in for new features. No attributes are
-    currently supported so all attributes will silently ignore being set and
-    will always appear to have the value None.
-
-    .. note::
-
-        This method is an extension to the DB API definition.
-
-
 .. function:: Binary(string)
 
     Constructs an object holding a binary (long) string value.
@@ -1291,6 +1279,30 @@ Oracledb Methods
     (number of seconds since the epoch; see the documentation of the standard
     Python time module for details).
 
+.. _futureobj:
+
+Oracledb.__future__ Object
+==========================
+
+Special object that contains attributes which control the behavior of
+python-oracledb, allowing for opting in for new features.
+
+.. note::
+
+    This method is an extension to the DB API definition.
+
+.. attribute:: __future__.old_json_col_as_obj
+
+    A boolean attribute which when set to *True* while using Oracle Database
+    12c (or later), fetches VARCHAR2 and LOB columns that were created with
+    the ``IS JSON`` constraint and therefore contain JSON data in the same way
+    that :ref:`columns of type JSON <json21fetch>` are fetched when using
+    Oracle Database 21c (or later).
+
+    In python-oracledb 2.0, the setting of this attribute will no longer be
+    required since this will be the default behavior.
+
+    .. versionadded:: 1.4.0
 
 .. _constants:
 

doc/src/api_manual/soda.rst

@@ -541,30 +541,6 @@ SodaOperation Methods
     Use of this method requires Oracle Client 21.3 or higher (or Oracle Client
     19 from 19.11).
 
-
-.. method:: SodaOperation.lock()
-
-    Specifies whether the documents fetched from the collection should be
-    locked (equivalent to SQL "select for update").
-
-    The next commit or rollback on the connection made after the operation is
-    performed will "unlock" the documents. Ensure that the connection is not in
-    autocommit mode or the documents will be unlocked immediately after the
-    operation is complete.
-
-    This method should only be used with read operations (other than
-    :func:`~SodaOperation.count()`) and should not be used in
-    conjunction with non-terminal methods :meth:`~SodaOperation.skip()` and
-    :meth:`~SodaOperation.limit()`.
-
-    If this method is specified in conjunction with a write operation this
-    method is ignored.
-
-    This method is only supported in Oracle Client 21.3 and higher (also
-    available in Oracle Client 19 from 19.11).
-
-    .. versionadded:: 1.4
-
 .. method:: SodaOperation.key(value)
 
     Specifies that the document with the specified key should be returned.
@@ -597,6 +573,29 @@ SodaOperation Methods
     criteria can be specified by chaining methods together.
 
 
+.. method:: SodaOperation.lock()
+
+    Specifies whether the documents fetched from the collection should be
+    locked (equivalent to SQL "select for update").
+
+    The next commit or rollback on the connection made after the operation is
+    performed will "unlock" the documents. Ensure that the connection is not in
+    autocommit mode or the documents will be unlocked immediately after the
+    operation is complete.
+
+    This method should only be used with read operations (other than
+    :func:`~SodaOperation.count()`) and should not be used in
+    conjunction with non-terminal methods :meth:`~SodaOperation.skip()` and
+    :meth:`~SodaOperation.limit()`.
+
+    If this method is specified in conjunction with a write operation this
+    method is ignored.
+
+    This method is only supported in Oracle Client 21.3 or later (or
+    Oracle Client 19 from 19.11).
+
+    .. versionadded:: 1.4.0
+
 .. method:: SodaOperation.remove()
 
     Removes all of the documents in the collection that match the criteria. The

doc/src/api_manual/subscription.rst

@@ -136,8 +136,9 @@ Message Objects
 
     This read-only attribute returns a list of message query objects that give
     information about query result sets changed for this notification. This
-    attribute will be None if the ``qos`` parameter did not include the flag
-    :data:`~oracledb.SUBSCR_QOS_QUERY` when the subscription was created.
+    attribute will be an empty list if the ``qos`` parameter did not include
+    the flag :data:`~oracledb.SUBSCR_QOS_QUERY` when the subscription was
+    created.
 
 
 .. attribute:: Message.queue_name
@@ -170,7 +171,7 @@ Message Objects
 
     This read-only attribute returns a list of message table objects that give
     information about the tables changed for this notification. This
-    attribute will be None if the ``qos`` parameter included the flag
+    attribute will be an empty list if the ``qos`` parameter included the flag
     :data:`~oracledb.SUBSCR_QOS_QUERY` when the subscription was created.
 
 

doc/src/api_manual/variable.rst

@@ -52,10 +52,10 @@ Variable Attributes
 
 .. attribute:: Variable.convert_nulls
 
-   This read-only attribute returns whether the :data:`~Variable.outconverter`
+   This read-only attribute returns whether the :attr:`~Variable.outconverter`
    method is called when null values are fetched from the database.
 
-   .. versionadded:: 1.4
+   .. versionadded:: 1.4.0
 
 .. attribute:: Variable.inconverter
 

doc/src/release_notes.rst

@@ -17,36 +17,35 @@ Thin Mode Changes
     performance of connection creation by reducing the number of round trips
     required to create the second and subsequent connections to the same
     database.
-#)  Added support for the ``ORA_SDTZ`` environment variable used to set the
-    session time zone used by the database.
-#)  Added support for shrinking the pool back to the minimum number of
-    connections allowed in the pool when the pool is idle for
-    :data:`ConnectionPool.timeout` seconds.
-#)  Added support for sending a generated connection identifier to the
-    database used for tracing. An application specific prefix is prepended to
-    this value if specified via a new ``connection_id_prefix`` parameter when
-    creating standalone connections or connection pools.
-#)  Added support for growing the pool back to the minimum number of
-    connections allowed in the pool when connections are killed or otherwise
-    made unusable.
-#)  Added URL to the Oracle Database Error Help Portal in Oracle Database
-    error messages similar to when Thick mode uses Oracle Client 23c.
+#)  Added support for shrinking the connection pool back to the specified
+    minimum size when the pool is idle for :data:`ConnectionPool.timeout`
+    seconds.
+#)  Added support for growing the connection pool back to the minimum number of
+    connections after connections are killed or otherwise made unusable.
 #)  A default connection class is now generated when DRCP is used with a
     connection pool and no connection class was specified when the pool was
     created. The default connection class will be of the form ``DPY:`` followed
     by a 16-byte unique identifier converted to base64 encoding.
 #)  Changed internal connection feature negotiation for more accurate Oracle
     Database 23c support.
-#)  Fixed bug when a dynamically sized pool is created with an ``increment``
-    of zero and the pool needs to grow.
+#)  Added support for sending a generated connection identifier to the
+    database used for tracing. An application specific prefix is prepended to
+    this value if specified via a new ``connection_id_prefix`` parameter when
+    creating standalone connections or connection pools.
+#)  Added URL to the Oracle Database Error Help Portal in Oracle Database
+    error messages similar to when Thick mode uses Oracle Client 23c.
+#)  Added support for the ``ORA_SDTZ`` environment variable used to set the
+    session time zone used by the database.
+#)  Fixed bug when a dynamically sized connection pool is created with an
+    ``increment`` of zero and the pool needs to grow.
 #)  Fixed bug affecting connection reuse when connections were acquired from
     the connection pool with a ``cclass`` different to the one used to
     create the pool.
-#)  Fixed bug when a connection is discarded from the pool during
+#)  Fixed bug when a connection is discarded from the connection pool during
     :meth:`ConnectionPool.acquire()` and the ping check fails due to the
     connection being dead.
 #)  Fixed bug when an output type handler is used and the value of
-    cursor.prefetchrows exceeds cursor.arraysize
+    :attr:`Cursor.prefetchrows` exceeds :attr:`Cursor.arraysize`
     (`issue 173 <https://github.com/oracle/python-oracledb/issues/173>`__).
 #)  Fixed bug when an Application Continuity replay context is returned during
     connection to the database
@@ -58,7 +57,7 @@ Thin Mode Changes
 Thick Mode Changes
 ++++++++++++++++++
 
-#)  Added function :meth:`SodaCollection.getIndexes()` for getting the indexes
+#)  Added function :meth:`SodaCollection.listIndexes()` for getting the indexes
     on a SODA collection.
 #)  Added support for specifying if documents should be locked when fetched
     from SODA collections. A new non-terminal method
@@ -87,12 +86,12 @@ Common Changes
     ``handler(cursor, metadata)`` where the ``metadata`` parameter is a
     :ref:`FetchInfo<fetchinfoobj>` object containing the same information found
     in :data:`Cursor.description`. The original signature for output type
-    handlers is deprecated and will be removed in some future version.
+    handlers is deprecated and will be removed in a future version.
 #)  Added support for fetching VARCHAR2 and LOB columns which contain JSON (and
     have the "IS JSON" check constraint enabled) in the same way as columns of
     type JSON (which requires Oracle Database 21c or higher) are fetched. In
     thick mode this requires Oracle Client 19c or higher. The attribute
-    ``oracledb.__future__.old_json_col_as_obj`` must be set to the value
+    :attr:`oracledb.__future__.old_json_col_as_obj` must be set to the value
     ``True`` for this behavior to occur. In version 2.0 this will become the
     normal behavior and setting this attribute will no longer be needed.
 #)  Added new property :attr:`Connection.instance_name` which provides the
@@ -163,7 +162,8 @@ Thin Mode Changes
 #)  Fixed bug with Oracle Database 23c when SQL is executed after first being
     parsed.
 #)  Fixed bug when :data:`ConnectionPool.timeout` is not `None` when creating a
-    pool (`issue 166 <https://github.com/oracle/python-oracledb/issues/166>`__).
+    connection pool
+    (`issue 166 <https://github.com/oracle/python-oracledb/issues/166>`__).
 #)  Fixed bug when a query is re-executed after an underlying table is dropped
     and recreated, and the query select list contains LOBs or JSON data.
 #)  Fixed bug when warning message such as for impending password expiry is

doc/src/user_guide/json_data_type.rst

@@ -75,6 +75,8 @@ binding as shown below:
     cursor.setinputsizes(None, oracledb.DB_TYPE_JSON)
     cursor.execute(insert_sql, [1, data])
 
+.. _json21fetch:
+
 To fetch a JSON column, use:
 
 .. code-block:: python
@@ -83,7 +85,7 @@ To fetch a JSON column, use:
         print(row)
 
 See `json_direct.py
-<https://github.com/oracle/python-oracledb/tree/main/samplesjson_direct.py>`__
+<https://github.com/oracle/python-oracledb/tree/main/samples/json_direct.py>`__
 for a runnable example.  The example also shows how to use this type when
 python-oracledb Thick mode uses older Oracle Client libraries.
 
@@ -102,7 +104,24 @@ insert JSON strings like:
 
     cursor.execute(inssql, [1, json.dumps(data)])
 
-To fetch JSON strings, use:
+You can fetch VARCHAR2 and LOB columns that contain JSON data without needing
+to call ``json.loads()`` on the value (similar to
+:ref:`fetching JSON type columns <json21fetch>` when using Oracle Database
+21c). This can be done by setting the attribute
+:attr:`oracledb.__future__.old_json_col_as_obj` to the value *True* as shown
+below.  If you are using python-oracledb Thick mode, you must also use Oracle
+Client 19c (or later).
+
+.. code-block:: python
+
+    oracledb.__future__.old_json_col_as_obj = True
+
+    for row in cursor.execute("select * from CustomersAsBlob"):
+        print(row)
+
+To fetch JSON without setting the attribute
+``oracledb.__future__.old_json_col_as_obj``, you can use ``json.loads()`` on
+the returned data. For example, to fetch JSON which uses BLOB storage:
 
 .. code-block:: python
 
@@ -113,7 +132,7 @@ To fetch JSON strings, use:
         print(json.loads(j.read()))
 
 See `json_blob.py
-<https://github.com/oracle/python-oracledb/tree/main/samplesjson_blob.py>`__
+<https://github.com/oracle/python-oracledb/tree/main/samples/json_blob.py>`__
 for a runnable example.
 
 IN Bind Type Mapping