Why are select()'s scalar TypeVars constrained rather than bounded?

[cooperoptigrid]

First Check

• I added a very descriptive title here.
• I used the GitHub search to find a similar question and didn't find it.
• I searched the documentation, with the integrated search.
• I already searched in Google "How to X" and didn't find any information.
• I already read and followed all the tutorials in the docs and didn't find an answer.

Example Code

# ty: no-matching-overload on this line (astral-sh/ty#4892)
    statuses = session.exec(select(Hero.status)).all()
    # mypy, pyright: Sequence[str]; ty: Sequence[Unknown]
    # with a bound: Sequence[Status]
    reveal_type(statuses)
    # mypy, pyright: error, `str` has no attribute `name`
    # with a bound: no error
    print(statuses[0].name)  # ACTIVE

    # ty: no-matching-overload on this line (astral-sh/ty#4892)
    nicknames = session.exec(select(Hero.nickname)).all()
    # mypy, pyright: Sequence[str] | Sequence[None]; ty: Sequence[Unknown]
    # with a bound: Sequence[str | None]
    reveal_type(nicknames)
    print(nicknames)  # ['Deadpond', None]

Description

I'm migrating a SQLModel project from mypy to ty. After the switch, ty reported no-matching-overload on calls like session.exec(select(Hero.name)) that mypy accepts. That turned out to be a ty regression, which I reported in astral-sh/ty#4892.

While looking into it, I noticed that the _TScalar_* TypeVars that select() uses for single columns are constrained (TypeVar("_TScalar_0", Column, Sequence, Mapping, UUID, datetime, float, int, bool, bytes, str, None)). Out of curiosity, I tried changing them locally to a bound with the same types:

_TScalar_0 = TypeVar(
    "_TScalar_0",
    bound=Column | Sequence | Mapping | UUID | datetime | float | int | bool | bytes | str | None,
)

That avoids the ty problem. It also changes what mypy and pyright infer for some columns, and the results look more accurate to me. The example above prints ACTIVE and ['Deadpond', None] at runtime. With SQLModel 0.0.48 as it is:

	statuses	statuses[0].name	nicknames
mypy 1.19.1	Sequence[str]	error: "str" has no attribute "name"	Sequence[str] | Sequence[None]
pyright 1.1.414	Sequence[str]	error: Cannot access attribute "name" for class "str"	Sequence[str] | Sequence[None]
ty 0.0.96	Sequence[Unknown]	—	Sequence[Unknown]

With the bound, all three infer Sequence[Status] and Sequence[str | None] with no errors.

Of course the general advice is to use col(). select(col(Hero.status)) and select(col(Hero.nickname)) give those same accurate types on the current release, so this is less a report than a question: is there a reason these are constrained rather than bounded?

Operating System

Linux

Operating System Details

No response

Project Version

0.0.48

Python Version

3.14.9

Additional Context

No response

[CharlieJamesGwapo]

I can't speak to the original intent: the constrained form has been there since the first commit (fcff205, "Add SQLModel core code", Aug 2021) and I couldn't find a recorded reason. But I can add one more data point for the bound: with constraints, columns whose Python type isn't in the list are rejected outright, not just widened.

from datetime import date
from decimal import Decimal

class Hero(SQLModel, table=True):
    id: int | None = Field(default=None, primary_key=True)
    status: Status = Status.ACTIVE      # StrEnum
    born: date = date(2000, 1, 1)
    salary: Decimal = Decimal("1.5")

session.exec(select(Hero.status)).all()   # mypy/pyright: Sequence[str]   (enum collapses to the constraint)
session.exec(select(Hero.born)).all()     # mypy: No overload variant of "select" matches argument type "date"
session.exec(select(Hero.salary)).all()   # mypy: No overload variant of "select" matches argument type "Decimal"
session.exec(select(col(Hero.born))).all()  # Sequence[date]

On SQLModel 0.0.48 with mypy 2.4.1, both date and Decimal fail with call-overload (pyright: "No overloads for select match"), while all three queries run fine and return Status.ACTIVE, date(2000, 1, 1) and Decimal('1.5…'). date isn't in the list (only datetime, its subclass) and Decimal isn't a float, so neither matches a constraint. This is what the old PR #776 ("Add type of _TScalar", adding date/time to the list) was working around one type at a time; a bound fixes it for any subclass of the listed types, and arguably the list itself could be widened.

So the two behaviours you saw have the same cause. A constrained TypeVar must solve to exactly one of the listed types, so a subclass (Status → str) is widened to the constraint, and a type outside the list (date, Decimal) has nothing to solve to. A bound solves to the actual argument type. The only thing I can think of that the constraint gives you that a bound doesn't is that it rejects arbitrary non-column objects, but the bound keeps that, since it uses the same union.

Until something changes, col() is the workaround, as you said: select(col(Hero.born)) gives Sequence[date].