consider a function-layer in the ORM that returns "Any"

all ORM functions that are used in declarative are now
made separate from the classes they refer towards in all
cases and indicate the return type of Any so they can be
used inline with Mapped[_T] in declarative mappings
such that IDEs can deliver Mapped[] behavior without any
linter errors.

this will require changes in the mypy plugin as we
can no longer rely on simple things like "composite()" returning
CompositeProperty.

References: https://gerrit.sqlalchemy.org/c/sqlalchemy/sqlalchemy/+/3074

Fixes: #170

Author: zzzeek

sqlalchemy-stubs/orm/__init__.pyi

@@ -1,7 +1,15 @@
+from typing import AbstractSet
 from typing import Any
+from typing import Callable
+from typing import Literal
 from typing import Mapping
+from typing import MutableMapping
 from typing import Optional
+from typing import overload
+from typing import Sequence
 from typing import Tuple
+from typing import Type
+from typing import Union
 
 from . import exc as exc
 from . import mapper as mapperlib  # noqa
@@ -46,6 +54,7 @@ from .properties import ColumnProperty as ColumnProperty
 from .query import AliasOption as AliasOption
 from .query import FromStatement as FromStatement
 from .query import Query as Query
+from .relationships import _OrderByArgument
 from .relationships import foreign as foreign
 from .relationships import RelationshipProperty as RelationshipProperty
 from .relationships import remote as remote
@@ -73,27 +82,148 @@ from .util import polymorphic_union as polymorphic_union
 from .util import was_deleted as was_deleted
 from .util import with_parent as with_parent
 from .util import with_polymorphic as with_polymorphic
+from ..sql import schema
+from ..sql.schema import _ServerDefaultType
+from ..sql.schema import FetchedValue
+from ..sql.schema import SchemaEventTarget
 
 def create_session(bind: Optional[Any] = ..., **kwargs: Any) -> Session: ...
 
 with_loader_criteria = LoaderCriteriaOption
-relationship = RelationshipProperty
-
-def relation(*arg: Any, **kw: Any) -> RelationshipProperty[Any]: ...
-def dynamic_loader(argument: Any, **kw: Any) -> RelationshipProperty[Any]: ...
-
-column_property = ColumnProperty
-composite = CompositeProperty
 
 _BackrefResult = Tuple[str, Mapping[str, Any]]
 
