Ah! Got it. Thanks so much for the detailed example. Given that, it should be no trouble whatsoever for @beartype to officially support typer. I'll just need a spare moment of free time and... that's never gonna happen, is it!?

Maybe not. I really hope it does, though! typer is nifty. Nifty packages deserve our support. So, I've converted your awesome commentary into a new feature request #436.

What Can Be Done Until @leycec Does Something, Though?

Thankfully, you don't have to wait for @leycec to finally do something. Instead, just tell @beartype that it should ignore all @APP.command()-decorated callables like so:

from typing import no_type_check

@APP.command()
@no_type_check
def sync(
    targets: list[int] = typer.Argument(
        ...,
        metavar="PID [PID [...]]",
        help="Target PIDs to sync tile data for.",
    ),
    submit_change: bool = typer.Option(
        False,
        rich_help_panel="Perforce Options",
        help="Whether or not to submit the changelist with the downloaded tile data (if any).",
    ),
) -> None:
    ...

Like all runtime type-checkers (e.g., typeguard) and static type-checkers (e.g., mypy, pyright), @beartype silently ignores all callables and classes decorated by the standard @typing.no_type_check decorator. Since typer kinda violates PEP standards, ^...sad! it's helpful to notify type-checkers that they should ignore typer-based callables.

Decorating typer-based callables with @typing.no_type_check then allows you to use the convenient beartype.claw.beartype_this_package() import hook to globally runtime type-check your entire package. This is how the QA was won.

@beartype + typer: soon to be a match made in CLI heaven. 👼

Gah! Sadly...

Is there a way to verify what hooks were registered and what functions/modules are affected?

Tragically, no such public API exists at the moment. This is the first case in which beartype.claw isn't doing what someone tells beartype.claw to do – to my knowledge, anyway. Clearly, this calls for a change. Let's open up a new feature request tracking this extremely useful feature request.

Superficially, it looks like you're doing everything right...

WAIT. I Stupidly Glossed Over Your Comment Earlier!

I feel growing fear for your code, @taranlu-houzz:

I actually tend to try to keep the empty __init__.py modules out of my projects unless absolutely necessary, so the structure I have you is actually how my project is (e.g. no __init__.py for the internal _private dir).

Ho, ho, ho. You're now swimming with sharks in dangerous waters. I see that you like to live fast and loose. I also understand your totally valid concerns. From the post-modern 2024 perspective, empty __init__.py modules seem really weird, superfluous, and an archaic holdover from the violent medieval era of Python 2.7. You are now thinking: "Who needs those silly things anyway?"

Sadly, the answer is: "Everybody. Everybody needs those silly things." None of us like empty __init__.py modules, but we all still need those silly things. Empty __init__.py modules are absolutely required at all packaging levels throughout every single subdirectory of your package. This means that your package structure really does need to resemble:

.
├── src
│  └── A
│     ├── __init__.py
│     └── B
│        ├── __init__.py
│        └── C
│           ├── __init__.py
│           └── D
│              ├── __init__.py
│              └── _private
│                 ├── __init__.py
│                 ├── exceptions.py
│                 ├── lib.py
│                 └── logging.py
├── pyproject.toml
└── uv.lock

Love that ASCII art, by the way. So h0t! 😍

But Why Do I Need Those Awful Empty __init__.py Modules? WHY!?!?

...heh. I feel you. The reason is simple. Actually, the reason is complex.

Python implicitly treats any package subdirectory lacking an __init__.py module as an "implicit namespace package." If you don't know exactly what an "implicit namespace package" is, you definitely shouldn't be creating them – which means you really shouldn't be omitting __init__.py modules. Implicit namespace packages are fundamentally dangerous. They're not something you want to do unless you really know that you need to do that thing, despite the shark-infested waters.

Implicit namespace packages create a heap of trouble for everybody in the Python space. They're actually quite rare. I've only ever encountered a single open-source namespace package in the wild: ruamel.yaml, Python's best YAML (and thus JSON) parser by a wide margin. The ruamel in ruamel.yaml is a namespace package; meanwhile, the yaml in ruamel.yaml is a normal non-namespace subpackage.

As far as I know, static type-checkers like mypy and pyright still have difficulty with implicit namespace packages. Most Python tools and IDEs do. They're weird; they don't import or behave correctly; they're not "real" packages in the normal sense of "real."

But... maybe you do intentionally want your A, A.B, A.B.C, and A.B.C.D folders to all be treated as implicit namespace packages? This would be the case if, for example, the funding for your package is governed by an A organization with a B suborganization and so on – and all of these organizations publish a variety of Python packages controlled by different teams and devs. But... yeah. That's probably not the case. Is it? No idea. I'm just a bald dude on GitHub. 🤣

What Do Namespace Packages Have to Do with Import Hooks?

No idea. I don't think anyone's attempted to apply @beartype import hooks to namespace packages before. You're the first – and it doesn't seem to be going well. It's possible that namespace packages aren't hookable by name. Maybe? Seems plausible. Namespace packages are weird. Unfortunately, I never tested that. Awkward moment, huh? In my defence, namespace packages are so rare "in the wild" that I never expected anyone to actually create one – let alone apply @beartype to one.

Guess I should've probably tested that. 😮‍💨

One Last Idea: Does beartype_this_package() + @no_type_check Work?

As a last-ditch desperate idea, would you mind trying to:

• Additionally decorate all of your typer-specific callables with @typing.no_type_check?
• Replacing that call to beartype_package(f"{__package__}.lib") with just beartype_this_package()? This should always work: e.g.,

# In your "A.B.C.D._private.__init__" submodule:
from beartype.claw import beartype_this_package
beartype_this_package()

If even that fails, there is a secret print() statement in the @beartype codebase that debugs exactly what you want to debug. Sadly, it's commented out; you'll have to manually uncomment it. The print() statement in question lives in the beartype/claw/_importlib/_clawimpload.py submodule. Just:

# In the "beartype/claw/_importlib/_clawimpload.py" submodule,
# replace this commented-out code black:
        #FIXME: Conditionally perform this logic if "conf.is_debug", please.
        #Note that printing to "stderr" is pivotal. For some reason, Python
        #fails to forward printing to "stdout" across subprocesses even when we
        #explicitly tell it to. Look. I don't even know. Just roll with it!
        # from sys import stderr
        # print(
        #     (
        #         f'Module "{self._module_name_beartype}" abstract syntax tree (AST) '
        #         f'transformed by @beartype to:\n\n'
        #         f'{get_node_repr_indented(module_ast_beartyped)}'
        #     ),
        #     file=stderr,
        # )

# ...with this uncommented code block:
        from sys import stderr
        print(
            (
                f'Module "{self._module_name_beartype}" abstract syntax tree (AST) '
                f'transformed by @beartype to:\n\n'
                f'{get_node_repr_indented(module_ast_beartyped)}'
            ),
            file=stderr,
        )

So sorry about that! We really do need that new BeartypeConf(claw_is_trace_imports) option. 😢

I did try using @typing.no_type_check and it unfortunately did not work (at least, as far as preventing beartype from triggering goes).

Madness continues, huh? My tired face is tired, fam. 😮‍💨

It also seems like it would prevent mypy from checking those functions, which isn't quite ideal.

...heh. You noticed even that, huh? Nothing slips past @taranlu-houzz. I didn't want to muddy the waters any further, but the @beartype API does actually provide a @beartype-specific means of selectively blacklisting (i.e., ignoring) undesirable callables and classes: the O(0) type-checking strategy, meaning "do literally nothing by silently reducing to a noop, @beartype." Here's what that looks like for this specific use case:

from beartype import beartype, BeartypeConf, BeartypeStrategy

# "beartype.claw" import hooks will now ignore this sync() function. Yay!
@APP.command()
@beartype(conf=BeartypeConf(strategy=BeartypeStrategy.O0))
def sync(
    targets: list[int] = typer.Argument(
        ...,
        metavar="PID [PID [...]]",
        help="Target PIDs to sync tile data for.",
    ),
    submit_change: bool = typer.Option(
        False,
        rich_help_panel="Perforce Options",
        help="Whether or not to submit the changelist with the downloaded tile data (if any).",
    ),
) -> None:
    ...

If you get exhausted of copy-pasting @beartype(conf=BeartypeConf(strategy=BeartypeStrategy.O0)) everywhere, consider aliasing that to a private global ala:

