implicit typing imports¶

names from the typing standard library are implicitly available in .by source. referencing one inserts a matching from typing import ... in the transpiled output without an explicit import:

a: Sequence[int]

transpiles to:

from typing import Sequence
a: Sequence[int]

multiple references collapse into a single sorted import line:

def f(x: Optional[int], y: Mapping[str, int]) -> Iterable[int]: ...

from typing import Iterable, Mapping, Optional
def f(x: Optional[int], y: Mapping[str, int]) -> Iterable[int]: ...

which names¶

the implicit set covers typing members whose role is to describe a type or structural protocol. it includes the ABCs (Sequence, Mapping, Iterable, Iterator, MutableMapping, MutableSequence, …), generic helpers (Optional, Union, Type, Annotated), narrowing (TypeGuard), version-specific names (Self, LiteralString, Never, Required, NotRequired, ReadOnly), and the Supports* / AsyncContext* family

names whose role is covered by dedicated basedpython syntax are not in the implicit set — referencing them does not auto-import:

• Callable — use callable arrow syntax
• Final, ClassVar, NewType, final, override — use modifiers
• Literal — see literal types
• Protocol, Generic — use protocol class / generic class syntax
• TypeVar, ParamSpec, TypeVarTuple — use generic syntax
• Unpack — use unpack syntax
• NamedTuple — see anonymous named tuples
• TypedDict — see typed dict literals
• TypeIs — see type narrowing predicates
• TypeAlias — use the type X = … statement

runtime helpers (cast, get_type_hints, get_args, get_origin, overload, assert_type, reveal_type, …) are also excluded — they must be imported explicitly

interaction with existing imports¶

if the name is already bound at module scope (from typing import Sequence, from collections.abc import Sequence, or a user-level Sequence = …), no implicit import is emitted. existing bindings win

interaction with typing_extensions¶

implicit names that are too new for the target python (Self, Never, LiteralString, Required, NotRequired, ReadOnly, …) come from typing_extensions automatically. nothing to configure in .by source