In order to be able to eventually retire trio-typing (see https://github.com/python-trio/trio-typing), track progress on #543 (and once type complete, make sure that we stay that way) and as a minor bonus give a check on docstrings, I suggest adding
pyright --verifytypes to the checks in CI, that at a beginning is required only to go up from current state, and when we've achieved 100% type completeness will then require not dropping below that.
See #2623 where I reinvented the wheel in a quite clunky way and some discussion around it, https://github.com/microsoft/pyright/blob/main/docs/typed-libraries.md#type-completeness for the definition of type completeness, and https://github.com/microsoft/pyright/blob/main/docs/typed-libraries.md#verifying-type-completeness for documentation on --verifytypes.

There's unfortunately a couple blockers before we're able to use it.

1. Imports in __init_.py, socket.py, abc.py, from_thread.py, lowlevel.py, socket.py and to_thread.py are not visible to --verifytypes. Also related to Use less magic in constructing our public API exports, to make trio more intelligible to static analysis #542
   • See https://github.com/microsoft/pyright/blob/main/docs/typed-libraries.md#library-interface for official docs on why this is the case, and verifytypes does not include imports from underscored modules microsoft/pyright#4869 for a quick explainer
   • I can come up with the following alternatives:
     1. Define __all__, see discussion in Simplify imports #594 (comment)
     2. Change the imports to from X import A as A - a bit verbose, but simple
     3. Change the imports to from X import * - I'm not sure if we're currently exporting everything, so this might expose more symbols unless they are/get named with a leading underscore.
     4. Overhaul the current file structure, creating subdirectories with their own __init__'s for the different submodules, and remove leading underscores from file names. (this has likely been discussed in Use less magic in constructing our public API exports, to make trio more intelligible to static analysis #542 and other places and there's presumably some decent logic for the current layout?).
2. trio.tests is a public module and is included as a submodule that needs verifying. See Fix our test layout #274, suggestions there include renaming trio/tests to trio/_tests, moving it out to a separate top-level tests/, or removing trio/tests/__init__.py.
3. How to actually check that the type completeness score doesn't go down.
   • A relatively straightforward solution would be to use --outputjson and dump the results in a _type_completeness.json, which in check.sh is parsed for the % and the individual values, then regenerated on the new code and reparsed, and finally compare the individual values so none of them are dropping (other than the number of symbols exported, or the number of symbols exported with known type.) This'd be a quick&dirty python/shell script, and can make it take a command-line flag whether to overwrite the file or not (that is set in CI, but otherwise not) so it can be used locally repeatedly when developing.

Ticking all these boxes is definitely gonna take a while and bunch of discussion, so I don't personally consider it completely out of the question to use #2623 in the meanwhile - but a better solution would probably be a dirty script that does something like

1. copy the contents of trio/ to a separate directory
2. run a replace on __init__.py and friends to change all the imports to from X import A as A
3. remove/rename the trio/tests/ directory

This can then be retired/simplified as 1&2 are fixed.

@A5rocks @Fuyukai @Zac-HD @njsmith