Doc and collateral updates.

Author: anthony-tuininga

README.md

@@ -1,20 +1,53 @@
 # python-oracledb
 
-python-oracledb is a [Python programming language][python] extension module
+Python-oracledb is a [Python programming language][python] extension module
 allowing Python programs to connect to [Oracle Database][oracledb].
-Python-oracledb is the new name for Oracle's popular cx_Oracle driver.
+Python-oracledb is the new name for the obsolete cx_Oracle driver.
+
+Python-oracledb uses the same Python DB API as cx_Oracle, and has many new
+features.
 
 The module conforms to the [Python Database API 2.0 specification][pep249] with
 a considerable number of additions and a couple of minor exclusions, see the
 [feature list][features].
 
 Synchronous and [concurrent][concurrent] coding styles are supported.
 
+Python-oracledb is available under an open source license, see below.
+
 ## Installation
 
-Run `python -m pip install oracledb`
+Run:
+
+```
+python -m pip install oracledb --upgrade
+```
+
+See [python-oracledb Installation][installation] for details.
+
+## Samples
+
+Examples can be found in the [/samples][samples] directory and the
+[Python and Oracle Database Tutorial][tutorial].
 
-See [python-oracledb Installation][installation].
+A basic example:
+
+```
+import oracledb
+import getpass
+
+un = "scott"
+cs = "localhost/orclpdb"
+# cs = "localhost/freepdb1"   # for Oracle Database Free users
+# cs = "localhost/orclpdb1"   # some databases may have this service
+pw = getpass.getpass(f"Enter password for {un}@{cs}: ")
+
+with oracledb.connect(user=un, password=pw, dsn=cs) as connection:
+    with connection.cursor() as cursor:
+        sql = "select sysdate from dual"
+        for r in cursor.execute(sql):
+            print(r)
+```
 
 ## Dependencies and Interoperability
 
@@ -52,11 +85,6 @@ See [python-oracledb Installation][installation].
 See the [python-oracledb Documentation][documentation] and [Release
 Notes][relnotes].
 
-## Samples
-
-Examples can be found in the [/samples][samples] directory and the
-[Python and Oracle Database Tutorial][tutorial].
-
 ## Help
 
 Questions can be asked in [GitHub Discussions][ghdiscussions].

doc/src/user_guide/appendix_c.rst

@@ -32,7 +32,7 @@ Specification.
 cx_Oracle always runs in a Thick mode using Oracle Client libraries.  The
 features in python-oracledb Thick mode and cx_Oracle 8.3 are the same, subject
 to the :ref:`new features <releasenotes>`, some :ref:`deprecations
-<deprecations>`, and to other changes noted in this section.
+<deprecations>`, and to other changes noted in the documentation.
 
 Oracle Client Library Loading Differences from cx_Oracle
 --------------------------------------------------------
@@ -187,8 +187,9 @@ SessionPool Object Differences
 The SessionPool object (which is an alias for the :ref:`ConnectionPool object
 <connpool>`) differences between the python-oracledb and cx_Oracle drivers are:
 
-- A Python type() will show the class as ``oracledb.ConnectionPool`` instead
-  of ``cx_Oracle.SessionPool``.
+- A Python `type() <https://docs.python.org/3/library/functions.html#type>`__
+  will show the class as ``oracledb.ConnectionPool`` instead of
+  ``cx_Oracle.SessionPool``.
 
 - A new boolean attribute, ``SessionPool.thin`` (see
   :attr:`ConnectionPool.thin`) is available. This attribute is *True* if the
@@ -374,33 +375,46 @@ Example error messages are:
 Upgrading from cx_Oracle 8.3 to python-oracledb
 ===============================================
 
-This section provides the detailed steps needed to upgrade from the obsolete
-cx_Oracle driver to python-oracledb.
-
 Things to Know Before the Upgrade
 ---------------------------------
 
 Below is a list of some useful things to know before upgrading from cx_Oracle
 to python-oracledb:
 
 - You can have both cx_Oracle and python-oracledb installed, and can use both
-  in the same application.
+  in the same application.  Install python-oracledb like::
+
+      python -m pip install oracledb --upgrade
+
+  See :ref:`installation` for details.
+
+- By default, python-oracledb runs in a 'Thin' mode which connects directly to
+  Oracle Database.  This mode does not need Oracle Client libraries to be
+  installed.  However, some additional functionality is available when
+  python-oracledb uses them.  Python-oracledb is said to be in 'Thick' mode
+  when Oracle Client libraries are used. The Thick mode is equivalent to
+  cx_Oracle.
 
-- If you only want to use the python-oracledb driver in Thin mode, then you do
-  not need Oracle Client libraries such as from Oracle Instant Client.  You
-  only need to :ref:`install <installation>` the driver itself::
+- python-oracledb Thin and Thick modes have the same level of support for the
+  `Python Database API specification <https://peps.python.org/pep-0249/>`_ and
+  can be used to connect to on-premises databases and Oracle Cloud
+  databases. See :ref:`driverdiff`.
 
