From: Federico Caselli Date: Tue, 21 Feb 2023 20:05:25 +0000 (+0100) Subject: Create public QueryPropertyDescriptor type for query_property X-Git-Tag: rel_2_0_5~24^2 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=18db042ea74a0ff4e6f4bdecb66c9321a999c1a8;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git 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 --- diff --git a/doc/build/changelog/unreleased_20/9338.rst b/doc/build/changelog/unreleased_20/9338.rst new file mode 100644 index 0000000000..426fa85ac5 --- /dev/null +++ b/doc/build/changelog/unreleased_20/9338.rst @@ -0,0 +1,7 @@ +.. change:: + :tags: typing, usecase + :tickets: 9338 + + Exported the type returned by + :meth:`_orm.scoped_session.query_property` using a new public type + :class:`.orm.QueryPropertyDescriptor`. diff --git a/doc/build/orm/contextual.rst b/doc/build/orm/contextual.rst index 1fc64c9659..3e03e93167 100644 --- a/doc/build/orm/contextual.rst +++ b/doc/build/orm/contextual.rst @@ -271,7 +271,7 @@ otherwise self-managed. Contextual Session API ---------------------- -.. autoclass:: sqlalchemy.orm.scoping.scoped_session +.. autoclass:: sqlalchemy.orm.scoped_session :members: :inherited-members: @@ -279,3 +279,5 @@ Contextual Session API :members: .. autoclass:: sqlalchemy.util.ThreadLocalRegistry + +.. autoclass:: sqlalchemy.orm.QueryPropertyDescriptor diff --git a/lib/sqlalchemy/orm/__init__.py b/lib/sqlalchemy/orm/__init__.py index d54e1ccb9c..69cd7f5985 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 b46d26d0bb..f5f894583b 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() diff --git a/test/ext/mypy/plain_files/sessionmakers.py b/test/ext/mypy/plain_files/sessionmakers.py index 2d02f2a3f4..2897606cfc 100644 --- a/test/ext/mypy/plain_files/sessionmakers.py +++ b/test/ext/mypy/plain_files/sessionmakers.py @@ -1,4 +1,6 @@ -"""test #7656""" +"""test sessionmaker, originally for #7656""" + +from typing import reveal_type from sqlalchemy import create_engine from sqlalchemy import Engine @@ -7,6 +9,7 @@ from sqlalchemy.ext.asyncio import async_sessionmaker from sqlalchemy.ext.asyncio import AsyncEngine from sqlalchemy.ext.asyncio import AsyncSession from sqlalchemy.ext.asyncio import create_async_engine +from sqlalchemy.orm import QueryPropertyDescriptor from sqlalchemy.orm import scoped_session from sqlalchemy.orm import Session from sqlalchemy.orm import sessionmaker @@ -110,3 +113,30 @@ def test_8837_async() -> None: # EXPECTED_TYPE: AsyncSession reveal_type(async_session) + + +# test #9338 +ss_9338 = scoped_session_factory(engine) + +# EXPECTED_TYPE: QueryPropertyDescriptor +reveal_type(ss_9338.query_property()) +qp: QueryPropertyDescriptor = ss_9338.query_property() + + +class Foo: + query = qp + + +# EXPECTED_TYPE: Query[Foo] +reveal_type(Foo.query) + +# EXPECTED_TYPE: list[Foo] +reveal_type(Foo.query.all()) + + +class Bar: + query: QueryPropertyDescriptor = ss_9338.query_property() + + +# EXPECTED_TYPE: Query[Bar] +reveal_type(Bar.query) diff --git a/test/ext/mypy/plugin_files/issue_9156.py b/test/ext/mypy/plugin_files/issue_9156.py index 46e5e95703..e67f64442a 100644 --- a/test/ext/mypy/plugin_files/issue_9156.py +++ b/test/ext/mypy/plugin_files/issue_9156.py @@ -1,4 +1,5 @@ -from typing import Any, Type +from typing import Any +from typing import Type from sqlalchemy.sql.elements import ColumnElement from sqlalchemy.sql.type_api import TypeEngine