+def relationship(
+    argument: Any,
+    secondary: Optional[Any] = ...,
+    primaryjoin: Optional[Any] = ...,
+    secondaryjoin: Optional[Any] = ...,
+    foreign_keys: Optional[Any] = ...,
+    uselist: Optional[bool] = ...,
+    order_by: _OrderByArgument = ...,
+    backref: Union[str, _BackrefResult] = ...,
+    back_populates: str = ...,
+    overlaps: Union[AbstractSet[str], str] = ...,
+    post_update: bool = ...,
+    cascade: Union[Literal[False], Sequence[str]] = ...,
+    viewonly: bool = ...,
+    lazy: str = ...,
+    collection_class: Optional[Union[Type[Any], Callable[[], Any]]] = ...,
+    passive_deletes: Union[bool, Literal["all"]] = ...,
+    passive_updates: bool = ...,
+    remote_side: Optional[Any] = ...,
+    enable_typechecks: bool = ...,  # NOTE: not documented
+    join_depth: Optional[int] = ...,
+    comparator_factory: Optional[Any] = ...,
+    single_parent: bool = ...,
+    innerjoin: Union[bool, str] = ...,
+    distinct_target_key: Optional[bool] = ...,
+    doc: Optional[str] = ...,
+    active_history: bool = ...,
+    cascade_backrefs: bool = ...,
+    load_on_pending: bool = ...,
+    bake_queries: bool = ...,
+    _local_remote_pairs: Optional[Any] = ...,
+    query_class: Optional[Any] = ...,
+    info: Optional[MutableMapping[Any, Any]] = ...,
+    omit_join: Optional[Literal[False]] = ...,
+    sync_backref: Optional[Any] = ...,
+) -> Any: ...
+def relation(*arg: Any, **kw: Any) -> Any: ...
+def dynamic_loader(argument: Any, **kw: Any) -> Any: ...
+def column_property(*arg: Any, **kw: Any) -> Any: ...
+def composite(*arg: Any, **kw: Any) -> Any: ...
+@overload
+def mapped_column(
+    __name: str,
+    *args: SchemaEventTarget,
+    autoincrement: Union[bool, Literal["auto", "ignore_fk"]] = ...,
+    default: Optional[Any] = ...,
+    doc: Optional[str] = ...,
+    key: Optional[str] = ...,
+    index: Optional[bool] = ...,
+    info: MutableMapping[Any, Any] = ...,
+    nullable: bool = ...,
+    onupdate: Optional[Any] = ...,
+    primary_key: bool = ...,
+    server_default: Optional[_ServerDefaultType[Any]] = ...,
+    server_onupdate: Optional[FetchedValue] = ...,
+    quote: Optional[bool] = ...,
+    unique: Optional[bool] = ...,
+    system: bool = ...,
+    comment: Optional[str] = ...,
+    **kwargs: Any,
+) -> Any: ...
+@overload
+def mapped_column(
+    *args: SchemaEventTarget,
+    autoincrement: Union[bool, Literal["auto", "ignore_fk"]] = ...,
+    default: Optional[Any] = ...,
+    doc: Optional[str] = ...,
+    key: Optional[str] = ...,
+    index: Optional[bool] = ...,
+    info: MutableMapping[Any, Any] = ...,
+    nullable: bool = ...,
+    onupdate: Optional[Any] = ...,
+    primary_key: bool = ...,
+    server_default: Optional[_ServerDefaultType[Any]] = ...,
+    server_onupdate: Optional[FetchedValue] = ...,
+    quote: Optional[bool] = ...,
+    unique: Optional[bool] = ...,
+    system: bool = ...,
+    comment: Optional[str] = ...,
+    **kwargs: Any,
+) -> Any: ...
+@overload
+def mapped_column(
+    __name: str,
+    __type: Union[schema._TE, Type[schema._TE]],
+    *args: SchemaEventTarget,
+    autoincrement: Union[bool, Literal["auto", "ignore_fk"]] = ...,
+    default: Optional[Any] = ...,
+    doc: Optional[str] = ...,
+    key: Optional[str] = ...,
+    index: Optional[bool] = ...,
+    info: MutableMapping[Any, Any] = ...,
+    nullable: bool = ...,
+    onupdate: Optional[Any] = ...,
+    primary_key: bool = ...,
+    server_default: Optional[_ServerDefaultType[schema._TE]] = ...,
+    server_onupdate: Optional[FetchedValue] = ...,
+    quote: Optional[bool] = ...,
+    unique: Optional[bool] = ...,
+    system: bool = ...,
+    comment: Optional[str] = ...,
+    **kwargs: Any,
+) -> Any: ...
+@overload
+def mapped_column(
+    __type: Union[schema._TE, Type[schema._TE]],
+    *args: SchemaEventTarget,
+    autoincrement: Union[bool, Literal["auto", "ignore_fk"]] = ...,
+    default: Optional[Any] = ...,
+    doc: Optional[str] = ...,
+    key: Optional[str] = ...,
+    index: Optional[bool] = ...,
+    info: MutableMapping[Any, Any] = ...,
+    nullable: bool = ...,
+    onupdate: Optional[Any] = ...,
+    primary_key: bool = ...,
+    server_default: Optional[_ServerDefaultType[schema._TE]] = ...,
+    server_onupdate: Optional[FetchedValue] = ...,
+    quote: Optional[bool] = ...,
+    unique: Optional[bool] = ...,
+    system: bool = ...,
+    comment: Optional[str] = ...,
+    **kwargs: Any,
+) -> Any: ...
 def backref(name: str, **kwargs: Any) -> _BackrefResult: ...
-def deferred(*columns: Any, **kw: Any) -> ColumnProperty: ...
-def query_expression(default_expr: Any = ...) -> ColumnProperty: ...
+def deferred(*columns: Any, **kw: Any) -> Any: ...
+def query_expression(default_expr: Any = ...) -> Any: ...
 
 mapper = Mapper
-synonym = SynonymProperty
 
+def synonym(*arg, **kw) -> Any: ...
 def clear_mappers() -> None: ...
 
 joinedload = strategy_options.joinedload._unbound_fn

sqlalchemy-stubs/sql/schema.pyi

@@ -56,6 +56,8 @@ _ID = TypeVar("_ID", bound=Identity)
 
 _ServerDefaultType = Union[FetchedValue, str, TextClause, ColumnElement[_T]]
 
+_T = TypeVar("_T", bound=type_api.TypeEngine)
+
 class SchemaItem(SchemaEventTarget, visitors.Visitable):
     __visit_name__: str = ...
     create_drop_stringify_dialect: str = ...