feat: typing support for helpers

[henryiii]

Description

The goal here is to enable external typing support, so users can type check code containing pybind11 calls (just the import pybind11, not something magical with compiled extensions)! It is also checked internally with mypy, as well, integrated into the pre-commit checks.

However, it did expose a small logical issue when checked internally; sysconfig.get_path logically is not required to return a string, so we could be adding None's to the path. Fixed by only adding truthy strings.

If this is too large to go into 2.6.0, we can go with #2589 instead.

Suggested changelog entry:

- Added external typing support to the helper module, code from ``import pybind11`` can now be type checked.

[YannickJadoul]

As far as I'm concerned this is not too big or too extensive to still add to 2.6.0. But neither would I expect it's very urgent (do people actually add typing to their setup.py?).

[henryiii]

It doesn't really touch real code (save for the one mentioned change), just adds supporting files mostly, so I rather think it's fine too.

do people actually add typing to their setup.py?

Given how poor support for typing is in typeshed for distutils (build_ext was missing), I wouldn't expect so. But that could/should change? And, besides, many people use PyCharm (myself included once in a while), and this will just start helping them work with our tools immediately. :)

neither would I expect it's very urgent

Nope, which is why I didn't get around to it until now. (Plus it's best to add a pyi file after the py file is mostly stable).

[YannickJadoul]

And, besides, many people use PyCharm (myself included once in a while), and this will just start helping them work with our tools immediately. :)

Ah yes, if it helps, why not. This one CI job keeps the .pyi in sync with the actual code, right? Will it complain if there's a new function added, for example?

[henryiii]

It should complain if you add a function that has no type info (the --strict parameter). If you lie about types(*), this is also caught by the internal type checking (external entities only see the .pyi when type checking code against us, if there is one with the same name). The reason to use .pyi over type comments is to avoid importing typing and added a dependency pre-3.5; if it was possible to not add a .pyi, I did avoid it.

*: Lying defined as making a type statement that does not satisfy the code type check. You may lie about inner details, inheritance, skip non public methods, etc, and that's not lying in this sense.

[rwgk]

I think this is fine to include in 2.6.0.