File Manager

✏️ pper.py

# orm/mapper.py
# Copyright (C) 2005-2021 the SQLAlchemy authors and contributors
# <see AUTHORS file>
#
# This module is part of SQLAlchemy and is released under
# the MIT License: http://www.opensource.org/licenses/mit-license.php

"""Logic to map Python classes to and from selectables.

Defines the :class:`~sqlalchemy.orm.mapper.Mapper` class, the central
configurational unit which associates a class with a database table.

This is a semi-private module; the main configurational API of the ORM is
available in :class:`~sqlalchemy.orm.`.

"""
from __future__ import absolute_import

from collections import deque
from itertools import chain
import sys
import types
import weakref

from . import attributes
from . import exc as orm_exc
from . import instrumentation
from . import loading
from . import properties
from . import util as orm_util
from .base import _class_to_mapper
from .base import _INSTRUMENTOR
from .base import _state_mapper
from .base import class_mapper
from .base import state_str
from .interfaces import _MappedAttribute
from .interfaces import EXT_SKIP
from .interfaces import InspectionAttr
from .interfaces import MapperProperty
from .path_registry import PathRegistry
from .. import event
from .. import exc as sa_exc
from .. import inspection
from .. import log
from .. import schema
from .. import sql
from .. import util
from ..sql import expression
from ..sql import operators
from ..sql import util as sql_util
from ..sql import visitors

_mapper_registry = weakref.WeakKeyDictionary()
_already_compiling = False

_memoized_configured_property = util.group_expirable_memoized_property()

# a constant returned by _get_attr_by_column to indicate
# this mapper is not handling an attribute for a particular
# column
NO_ATTRIBUTE = util.symbol("NO_ATTRIBUTE")

# lock used to synchronize the "mapper configure" step
_CONFIGURE_MUTEX = util.threading.RLock()

@inspection._self_inspects
@log.class_logger
class Mapper(InspectionAttr):
    """Define the correlation of class attributes to database table
    columns.

The :class:`_orm.Mapper` object is instantiated using the
    :func:`~sqlalchemy.orm.mapper` function.    For information
    about instantiating new :class:`_orm.Mapper` objects, see
    that function's documentation.

When :func:`.mapper` is used
    explicitly to link a user defined class with table
    metadata, this is referred to as *classical mapping*.
    Modern SQLAlchemy usage tends to favor the
    :mod:`sqlalchemy.ext.declarative` extension for class
    configuration, which
    makes usage of :func:`.mapper` behind the scenes.

Given a particular class known to be mapped by the ORM,
    the :class:`_orm.Mapper` which maintains it can be acquired
    using the :func:`_sa.inspect` function::

from sqlalchemy import inspect

mapper = inspect(MyClass)

A class which was mapped by the :mod:`sqlalchemy.ext.declarative`
    extension will also have its mapper available via the ``__mapper__``
    attribute.

"""

_new_mappers = False
    _dispose_called = False

