inline stubs from typeshed

[MarcoGorelli]

closes #31

Doing a local install from git

$ uv pip install git+https://github.com/MarcoGorelli/first.git@inline-stubs --no-cache

and then running mypy on a t.py file with

from first import first
first(lambda x: 2)

this immediately gives

$ mypy t.py
t.py:2: error: No overload variant of "first" matches argument type "Callable[[Any], int]"  [call-overload]
t.py:2: note: Possible overload variants:
t.py:2: note:     def [_T] first(iterable: Iterable[_T]) -> _T | None
t.py:2: note:     def [_T, _S] first(iterable: Iterable[_T], default: _S) -> _T | _S
t.py:2: note:     def [_T, _S] first(iterable: Iterable[_T], default: _S, key: Callable[[_T], Any] | None) -> _T | _S
t.py:2: note:     def [_T] first(iterable: Iterable[_T], default: None, key: Callable[[_T], Any] | None) -> _T | None
t.py:2: note:     def [_T] first(iterable: Iterable[_T], *, key: Callable[[_T], Any] | None) -> _T | None
Found 1 error in 1 file (checked 1 source file)

, without needing extra stubs packages to be installed separately

From the typing docs, this brings the following benefits:

We recommend using the inline type annotations approach, since it has the following benefits:

• Typically requires the least effort to add and maintain
• Users don’t have to download additional packages
• Always remains consistent with the implementation
• Allows library authors to type check their own code
• Allows language servers to show users relevant details about the implementation, such as docstrings and default parameter values

I've also verified that

(first-dev) marcogorelli@DESKTOP-U8OKFP3:~/first-dev$ python -m mypy.stubtest first
Success: no issues found in 1 module
(first-dev) marcogorelli@DESKTOP-U8OKFP3:~/first-dev$ mypy first
Success: no issues found in 1 source file

pass fine, though there seems to be no github actions workflow to add this to? should i add one?