Various minor fixes

Fix typo in exported class in init. #10578
Improve warning for loaderes. #10579
Properly document ARRAY.contains. #10587
Mention how to set a schema to the automatically generated enums. #10583
Improve type of cache key dispatcher

Change-Id: I86e4f01f5d897b257246fe5f970b78e3444aca3e

diff --git a/doc/build/changelog/changelog_13.rst b/doc/build/changelog/changelog_13.rst
index 462511f3fdf293eba0690c5a3393d5f34e7116a8..74fc0c202da910839dbe9c0976d41f2323911e37 100644 (file)
--- a/doc/build/changelog/changelog_13.rst
+++ b/doc/build/changelog/changelog_13.rst
@@ -3337,7 +3337,7 @@
        :tags: change, orm
        :tickets: 4412
 
-       Added a new function :func:`.close_all_sessions` which takes
+       Added a new function :func:`_orm.close_all_sessions` which takes
        over the task of the :meth:`.Session.close_all` method, which
        is now deprecated as this is confusing as a classmethod.
        Pull request courtesy Augustin Trancart.

diff --git a/doc/build/orm/declarative_tables.rst b/doc/build/orm/declarative_tables.rst
index 711fa11bbee57c087f8ce26fcc723461f8891613..4a1cbd0da3db2c157c4b3b3ac920a415e01561bd 100644 (file)
--- a/doc/build/orm/declarative_tables.rst
+++ b/doc/build/orm/declarative_tables.rst
@@ -856,8 +856,23 @@ datatype::
             Status: sqlalchemy.Enum(Status, length=50, native_enum=False)
         }
 
+By default :class:`_sqltypes.Enum` that are automatically generated are not
+associated with the :class:`_sql.MetaData` instance used by the ``Base``, so if
+the metadata defines a schema it will not be automatically associated with the
+enum. To automatically associate the enum with the schema in the metadata or
+table they belong to the :paramref:`_sqltypes.Enum.inherit_schema` can be set::
+
+    from enum import Enum
+    import sqlalchemy as sa
+    from sqlalchemy.orm import DeclarativeBase
+
+
+    class Base(DeclarativeBase):
+        metadata = sa.MetaData(schema="my_schema")
+        type_annotation_map = {Enum: sa.Enum(Enum, inherit_schema=True)}
+
 Linking Specific ``enum.Enum`` or ``typing.Literal`` to other datatypes
-++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
 The above examples feature the use of an :class:`_sqltypes.Enum` that is
 automatically configuring itself to the arguments / attributes present on

diff --git a/lib/sqlalchemy/__init__.py b/lib/sqlalchemy/__init__.py
index 472f01ad06322d532605242c169aa389ad5fd8b3..871e403a77d228303a5806a184c015e4915d40ab 100644 (file)
--- a/lib/sqlalchemy/__init__.py
+++ b/lib/sqlalchemy/__init__.py
@@ -55,7 +55,7 @@ from .pool import Pool as Pool
 from .pool import PoolProxiedConnection as PoolProxiedConnection
 from .pool import PoolResetState as PoolResetState
 from .pool import QueuePool as QueuePool
-from .pool import SingletonThreadPool as SingleonThreadPool
+from .pool import SingletonThreadPool as SingletonThreadPool
 from .pool import StaticPool as StaticPool
 from .schema import BaseDDLElement as BaseDDLElement
 from .schema import BLANK_SCHEMA as BLANK_SCHEMA
@@ -273,9 +273,7 @@ __version__ = "2.0.24"
 
 
 def __go(lcls: Any) -> None:
-    from . import util as _sa_util
-
-    _sa_util.preloaded.import_prefix("sqlalchemy")
+    _util.preloaded.import_prefix("sqlalchemy")
 
     from . import exc
 
@@ -283,3 +281,14 @@ def __go(lcls: Any) -> None:
 
 
 __go(locals())
