Аннотация Self модуля typing в Python

Аннотация методов, возвращаемых экземпляр класса

Аннотация typing.Self (добавлена в Python 3.11.) предоставляет простой и интуитивно понятный способ аннотировать методы, которые возвращают экземпляр своего класса. Это похоже на подход на основе typing.TypeVar, но более лаконичный и простой для понимания.

Общие варианты использования включают альтернативные конструкторы, предоставляемые как методы класса, и методы __enter__(), которые возвращают self:

from typing import Self

class MyLock:
    def __enter__(self) -> Self:
        self.lock()
        return self

    ...

class MyInt:
    @classmethod
    def fromhex(cls, s: str) -> Self:
        return cls(int(s, 16))

    ...

Аннотацию typing.Self также можно использовать для аннотирования параметров метода или атрибутов того же типа, что и окружающий их класс.

Новое в версии 3.11.

Описание typing.Self.

Аннотация typing.Self - это специальный тип для представления текущего закрытого класса.

from typing import Self

class Foo:
   def return_self(self) -> Self:
      ...
      return self

Эта аннотация семантически эквивалентна следующей, хотя и в более краткой форме:

from typing import TypeVar

Self = TypeVar("Self", bound="Foo")

class Foo:
   def return_self(self: Self) -> Self:
      ...
      return self

В общем, если что-то в коде следует шаблону:

class Foo:
   def return_self(self) -> "Foo":
      ...
      return self

Необходимо использовать typing.Self, так как вызовы SubclassOfFoo.return_self будут иметь Foo в качестве возвращаемого типа, а не SubclassOfFoo.

Другие распространенные варианты использования:

• Аннотирование метода класса, которые используются в качестве альтернативных конструкторов и возвращают экземпляры параметра cls.
• Аннотирование метода __enter__(), возвращающего self.