-      python -m pip install oracledb
+  Examples can be found in the `GitHub samples directory
+  <https://github.com/oracle/python-oracledb/tree/main/samples>`__. A basic
+  example is:
 
-  See :ref:`driverdiff`.
+  .. code-block:: python
+
+      import oracledb
+      import getpass
 
-- python-oracledb Thin and Thick modes have the same level of support for
-  the `Python Database API specification <https://peps.python.org/pep-0249/>`_
-  and can be used to connect to on-premises databases and Oracle Cloud
-  databases. However, python-oracledb Thin mode does not support some
-  advanced Oracle Database features such as Application Continuity (AC),
-  Continuous Query Notification (CQN), and Sharding. See :ref:`Features
-  Supported <featuresummary>` for details.
+      pw = getpass.getpass(f"Enter password for hr@localhost/orclpdb: ")
+
+      with oracledb.connect(user="hr", password=userpwd, dsn="localhost/orclpdb") as connection:
+          with connection.cursor() as cursor:
+              for r in cursor.execute("select sysdate from dual"):
+                  print(r)
 
 - python-oracledb can be used in SQLAlchemy, Django, Pandas, Superset and other
   frameworks and Object-relational Mappers (ORMs). To use python-oracledb in
@@ -414,17 +428,19 @@ to python-oracledb:
 
   .. code-block:: python
 
-       oracledb.connect(user="scott", password=pw, dsn="localhost/orclpdb")
+       connection = oracledb.connect(user="scott", password=pw, dsn="localhost/orclpdb")
 
   This no longer works:
 
   .. code-block:: python
 
-       oracledb.connect("scott", pw, "localhost/orclpdb")
+       connection = oracledb.connect("scott", pw, "localhost/orclpdb")
 
 - Some previously deprecated features are no longer available. See
   :ref:`deprecations`.
 
+- There are many new features, see the :ref:`release notes <releasenotes>`.
+
 .. _commonupgrade:
 
 Steps to Upgrade to python-oracledb
@@ -577,8 +593,8 @@ following steps:
 Additional Upgrade Steps to use python-oracledb Thin Mode
 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
-To use python-oracledb Thin mode, the following changes need to be made in
-addition to the common :ref:`commonupgrade`:
+To upgrade from cx_Oracle to python-oracledb Thin mode, the following changes
+need to be made in addition to the common :ref:`commonupgrade`:
 
 1. Remove calls to :func:`~oracledb.init_oracle_client` since this turns on
    python-oracledb Thick mode.
@@ -635,7 +651,7 @@ addition to the common :ref:`commonupgrade`:
    :ref:`oraaccess.xml <optclientfiles>` files.  The Thin mode lets equivalent
    properties be set in the application when connecting.
 
-6. To use python-oracledb Thin mode in an ORACLE_HOME database installation
+6. To use python-oracledb Thin mode in an ``ORACLE_HOME`` database installation
    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.
@@ -664,8 +680,8 @@ addition to the common :ref:`commonupgrade`:
 Additional Upgrade Steps to use python-oracledb Thick Mode
 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
-To use python-oracledb Thick mode, the following changes need to be made in
-addition to the common :ref:`commonupgrade`:
+To upgrade from cx_Oracle to python-oracledb Thick mode, the following changes
+need to be made in addition to the common :ref:`commonupgrade`:
 
 1. The function :func:`oracledb.init_oracle_client()` *must* be called to
    enable python-oracle Thick mode.  It can be called anywhere before the first

doc/src/user_guide/connection_handling.rst

@@ -633,8 +633,8 @@ known to python-oracledb are discarded and not passed to the database.
 
 .. _pyoparams:
 
-Python-oracledb Parameters Settable in Easy Connect Strings or Central Configuration Providers
-----------------------------------------------------------------------------------------------
+Python-oracledb Parameters Settable in Easy Connect Strings or Centralized Configuration Providers
+--------------------------------------------------------------------------------------------------
 
 Some python-oracledb connection and pool creation parameters can be set in
 :ref:`Easy Connect strings <easyconnect>` or via a :ref:`Centralized

doc/src/user_guide/installation.rst

@@ -65,17 +65,18 @@ Python-oracledb is typically installed from Python's package repository
 
   .. code-block:: python
 
-      import getpass
-
       import oracledb
+      import getpass
 
-      un = 'scott'
-      cs = 'localhost/orclpdb'
-      pw = getpass.getpass(f'Enter password for {un}@{cs}: ')
+      un = "scott"
+      cs = "localhost/orclpdb"
+      # cs = "localhost/freepdb1"   # for Oracle Database Free users
+      # cs = "localhost/orclpdb1"   # some databases may have this service
+      pw = getpass.getpass(f"Enter password for {un}@{cs}: ")
 
       with oracledb.connect(user=un, password=pw, dsn=cs) as connection:
           with connection.cursor() as cursor:
-              sql = """select sysdate from dual"""
+              sql = "select sysdate from dual"
               for r in cursor.execute(sql):
                   print(r)
 
@@ -131,8 +132,8 @@ In python-oracledb Thick mode, Oracle Database's standard client-server network
 interoperability allows connections between different versions of Oracle Client
 libraries and Oracle Database.  For current or previously certified
 configurations, see Oracle Support's `Doc ID 207303.1
