dhcpkit.typing.py352_typing module

class dhcpkit.typing.py352_typing.Any[source]

Bases: dhcpkit.typing.py352_typing.Final

Special type indicating an unconstrained type.

  • Any object is an instance of Any.
  • Any class is a subclass of Any.
  • As a special case, Any and object are subclasses of each other.
class dhcpkit.typing.py352_typing.Callable[source]

Bases: dhcpkit.typing.py352_typing.Final

Callable type; Callable[[int], str] is a function of (int) -> str.

The subscription syntax must always be used with exactly two values: the argument list and the return type. The argument list must be a list of types; the return type must be a single type.

There is no syntax to indicate optional or keyword arguments, such function types are rarely used as callback types.

class dhcpkit.typing.py352_typing.Generic[source]

Bases: object

Abstract base class for generic types.

A generic type is typically declared by inheriting from an instantiation of this class with one or more type variables. For example, a generic mapping type might be defined as:

class Mapping(Generic[KT, VT]):
    def __getitem__(self, key: KT) -> VT:
    # Etc.

This class can then be used as follows:

def lookup_name(mapping: Mapping[KT, VT], key: KT, default: VT) -> VT:
        return mapping[key]
    except KeyError:
        return default
class dhcpkit.typing.py352_typing.Optional[source]

Bases: dhcpkit.typing.py352_typing.Final

Optional type.

Optional[X] is equivalent to Union[X, type(None)].

class dhcpkit.typing.py352_typing.Tuple[source]

Bases: dhcpkit.typing.py352_typing.Final

Tuple type; Tuple[X, Y] is the cross-product type of X and Y.

Example: Tuple[T1, T2] is a tuple of two elements corresponding to type variables T1 and T2. Tuple[int, float, str] is a tuple of an int, a float and a string.

To specify a variable-length tuple of homogeneous type, use Sequence[T].

class dhcpkit.typing.py352_typing.Type[source]

Bases: type, dhcpkit.typing.py352_typing.Generic

A special construct usable to annotate class objects.

For example, suppose we have the following classes:

class User: ...  # Abstract base for User classes
class BasicUser(User): ...
class ProUser(User): ...
class TeamUser(User): ...

And a function that takes a class argument that’s a subclass of User and returns an instance of the corresponding class:

U = TypeVar('U', bound=User)
def new_user(user_class: Type[U]) -> U:
    user = user_class()
    # (Here we could write the user object to a database)
    return user

joe = new_user(BasicUser)

At this point the type checker knows that joe has type BasicUser.

class dhcpkit.typing.py352_typing.TypeVar(*args, **kwds)[source]

Bases: dhcpkit.typing.py352_typing.TypingMeta

Type variable.


T = TypeVar('T')  # Can be anything
A = TypeVar('A', str, bytes)  # Must be str or bytes

Type variables exist primarily for the benefit of static type checkers. They serve as the parameters for generic types as well as for generic function definitions. See class Generic for more information on generic types. Generic functions work as follows:

def repeat(x: T, n: int) -> Sequence[T]:
‘’‘Return a list containing n references to x.’‘’ return [x]*n
def longest(x: A, y: A) -> A:
‘’‘Return the longest of two strings.’‘’ return x if len(x) >= len(y) else y

The latter example’s signature is essentially the overloading of (str, str) -> str and (bytes, bytes) -> bytes. Also note that if the arguments are instances of some subclass of str, the return type is still plain str.

