A few thoughts.

First, on guided annotations. For non-main files, that don't have an intended execution behavior (or those that do, once imported), a series of beartype hooks / flags within the file could provided granular direction. For example, inferring the entire file, inferring all usages of certain variables everywhere, inferring certain functions, doing those operations only to function definitions, and/or doing it to variable definitions within functions, omitting annotating when clearly defined by an assignment from a known type, or passed into a well-typed function, etc. And whence done, removes those annotations. No cli required.
find . -name '*.py' -type f -execdir python -c 'import {}'\; |& less

As for the quality of the generated types themselves, I suspect most would prefer semantic aliases of longer things, for sanity's sake. Ex, when encountering a type hint or a variable name with a gnarly hint for the first time, prompting for the user for a shorthand would clear these up. Like with git rerere, these responses can be cached for all the subsequent imports, which should sanely propagate type hints throughout the dependency chain (especially if the inference started with a main executable root, which then recursively imports all its dependencies, automatically, as normal). (Or searches the import for an already defined shorthand for that said type)

Ex: type WeirdoCustomList_T = typing.Annotated[collections.abc.MutableSequence[str], IsInstance[WeirdoCustomList]]
. And every other numpy/validating generated type that was in the release notes.

Lastly, in git we trust. If performing operations on the host pc is still too tenuous, then all of this modification could be done in-memory, the imported files stored in memory, and then only dump/print() the patch file with the diff, leaving it to the user to apply said patch file, and handle the likes/dislikes appropriately.

...heh. I've created a nightmare. In so many words, this is what you are saying, @JWCS.

Help! Somebody help! Save me from the feature creep horrors I have unwittingly unleashed on us all! I was trying to have fun and now I've created a shambolic megalith of empty hopes and shattered dreams resembling git rerere that's suddenly prompting for user responses, inferring the directed graph of all possible runtime type hints, exploding with dozens of different hooks and configuration options, and just generally acting like a crazy bear freshly awakened from the hibernal dream state in early Spring and ready to gnaw something's face off.

I agree with what you are saying, @JWCS. Somebody should do all of those things. Let us please acknowledge the bitter reality, however: that somebody will probably not be @leycec. I haven't even finished deep O(1) type-checking of core type hints first standardized by Guido's PEP 484 a decade ago. Gods! How is it that PEP 484 is actually a decade old? It all seems so new and fresh. Yet, a decade passed in the blink of a keyboard.

It's been years of blood-curdling @beartype development at this point. @beartype is still nowhere close to being where we all expected @beartype to be. Dynamic code generation is rough stuff, indeed. I guess that's why only @beartype does that stuff, huh? Emoji face sighs. 😮‍💨

Thankfully, I've been thinking. It's weird but stay with me. @leycec thinks for once. And what I'm thinking is... everything @thiswillbeyourgithub, @JWCS, and probably everybody else wants here is probably best achieved in some new third-party package that lives outside @beartype. I'm thinking of a Plum-style arrangement, where:

• Somebody who is admittedly not @leycec writes and maintains all of this awesome sauce for me.
• @leycec adds that third-party package to the @beartype organization and graciously helps that somebody out in any way – just so long as "in any way" doesn't actually mean "by writing any code." 😂

Hi everyone, sorry for the time I took to answer.

TL;DR

We all three (@JWCS and @leycec) seem to have come to the same conclusion: modifying the source code brings a lot of questions whereas simply writing a txt file containing a record of all the types hints for each function (and organised such that each function is described only once in the dump of course) would be amazingly useful while remaining seemingly doable.

I have too much time:

Import hooks aren't really composable in Python

Didn't know that, thanks!

You'd need to be very certain that your package is 100% bug-free. If your package is even a little buggy, type hint inference will permissively infer incorrect type hints for your package without your knowledge.

I disagree. So far a type hint in python means "the developper says that thing should be of this type". But the idea I'm suggesting allows to reverse this: the actual run encountered this type. This is new because AFAWK nobody has yet done something that infers type as the code runs then writes it to the file. So you don't need the code to be bugfree, as you can use this to debug your code.

Frequently, I have to read someone else's code and it's bad, has bad variable names, bad comments, and especially: it lacks type hints. This makes it even harder to figure out what exactly is going on in some parts of the code. What I'm suggesting could solve this: just run the code and then you have descriptive typehints that make it easier to figure out what's going on.

Those incorrect type hints will then be permanently "patched" into your package, permanently installing a state of buginess into your package. You're now thinking: "Ah-ha! That's not true. Nothing is permanent. I'll just fix up those bugs at some later date. Got no time now, of course." To which I reply: "That's nice, dear." Snarky response, but it's true. It's already too late. Your codebase is dead. You inferred type hints back when your package was buggy. Those type hints are now buggy. You "patched" those buggy type hints all over package.

Apart from using git, this can be solved by adding a comment after the hint, like Bearhint. Actually instead of adding hints if the idea is just to make the code more readable by adding descriptive hints then they can just be comments instead of actual type hints.

Users would need an API to "finalize" the type hint inference process. At some point, @beartype needs to stop inferring type hints and actually do something productive with those type hints. If @beartype never stops inferring type hints, then literally any object would eventually be seen as valid. But how do you "finalize" the type hint inference process in a thread-safe manner that integrates cleanly with both standard importlib machinery and type-checking wrapper functions already generated by @beartype? You... kinda just don't.

I was thinking python -m bearhint my_script.py my args and --keyword=wargs. But an unorthodox way could be just to have a two step run:

1. Run bearhint from your codebase, at the end of the execution it creates a bearhints.py
2. Run something like python -m bearhint --apply bearhints.py my_codebase

What does "patching" your package with inferred type hints even mean? Do you really trust some fast-and-loose unpaid volunteer hobby project with a name like "beartype" authored by a Canadian neckbeard with no neck and maximum beard to physically modify all of the .py files in your on-disk package by somehow globally injecting inferred type hints into those files?

First of all you seem nice :). But yeah a solution for this is to just add comments instead of hardcording the hints.

Actually I usable product would be simply a package bearhint that creates a sort of text file where each function called has its input and output hints written. That would bring a lot of value and be a solution for my use case without running into the issues of how bad it could be to hardcode values in the actual source code.

The solution to 1. and 2. above is clear: define a new BeartypeConf(claw_is_infer_hints=True) configuration option. When enabled, @beartype will dynamically generate additional runtime logic in type-checking wrapper function to infer type hints for passed and returned objects that lack existing type hints. In other words, we piggy-back type hint inference onto the existing beartype.claw import hook infrastructure by just adding a new configuration option. So far, so good.

Yeah and just add an output file to store it and it would already be amazing.

Really easy sounds preferable, right? The Really Easy Way is for @beartype to just print out or log all inferred type hints.

In light of the above, would @beartype just printing out or logging all inferred type hints satisfy your use case? Would world-shattering scientists such as yourself be equally satisfied or would everybody riot and burn down the @beartype issue tracker? Does everybody trust @beartype to try patching their packages with inferred type hints, despite the high likelihood that doing so would destroy their packages forever?

We came to the same conclusion, hurray!