Protocol doesn't seem to agree with SQLAlchemy Mapped attributes

[MajorDallas]

My app has a database and a Swagger API, so I have two models for the same kind of thing:

# sqlalchemy model
class Host(DeclarativeMeta):
    hostname: Mapped[str]


# pydantic model
class GetHost(BaseModel):
    hostname: str

Elsewhere, I have a bit of code that wants to access that hostname attribute but doesn't care about anything else, making it a good candidate for a Protocol:

class HasHostname(Protocol):
    hostname: str


def process_hostname(obj: HasHostname): ...

And when I go to use it with the SQLAlchemy model, I get an error:

"Host" is incompatible with protocol "HasHostname"
      "hostname" is invariant because it is mutable
      "hostname" is an incompatible type
        "Mapped[str]" is not assignable to "str"

I'm pretty sure Pyright is technically correct: Mapped isn't a str, after all. Mypy doesn't seem to care, even with --strict.

Is there a way I can persuade Pyright to accept these as compatible, anyway? I mean, other than using cast at the call site. I tried changing the protocol to str | Mapped[str], but that gave the same error with extra steps; converting it to a property had no effect at all (and probably wouldn't work anyway, since properties and attributes aren't type-equivalent under Pyright)... I'm not sure what else I can try to make this pass type-checking short of refactoring the function to take the hostname value instead of fetching it from an attribute.

[Rich Chiodo (rchiodo)]

You're right that the diagnostic is technically accurate, but the reason it fires is more subtle than "Mapped isn't a str," and it explains why none of your workarounds helped.

What's actually happening

Mapped is a descriptor. When you access it on an instance, pyright correctly resolves __get__:

reveal_type(Host().hostname)  # str
reveal_type(Host.hostname)    # Mapped[str]

But during protocol matching, pyright does not apply the descriptor. It compares the member's declared type (Mapped[str]) against the protocol member, not the __get__-resolved type (str). Combined with the invariance rule for mutable protocol attributes, Mapped[str] has to equal str, and it doesn't.

This is also why switching to a property didn't help — the source side is still evaluated as Mapped[str], so a read-only @property protocol member returning str fails with the same message. It's a divergence from mypy, which honors the descriptor here.

A workaround that actually type-checks

Make the protocol member read-only (so it's covariant, not invariant) and widen its type to a common supertype of both str and Mapped[str]:

class HasHostname(Protocol):
    @property
    def hostname(self) -> str | Mapped[str]: ...   # read-only => covariant

Both your models now satisfy it:

process_hostname(Host())     # ok (SQLAlchemy, Mapped[str])
process_hostname(GetHost())  # ok (pydantic, str)

The trade-off is that inside process_hostname, obj.hostname is str | Mapped[str] (or object if you widen that far), so you'd narrow/cast there instead of at the call site. There's no protocol member type that both accepts Mapped[str] structurally and stays exactly str, precisely because pyright uses the declared type.

If you'd rather keep hostname: str and localize the cast, note that instance access already gives you a clean str (h = Host().hostname is str), so pulling the value into a local before passing it also sidesteps the descriptor issue.

If you think pyright should resolve the descriptor during protocol matching (as it does for direct access, and as mypy does), that'd be worth filing as a separate issue.

[MajorDallas]

Very helpful, thank you!

Follow-up question: shouldn't this also interfere with classes that use __slots__? Say we had these two models, as well:

@dataclass(slots=True, frozen=True)
class HostDC:
    hostname: str

class HostPOPO:
    __slots__ = ("hostname",)

    def __init__(self, hostname: str):
        self.hostname = hostname

With __slots__, every listed attribute gets replaced with descriptors. I assume Pyright won't have an issue with the dataclass, where the explicit annotation is right there. I also assume it will correctly infer str for the plain old Python object. However, I would also expect that Pyright is aware of __slots__ and knows that it will have to call a __get__ at some point.

Is that special-cased? Or does it not matter because the declared annotations are just str?

[Rich Chiodo (rchiodo)]

Good instinct, but __slots__ doesn't cause the same problem — and the reason is exactly the distinction that made Mapped special.

The key difference: what the declared type is.

With Mapped, you explicitly annotated hostname: Mapped[str]. The declared type is a descriptor class, and that's what pyright compares during protocol matching.

With __slots__, the slot descriptor is created implicitly at runtime to back an attribute whose declared type is just str. Pyright models __slots__ as a storage/allocation mechanism, not as a descriptor with a __get__ that changes the attribute's type. So the member type it sees is str — same as any normal attribute. There's no Mapped[str]-vs-str mismatch to begin with, so nothing to special-case.

Verified with your exact examples:

reveal_type(HostDC("x").hostname)    # str
reveal_type(HostPOPO("x").hostname)  # str

class HasHostname(Protocol):
    hostname: str

process(HostDC("x"))    # ok (non-frozen)
process(HostPOPO("x"))  # ok

Both satisfy the protocol.

One wrinkle with your frozen=True example — that does error, but for an unrelated reason:

"hostname" is not read-only in protocol
"hostname" is writable in protocol

A frozen=True dataclass makes hostname read-only, and your protocol declares a mutable (writable) hostname. A read-only attribute can't satisfy a writable protocol member. Drop frozen=True (or make the protocol member a read-only @property) and it passes. This has nothing to do with __slots__ or descriptors — it's the same read-only-vs-writable rule.

So to directly answer: it's not that pyright special-cases __slots__ to call __get__; it's that __slots__ never changes the declared attribute type the way an explicit Mapped[str] annotation does.

[MajorDallas]

Makes sense. Thanks again!