At runtime, isinstance(x, T) will raise TypeError. However, issubclass(C, T) is true for any class C, and issubclass(str, A) and issubclass(bytes, A) are true, and issubclass(int, A) is false. (TODO: Why is this needed? This may change. See #136.)

Type variables may be marked covariant or contravariant by passing covariant=True or contravariant=True. See PEP 484 for more details. By default type variables are invariant.

Type variables can be introspected. e.g.:

T.__name__ == ‘T’ T.__constraints__ == () T.__covariant__ == False T.__contravariant__ = False A.__constraints__ == (str, bytes)
class dhcpkit.typing.py352_typing.Union[source]

Bases: dhcpkit.typing.py352_typing.Final

Union type; Union[X, Y] means either X or Y.

To define a union, use e.g. Union[int, str]. Details:

  • The arguments must be types and there must be at least one.

  • None as an argument is a special case and is replaced by type(None).

  • Unions of unions are flattened, e.g.:

    Union[Union[int, str], float] == Union[int, str, float]
  • Unions of a single argument vanish, e.g.:

    Union[int] == int  # The constructor actually returns int
  • Redundant arguments are skipped, e.g.:

    Union[int, str, int] == Union[int, str]
  • When comparing unions, the argument order is ignored, e.g.:

    Union[int, str] == Union[str, int]
  • When two arguments have a subclass relationship, the least derived argument is kept, e.g.:

    class Employee: pass
    class Manager(Employee): pass
    Union[int, Employee, Manager] == Union[int, Employee]
    Union[Manager, int, Employee] == Union[int, Employee]
    Union[Employee, Manager] == Employee
  • Corollary: if Any is present it is the sole survivor, e.g.:

    Union[int, Any] == Any
  • Similar for object:

    Union[int, object] == object
  • To cut a tie: Union[object, Any] == Union[Any, object] == Any.

  • You cannot subclass or instantiate a union.

  • You cannot write Union[X][Y] (what would it mean?).

  • You can use Optional[X] as a shorthand for Union[X, None].

class dhcpkit.typing.py352_typing.AbstractSet[source]

Bases: collections.abc.Sized, dhcpkit.typing.py352_typing.Iterable, dhcpkit.typing.py352_typing.Container

class dhcpkit.typing.py352_typing.Awaitable[source]

Bases: dhcpkit.typing.py352_typing.Generic

class dhcpkit.typing.py352_typing.AsyncIterator[source]

Bases: dhcpkit.typing.py352_typing.AsyncIterable

class dhcpkit.typing.py352_typing.AsyncIterable[source]

Bases: dhcpkit.typing.py352_typing.Generic

class dhcpkit.typing.py352_typing.ByteString[source]

Bases: dhcpkit.typing.py352_typing.Sequence

class dhcpkit.typing.py352_typing.Container[source]

Bases: dhcpkit.typing.py352_typing.Generic

class dhcpkit.typing.py352_typing.Hashable

Bases: object

class dhcpkit.typing.py352_typing.ItemsView[source]

Bases: dhcpkit.typing.py352_typing.MappingView, dhcpkit.typing.py352_typing.AbstractSet, dhcpkit.typing.py352_typing.Generic

class dhcpkit.typing.py352_typing.Iterable[source]

Bases: dhcpkit.typing.py352_typing.Generic

class dhcpkit.typing.py352_typing.Iterator[source]

Bases: dhcpkit.typing.py352_typing.Iterable

class dhcpkit.typing.py352_typing.KeysView[source]

Bases: dhcpkit.typing.py352_typing.MappingView, dhcpkit.typing.py352_typing.AbstractSet

class dhcpkit.typing.py352_typing.Mapping[source]

Bases: collections.abc.Sized, dhcpkit.typing.py352_typing.Iterable, dhcpkit.typing.py352_typing.Container, dhcpkit.typing.py352_typing.Generic

class dhcpkit.typing.py352_typing.MappingView[source]

Bases: collections.abc.Sized, dhcpkit.typing.py352_typing.Iterable

class dhcpkit.typing.py352_typing.MutableMapping[source]

Bases: dhcpkit.typing.py352_typing.Mapping

class dhcpkit.typing.py352_typing.MutableSequence[source]

Bases: dhcpkit.typing.py352_typing.Sequence

class dhcpkit.typing.py352_typing.MutableSet[source]

Bases: dhcpkit.typing.py352_typing.AbstractSet

class dhcpkit.typing.py352_typing.Sequence[source]

Bases: collections.abc.Sized, dhcpkit.typing.py352_typing.Iterable, dhcpkit.typing.py352_typing.Container

class dhcpkit.typing.py352_typing.Sized

Bases: object

class dhcpkit.typing.py352_typing.ValuesView[source]

Bases: dhcpkit.typing.py352_typing.MappingView

class dhcpkit.typing.py352_typing.Reversible[source]

Bases: dhcpkit.typing.py352_typing._Protocol

class dhcpkit.typing.py352_typing.SupportsAbs[source]

Bases: dhcpkit.typing.py352_typing._Protocol

class dhcpkit.typing.py352_typing.SupportsFloat[source]

Bases: dhcpkit.typing.py352_typing._Protocol

class dhcpkit.typing.py352_typing.SupportsInt[source]

Bases: dhcpkit.typing.py352_typing._Protocol

class dhcpkit.typing.py352_typing.SupportsRound[source]

Bases: dhcpkit.typing.py352_typing._Protocol

class dhcpkit.typing.py352_typing.Dict[source]

Bases: dict, dhcpkit.typing.py352_typing.MutableMapping

class dhcpkit.typing.py352_typing.DefaultDict[source]

Bases: collections.defaultdict, dhcpkit.typing.py352_typing.MutableMapping

class dhcpkit.typing.py352_typing.List[source]

Bases: list, dhcpkit.typing.py352_typing.MutableSequence

class dhcpkit.typing.py352_typing.Set[source]

Bases: set, dhcpkit.typing.py352_typing.MutableSet

dhcpkit.typing.py352_typing.NamedTuple(typename, fields)[source]

Typed version of namedtuple.


Employee = typing.NamedTuple('Employee', [('name', str), 'id', int)])

