Wonderful user @taranlu-houzz highlighted at discussion thread #434 that beartype.claw import hooks probably fail to support namespace packages.

Actually, it's currently unknown whether beartype.claw import hooks support namespace packages or not. Since @taranlu-houzz stumbled into a Pit Of Doom™ when attempting to apply beartype.claw import hooks to a deeply nested namespace packaging structure, we can infer that beartype.claw import hooks indeed do not support namespace packages.

At the least, our test suite needs to explicitly test beartype.claw import hooks against a deeply nested namespace packaging structure. At the most (i.e., if those tests fail), beartype.claw import hooks need to be generalized to support namespace packages. However...

...I Can Feel a Storm A-comin'

Namespace packaging is really non-trivial. Usually, that's not an issue. In the case of import hooks, though, that's an issue. All import hooks (including those published through the beartype.claw API) are implemented in terms of importlib machinery. importlib is the extremely low-level esoteric standard CPython API that governs import statements. importlib is incredibly obtuse and difficult to fully "grok." I am convinced that no one (including Guido himself) fully appreciates or understands the modern post-Python 3.3 implementation of importlib.

Namespace packages are fundamentally different from standard packages. Thus, so is their importation. Thus, so is their implementation via the importlib API. Thus, so is their usage from import hooks like beartype.claw. The way that beartype.claw "hooks" namespace packages probably needs to fundamentally differ from the way that beartype.claw "hooks" standard packages. I weep openly.

In other words, beartype.claw needs explicit support for namespace packages. In the absence of explicit support, it is unsurprising that beartype.claw fails to support namespace packages. After all, if you never test something, that thing is almost certainly broken. I am shocked cat.

^{@leycec is shocked cat.}

...I Don't Like What I See in CPython Issues, Either

There are many suspicious CPython issues intersecting import hooks + namespace packages – like python/cpython#76978, python/cpython#78125, and python/cpython#92054. The discussions that ensue between mostly CPython devs get intense, insane, and more intellectually convoluted than Alexander the Great hacking on a Gordian knot.

What I'm trying (but failing) to say is:

"This might take a hot minute to resolve. In fact, this might take a hot year."

I don't know if any existing third-party import hooks support namespace packages. Can this be done? Probably. Has anyone else done this? Possibly not. Does anyone else even want to try doing this? Definitely not.

Still, this is high-priority stuff. Namespace packages should "just work" out-of-the-box with beartype.claw. If they don't, that's our fault – and we must fix that. I sigh, fam. I sigh so hard. 😮‍💨