Bug
Links
def mapped_column(__name_pos: 'Optional[Union[str, _TypeEngineArgument[Any], SchemaEventTarget]]' = None, __type_pos: 'Optional[Union[_TypeEngineArgument[Any], SchemaEventTarget]]' = None, *args: 'SchemaEventTarget', init: 'Union[_NoArg, bool]' = _NoArg.NO_ARG, repr: 'Union[_NoArg, bool]' = _NoArg.NO_ARG, default: 'Optional[Any]' = _NoArg.NO_ARG, default_factory: 'Union[_NoArg, Callable[[], _T]]' = _NoArg.NO_ARG, compare: 'Union[_NoArg, bool]' = _NoArg.NO_ARG, kw_only: 'Union[_NoArg, bool]' = _NoArg.NO_ARG, hash: 'Union[_NoArg, bool, None]' = _NoArg.NO_ARG, nullable: 'Optional[Union[bool, Literal[SchemaConst.NULL_UNSPECIFIED]]]' = <SchemaConst.NULL_UNSPECIFIED: 3>, primary_key: 'Optional[bool]' = False, deferred: 'Union[_NoArg, bool]' = _NoArg.NO_ARG, deferred_group: 'Optional[str]' = None, deferred_raiseload: 'Optional[bool]' = None, use_existing_column: 'bool' = False, name: 'Optional[str]' = None, type_: 'Optional[_TypeEngineArgument[Any]]' = None, autoincrement: '_AutoIncrementType' = 'auto', doc: 'Optional[str]' = None, key: 'Optional[str]' = None, index: 'Optional[bool]' = None, unique: 'Optional[bool]' = None, info: 'Optional[_InfoType]' = None, onupdate: 'Optional[Any]' = None, insert_default: 'Optional[Any]' = _NoArg.NO_ARG, server_default: 'Optional[_ServerDefaultArgument]' = None, server_onupdate: 'Optional[_ServerOnUpdateArgument]' = None, active_history: 'bool' = False, quote: 'Optional[bool]' = None, system: 'bool' = False, comment: 'Optional[str]' = None, sort_order: 'Union[_NoArg, int]' = _NoArg.NO_ARG, **kw: 'Any') -> 'MappedColumn[Any]'
declare a new ORM-mapped :class:`_schema.Column` construct
for use within :ref:`Declarative Table <orm_declarative_table>`
configuration.
The :func:`_orm.mapped_column` function provides an ORM-aware and
Python-typing-compatible construct which is used with
:ref:`declarative <orm_declarative_mapping>` mappings to indicate an
attribute that's mapped to a Core :class:`_schema.Column` object. It
provides the equivalent feature as mapping an attribute to a
:class:`_schema.Column` object directly when using Declarative,
specifically when using :ref:`Declarative Table <orm_declarative_table>`
configuration.
.. versionadded:: 2.0
:func:`_orm.mapped_column` is normally used with explicit typing along with
the :class:`_orm.Mapped` annotation type, where it can derive the SQL
type and nullability for the column based on what's present within the
:class:`_orm.Mapped` annotation. It also may be used without annotations
as a drop-in replacement for how :class:`_schema.Column` is used in
Declarative mappings in SQLAlchemy 1.x style.
For usage examples of :func:`_orm.mapped_column`, see the documentation
at :ref:`orm_declarative_table`.
.. seealso::
:ref:`orm_declarative_table` - complete documentation
:ref:`whatsnew_20_orm_declarative_typing` - migration notes for
Declarative mappings using 1.x style mappings
:param __name: String name to give to the :class:`_schema.Column`. This
is an optional, positional only argument that if present must be the
first positional argument passed. If omitted, the attribute name to
which the :func:`_orm.mapped_column` is mapped will be used as the SQL
column name.
:param __type: :class:`_types.TypeEngine` type or instance which will
indicate the datatype to be associated with the :class:`_schema.Column`.
This is an optional, positional-only argument that if present must
immediately follow the ``__name`` parameter if present also, or otherwise
be the first positional parameter. If omitted, the ultimate type for
the column may be derived either from the annotated type, or if a
:class:`_schema.ForeignKey` is present, from the datatype of the
referenced column.
:param \*args: Additional positional arguments include constructs such
as :class:`_schema.ForeignKey`, :class:`_schema.CheckConstraint`,
and :class:`_schema.Identity`, which are passed through to the constructed
:class:`_schema.Column`.
:param nullable: Optional bool, whether the column should be "NULL" or
"NOT NULL". If omitted, the nullability is derived from the type
annotation based on whether or not ``typing.Optional`` is present.
``nullable`` defaults to ``True`` otherwise for non-primary key columns,
and ``False`` for primary key columns.
:param primary_key: optional bool, indicates the :class:`_schema.Column`
would be part of the table's primary key or not.
:param deferred: Optional bool - this keyword argument is consumed by the
ORM declarative process, and is not part of the :class:`_schema.Column`
itself; instead, it indicates that this column should be "deferred" for
loading as though mapped by :func:`_orm.deferred`.
.. seealso::
:ref:`orm_queryguide_deferred_declarative`
:param deferred_group: Implies :paramref:`_orm.mapped_column.deferred`
to ``True``, and set the :paramref:`_orm.deferred.group` parameter.
.. seealso::
:ref:`orm_queryguide_deferred_group`
:param deferred_raiseload: Implies :paramref:`_orm.mapped_column.deferred`
to ``True``, and set the :paramref:`_orm.deferred.raiseload` parameter.
.. seealso::
:ref:`orm_queryguide_deferred_raiseload`
:param use_existing_column: if True, will attempt to locate the given
column name on an inherited superclass (typically single inheriting
superclass), and if present, will not produce a new column, mapping
to the superclass column as though it were omitted from this class.
This is used for mixins that add new columns to an inherited superclass.
.. seealso::
:ref:`orm_inheritance_column_conflicts`
.. versionadded:: 2.0.0b4
:param default: Passed directly to the
:paramref:`_schema.Column.default` parameter if the
:paramref:`_orm.mapped_column.insert_default` parameter is not present.
Additionally, when used with :ref:`orm_declarative_native_dataclasses`,
indicates a default Python value that should be applied to the keyword
constructor within the generated ``__init__()`` method.
Note that in the case of dataclass generation when
:paramref:`_orm.mapped_column.insert_default` is not present, this means
the :paramref:`_orm.mapped_column.default` value is used in **two**
places, both the ``__init__()`` method as well as the
:paramref:`_schema.Column.default` parameter. While this behavior may
change in a future release, for the moment this tends to "work out"; a
default of ``None`` will mean that the :class:`_schema.Column` gets no
default generator, whereas a default that refers to a non-``None`` Python
or SQL expression value will be assigned up front on the object when
``__init__()`` is called, which is the same value that the Core
:class:`_sql.Insert` construct would use in any case, leading to the same
end result.
.. note:: When using Core level column defaults that are callables to
be interpreted by the underlying :class:`_schema.Column` in conjunction
with :ref:`ORM-mapped dataclasses
<orm_declarative_native_dataclasses>`, especially those that are
:ref:`context-aware default functions <context_default_functions>`,
**the** :paramref:`_orm.mapped_column.insert_default` **parameter must
be used instead**. This is necessary to disambiguate the callable from
being interpreted as a dataclass level default.
.. seealso::
:ref:`defaults_default_factory_insert_default`
:paramref:`_orm.mapped_column.insert_default`
:paramref:`_orm.mapped_column.default_factory`
:param insert_default: Passed directly to the
:paramref:`_schema.Column.default` parameter; will supersede the value
of :paramref:`_orm.mapped_column.default` when present, however
:paramref:`_orm.mapped_column.default` will always apply to the
constructor default for a dataclasses mapping.
.. seealso::
:ref:`defaults_default_factory_insert_default`
:paramref:`_orm.mapped_column.default`
:paramref:`_orm.mapped_column.default_factory`
:param sort_order: An integer that indicates how this mapped column
should be sorted compared to the others when the ORM is creating a
:class:`_schema.Table`. Among mapped columns that have the same
value the default ordering is used, placing first the mapped columns
defined in the main class, then the ones in the super classes.
Defaults to 0. The sort is ascending.
.. versionadded:: 2.0.4
:param active_history=False:
When ``True``, indicates that the "previous" value for a
scalar attribute should be loaded when replaced, if not
already loaded. Normally, history tracking logic for
simple non-primary-key scalar values only needs to be
aware of the "new" value in order to perform a flush. This
flag is available for applications that make use of
:func:`.attributes.get_history` or :meth:`.Session.is_modified`
which also need to know the "previous" value of the attribute.
.. versionadded:: 2.0.10
:param init: Specific to :ref:`orm_declarative_native_dataclasses`,
specifies if the mapped attribute should be part of the ``__init__()``
method as generated by the dataclass process.
:param repr: Specific to :ref:`orm_declarative_native_dataclasses`,
specifies if the mapped attribute should be part of the ``__repr__()``
method as generated by the dataclass process.
:param default_factory: Specific to
:ref:`orm_declarative_native_dataclasses`,
specifies a default-value generation function that will take place
as part of the ``__init__()``
method as generated by the dataclass process.
.. seealso::
:ref:`defaults_default_factory_insert_default`
:paramref:`_orm.mapped_column.default`
:paramref:`_orm.mapped_column.insert_default`
:param compare: Specific to
:ref:`orm_declarative_native_dataclasses`, indicates if this field
should be included in comparison operations when generating the
``__eq__()`` and ``__ne__()`` methods for the mapped class.
.. versionadded:: 2.0.0b4
:param kw_only: Specific to
:ref:`orm_declarative_native_dataclasses`, indicates if this field
should be marked as keyword-only when generating the ``__init__()``.
:param hash: Specific to
:ref:`orm_declarative_native_dataclasses`, controls if this field
is included when generating the ``__hash__()`` method for the mapped
class.
.. versionadded:: 2.0.36
:param \**kw: All remaining keyword arguments are passed through to the
constructor for the :class:`_schema.Column`.
Améliorations / Corrections
Vous avez des améliorations (ou des corrections) à proposer pour ce document : je vous remerçie par avance de m'en faire part, cela m'aide à améliorer le site.
Emplacement :
Description des améliorations :