Documentation improvements.

Author: anthony-tuininga

doc/src/api_manual/module.rst

@@ -1726,7 +1726,7 @@ Oracledb Methods
 
     .. deprecated:: python-oracledb 1.0
 
-    Use :ref:`ConnectParams class <connparam>` instead.
+    Use the :meth:`oracledb.ConnectParams()` method instead.
 
     .. note::
 

doc/src/user_guide/appendix_c.rst

@@ -48,8 +48,8 @@ See :ref:`enablingthick` for more information.
 Calling the ``init_oracle_client()`` method immediately loads Oracle Client
 libraries.  To emulate the cx_Oracle behavior of deferring library loading
 until the creation of the first connection (in the case when
-``init_oracle_client()`` is not called), your application will need to defer
-calling ``init_oracle_client()`` as appropriate.
+``init_oracle_client()`` is not called), your application will need to
+explicitly defer calling ``init_oracle_client()`` as appropriate.
 
 In python-oracledb, ``init_oracle_client()`` can now be called multiple times
 in the one Python process as long as its arguments are the same each time.
@@ -79,11 +79,11 @@ from cx_Oracle:
   specification PEP 249.  See
   :ref:`Standalone Connections <standaloneconnection>` and :ref:`connerrors`.
 
-- New keyword arguments can be passed to :func:`~oracledb.connect()`.  For
-  example you can pass the hostname, port and servicename as separate
+- New optional keyword arguments can be passed to :func:`~oracledb.connect()`.
+  For example you can pass the hostname, port and servicename as separate
   parameters instead of using an Easy Connect connection string.  In
-  python-oracledb Thin mode, some of the new arguments replace ``sqlnet.ora``
-  settings.
+  python-oracledb Thin mode, some of the new arguments replace :ref:`sqlnet.ora
+  <optnetfiles>` settings.
 
 - A new optional parameter ``params`` of type :ref:`ConnectParams <connparam>`
   can be used to encapsulate connection properties. See :ref:`usingconnparams`
@@ -102,6 +102,11 @@ The use of the class constructor method ``oracledb.Connection()`` to create
 connections is no longer recommended for creating connections.  Use
 :func:`~oracledb.connect()` instead.
 
+The :meth:`oracledb.makedsn()` method for creating the ``dsn`` value has been
+deprecated.  New code should use :meth:`oracledb.ConnectParams()` or use the
+new keyword arguments in :func:`oracledb.connect()`.
+
+
 Connection Object Differences
 +++++++++++++++++++++++++++++
 
@@ -115,14 +120,19 @@ and cx_Oracle drivers are:
   attribute is True if the connection was established in the Thin mode. In
   Thick mode, the value of this attribute is False.
 
+- The new method signature of :attr:`Connection.outputtypehandler` is
+  ``handler(cursor, metadata)``. The old signature ``handler(cursor, name,
+  default_type, length, precision, scale)`` was deprecated in python-oracledb
+  1.4 but will still work and will be removed in a future version.
+
 See :ref:`connattrs` for more information.
 
 Pooling Differences from cx_Oracle
 ----------------------------------
 
-It is recommended to use the new equivalent :ref:`ConnectionPool Object
-<connpool>` instead of the SessionPool object, which is deprecated.  To create
-a connection pool, use :meth:`oracledb.create_pool()`, which is equivalent to
+It is recommended to use the new :ref:`ConnectionPool Object <connpool>`
+instead of the equivalent SessionPool object, which is deprecated.  To create a
+connection pool, use :meth:`oracledb.create_pool()`, which is equivalent to
 calling `cx_Oracle.SessionPool() <https://cx-oracle.readthedocs.io/en/latest/
 api_manual/module.html#cx_Oracle.SessionPool>`__.
 
