python / python/mypy

Inconsistent Handling of Self in ClassVar Annotations

Open
#18,776 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

bug topic-self-types
Dominant language
Python
Stars
20.6k
Forks
3.3k
PR merge metrics
PR metrics pending

Description

Bug Report
When using Self within a ClassVar, mypy raises an arg-type error. This behavior seems inconsistent with the intended use of Self and ClassVar.​

To Reproduce

MyPy playground: https://mypy-play.net/?mypy=latest&python=3.12&gist=dfe06f06e69d157317a667311aa75952

from typing import TypeVar, Generic, ClassVar, Self

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

class BaseModel:
    _meta: "ClassVar[Meta[Self]]"

    class Meta(Generic[T]):
        """Metadata class for BaseModel."""
        def __init__(self, model: type[T]) -> None:
            self.model = model

    @classmethod
    def __init_subclass__(cls) -> None:
        # The following line triggers mypy error "arg-type"
        # bug.py: note: In member "__init_subclass__" of class "BaseModel":
	# bug.py:21:30: error: Argument 1 to "Meta" has incompatible type "type[BaseModel]"; expected "type[Self]"  [arg-type]
        cls._meta = cls.Meta(cls)

# outputs  -->  Revealed type is "bug.BaseModel.Meta[bug.BaseModel]"
reveal_type(BaseModel._meta)

Expected Behavior

The code should type-check without errors, as Self within the ClassVar should correspond to the subclass type, making cls.Meta(cls) a valid instantiation.​

Actual Behavior

mypy raises an arg-type error

bug.py: note: In member "__init_subclass__" of class "BaseModel":
bug.py:21:30: error: Argument 1 to "Meta" has incompatible type "type[BaseModel]"; expected "type[Self]"  [arg-type]

Your Environment:

mypy version used: 1.15.0
Python version used: 3.12.8

Additional Context:

Removing ClassVar, or changing Self to BaseModel both eliminate the mypy error.

This issue may be related to or a duplicate of Issue #17395, where Self types in ClassVar annotations lose specificity through TypeVar. In that case, Self appears to decay to the TypeVar bound instead of retaining the specific subclass type.​ I'm not certain if these are the same issue.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the MyPy playground reproducer using mypy 1.15.0 and Python 3.12.8, then compare the behavior with issue #17395. Trace how Self is handled inside the ClassVar annotation and the init_subclass call. Done means the example type-checks without the arg-type error and has regression coverage.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
devtools
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.