Merge "initial reorganize for static typing" into main

1 files changed, 104 insertions, 312 deletions

diff --git a/lib/sqlalchemy/orm/__init__.py b/lib/sqlalchemy/orm/__init__.py
index 0d197bf87..17167a7de 100644
--- a/lib/sqlalchemy/orm/__init__.py
+++ b/lib/sqlalchemy/orm/__init__.py
@@ -13,323 +13,115 @@ documentation for an overview of how this module is used.
 
 """
 
-from . import exc
+from . import exc as exc
 from . import mapper as mapperlib
-from . import strategy_options
-from .attributes import AttributeEvent
-from .attributes import InstrumentedAttribute
-from .attributes import Mapped
-from .attributes import QueryableAttribute
-from .context import QueryContext
-from .decl_api import as_declarative
-from .decl_api import declarative_base
-from .decl_api import declarative_mixin
-from .decl_api import DeclarativeMeta
-from .decl_api import declared_attr
-from .decl_api import has_inherited_table
-from .decl_api import registry
-from .decl_api import synonym_for
-from .descriptor_props import CompositeProperty
-from .descriptor_props import SynonymProperty
-from .identity import IdentityMap
-from .instrumentation import ClassManager
-from .interfaces import EXT_CONTINUE
-from .interfaces import EXT_SKIP
-from .interfaces import EXT_STOP
-from .interfaces import InspectionAttr
-from .interfaces import InspectionAttrInfo
-from .interfaces import MANYTOMANY
-from .interfaces import MANYTOONE
-from .interfaces import MapperProperty
-from .interfaces import NOT_EXTENSION
-from .interfaces import ONETOMANY
-from .interfaces import PropComparator
-from .interfaces import UserDefinedOption
-from .loading import merge_frozen_result
-from .loading import merge_result
-from .mapper import class_mapper
-from .mapper import configure_mappers
-from .mapper import Mapper
-from .mapper import reconstructor
-from .mapper import validates
-from .properties import ColumnProperty
-from .query import AliasOption
-from .query import FromStatement
-from .query import Query
-from .relationships import foreign
-from .relationships import RelationshipProperty
-from .relationships import remote
-from .scoping import scoped_session
-from .session import close_all_sessions
-from .session import make_transient
-from .session import make_transient_to_detached
-from .session import object_session
-from .session import ORMExecuteState
-from .session import Session
-from .session import sessionmaker
-from .session import SessionTransaction
-from .state import AttributeState
-from .state import InstanceState
-from .strategy_options import contains_eager
-from .strategy_options import defaultload
-from .strategy_options import defer
-from .strategy_options import immediateload
-from .strategy_options import joinedload
-from .strategy_options import lazyload
-from .strategy_options import Load
-from .strategy_options import load_only
-from .strategy_options import noload
-from .strategy_options import raiseload
-from .strategy_options import selectin_polymorphic
-from .strategy_options import selectinload
-from .strategy_options import subqueryload
-from .strategy_options import undefer
-from .strategy_options import undefer_group
-from .strategy_options import with_expression
-from .unitofwork import UOWTransaction
-from .util import aliased
-from .util import Bundle
-from .util import CascadeOptions
-from .util import join
-from .util import LoaderCriteriaOption
-from .util import object_mapper
-from .util import outerjoin
-from .util import polymorphic_union
-from .util import was_deleted
-from .util import with_parent
-from .util import with_polymorphic
-from .. import sql as _sql
+from . import strategy_options as strategy_options
+from ._orm_constructors import _mapper_fn as mapper
+from ._orm_constructors import backref as backref
+from ._orm_constructors import clear_mappers as clear_mappers
+from ._orm_constructors import column_property as column_property
+from ._orm_constructors import composite as composite
+from ._orm_constructors import contains_alias as contains_alias
+from ._orm_constructors import create_session as create_session
+from ._orm_constructors import deferred as deferred
+from ._orm_constructors import dynamic_loader as dynamic_loader
+from ._orm_constructors import query_expression as query_expression
+from ._orm_constructors import relationship as relationship
+from ._orm_constructors import synonym as synonym
+from ._orm_constructors import with_loader_criteria as with_loader_criteria
+from .attributes import AttributeEvent as AttributeEvent
+from .attributes import InstrumentedAttribute as InstrumentedAttribute
+from .attributes import Mapped as Mapped
+from .attributes import QueryableAttribute as QueryableAttribute
+from .context import QueryContext as QueryContext
+from .decl_api import as_declarative as as_declarative
+from .decl_api import declarative_base as declarative_base
+from .decl_api import declarative_mixin as declarative_mixin
+from .decl_api import DeclarativeMeta as DeclarativeMeta
+from .decl_api import declared_attr as declared_attr
+from .decl_api import has_inherited_table as has_inherited_table
+from .decl_api import registry as registry
+from .decl_api import synonym_for as synonym_for
+from .descriptor_props import CompositeProperty as CompositeProperty
+from .descriptor_props import SynonymProperty as SynonymProperty
+from .dynamic import AppenderQuery as AppenderQuery
+from .events import AttributeEvents as AttributeEvents
+from .events import InstanceEvents as InstanceEvents
+from .events import InstrumentationEvents as InstrumentationEvents
+from .events import MapperEvents as MapperEvents
+from .events import QueryEvents as QueryEvents
+from .events import SessionEvents as SessionEvents
+from .identity import IdentityMap as IdentityMap
+from .instrumentation import ClassManager as ClassManager
+from .interfaces import EXT_CONTINUE as EXT_CONTINUE
+from .interfaces import EXT_SKIP as EXT_SKIP
+from .interfaces import EXT_STOP as EXT_STOP
+from .interfaces import InspectionAttr as InspectionAttr
+from .interfaces import InspectionAttrInfo as InspectionAttrInfo
+from .interfaces import MANYTOMANY as MANYTOMANY
+from .interfaces import MANYTOONE as MANYTOONE
+from .interfaces import MapperProperty as MapperProperty
+from .interfaces import NOT_EXTENSION as NOT_EXTENSION
+from .interfaces import ONETOMANY as ONETOMANY
+from .interfaces import PropComparator as PropComparator
+from .interfaces import UserDefinedOption as UserDefinedOption
+from .loading import merge_frozen_result as merge_frozen_result
+from .loading import merge_result as merge_result
+from .mapper import class_mapper as class_mapper
+from .mapper import configure_mappers as configure_mappers
+from .mapper import Mapper as Mapper
+from .mapper import reconstructor as reconstructor
+from .mapper import validates as validates
+from .properties import ColumnProperty as ColumnProperty
+from .query import AliasOption as AliasOption
+from .query import FromStatement as FromStatement
+from .query import Query as Query
+from .relationships import foreign as foreign
+from .relationships import RelationshipProperty as RelationshipProperty
+from .relationships import remote as remote
+from .scoping import scoped_session as scoped_session
+from .session import close_all_sessions as close_all_sessions
+from .session import make_transient as make_transient
+from .session import make_transient_to_detached as make_transient_to_detached
+from .session import object_session as object_session
+from .session import ORMExecuteState as ORMExecuteState
+from .session import Session as Session
+from .session import sessionmaker as sessionmaker
+from .session import SessionTransaction as SessionTransaction
+from .state import AttributeState as AttributeState
+from .state import InstanceState as InstanceState
+from .strategy_options import contains_eager as contains_eager
+from .strategy_options import defaultload as defaultload
+from .strategy_options import defer as defer
+from .strategy_options import immediateload as immediateload
+from .strategy_options import joinedload as joinedload
+from .strategy_options import lazyload as lazyload
+from .strategy_options import Load as Load
+from .strategy_options import load_only as load_only
+from .strategy_options import noload as noload
+from .strategy_options import raiseload as raiseload
+from .strategy_options import selectin_polymorphic as selectin_polymorphic
+from .strategy_options import selectinload as selectinload
+from .strategy_options import subqueryload as subqueryload
+from .strategy_options import undefer as undefer
+from .strategy_options import undefer_group as undefer_group
+from .strategy_options import with_expression as with_expression
+from .unitofwork import UOWTransaction as UOWTransaction
+from .util import aliased as aliased
+from .util import Bundle as Bundle
+from .util import CascadeOptions as CascadeOptions
+from .util import join as join
+from .util import LoaderCriteriaOption as LoaderCriteriaOption
+from .util import object_mapper as object_mapper
+from .util import outerjoin as outerjoin
+from .util import polymorphic_union as polymorphic_union
+from .util import was_deleted as was_deleted
+from .util import with_parent as with_parent
+from .util import with_polymorphic as with_polymorphic
 from .. import util as _sa_util
-from ..exc import InvalidRequestError
-from ..util.langhelpers import public_factory
-
-
-def create_session(bind=None, **kwargs):
-    r"""Create a new :class:`.Session`
-    with no automation enabled by default.
-
-    This function is used primarily for testing.   The usual
-    route to :class:`.Session` creation is via its constructor
-    or the :func:`.sessionmaker` function.
-
-    :param bind: optional, a single Connectable to use for all
-      database access in the created
-      :class:`~sqlalchemy.orm.session.Session`.
-
-    :param \*\*kwargs: optional, passed through to the
-      :class:`.Session` constructor.
-
-    :returns: an :class:`~sqlalchemy.orm.session.Session` instance
-
-    The defaults of create_session() are the opposite of that of
-    :func:`sessionmaker`; ``autoflush`` and ``expire_on_commit`` are
-    False.
-
-    Usage::
-
-      >>> from sqlalchemy.orm import create_session
-      >>> session = create_session()
-
-    It is recommended to use :func:`sessionmaker` instead of
-    create_session().
-
-    """
-
-    kwargs.setdefault("autoflush", False)
-    kwargs.setdefault("expire_on_commit", False)
-    return Session(bind=bind, **kwargs)
-
-
-with_loader_criteria = public_factory(LoaderCriteriaOption, ".orm")
-
-relationship = public_factory(RelationshipProperty, ".orm.relationship")
-
-
-def mapper(*arg, **kw):
-    """Placeholder for the now-removed ``mapper()`` function.
-
-    Classical mappings should be performed using the
-    :meth:`_orm.registry.map_imperatively` method.
-
-    This symbol remains in SQLAlchemy 2.0 to suit the deprecated use case
-    of using the ``mapper()`` function as a target for ORM event listeners,
-    which failed to be marked as deprecated in the 1.4 series.
-
-    Global ORM mapper listeners should instead use the :class:`_orm.Mapper`
-    class as the target.
-
-    .. versionchanged:: 2.0  The ``mapper()`` function was removed; the
-       symbol remains temporarily as a placeholder for the event listening
-       use case.
-
-    """
-    raise InvalidRequestError(
-        "The 'sqlalchemy.orm.mapper()' function is removed as of "
-        "SQLAlchemy 2.0.  Use the "
-        "'sqlalchemy.orm.registry.map_imperatively()` "
-        "method of the ``sqlalchemy.orm.registry`` class to perform "
-        "classical mapping."
-    )
-
-
-def dynamic_loader(argument, **kw):
-    """Construct a dynamically-loading mapper property.
-
-    This is essentially the same as
-    using the ``lazy='dynamic'`` argument with :func:`relationship`::
-
-        dynamic_loader(SomeClass)
-
-        # is the same as
-
-        relationship(SomeClass, lazy="dynamic")
-
-    See the section :ref:`dynamic_relationship` for more details
-    on dynamic loading.
-
-    """
-    kw["lazy"] = "dynamic"
-    return relationship(argument, **kw)
-
-
-column_property = public_factory(ColumnProperty, ".orm.column_property")
-composite = public_factory(CompositeProperty, ".orm.composite")
-
-
-def backref(name, **kwargs):
-    """Create a back reference with explicit keyword arguments, which are the
-    same arguments one can send to :func:`relationship`.
-
-    Used with the ``backref`` keyword argument to :func:`relationship` in
-    place of a string argument, e.g.::
-
-        'items':relationship(
-            SomeItem, backref=backref('parent', lazy='subquery'))
-
-    .. seealso::
-
-        :ref:`relationships_backref`
-
-    """
-
-    return (name, kwargs)
-
-
-def deferred(*columns, **kw):
-    r"""Indicate a column-based mapped attribute that by default will
-    not load unless accessed.
-
-    :param \*columns: columns to be mapped.  This is typically a single
-     :class:`_schema.Column` object,
-     however a collection is supported in order
-     to support multiple columns mapped under the same attribute.
-
-    :param raiseload: boolean, if True, indicates an exception should be raised
-     if the load operation is to take place.
-
-     .. versionadded:: 1.4
-
-     .. seealso::
-
-        :ref:`deferred_raiseload`
-
-    :param \**kw: additional keyword arguments passed to
-     :class:`.ColumnProperty`.
-
-    .. seealso::
-
-        :ref:`deferred`
-
-    """
-    return ColumnProperty(deferred=True, *columns, **kw)
-
-
-def query_expression(default_expr=_sql.null()):
-    """Indicate an attribute that populates from a query-time SQL expression.
-
-    :param default_expr: Optional SQL expression object that will be used in
-        all cases if not assigned later with :func:`_orm.with_expression`.
-        E.g.::
-
-            from sqlalchemy.sql import literal
-
-            class C(Base):
-                #...
-                my_expr = query_expression(literal(1))
-
-        .. versionadded:: 1.3.18
-
-
-    .. versionadded:: 1.2
-
-    .. seealso::
-
-        :ref:`mapper_querytime_expression`
-
-    """
-    prop = ColumnProperty(default_expr)
-    prop.strategy_key = (("query_expression", True),)
-    return prop
-
-
-synonym = public_factory(SynonymProperty, ".orm.synonym")
-
-
-def clear_mappers():
-    """Remove all mappers from all classes.
-
-    .. versionchanged:: 1.4  This function now locates all
-       :class:`_orm.registry` objects and calls upon the
-       :meth:`_orm.registry.dispose` method of each.
-
-    This function removes all instrumentation from classes and disposes
-    of their associated mappers.  Once called, the classes are unmapped
-    and can be later re-mapped with new mappers.
-
-    :func:`.clear_mappers` is *not* for normal use, as there is literally no
-    valid usage for it outside of very specific testing scenarios. Normally,
-    mappers are permanent structural components of user-defined classes, and
-    are never discarded independently of their class.  If a mapped class
-    itself is garbage collected, its mapper is automatically disposed of as
-    well. As such, :func:`.clear_mappers` is only for usage in test suites
-    that re-use the same classes with different mappings, which is itself an
-    extremely rare use case - the only such use case is in fact SQLAlchemy's
-    own test suite, and possibly the test suites of other ORM extension
-    libraries which intend to test various combinations of mapper construction
-    upon a fixed set of classes.
-
-    """
-
-    mapperlib._dispose_registries(mapperlib._all_registries(), False)
-
-
-contains_alias = public_factory(AliasOption, ".orm.contains_alias")
-
-if True:
-    from .events import AttributeEvents
-    from .events import MapperEvents
-    from .events import InstanceEvents
-    from .events import InstrumentationEvents
-    from .events import QueryEvents
-    from .events import SessionEvents
 
 
 def __go(lcls):
-    global __all__
-    global AppenderQuery
-    from .. import util as sa_util
-    from . import dynamic
-    from . import events
-    from . import loading
-    import inspect as _inspect
-
-    from .dynamic import AppenderQuery
-
-    __all__ = sorted(
-        name
-        for name, obj in lcls.items()
-        if not (name.startswith("_") or _inspect.ismodule(obj))
-    )
 
     _sa_util.preloaded.import_prefix("sqlalchemy.orm")
     _sa_util.preloaded.import_prefix("sqlalchemy.ext")