This is equivalent to:

Employee = collections.namedtuple('Employee', ['name', 'id'])

The resulting class has one extra attribute: _field_types, giving a dict mapping field names to types. (The field names are in the _fields attribute, which is part of the namedtuple API.)

class dhcpkit.typing.py352_typing.Generator[source]

Bases: dhcpkit.typing.py352_typing.Iterator, dhcpkit.typing.py352_typing.Generic

class dhcpkit.typing.py352_typing.AnyStr

Bases: dhcpkit.typing.py352_typing.Final

dhcpkit.typing.py352_typing.cast(typ, val)[source]

Cast a value to a type.

This returns the value unchanged. To the type checker this signals that the return value has the designated type, but at runtime we intentionally don’t check anything (we want this to be as fast as possible).

dhcpkit.typing.py352_typing.get_type_hints(obj, globalns=None, localns=None)[source]

Return type hints for a function or method object.

This is often the same as obj.__annotations__, but it handles forward references encoded as string literals, and if necessary adds Optional[t] if a default value equal to None is set.

BEWARE – the behavior of globalns and localns is counterintuitive (unless you are familiar with how eval() and exec() work). The search order is locals first, then globals.

  • If no dict arguments are passed, an attempt is made to use the globals from obj, and these are also used as the locals. If the object does not appear to have globals, an exception is raised.
  • If one dict argument is passed, it is used for both globals and locals.
  • If two dict arguments are passed, they specify globals and locals, respectively.
dhcpkit.typing.py352_typing.NewType(name, tp)[source]

NewType creates simple unique types with almost zero runtime overhead. NewType(name, tp) is considered a subtype of tp by static type checkers. At runtime, NewType(name, tp) returns a dummy function that simply returns its argument. Usage:

UserId = NewType('UserId', int)

def name_by_id(user_id: UserId) -> str:

UserId('user')          # Fails type check

name_by_id(42)          # Fails type check
name_by_id(UserId(42))  # OK

num = UserId(5) + 1     # type: int

Decorator to indicate that annotations are not type hints.

The argument must be a class or function; if it is a class, it applies recursively to all methods defined in that class (but not to methods defined in its superclasses or subclasses).

This mutates the function(s) in place.


Decorator to give another decorator the @no_type_check effect.

This wraps the decorator with something that wraps the decorated function in @no_type_check.


Decorator for overloaded functions/methods.

In a stub file, place two or more stub definitions for the same function in a row, each decorated with @overload. For example:

def utf8(value: None) -> None: ...
def utf8(value: bytes) -> bytes: ...
def utf8(value: str) -> bytes: ...

In a non-stub file (i.e. a regular .py file), do the same but follow it with an implementation. The implementation should not be decorated with @overload. For example:

def utf8(value: None) -> None: ...
def utf8(value: bytes) -> bytes: ...
def utf8(value: str) -> bytes: ...

def utf8(value):
    # implementation goes here

alias of builtins.str