Beartype 0.19.0: A Flying Man-Pig Gives the Thumbs Up of QA @beartype 0.19.0 gently glides into your CI workflow for a ~~crash~~ miracle landing. Engines go *brrrrrrrr.* ![](https://media1.tenor.com/m/NO25qNwRMDUAAAAC/porco-rosso-plane.gif) ^{*@beartype 0.19.0 narrowly avoids the grazing sheep in this terrifying metaphor.*} @beartype 0.19.0 invites you to experience either the future of QA *or* a new catastrophe for QA – all from the comfort of your (t)rusty keyboard. It now thrums with untold power and the lurid afterglow of our out-of-control release cycle. ```bash pip install --upgrade beartype # <-- engines hit full throttle, stomach hits full empty ``` @beartype 0.19.0 is proudly brought to you by... ## GitHub Sponsors: When You Befriend the Bear, You Got a Bear This release comes courtesy these proud [GitHub Sponsors](https://github.com/sponsors/leycec), without whom @leycec's cats would currently be eating grasshoppers: * @sesco-llc (SESCO Enterprises), "The Power of Innovation in Trading": ^{*this inspires me to get out of the house and do something*} https://sescollc.com * @DylanModesitt (Dylan Modesitt), quantitative strategies energy trading associate: ^{*...wikipedia, don't fail me now!*} https://dylanmodesitt.com * @tactile-metrology (Tactile Metrology), "Software and hardware that you can touch." When I want to be touched by software and hardware, I call @tactile-metrology: https://metrolo.gy ^{imagine if this domain actually worked. *how cool would that be!?*} Thanks so much, masters of fintech and metrology. ![](https://media1.tenor.com/m/eP5wF2oH6E4AAAAC/falling-land.gif) ^{The Masters of Fintech and Metrology. *That's who.*} ## @beartype 0.19.0: What Broke This Time? ^{*Probably, a whole lot. Hopefully, a whole little. The truth lies in the middle.*} @beartype 0.19.0 sidles up to your codebase in its blind spot with something suspicious in its paws. Questionable new features include: * `beartype.door.infer_hint()`: let BeartypeAI™ write your type hints for you, because you no longer have [*der Wille zur Macht*](https://en.wikipedia.org/wiki/Will_to_power) to constantly deal with all this **[**`redacted pejorative`**]**: ```python # I've got a crazy object here, @beartype. What's the crazy type hint that # matches my crazy object? This is gonna really suck. I can *FEEL* it coming # through my monitor tonight. >>> beartype.door.infer_hint(pygments.lexers.PythonLexer().tokens["root"]) list[typing.Union[tuple[str | collections.abc.Callable[ typing.Concatenate[object, object, ...], object], ...], tuple[str | pygments.token._TokenType[str], ...], typing.Annotated[ collections.abc.Collection[str], beartype.vale.IsInstance[ pygments.lexer.include]]]] # <-- I have no idea. Neither does that cute intern. ``` * `beartype.claw.beartype_all()` + `BeartypeConf(claw_skip_package_names)`: a single one-liner type-checks your **entire app stack** at runtime *or* test-time while ignoring problematic third-party packages that inexplicably hate @beartype for "reasons": ```python beartype_all(conf=BeartypeConf(claw_skip_package_names=('bad_package', 'dumb.submodule'))) ``` * `**kwargs: int | str`: @beartype type-checks annotated variadic keyword arguments! yay! uhh... **wait.** wasn't @beartype *always* doing that? these emoji suggest otherwise: :smile: → :sob: ```python def i_am_simply_shocked(**kwargs: int | str): ... # <-- @beartype actually checks this now ``` * **Deeper `O(1)` type-checking.** @beartype 0.19.0 now deeply type-checks type hints like: * `frozenset[...]`. * `set[...]`. * `collections.deque[...]`. * `collections.abc.Collection[...]`. * `collections.abc.KeysView[...]`. * `collections.abc.MutableSet[...]`. * `collections.abc.Set[...]`. * `collections.abc.ValuesView[...]`. * `typing.AbstractSet[...]`. * `typing.Collection[...]`. * `typing.Deque[...]`. * `typing.FrozenSet[...]`. * `typing.KeysView[...]`. * `typing.MutableSet[...]`. * `typing.Set[...]`. * `typing.ValuesView[...]`. * **Shallow `O(1)` type-checking support** for exciting (yet wildly unpopular) PEP standards that nobody uses. @beartype 0.19.0 now quietly ignores these PEPs *without* throwing up everywhere: * [PEP 612 – Parameter Specification Variables](https://peps.python.org/pep-0612) (e.g., `def muh_decorator_closure(*args: P.args, **kwargs: P.kwargs):`). * [PEP 646 – Variadic Generics](https://peps.python.org/pep-0646) (e.g., `Ts = typing.TypeVarTuple('Ts')`). * [PEP 692 – Using TypedDict for more precise `**kwargs` typing](https://peps.python.org/pep-0692) (e.g., `def muh_kwargs_func(**kwargs: typing.Unpack[MuhTypedDict]]):`). * **Official `multiprocessing` support.** @beartype 0.19.0 now officially supports fork-based distributed workloads based on the awful `pickle` module. :rofl: * **Third-party decorator integration.** @beartype 0.19.0 now officially supports popular Just-in-Time (JIT) decorators for machine learning (ML) like: * `@equinox.filter_jit`. * `@jax.jit`. * `@numba.njit`. * **Python 3.13** + [`--disable-gil`](https://peps.python.org/pep-0703) + [`--enable-experimental-jit`](https://peps.python.org/pep-0744). Pinch me, I must be hyperventilating into a paper bag again. * **Sane build toolchain:** from `setuptools` + `setup.py` ^{:vomiting_face:} to [**Hatch**](https://github.com/pypa/hatch) + `pyproject.toml`. ^{:clinking_glasses:} * **Sane publishing toolchain:** from antiquated GitHub Actions tokens ^{:vomiting_face:} to **[PyPI-specific "Trusted Publishers"](https://blog.pypi.org/posts/2023-04-20-introducing-trusted-publishers).** ^{:clinking_glasses:} * **Critical bugs resolutions:** *blah, blah*. Who cares. I'm tired. So are you. ![](https://media1.tenor.com/m/F6JHVULHwxwAAAAd/porco-rosso-studio-ghibli.gif) ^{*@beartype 0.19.0 feature list mollifies even the unruly pirate crowd*} ## `infer_hint():` Introducing BeartypeAI™, Your Chummy QA Pal Chummy Unpaid QA Pal BeartypeAI™ is on the job and grumbling already about union overtime. Because your team hates type hints (and you're reluctantly starting to admit they might be onto something), BeartypeAI™ does what nobody else wants to do. Authoring type hints is a thankless janitorial fetch quest that smells bad and consumes your last will to code. Allow our new `beartype.door.infer_hint()` function to automate your ongoing stomache pain away. Type hints may be like that kidney stone the size of your mother-in-law's big head, but that's no reason to curl up on a gurney clutching your side in blinding agony. But first: > "What *are* type hints, really – aside from the second-worst ongoing maintenance nightmare in Python next to `pyproject.toml` semantic versioning dependency bumps?" Type hints are the most compact description of the internal structure of your objects. If you know the type hint of an object, you know the object better than the object knows itself. Type hints are the ultimate self-documentation. Unlike docstrings, type hints never lie or @beartype breaks your app. Type hints are both human-readable *and* machine-readable. They're literally the only thing that is. Many type hints are trivial to write. All of us can sling around breezy `list[int] | None` type hints while yawning. It's not impressive. My cats can write that type hint with one sleepless eye open. Seriously. Why do cats sleep with one eye open, anyway? Doesn't that kinda defeat the purpose of... I dunno, *sleeping*? Must suck to be a paranoid cat. Uhhh. *Back to the discussion.* Some type hints, however, are non-trivial. You can't write them. Nobody can. They contain more square brackets than an 80's ASCII roguelike with an understated name like *Death Gehenna* or *Eternal Furnaces of NetSwargy.* When your type hint looks like this, the end of code maintainability cannot be far: ![](https://media1.tenor.com/m/28x-EJ7uoq8AAAAC/porco-rosso-kurenai-no-buta.gif) ^{*that feeling when your type hints resemble incomprehensible toddlers*} Moreover, you don't even *know* the internal structure of most objects. Somebody else wrote those objects. They forgot how those objects worked a hot minute after clocking out at 4:12AM seven days deep into a crunch-time death march last January. They documented how those objects worked, but their documentation doesn't make sense and lies about everything. Now nobody knows how those objects work. But what if somebody *did* know how those objects work? What if somebody knew Python better than Python knew itself? Introducing... *somebody.* ## `infer_hint():` Deep Introspection for the Deep Code Diver Let `@beartype` ease your weary burden, traveller. It is dangerous to go alone: ```python # Crazy object you could understand. But... ain't nobody got that kinda time. >>> from pygments.lexers import PythonLexer >>> root_tokens = PythonLexer().tokens["root"] # I've got a crazy object here, @beartype. What's the crazy type hint that # matches my crazy object? This is gonna really suck. I can *FEEL* it coming # through my monitor tonight. >>> from beartype.door import infer_hint >>> infer_hint(root_tokens) list[ # <-- what could possibly go wrong? typing.Union[ # <-- sucky stuff starts tuple[str | collections.abc.Callable[typing.Concatenate[object, object, ...], object], ...], # <-- sucky stuff intensifies tuple[str | pygments.token._TokenType[str], ...], # <-- so much sucky stuff typing.Annotated[collections.abc.Collection[str], beartype.vale.IsInstance[pygments.lexer.include]] # <-- go to heck, typing! ] # <-- a pox on your square brackets ] # <-- i have no idea and neither do you ``` *...uhh.* If you say so, `@beartype`. I guess? `` ![](https://media1.tenor.com/m/MT4FJbX6XOwAAAAC/porco-rosso-kurenai-no-buta.gif) ^{*codebase narrowly dodges another inexpert potshot from* `pygments`} ### BeartypeAI™: Even a Broken Algorithm is Right Twice a Commit `beartype.door.infer_hint()` (i.e., the algorithm hereafter known simply as BeartypeAI™) knows all about deep introspection of arbitrarily complex objects. Here's what BeartypeAI™ knows: > **BeartypeAI™**: "I know that your type hints kinda suck. Wait... where *are* your type hints? Oh, Gods. You don't type hint. I'm panicking. I'm panicking." > **You**: "Tell my team something my team don't know, BeartypeAI™. We hate type hints. So we don't type hint. We code instead. You should try it sometime. But... hey, aren't you a type-checking bear? Can you even code with those fat paws?" > **BeartypeAI™**: "Hold my QA beer." BeartypeAI™ is here to tell you something you don't know and wouldn't care about even if you did. BeartypeAI™ is here to write your type hints for you. Why? Because you hate type hints. Just: 1. Feed `beartype.door.infer_hint()` arbitrarily complex objects. 1. Annotate those objects with the type hints it regurgitates. It's impossible to unpack how much madness is happening inside BeartypeAI™. *Let's try anyway.* ```python >>> from beartype.door import infer_hint # <-- all your dreams begin here # Show me the type hint describing a useless object, @beartype! >>> infer_hint(object()) # <-- makes sense # Show me the type hint describing a useless type, @beartype! >>> infer_hint(object) type[object] # <-- so. cool. # Show me the type hint describing a list of strings, @beartype! >>> infer_hint(['expose', 'extreme', 'explosions!',]) list[str] # <-- hole in one # Show me the type hint describing a tuple of crazy stuff, @beartype! >>> infer_hint((b'heh', [0xBEEEEEEEF, 'ohnoyoudont',])) tuple[bytes, list[int | str]] # <-- no idea, but i trust it # Show me the type hint describing an insane recursive list, @beartype! >>> recursive_list = ['this is fine', b'but...',] >>> recursive_list.append(recursive_list) >>> infer_hint(recursive_list) list[str | bytes | beartype.door._func.infer.inferhint.BeartypeInferHintContainerRecursion] # <-- just go with it ``` ![](https://media1.tenor.com/m/05gRxRVlVjQAAAAd/porco-rosso.gif) ^{*BeartypeAI™ pounds back another as your* `git log` *explodes in the distance*} ### Homebrew Collection Classes: Annotate the Unannotatable We've all been there. Some "genius"-tier wise guy devbro invented his own homebrew pure-Python collection called `WeirdoCustomList` *without* subclassing a standard `collections.abc` abstract base class. Sure, they *could* have just subclassed `collections.abc.MutableSequence` to write their special-needs alternative to the builtin `list` type. That would have been too easy. They're a masochist, so they wrote everything from scratch. Homebrew collections are more common than you think. They're friggin' *everywhere*! They're multiplying like meat flies! The cat's choking on bloody homebrow collections! Look above, for example. See that nasty `typing.Annotated[collections.abc.Collection[str], IsInstance[pygments.lexer.include]]` type hint that BeartypeAI™ wrote for you? *Yeah.* That's right. The public `pygments.lexer.include` type is actually a homebrew collection. They thought they were being smart. Sadly, they were being dumb. Because they wrote a homebrew collection from scratch, their collection type is unsubscriptable. You can't subscript it with child type hints like with `list[str]`, so you can't use their collection type as a type hint factory to write type hints, so you can't actually validate their homebrew collection. In fact, you can't validate *any* homebrew collections. **...until now.** BeartypeAI™ knows all about homebrew collections. BeartypeAI™ knows that you *can* actually validate homebrew collections – but only if you write a custom beartype validator leveraging the PEP 593-compliant `typing.Annotated[...]` type hint factory in concert with the @beartype-specific `beartype.vale.IsInstance[...]` validator. Please don't do this manually. You value your precious life force that is leaking all over your keyboard as we speak. That's what the `typing.Annotated[collections.abc.Collection[str], IsInstance[pygments.lexer.include]]` type hint is all about. BeartypeAI™ correctly detected that this homebrew collection is *actually* just an instance of the `pygments.lexer.include` class that is externally usable as a collection of strings. Let's get more explicit. Nobody understands `pygments` – not even `pygments`. Instead, consider... ![](https://media1.tenor.com/m/T4Se3E_xPMQAAAAd/porco-rosso-plane.gif) ^{*BeartypeAI™ casually flings itself above another picturesque yet ultimately incomprehensible codebase*} #### Exhibit (A) – Weirdo Custom List It's... it's hideous! ```python from beartype.door import infer_hint from collections.abc import Iterable, Iterator # Define a weirdo custom list. class WeirdoCustomList(object): ''' Weirdo custom list. The one. The only. Weirdo custom list pretends to mean no harm. Weirdo custom list is lonely at night and only wants to be snuggle-friends. *How could you refuse weirdo custom list in its example of need?* ''' def __init__(self, items: list) -> None: self._items = items def __contains__(self, item: object) -> bool: return item in self._items def __iter__(self) -> Iterator: return iter(self._items) def __len__(self) -> int: return len(self._items) def __getitem__(self, index: int) -> object: return self._items[index] def __reversed__(self) -> Iterator: return reversed(self._items) def count(self, item: object) -> int: return self._items.count(item) def index(self, *args, **kwargs) -> int: return self._items.index(*args, **kwargs) def __delitem__(self, index: int) -> None: del self._items[index] def __setitem__(self, index: int, item: object) -> None: self._items[index] = item def __iadd__(self, item: object) -> object: self._items += item def append(self, item: object) -> None: self._items.append(item) def clear(self) -> None: self._items.clear() def extend(self, items: Iterable) -> None: self._items.extend(items) def insert(self, index: int, item: object) -> None: self._items.insert(index, item) def pop(self, *args, **kwargs) -> object: return self._items.pop(*args, **kwargs) def remove(self, item: object) -> None: self._items.remove(item) def reverse(self) -> None: self._items.reverse() # Infer the type hint for a weirdo custom list of strings. print(infer_hint(WeirdoCustomList([ 'No way,', '@beartype.', 'No.', "Friggin'.", 'Way.']))) ``` ...which prints: ```python typing.Annotated[collections.abc.MutableSequence[str], IsInstance[WeirdoCustomList]] ``` "What's so hot about that?", you may now be thinking. Allow me to now pontificate boringly. `WeirdoCustomList` isn't subscriptable. It's *not* a type hint factory. Moreover, despite being a mutable sequence, `WeirdoCustomList` doesn't actually subclass the standard `collections.abc.MutableSequence` protocol. Yet, BeartypeAI™ correctly detected that this particular weirdo custom list is a mutable sequence of strings. How? It's best not to ask weirdo custom list these questions. :rofl: ![](https://media1.tenor.com/m/tc_T8z3f_BkAAAAC/studio-ghibli-hayao-miyazaki.gif) ^{*wake up BeartypeAI™ when those type hints start making sense*} ### `Callable[...]` Type Hints: Gods, They Suck. Annotating callables (especially callbacks) with PEP-compliant `Callable[...]` type hints is *basically* impossible. Personally, I've never gotten a single `Callable[...]` type hint to work right. They *never* match the callables they're supposed to when I write them myself. `mypy` and `pyright` *always* vomit all over themselves and then me. I mostly just give up now and use the unsubscripted `collections.abc.Callable` abstract base class instead of full-blown `Callable[...]` type hints... **...until now.** BeartypeAI™ knows literally everything there is to know about annotating callables. What doesn't BeartypeAI™ know? Well, friends: * BeartypeAI™ knows that a `lambda` function accepting no parameters is annotated as... ```python >>> infer_hint(lambda: "No. Friggin'. Way.") collections.abc.Callable[[], object] # <-- woah ``` * BeartypeAI™ knows that a `lambda` function accepting multiple parameters is annotated as... ```python >>> infer_hint(lambda you, will, believe: "@beartype, I am your code father.") collections.abc.Callable[[object, object, object], object] # <-- i don't know what's happening here, but i like it ``` * BeartypeAI™ knows that a normal function accepting two mandatory annotated parameters and one optional annotated parameter is "best" annotated with a PEP 612-compliant `typing.Concatenate[...]` subscription as... ```python >>> def i_am_tired(this: float, so: int, boring: str = "y u so boring, @beartype!?"): ... >>> infer_hint(i_am_tired) collections.abc.Callable[typing.Concatenate[float, int, ...], object] # <-- don't ask, just accept. ``` * BeartypeAI™ knows that a decorator wrapper function accepting a PEP 612-compliant parameter specification is annotated as... ```python >>> from typing import ParamSpec >>> P = ParamSpec('P') >>> def so_param_so_spec(*args: P.args, **kwargs: P.kwargs): ... >>> infer_hint(so_param_so_spec) collections.abc.Callable[~P, object] # <-- yer frickin' blowin' mah mind here, yo ``` * BeartypeAI™ knows that a decorator wrapper function accepting two mandatory annotated parameters followed by a PEP 612-compliant parameter specification is annotated with a PEP 612-compliant `typing.Concatenate[...]` subscription as... ```python >>> from typing import ParamSpec >>> P = ParamSpec('P') >>> def more_param_more_spec( ... go_crazy: int, ... dont_mind_if_i_do: str, ... *args: P.args, ... **kwargs: P.kwargs ... ): ... >>> infer_hint(more_param_more_spec) collections.abc.Callable[typing.Concatenate[int, str, ~P], object] # <-- pretty sure the universe just exploded ``` What I'm trying to say here is that BeartypeAI™ knows all and sees all and doesn't like it what it sees, but is still doing it's best for everybody. It knows more than me. It probably knows more than even you, even though you know everything. That's how much BeartypeAI™ knows. ![](https://media1.tenor.com/m/Wbsns4VU_PsAAAAC/studio-ghibli-ghibli.gif) ^{*BeartypeAI™ takes the high road when it comes to `Callable[...]` type hints*} ### Tensors Type Hints: Gods, They Suck Too. Tensor type hints *really* suck. So your team wants to annotate NumPy, JAX, PyTorch, or TensorFlow arrays, huh? That's a perfectly reasonable request. Too bad, though. *Because tensor type hints suck.* Tensor type hints suck so bad you have to use third-party packages like `jaxtyping` just to make them work, despite the fact that both NumPy and JAX ship type hint-centric subpackages like `numpy.typing` and `jax.typing` that are *supposed* to make tensor type hints "just work." Of course, tensor type hints don't "just work." They don't even work... **...until now.** BeartypeAI™ knows literally everything there is to know about annotating tensor type hints. Actually, that's a lie. I *really* wanted BeartypeAI™ to know literally everything there is to know about annotating tensor type hints in time for @beartype `0.19.0rc1`. Sadly, I played video games instead. I only got around to implementing BeartypeAI™ support for inferring **NumPy tensor type hints.** Still, NumPy is better than nothing. One out of four ain't bad. Right? ...anybody? :face_exhaling: ```python # Define the greatest NumPy array that has ever existed. >>> from numpy import asarray >>> best_array_is_best = asarray((1, 0, 3, 5, 2, 6, 4, 9, 2, 3, 8, 4, 1, 3, 7, 7, 5, 0,)) # Create a type hint validating that array, @beartype! Look. Just do it. >>> from beartype.door import infer_hint >>> infer_hint(best_array_is_best) typing.Annotated[numpy.NDArray[int], beartype.vale.IsAttr['ndim', beartype.vale.IsEqual[1]]] # <-- wtf, @beartype ``` And... *that's the type hint.* That type hint requires *no* third-party dependencies. It's all BeartypeAI™, all one-liner. Nobody's writing that sort of gruelling bracket hell on their own. Not even @leycec. Just let somebody else do your suffering for you. That somebody is BeartypeAI™. Who knew? ![](https://media1.tenor.com/m/zynthmbNFvUAAAAC/porco-rosso-kurenai-no-buta.gif) ^{*your codebase grips its hat as BeartypeAI™ boldly shows off for no reason*} ## `infer_hint()` Time Complexity: All Roads Lead to `O(1)` `infer_hint()` is the first @beartype API to respect the long-standing BeartypeConf(strategy=BeartypeStrategy.O*)` configuration option. Previously, *all* @beartype APIs defaulted to `O(1)` constant-time behaviour by randomly sampling container items for improved scalability. In the future, *all* @beartype APIs will allow you to customize this behaviour by specifying alternate iteration strategies like: * `O(n)` linear-time behaviour, in which @beartype exhaustively examines *all* possible container items with recursion. * `O(log n)` logarithmic-time behaviour, in which @beartype recursively examines *only* a logarithmic subset of all possible container items – a scalable compromise between non-deterministic `O(1)` immediacy and deterministic `O(n)` lethargy. Now, `infer_hint()` is the first @beartype API to fully support two of those three strategies. Witness as history unfolds with a discomfiting "*plop!*": * **(Default)** `infer_hint(obj)` is equivalent to `infer_hint(obj, conf=BeartypeConf(strategy=BeartypeStrategy.On)))`. Under the `O(n)` strategy, `infer_hint()` exhaustively examines *all* possible container items with recursion. To infer authoritative type hints from interactive REPLs and Jupyter Notebooks, `infer_hint()` differs from the remainder of the @beartype codebase by defaulting to **`O(n)`-style linear-time iteration**. This is generally what most users "probably" want when inferring type hints. Since you are reading this, you are not one of those users. * `infer_hint(obj, conf=BeartypeConf(strategy=BeartypeStrategy.O1)))`. Under the `O(1)` strategy, `infer_hint()` pseudo-randomly examines only a single container item at each nesting level. This is generally what algorithms like **structural similarity** ^{*see below*} and **multiple dispatch** ^{*more seeing below*} want. To activate the Hyperlight Drive, these use cases want to explicitly pass a `conf` enabling the `O1` strategy. `BeartypeStrategy.O1`: *punch it, bald man!* ![](https://media1.tenor.com/m/r9vxK4n7zrkAAAAC/%E3%81%8B%E3%81%BF%E5%A4%AA.gif) ^{*@leycec punches it with fear in his heart*} ## `infer_hint()` Use Cases: Where We Pontificate Both Laconically and Loquaciously What do those words even mean? Doesn't matter. Thankfully, what *does* matter is that type hint inference has real-world use cases that far exceed just "write my type hints for me, cause i h8 type hints m8. fr!" Just get a gander of *these* algorithmic goodies: * **Worst-case `O(1)` structural similarity comparison** – faster even than `==`-based equality comparison between arbitrary objects, which has worst-case `O(n)` linear-time complexity and thus scales poorly. *Hyper-fast object comparison is what we sayin'.* * **Best- and average-case `O(1)` and worst-case `O(k)` multiple-dispatch** for `k` the number of callables being dispatched to – probably the fastest multiple-dispatch algorithm in *any* language. *Hyper-fast dispatch is what we still sayin'.* Let's plumb these depths like Mario on a Piranha plant pipe bender. ![](https://media1.tenor.com/m/9Y3EabMvvbQAAAAC/porco-rosso-kurenai-no-buta.gif) ^{*@beartype smokes two bug-filled joints. then, @beartype smokes two more.*} ### Use Case #1: Structural Similarity (So It Does That Too Now, Huh?) In the beginning, there was: ```python # The "is" operator. Test whether two objects are literally identical. >>> "I like big bugs and I cannot lie." is "I like big bugs and I cannot lie." True # The "==" operator. Test whether two objects are semantically identical. >>> ['Other', 'devbros', 'may', 'deny',] == ['Other', 'devbros', 'may', 'deny',] True ``` But what if you want to test whether two objects are merely **structurally similar** (i.e., have a similar internal structure but are neither literally nor semantically identical)? Without BeartypeAI™, you can't do that. But you have BeartypeAI™. You no longer have to accept the mouldy table scraps that the standard Python library has left you. Structural similarity compares the large-scale "shape" of two objects without regard for the small-scale minutiae (like the exact items) in those objects. Structural similarity thus combines: * All the benefits of the `is` operator (like `O(1)` time complexity when calling `infer_hint(obj, conf=BeartypeConf(strategy=BeartypeStrategy.On)))`) with... * All the benefits of the `==` operator (like actually computing meaningful work) with... * None of the disadvantages of either. Tensors offer a useful way to understand structural similarity: "Do two tensors have the same `dtype` (i.e., type of all items in a tensor) and `ndim` (i.e., dimensionality)? If yay, those two tensors are structurally similar; if nay, those two tensors are structurally *dis*similar." There are two different kinds of structural similarity, broadly speaking: * **Exact structural similarity,** in which you test whether two objects have the exact same "shape": e.g., ```python >>> from beartype.door import infer_hint, is_bearable # <-- boring stuff # @beartype builds excitement builds. Declare data structures for great glory of your code. >>> awesome_data_structure = [{"hoh, boy": int, "lol, golgo 13": [lambda: None]}, 0xFAAAAAACE] >>> baleful_data_structure = [0xDEAFDEFF, {"nopleaseno": [lambda: False], "NOOOO!": object}] # Describe the internal structure of your final masterpiece. >>> awesome_hint = infer_hint(awesome_data_structure) list[int | dict[str, list[collections.abc.Callable[[], object]] | type[int]]] # <-- ok >>> baleful_hint = infer_hint(baleful_data_structure) list[int | dict[str, type[object] | list[collections.abc.Callable[[], object]]]] # <-- whateva you say, bear # Do these two objects have the exact same internal structure? >>> awesome_hint == baleful_hint False # <----- no dice, huh? *sigh* ``` * **Substructural similarity,** in which you test whether one object has a "shape" that "fits inside" that of another object. As the prior example illustrates, two data structures can have a similar internal structure but ultimately differ on a specific detail that nobody particularly cares about. Whereas `awesome_hint` contains a dictionary mapping to *integers,* `baleful_hint` contains a dictionary mapping to merely *objects.* You are now thinking: "Integers *are* objects, you doltish man. Shouldn't we be able to ignore these awkward trivialities?" I object to being called a dolt while admitting you make a point. Make things vaguer by harnessing the perfidious power of `beartype.door.infer_hint()` + `beartype.door.is_bearable()`. Arise, substructural similarity! A new darkness! ```python >>> from beartype.door import infer_hint, is_bearable # <-- boring stuff # Excitement builds. Declare data structures for great glory of your code. >>> awesome_data_structure = [{"uhh...": int, "wat!?!": [lambda: None]}, 0xFEEEEEEED] >>> baleful_data_structure = [0xBABEEEE, {"ohgod": [lambda: True], "NOOOO!": object}] # Describe the internal structure of your great glory. >>> infer_hint(awesome_data_structure) list[int | dict[str, list[collections.abc.Callable[[], object]] | type[int]]] # <-- ok >>> infer_hint(baleful_data_structure) list[int | dict[str, type[object] | list[collections.abc.Callable[[], object]]]] # <-- i don't know. sure, i guess? # Do these two objects have a similar internal structure? >>> is_bearable(baleful_data_structure, infer_hint(awesome_data_structure)) True # <----- WTF-F-F-F-F- ``` Structural similarity cheatsheet, because the one-liner is a harsh mistress: * **Exact structural similarity** is `infer_hint(obj_1) == infer_hint(obj_2)`. * **Substructural similarity** is `is_bearable(obj_1, infer_hint(obj_2))`. Structural similarity: *when you care about what your objects care about.* ![](https://media1.tenor.com/m/UPuC5qApdocAAAAC/porco-rosso-kurenai-no-buta.gif) ^{*say goodbye to expensive comparisons that never really liked you anyway*} ### Use Case #3: Single Dispatch (Dis Ain't Yo Momma's Dispatch) "Dispatch" is a common decision problem in... well, basically any modern language that matters. So, not C. ^{*i have no regrets for igniting this flame war*} Everyone's familiar with [single-dispatch polymorphism](https://en.wikipedia.org/wiki/Polymorphism_in_object-oriented_programming), whereby an object-oriented language dynamically routes a call of an object's method to that object's "deepest" subclass overriding that method. In Python, we call this [the method-resolution order (MRO)](https://www.python.org/download/releases/2.3/mro) of an object. It's quite boring and pedantic stuff, really. I personally wouldn't click any of those links – *especially not on the weekend.* But what if you want to perform single-dispatch *outside* of a class hierarchy that you directly control? Moreover, what if want to single-dispatch on arbitrary type hints deeply describing the internal structures of objects? Classes are superficial; they fail to fully convey the types of items contained in instances of those classes, which is why we do this type hint thing. Moreover, what if we want to perform [multiple-dispatch](https://en.wikipedia.org/wiki/Multiple_dispatch), whereby the callable that is dynamically routed to (i.e., called) depends not simply on the type of a *single* object but an arbitrary number of objects? This is the dynamical Hell we now find ourselves in. Interestingly, it turns out that combining the `beartype.door.infer_hint()` + `beartype.door.is_bearable()` functions trivially yields **highly efficient `O(1)` algorithms that transparently implement both single- and multiple-dispatch.** First, the full-throttle single dispatch algorithm: ```python from beartype import BeartypeConf, BeartypeStrategy, beartype from beartype.door import infer_hint, is_bearable from collections.abc import Callable _CONF_STRATEGY_O1 = BeartypeConf(strategy=BeartypeStrategy.O1) ''' Beartype configuration enabling :math:`O(1)` constant-time random sampling. ''' @beartype def single_dispatch(obj: object, dispatcher: dict[object, Callable]) -> Callable: ''' Callable suitable for dispatching the passed object from a type hint of the passed dispatch dictionary. Parameters ---------- obj : object Object to be dispatched. dispatcher : dict[object, Callable] **Dispatch dictionary** (i.e., dictionary mapping from various type hints to corresponding callables dispatching the passed object when that object is validated by those type hints). ''' # O(1) type hint inference, I choose you! obj_hint = infer_hint(obj, conf=_CONF_STRATEGY_O1) # Go for the O(1) short-circuit, @beartype. Do it. dispatch_callable = dispatcher.get(obj_hint) if dispatch_callable and is_bearable(obj, obj_hint): return dispatch_callable # Oh, noes! Disaster. Fallback to the O(k) iteration. Pretend this is okay. for dispatch_hint, dispatch_callable in dispatcher.items(): if is_bearable(obj, obj_hint): # Inject this inferred type hint and corresponding callable back into # the dispatch dictionary, reducing the next call of this function # passed a similar object to the O(1) short-circuit above. This # guarantees amortized O(1) time complexity. dispatcher[obj_hint] = dispatch_callable return dispatch_callable raise DispatchException(f'Passed object {repr(obj)} sucks. Blowing everything up!') ``` This exhibits time complexity: * **Amortized worst-case `O(1)`.** ^{*oh by gods*} * **Non-amortized best- and average-case `O(1)`.** ^{*the gods glare with envy*} * **Non-amortized worst-case `O(k)`** for `k` callables being dispatched to. ^{*the gods smugly look down and snicker*} Generally speaking, we expect `k` to be small in the average case – like, `k < 10` small. So this is *basically* `O(1)` single-dispatch in even the non-amortized worst case. Totally realistic and compelling usage resembles something like: ```python # User-defined callables to be dispatched to. Excitement builds. def join_list_of_strs(lst: list[str]) -> str: return ''.join(lst) def join_list_of_bytes(lst: list[bytes]) -> bytes: return b''.join(lst) # User-defined object to be dispatched on. Excitement peaks. list_of_things = [b'This. ', b'String. ', b'Bytes.'] # User-defined callable suitable for this object. Excitement subsides. join_list_of_things = single_dispatch(list_of_things, dispatcher={ list[str]: join_list_of_strs, list[bytes]: join_list_of_bytes, }) # Pass this object to this callable. Excitement is in the gutter now. assert join_list_of_things(list_of_things) == b'This. String. Bytes.' ``` That's *probably* the fastest possible single-dispatch algorithm in any language. But here's where the bullet train really goes off the rails... ![](https://media1.tenor.com/m/9OmmPZ4zRSgAAAAC/porco-rosso-plane.gif) ^{*@beartype flies foolishly close to the fathomless void so you don't have to*} ### Use Case #3: Multiple Dispatch (Dat Sasquatch Ain't Got Nuthin' on Us) The single-dispatch algorithm trivially generalizes to multiple-dispatch as well. How? With cleverness, grit, and twin handlebar moustaches. :man: :man: ^{← *gritty moustauche twins*} Let's reduce the multiple-dispatch case (of dispatching over multiple objects) to the single-dispatch case (of dispatching on a single object) by **concatenating those multiple objects into a single object.** Specifically, let's encapsulate those multiple objects into a tuple. Tuples are highly space- and time-efficient in Python. More importantly, tuples whose items are hashable are themselves hashable. By subscripting fixed-length `tuple[...]` types by the multiple type hints (almost all of which are hashable) to be dispatched across, we can actually leverage the almost *exact* same algorithm as above to perform `O(1)` multiple dispatch: ```python from beartype import BeartypeConf, BeartypeStrategy, beartype from beartype.door import infer_hint, is_bearable from collections.abc import Callable, Collection _CONF_STRATEGY_O1 = BeartypeConf(strategy=BeartypeStrategy.O1) ''' Beartype configuration enabling :math:`O(1)` constant-time random sampling. ''' @beartype def multiple_dispatch( *args: object, dispatcher: dict[object, Callable]) -> Callable: ''' Callable suitable for dispatching all objects in the passed collection from a type hint of the passed dispatch dictionary. Parameters ---------- *args : object Tuple of all objects to be dispatched. dispatcher : dict[object, Callable] **Dispatch dictionary** (i.e., dictionary mapping from various type hints to corresponding callables dispatching the passed objects when those objects are validated by those type hints). ''' # O(1) type hint inference, I choose you! obj_hint = infer_hint(args, conf=_CONF_STRATEGY_O1) # Go for the O(1) short-circuit, @beartype. Do it. dispatch_callable = dispatcher.get(obj_hint) if dispatch_callable and is_bearable(args, obj_hint): return dispatch_callable # Oh, noes! Disaster. Fallback to the O(k) iteration. Pretend this is okay. for dispatch_hint, dispatch_callable in dispatcher.items(): if is_bearable(args, obj_hint): # Inject this inferred type hint and corresponding callable back into # the dispatch dictionary, reducing the next call of this function # passed a similar object to the O(1) short-circuit above. This # guarantees amortized O(1) time complexity. dispatcher[obj_hint] = dispatch_callable return dispatch_callable raise DispatchException(f'Passed object {repr(obj)} sucks. Blowing everything up!') ``` That's... *literally the exact same function.* The signature just accepts variadic positional arguments `*args` rather than a single `obj`. Whatevah! Crucially, this is still amortized worst-case `O(1)` and non-amortized worst-case `O(k)` multiple-dispatch for `k` the number of callables being dispatched. In other words, we have a **cardinality-invariant dispatch algorithm.** The time complexity of this algorithm is unconditionally `O(k)` regardless of the number of objects being dispatched over or the size of those objects. Since we generally expect `k` to be small, this is still *basically* `O(1)` multiple-dispatch. *wuuuuuuuuuut* Totally realistic and compelling usage intensifies holistically: ```python # User-defined callables to be dispatched to. Excitement builds. def join_list_of_strs_plus_str(lst: list[str], text: str) -> str: return ''.join(lst) + text def join_list_of_bytes_plus_bytes(lst: list[bytes], text: bytes) -> bytes: return b''.join(lst) + text # User-defined objects to be dispatched on. Excitement peaks. list_of_things = [b'This. ', b'String. ', b'Still. ',] plus_thing = b'Bytes.' # Tuple of all user-defined objects to be dispatched over. list_of_things_plus_thing = (list_of_things, plus_thing) # User-defined callable suitable for these objects. Excitement subsides. join_list_of_things_plus_thing = multiple_dispatch(*list_of_things_plus_thing, dispatcher={ tuple[list[str], str]: join_list_of_strs_plus_str, tuple[list[bytes], bytes]: join_list_of_bytes_plus_bytes, }) # Pass these objects to this callable. Excitement is in the gutter now. assert join_list_of_things_plus_thing(*list_of_things_plus_thing) == b'This. String. Still. Bytes.' ``` That's *definitely* the fastest possible multiple-dispatch algorithm in any language. Can't do better than `O(1)`. Suck it, Julia. Suck it. I've tested that rickety jerry-rigged shadow madness. Against all odds... *it somehow works*. No idea how, honestly. Probably falls down in edge cases, honestly. But at least for one fleeting moment in the rain, we had a dream of something beautiful. :rofl: ![](https://media1.tenor.com/m/gDkvU6Zt55EAAAAC/porco-rosso-morbid.gif) ^{*`O(1)` multiple dispatch: the skull means it wants to help you*} ## `**kwargs`: The Type-checking Chickens Come Home to Roost A few bicycle trips ago, my wife asked me a real eye-opener as the stinging sweat trickled down: > Why does "his chickens came home to roost" always mean that something bad just happened? > Isn't it a *good* thing when the chickens come home to roost? > Isn't that what chickens are supposed to do at night? *Roost?* Me: > I see that you too have autism. Seriously. Metaphors, folks. What good are they for if they make less sense than cats wearing pizza hats? Which leads us straight to... **Variadic keyword arguments.** All this time, it was reasonable to believe that @beartype was type-checking annotated variadic keyword arguments like `def func_in_a_funk(**kwargs: int)`. In actuality, @beartype was type-checking nothing there. Annotated variadic keyword arguments were silently ignored. Our flimsy reasons for doing nothing were fivefold: * **(A)** It was hard, because... * **(B)** @leycec is lazy, because... * **(C)** Nobody noticed, because... * **(D)** Nobody annotates variadic keyword arguments, because... * **(E)** The types of the values of excess keyword arguments vary by keyword. In other words, annotating variadic keyword arguments is hard, increases fragility, usually increases ambiguity, and never quite works as intended. The last reason is a good reason. The rest are bad reasons. Therefore, @beartype now type-checks annotated variadic keyword arguments as standardized by PEP 484 a decade ago. The syntax is a bit odd, though. Although boring, this is worth belabouring. Python usually wants you to explicitly spell everything out. ["Explicit is better than implicit"](https://peps.python.org/pep-0020) – except when it's not, apparently. All variadic keyword arguments are dictionaries mapping from **strings** (i.e., excess parameter names passed by keyword) to **arbitrary objects** (i.e., the values of those parameters). So far, so boring. Since all variadic keyword arguments necessarily satisfy the type hint `dict[str, object]`, however, Python interprets the type hint annotating a variadic keyword argument as the **child value type hint** of that dictionary. Thus, `def oh_boy(**kwargs: float)` is semantically equivalent to `def oh_boy(kwargs: dict[str, float])` from the perspective of the body of `oh_boy()`. So far, still boring... albeit kinda weird and meandering now. Above, I self-importantly wrote that "The types of the values of excess keyword arguments vary by keyword." The real-life embodiment of this is: ```python def fugly_muffin(**kwargs) -> int: return kwargs['hear_nuffin'] + len(kwargs['see_nuffin']) assert ugly_muffin(hear_nuffin=0xDEAF, see_nuffin='NOPE.') == 57012 ``` Above, the first excess keyword parameter `hear_nuffin` has type `int` while the second excess keyword parameter `see_nuffin` has type `str`. How do you type this madness as a single type hint when the types vary by keyword? Simple: * **The Beartype-Friendly Way,** which is also the awful way. This approach has the benefit of being supported by @beartype, but the drawback of sucking. You ambiguously type `**kwargs` as the **union** of the types of the values of all excess keyword arguments: e.g., ```python # This is trash. What you goin' do? def fugly_muffin(**kwargs: int | str) -> int: return kwargs['hear_nuffin'] + len(kwargs['see_nuffin']) ``` * **The [PEP 692 Way](https://peps.python.org/pep-0692),** which is honestly also kinda awful. This has the benefit of being unambiguous (unlike the "Beartype-Friendly Way" above), but the multiple drawbacks of not currently being supported by @beartype, requiring Python ≥ 3.12, and expanding into 500 lines of sad-faced boilerplate that will break your will to sling code on Friday nights. Under [PEP 692](https://peps.python.org/pep-0692), you type `**kwargs` as the `typing.Unpack` of a `typing.TypedDict` subclass that you define just to unambiguously constrain the types of the values of all excess keyword arguments: e.g., ```python # This is still trash -- merely a different and larger kind of trash. from typing import TypedDict, Unpack class _GodsThisIsTrashy(TypedDict): ''' You didn' see nuffin' except 500 lines of boilerplate that burn the eyes. ''' hear_nuffin: int see_nuffin: str def fugly_muffin(**kwargs: _GodsThisIsTrashy) -> int: ''' Still trashy after all these years. ''' return kwargs['hear_nuffin'] + len(kwargs['see_nuffin']) ``` Even if @beartype supports [PEP 692](https://peps.python.org/pep-0692) by the time you read this, ^{**Spoiler from the sad future:** *...it still doesn't!?*} I'd still personally opt for the `@beartype`-friendly `def fugly_muffin(**kwargs: int | str):` approach. Sure, it's ambiguous. But it's also a trivial 9 characters rather than 500 lines of sad-faced boilerplate. Consider the number of callables that accept `**kwargs` in your codebase. Are you *really* gonna define one unique `TypedDict` subclass just to unambiguously annotate each `**kwargs` parameter? *Really?* Some of us might think we are. But then we try and fall down clutching our rib cages. The finger-breaking reality of that much boilerplate has broken greater devs than us before. I scoff into my ["Revenge of the Nerds"](https://www.youtube.com/watch?v=kIZH5TKnEeg)-era pocket protector. Annotating variadic keyword arguments may still suck after all these years – but at least @beartype now supports the slightly less sucktastic way. ![](https://media1.tenor.com/m/P_NLDhbe4pAAAAAC/porco-rosso-kurenai-no-buta.gif) ^{*five out of ten men who are pigs support this feature. do you?*} ### Theory Crafting Time: @leycec Spins Fake News Faster Than a Turboprop Let's create a fake PEP and pretend it exists. In other words, this subsection is of no value to anyone whatsoever. Still, unhinged dreams exist for a reason. If I was a CPython `typing` dev, this is the **Mirror World PEP 692** that I personally would have written to trivialize `**kwargs` type hints: ```python from typing import Unpack def fugly_muffin(**kwargs: Unpack['hear_nuffin': int, 'see_nuffin': str]) -> int: return kwargs['hear_nuffin'] + len(kwargs['see_nuffin']) ``` **Trivial.** Right? Just subscript `typing.Unpack[...]` with dictionary-like key-value pairs of the names and types of all excess keyword arguments accepted by that callable. This is already valid Python syntax as shown above. No changes to the CPython [PEG (Parser Expression Grammar)](https://en.wikipedia.org/wiki/Parsing_expression_grammar) or parser are required. This syntax promotes trivial, readable, maintainable, debuggable one-line type hints for `**kwargs`. No extraneous 500-line `TypeDef` subclasses or *whatevah* boilerplate are required. Moreover, this same syntax easily generalizes to `Callable[...]` type hints. Currently, `Callable[...]` type hints fail to support keyword arguments; they only support positional-only parameters. Since nobody uses positional-only arguments, `Callable[...]` type hints are *basically* useless as defined. Instead, `Callable[...]` type hints could be readily extended using the exact same syntactic mechanism to support both keyword and keyword-only arguments: e.g., ```python from collections.abc import Callable # This should, like, totally be the way you annotate callbacks in Python and stuff. def call_back(callback: Callable[['trust_me_bro': int, 'grifter': str], int]) -> int: return callback(trust_me_bro=42, grifter='y u so grifty, Grifty McGrift?') ``` Dictionary-like syntax should *totally* be the standard way to type keyword parameters. We know I mean standardization business, because I just used the word "totally." ![](https://media1.tenor.com/m/lVPZA2-_sLMAAAAd/porco-rosso-anime-film.gif) ^{*man-pig ponders the existential nature of bad standards, as nobody cares*} ## `beartype_all()`: It Actually Works Now, Kinda **Ah, yes.** The [venerable `beartype.claw.beartype_all()` import hook](https://beartype.readthedocs.io/en/latest/api_claw/#beartype.claw.beartype_all). Anybody remember that thing? Me neither. Nobody uses that thing, because that thing blows up whenever you look at it. Let's back up. `beartype_all()` unconditionally type-checks literally *everything*. Whereas `beartype_this_package()` only type-checks your package, `beartype_all()` type-checks both your package *and* everybody else's packages too. ^{**Fake footnote:** Technically, this includes even the standard CPython library. Pragmatically, the standard CPython library contains *no* type hints whatsoever. Why? Because CPython devs hate runtime typing. This fake footnote means nothing. I wasted my time writing this. You wasted your time reading this. We cry tears in the rain together.} It's the "everybody else's packages too" part that is the problem there. Although you expect *your* package to be type-checked with `@beartype`, nobody else does. Nobody expects *their* package to be type-checked with `@beartype` without their permission or knowledge – at least, not until you open 317 pending issues on their issue tracker enumerating every shocking yet mundane "error" in their package when type-checked with `@beartype`. This is why `beartype_all()` fails you when you need it most. You can't control other people's intransigence towards the Bear... **until now.** Introducing the new `BeartypeConf(claw_skip_package_names: Collection[str] = ())` configuration option! `claw_skip_package_names` is a **package name blacklist** (e.g., ban, deny, ignore, or omit list of the names of all packages and modules to be excluded from consideration), enabling you to selectively ignore one or more problematic third-party packages when type-checking the entire Universe via `beartype_all()`. The Universe just got a little smaller and a lot smarter, folks. Because `claw_skip_package_names` is sane: * This blacklist accepts any valid Python collection (e.g., `list`, `tuple`, `set`, *whatevahs*). * The items of this blacklist are the absolute names of any (sub)package or (sub)module you want ignored. This includes both: * Top-level package names (e.g., `'bad_apple'`). * Sub-level module names (e.g., `'lovely_cat.ugly_dog'`). Because reality is even more disappointing than public education prepared us for, the `claw_skip_package_names` "option" is *basically* mandatory. It's not optional despite being called an option. Whenever you call `beartype_all()`, you also need to pass `claw_skip_package_names`: e.g., ```python from beartype import BeartypeConf from beartype.claw import beartype_all # Beartype everything except sucky packages that hate everything good in the world. beartype_all(conf=BeartypeConf(claw_skip_package_names=( 'some_sucky_package', 'another_package_hates_you', 'this_package_is_great.this_submodule_is_trash', ))) ``` `claw_skip_package_names`: *because the Universe is kinda like in the Aliens franchise.* ![](https://media1.tenor.com/m/9OmmPZ4zRSgAAAAC/porco-rosso-plane.gif) ^{*when you fly with @beartype, you fly with a man who is a pig*} ### `beartype_all()` + `pytest-beartype`: They Were Meant for Each Other [`pytest-beartype` plugin users](https://github.com/beartype/pytest-beartype) are now thoughtfully chewing their upper lips and thinking: > What about us!? We deserve better, too. Neglect us and we'll burn this issue tracker down. You do you. That's why `pytest-beartype` maintainer (and all-around Python-[Zig](https://en.wikipedia.org/wiki/Zig_(programming_language)) tooling God) @tusharsadhwani has already implemented support for command-line equivalents of both the `beartype_all()` import hook *and* the `claw_skip_package_names` option. In short, just: ```bash pytest --beartype-packages='*' --beartype-skip-packages='awful_package, horrible.submodule' ``` Let's unpack this. CLI stuff is always so crufty, isn't it? Passing: * `--beartype-packages='*'` instructs `pytest-beartype` to internally call the universal `beartype_all()` import hook rather than the local `beartype_packages()` import hook. *Good.* * `--beartype-skip-packages` blacklists those packages and modules from consideration. *Good.* `--beartype-skip-packages`: *because not all heroes write one-liners.* ![](https://media1.tenor.com/m/hUP_asGYp2sAAAAC/porco-rosso.gif) ^{*sick burn, pig-man. but what does this have to do with @beartype? the answer may shock somebody.*} ## A Deeper Shade of ~~Gray~~ `O(1)` Type-checking @beartype 0.19.0 deeply type-checks a *ton* of fun containers I've loosely dubbed **reiterables.** A reiterable is a collection satisfying the `collections.abc.Collection` protocol with guaranteed `O(1)` read-only access to *only* the first collection item. Reiterables include **sets**, **frozen sets**, **dictionary views**, **deques** (i.e., double-ended queues), and all other containers matched by one or more of the following PEP 484- or 585-compliant type hints: * `frozenset[...]`. * `set[...]`. * `collections.ChainMap[...]`. * `collections.Counter[...]`. * `collections.deque[...]`. * `collections.abc.Collection[...]`. * `collections.abc.ItemsView[...]`. * `collections.abc.KeysView[...]`. * `collections.abc.MutableSet[...]`. * `collections.abc.Set[...]`. * `collections.abc.ValuesView[...]`. * `typing.AbstractSet[...]`. * `typing.ChainMap[...]`. * `typing.Collection[...]`. * `typing.Counter[...]`. * `typing.Deque[...]`. * `typing.FrozenSet[...]`. * `typing.ItemsView[...]`. * `typing.KeysView[...]`. * `typing.MutableSet[...]`. * `typing.Set[...]`. * `typing.ValuesView[...]`. @beartype now deeply type-checks *almost* all of the core PEP 484 and 585 standards, resolving feature request #167 kindly submitted by the perennial brilliant @langfield (...*how I miss that awesome guy!*) several lifetimes ago back when I was probably a wandering vagabond Buddhist monk with a bad attitude, a begging bowl the size of my emaciated torso, and an honestly pretty cool straw hat that glinted dangerously in the firelight. There's still a bit of low-hanging fruit dangling its juicy skin here and there – but not much. The biggest offenders that have yet to be deeply type-checked are: * **`Iterable[...]` type hints.** Not hard, so I claim. Just needs a bit of spit and polish, so I claim. I'm claiming lots of things without hard evidence here. * **Callable type hints** (e.g., `collections.abc.Callable[...]`, `typing.Callable[...]`). Thankfully, BeartypeAI™ now provides a trivial `O(1)` one-liner for deeply type-checking *any* callable type hint `hint` against any arbitrary callable `func`: ```python def is_func_bearable(func: Callable, hint: object) -> bool: return is_subhint(infer_hint(func), hint) # <-- lolbro ``` * **Type variables** (e.g., `typing.TypeVar('T')`. Still no idea how to dynamically generate efficient code type-checking type variables, honestly. It's feasible, but let's avoid thinking about this until there's *absolutely* nothing left to do. :sweat_smile: ...how is to possible that so much and yet so little has changed? Please manage our time better or we're never gonna cross that finish line, GitHub. @leycec assumes no responsibility for just playing video games for a year. @beartype: *It's actually starting to do stuff, now.* ![](https://media1.tenor.com/m/9AoawPQh3p0AAAAC/anime-sad.gif) ^{*if i'm reading these schematics right, @beartype actually does stuff now*} ## PEPs 612 + 646 + 692: @beartype Now Shallowly Loves You! @beartype's love for [PEP 612 – Parameter Specification Variables](https://peps.python.org/pep-0612), [PEPs646 – Variadic Generics](https://peps.python.org/pep-0646/#unpacking-tuple-types), and [PEP 692 – Using TypedDict for more precise `**kwargs` typing](https://peps.python.org/pep-0692) may be a tepid pool of mucky brackish water you can barely dip your toes into – but at least @beartype 0.19.0 tried, *daggumit*. ### PEP 612: Make Your Decorator Closure So Complex It Explodes @beartype 0.19.0 now supports you in your aspirations to obfuscate decorator closures beyond the dark horizon of MIT Python obfuscation competitions by silently ignoring those aspirations: ```python # Guido himself defined a decorator so complex it "logs to a database" # while exploding @beartype with soul-sucking parameter specifications. from typing import Awaitable, Callable, ParamSpec, TypeVar P = ParamSpec("P") R = TypeVar("R") def add_logging(f: Callable[P, R]) -> Callable[P, Awaitable[R]]: async def inner(*args: P.args, **kwargs: P.kwargs) -> R: await log_to_database() return f(*args, **kwargs) return inner ``` @beartype doesn't pretend to understand what `typing.ParamSpec('P').kwargs` means, but @beartype doesn't have to. @beartype is here to crush bugs and play video games... *and @beartype is all outta video games.* ![](https://media1.tenor.com/m/QjBX4FDsb0QAAAAC/porco-rosso-smoking.gif) ^{*that one unforgettable moment when @beartype 0.19.0 reveals its true nature*} ### PEP 692: Finally, `TypedDict` Is Useful for Something @beartype 0.19.0 now supports you in your aspirations to precisely type-check `**kwargs` by silently ignoring those aspirations: ```python from beartype import beartype from typing import TypedDict, Unpack class Kwargs(TypedDict): this_kwarg_must_be_a_string: str this_kwarg_must_be_a_complex_number_just_kidding_its_actually_an_integer: int @beartype def function_accepts_two_kwargs(**kwargs: Unpack[Kwargs]) -> None: ... ``` That's better than @beartype used to do (which was blow chunks everywhere). We don't deeply type-check this yet, but we will. Would @leycec lie!? :sweat: ![](https://media1.tenor.com/m/zynthmbNFvUAAAAC/porco-rosso-kurenai-no-buta.gif) ^{*newer and sleaker @beartype does a surprise fly-by over your codebase. hats are almost lost.*} ### PEP 646: Even Type Variables Are Now Tuples, Huh? It's all tuples all the way down with PEP 646. @beartype 0.19.0 now supports you in your aspirations to precisely type-check... actually, I really have *no* idea. But that's okay, because neither does @beartype 0.19.0. What is PEP 646 besides *really* confusing? Couldn't tell ya. All I know is that @beartype now silently ignores PEP 646-compliant **type variable tuples** (i.e., `typing.TypeVarTuple` objects): ```python from beartype import beartype from typing import TypeVar, TypeVarTuple DType = TypeVar('DType') Shape = TypeVarTuple('Shape') @beartype class Array(Generic[DType, *Shape]): def __abs__(self) -> Array[DType, *Shape]: ... def __add__(self, other: Array[DType, *Shape]) -> Array[DType, *Shape]: ... ``` I kinda get it, but I kinda don't. Since @beartype 0.19.0 doesn't get it any more than I do, @beartype doesn't deeply type-check `TypeVarTuple` objects yet. Will it ever? No idea. Let's pretend: > "Yes! Absolutely! All your dreams will be realized by... @beartype 42.42.42!?" @beartype doesn't even deeply type-check `TypeVar` objects yet – which is the slightly lower-hanging fruit here. Oh, when will free time materialize for @leycec? What has @beartype done to deserve this punishing development schedule? I fear for your immortal `git log`, @beartype. :fearful: ![](https://media1.tenor.com/m/Xb-nV-Ta3qcAAAAC/porco-rosso-laughing.gif) ^{*@beartype 42.42.42 chortles as it contemplates the darkness of the past*} ## Multiprocessing Queues: @beartype No Longer Hates You! @beartype 0.19.0 officially supports the standard `multiprocessing` API for fork-based distributed workloads. All **beartype exceptions** (i.e., exception subclasses published by the `beartype.roar` subpackage) now support pickling and unpickling via the standard `pickle` module, which then suffices to support the standard `multiprocessing` package, which shockingly leverages `pickle` rather than `dill` in 2024. @beartype 0.19.0: *"Why is `pickle` still even a thing!?"* ![](https://media1.tenor.com/m/CIId7ftWp8YAAAAC/romance-stupid.gif) ^{*You're stupid, `multiprocessing`. I hate that in an API.*} ## Third-party Decorators: @beartype No Longer Hates You! @beartype 0.19.0 goes hard on integration with external decorators published by third-party packages that previously hated @beartype. This includes popular Just-in-Time (JIT) decorators for machine learning (ML) like: * `@equinox.filter_jit`. * `@jax.jit`. * `@numba.njit`. @beartype should now support *almost* everybody else's decorators. In fact, @beartype now generically supports *all* **pseudo-callable wrapper objects** (i.e., objects defining both the `__call__()` and `__wrapped__` dunder attributes). The `@beartype` decorator should also now be **context-free.** You may now chain (i.e., list) `@beartype` above *or* below most third-party decorators. Since `beartype.claw` import hooks (like `beartype_this_package()` and `beartype_package()`) inject `@beartype` above all other decorators, `beartype.claw` import hooks now transparently support all other decorators... *probably*. :grimacing: If you previously blacklisted @beartype from type-checking callables decorated by any of the above with `@typing.no_type_check`, let us give thanks as you remove `@typing.no_type_check` everywhere. Examples or it only happened in the DMT hyperplane: ```python from beartype import beartype from jax import ( jit, numpy as jax_numpy, ) from jaxtyping import ( Array, Float, ) @beartype # <-- *GOOD*. @beartype goes last! patiently suffer in silence, @beartype. @jit # <-- *GOOD*. @jax.jit goes first! yoink. def what_would_chat_gpt_do( probably_hallucinate_everything: Float[Array, '']) -> Float[Array, '']: # One-liner: "Do what I say, not what I code." return probably_hallucinate_everything + 1 assert what_would_chat_gpt_do(jax_numpy.array(1.0)) == jax_numpy.array(2.0) what_would_chat_gpt_do('If this is a JAX array, we all have serious problems.') ``` ...which raises the expected type-checking violation: ```python Traceback (most recent call last): File "/home/leycec/tmp/mopy.py", line 22, in what_would_chat_gpt_do('If this is a JAX array, we all have serious problems.') File "<@beartype(PjitFunction.__call__) at 0x7fd9afc96140>", line 29, in __call__ beartype.roar.BeartypeCallHintParamViolation: Object PjitFunction.__call__() parameter probably_hallucinate_everything='If this is a JAX array, we all have serious problems.' violates type hint , as str 'If this is a JAX array, we all have serious problems.' not instance of . ``` The perspicacious user may now be thinking: > "WAIT. What is a `PjitFunction.__call__()`? That's ambiguous and means less than my cat licking itself. Your type-checking violation message sucks, huh?" You're *not* wrong. But we're tired. At least @beartype works now for various definitions of "works." If you just hit this ambiguous type-checking violation message in your workflow and want @beartype to justifiably do something about it, bang on our issue tracker until the cats start squalling and biting @leycec in the face. *Works every time.* **@beartype 0.19.0:** we broke our sanity for your security. ![](https://media1.tenor.com/m/F1080tt022kAAAAC/porco-rosso-studio-ghibli.gif) ^{@beartype 0.19.0: *it's been a long journey, fam.*} ## CPython 3.13: Finally, No Longer Feel Emberassed about CPython @beartype 0.19.0 officially supports **Python 3.13,** the first official CPython release you no longer need to feel ashamed of running in public. Python 3.13 supports [**an official LLVM-based Just-in-Time (JIT) compiler** via the PEP 744-compliant `--enable-experimental-jit` compile-time option](https://peps.python.org/pep-0744). *OMMMMMMMMMMMMMMMMG.....* It's happening. It's really happening. My breathing is now laboured and making awkwardly squishy noises that upset the cat. Python 3.13 also supports [**no-GIL GIL-free multi-threading** via the PEP 703-compliant `--disable-gil` compile-time option](https://peps.python.org/pep-0703). *Yes! YES! YEEEEEEESSSSS!!!!* Wait. Where am I? What are these fingers on this keyboard? This must be what Xanadu is typed of. If I worked on a proprietary Python package, I'd have money. I'd also: * Hard-require `python >=3.13` for production workloads as soon as CPython 3.13 lands in October. * Hand-compile CPython 3.13 with `--enable-experimental-jit` for development workloads. It's time to go fast. Finally, it's time to feel shameless. ![](https://media1.tenor.com/m/9C…

Uh oh!

Switcheroo variables passed to decorator #1

Description

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions