Documntation updates.

anthony-tuininga · anthony-tuininga · commit d5aaff8995a8 · 2022-09-12T10:22:58.000-06:00
diff --git a/doc/src/api_manual/module.rst b/doc/src/api_manual/module.rst
@@ -906,6 +906,9 @@ Oracledb Methods
 
         This method is an extension to the DB API definition.
 
+    .. versionadded:: 1.1.0
+
+
 .. function:: makedsn(host, port, sid=None, service_name=None, region=None, \
         sharding_key=None, super_sharding_key=None)
 
diff --git a/doc/src/index.rst b/doc/src/index.rst
@@ -11,8 +11,9 @@ additions and a couple of exclusions.
 This module is currently tested with Python 3.6, 3.7, 3.8, 3.9, and 3.10
 against Oracle Database 21c, 19c, 18c, 12c, and 11.2.
 
-Changes in python-oracledb releases can be found in the :ref:`release notes
-<releasenotes>`.
+**python-oracledb** is distributed under an open-source
+:ref:`license <license>`. Changes in python-oracledb releases can be found in
+the :ref:`release notes <releasenotes>`.
 
 User Guide
 ==========
diff --git a/doc/src/license.rst b/doc/src/license.rst
@@ -10,7 +10,7 @@ License
 
 .. centered:: **LICENSE AGREEMENT FOR python-oracledb**
 
-Copyright (c) 2016, 2022 Oracle and/or its affiliates.
+Copyright |copy| 2016, 2022 Oracle and/or its affiliates.
 
 This software is dual-licensed to you under the Universal Permissive License
 (UPL) 1.0 as shown at https://oss.oracle.com/licenses/upl and Apache License
diff --git a/doc/src/user_guide/appendix_c.rst b/doc/src/user_guide/appendix_c.rst
@@ -144,6 +144,12 @@ 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
@@ -216,6 +222,14 @@ Replace:
 - :meth:`Connection.enq()` with :meth:`Queue.enqone()` or :meth:`Queue.enqmany()`
 - :meth:`Connection.deqoptions()` with attribute :attr:`Queue.deqoptions`
 
+The AQ feature in the python-oracledb driver differs from cx_Oracle as follows:
+
+- AQ messages can be enqueued and dequeued as a JSON payload type
+- Recipient lists can be enqueued and dequeued
+- Enqueue options, dequeue options, and message properties can be set
+
+See :ref:`Oracle Advanced Queuing (AQ) <aqusermanual>`.
+
 .. _errordiff:
 
 Error Handling Differences from cx_Oracle
diff --git a/doc/src/user_guide/batch_statement.rst b/doc/src/user_guide/batch_statement.rst
@@ -1,8 +1,8 @@
 .. _batchstmnt:
 
-******************************************
-Executing Batch Statement and Bulk Loading
-******************************************
+*******************************************
+Executing Batch Statements and Bulk Loading
+*******************************************
 
 Inserting or updating multiple rows can be performed efficiently with
 :meth:`Cursor.executemany()`, making it easy to work with large data sets with
diff --git a/doc/src/user_guide/initialization.rst b/doc/src/user_guide/initialization.rst
@@ -50,15 +50,19 @@ begins with ``python-oracledb thk``. See :ref:`vsessconinfo`.
 
 .. _libinit:
 
-Locating the Oracle Client Libraries
-------------------------------------
+Setting the Oracle Client Library Directory
+-------------------------------------------
 
 When :meth:`~oracledb.init_oracle_client()` is called, python-oracledb
 dynamically loads Oracle Client libraries using a search heuristic.  Only the
-first set of libraries found are loaded.  The libraries can be in an
-installation of Oracle Instant Client, in a full Oracle Client installation, or
-in an Oracle Database installation (if Python is running on the same machine as
-the database).  The versions of Oracle Client and Oracle Database do not have
+first set of libraries found are loaded.  The libraries can be:
+
+- in an installation of Oracle Instant Client
+- or in a full Oracle Client installation
+- or in an Oracle Database installation (if Python is running on the same
+  machine as the database).
+
+The versions of Oracle Client and Oracle Database do not have
 to be the same.  For certified configurations see Oracle Support's `Doc ID
 207303.1
 <https://support.oracle.com/epmos/faces/DocumentDisplay?id=207303.1>`__.
