From: Matthew Martin Date: Sat, 12 Jul 2025 10:34:22 +0000 (-0500) Subject: docs: Clarify Mapped accepts equivalents to Optional (#12622) X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=refs%2Fheads%2Fmain;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git docs: Clarify Mapped accepts equivalents to Optional (#12622) Co-authored-by: Matthew Martin --- diff --git a/doc/build/orm/basic_relationships.rst b/doc/build/orm/basic_relationships.rst index b4a3ed2b5f..97ab85d7cb 100644 --- a/doc/build/orm/basic_relationships.rst +++ b/doc/build/orm/basic_relationships.rst @@ -248,8 +248,8 @@ In the preceding example, the ``Parent.child`` relationship is not typed as allowing ``None``; this follows from the ``Parent.child_id`` column itself not being nullable, as it is typed with ``Mapped[int]``. If we wanted ``Parent.child`` to be a **nullable** many-to-one, we can set both -``Parent.child_id`` and ``Parent.child`` to be ``Optional[]``, in which -case the configuration would look like:: +``Parent.child_id`` and ``Parent.child`` to be ``Optional[]`` (or its +equivalent), in which case the configuration would look like:: from typing import Optional diff --git a/doc/build/orm/declarative_tables.rst b/doc/build/orm/declarative_tables.rst index ebf185d537..a4b057d56b 100644 --- a/doc/build/orm/declarative_tables.rst +++ b/doc/build/orm/declarative_tables.rst @@ -558,10 +558,11 @@ The two qualities that :func:`_orm.mapped_column` derives from the ``True``, that will also imply that the column should be ``NOT NULL``. In the absence of **both** of these parameters, the presence of - ``typing.Optional[]`` within the :class:`_orm.Mapped` type annotation will be - used to determine nullability, where ``typing.Optional[]`` means ``NULL``, - and the absence of ``typing.Optional[]`` means ``NOT NULL``. If there is no - ``Mapped[]`` annotation present at all, and there is no + ``typing.Optional[]`` (or its equivalent) within the :class:`_orm.Mapped` + type annotation will be used to determine nullability, where + ``typing.Optional[]`` means ``NULL``, and the absence of + ``typing.Optional[]`` means ``NOT NULL``. If there is no ``Mapped[]`` + annotation present at all, and there is no :paramref:`_orm.mapped_column.nullable` or :paramref:`_orm.mapped_column.primary_key` parameter, then SQLAlchemy's usual default for :class:`_schema.Column` of ``NULL`` is used. diff --git a/doc/build/orm/quickstart.rst b/doc/build/orm/quickstart.rst index 48f3673699..e8d4a26233 100644 --- a/doc/build/orm/quickstart.rst +++ b/doc/build/orm/quickstart.rst @@ -80,11 +80,11 @@ of each attribute corresponds to the column that is to be part of the database table. The datatype of each column is taken first from the Python datatype that's associated with each :class:`_orm.Mapped` annotation; ``int`` for ``INTEGER``, ``str`` for ``VARCHAR``, etc. Nullability derives from whether or -not the ``Optional[]`` type modifier is used. More specific typing information -may be indicated using SQLAlchemy type objects in the right side -:func:`_orm.mapped_column` directive, such as the :class:`.String` datatype -used above in the ``User.name`` column. The association between Python types -and SQL types can be customized using the +not the ``Optional[]`` (or its equivalent) type modifier is used. More specific +typing information may be indicated using SQLAlchemy type objects in the right +side :func:`_orm.mapped_column` directive, such as the :class:`.String` +datatype used above in the ``User.name`` column. The association between Python +types and SQL types can be customized using the :ref:`type annotation map `. The :func:`_orm.mapped_column` directive is used for all column-based diff --git a/lib/sqlalchemy/orm/_orm_constructors.py b/lib/sqlalchemy/orm/_orm_constructors.py index 5dad065396..d2f526309b 100644 --- a/lib/sqlalchemy/orm/_orm_constructors.py +++ b/lib/sqlalchemy/orm/_orm_constructors.py @@ -189,9 +189,9 @@ def mapped_column( :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. + annotation based on whether or not ``typing.Optional`` (or its equivalent) + 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