docs: Clarify Mapped accepts equivalents to Optional (#12622)

Co-authored-by: Matthew Martin <mmartin@booliproject.com>

diff --git a/doc/build/orm/basic_relationships.rst b/doc/build/orm/basic_relationships.rst
index b4a3ed2b5f5da3caf3f798c3a1b0e8c657afc28d..97ab85d7cbfd26e27cbca78462d3db34b13b8b87 100644 (file)
--- 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 ebf185d53755aef6d537299fcf39f5e5b599ca3b..a4b057d56bd0335fc29c21d0a78f763f326d4853 100644 (file)
--- 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 48f3673699f2ad80dae51c7602f2336a22d20547..e8d4a2623391e67255e833f76773f22cc9b47d4e 100644 (file)
--- 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 <orm_declarative_mapped_column_type_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 5dad065396094e7ea39edfbeb2ab3ec9f2192a66..d2f526309bc608c89cd124bf359bb8905fbf6a58 100644 (file)
--- 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