@util.deprecated_params(
        extension=(
            "0.7",
            ":class:`.MapperExtension` is deprecated in favor of the "
            ":class:`.MapperEvents` listener interface.  The "
            ":paramref:`.mapper.extension` parameter will be "
            "removed in a future release.",
        ),
        order_by=(
            "1.1",
            "The :paramref:`.mapper.order_by` parameter "
            "is deprecated, and will be removed in a future release. "
            "Use :meth:`_query.Query.order_by` "
            "to determine the ordering of a "
            "result set.",
        ),
        non_primary=(
            "1.3",
            "The :paramref:`.mapper.non_primary` parameter is deprecated, "
            "and will be removed in a future release.  The functionality "
            "of non primary mappers is now better suited using the "
            ":class:`.AliasedClass` construct, which can also be used "
            "as the target of a :func:`_orm.relationship` in 1.3.",
        ),
    )
    def __init__(
        self,
        class_,
        local_table=None,
        properties=None,
        primary_key=None,
        non_primary=False,
        inherits=None,
        inherit_condition=None,
        inherit_foreign_keys=None,
        extension=None,
        order_by=False,
        always_refresh=False,
        version_id_col=None,
        version_id_generator=None,
        polymorphic_on=None,
        _polymorphic_map=None,
        polymorphic_identity=None,
        concrete=False,
        with_polymorphic=None,
        polymorphic_load=None,
        allow_partial_pks=True,
        batch=True,
        column_prefix=None,
        include_properties=None,
        exclude_properties=None,
        passive_updates=True,
        passive_deletes=False,
        confirm_deleted_rows=True,
        eager_defaults=False,
        legacy_is_orphan=False,
        _compiled_cache_size=100,
    ):
        r"""Return a new :class:`_orm.Mapper` object.

This function is typically used behind the scenes
        via the Declarative extension.   When using Declarative,
        many of the usual :func:`.mapper` arguments are handled
        by the Declarative extension itself, including ``class_``,
        ``local_table``, ``properties``, and  ``inherits``.
        Other options are passed to :func:`.mapper` using
        the ``__mapper_args__`` class variable::

class MyClass(Base):
               __tablename__ = 'my_table'
               id = Column(Integer, primary_key=True)
               type = Column(String(50))
               alt = Column("some_alt", Integer)

__mapper_args__ = {
                   'polymorphic_on' : type
               }

Explicit use of :func:`.mapper`
        is often referred to as *classical mapping*.  The above
        declarative example is equivalent in classical form to::

my_table = Table("my_table", metadata,
                Column('id', Integer, primary_key=True),
                Column('type', String(50)),
                Column("some_alt", Integer)
            )

class MyClass(object):
                pass

mapper(MyClass, my_table,
                polymorphic_on=my_table.c.type,
                properties={
                    'alt':my_table.c.some_alt
                })

.. seealso::

:ref:`classical_mapping` - discussion of direct usage of
            :func:`.mapper`

:param class\_: The class to be mapped.  When using Declarative,
          this argument is automatically passed as the declared class
          itself.

:param local_table: The :class:`_schema.Table` or other selectable
           to which the class is mapped.  May be ``None`` if
           this mapper inherits from another mapper using single-table
           inheritance.   When using Declarative, this argument is
           automatically passed by the extension, based on what
           is configured via the ``__table__`` argument or via the
           :class:`_schema.Table`
           produced as a result of the ``__tablename__``
           and :class:`_schema.Column` arguments present.

:param always_refresh: If True, all query operations for this mapped
           class will overwrite all data within object instances that already
           exist within the session, erasing any in-memory changes with
           whatever information was loaded from the database. Usage of this
           flag is highly discouraged; as an alternative, see the method
           :meth:`_query.Query.populate_existing`.

:param allow_partial_pks: Defaults to True.  Indicates that a
           composite primary key with some NULL values should be considered as
           possibly existing within the database. This affects whether a
           mapper will assign an incoming row to an existing identity, as well
           as if :meth:`.Session.merge` will check the database first for a
           particular primary key value. A "partial primary key" can occur if
           one has mapped to an OUTER JOIN, for example.

:param batch: Defaults to ``True``, indicating that save operations
           of multiple entities can be batched together for efficiency.
           Setting to False indicates
           that an instance will be fully saved before saving the next
           instance.  This is used in the extremely rare case that a
           :class:`.MapperEvents` listener requires being called
           in between individual row persistence operations.

:param column_prefix: A string which will be prepended
           to the mapped attribute name when :class:`_schema.Column`
           objects are automatically assigned as attributes to the
           mapped class.  Does not affect explicitly specified
           column-based properties.

See the section :ref:`column_prefix` for an example.

:param concrete: If True, indicates this mapper should use concrete
           table inheritance with its parent mapper.

See the section :ref:`concrete_inheritance` for an example.

:param confirm_deleted_rows: defaults to True; when a DELETE occurs
          of one more rows based on specific primary keys, a warning is
          emitted when the number of rows matched does not equal the number
          of rows expected.  This parameter may be set to False to handle the
          case where database ON DELETE CASCADE rules may be deleting some of
          those rows automatically.  The warning may be changed to an
          exception in a future release.

.. versionadded:: 0.9.4 - added
             :paramref:`.mapper.confirm_deleted_rows` as well as conditional
             matched row checking on delete.

:param eager_defaults: if True, the ORM will immediately fetch the
          value of server-generated default values after an INSERT or UPDATE,
          rather than leaving them as expired to be fetched on next access.
          This can be used for event schemes where the server-generated values
          are needed immediately before the flush completes.   By default,
          this scheme will emit an individual ``SELECT`` statement per row
          inserted or updated, which note can add significant performance
          overhead.  However, if the
          target database supports :term:`RETURNING`, the default values will
          be returned inline with the INSERT or UPDATE statement, which can
          greatly enhance performance for an application that needs frequent
          access to just-generated server defaults.

.. seealso::

:ref:`orm_server_defaults`

.. versionchanged:: 0.9.0 The ``eager_defaults`` option can now
             make use of :term:`RETURNING` for backends which support it.

:param exclude_properties: A list or set of string column names to
          be excluded from mapping.

See :ref:`include_exclude_cols` for an example.

:param extension: A :class:`.MapperExtension` instance or
           list of :class:`.MapperExtension` instances which will be applied
           to all operations by this :class:`_orm.Mapper`.

:param include_properties: An inclusive list or set of string column
          names to map.

See :ref:`include_exclude_cols` for an example.

:param inherits: A mapped class or the corresponding
          :class:`_orm.Mapper`
          of one indicating a superclass to which this :class:`_orm.Mapper`
          should *inherit* from.   The mapped class here must be a subclass
          of the other mapper's class.   When using Declarative, this argument
          is passed automatically as a result of the natural class
          hierarchy of the declared classes.

.. seealso::

:ref:`inheritance_toplevel`

:param inherit_condition: For joined table inheritance, a SQL
           expression which will
           define how the two tables are joined; defaults to a natural join
           between the two tables.

:param inherit_foreign_keys: When ``inherit_condition`` is used and
           the columns present are missing a :class:`_schema.ForeignKey`
           configuration, this parameter can be used to specify which columns
           are "foreign".  In most cases can be left as ``None``.

:param legacy_is_orphan: Boolean, defaults to ``False``.
          When ``True``, specifies that "legacy" orphan consideration
          is to be applied to objects mapped by this mapper, which means
          that a pending (that is, not persistent) object is auto-expunged
          from an owning :class:`.Session` only when it is de-associated
          from *all* parents that specify a ``delete-orphan`` cascade towards
          this mapper.  The new default behavior is that the object is
          auto-expunged when it is de-associated with *any* of its parents
          that specify ``delete-orphan`` cascade.  This behavior is more
          consistent with that of a persistent object, and allows behavior to
          be consistent in more scenarios independently of whether or not an
          orphan object has been flushed yet or not.

See the change note and example at :ref:`legacy_is_orphan_addition`
          for more detail on this change.

:param non_primary: Specify that this :class:`_orm.Mapper`
          is in addition
          to the "primary" mapper, that is, the one used for persistence.
          The :class:`_orm.Mapper` created here may be used for ad-hoc
          mapping of the class to an alternate selectable, for loading
          only.

:paramref:`_orm.Mapper.non_primary` is not an often used option, but
          is useful in some specific :func:`_orm.relationship` cases.

.. seealso::

:ref:`relationship_non_primary_mapper`

:param order_by: A single :class:`_schema.Column` or list of
           :class:`_schema.Column`
           objects for which selection operations should use as the default
           ordering for entities.  By default mappers have no pre-defined
           ordering.

:param passive_deletes: Indicates DELETE behavior of foreign key
           columns when a joined-table inheritance entity is being deleted.
           Defaults to ``False`` for a base mapper; for an inheriting mapper,
           defaults to ``False`` unless the value is set to ``True``
           on the superclass mapper.

When ``True``, it is assumed that ON DELETE CASCADE is configured
           on the foreign key relationships that link this mapper's table
           to its superclass table, so that when the unit of work attempts
           to delete the entity, it need only emit a DELETE statement for the
           superclass table, and not this table.

When ``False``, a DELETE statement is emitted for this mapper's
           table individually.  If the primary key attributes local to this
           table are unloaded, then a SELECT must be emitted in order to
           validate these attributes; note that the primary key columns
           of a joined-table subclass are not part of the "primary key" of
           the object as a whole.

Note that a value of ``True`` is **always** forced onto the
           subclass mappers; that is, it's not possible for a superclass
           to specify passive_deletes without this taking effect for
           all subclass mappers.

.. versionadded:: 1.1

.. seealso::

:ref:`passive_deletes` - description of similar feature as
               used with :func:`_orm.relationship`

:paramref:`.mapper.passive_updates` - supporting ON UPDATE
               CASCADE for joined-table inheritance mappers

:param passive_updates: Indicates UPDATE behavior of foreign key
           columns when a primary key column changes on a joined-table
           inheritance mapping.   Defaults to ``True``.

When True, it is assumed that ON UPDATE CASCADE is configured on
           the foreign key in the database, and that the database will handle
           propagation of an UPDATE from a source column to dependent columns
           on joined-table rows.

When False, it is assumed that the database does not enforce
           referential integrity and will not be issuing its own CASCADE
           operation for an update.  The unit of work process will
           emit an UPDATE statement for the dependent columns during a
           primary key change.

.. seealso::

:ref:`passive_updates` - description of a similar feature as
               used with :func:`_orm.relationship`

:paramref:`.mapper.passive_deletes` - supporting ON DELETE
               CASCADE for joined-table inheritance mappers

:param polymorphic_load: Specifies "polymorphic loading" behavior
          for a subclass in an inheritance hierarchy (joined and single
          table inheritance only).   Valid values are:

* "'inline'" - specifies this class should be part of the
              "with_polymorphic" mappers, e.g. its columns will be included
              in a SELECT query against the base.

* "'selectin'" - specifies that when instances of this class
              are loaded, an additional SELECT will be emitted to retrieve
              the columns specific to this subclass.  The SELECT uses
              IN to fetch multiple subclasses at once.

.. versionadded:: 1.2

.. seealso::

:ref:`with_polymorphic_mapper_config`

:ref:`polymorphic_selectin`

:param polymorphic_on: Specifies the column, attribute, or
          SQL expression used to determine the target class for an
          incoming row, when inheriting classes are present.

This value is commonly a :class:`_schema.Column` object that's
          present in the mapped :class:`_schema.Table`::

class Employee(Base):
                __tablename__ = 'employee'

id = Column(Integer, primary_key=True)
                discriminator = Column(String(50))

__mapper_args__ = {
                    "polymorphic_on":discriminator,
                    "polymorphic_identity":"employee"
                }

It may also be specified
          as a SQL expression, as in this example where we
          use the :func:`.case` construct to provide a conditional
          approach::

class Employee(Base):
                __tablename__ = 'employee'

id = Column(Integer, primary_key=True)
                discriminator = Column(String(50))

__mapper_args__ = {
                    "polymorphic_on":case([
                        (discriminator == "EN", "engineer"),
                        (discriminator == "MA", "manager"),
                    ], else_="employee"),
                    "polymorphic_identity":"employee"
                }

It may also refer to any attribute
          configured with :func:`.column_property`, or to the
          string name of one::

class Employee(Base):
                    __tablename__ = 'employee'

id = Column(Integer, primary_key=True)
                    discriminator = Column(String(50))
                    employee_type = column_property(
                        case([
                            (discriminator == "EN", "engineer"),
                            (discriminator == "MA", "manager"),
                        ], else_="employee")
                    )

__mapper_args__ = {
                        "polymorphic_on":employee_type,
                        "polymorphic_identity":"employee"
                    }

When setting ``polymorphic_on`` to reference an
          attribute or expression that's not present in the
          locally mapped :class:`_schema.Table`, yet the value
          of the discriminator should be persisted to the database,
          the value of the
          discriminator is not automatically set on new
          instances; this must be handled by the user,
          either through manual means or via event listeners.
          A typical approach to establishing such a listener
          looks like::

from sqlalchemy import event
                from sqlalchemy.orm import object_mapper

@event.listens_for(Employee, "init", propagate=True)
                def set_identity(instance, *arg, **kw):
                    mapper = object_mapper(instance)
                    instance.discriminator = mapper.polymorphic_identity

Where above, we assign the value of ``polymorphic_identity``
          for the mapped class to the ``discriminator`` attribute,
          thus persisting the value to the ``discriminator`` column
          in the database.

.. warning::

Currently, **only one discriminator column may be set**, typically
             on the base-most class in the hierarchy. "Cascading" polymorphic
             columns are not yet supported.

.. seealso::

:ref:`inheritance_toplevel`

:param polymorphic_identity: Specifies the value which
          identifies this particular class as returned by the
          column expression referred to by the ``polymorphic_on``
          setting.  As rows are received, the value corresponding
          to the ``polymorphic_on`` column expression is compared
          to this value, indicating which subclass should
          be used for the newly reconstructed object.

:param properties: A dictionary mapping the string names of object
           attributes to :class:`.MapperProperty` instances, which define the
           persistence behavior of that attribute.  Note that
           :class:`_schema.Column`
           objects present in
           the mapped :class:`_schema.Table` are automatically placed into
           ``ColumnProperty`` instances upon mapping, unless overridden.
           When using Declarative, this argument is passed automatically,
           based on all those :class:`.MapperProperty` instances declared
           in the declared class body.

:param primary_key: A list of :class:`_schema.Column`
           objects which define
           the primary key to be used against this mapper's selectable unit.
           This is normally simply the primary key of the ``local_table``, but
           can be overridden here.

:param version_id_col: A :class:`_schema.Column`
           that will be used to keep a running version id of rows
           in the table.  This is used to detect concurrent updates or
           the presence of stale data in a flush.  The methodology is to
           detect if an UPDATE statement does not match the last known
           version id, a
           :class:`~sqlalchemy.orm.exc.StaleDataError` exception is
           thrown.
           By default, the column must be of :class:`.Integer` type,
           unless ``version_id_generator`` specifies an alternative version
           generator.

.. seealso::

:ref:`mapper_version_counter` - discussion of version counting
              and rationale.

:param version_id_generator: Define how new version ids should
          be generated.  Defaults to ``None``, which indicates that
          a simple integer counting scheme be employed.  To provide a custom
          versioning scheme, provide a callable function of the form::

def generate_version(version):
                  return next_version

Alternatively, server-side versioning functions such as triggers,
          or programmatic versioning schemes outside of the version id
          generator may be used, by specifying the value ``False``.
          Please see :ref:`server_side_version_counter` for a discussion
          of important points when using this option.

.. versionadded:: 0.9.0 ``version_id_generator`` supports
             server-side version number generation.

.. seealso::

:ref:`custom_version_counter`

:ref:`server_side_version_counter`

:param with_polymorphic: A tuple in the form ``(<classes>,
            <selectable>)`` indicating the default style of "polymorphic"
            loading, that is, which tables are queried at once. <classes> is
            any single or list of mappers and/or classes indicating the
            inherited classes that should be loaded at once. The special value
            ``'*'`` may be used to indicate all descending classes should be
            loaded immediately. The second tuple argument <selectable>
            indicates a selectable that will be used to query for multiple
            classes.

.. seealso::

:ref:`with_polymorphic` - discussion of polymorphic querying
              techniques.

"""

