beartype 0.1.1

Builtin Types

Builtin types like dict, int, list, set, and str are trivially type-checked by annotating parameters and return values with those types as is.

Let’s declare a simple beartyped function accepting a string and a dictionary and returning a tuple:

from beartype import beartype

@beartype
def law_of_the_jungle(wolf: str, pack: dict) -> tuple:
    return (wolf, pack[wolf]) if wolf in pack else None

Let’s call that function with good types:

>>> law_of_the_jungle(wolf='Akela', pack={'Akela': 'alone', 'Raksha': 'protection'})
('Akela', 'alone')

Good function. Let’s call it again with bad types:

>>> law_of_the_jungle(wolf='Akela', pack=['Akela', 'Raksha'])
Traceback (most recent call last):
  File "<ipython-input-10-7763b15e5591>", line 1, in <module>
    law_of_the_jungle(wolf='Akela', pack=['Akela', 'Raksha'])
  File "<string>", line 22, in __law_of_the_jungle_beartyped__
beartype.roar.BeartypeCallTypeParamException: @beartyped law_of_the_jungle() parameter pack=['Akela', 'Raksha'] not a <class 'dict'>.

The beartype.roar submodule publishes exceptions raised at both decoration time by @beartype and at runtime by wrappers generated by @beartype. In this case, a runtime type exception describing the improperly typed pack parameter is raised.

Good function! Let’s call it again with good types exposing a critical issue in this function’s implementation and/or return type annotation:

>>> law_of_the_jungle(wolf='Leela', pack={'Akela': 'alone', 'Raksha': 'protection'})
Traceback (most recent call last):
  File "<ipython-input-10-7763b15e5591>", line 1, in <module>
    law_of_the_jungle(wolf='Leela', pack={'Akela': 'alone', 'Raksha': 'protection'})
  File "<string>", line 28, in __law_of_the_jungle_beartyped__
beartype.roar.BeartypeCallTypeReturnException: @beartyped law_of_the_jungle() return value None not a <class 'tuple'>.

Bad function. Let’s conveniently resolve this by permitting this function to return either a tuple or None as detailed below:

>>> from beartype.cave import NoneType
>>> @beartype
... def law_of_the_jungle(wolf: str, pack: dict) -> (tuple, NoneType):
...     return (wolf, pack[wolf]) if wolf in pack else None
>>> law_of_the_jungle(wolf='Leela', pack={'Akela': 'alone', 'Raksha': 'protection'})
None

The beartype.cave submodule publishes generic types suitable for use with the @beartype decorator and anywhere else you might need them. In this case, the type of the None singleton is imported from this submodule and listed in addition to tuple as an allowed return type from this function.

Note that usage of the beartype.cave submodule is entirely optional (but more efficient and convenient than most alternatives). In this case, the type of the None singleton can also be accessed directly as type(None) and listed in place of NoneType above: e.g.,

>>> @beartype
... def law_of_the_jungle(wolf: str, pack: dict) -> (tuple, type(None)):
...     return (wolf, pack[wolf]) if wolf in pack else None
>>> law_of_the_jungle(wolf='Leela', pack={'Akela': 'alone', 'Raksha': 'protection'})
None

Of course, the beartype.cave submodule also publishes types not accessible directly like RegexCompiledType (i.e., the type of all compiled regular expressions). All else being equal, beartype.cave is preferable.

Good function! The type hints applied to this function now accurately document this function’s API. All’s well that ends typed well. Suck it, Shere Khan.

Arbitrary Types

Everything above also extends to:

• Arbitrary types like user-defined classes and stock classes in the Python stdlib (e.g., argparse.ArgumentParser) – all of which are also trivially type-checked by annotating parameters and return values with those types.

• Arbitrary callables like instance methods, class methods, static methods, and generator functions and methods – all of which are also trivially type-checked with the @beartype decorator.

Let’s declare a motley crew of beartyped callables doing various silly things in a strictly typed manner, just ‘cause:

from beartype import beartype
from beartype.cave import GeneratorType, IterableType, NoneType

class MaximsOfBaloo(object):
    @beartype
    def __init__(self, sayings: IterableType):
        self.sayings = sayings

@beartype
def inform_baloo(maxims: MaximsOfBaloo) -> GeneratorType:
    for saying in maxims.sayings:
        yield saying

For genericity, the MaximsOfBaloo class initializer accepts any generic iterable (via the beartype.cave.IterableType tuple listing all valid iterable types) rather than an overly specific list or tuple type. Your users may thank you later.

