'Return a new :class:`~.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:`.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:`.Table` produced as a result of the ``__tablename__``
and :class:`.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.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:`.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 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.
.. 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:`.Mapper`.  **Deprecated.**
Please see :class:`.MapperEvents`.
: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:`.Mapper`
of one indicating a superclass to which this :class:`.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:`.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 orphanable
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.
.. versionadded:: 0.8 - the consideration of a pending object as
an "orphan" has been modified to more closely match the
behavior as that of persistent objects, which is that the object
is expunged from the :class:`.Session` as soon as it is
de-associated from any of its orphan-enabled parents.  Previously,
the pending object would be expunged only if de-associated
from all of its orphan-enabled parents. The new flag ``legacy_is_orphan``
is added to :func:`.orm.mapper` which re-establishes the
legacy behavior.
:param non_primary: Specify that this :class:`.Mapper` is in addition
to the "primary" mapper, that is, the one used for persistence.
The :class:`.Mapper` created here may be used for ad-hoc
mapping of the class to an alternate selectable, for loading
only.
:paramref:`.Mapper.non_primary` is not an often used option, but
is useful in some specific :func:`.relationship` cases.
.. seealso::
:ref:`relationship_non_primary_mapper`
:param order_by: A single :class:`.Column` or list of :class:`.Column`
objects for which selection operations should use as the default
ordering for entities.  By default mappers have no pre-defined
ordering.
: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:`.relationship`
: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:`.Column` object that\'s
present in the mapped :class:`.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"
.. versionchanged:: 0.7.4
``polymorphic_on`` may be specified as a SQL expression,
or refer to any attribute configured with
:func:`.column_property`, or to the string name of one.
When setting ``polymorphic_on`` to reference an
attribute or expression that\'s not present in the
locally mapped :class:`.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.
.. 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:`.Column`
objects present in
the mapped :class:`.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:`.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:`.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.'

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, allow_partial_pks=True, batch=True, column_prefix=None, include_properties=None, exclude_properties=None, passive_updates=True, confirm_deleted_rows=True, eager_defaults=False, legacy_is_orphan=False, _compiled_cache_size=100):

    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.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
    self._set_with_polymorphic(with_polymorphic)
    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.")
    if (self.with_polymorphic and isinstance(self.with_polymorphic[1], expression.SelectBase)):
        self.with_polymorphic = (self.with_polymorphic[0], self.with_polymorphic[1].alias())
    self.polymorphic_identity = polymorphic_identity
    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
    _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()