+
+
+def __getattr__(name: str) -> Any:
+    if name == "SingleonThreadPool":
+        _util.warn_deprecated(
+            "SingleonThreadPool was a typo in the v2 series. "
+            "Please use the correct SingletonThreadPool name.",
+            "2.0.24",
+        )
+        return SingletonThreadPool
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

diff --git a/lib/sqlalchemy/orm/context.py b/lib/sqlalchemy/orm/context.py
index 79b43f5fe7dd05001223d75ada73690f73562d6d..2f5e4ce8b7ba581db6b10a31a715b46181dd176d 100644 (file)
--- a/lib/sqlalchemy/orm/context.py
+++ b/lib/sqlalchemy/orm/context.py
@@ -519,9 +519,9 @@ class ORMCompileState(AbstractORMCompileState):
         ):
             util.warn(
                 "Loader depth for query is excessively deep; caching will "
-                "be disabled for additional loaders.  Consider using the "
-                "recursion_depth feature for deeply nested recursive eager "
-                "loaders.  Use the compiled_cache=None execution option to "
+                "be disabled for additional loaders.   For recursive eager "
+                "loaders consider using the recursion_depth feature.  "
+                "Use the compiled_cache=None execution option to "
                 "skip this warning."
             )
             execution_options = execution_options.union(

diff --git a/lib/sqlalchemy/sql/cache_key.py b/lib/sqlalchemy/sql/cache_key.py
index 500e3e4dd72b9fb600d5cc8016b1cc5f81835bfd..831b90809b28b410a6310056e5ad3aaa1e5c07f2 100644 (file)
--- a/lib/sqlalchemy/sql/cache_key.py
+++ b/lib/sqlalchemy/sql/cache_key.py
@@ -11,6 +11,7 @@ import enum
 from itertools import zip_longest
 import typing
 from typing import Any
+from typing import Callable
 from typing import Dict
 from typing import Iterable
 from typing import Iterator
@@ -43,7 +44,7 @@ if typing.TYPE_CHECKING:
 class _CacheKeyTraversalDispatchType(Protocol):
     def __call__(
         s, self: HasCacheKey, visitor: _CacheKeyTraversal
-    ) -> CacheKey:
+    ) -> _CacheKeyTraversalDispatchTypeReturn:
         ...
 
 
@@ -75,6 +76,18 @@ class CacheTraverseTarget(enum.Enum):
     ANON_NAME,
 ) = tuple(CacheTraverseTarget)
 
+_CacheKeyTraversalDispatchTypeReturn = Sequence[
+    Tuple[
+        str,
+        Any,
+        Union[
+            Callable[..., Tuple[Any, ...]],
+            CacheTraverseTarget,
+            InternalTraversal,
+        ],
+    ]
+]
+
 
 class HasCacheKey:
     """Mixin for objects which can produce a cache key.
@@ -324,7 +337,7 @@ class HasCacheKey:
                             ),
                         )
                     else:
-                        result += meth(
+                        result += meth(  # type: ignore
                             attrname, obj, self, anon_map, bindparams
                         )
         return result

diff --git a/lib/sqlalchemy/sql/sqltypes.py b/lib/sqlalchemy/sql/sqltypes.py
index ddee7767bc328750c4cda68e80d633861a9988c6..7e866cc032dafec75c3a6264964cb3505edc532a 100644 (file)
--- a/lib/sqlalchemy/sql/sqltypes.py
+++ b/lib/sqlalchemy/sql/sqltypes.py
@@ -2908,6 +2908,13 @@ class ARRAY(
                 return operators.getitem, index, return_type
 
         def contains(self, *arg, **kw):
+            """``ARRAY.contains()`` not implemented for the base ARRAY type.
+            Use the dialect-specific ARRAY type.
+
+            .. seealso::
+
+                :class:`_postgresql.ARRAY` - PostgreSQL specific version.
+            """
             raise NotImplementedError(
                 "ARRAY.contains() not implemented for the base "
                 "ARRAY type; please use the dialect-specific ARRAY type"