For specificity, the inform_baloo generator function has been explicitly annotated to return a beartype.cave.GeneratorType (i.e., the type returned by functions and methods containing at least one yield statement). Type safety brings good fortune for the New Year.

Let’s iterate over that generator with good types:

>>> maxims = MaximsOfBaloo(sayings={
...     '''If ye find that the Bullock can toss you,
...           or the heavy-browed Sambhur can gore;
...      Ye need not stop work to inform us:
...           we knew it ten seasons before.''',
...     '''“There is none like to me!” says the Cub
...           in the pride of his earliest kill;
...      But the jungle is large and the Cub he is small.
...           Let him think and be still.''',
... })
>>> for maxim in inform_baloo(maxims): print(maxim.splitlines()[-1])
       Let him think and be still.
       we knew it ten seasons before.

Good generator. Let’s call it again with bad types:

>>> for maxim in inform_baloo([
...     'Oppress not the cubs of the stranger,',
...     '     but hail them as Sister and Brother,',
... ]): print(maxim.splitlines()[-1])
Traceback (most recent call last):
  File "<ipython-input-10-7763b15e5591>", line 30, in <module>
    '     but hail them as Sister and Brother,',
  File "<string>", line 12, in __inform_baloo_beartyped__
beartype.roar.BeartypeCallTypeParamException: @beartyped inform_baloo() parameter maxims=['Oppress not the cubs of the stranger,', '     but hail them as Sister and ...'] not a <class '__main__.MaximsOfBaloo'>.

Good generator! The type hints applied to these callables now accurately document their respective APIs. Thanks to the pernicious magic of beartype, all ends typed well… yet again.

Unions of Types

That’s all typed well, but everything above only applies to parameters and return values constrained to singular types. In practice, parameters and return values are often relaxed to any of multiple types referred to as unions of types. ^{You can thank set theory for the jargon… unless you hate set theory. Then it’s just our fault.}

Unions of types are trivially type-checked by annotating parameters and return values with tuples containing those types. Let’s declare another beartyped function accepting either a mapping or a string and returning either another function or an integer:

from beartype import beartype
from beartype.cave import FunctionType, IntType, MappingType

@beartype
def toomai_of_the_elephants(memory: (str, MappingType)) -> (
    IntType, FunctionType):
    return len(memory) if isinstance(memory, str) else lambda key: memory[key]

For genericity, the toomai_of_the_elephants function accepts any generic integer (via the beartype.cave.IntType abstract base class (ABC) matching both builtin integers and third-party integers from frameworks like NumPy and SymPy) rather than an overly specific int type. The API you relax may very well be your own.

Let’s call that function with good types:

>>> memory_of_kala_nag = {
...     'remember': 'I will remember what I was, I am sick of rope and chain—',
...     'strength': 'I will remember my old strength and all my forest affairs.',
...     'not sell': 'I will not sell my back to man for a bundle of sugar-cane:',
...     'own kind': 'I will go out to my own kind, and the wood-folk in their lairs.',
...     'morning':  'I will go out until the day, until the morning break—',
...     'caress':   'Out to the wind’s untainted kiss, the water’s clean caress;',
...     'forget':   'I will forget my ankle-ring and snap my picket stake.',
...     'revisit':  'I will revisit my lost loves, and playmates masterless!',
... }
>>> toomai_of_the_elephants(memory_of_kala_nag['remember'])
56
>>> toomai_of_the_elephants(memory_of_kala_nag)('remember')
'I will remember what I was, I am sick of rope and chain—'

Good function. Let’s call it again with a tastelessly bad type:

>>> toomai_of_the_elephants(0xDEADBEEF)
Traceback (most recent call last):
  File "<ipython-input-7-e323f8d6a4a0>", line 1, in <module>
    toomai_of_the_elephants(0xDEADBEEF)
  File "<string>", line 12, in __toomai_of_the_elephants_beartyped__
BeartypeCallTypeParamException: @beartyped toomai_of_the_elephants() parameter memory=3735928559 not a (<class 'str'>, <class 'collections.abc.Mapping'>).

Good function! The type hints applied to this callable now accurately documents its API. All ends typed well… still again and again.

from beartype import beartype
from beartype.cave import EnumType, EnumMemberType, NoneTypeOr
from enum import Enum

class Lukannon(Enum):
    WINTER_WHEAT = 'The Beaches of Lukannon—the winter wheat so tall—'
    SEA_FOG      = 'The dripping, crinkled lichens, and the sea-fog drenching all!'
    PLAYGROUND   = 'The platforms of our playground, all shining smooth and worn!'
    HOME         = 'The Beaches of Lukannon—the home where we were born!'
    MATES        = 'I met my mates in the morning, a broken, scattered band.'
    CLUB         = 'Men shoot us in the water and club us on the land;'
    DRIVE        = 'Men drive us to the Salt House like silly sheep and tame,'
    SEALERS      = 'And still we sing Lukannon—before the sealers came.'

