Type Guide either in the Documentation or in a readme file.

[MrDiver]

Description of proposed feature

There should be a clear type guide for which types to prefer in manim. There are a lot of ways to type things for example Optional[int] and int | None are the same thing when considering a linter like mypy, but they convey a different story when reading. For parameters if something has the type Optional it's very clear that this parameter can be left out safely and the rest is handled by the function itself.
This also reflects itself inside the function when reading the typehints, where the error messages state that the type is Optional and thus things like x.something don't work. This is also the case with int | None (it translates to Union[int, None] but it suggests that this variable can be in general a None value and also might just be changed back to one during the lifetime of the Object.

That's why i think we need to discuss a clear typeguide for manim and also have some kind of suggestions and help regarding typing.

I also would suggest the addition of a type module for Custom types needed in the future like the Color type which currently is str | Color, but this might be an addition for another day. But could also be discussed here if we need some standard types.

V1	V2	We use!
Optional[T]	T | None	V2
ndarray	NDArray[dtype]	V2
List[T]	list[T]	V2
Type[cls]	type[cls]	V2
Union[T,K]	T | K	V2

New Types in question

• TimeBasedUpdater = Callable[["Mobject", float], None]

• NonTimeUpdater = Callable[["Mobject"], None]

• Updater = Union[TimeBasedUpdater, NonTimeUpdater]

• ManimColor = Union[str, Color]

• kwargs: dict[str, Any]

• resolution: Tuple[int, int]

Types that return the class itself should return Self from the typing_extensions Module
This resolves conflicts with subclassing later on because the types of the subclass will automatically be inserted when overwriting which resolves the problem of conflicting return types

Use TYPE_CHECKING from the typing module to reduce import overhead for manim.

from typing import TYPE_CHECKING
if TYPE_CHECKING:
    import types here

Related to

• Add typings #52
• Update documentation on typings #2501
• Fix Typing #3086 -> Already uses Adding :class: ManimColor to manim and converting all types #3020
• Adding :class: ManimColor to manim and converting all types #3020 -> Adds ManimColor as class and ParsableManimColor as TypeAlias

[behackl]

It would be very nice to have a dedicated manim.typing module where we can (consistently) write more complicated types and then just use them in the rest of the library.

In terms of the semantics between Optional[bla] vs. bla | None: do you have any references for how other projects handle this? Personally, I don't have a strong opinion on caring about semantics between the two variants.

[Viicos]

In terms of the semantics between Optional[bla] vs. bla | None: do you have any references for how other projects handle this? Personally, I don't have a strong opinion on caring about semantics between the two variants.

Union types using the | syntax was added python 3.10, builtins supporting subscripting was added in python 3.9. They can still be used in older python versions using the annotations future import, the only downside is we can't use annotations at runtime without performing postponed evaluation (I don't think this is an issue for manim).

I've seen both solutions being used in several libraries, I think we can go for the "V2" syntax as it is less verbose.