@@ -144,29 +154,33 @@ SessionPool>`_ as follows:
   password is now supported in the same way as :func:`oracledb.connect()`. For
   example ``dsn="un/pw@cs"`` can be used.
 
-- New keyword arguments can be passed to :func:`~oracledb.create_pool()`.  For
-  example you can pass the hostname, port and servicename as separate
-  parameters instead of using an Easy Connect connection string.  In
-  python-oracledb Thin mode, some of the new arguments replace ``sqlnet.ora``
-  settings.
-
-- The default mode is :data:`~oracledb.POOL_GETMODE_WAIT` instead of
-  :data:`~oracledb.POOL_GETMODE_NOWAIT`. If the mode
-  :data:`~oracledb.POOL_GETMODE_NOWAIT` is truly desired, modify any pool
-  creation code to specify this value instead.  Note the namespace of constant
-  has been improved.  Old names like ``SPOOL_ATTRVAL_NOWAIT`` can be used but
-  are now deprecated.
+- New optional keyword arguments can be passed to
+  :func:`~oracledb.create_pool()`.  For example you can pass the hostname, port
+  and servicename as separate parameters instead of using an Easy Connect
+  connection string.  In python-oracledb Thin mode, some of the new arguments
+  replace :ref:`sqlnet.ora <optnetfiles>` settings.
 
 - A new optional parameter ``params`` of type :ref:`PoolParams <poolparam>`
   can be used to encapsulate connection properties. See :ref:`usingconnparams`
   for more information.
 
-- The ``encoding`` and ``decoding`` parameters are deprecated and ignored. The
-  encodings in use are always UTF-8.
+- The default mode is :data:`~oracledb.POOL_GETMODE_WAIT` instead of
+  :data:`~oracledb.POOL_GETMODE_NOWAIT`. If the mode
+  :data:`~oracledb.POOL_GETMODE_NOWAIT` is truly desired, modify any pool
+  creation code to specify this value instead.  Note the namespace of
+  constants has been improved.  Old names like ``SPOOL_ATTRVAL_NOWAIT`` can be
+  used but are now deprecated.
+
+- The ``encoding`` and ``nenecoding`` parameters are deprecated and
+  ignored. The encodings in use are always UTF-8.
 
 - New keyword arguments that are used internally to create a :ref:`PoolParams
   object <connparam>` before creating the connection.
 
+The :meth:`oracledb.makedsn()` method for creating the ``dsn`` value has been
+deprecated.  New code should use :meth:`oracledb.ConnectParams()` or use the
+new keyword arguments to :func:`oracledb.create_pool()`.
+
 SessionPool Object Differences
 ++++++++++++++++++++++++++++++
 
@@ -201,31 +215,69 @@ python-oracledb and cx_Oracle drivers are:
   :meth:`Cursor.executemany()`, by passing None for the statement argument and
   an integer for the parameters argument.
 
-- ``Cursor.bindarraysize``: This attribute is deprecated and removed in
+- ``Cursor.bindarraysize``: This attribute is desupported and removed in
   python-oracledb. It is not needed in the application code.
 
 - :attr:`Cursor.rowcount`: After :meth:`Cursor.execute()` or
   :meth:`Cursor.executemany()` with PL/SQL statements, ``Cursor.rowcount``
   will return 0. If the cursor or connection are not open, then the value -1
   will be returned as required by the Python Database API.
 
+- :attr:`Cursor.description`: This attribute was previously a sequence of
+  7-item sequences in cx_Oracle and python-oracledb. Each of these sequences
+  contained information describing one result column, that is, (name, type,
+  display_size, internal_size, precision, scale, null_ok). In
+  python-oracledb 1.4, this attribute was changed to a sequence of
+  :ref:`FetchInfo <fetchinfoobj>` objects. Each FetchInfo object describes one
+  result column and can behave as a 7-tuple like before, but contains
+  additional information that may be helpful when using
+  :ref:`output type handlers <outputtypehandlers>`.
+
+- :attr:`Cursor.outputtypehandler`: The new method signature of this attribute
+  is ``handler(cursor, metadata)``. The old signature ``handler(cursor, name,
+  default_type, length, precision, scale)`` was deprecated in python-oracledb
+  1.4 but will still work and will be removed in a future version.
+
+.. _fetchisjson:
+
+Fetching IS JSON Column Differences from cx_Oracle
+--------------------------------------------------
+
+In python-oracledb, VARCHAR2 and LOB columns that have the ``IS JSON``
+constraint enabled are fetched as Python objects. These columns are fetched in
+the same way that :ref:`JSON type columns <json21fetch>` are fetched when
+using Oracle Database 21c (or later). The returned value varies depending on
+the JSON data. If the JSON data is an object, then a dictionary is returned.
+If it is an array, then a list is returned. If it is a scalar value, then that
+particular scalar value is returned.
+
+In cx_Oracle, VARCHAR2 and LOB columns that have the ``IS JSON`` constraint
+enabled are fetched as strings and LOB objects respectively. To enable this
+same fetch behavior in python-oracledb, you must use an
+:ref:`output type handler <outputtypehandlers>` as shown below.
+
+.. code-block:: python
+
+    def type_handler(cursor, fetch_info):
+        if fetch_info.is_json:
+            return cursor.var(fetch_info.type_code, cursor.arraysize)
+
 Advanced Queuing (AQ) Differences from cx_Oracle
 ------------------------------------------------
 
-The old Advanced Queuing (AQ) API is not available in python-oracledb since it
-was deprecated in cx_Oracle 7.2. Use the
-:ref:`new Advanced Queuing (AQ) <aqusermanual>`. Note that AQ is only
-available in the Thick mode.
+Use the new :ref:`Advanced Queuing (AQ) <aqusermanual>` API instead of the
+older API which was deprecated in cx_Oracle 7.2 and is not available in
+python-oracledb. Note that AQ is only available in python-oracledb Thick mode.
 
 Replace:
 
-- :meth:`Connection.deq()` with :meth:`Queue.deqone()` or :meth:`Queue.deqmany()`
-- :meth:`Connection.deqoptions()` with attribute :attr:`Queue.deqoptions`
-- :meth:`Connection.enq()` with :meth:`Queue.enqone()` or :meth:`Queue.enqmany()`
-- :meth:`Connection.deqoptions()` with attribute :attr:`Queue.deqoptions`
+- ``Connection.deq()`` with :meth:`Queue.deqone()` or :meth:`Queue.deqmany()`
+- ``Connection.deqoptions()`` with attribute :attr:`Queue.deqoptions`
+- ``Connection.enq()`` with :meth:`Queue.enqone()` or :meth:`Queue.enqmany()`
+- ``Connection.enqoptions()`` with attribute :attr:`Queue.enqoptions`
 
-The AQ feature in the python-oracledb driver differs from cx_Oracle as
-follows:
+The AQ support in python-oracledb has the following enhancements from
+cx_Oracle:
 
 - AQ messages can be enqueued and dequeued as a JSON payload type
 - Recipient lists can be enqueued and dequeued
@@ -241,10 +293,10 @@ Error Handling Differences from cx_Oracle
 In python-oracledb Thick mode, error messages generated by the Oracle Client
 libraries and the `ODPI-C <https://oracle.github.io/odpi/>`_ layer used by
 cx_Oracle and python-oracledb in Thick mode are mostly returned unchanged from