-<https://support.oracle.com/epmos/faces/DocumentDisplay?id=207303.1>`__.  In
-summary:
+<https://support.oracle.com/knowledge/Oracle%20Database%20Products/207303_1.html>`__.
+In summary:
 
 - Oracle Client 23 can connect to Oracle Database 19 or later
 - Oracle Client 21 can connect to Oracle Database 12.1 or later

doc/src/user_guide/sql_execution.rst

@@ -816,8 +816,9 @@ support makes use of `Apache nanoarrow <https://arrow.apache.org/nanoarrow/>`__
 libraries to build data frames.
 
 The following data type mapping occurs from Oracle Database types to the Arrow
-types used in OracleDataFrame objects.  Querying any other data types from
-Oracle Database will result in an exception.
+types used in OracleDataFrame objects. Querying any other data types from
+Oracle Database will result in an exception. :ref:`Output type handlers
+<outputtypehandlers>` cannot be used to map data types.
 
 .. list-table-with-summary::
     :header-rows: 1

samples/async_gather.py

@@ -1,5 +1,5 @@
 # -----------------------------------------------------------------------------
-# Copyright (c) 2023, 2024, Oracle and/or its affiliates.
+# Copyright (c) 2023, 2025, 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
@@ -27,55 +27,67 @@
 #
 # Demonstrates using a connection pool with asyncio and gather().
 #
-# Multiple database sessions will be opened and used by each coroutine.  The
-# number of connections opened can depend on the speed of your environment.
+# This also shows the use of pool_alias for connection pool caching, so the
+# pool handle does not need to passed through the app.
+#
+# Each coroutine invocation will acquire a connection from the connection pool.
+# The number of connections in the pool will depend on the speed of your
+# environment. In some cases existing connections will get reused. In other
+# cases up to CONCURRENCY connections will be created by the pool.
 # -----------------------------------------------------------------------------
 
 import asyncio
 
 import oracledb
 import sample_env
 
+# Pool name for the connection pool cache
+POOL_ALIAS_NAME = "mypool"
+
 # Number of coroutines to run
 CONCURRENCY = 5
 
 # Query the unique session identifier/serial number combination of a connection
-SQL = """SELECT UNIQUE CURRENT_TIMESTAMP AS CT, sid||'-'||serial# AS SIDSER
-         FROM v$session_connect_info
-         WHERE sid = SYS_CONTEXT('USERENV', 'SID')"""
+SQL = """select unique current_timestamp as ct, sid||'-'||serial# as sidser
+         from v$session_connect_info
+         where sid = sys_context('userenv', 'sid')"""
 
 
 # Show the unique session identifier/serial number of each connection that the
-# pool opens
+# pool creates
 async def init_session(connection, requested_tag):
     res = await connection.fetchone(SQL)
     print(res[0].strftime("%H:%M:%S.%f"), "- init_session SID-SERIAL#", res[1])
 
 
 # The coroutine simply shows the session identifier/serial number of the
-# connection returned by the pool.acquire() call
-async def query(pool):
-    async with pool.acquire() as connection:
+# connection returned from the pool
+async def query():
+    async with oracledb.connect_async(
+        pool_alias=POOL_ALIAS_NAME
+    ) as connection:
         await connection.callproc("dbms_session.sleep", [1])
         res = await connection.fetchone(SQL)
         print(res[0].strftime("%H:%M:%S.%f"), "- query SID-SERIAL#", res[1])
 
 
 async def main():
-    pool = oracledb.create_pool_async(
+    oracledb.create_pool_async(
         user=sample_env.get_main_user(),
         password=sample_env.get_main_password(),
         dsn=sample_env.get_connect_string(),
         params=sample_env.get_pool_params(),
         min=1,
         max=CONCURRENCY,
         session_callback=init_session,
+        pool_alias=POOL_ALIAS_NAME,
     )
 
-    coroutines = [query(pool) for i in range(CONCURRENCY)]
+    coroutines = [query() for i in range(CONCURRENCY)]
 
     await asyncio.gather(*coroutines)
 
+    pool = oracledb.get_pool(POOL_ALIAS_NAME)
     await pool.close()