From 18db042ea74a0ff4e6f4bdecb66c9321a999c1a8 Mon Sep 17 00:00:00 2001 From: Federico Caselli Date: Tue, 21 Feb 2023 21:05:25 +0100 Subject: Create public QueryPropertyDescriptor type for query_property Exported the type returned by :meth:`_orm.scoped_session.query_property` using a new public type :class:`.orm.QueryPropertyDescriptor`. Also stated ``scoped_session()`` from ``sqlalchemy.orm`` in the documentation rather than from ``sqlalchemy.orm.scoping``. Fixes: #9338 Change-Id: I77da54891860095edcb1f0625ead99fee89bd76f --- lib/sqlalchemy/orm/__init__.py | 1 + lib/sqlalchemy/orm/scoping.py | 27 +++++++++++++++++++++------ 2 files changed, 22 insertions(+), 6 deletions(-) (limited to 'lib/sqlalchemy') diff --git a/lib/sqlalchemy/orm/__init__.py b/lib/sqlalchemy/orm/__init__.py index d54e1ccb9..69cd7f598 100644 --- a/lib/sqlalchemy/orm/__init__.py +++ b/lib/sqlalchemy/orm/__init__.py @@ -120,6 +120,7 @@ from .relationships import foreign as foreign from .relationships import Relationship as Relationship from .relationships import RelationshipProperty as RelationshipProperty from .relationships import remote as remote +from .scoping import QueryPropertyDescriptor as QueryPropertyDescriptor from .scoping import scoped_session as scoped_session from .session import close_all_sessions as close_all_sessions from .session import make_transient as make_transient diff --git a/lib/sqlalchemy/orm/scoping.py b/lib/sqlalchemy/orm/scoping.py index b46d26d0b..f5f894583 100644 --- a/lib/sqlalchemy/orm/scoping.py +++ b/lib/sqlalchemy/orm/scoping.py @@ -76,7 +76,14 @@ if TYPE_CHECKING: _T = TypeVar("_T", bound=Any) -class _QueryDescriptorType(Protocol): +class QueryPropertyDescriptor(Protocol): + """Describes the type applied to a class-level + :meth:`_orm.scoped_session.query_property` attribute. + + .. versionadded:: 2.0.5 + + """ + def __get__(self, instance: Any, owner: Type[_T]) -> Query[_T]: ... @@ -254,17 +261,25 @@ class scoped_session(Generic[_S]): def query_property( self, query_cls: Optional[Type[Query[_T]]] = None - ) -> _QueryDescriptorType: - """return a class property which produces a :class:`_query.Query` - object - against the class and the current :class:`.Session` when called. + ) -> QueryPropertyDescriptor: + """return a class property which produces a legacy + :class:`_query.Query` object against the class and the current + :class:`.Session` when called. + + .. legacy:: The :meth:`_orm.scoped_session.query_property` accessor + is specific to the legacy :class:`.Query` object and is not + considered to be part of :term:`2.0-style` ORM use. e.g.:: + from sqlalchemy.orm import QueryPropertyDescriptor + from sqlalchemy.orm import scoped_session + from sqlalchemy.orm import sessionmaker + Session = scoped_session(sessionmaker()) class MyClass: - query = Session.query_property() + query: QueryPropertyDescriptor = Session.query_property() # after mappers are defined result = MyClass.query.filter(MyClass.name=='foo').all() -- cgit v1.2.1