Q: Can @beartype check annotated variable assignments like foo: list[str] = [42, 24]? A: Nopers. beartype_this_package(), instead. Never @beartype. Just never.

[reikdas]

Shouldn't the following raise an error?

from typing import Annotated
from annotated_types import Gt
from beartype import beartype
from beartype.vale import Is

@beartype
def main():
    foo: list[Annotated[int, Is[Gt(0)]]] = [-1, 0, 10]
    print(foo)

main()

When executing the program, it runs without errors.

[leycec]

Excellent question! The tl;dr (i.e., short answer) is that you probably want to do this instead:

# In the "{your_package}.__init__" submodule:
from beartype.claw import beartype_this_package
beartype_this_package()

And then...

# In the "{your_package}.__main__" submodule (or whatevahs):
from typing import Annotated
from annotated_types import Gt
from beartype.vale import Is

def main():
    foo: list[Annotated[int, Is[Gt(0)]]] = [-1, 0, 10]
    print(foo)

main()

You should now receive joy. You may also be thinking to yourself:

"This is balls. I hate this. What is happening here?"

Boring Stuff Follows: It Is Boring

Allow me to now boringly explicate.

foo: list[Annotated[int, Is[Gt(0)]]] = [-1, 0, 10] is a PEP 526-compliant annotated variable assignment. For both space and time efficiency, CPython itself silently strips (i.e., removes) all type hints from all annotated variable assignments at early parsing time. The @beartype decorator runs after the CPython parser. By the time @beartype runs, CPython has already stripped those type hints. @beartype never even gets a chance to see those type hints.

From the perspective of @beartype, your original code is literally identical to this:

from beartype import beartype

@beartype
def main():
    foo = [-1, 0, 10]
    print(foo)

main()

Note the complete absence of type hints. Blame CPython. I always do. You may now be thinking to yourself:

"B-b-but... how does beartype_this_package() do this, if this is so impossible, wise bear guy?"

More Boring Stuff: Boring Stuff Intensifies

beartype_this_package() is an import hook. Like most import hooks (including pytest itself), beartype_this_package() works by quietly installing an abstract syntax tree (AST) transformation. CPython runs this transformation during its early parser phase before stripping the type hints from annotated variable assignments.

beartype_this_package() thus sees those type hints and responds accordingly.

tl;dr: That Was Sure Boring

Always beartype_this_package(). The @beartype decorator is legacy. While you can still manually decorate callables and classes with @beartype, doing so is increasingly unsupported and likely to fail in a growing laundry list of edge cases – including annotated variable assignments.

As these sorts of issues continue to arise and bedevil us, we might even officially deprecate the @beartype decorator at some point. ^{Oh, Gods! No! No! Gods, why!!!!} 😱

[reikdas]

Might not be very relevant to the same issue, but I have a question related to the this code:

Directory structure -

➜  src tree
.
├── eg
│   ├── __init__.py
│   ├── __pycache__
│   │   ├── __init__.cpython-311.pyc
│   │   └── main.cpython-311.opt-beartype0v16v4.pyc
│   └── main.py
└── try.py

3 directories, 5 files

eg/init.py:

➜  src cat eg/__init__.py
from beartype.claw import beartype_this_package
beartype_this_package()

eg/main.py:

➜  src cat eg/main.py
from typing import Annotated
from annotated_types import Gt
from beartype.vale import Is

def main():
    foo: list[Annotated[int, Is[Gt(0)]]] = [20, 10]
    print(foo)

try.py:

from eg import main

main.main()

When I try and execute try.py I get the error:

Traceback (most recent call last):
  File "/Users/das160/pytype/src/try.py", line 1, in <module>
    from eg import main
  File "/Users/das160/pytype/src/eg/main.py", line 9, in <module>
    main.main()
  File "/Users/das160/pytype/src/eg/main.py", line 6, in main
    foo: list[Annotated[int, Is[Gt(0)]]] = [20, 10]
                             ~~^^^^^^^
  File "/usr/local/lib/python3.11/site-packages/beartype/vale/_is/_valeis.py", line 332, in __getitem__
    die_unless_validator_tester(is_valid)
  File "/usr/local/lib/python3.11/site-packages/beartype/vale/_util/_valeutilfunc.py", line 46, in die_unless_validator_tester
    die_unless_func_args_len_flexible_equal(
  File "/usr/local/lib/python3.11/site-packages/beartype/_util/func/arg/utilfuncargtest.py", line 90, in die_unless_func_args_len_flexible_equal
    func_args_len_flexible_actual = get_func_args_flexible_len(
                                    ^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.11/site-packages/beartype/_util/func/arg/utilfuncargget.py", line 123, in get_func_args_flexible_len
    func_codeobj = get_func_codeobj(
                   ^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.11/site-packages/beartype/_util/func/utilfunccodeobj.py", line 128, in get_func_codeobj
    die_unless_func_python(func=func, exception_cls=exception_cls)
  File "/usr/local/lib/python3.11/site-packages/beartype/_util/func/utilfunctest.py", line 106, in die_unless_func_python
    raise exception_cls(f'{exception_prefix}{repr(func)} not callable.')
beartype.roar.BeartypeValeSubscriptionException: Gt(gt=0) not callable.

Is this because Gt(0) isn't supported by beartype?

[leycec]

Excellent question! I'm... unsure, actually. Your exception traceback is missing the actual exception message. It's unclear what's going on there, really. That said, if @beartype does not already support the third-party annotated_types package out-of-the-box, @beartype can and probably should be made to do so.

Likewise, beartype should probably also provide equivalent beartype.vale.Is* validators to those provided by annotated_types. Ideally, third-party packages shouldn't even be needed to validate trivial constraints like bounds checks on numeric scalars. There's alot of low-hanging fruit to be plucked here. Let us pluck that fruit as fructose dribbles down our chins.

Potential new beartype validators include:

• beartype.vale.IsGreater[maximum: typing.Any], an arbitrary non-inclusive maximum constraint to be applied to an arbitrary object.
• beartype.vale.IsLess[minimum: typing.Any], an arbitrary non-inclusive minimum constraint to be applied to an arbitrary object.
• beartype.vale.IsGreaterOrEquals[maximum: typing.Any], likewise for inclusivity.
• beartype.vale.IsLessOrEquals[minimum: typing.Any], likewise for inclusivity.

There are heaps more, too. But those above would be a great start. Deep thoughts for Christmas time. ☃️ ❄️

[reikdas]

Your exception traceback is missing the actual exception message

Oops, I don't know why I had only half the message on my clipboard. Updated the message with the full error message.

Thanks for the quick reply!!

[leycec]

Ah... ha. Thanks so much for that full traceback. Looks like annotated_types "type hints" aren't actually type hints but non-standard objects that aren't even callable. Well, that's not exactly great.

Thankfully, you don't even need annotated_types! That's right. Just ditch that noise for beartype validators – the builtin API that already supports everything you want to do out-of-the-box. Drop annotated_types like the lead sack full of rotten potatoes it is:

from typing import Annotated
from beartype.vale import Is

def main():
    foo: list[Annotated[int, Is[lambda number: number > 0]]] = [-1, 0, 10]  # <-- srsly. that's it.
    print(foo)

main()

Srsly. That's it. Do Is[lambda number: number > 0] instead of Is[Gt(0)]. Sure, beartype validators are a little bit more verbose than annotated_types objects – but that's a good thing. They're Pythonic; they're explicit; they're debuggable, intelligible, and readable; they reduce your dependency on fragile third-party black boxes; most importantly, they actually work.

Really! Believe my lies. 😉