Add stub file for static type checkers

[dlugoschvincent]

Summary

This PR adds first-party PEP 561 type stubs for pycapnp.

It includes stubs for the root capnp package, the Cython extension module, capnp.types, and version information. The py.typed marker and packaging configuration ensure the stubs are included in wheels and source distributions.

Approach

The declarations were audited against the compiled runtime and Cython implementation. The stubs describe existing objects without introducing typing-only classes, generic APIs, inheritance relationships, or modules.

Notable details include:

• capnp.AsyncIoStream correctly represents the public alias of the internal runtime class.
• capnp.types exposes the real built-in schema descriptors.
• Runtime enum and module-like objects retain their actual structure.
• The base which() return type remains schema-agnostic; generated schema stubs can refine it using Literal[...].
• Cython docstrings are included for editor hover documentation.

Validation

The exported names, inheritance, aliases, signatures, and docstrings were checked against runtime objects. The stubs also pass Ruff, Basedpyright, and the pycapnp test suite.

[dlugoschvincent]

Changing to draft as its being finalized.

[haata]

@dlugoschvincent sorry this took me so long to look at. Do you think this is ready now?

[dlugoschvincent]

I think there is still a few issues. I will try to work them out in the coming days and align with my current local version!

[dlugoschvincent]

Alright @haata I think its ready to merge I removed some complexity. Matched the docstrings to the cython functions and improved accuracy across the board. I also added types for the latest additions to the project.

[haata]

One question, is there a good way to identify (or have some sort of unit test) to make sure when new APIs are added or changed that these hints are also updated? Even better if it was some sort of compilation error.

[dlugoschvincent]

Hmm I could add a Test case for that if you want. What do you think?

[dlugoschvincent]

Okay I added a separate test using tox -e stubtest that test if stubs exist and if they are plausible for not explicitly ignored symbols or files.

[dlugoschvincent]

I hope I fixed the issues with the build failures can you rerun the workflow?