Review fixes. Add link

diff --git a/doc/build/core/engines.rst b/doc/build/core/engines.rst
index 82820b090ce3f5a68c1e30c1b4130c2ed9122522..108a939a9ea572ea29f5f6182aaa80fe7d37e4d3 100644 (file)
--- a/doc/build/core/engines.rst
+++ b/doc/build/core/engines.rst
@@ -209,7 +209,8 @@ DBAPI::
 
       engine = create_engine("oracle+oracledb://scott:tiger@tnsalias")
 
-The Oracle dialect uses the obsolete cx_Oracle driver as the default DBAPI::
+For historical reasons, the Oracle dialect uses the obsolete cx_Oracle driver
+as the default DBAPI::
 
       engine = create_engine("oracle://scott:tiger@127.0.0.1:1521/?service_name=freepdb1")
 

diff --git a/lib/sqlalchemy/dialects/oracle/base.py b/lib/sqlalchemy/dialects/oracle/base.py
index 9fcc75d22ce7c2185a195a45d11dd39144b778cd..e83204b39cce5d48909061f26292b4b2083a03ef 100644 (file)
--- a/lib/sqlalchemy/dialects/oracle/base.py
+++ b/lib/sqlalchemy/dialects/oracle/base.py
@@ -7,7 +7,8 @@
 # mypy: ignore-errors
 
 
-r""".. dialect:: oracle
+r"""
+.. dialect:: oracle
     :name: Oracle
     :normal_support: 11+
     :best_effort: 9+
@@ -54,7 +55,7 @@ Database also supports two custom options specified using dialect kwargs:
   with a 'BY DEFAULT' identity column.
 * ``oracle_order``: when ``True``, renders the ORDER keyword, indicating the
   identity is definitively ordered. May be necessary to provide deterministic
-  ordering using Oracle RAC.
+  ordering using Oracle Real Application Clusters (RAC).
 
 Using a SEQUENCE (all Oracle Database versions)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -84,7 +85,7 @@ custom option specified using dialect kwargs:
 
 * ``oracle_order``: when ``True``, renders the ORDER keyword, indicating the
   sequence is definitively ordered. May be necessary to provide deterministic
-  ordering using Oracle Real Application Clusters (RAC).
+  ordering using Oracle RAC.
 
 .. versionchanged::  1.4   Added :class:`_schema.Identity` construct
    in a :class:`_schema.Column` to specify the option of an autoincrementing
@@ -118,9 +119,9 @@ Valid values for ``isolation_level`` include:
 
 .. note:: The implementation for the
    :meth:`_engine.Connection.get_isolation_level` method as implemented by the
-   Oracle Database dialects necessarily force the start of a transaction using
-   the Oracle Database DBMS_TRANSACTION.LOCAL_TRANSACTION_ID function;
-   otherwise no level is normally readable.
+   Oracle Database dialects necessarily force the start of a transaction using the
+   Oracle Database DBMS_TRANSACTION.LOCAL_TRANSACTION_ID function; otherwise no
+   level is normally readable.
 
    Additionally, the :meth:`_engine.Connection.get_isolation_level` method will
    raise an exception if the ``v$transaction`` view is not available due to
@@ -415,8 +416,8 @@ will also include these constraints.
 Note the following caveats:
 
 * When using the :meth:`_reflection.Inspector.get_check_constraints` method,
-  Oracle Database dialects build a special "IS NOT NULL" constraint for columns
-  that specify "NOT NULL".  This constraint is **not** returned by default; to
+  Oracle Database builds a special "IS NOT NULL" constraint for columns that
+  specify "NOT NULL".  This constraint is **not** returned by default; to
   include the "IS NOT NULL" constraints, pass the flag ``include_all=True``::
 
       from sqlalchemy import create_engine, inspect

diff --git a/lib/sqlalchemy/dialects/oracle/cx_oracle.py b/lib/sqlalchemy/dialects/oracle/cx_oracle.py
index 2113defc93f1f749c3674ccadb0f1af982806188..babb916a60209ab58f0af1457ab7f3d7a38a4519 100644 (file)
--- a/lib/sqlalchemy/dialects/oracle/cx_oracle.py
+++ b/lib/sqlalchemy/dialects/oracle/cx_oracle.py
@@ -381,14 +381,6 @@ series.   This setting can be modified as follows::
             if dbapitype is CLOB:
                 del inputsizes[bindparam]
 
