Add Typing via stub file

[dimitrivinet]

I discovered picows recently and have been really impressed with the speed.

I believe type hints are currently missing for this librairy. I think they could be useful to add, to provide better linting and documentation, like when hovering in VSCode.

For now I type hinted the public API as exposed in init.py. It is however missing documentation for certain classes like WSTransport.

Let me know if you think it is something you would be willing to add to picows !

Other info:

• all tests pass with Python 3.12 on Windows

[tarasko]

Thank you, it is a nice contribution indeed!

Just a few thing to make it complete. We would have to:

• also copy missing part to pyi. (docs strings for ws_create_server, WSTransport etc)
• switch sphinx doc generation to use pyi files as a source if possible. Currently, it extracts docstrings from the compiled module. Maybe it will automatically extract from pyi. Honestly, I'm not good at it :)
• remove docstrings from picows.pyx, if previous was possible
• make sure that pyi is included into the wheel. Maybe it is automatically included, I don't know.
• add py.typed file

I can do it myself, but perhaps only in a few weeks, very busy with other stuff now. Or you can help and expedite it a bit, I would appreciate.

[dimitrivinet]

Interesting, I will get right on it !

[dimitrivinet]

• I added the py.typed file.
• The stub is indeed included in the wheel.
• According to https://typing.readthedocs.io/en/latest/spec/distributing.html and https://typing.readthedocs.io/en/latest/guides/writing_stubs.html, docstrings should not be included in stubs, which I didn't know before.
• I can add flake8-pyi to lint the stub and add it to the linting workflow, if that is something you are interested in.

There is still an issue of not being able to read the docstrings in the IDE when hovering. I am looking at examples of other C extensions. However, maybe it is not necessary since the docs are available online ?

[dimitrivinet]

For example:

diff --git a/.github/workflows/run-tests.yml b/.github/workflows/run-tests.yml
index c17be37..a5c4150 100644
--- a/.github/workflows/run-tests.yml
+++ b/.github/workflows/run-tests.yml
@@ -26,13 +26,14 @@ jobs:
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
-        pip install setuptools Cython flake8
+        pip install setuptools Cython flake8 flake8-pyi
     - name: Lint with flake8
       run: |
         # stop the build if there are Python syntax errors or undefined names
         flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
         # exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide
-        flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
+        flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 \
+          --per-file-ignores='*.pyi:B,E301,E302,E305,E501,E701,E704,W503' --statistics
 
   build:
     strategy: