Various documentation and tutorial improvements.

anthony-tuininga · anthony-tuininga · commit 079927c8ce2d · 2020-06-25T15:23:41.000-06:00
diff --git a/doc/src/api_manual/module.rst b/doc/src/api_manual/module.rst
@@ -208,23 +208,34 @@ Module Interface
         edition=None, timeout=0, waitTimeout=0, maxLifetimeSession=0, \
         sessionCallback=None, maxSessionsPerShard=0)
 
-    Create and return a :ref:`session pool object <sesspool>`.
+    Create and return a :ref:`session pool object <sesspool>`.  Session pooling
+    (also known as connection pooling) creates a pool of available connections
+    to the database, allowing applications to acquire a connection very quickly.
+    It is of primary use in a server where connections are requested in rapid
+    succession and used for a short period of time, for example in a web server.
+    See :ref:`connpool` for more information.
+
     Connection pooling in cx_Oracle is handled by Oracle's
     `Session pooling <https://www.oracle.com/pls/topic/lookup?
     ctx=dblatest&id=GUID-F9662FFB-EAEF-495C-96FC-49C6D1D9625C>`__
     technology.  This allows cx_Oracle applications to support features
     like `Application Continuity <https://www.oracle.com/pls/topic/lookup?
     ctx=dblatest&id=GUID-A8DD9422-2F82-42A9-9555-134296416E8F>`__.
 
-    See :ref:`connpool` for information on connection pooling.
+    The user, password and dsn parameters are the same as for
+    :meth:`cx_Oracle.connect()`
 
-    Session pooling creates a pool of available connections to the
-    database, allowing applications to acquire a connection very quickly.
-    It is of primary use in a server where connections are requested
-    in rapid succession and used for a short period of time, for example in a
-    web server.
+    The min, max and increment parameters control pool growth behavior.  A fixed
+    pool size where min equals max is recommended to help prevent connection
+    storms and to help overall system stability.  The min parameter is the
+    number of connections opened when the pool is created.  The increment is the
+    number of connections that are opened whenever a connection request exceeds
+    the number of currently open connections.  The max parameter is the maximum
+    number of connections that can be open in the connection pool.  Note that
+    when :ref:`external authentication <extauth>` or :ref:`heterogeneous pools
+    <connpooltypes>` are used, the pool growth behavior is different.
 
-    If the connection type is specified, all calls to
+    If the connectiontype parameter is specified, all calls to
     :meth:`~SessionPool.acquire()` will create connection objects of that type,
     rather than the base type defined at the module level.
 
@@ -233,6 +244,10 @@ Module Interface
     Doing so in single threaded applications imposes a performance penalty of
     about 10-15% which is why the default is False.
 
+    The getmode parameter indicates whether or not future
+    :func:`SessionPool.acquire()` calls will wait for available connections.  It
+    can be one of the :ref:`Session Pool Get Modes <sesspoolmodes>` values.
+
     The events parameter is expected to be a boolean expression which indicates
     whether or not to initialize Oracle in events mode. This is required for
     continuous query notification and high availability event notifications.
@@ -241,22 +256,26 @@ Module Interface
     indicates whether or not to create a homogeneous pool. A homogeneous pool
     requires that all connections in the pool use the same credentials. As such
     proxy authentication and external authentication is not possible with a
-    homogeneous pool.
+    homogeneous pool.  See :ref:`Heterogeneous and Homogeneous Connection Pools
+    <connpooltypes>`.
 
     The externalauth parameter is expected to be a boolean expression which
     indicates whether or not external authentication should be used. External
     authentication implies that something other than the database is
     authenticating the user to the database. This includes the use of operating
-    system authentication and Oracle wallets.
+    system authentication and Oracle wallets.  See :ref:`Connecting Using
+    External Authentication <extauth>`.
 
-    See the :ref:`globalization <globalization>` section for details on the
-    encoding and nencoding parameters.  Note the default encoding and nencoding
-    values changed to "UTF-8" in cx_Oracle 8, and any character set in NLS_LANG
-    is ignored.
+    The encoding and nencoding parameters set the encodings used for string
+    values transferred between cx_Oracle and Oracle Database, see
+    :ref:`Character Sets and Globalization <globalization>`. Note the default
+    encoding and nencoding values changed to "UTF-8" in cx_Oracle 8, and any
+    character set in NLS_LANG is ignored.
 
-    The edition parameter is expected to be a string, if specified, and sets
-    the edition to use for the sessions in the pool. It is only relevant if
-    both the client and the server are at least Oracle Database 11.2.
+    The edition parameter is expected to be a string, if specified, and sets the
+    edition to use for the sessions in the pool. It is only relevant if both the
+    client and the server are at least Oracle Database 11.2.  See
+    :ref:`Edition-Based Redefinition (EBR) <ebr>`.
 
     The timeout parameter is expected to be an integer, if specified, and sets
     the length of time (in seconds) after which idle sessions in the pool are
@@ -279,17 +298,18 @@ Module Interface
     may exist.
 
     The sessionCallback parameter is expected to be either a string or a
-    callable. If the parameter is a string, this refers to a PL/SQL procedure
-    that will be called when :func:`SessionPool.acquire()` requests a tag and
-    that tag does not match the connection's actual tag. Support for the PL/SQL
-    procedure requires Oracle Client libraries 12.2 or later. See the
-    `OCI documentation <https://www.oracle.com/pls/topic/lookup?
-    ctx=dblatest&id=GUID-B853A020-752F-494A-8D88-D0396EF57177>`__ for more
-    information. If the sessionCallback parameter is a callable, however, it
-    will be called when a newly created connection is returned from the pool
-    or when a tag is requested and that tag does not match the connection's
-    actual tag. The callable will be invoked with the connection and the
-    requested tag as its only parameters.
+    callable. If the sessionCallback parameter is a callable, it will be called
+    when a newly created connection is returned from the pool, or when a tag is
+    requested and that tag does not match the connection's actual tag. The
+    callable will be invoked with the connection and the requested tag as its
+    only parameters.  If the parameter is a string, it should be the name of a
+    PL/SQL procedure that will be called when :func:`SessionPool.acquire()`
+    requests a tag and that tag does not match the connection's actual tag. See
+    :ref:`Session CallBacks for Setting Pooled Connection State
+    <sessioncallback>`. Support for the PL/SQL procedure requires Oracle Client
+    libraries 12.2 or later.  See the `OCI documentation
+    <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&
+    id=GUID-B853A020-752F-494A-8D88-D0396EF57177>`__ for more information.
 
     The maxSessionsPerShard parameter is expected to be an integer, if
     specified, and sets the maximum number of sessions in the pool that can be
@@ -823,6 +843,7 @@ also used by the :attr:`MessageTable.operation` or
     This constant is used to specify that messages should be sent when data is
     updated, or that the message identifies a row that has been updated.
 
+.. _sesspoolmodes:
 
 Session Pool Get Modes
 ----------------------
diff --git a/doc/src/api_manual/session_pool.rst b/doc/src/api_manual/session_pool.rst
@@ -150,9 +150,11 @@ SessionPool Object
 
     This read-write attribute specifies the size of the statement cache that
     will be used as the starting point for any connections that are created by
-    the session pool. Once created, the connection's statement cache size can
-    only be changed by setting the stmtcachesize attribute on the connection
-    itself.
+    the session pool. Once a connection is created, that connection's statement
+    cache size can only be changed by setting the
+    :attr:`Connection.stmtcachesize` attribute on the connection itself.
+
+    See :ref:`Statement Caching <stmtcache>` for more information.
 
     .. versionadded:: 6.0
 
diff --git a/doc/src/license.rst b/doc/src/license.rst
@@ -10,7 +10,7 @@ License
 
 .. centered:: **LICENSE AGREEMENT FOR CX_ORACLE**
 
-Copyright |copy| 2016, 2018, Oracle and/or its affiliates. All rights reserved.
+Copyright |copy| 2016, 2020, Oracle and/or its affiliates. All rights reserved.
 
 Copyright |copy| 2007-2015, Anthony Tuininga. All rights reserved.
 
diff --git a/doc/src/user_guide/connection_handling.rst b/doc/src/user_guide/connection_handling.rst
@@ -324,9 +324,9 @@ connections, so monitor the connection rate in AWR for an unexpected value.  You
 can explicitly initiate a full ping to check connection liveness with
 :meth:`Connection.ping()` but overuse will impact performance and scalability.
 
-The Oracle Real-World Performance Group's general recommendation for connection
-pools is use a fixed sized pool.  The values of `min` and `max` should be the
-same (and `increment` equal to zero).  the firewall, `resource manager
+The Oracle Real-World Performance Group's recommendation is to use fixed size
+connection pools.  The values of min and max should be the same (and the
+increment equal to zero).  The :ref:`firewall <hanetwork>`, `resource manager
 <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-2BEF5482-CF97-4A85-BD90-9195E41E74EF>`__
 or user profile `IDLE_TIME
 <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-ABC7AE4D-64A8-4EA9-857D-BEF7300B64C3>`__
@@ -336,6 +336,11 @@ Static Pools
 <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-7DFBA826-7CC0-4D16-B19C-31D168069B54>`__,
 which contains details about sizing of pools.
 
+The Real-World Performance Group also recommends keeping pool sizes small, as
+they may perform better than larger pools. The pool attributes should be
+adjusted to handle the desired workload within the bounds of available resources
+in cx_Oracle and the database.
+
 .. _sessioncallback:
 
 Session CallBacks for Setting Pooled Connection State
diff --git a/doc/src/user_guide/initialization.rst b/doc/src/user_guide/initialization.rst
@@ -38,8 +38,9 @@ cx_Oracle looks for the Oracle Client libraries as follows:
       database installation, such as Oracle Database "XE" Express Edition, then
       you will need to have previously set your environment to use that
       software installation, otherwise files such as message files will not be
-      located.  If the Oracle Client libraries cannot be loaded from
-      ``lib_dir``, then an exception is raised.
+      located. On Windows when the path contains backslashes, use a 'raw'
+      string like ``lib_dir = r"C:\instantclient_19_6"``. If the Oracle Client
+      libraries cannot be loaded from ``lib_dir``, then an exception is raised.
 
     - If ``lib_dir`` was not specified, then Oracle Client libraries are looked
       for in the directory where the cx_Oracle binary module is installed.
diff --git a/doc/src/user_guide/installation.rst b/doc/src/user_guide/installation.rst
@@ -10,19 +10,20 @@ Overview
 To use cx_Oracle 8 with Python and Oracle Database you need:
 
 - Python 3.5 and higher.  Older versions of cx_Oracle may work with older
-  versions of Python.
+  versions of Python, for example see :ref:`Installing cx_Oracle in Python 2
+  <python2>`
 
 - Oracle Client libraries. These can be from the free `Oracle Instant
   Client
   <https://www.oracle.com/database/technologies/instant-client.html>`__,
   or those included in Oracle Database if Python is on the same
   machine as the database.  Oracle client libraries versions 19, 18, 12,
   and 11.2 are supported on Linux, Windows and macOS.  Users have
-  also reported success with other platforms.
+  also reported success with other platforms.  Use the latest client possible:
+  Oracle's standard client-server version interoperability allows connection to
+  both older and newer databases.
 
-- An Oracle Database. Oracle's standard client-server version
-  interoperability allows cx_Oracle to connect to both older and newer
-  databases.
+- An Oracle Database, either local or remote.
 
 The cx_Oracle module loads Oracle Client libraries which communicate
 over Oracle Net to an existing database.  Oracle Net is not a separate
@@ -39,8 +40,8 @@ Quick Start cx_Oracle Installation
 - Install `Python <https://www.python.org/downloads>`__ 3, if not already
   available.  On macOS you must always install your own Python.
 
-  Python 3.5 and higher are supported by cx_Oracle 8.  For Python 2, use
-  cx_Oracle 7.3.
+  Python 3.5 and higher are supported by cx_Oracle 8.  For Python 2, see
+  :ref:`Installing cx_Oracle in Python 2 <python2>`.
 
 - Install cx_Oracle from `PyPI
   <https://pypi.org/project/cx-Oracle/>`__ with:
@@ -499,6 +500,8 @@ To use cx_Oracle with Oracle Instant Client zip files:
          import cx_Oracle
          cx_Oracle.init_oracle_client(lib_dir=r"C:\oracle\instantclient_19_6")
 
+     Note a 'raw' string is used because backslashes occur in the path.
+
    * Alternatively, add the Oracle Instant Client directory to the ``PATH``
      environment variable.  The directory must occur in ``PATH`` before any
      other Oracle directories.  Restart any open command prompt windows.
@@ -786,6 +789,23 @@ If you are upgrading from cx_Oracle 5 note these installation changes:
       hosted.  Use the supplied cx_Oracle Wheels instead, or use RPMs
       from Oracle, see :ref:`oraclelinux`.
 
+.. _python2:
+
+Installing cx_Oracle in Python 2
+================================
+
+To install cx_Oracle in Python 2, use a command like::
+
+    python -m pip install cx_Oracle==7.3 --upgrade --user
+
+cx_Oracle 7.3 was the last version with support for Python 2.
+
+For other installation options such as installing through a proxy, see
+instructions above.  Make sure the Oracle Client libraries are in the system
+library search path because cx_Oracle 7 does not support the
+:meth:`cx_Oracle.init_oracle_client()` method and does not support loading the
+Oracle Client libraries from the directory containing the cx_Oracle module
+binary.
 
 Installing cx_Oracle 5.3
 ========================