-.. _cx_oracle_returning:
-
-RETURNING Support
------------------
-
-The cx_Oracle dialect implements RETURNING using OUT parameters.
-The dialect supports RETURNING fully.
-
 .. _cx_oracle_lob:
 
 LOB Datatypes
@@ -404,6 +396,14 @@ buffered objects with a ``read()`` method, the parameter
 ``auto_convert_lobs=False`` may be passed to :func:`_sa.create_engine`,
 which takes place only engine-wide.
 
+.. _cx_oracle_returning:
+
+RETURNING Support
+-----------------
+
+The cx_Oracle dialect implements RETURNING using OUT parameters.
+The dialect supports RETURNING fully.
+
 Two Phase Transactions Not Supported
 ------------------------------------
 

diff --git a/lib/sqlalchemy/dialects/oracle/oracledb.py b/lib/sqlalchemy/dialects/oracle/oracledb.py
index b7cd5034a1294da416c5b654a7909f0725ded82f..541d088cd1e1b43f899adf2f8def5929f2cd4698 100644 (file)
--- a/lib/sqlalchemy/dialects/oracle/oracledb.py
+++ b/lib/sqlalchemy/dialects/oracle/oracledb.py
@@ -111,14 +111,23 @@ terminated by a firewall::
         }
     )
 
+The Easy Connect syntax has been enhanced during the life of Oracle Database.
+Review the documentation for your database version.  The current documentation
+is at `Understanding the Easy Connect Naming Method
+<https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-B0437826-43C1-49EC-A94D-B650B6A4A6EE>`_.
+
+The general syntax is similar to::
+
+    [[protocol:]//]host[:port][/[service_name]][?parameter_name=value{&parameter_name=value}]
+
 Note that although the SQLAlchemy URL syntax ``hostname:port/dbname`` looks
-like Oracle's Easy Connect syntax, it is different. It requires a system
-identifier (SID) for the ``dbname`` component of the URL::
+like Oracle's Easy Connect syntax, it is different. SQLAlchemy's URL requires a
+system identifier (SID) for the ``dbname`` component::
 
     engine = create_engine("oracle+oracledb://scott:tiger@hostname:port/sid")
 
-Easy Connect syntax does not support SIDs.  It uses services names, which are
-the preferred choice for connecting to Oracle Database
+Easy Connect syntax does not support SIDs. It uses services names, which are
+the preferred choice for connecting to Oracle Database.
 
 Passing python-oracledb connect arguments
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -249,6 +258,10 @@ connection pooling::
     with engine.connect() as conn:
         print(conn.scalar(text("select 1 from dual")))
 
+Refer to the python-oracledb documentation for `oracledb.create_pool()
+<https://python-oracledb.readthedocs.io/en/latest/api_manual/module.html#oracledb.create_pool>`_
+for the arguments that can be used when creating a connection pool.
+
 .. _drcp:
 
 Using Oracle Database Resident Connection Pooling (DRCP)
@@ -449,14 +462,6 @@ follows::
             if dbapitype is CLOB:
                 del inputsizes[bindparam]
 
-.. _oracledb_returning:
-
-RETURNING Support
------------------
-
-The oracledb dialect implements RETURNING using OUT parameters.  The dialect
-supports RETURNING fully.
-
 .. _oracledb_lob:
 
 LOB Datatypes
@@ -470,6 +475,14 @@ To disable the use of the type handlers and deliver LOB objects as classic
 buffered objects with a ``read()`` method, the parameter
 ``auto_convert_lobs=False`` may be passed to :func:`_sa.create_engine`.
 
+.. _oracledb_returning:
+
+RETURNING Support
+-----------------
+
+The oracledb dialect implements RETURNING using OUT parameters.  The dialect
+supports RETURNING fully.
+
 Two Phase Transaction Support
 -----------------------------
 
@@ -480,8 +493,6 @@ the Core level via :meth:`_engine.Connection.begin_twophase` and
 
 .. versionchanged:: 2.0.32 added support for two phase transactions
 
-.. versionadded:: 2.0.0 added support for the python-oracledb driver.
-
 .. _oracledb_numeric:
 
 Precision Numerics
@@ -523,6 +534,8 @@ SQLAlchemy type (or a subclass of such).
    been reworked to take advantage of newer driver features as well as better
    integration of outputtypehandlers.
 
+.. versionadded:: 2.0.0 added support for the python-oracledb driver.
+
 """  # noqa
 from __future__ import annotations