Fix a wide variety of typos and broken links

Note the PR has a few remaining doc linking issues
listed in the comment that must be addressed separately.

Signed-off-by: aplatkouski <5857672+aplatkouski@users.noreply.github.com>
Closes: #5371
Pull-request: https://github.com/sqlalchemy/sqlalchemy/pull/5371
Pull-request-sha: 7e7d233cf3a0c66980c27db0fcdb3c7d93bc2510

Change-Id: I9c36e8d8804483950db4b42c38ee456e384c59e3

11 files changed, 79 insertions, 78 deletions

diff --git a/lib/sqlalchemy/orm/base.py b/lib/sqlalchemy/orm/base.py
index 54e45cd1a..6fdf1f372 100644
--- a/lib/sqlalchemy/orm/base.py
+++ b/lib/sqlalchemy/orm/base.py
@@ -463,8 +463,8 @@ class InspectionAttr(object):
     __slots__ = ()
 
     is_selectable = False
-    """Return True if this object is an instance of """
-    """:class:`expression.Selectable`."""
+    """Return True if this object is an instance of
+    :class:`_expression.Selectable`."""
 
     is_aliased_class = False
     """True if this object is an instance of :class:`.AliasedClass`."""
@@ -505,8 +505,8 @@ class InspectionAttr(object):
     """
 
     is_clause_element = False
-    """True if this object is an instance of """
-    """:class:`_expression.ClauseElement`."""
+    """True if this object is an instance of
+    :class:`_expression.ClauseElement`."""
 
     extension_type = NOT_EXTENSION
     """The extension type, if any.
diff --git a/lib/sqlalchemy/orm/context.py b/lib/sqlalchemy/orm/context.py
index 77237f089..3a0cce609 100644
--- a/lib/sqlalchemy/orm/context.py
+++ b/lib/sqlalchemy/orm/context.py
@@ -792,7 +792,7 @@ class ORMSelectCompileState(ORMCompileState, SelectState):
         if self.order_by:
             # the default coercion for ORDER BY is now the OrderByRole,
             # which adds an additional post coercion to ByOfRole in that
-            # elements are converted into label refernences.  For the
+            # elements are converted into label references.  For the
             # eager load / subquery wrapping case, we need to un-coerce
             # the original expressions outside of the label references
             # in order to have them render.
@@ -1421,16 +1421,16 @@ class ORMSelectCompileState(ORMCompileState, SelectState):
                     "from, there are multiple FROMS which can "
                     "join to this entity. Please use the .select_from() "
                     "method to establish an explicit left side, as well as "
-                    "providing an explcit ON clause if not present already to "
-                    "help resolve the ambiguity."
+                    "providing an explicit ON clause if not present already "
+                    "to help resolve the ambiguity."
                 )
             else:
                 raise sa_exc.InvalidRequestError(
                     "Don't know how to join to %r. "
                     "Please use the .select_from() "
                     "method to establish an explicit left side, as well as "
-                    "providing an explcit ON clause if not present already to "
-                    "help resolve the ambiguity." % (right,)
+                    "providing an explicit ON clause if not present already "
+                    "to help resolve the ambiguity." % (right,)
                 )
 
         elif self._entities:
@@ -1467,16 +1467,16 @@ class ORMSelectCompileState(ORMCompileState, SelectState):
                     "from, there are multiple FROMS which can "
                     "join to this entity. Please use the .select_from() "
                     "method to establish an explicit left side, as well as "
