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

Co-authored-by: Matthew Martin <mmartin@booliproject.com>
(cherry picked from commit 606a979719a6e180006d881a13e53e9e3abf2e69)

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 f039407d7bf60e8fc077cec7a0f42bec30330d8f..59e7418a66328caf33e9f9fd423dbc4cb6693f2a 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 d9e3ec37ba2d8aea62634e19a912e9dc6f178619..30fc794672a494e828646a1cccbec8d04f249ac4 100644 (file)
--- a/lib/sqlalchemy/orm/_orm_constructors.py
+++ b/lib/sqlalchemy/orm/_orm_constructors.py
@@ -187,9 +187,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