diff --git a/doc/src/user_guide/plsql_execution.rst b/doc/src/user_guide/plsql_execution.rst
@@ -234,6 +234,7 @@ Data from both the result sets are returned::
     (1000, 1, 'BOOKS')
     (2000, 2, 'FURNITURE')
 
+.. _ebr:
 
 Edition-Based Redefinition (EBR)
 --------------------------------
diff --git a/doc/src/user_guide/tuning.rst b/doc/src/user_guide/tuning.rst
@@ -37,7 +37,7 @@ Some general tuning tips are:
   Make good use of PL/SQL to avoid executing many individual statements from
   cx_Oracle.
 
-  Tune the Statement Cache with :attr:`Connection.stmtcachesize`.
+  Tune the :ref:`Statement Cache <stmtcache>`.
 
   Enable :ref:`Client Result Caching <clientresultcache>` for small lookup tables.
 
@@ -258,20 +258,21 @@ Statement Caching
 cx_Oracle's :meth:`Cursor.execute()` and :meth:`Cursor.executemany()` functions
 use the `Oracle Call Interface statement cache
 <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-4947CAE8-1F00-4897-BB2B-7F921E495175>`__
-to make re-execution of statements efficient.  This cache removes most needs for
-using the :meth:`Cursor.prepare()` method.
-
-The statement cache size can be set with :attr:`Connection.stmtcachesize`.
-
-Each non-pooled connection and each session in the connection pool has
-its own cache of statements with a default size of 20.  Statement
-caching lets cursors be used without re-parsing the statement.
-Statement caching also reduces meta data transfer costs between the
-cx_Oracle and the database.  Performance and scalability are
-improved.
-
-In general, set the statement cache to the size of the working set of
-statements being executed by the application.
+to make re-execution of statements efficient.  Each standalone or pooled
+connection has its own cache of statements with a default size of 20.  Statement
+caching lets cursors be used without re-parsing the statement.  Statement
+caching also reduces metadata transfer costs between the cx_Oracle and the
+database.  Performance and scalability are improved.
+
+The statement cache size can be set with :attr:`Connection.stmtcachesize` or
+:attr:`SessionPool.stmtcachesize`.  In general, set the statement cache size to
+the size of the working set of statements being executed by the application.  To
+manually tune the cache, monitor the general application load and the `Automatic
+Workload Repository
+<https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-56AEF38E-9400-427B-A818-EDEC145F7ACD>`__
+(AWR) "bytes sent via SQL*Net to client" values.  The latter statistic should
+benefit from not shipping statement metadata to cx_Oracle.  Adjust the statement
+cache size to your satisfaction.
 
 Statement caching can be disabled by setting the size to 0.  Disabling
 the cache may be beneficial when the quantity or order of statements
@@ -283,12 +284,24 @@ be flushed from the cache before the statements are re-executed.
 With Oracle Database 12c, or later, the statement cache size can be
 automatically tuned using the :ref:`oraaccess.xml <optclientfiles>` file.
 
-To manually tune the statement cache size, monitor general application load and
-the `Automatic Workload Repository
-<https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-56AEF38E-9400-427B-A818-EDEC145F7ACD>`__
-(AWR) "bytes sent via SQL*Net to client" values.  The latter statistic should
-benefit from not shipping statement metadata to cx_Oracle.  Adjust the statement
-cache size to your satisfaction.
+When it is inconvenient to pass statement text through an application, the
+:meth:`Cursor.prepare()` call can be used to avoid statement re-parsing.
+Subsequent ``execute()`` calls use the value ``None`` instead of the SQL text:
+
+.. code-block:: python
+
+    cur.prepare("select * from dept where deptno = :id order by deptno")
+
+    cur.execute(None, id = 20)
+    res = cur.fetchall()
+    print(res)
+
+    cur.execute(None, id = 10)
+    res = cur.fetchall()
+    print(res)
+
+Statements passed to :meth:`~Cursor.prepare()` are also stored in the statement
+cache.
 
 .. _clientresultcache:
 
diff --git a/samples/tutorial/Python-and-Oracle-Database-Scripting-for-the-Future.html b/samples/tutorial/Python-and-Oracle-Database-Scripting-for-the-Future.html
diff --git a/samples/tutorial/bind_query.py b/samples/tutorial/bind_query.py
diff --git a/samples/tutorial/clob.py b/samples/tutorial/clob.py
diff --git a/samples/tutorial/clob_string.py b/samples/tutorial/clob_string.py
