How to annotate a user-defined collection in Python?

I've created a collection type:

from collections.abc import Sequence

class MyCollection(Sequence):
    pass

and I want to annotate object of my class like this:

obj: MyCollection[int] = MyCollection()

How to achieve this?

I wrote:

obj: MyCollection[int] = MyCollection()

But IntelliSense only specifies MyCollection not MyCollection[int].

You could use typing it provides runtime support for type hints, for user-defined generic collection, you can use typing.Generic and typing.TypeVar

Here is an example:

from typing import TypeVar, Generic
from collections.abc import Sequence

T = TypeVar('T')

class MyCollection(Sequence, Generic[T]):
    def __init__(self):
        self.data = []

    def __getitem__(self, index):
        return self.data[index]

    def __len__(self):
        return len(self.data)

    def add(self, item: T):
        self.data.append(item)

obj: MyCollection[int] = MyCollection()
obj.add(1)

To learn about user-defined generic types, read this section of PEP 484.

You apparently want to subclass the Sequence abstract base class. Note that collections.abc.Sequence is already generic. That means to retain genericity in a subclass, you simply need to pass a type variable to Sequence during inheritance.

You just need to take care to implement the overloaded signatures of __getitem__ properly because it should accept indices and slices and return either a sequence item or a sub-sequence respectively.

Example:

from __future__ import annotations
from collections.abc import Iterable, Sequence
from typing import TypeVar, overload

T = TypeVar("T")


class MyCollection(Sequence[T]):
    def __init__(self, data: Iterable[T]) -> None:
        self.items = tuple(data)

    @overload
    def __getitem__(self, index: int) -> T: ...

    @overload
    def __getitem__(self, index: slice) -> MyCollection[T]: ...

    def __getitem__(self, index: int | slice) -> T | MyCollection[T]:
        if isinstance(index, slice):
            return MyCollection(self.items[index])
        return self.items[index]

    def __len__(self) -> int:
        return len(self.items)

Try that with mypy (playground):

s = MyCollection([10, 20, 30])
reveal_type(s)
reveal_type(s[0])
reveal_type(s[0:])
reveal_type(iter(s))

The output will be the following:

note: Revealed type is "MyCollection[builtins.int]"
note: Revealed type is "builtins.int"
note: Revealed type is "MyCollection[builtins.int]"
note: Revealed type is "typing.Iterator[builtins.int]"

Notice how the types are correctly inferred without the need for an explicit annotation during usage. Even the iterator item type is correctly inferred because Sequence[T] is set up to return Iterator[T] from its __iter__ method.

This means, when s is e.g. of type MyCollection[int] and you do for item in s: ... and the static type checker will infer item to be of type int.