modernize hybrids and apply typing

Improved the typing support for the :ref:`hybrids_toplevel`
extension, updated all documentation to use ORM Annotated Declarative
mappings, and added a new modifier called :attr:`.hybrid_property.inplace`.
This modifier provides a way to alter the state of a :class:`.hybrid_property`
**in place**, which is essentially what very early versions of hybrids
did, before SQLAlchemy version 1.2.0 :ticket:`3912` changed this to
remove in-place mutation.  This in-place mutation is now restored on an
**opt-in** basis to allow a single hybrid to have multiple methods
set up, without the need to name all the methods the same and without the
need to carefully "chain" differently-named methods in order to maintain
the composition.  Typing tools such as Mypy and Pyright do not allow
same-named methods on a class, so with this change a succinct method
of setting up hybrids with typing support is restored.

Change-Id: Iea88025f023428f9f006846d09fbb4be391f5ebb
References: #9321

1 files changed, 4 insertions, 2 deletions

diff --git a/lib/sqlalchemy/sql/_typing.py b/lib/sqlalchemy/sql/_typing.py
index e1190f7dd..ab124103f 100644
--- a/lib/sqlalchemy/sql/_typing.py
+++ b/lib/sqlalchemy/sql/_typing.py
@@ -40,7 +40,6 @@ if TYPE_CHECKING:
     from .dml import UpdateBase
     from .dml import ValuesBase
     from .elements import ClauseElement
-    from .elements import ColumnClause
     from .elements import ColumnElement
     from .elements import KeyedColumnElement
     from .elements import quoted_name
@@ -224,7 +223,10 @@ _SelectStatementForCompoundArgument = Union[
 """SELECT statement acceptable by ``union()`` and other SQL set operations"""
 
 _DMLColumnArgument = Union[
-    str, "ColumnClause[Any]", _HasClauseElement, roles.DMLColumnRole
+    str,
+    _HasClauseElement,
+    roles.DMLColumnRole,
+    "SQLCoreOperations",
 ]
 """A DML column expression.  This is a "key" inside of insert().values(),
 update().values(), and related.