InstrumentedAttribute should also be covariant on its input type

[ejlangev]

Ensure stubs packages are not installed

• No sqlalchemy stub packages is installed (both sqlalchemy-stubs and sqlalchemy2-stubs are not compatible with v2)

Verify if the api is typed

• The api is not in a module listed in #6810 so it should pass type checking

Describe the typing issue

InstrumentedAttribute is defined as

class InstrumentedAttribute(QueryableAttribute[_T):
    ...

In #10289, many of the types related to Mapped were made to be covariant which is helpful for user facing types. In my case I want to define a function that operates on relationship fields of my models generically. Roughly this:

_BaseModelT = TypeVar("_BaseModelT", bound=BaseModel)

def my_relationship_function(relationships: list[InstrumentedAttribute[_BaseModelT | Optional[_BaseModelT] | Sequence[_BaseModelT]]]) -> int:
    return len(relationships)

But I can't do that because the TypeVar passed into the InstrumentedAttribute class is not covariant. Allowing this I think should be as simple as changing class InstrumentedAttribute(QueryableAttribute[_T]): into class InstrumentedAttribute(QueryableAttribute[_T_co]):

To Reproduce

from typing import Optional, Sequence, TypeVar
from sqlalchemy.orm import DeclarativeBase, InstrumentedAttribute, Mapped, relationship

class BaseModel(DeclarativeBase):
    pass

class MyParent(BaseModel):
    __tablename__ = "my_parents"
    id: Mapped[int]
    name: Mapped[str]

    children: Mapped[Sequence["MyChild"]] = relationship(back_populates="parent")

class MyChild(BaseModel):
    __tablename__ = "my_children"

    id: Mapped[int]
    last_name: Mapped[str]
    parent_id: Mapped[int]

    parent: Mapped["MyParent"]  = relationship(back_populates="children")

_BaseModelT = TypeVar("_BaseModelT", bound=BaseModel)

def my_relationship_function(relationships: list[InstrumentedAttribute[_BaseModelT | Optional[_BaseModelT] | Sequence[_BaseModelT]]]) -> int:
    return len(relationships)

# This is a type error but should not be
my_relationship_function([MyParent.children])
# This is also a type error and should be but is an error
# for the wrong reasons
my_relationship_function([MyParent.name])

Error

Argument of type "list[InstrumentedAttribute[Sequence[MyChild]]]" cannot be assigned to parameter "relationships" of type "list[InstrumentedAttribute[_BaseModelT@my_relationship_function | Sequence[_BaseModelT@my_relationship_function] | None]]" in function "my_relationship_function"
  "InstrumentedAttribute[Sequence[MyChild]]" is incompatible with "InstrumentedAttribute[_BaseModelT@my_relationship_function | Sequence[_BaseModelT@my_relationship_function] | None]"
    Type parameter "_T@InstrumentedAttribute" is invariant, but "Sequence[MyChild]" is not the same as "_BaseModelT@my_relationship_function | Sequence[_BaseModelT@my_relationship_function] | None

Versions

• OS: MacOS
• Python: 3.11.6
• SQLAlchemy: 2.0.28
• Type checker (eg: mypy 0.991, pyright 1.1.290, etc): pyright 1.1.345

Additional context

The type checker is correct here, the type definitions are (I think) unnecessarily limiting.

[zzzeek]

feel free to send a PR, including a test as you see in the change you refer to. I'd put it in the same mapped_covariant file for succinctness

[ejlangev]

feel free to send a PR, including a test as you see in the change you refer to.

Will do!

[ejlangev]

Filed: #11113