self.class_ = util.assert_arg_type(class_, type, "class_")

self.class_manager = None

self._primary_key_argument = util.to_list(primary_key)
        self.non_primary = non_primary

if order_by is not False:
            self.order_by = util.to_list(order_by)
        else:
            self.order_by = order_by

self.always_refresh = always_refresh

if isinstance(version_id_col, MapperProperty):
            self.version_id_prop = version_id_col
            self.version_id_col = None
        else:
            self.version_id_col = version_id_col
        if version_id_generator is False:
            self.version_id_generator = False
        elif version_id_generator is None:
            self.version_id_generator = lambda x: (x or 0) + 1
        else:
            self.version_id_generator = version_id_generator

self.concrete = concrete
        self.single = False
        self.inherits = inherits
        self.local_table = local_table
        self.inherit_condition = inherit_condition
        self.inherit_foreign_keys = inherit_foreign_keys
        self._init_properties = properties or {}
        self._delete_orphans = []
        self.batch = batch
        self.eager_defaults = eager_defaults
        self.column_prefix = column_prefix
        self.polymorphic_on = expression._clause_element_as_expr(
            polymorphic_on
        )
        self._dependency_processors = []
        self.validators = util.immutabledict()
        self.passive_updates = passive_updates
        self.passive_deletes = passive_deletes
        self.legacy_is_orphan = legacy_is_orphan
        self._clause_adapter = None
        self._requires_row_aliasing = False
        self._inherits_equated_pairs = None
        self._memoized_values = {}
        self._compiled_cache_size = _compiled_cache_size
        self._reconstructor = None
        self._deprecated_extensions = util.to_list(extension or [])
        self.allow_partial_pks = allow_partial_pks

