From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Wed, 10 May 2023 20:44:02 +0000 (-0400)
Subject: add missing docs
X-Git-Tag: rel_2_0_13~1
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=32fc4f3de20c9d983742b064e47f591342c42de2;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

add missing docs

ColumnExpressionArgument, as well as Oracle datatypes
mentioned in the changelog

Change-Id: I9496de9a1092af21f84492ff9d91a0cefb1a8a5b
---

diff --git a/doc/build/changelog/unreleased_20/9656.rst b/doc/build/changelog/unreleased_20/9656.rst
index 16c170aa85..1b00da816e 100644
--- a/doc/build/changelog/unreleased_20/9656.rst
+++ b/doc/build/changelog/unreleased_20/9656.rst
@@ -2,7 +2,8 @@
     :tags: typing, sql
     :tickets: 9656
 
-    Added type ``ColumnExpressionArgument`` as a public alias of an internal
-    type. This type is useful since it's what' accepted by the sqlalchemy in
-    many api calls, such as :meth:`_sql.Select.where`, :meth:`_sql.and` and
-    many other.
+    Added type :data:`_sql.ColumnExpressionArgument` as a public-facing type
+    that indicates column-oriented arguments which are passed to SQLAlchemy
+    constructs, such as :meth:`_sql.Select.where`, :func:`_sql.and_` and
+    others. This may be used to add typing to end-user functions which call
+    these methods.
diff --git a/doc/build/core/internals.rst b/doc/build/core/internals.rst
index 26aa9831d2..5146ef4af4 100644
--- a/doc/build/core/internals.rst
+++ b/doc/build/core/internals.rst
@@ -70,5 +70,3 @@ Some key internal constructs are listed here.
 .. autoclass:: sqlalchemy.engine.AdaptedConnection
     :members:
 
-.. autoattribute:: sqlalchemy.sql.ColumnExpressionArgument
-    :members:
diff --git a/doc/build/core/sqlelement.rst b/doc/build/core/sqlelement.rst
index 9378409242..23dd2118b0 100644
--- a/doc/build/core/sqlelement.rst
+++ b/doc/build/core/sqlelement.rst
@@ -150,12 +150,23 @@ The classes here are generated using the constructors listed at
 .. autoclass:: ColumnCollection
    :members:
 
-
 .. autoclass:: ColumnElement
    :members:
    :inherited-members:
    :undoc-members:
 
+.. data:: ColumnExpressionArgument
+
+   General purpose "column expression" argument.
+
+   .. versionadded:: 2.0.13
+
+   This type is used for "column" kinds of expressions that typically represent
+   a single SQL column expression, including :class:`_sql.ColumnElement`, as
+   well as ORM-mapped attributes that will have a ``__clause_element__()``
+   method.
+
+
 .. autoclass:: ColumnOperators
    :members:
    :special-members:
diff --git a/doc/build/dialects/oracle.rst b/doc/build/dialects/oracle.rst
index 02f5122141..8187e71479 100644
--- a/doc/build/dialects/oracle.rst
+++ b/doc/build/dialects/oracle.rst
@@ -44,6 +44,12 @@ construction arguments, are as follows:
 .. autoclass:: BFILE
   :members: __init__
 
+.. autoclass:: BINARY_DOUBLE
+  :members: __init__
+
+.. autoclass:: BINARY_FLOAT
+  :members: __init__
+
 .. autoclass:: DATE
    :members: __init__
 
@@ -56,6 +62,9 @@ construction arguments, are as follows:
 .. autoclass:: NCLOB
   :members: __init__
 
+.. autoclass:: NVARCHAR2
+   :members: __init__
+
 .. autoclass:: NUMBER
    :members: __init__
 
@@ -65,6 +74,9 @@ construction arguments, are as follows:
 .. autoclass:: RAW
   :members: __init__
 
+.. autoclass:: ROWID
+  :members: __init__
+
 .. autoclass:: TIMESTAMP
   :members: __init__
 
diff --git a/lib/sqlalchemy/sql/_typing.py b/lib/sqlalchemy/sql/_typing.py
index 9e83c3f429..513ce78d4f 100644
--- a/lib/sqlalchemy/sql/_typing.py
+++ b/lib/sqlalchemy/sql/_typing.py
@@ -186,8 +186,11 @@ typically represent a single SQL column expression, not a set of columns the
 way a table or ORM entity does.
 
 This includes ColumnElement, or ORM-mapped attributes that will have a
-`__clause_element__()` method, it also has the ExpressionElementRole
+``__clause_element__()`` method, it also has the ExpressionElementRole
 overall which brings in the TextClause object also.
+
+.. versionadded:: 2.0.13
+
 """
 
 _ColumnExpressionOrLiteralArgument = Union[Any, _ColumnExpressionArgument[_T]]
diff --git a/lib/sqlalchemy/sql/expression.py b/lib/sqlalchemy/sql/expression.py
index 4fa9cda005..f1cb4c276a 100644
--- a/lib/sqlalchemy/sql/expression.py
+++ b/lib/sqlalchemy/sql/expression.py
@@ -61,6 +61,7 @@ from ._selectable_constructors import tablesample as tablesample
 from ._selectable_constructors import union as union
 from ._selectable_constructors import union_all as union_all
 from ._selectable_constructors import values as values
+from ._typing import ColumnExpressionArgument as ColumnExpressionArgument
 from .base import _from_objects as _from_objects
 from .base import _select_iterables as _select_iterables
 from .base import ColumnCollection as ColumnCollection