from beartype import beartype, BeartypeConf, BeartypeStrategy

_no_beartype = beartype(conf=BeartypeConf(strategy=BeartypeStrategy.O0))
'''
:func:`beartype.beartype` decorator configured to do absolutely nuffin'.
'''

@APP.command()
@_no_beartype
def sync(
    targets: list[int] = typer.Argument(
        ...,
        metavar="PID [PID [...]]",
        help="Target PIDs to sync tile data for.",
    ),
    submit_change: bool = typer.Option(
        False,
        rich_help_panel="Perforce Options",
        help="Whether or not to submit the changelist with the downloaded tile data (if any).",
    ),
) -> None:
    ...

If that still doesn't work, I will eat my priceless Tilly hat live on GitHub. 👒 😋

...but the error message that it logs gets messed up by the pretty exception handling that typer does using the rich library. It seems to output the message with rich markup codes embedded:

Ah-ha! Those are Good Ol' ANSI Escape Sequences™ (GOAES), actually. Substrings like [0m and [1m[32m are the telltale giveaway. They were used prominently during the 1980's Bulletin Board System (BBS) craze, but are now just a relic of a long-forgotten age that nobody wants to think about anymore. This is almost certainly an integration issue between @beartype and whatever logging system you're currently using. Fear not! An old bald guy named @leycec will now solve all your problems.

By default, @beartype colourizes type-checking violations (i.e., beartype.roar.BeartypeViolation exceptions) by embedding Good Ol' ANSI Escape Sequences™ (GOAES) in violation messages. Thankfully, you can disable that via a similar mechanism as above: by passing the conf=BeartypeConf parameter to either the @beartype decorator or a beartype.claw import hook.

If you currently prefer the @beartype decorator, I totally get you. One human can only struggle with beartype.claw so much before giving up. In this case, you'll probably want to create your own @beartype decorator uniquely configured for your codebase: e.g.,

# Declare this somewhere useful in your codebase -- like, say, a
# "A.B.C.D._private.util" submodule or something similar.
from beartype import beartype, BeartypeConf

monobeartype = beartype(conf=BeartypeConf(is_color=False))
'''
:func:`beartype.beartype` decorator configured to disable colourization.
'''

Then replace all uses of the standard @beartype decorator throughout your code with this new @monobeartype decorator: e.g.,

# In some other submodule:
from A.B.C.D._private.util import monobeartype

@monobeartype
def awesome_func(so_much_awesome: list[str]) -> int: ...

Unsurprisingly, this is one of many face-palming reasons why the beartype.claw API is dramatically superior – assuming it actually worked, anyway! Rather than having to globally refactor your usage of @beartype (...pretty annoying, in all honesty), you'd just revise your call of a beartype.claw import hook to resemble:

# In some "...__init__" submodule somewhere:
from beartype import beartype, BeartypeConf
from beartype.claw import beartype_this_package
beartype_this_package(conf=BeartypeConf(is_color=False))

Strangely, it now does not error at the section inside the function the way it did when I used beartype.claw to beartype the whole package. Seems like that must be doing something different/deeper?

Ho, ho, ho. Madness intensifies. Indeed, you have discovered the truth: @beartype is a hybrid runtime-static type-checker. This means that @beartype performs both static type-checking (like mypy and pyright) and runtime type-checking (like, uhh, @beartype and typeguard). To minimize false positives and maximize correctness, @beartype prefers to do most of its type-checking at runtime. Unfortunately, some forms of type-checking can only be performed statically. This includes PEP 526-compliant annotated variable assignments like:

# @beartype only type-checks annotated variable assignments like this when
# @beartype is applied via a "beartype.claw" import hook. Sadness and confusion ensues.
some_global: list[str] = [42, 3.14]  # <--- *BUG*

As the above comment suggests, @beartype only performs static type-checking when applied via a beartype.claw import hook. The lower-level @beartype.beartype decorator is incapable of type-checking PEP 526-compliant annotated variable assignments like above; all of those assignments will be silently ignored unless a beartype.claw import hook is run.

I swear this isn't our fault! It's kinda just how Python works. I blame Guido for everything. 🥹