pylance complains about return type using Self in a class method

[hardhu]

Consider this code:

from typing import Self


class Book:
    def __init__(self, title: str, pages: int) -> None:
        self.title = title
        self.pages = pages

    def __add__(self, other: Self) -> Self:
        combined_title = self.title + " & " + other.title
        combined_pages = self.pages + other.pages
        return Book(combined_title, combined_pages)

def main() -> None:
    book1: Book = Book("Python Programming", 300)
    book2: Book = Book("Java Programming", 400)
    combined_book: Book = book1 + book2

    print(combined_book.title)
    print(combined_book.pages)

if __name__ == "__main__":
    main()

I get pylance underlying in red the last line of the code of the add method, and when I move the mouse over it, I get the following message:
'Type "Book" is not assignable to return type "Self@Book"'

However, if I try to run the code, I encounter no errors. Also, if I open the same code with PyCharm,
I get no errors or warnings about the cited line.
Can anybody explain me why is this happening with pylance?

[erictraut]

Pyright (the type checker that underlies pylance) is working correctly here and in conformance with the Python typing spec. If you'd like to read more about the Self type and how the typing spec defines it, refer to this link.

When you use Self in a type annotation, it represents an implicit type variable scoped to the class in which it is contained and with an upper bound of that class. It is meant to be used in cases where the class may be subclassed, and it's a stand-in for whatever subclass is used for a given instance. For example, if you created a subclass of Book called Novel, the Self type variable would concretely be of type Novel if you were to instantiate a Novel object.

Note that your __add__ method violates this contract because it always returns a Book instance. If you were to instantiate a Novel object and call __add__, it would still return a Book object even though the return type of __add__ indicates that it should return a Novel instance in this case.

You can fix your code in one of two ways here:

1. Change the return type of __add__ to Book. (You will need to add quotes around the annotation because it is a forward reference.)

    def __add__(self, other: Self) -> "Book":

2. Change __add__ to return a value that is instantiated from the self parameter, like this:

    return type(self)(combined_title, combined_pages)

or

    return self.__class__(combined_title, combined_pages)