@beartype
def tell_the_deep_sea_viceroys(story: NoneTypeOr[EnumType] = None) -> (
    NoneTypeOr[EnumMemberType]):
    return story if story is None else list(story.__members__.values())[-1]

>>> tell_the_deep_sea_viceroys(Lukannon)
<Lukannon.SEALERS: 'And still we sing Lukannon—before the sealers came.'>
>>> tell_the_deep_sea_viceroys()
None

from beartype import beartype
from beartype.cave import EnumType, EnumMemberType, NoneType

@beartype
def tell_the_deep_sea_viceroys(story: (EnumType, NoneType) = None) -> (
    (EnumMemberType, NoneType)):
    return list(story.__members__.values())[-1] if story is not None else None

from beartype import beartype
from beartype.cave import EnumType, EnumMemberType, NoneTypeOr

EnumOrEnumMemberType = (EnumType, EnumMemberType)

@beartype
def sang_them_up_the_beach(
    woe: NoneTypeOr[EnumOrEnumMemberType] = None) -> (
    NoneTypeOr[EnumOrEnumMemberType]):
    return woe if isinstance(woe, NoneTypeOr[EnumMemberType]) else (
        list(woe.__members__.values())[-1])

>>> sang_them_up_the_beach(Lukannon)
<Lukannon.SEALERS: 'And still we sing Lukannon—before the sealers came.'>
>>> sang_them_up_the_beach()
None

Efficiency Concerns

Why? Because implementing even the core PEP 484 standard in pure Python while preserving beartype’s O(1) time complexity guarantee is infeasible.

Consider a hypothetical PEP 484-compliant @slothtype decorator decorating a hypothetical callable accepting a list of strings and returning anything:

from slothtype import slothtype
from typing import Any, List

@slothtype
def slothful(sluggard: List[str]) -> Any:
    ...

This is hardly the worst-case usage scenario. By compare to some of the more grotesque outliers enabled by the typing API (e.g., infinitely recursive types), a non-nested iterable of scalars is rather tame. Sadly, slothful still exhibits Ω(n) time complexity for length n of the passed list, where Ω may be read as “at least as asymptotically complex as” under the standard Knuth definition.

That’s bad. Each call to slothful now type-checks each item of a list of arbitrary size before performing any meaningful work. Python prohibits monkey-patching builtin types, so this up-front cost cannot be amortized across all calls to slothful (e.g., by monkey-patching the builtin list type to cache the result of prior type-checks of lists previously passed to slothful and invalidating these caches on external changes to these lists) but must instead be paid on each call to slothful. Ergo, Ω(n).

Safety Concerns

That’s not all, though. PEP 484 itself violates prior PEPs, including:

• PEP 3141 – A Type Hierarchy for Numbers, which PEP 484 authors subjectively deride without evidence or explanation as suffering “some issues” despite offering only a substantially worse solution – seemingly just to promote the type hierarchy defined by the “typing” module over those defined by other (presumably lesser) modules. Rather than reuse the existing numeric tower used by all third-party numeric frameworks (e.g., NumPy, SymPy), PEP 484-compliant type checkers instead silently coerce float types into Union[float, int] types and complex types into Union[complex, float, int] types. This is blatantly bad. A function internally guaranteed to return a floating-point number never returns an integer. Integers, floating point numbers, and complex numbers exhibit markedly different usage, safety, and performance characteristics. Under PEP 484, preserving these distinctions is infeasible.

• The entirety of PEP 20 – The Zen of Python, especially the sanity-preserving and safety-enhancing “Explicit is better than implicit” maxim, which PEP 484 repeatedly violates by implicitly coercing:

  • The non-type None singleton to type(None).

  • The complex type to Union[complex, float, int].

  • The float type to Union[float, int].

Optimistic Hand-waving

Beartype does intend to support the proper subset of PEP 484 (and its vituperative band of ne’er-do-wells) that both complies with prior PEPs and is efficiently implementable in pure Python – whatever that may be. Full compliance may be off the map, but at least partial compliance with the portions of these standards that average users care about is well within the realm of “…maybe?”

Preserving beartype’s O(1) time complexity guarantee is the ultimate barometer for what will be and will not be implemented. That and @leycec’s declining sanity. Our bumpy roadmap to a better-typed future now resembles:

If we wish upon a GitHub star, even the improbable is possible.