[Documentation] Document how to @beartype other people's code

[leycec]

Via the ultimate power of aspect-oriented programming, mega-mind @amogorkon's third-party justuse package proposes to let anyone dynamically @beartype anyone else's well-typed code without their consent or knowledge.

Behold! numpy maintainers will never voluntarily @beartype their codebase, so we quietly force the issue by externally @beartype-ing their entire codebase for them via a mysterious one-liner that we only pretend to understand. This...

import use
from beartype import beartype
np = use("numpy")
np @ beartype

...generates a Brython-fueled HTML dry run of what would happen if we actually did this.
justuse ➕ beartype just went there. Someone had to.

Let's document how to make this grim magic happen.

Relatedly...

This issue is comparable to a popular pending feature request for automagical import hooks. Both justuse and the import hooks we'll eventually bundle with @beartype will enable anyone to universally apply @beartype to an arbitrary package without manually decorating all callables and classes in that package under the @beartype decorator.

The similarities end there, though. Since justuse non-destructively generates an in-memory proxy object wrapping the underlying module(s) with aspect-oriented @beartype-ing, justuse preserves the underlying module(s) as is. Conversely, since our import hooks will directly modify the underlying module(s) with abstract syntax tree (AST) manipulations, our import hooks do not preserve the underlying module(s) as is.

The use cases then become clear, maybe:

• Use justuse to @beartype other people's code. If it's not under your direct control, use justuse to avoid breaking other people's use of other people's code.
• Use our import hooks to @beartype your people's code. If it's under your direct control, use our import hooks to preserve standard Python import semantics. You don't want to import your own code through an in-memory proxy object; you just want to import your own code as you always do, because you do you.

Thus spake @leycec as if he knew what he was spaking about. Sadly, he's just babbling again. 🙊

[amogorkon]

blush I just hope it'll be useful and doesn't break down at first opportunity, that would be embarassing >_>
But alas, my unit tests are green, so I'm hopeful 😁