-cx_Oracle 8.3 with the exceptions shown below.
+cx_Oracle 8.3. Some exceptions shown below.
 
-Note that the python-oracledb driver error messages can vary between Thin and
-Thick modes. See :ref:`errorhandling`.
+Note that the python-oracledb driver error messages can also vary between Thin
+and Thick modes. See :ref:`errorhandling`.
 
 ConnectionPool.acquire() Message Differences
 ++++++++++++++++++++++++++++++++++++++++++++
@@ -379,19 +431,20 @@ to python-oracledb:
   containing the file, or set :attr:`defaults.config_dir`, or set the
   ``config_dir`` parameter when connecting.
 
-  Only python-oracledb Thick mode will read ``sqlnet.ora`` files.  The Thin
-  mode lets equivalent properties be set in the application when connecting.
+  Only python-oracledb Thick mode will read :ref:`sqlnet.ora <optnetfiles>`
+  files.  The Thin mode lets equivalent properties be set in the application
+  when connecting.
 
   Configuration files in a "default" location such as the Instant Client
   ``network/admin/`` subdirectory, in ``$ORACLE_HOME/network/admin/``, or in
   ``$ORACLE_BASE/homes/XYZ/network/admin/`` (in a read-only Oracle Database
-  home) is not automatically loaded in Thin mode.  Default locations are
-  automatically searched by Thick mode.
+  home) are not automatically loaded in Thin mode.  Default locations are
+  only automatically searched in Thick mode.
 
 - To use the python-oracledb Thin mode in an ORACLE_HOME database installation
-  environment, you use an explicit connection string since the ``ORACLE_SID``,
-  ``TWO_TASK`` and ``LOCAL`` environment variables are not used.  They are
-  used in Thick mode.
+  environment, you must use an explicit connection string since the
+  ``ORACLE_SID``, ``TWO_TASK``, and ``LOCAL`` environment variables are not
+  used.  They are used in Thick mode.
 
 - This is a major release so some previously deprecated features are no longer
   available. See :ref:`deprecations`.
@@ -504,7 +557,20 @@ following steps:
    as :data:`~oracledb.POOL_GETMODE_NOWAIT` and :data:`~oracledb.PURITY_SELF`
    are now preferred.  The old namespaces still work.
 
-7. Review the following sections to see if your application requirements are
+7. The method signature of the :ref:`output type handler <outputtypehandlers>`
+   which can be specified on a
+   :attr:`connection <Connection.outputtypehandler>` or on a
+   :attr:`cursor <Cursor.outputtypehandler>` is ``handler(cursor, metadata)``.
+   The old signature ``handler(cursor, name, default_type, length, precision,
+   scale)`` was deprecated in python-oracledb 1.4 but will still work and will
+   be removed in a future version.
+
+8. VARCHAR2 and LOB columns that have the ``IS JSON`` constraint enabled are
+   fetched by default as Python objects in python-oracledb. In cx_Oracle,
+   VARCHAR2 and LOB columns that contain JSON data are fetched by default as
+   strings and LOB objects respectively. See :ref:`fetchisjson`.
+
+9. Review the following sections to see if your application requirements are
    satisfied by the python-oracledb Thin mode:
 
    - :ref:`featuresummary`
@@ -513,14 +579,14 @@ following steps:
    If your application requirements are not supported by the Thin mode, then
    use the python-oracledb Thick mode.
 
-8. Review :ref:`compatibility`.
+10. Review :ref:`compatibility`.
 
    If your code base uses an older cx_Oracle version, review the previous
    :ref:`release notes <releasenotes>` for additional changes to modernize
    the code.
 
-9. Modernize code as needed or desired.  See :ref:`deprecations` for the list
-   of deprecations in python-oracledb.
+11. Modernize code as needed or desired.  See :ref:`deprecations` for the list
+    of deprecations in python-oracledb.
 
 Additional Upgrade Steps to use python-oracledb Thin Mode
 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++