-                    "providing an explcit ON clause if not present already to "
-                    "help resolve the ambiguity."
+                    "providing an explicit ON clause if not present already "
+                    "to help resolve the ambiguity."
                 )
             else:
                 raise sa_exc.InvalidRequestError(
                     "Don't know how to join to %r. "
                     "Please use the .select_from() "
                     "method to establish an explicit left side, as well as "
-                    "providing an explcit ON clause if not present already to "
-                    "help resolve the ambiguity." % (right,)
+                    "providing an explicit ON clause if not present already "
+                    "to help resolve the ambiguity." % (right,)
                 )
         else:
             raise sa_exc.InvalidRequestError(
@@ -2471,7 +2471,7 @@ class _ORMColumnEntity(_ColumnEntity):
             column = column._deannotate()
 
         # use entity_zero as the from if we have it. this is necessary
-        # for polymorpic scenarios where our FROM is based on ORM entity,
+        # for polymorphic scenarios where our FROM is based on ORM entity,
         # not the FROM of the column.  but also, don't use it if our column
         # doesn't actually have any FROMs that line up, such as when its
         # a scalar subquery.
diff --git a/lib/sqlalchemy/orm/dynamic.py b/lib/sqlalchemy/orm/dynamic.py
index adc976e32..d15127563 100644
--- a/lib/sqlalchemy/orm/dynamic.py
+++ b/lib/sqlalchemy/orm/dynamic.py
@@ -274,7 +274,7 @@ class AppenderMixin(object):
             # this is a hack right now.  The Query only knows how to
             # make subsequent joins() without a given left-hand side
             # from self._from_obj[0].  We need to ensure prop.secondary
-            # is in the FROM.  So we purposly put the mapper selectable
+            # is in the FROM.  So we purposely put the mapper selectable
             # in _from_obj[0] to ensure a user-defined join() later on
             # doesn't fail, and secondary is then in _from_obj[1].
             self._from_obj = (prop.mapper.selectable, prop.secondary)
diff --git a/lib/sqlalchemy/orm/instrumentation.py b/lib/sqlalchemy/orm/instrumentation.py
index 432bff7d4..43e380101 100644
--- a/lib/sqlalchemy/orm/instrumentation.py
+++ b/lib/sqlalchemy/orm/instrumentation.py
@@ -40,7 +40,7 @@ from ..util import HasMemoized
 
 
 class ClassManager(HasMemoized, dict):
-    """tracks state information at the class level."""
+    """Tracks state information at the class level."""
 
     MANAGER_ATTR = base.DEFAULT_MANAGER_ATTR
     STATE_ATTR = base.DEFAULT_STATE_ATTR
@@ -229,7 +229,7 @@ class ClassManager(HasMemoized, dict):
         setattr(self.class_, self.MANAGER_ATTR, self)
 
     def dispose(self):
-        """Dissasociate this manager from its class."""
+        """Disassociate this manager from its class."""
 
         delattr(self.class_, self.MANAGER_ATTR)
 
@@ -493,7 +493,7 @@ class InstrumentationFactory(object):
 
 
 # this attribute is replaced by sqlalchemy.ext.instrumentation
-# when importred.
+# when imported.
 _instrumentation_factory = InstrumentationFactory()
 
 # these attributes are replaced by sqlalchemy.ext.instrumentation
diff --git a/lib/sqlalchemy/orm/loading.py b/lib/sqlalchemy/orm/loading.py
index a33e1b77d..abb8ce32d 100644
--- a/lib/sqlalchemy/orm/loading.py
+++ b/lib/sqlalchemy/orm/loading.py
@@ -657,7 +657,7 @@ def _instance_processor(
                             cached_populators,
                         )
             else:
-                # loader strategries like subqueryload, selectinload,
+                # loader strategies like subqueryload, selectinload,
                 # joinedload, basically relationships, these need to interact
                 # with the context each time to work correctly.
                 todo.append(prop)
@@ -1249,7 +1249,7 @@ def load_scalar_attributes(mapper, state, attribute_names, passive):
     # concrete inheritance, the class manager might have some keys
     # of attributes on the superclass that we didn't actually map.
     # These could be mapped as "concrete, dont load" or could be completely
-    # exluded from the mapping and we know nothing about them.  Filter them
+    # excluded from the mapping and we know nothing about them.  Filter them
     # here to prevent them from coming through.
     if attribute_names:
         attribute_names = attribute_names.intersection(mapper.attrs.keys())
diff --git a/lib/sqlalchemy/orm/mapper.py b/lib/sqlalchemy/orm/mapper.py
index ef0e9a49b..2b04f1cc7 100644
--- a/lib/sqlalchemy/orm/mapper.py
+++ b/lib/sqlalchemy/orm/mapper.py
@@ -324,7 +324,7 @@ class Mapper(
           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.
+          orphan 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.
@@ -733,7 +733,7 @@ class Mapper(
         return self.class_
 
     local_table = None
-    """The :class:`expression.Selectable` which this :class:`_orm.Mapper`
+    """The :class:`_expression.Selectable` which this :class:`_orm.Mapper`
     manages.
 
     Typically is an instance of :class:`_schema.Table` or
@@ -756,12 +756,11 @@ class Mapper(
     """
 
     persist_selectable = None
-    """The :class:`expression.Selectable` to which this :class:`_orm.Mapper`
+    """The :class:`_expression.Selectable` to which this :class:`_orm.Mapper`
     is mapped.
 
-    Typically an instance of :class:`_schema.Table`, :class:`_expression.Join`
-    , or
-    :class:`_expression.Alias`.
+    Typically an instance of :class:`_schema.Table`,
+    :class:`_expression.Join`, or :class:`_expression.Alias`.
 
     The :attr:`_orm.Mapper.persist_selectable` is separate from
     :attr:`_orm.Mapper.selectable` in that the former represents columns
diff --git a/lib/sqlalchemy/orm/query.py b/lib/sqlalchemy/orm/query.py
index 458217e22..336b7d9aa 100644
--- a/lib/sqlalchemy/orm/query.py
+++ b/lib/sqlalchemy/orm/query.py
@@ -436,7 +436,7 @@ class Query(
         reduce_columns=False,
         _legacy_core_statement=False,
     ):
-        """return the full SELECT statement represented by
+        """Return the full SELECT statement represented by
         this :class:`_query.Query`, embedded within an
         :class:`_expression.Alias`.
 
@@ -561,9 +561,9 @@ class Query(
         Analogous to
         :meth:`sqlalchemy.sql.expression.SelectBase.scalar_subquery`.
 
-        .. versionchanged:: 1.4 the :meth:`_query.Query.scalar_subquery`
-           method
-           replaces the :meth:`_query.Query.as_scalar` method.
+        .. versionchanged:: 1.4 The :meth:`_query.Query.scalar_subquery`
+           method replaces the :meth:`_query.Query.as_scalar` method.
+
         """
 
         return self.enable_eagerloads(False).statement.scalar_subquery()
@@ -645,8 +645,8 @@ class Query(
 
         .. note:: The :meth:`_query.Query.with_labels` method *only* applies
            the output of :attr:`_query.Query.statement`, and *not* to any of
-           the result-row invoking systems of :class:`_query.Query` itself, e.
-           g.
+           the result-row invoking systems of :class:`_query.Query` itself,
+           e.g.
            :meth:`_query.Query.first`, :meth:`_query.Query.all`, etc.
            To execute
            a query using :meth:`_query.Query.with_labels`, invoke the
@@ -879,8 +879,8 @@ class Query(
          the order in which they correspond to the mapped
          :class:`_schema.Table`
          object's primary key columns, or if the
-         :paramref:`_orm.Mapper.primary_key` configuration parameter were used
-         , in
+         :paramref:`_orm.Mapper.primary_key` configuration parameter were
+         used, in
          the order used for that parameter. For example, if the primary key
          of a row is represented by the integer
          digits "5, 10" the call would look like::
@@ -1621,10 +1621,10 @@ class Query(
 
     @_generative
     def params(self, *args, **kwargs):
-        r"""add values for bind parameters which may have been
+        r"""Add values for bind parameters which may have been
         specified in filter().
 
-        parameters may be specified using \**kwargs, or optionally a single
+        Parameters may be specified using \**kwargs, or optionally a single
         dictionary as the first positional argument. The reason for both is
         that \**kwargs is convenient, however some parameter dictionaries
         contain unicode keys in which case \**kwargs cannot be used.
@@ -1643,7 +1643,7 @@ class Query(
     @_generative
     @_assertions(_no_statement_condition, _no_limit_offset)
     def filter(self, *criterion):
-        r"""apply the given filtering criterion to a copy
+        r"""Apply the given filtering criterion to a copy
         of this :class:`_query.Query`, using SQL expressions.
 
         e.g.::
@@ -1702,7 +1702,7 @@ class Query(
         return self._raw_columns[0]
 
     def filter_by(self, **kwargs):
-        r"""apply the given filtering criterion to a copy
+        r"""Apply the given filtering criterion to a copy
         of this :class:`_query.Query`, using keyword expressions.
 
         e.g.::
@@ -1743,11 +1743,12 @@ class Query(
     @_generative
     @_assertions(_no_statement_condition, _no_limit_offset)
     def order_by(self, *clauses):
-        """apply one or more ORDER BY criterion to the query and return
-        the newly resulting ``Query``
+        """Apply one or more ORDER BY criterion to the query and return
+        the newly resulting :class:`_query.Query`.
+
+        All existing ORDER BY settings can be suppressed by  passing
+        ``None``.
 
-        All existing ORDER BY settings candef order_by be suppressed by
-        passing ``None``.
         """
 
         if len(clauses) == 1 and (clauses[0] is None or clauses[0] is False):
@@ -1774,15 +1775,15 @@ class Query(
     @_generative
     @_assertions(_no_statement_condition, _no_limit_offset)
     def group_by(self, *clauses):
-        """apply one or more GROUP BY criterion to the query and return
-        the newly resulting :class:`_query.Query`
+        """Apply one or more GROUP BY criterion to the query and return
+        the newly resulting :class:`_query.Query`.
 
         All existing GROUP BY settings can be suppressed by
         passing ``None`` - this will suppress any GROUP BY configured
         on mappers as well.
 
-        .. versionadded:: 1.1 GROUP BY can be cancelled by passing None,
-           in the same way as ORDER BY.
+        .. versionadded:: 1.1 GROUP BY can be cancelled by passing
+           ``None``, in the same way as ORDER BY.
 
         """
 
@@ -1810,7 +1811,7 @@ class Query(
     @_generative
     @_assertions(_no_statement_condition, _no_limit_offset)
     def having(self, criterion):
-        r"""apply a HAVING criterion to the query and return the
+        r"""Apply a HAVING criterion to the query and return the
         newly resulting :class:`_query.Query`.
 
         :meth:`_query.Query.having` is used in conjunction with
@@ -1948,7 +1949,7 @@ class Query(
         Where above, the call to :meth:`_query.Query.join` along
         ``User.addresses`` will result in SQL approximately equivalent to::
 
-            SELECT user.id, User.name
+            SELECT user.id, user.name
             FROM user JOIN address ON user.id = address.user_id
 
         In the above example we refer to ``User.addresses`` as passed to
diff --git a/lib/sqlalchemy/orm/session.py b/lib/sqlalchemy/orm/session.py
index a398da793..abc990f7b 100644
--- a/lib/sqlalchemy/orm/session.py
+++ b/lib/sqlalchemy/orm/session.py
@@ -218,7 +218,7 @@ class ORMExecuteState(util.MemoizedSlots):
     def is_orm_statement(self):
         """return True if the operation is an ORM statement.
 
-        This indictes that the select(), update(), or delete() being
+        This indicates that the select(), update(), or delete() being
         invoked contains ORM entities as subjects.   For a statement
         that does not have ORM entities and instead refers only to
         :class:`.Table` metadata, it is invoked as a Core SQL statement
@@ -1319,7 +1319,7 @@ class Session(_SessionClassMethods):
         resolved through any of the optional keyword arguments.   This
         ultimately makes usage of the :meth:`.get_bind` method for resolution.
 
-        :param bind_arguments: dictionary of bind arguments.  may include
+        :param bind_arguments: dictionary of bind arguments.  May include
          "mapper", "bind", "clause", other custom arguments that are passed
          to :meth:`.Session.get_bind`.
 
@@ -1462,8 +1462,8 @@ class Session(_SessionClassMethods):
 
         The :meth:`.Session.execute` method does *not* invoke autoflush.
 
-        The :class:`_engine.CursorResult` returned by the :meth:`.Session.
-        execute`
+        The :class:`_engine.CursorResult` returned by the
+        :meth:`.Session.execute`
         method is returned with the "close_with_result" flag set to true;
         the significance of this flag is that if this :class:`.Session` is
         autocommitting and does not have a transaction-dedicated
@@ -1476,7 +1476,7 @@ class Session(_SessionClassMethods):
         :class:`.Session` is configured with autocommit=True and no
         transaction has been started.
 
-        :param clause:
+        :param statement:
             An executable statement (i.e. an :class:`.Executable` expression
             such as :func:`_expression.select`) or string SQL statement
             to be executed.
@@ -1489,7 +1489,7 @@ class Session(_SessionClassMethods):
             must correspond to parameter names present in the statement.
 
         :param bind_arguments: dictionary of additional arguments to determine
-         the bind.  may include "mapper", "bind", or other custom arguments.
+         the bind.  May include "mapper", "bind", or other custom arguments.
          Contents of this dictionary are passed to the
          :meth:`.Session.get_bind` method.
 
@@ -1701,8 +1701,8 @@ class Session(_SessionClassMethods):
 
     def bind_mapper(self, mapper, bind):
         """Associate a :class:`_orm.Mapper` or arbitrary Python class with a
-        "bind", e.g. an :class:`_engine.Engine` or :class:`_engine.Connection`
-        .
+        "bind", e.g. an :class:`_engine.Engine` or
+        :class:`_engine.Connection`.
 
         The given entity is added to a lookup used by the
         :meth:`.Session.get_bind` method.
@@ -1781,15 +1781,15 @@ class Session(_SessionClassMethods):
 
         The order of resolution is:
 
-        1. if mapper given and session.binds is present,
+        1. if mapper given and :paramref:`.Session.binds` is present,
            locate a bind based first on the mapper in use, then
            on the mapped class in use, then on any base classes that are
            present in the ``__mro__`` of the mapped class, from more specific
            superclasses to more general.
-        2. if clause given and session.binds is present,
+        2. if clause given and ``Session.binds`` is present,
            locate a bind based on :class:`_schema.Table` objects
-           found in the given clause present in session.binds.
-        3. if session.bind is present, return that.
+           found in the given clause present in ``Session.binds``.
+        3. if ``Session.binds`` is present, return that.
         4. if clause given, attempt to return a bind
            linked to the :class:`_schema.MetaData` ultimately
            associated with the clause.
@@ -2783,7 +2783,7 @@ class Session(_SessionClassMethods):
 
         .. seealso::
 
-            ``load_on_pending`` at :func:`_orm.relationship` - this flag
+            :paramref:`_orm.relationship.load_on_pending` - this flag
             allows per-relationship loading of many-to-ones on items that
             are pending.
 
@@ -3568,7 +3568,7 @@ class sessionmaker(_SessionClassMethods):
 
         sess = Session()
 
-    .. seealso:
+    .. seealso::
 
         :ref:`session_getting` - introductory text on creating
         sessions using :class:`.sessionmaker`.
diff --git a/lib/sqlalchemy/orm/state.py b/lib/sqlalchemy/orm/state.py
index 48546f24e..233283497 100644
--- a/lib/sqlalchemy/orm/state.py
+++ b/lib/sqlalchemy/orm/state.py
@@ -119,7 +119,7 @@ class InstanceState(interfaces.InspectionAttrInfo):
 
     @property
     def transient(self):
-        """Return true if the object is :term:`transient`.
+        """Return ``True`` if the object is :term:`transient`.
 
         .. seealso::
 
@@ -130,7 +130,7 @@ class InstanceState(interfaces.InspectionAttrInfo):
 
     @property
     def pending(self):
-        """Return true if the object is :term:`pending`.
+        """Return ``True`` if the object is :term:`pending`.
 
 
         .. seealso::
@@ -142,7 +142,7 @@ class InstanceState(interfaces.InspectionAttrInfo):
 
     @property
     def deleted(self):
-        """Return true if the object is :term:`deleted`.
+        """Return ``True`` if the object is :term:`deleted`.
 
         An object that is in the deleted state is guaranteed to
         not be within the :attr:`.Session.identity_map` of its parent
@@ -196,7 +196,7 @@ class InstanceState(interfaces.InspectionAttrInfo):
 
     @property
     def persistent(self):
-        """Return true if the object is :term:`persistent`.
+        """Return ``True`` if the object is :term:`persistent`.
 
         An object that is in the persistent state is guaranteed to
         be within the :attr:`.Session.identity_map` of its parent
@@ -217,7 +217,7 @@ class InstanceState(interfaces.InspectionAttrInfo):
 
     @property
     def detached(self):
-        """Return true if the object is :term:`detached`.
+        """Return ``True`` if the object is :term:`detached`.
 
         .. seealso::
 
@@ -324,7 +324,7 @@ class InstanceState(interfaces.InspectionAttrInfo):
         """Return ``True`` if this object has an identity key.
 
         This should always have the same value as the
-        expression ``state.persistent or state.detached``.
+        expression ``state.persistent`` or ``state.detached``.
 
         """
         return bool(self.key)
diff --git a/lib/sqlalchemy/orm/unitofwork.py b/lib/sqlalchemy/orm/unitofwork.py
index 5a3f99e70..97eea4864 100644
--- a/lib/sqlalchemy/orm/unitofwork.py
+++ b/lib/sqlalchemy/orm/unitofwork.py
@@ -177,7 +177,7 @@ class UOWTransaction(object):
         return bool(self.states)
 
     def was_already_deleted(self, state):
-        """return true if the given state is expired and was deleted
+        """Return ``True`` if the given state is expired and was deleted
         previously.
         """
         if state.expired:
@@ -189,7 +189,7 @@ class UOWTransaction(object):
         return False
 
     def is_deleted(self, state):
-        """return true if the given state is marked as deleted
+        """Return ``True`` if the given state is marked as deleted
         within this uowtransaction."""
 
         return state in self.states and self.states[state][0]
@@ -202,7 +202,7 @@ class UOWTransaction(object):
             return ret
 
     def remove_state_actions(self, state):
-        """remove pending actions for a state from the uowtransaction."""
+        """Remove pending actions for a state from the uowtransaction."""
 
         isdelete = self.states[state][0]
 
@@ -211,7 +211,7 @@ class UOWTransaction(object):
     def get_attribute_history(
         self, state, key, passive=attributes.PASSIVE_NO_INITIALIZE
     ):
-        """facade to attributes.get_state_history(), including
+        """Facade to attributes.get_state_history(), including
         caching of results."""
 
         hashkey = ("history", state, key)
@@ -421,10 +421,10 @@ class UOWTransaction(object):
                 rec.execute(self)
 
     def finalize_flush_changes(self):
-        """mark processed objects as clean / deleted after a successful
+        """Mark processed objects as clean / deleted after a successful
         flush().
 
-        this method is called within the flush() method after the
+        This method is called within the flush() method after the
         execute() method has succeeded and the transaction has been committed.
 
         """
diff --git a/lib/sqlalchemy/orm/util.py b/lib/sqlalchemy/orm/util.py
index f7a97bfe5..e04c54497 100644
--- a/lib/sqlalchemy/orm/util.py
+++ b/lib/sqlalchemy/orm/util.py
@@ -60,7 +60,8 @@ all_cascades = frozenset(
 
 
 class CascadeOptions(frozenset):
-    """Keeps track of the options sent to relationship().cascade"""
+    """Keeps track of the options sent to
+    :paramref:`.relationship.cascade`"""
 
     _add_w_all_cascades = all_cascades.difference(
         ["all", "none", "delete-orphan"]
@@ -263,7 +264,7 @@ def polymorphic_union(
 
 
 def identity_key(*args, **kwargs):
-    """Generate "identity key" tuples, as are used as keys in the
+    r"""Generate "identity key" tuples, as are used as keys in the
     :attr:`.Session.identity_map` dictionary.
 
     This function has several call styles:
@@ -890,8 +891,8 @@ def aliased(element, alias=None, name=None, flat=False, adapt_on_names=False):
     ORM-mapped in this case.
 
     :param element: element to be aliased.  Is normally a mapped class,
-     but for convenience can also be a :class:`_expression.FromClause` element
-     .
+     but for convenience can also be a :class:`_expression.FromClause`
+     element.
 
     :param alias: Optional selectable unit to map the element to.  This is
      usually used to link the object to a subquery, and should be an aliased