if self.inherits and not self.concrete:
            self.confirm_deleted_rows = False
        else:
            self.confirm_deleted_rows = confirm_deleted_rows

if isinstance(self.local_table, expression.SelectBase):
            raise sa_exc.InvalidRequestError(
                "When mapping against a select() construct, map against "
                "an alias() of the construct instead."
                "This because several databases don't allow a "
                "SELECT from a subquery that does not have an alias."
            )

self._set_with_polymorphic(with_polymorphic)
        self.polymorphic_load = polymorphic_load

# our 'polymorphic identity', a string name that when located in a
        #  result set row indicates this Mapper should be used to construct
        # the object instance for that row.
        self.polymorphic_identity = polymorphic_identity

# a dictionary of 'polymorphic identity' names, associating those
        # names with Mappers that will be used to construct object instances
        # upon a select operation.
        if _polymorphic_map is None:
            self.polymorphic_map = {}
        else:
            self.polymorphic_map = _polymorphic_map

if include_properties is not None:
            self.include_properties = util.to_set(include_properties)
        else:
            self.include_properties = None
        if exclude_properties:
            self.exclude_properties = util.to_set(exclude_properties)
        else:
            self.exclude_properties = None

self.configured = False

# prevent this mapper from being constructed
        # while a configure_mappers() is occurring (and defer a
        # configure_mappers() until construction succeeds)
        _CONFIGURE_MUTEX.acquire()
        try:
            self.dispatch._events._new_mapper_instance(class_, self)
            self._configure_inheritance()
            self._configure_legacy_instrument_class()
            self._configure_class_instrumentation()
            self._configure_listeners()
            self._configure_properties()
            self._configure_polymorphic_setter()
            self._configure_pks()
            Mapper._new_mappers = True
            self._log("constructed")
            self._expire_memoizations()
        finally:
            _CONFIGURE_MUTEX.release()