@@ -68,150 +72,151 @@ libraries.
 
 .. _wininit:
 
-* On Windows, python-oracledb Thick mode can be enabled as follows:
+Setting the Oracle Client Directory on Windows
+++++++++++++++++++++++++++++++++++++++++++++++
 
-  - By passing the ``lib_dir`` parameter in a call to
-    :meth:`~oracledb.init_oracle_client()`, for example:
+On Windows, python-oracledb Thick mode can be enabled as follows:
 
-    .. code-block:: python
+- By passing the ``lib_dir`` parameter in a call to
+  :meth:`~oracledb.init_oracle_client()`, for example:
 
-        import oracledb
+  .. code-block:: python
 
-        oracledb.init_oracle_client(lib_dir=r"C:\instantclient_19_14")
+      import oracledb
 
-    This directory should contain the libraries from an unzipped Instant
-    Client 'Basic' or 'Basic Light' package.  If you pass the library
-    directory from a full client or database installation, such as Oracle
-    Database "XE" Express Edition, then you will need to have previously set
-    your environment to use that same software installation. Otherwise, files
-    such as message files will not be located and you may have library
-    version clashes.  On Windows, when the path contains backslashes, use a
-    'raw' string like ``r"C:\instantclient_19_14"``.
+      oracledb.init_oracle_client(lib_dir=r"C:\instantclient_19_14")
 
-    If the Oracle Client libraries cannot be loaded from ``lib_dir``, then an
-    exception is raised.
+  This directory should contain the libraries from an unzipped Instant
+  Client 'Basic' or 'Basic Light' package.  If you pass the library
+  directory from a full client or database installation, such as Oracle
+  Database "XE" Express Edition, then you will need to have previously set
+  your environment to use that same software installation. Otherwise, files
+  such as message files will not be located and you may have library
+  version clashes.  On Windows, when the path contains backslashes, use a
+  'raw' string like ``r"C:\instantclient_19_14"``.
 
-  - By calling :meth:`~oracledb.init_oracle_client()` without passing a
-    ``lib_dir`` parameter:
+  If the Oracle Client libraries cannot be loaded from ``lib_dir``, then an
+  exception is raised.
 
-    .. code-block:: python
+- By calling :meth:`~oracledb.init_oracle_client()` without passing a
+  ``lib_dir`` parameter:
 
-        import oracledb
+  .. code-block:: python
 
-        oracledb.init_oracle_client()
+      import oracledb
+
+      oracledb.init_oracle_client()
 
-    In this case, Oracle Client libraries are first looked for in the
-    directory where the python-oracledb binary module is installed.  This
-    directory should contain the libraries from an unzipped Instant Client
-    'Basic' or 'Basic Light' package.
+  In this case, Oracle Client libraries are first looked for in the
+  directory where the python-oracledb binary module is installed.  This
+  directory should contain the libraries from an unzipped Instant Client
+  'Basic' or 'Basic Light' package.
 
-    If the libraries are not found there, the search looks at the directories
-    on the system library search path, for example, the ``PATH`` environment
-    variable.
+  If the libraries are not found there, the search looks at the directories
+  on the system library search path, for example, the ``PATH`` environment
+  variable.
 
-    If the Oracle Client libraries cannot be loaded, then an exception is
-    raised.
+  If the Oracle Client libraries cannot be loaded, then an exception is
+  raised.
 
 .. _macinit:
 
-* On macOS, python-oracledb Thick mode can be enabled as follows:
+Setting the Oracle Client Directory on macOS
+++++++++++++++++++++++++++++++++++++++++++++
 
-  - By passing the ``lib_dir`` parameter in a call to
-    :meth:`~oracledb.init_oracle_client()`, for example:
+On macOS, python-oracledb Thick mode can be enabled as follows:
 
-    .. code-block:: python
+- By passing the ``lib_dir`` parameter in a call to
+  :meth:`~oracledb.init_oracle_client()`, for example:
 
-        import oracledb
+  .. code-block:: python
 
-        oracledb.init_oracle_client(lib_dir="/Users/your_username/Downloads/instantclient_19_8")
+      import oracledb
 
-    This directory should contain the libraries from an unzipped Instant
-    Client 'Basic' or 'Basic Light' package.  If the Oracle Client libraries
-    cannot be loaded from ``lib_dir``, then an exception is raised.
+      oracledb.init_oracle_client(lib_dir="/Users/your_username/Downloads/instantclient_19_8")
 
-  - By calling :meth:`~oracledb.init_oracle_client()` without passing a
-    ``lib_dir`` parameter:
+  This directory should contain the libraries from an unzipped Instant
+  Client 'Basic' or 'Basic Light' package.  If the Oracle Client libraries
+  cannot be loaded from ``lib_dir``, then an exception is raised.
+
+- By calling :meth:`~oracledb.init_oracle_client()` without passing a
+  ``lib_dir`` parameter:
 
     .. code-block:: python
 
         import oracledb
 
         oracledb.init_oracle_client()
 
-    In this case, the Oracle Client libraries are first looked for in the
-    directory where the python-oracledb Thick mode binary module is installed.
-    This directory should contain the libraries from an unzipped Instant Client
-    'Basic' or 'Basic Light' package, or a symbolic link to the main Oracle
-    Client library if Instant Client is in a different directory.
-
-    You can find the directory containing the Thick mode binary module by
-    calling the python CLI without specifying a Python script, executing
-    ``import oracledb``, and then typing ``oracledb`` at the prompt.  For
-    example if
-    ``/Users/yourname/Library/3.9.6/lib/python3.9/site-packages/oracledb-1.0.0-py3.9-macosx-11.5-x86_64.egg/oracledb``
-    contains ``thick_impl.cpython-39-darwin.so``, then you could run ``ln -s
-    ~/Downloads/instantclient_19_8/libclntsh.dylib
-    ~/Library/3.9.6/lib/python3.9/site-packages/oracledb-1.0.0-py3.9-macosx-11.5-x86_64.egg/oracledb/``.
-
-    If python-oracledb does not find the Oracle Client library in that
-    directory, the directories on the system library search path may be used,
-    for example, ``~/lib/`` and ``/usr/local/lib``, or in ``$DYLD_LIBRARY_PATH``.
-    These paths will vary with macOS version and Python version.  Any value
-    in ``DYLD_LIBRARY_PATH`` will not propagate to a sub-shell.
-
-    If the Oracle Client libraries cannot be loaded, then an exception is
-    raised.
+  In this case, the Oracle Client libraries are first looked for in the
+  directory where the python-oracledb Thick mode binary module is installed.
+  This directory should contain the libraries from an unzipped Instant Client
+  'Basic' or 'Basic Light' package, or a symbolic link to the main Oracle
+  Client library if Instant Client is in a different directory.
+
+  You can find the directory containing the Thick mode binary module by
+  calling the python CLI without specifying a Python script, executing
+  ``import oracledb``, and then typing ``oracledb`` at the prompt.  For
+  example if
+  ``/Users/yourname/Library/3.9.6/lib/python3.9/site-packages/oracledb-1.0.0-py3.9-macosx-11.5-x86_64.egg/oracledb``
+  contains ``thick_impl.cpython-39-darwin.so``, then you could run ``ln -s
+  ~/Downloads/instantclient_19_8/libclntsh.dylib
+  ~/Library/3.9.6/lib/python3.9/site-packages/oracledb-1.0.0-py3.9-macosx-11.5-x86_64.egg/oracledb/``.
+
+  If python-oracledb does not find the Oracle Client library in that
+  directory, the directories on the system library search path may be used,
+  for example, ``~/lib/`` and ``/usr/local/lib``, or in ``$DYLD_LIBRARY_PATH``.
+  These paths will vary with macOS version and Python version.  Any value
+  in ``DYLD_LIBRARY_PATH`` will not propagate to a sub-shell.
+
+  If the Oracle Client libraries cannot be loaded, then an exception is
+  raised.
 
 .. _linuxinit:
 
-* On Linux and related platforms, python-oracledb Thick mode can be enabled as
-  follows:
+Setting the Oracle Client Directory on Linux and Related Platforms
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
-  - By calling :meth:`~oracledb.init_oracle_client()` without passing a
-    ``lib_dir`` parameter:
+On Linux and related platforms, python-oracledb Thick mode can be enabled as
+follows:
 