# major attributes initialized at the classlevel so that
    # they can be Sphinx-documented.

is_mapper = True
    """Part of the inspection API."""

represents_outer_join = False

@property
    def mapper(self):
        """Part of the inspection API.

Returns self.

"""
        return self

@property
    def entity(self):
        r"""Part of the inspection API.

Returns self.class\_.

"""
        return self.class_

local_table = None
    """The :class:`_expression.Selectable` which this :class:`_orm.Mapper`
    manages.

Typically is an instance of :class:`_schema.Table` or
    :class:`_expression.Alias`.
    May also be ``None``.

The "local" table is the
    selectable that the :class:`_orm.Mapper` is directly responsible for
    managing from an attribute access and flush perspective.   For
    non-inheriting mappers, the local table is the same as the
    "mapped" table.   For joined-table inheritance mappers, local_table
    will be the particular sub-table of the overall "join" which
    this :class:`_orm.Mapper` represents.  If this mapper is a
    single-table inheriting mapper, local_table will be ``None``.

.. seealso::

:attr:`_orm.Mapper.persist_selectable`.

"""

persist_selectable = None
    """The :class:`_expression.Selectable` to which this :class:`_orm.Mapper`
    is mapped.

Typically an instance of :class:`_schema.Table`,
    :class:`_expression.Join`, or :class:`_expression.Alias`.

The :attr:`_orm.Mapper.persist_selectable` is separate from
    :attr:`_orm.Mapper.selectable` in that the former represents columns
    that are mapped on this class or its superclasses, whereas the
    latter may be a "polymorphic" selectable that contains additional columns
    which are in fact mapped on subclasses only.

"persist selectable" is the "thing the mapper writes to" and
    "selectable" is the "thing the mapper selects from".

:attr:`_orm.Mapper.persist_selectable` is also separate from
    :attr:`_orm.Mapper.local_table`, which represents the set of columns that
    are locally mapped on this class directly.

.. seealso::

:attr:`_orm.Mapper.selectable`.

:attr:`_orm.Mapper.local_table`.

"""

inherits = None
    """References the :class:`_orm.Mapper` which this :class:`_orm.Mapper`
    inherits from, if any.