-    .. code-block:: python
+- By calling :meth:`~oracledb.init_oracle_client()` without passing a
+  ``lib_dir`` parameter:
 
-        import oracledb
+  .. code-block:: python
 
-        oracledb.init_oracle_client()
+      import oracledb
 
-   Oracle Client libraries are looked for in the operating system library
-   search path, such as configured with ``ldconfig`` or set in the environment
-   variable ``LD_LIBRARY_PATH``.  On some UNIX platforms an OS specific
-   equivalent, such as ``LIBPATH`` or ``SHLIB_PATH`` is used instead of
-   ``LD_LIBRARY_PATH``.
-
-   If libraries are not found in the system library search path, then
-   ``$ORACLE_HOME/lib`` will be used.  Note that the environment variable
-   ``ORACLE_HOME`` should only ever be set when you have a full database
-   installation or full client installation (such as installed with the Oracle
-   GUI installer).  It should not be set if you are using Oracle Instant
-   Client.  The ``ORACLE_HOME`` variable, and other necessary variables, should
-   be set before starting Python.  See :ref:`envset`.
-
-   If the Oracle Client libraries cannot be loaded, then an exception is
-   raised.
-
-Ensure that the Python process has directory and file access permissions for the
-Oracle Client libraries.  On Linux ensure a ``libclntsh.so`` file exists.  On
-macOS ensure a ``libclntsh.dylib`` file exists.  python-oracledb Thick will not directly
-load ``libclntsh.*.XX.1`` files in ``lib_dir`` or from the directory where the
-python-oracledb binary module is available.  Note that other libraries used by
-``libclntsh*`` are also required.
+      oracledb.init_oracle_client()
 
-To trace the loading of Oracle Client libraries, the environment variable
-``DPI_DEBUG_LEVEL`` can be set to 64 before starting Python.  For example, on
-Linux, you might use::
+  Oracle Client libraries are looked for in the operating system library
+  search path, such as configured with ``ldconfig`` or set in the environment
+  variable ``LD_LIBRARY_PATH``.  On some UNIX platforms an OS specific
+  equivalent, such as ``LIBPATH`` or ``SHLIB_PATH`` is used instead of
+  ``LD_LIBRARY_PATH``.
 
-    $ export DPI_DEBUG_LEVEL=64
-    $ python myapp.py 2> log.txt
+  If libraries are not found in the system library search path, then
+  ``$ORACLE_HOME/lib`` will be used.  Note that the environment variable
+  ``ORACLE_HOME`` should only ever be set when you have a full database
+  installation or full client installation (such as installed with the Oracle
+  GUI installer).  It should not be set if you are using Oracle Instant
+  Client.  The ``ORACLE_HOME`` variable, and other necessary variables, should
+  be set before starting Python.  See :ref:`envset`.
 
+  If the Oracle Client libraries cannot be loaded, then an exception is
+  raised.
+
+Ensure that the Python process has directory and file access permissions for
+the Oracle Client libraries.  On Linux ensure a ``libclntsh.so`` file exists.
+On macOS ensure a ``libclntsh.dylib`` file exists.  python-oracledb Thick will
+not directly load ``libclntsh.*.XX.1`` files in ``lib_dir`` or from the directory
+where the python-oracledb binary module is available.  Note that other libraries
+used by ``libclntsh*`` are also required.
 
 .. _usinginitoracleclient:
 
-Using oracledb.init_oracle_client() to set the Oracle Client directory
-++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+Calling oracledb.init_oracle_client() to Set the Oracle Client Directory
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
 Oracle Client Libraries are loaded when :meth:`oracledb.init_oracle_client()`
 is called.  In some environments, applications can use the ``lib_dir``
@@ -250,6 +255,16 @@ variable.  Otherwise, you will get errors like ``ORA-1804``.  You should set thi
 along with other Oracle environment variables before starting Python as
 shown in :ref:`envset`.
 
+**Tracing Oracle Client Libraries Loading**
+
+To trace the loading of Oracle Client libraries, the environment variable
+``DPI_DEBUG_LEVEL`` can be set to 64 before starting Python.  For example, on
+Linux, you might use::
+
+    $ export DPI_DEBUG_LEVEL=64
+    $ python myapp.py 2> log.txt
+
+
 .. _optnetfiles:
 
 Optional Oracle Net Configuration Files
