Add stub file for static type checkers

MANIFEST.in

@@ -5,6 +5,12 @@ include requirements.txt
 include buildutils/*
 include _custom_build/*
 include capnp/lib/capnp_api.h
+include capnp/__init__.pyi
+include capnp/_internal.pyi
+include capnp/version.pyi
+include capnp/lib/__init__.pyi
+include capnp/lib/capnp.pyi
+include capnp/py.typed
 include Pipfile
 include tox.ini
 recursive-include examples *.capnp

capnp/__init__.pyi

@@ -0,0 +1,102 @@
+from __future__ import annotations
+
+# Import submodules
+from capnp import lib, version
+
+# Import the types module from lib.capnp where it's actually defined
+from capnp.lib.capnp import (
+    # Public classes
+    AsyncIoStream,
+    # Exception classes
+    KjException,
+    SchemaLoader,
+    SchemaParser,
+    TwoPartyClient,
+    TwoPartyServer,
+    # Internal classes and functions that are re-exported
+    _CapabilityClient,
+    _DynamicCapabilityClient,
+    _DynamicListBuilder,
+    _DynamicListReader,
+    _DynamicOrphan,
+    _DynamicResizableListBuilder,
+    _DynamicStructBuilder,
+    _DynamicStructReader,
+    _EventLoop,
+    _init_capnp_api,
+    _InterfaceModule,
+    _ListSchema,
+    _MallocMessageBuilder,
+    _PackedFdMessageReader,
+    _PyCustomMessageBuilder,
+    _StreamFdMessageReader,
+    _StructModule,
+    _write_message_to_fd,
+    _write_packed_message_to_fd,
+    # Public functions
+    add_import_hook,
+    cleanup_global_schema_parser,
+    deregister_all_types,
+    fill_context,
+    kj_loop,
+    load,
+    read_multiple_bytes_packed,
+    register_type,
+    remove_import_hook,
+    run,
+    types,
+    void_task_done_callback,
+)
+
+# Re-export everything from lib.capnp that's part of the public API
+# Version string
+from capnp.version import version as __version__
+
+__all__ = [
+    # Exception class
+    "KjException",
+    # Public classes
+    "AsyncIoStream",
+    "SchemaLoader",
+    "SchemaParser",
+    "TwoPartyClient",
+    "TwoPartyServer",
+    # Public functions
+    "add_import_hook",
+    "cleanup_global_schema_parser",
+    "deregister_all_types",
+    "fill_context",
+    "kj_loop",
+    "load",
+    "read_multiple_bytes_packed",
+    "register_type",
+    "remove_import_hook",
+    "run",
+    "void_task_done_callback",
+    # Modules
+    "lib",
+    "types",
+    "version",
+    # Version string
+    "__version__",
+    # Internal classes that are exposed but prefixed with underscore
+    "_CapabilityClient",
+    "_DynamicCapabilityClient",
+    "_DynamicListBuilder",
+    "_DynamicListReader",
+    "_DynamicOrphan",
+    "_DynamicResizableListBuilder",
+    "_DynamicStructBuilder",
+    "_DynamicStructReader",
+    "_EventLoop",
+    "_InterfaceModule",
+    "_ListSchema",
+    "_MallocMessageBuilder",
+    "_PackedFdMessageReader",
+    "_PyCustomMessageBuilder",
+    "_StreamFdMessageReader",
+    "_StructModule",
+    "_init_capnp_api",
+    "_write_message_to_fd",
+    "_write_packed_message_to_fd",
+]

capnp/_internal.pyi

@@ -0,0 +1,75 @@
+"""Internal types for pycapnp stubs - NOT part of public API.
+
+This module contains internal type definitions including:
+- Protocol classes for schema nodes that exist in the pycapnp runtime
+- TypeVars used in generic types
+- Helper types for type annotations
+
+These are imported by lib/capnp.pyi for type annotations but NOT re-exported.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any, Literal, Protocol, TypeVar
+
+from capnp.lib.capnp import _SchemaType
+
+# TypeVars used throughout the stubs
+T = TypeVar("T")
+T_co = TypeVar("T_co", covariant=True)
+TReader = TypeVar("TReader")
+TBuilder = TypeVar("TBuilder")
+TInterface = TypeVar("TInterface")
+
+# Protocol classes for types imported from capnp runtime
+
+class EnumType(Protocol):
+    typeId: int
+
+class StructType(Protocol):
+    typeId: int
+    brand: Any
+
+class InterfaceType(Protocol):
+    typeId: int
+
+class SlotRuntime(Protocol):
+    type: Any
+
+class SchemaNode(Protocol):
+    id: int
+    scopeId: int
+    displayName: str
+    displayNamePrefixLength: int
+    isGeneric: bool
+    nestedNodes: Any
+    parameters: Any
+    struct: Any
+    enum: Any
+    interface: Any
+    const: Any
+    annotation: Any
+    def which(
+        self,
+    ) -> Literal["interface", "struct", "const", "enum", "annotation"]: ...
+
+class CapnpTypesModule:
+    Void: _SchemaType
+    Bool: _SchemaType
+    Int8: _SchemaType
+    Int16: _SchemaType
+    Int32: _SchemaType
+    Int64: _SchemaType
+    UInt8: _SchemaType
+    UInt16: _SchemaType
+    UInt32: _SchemaType
+    UInt64: _SchemaType
+    Float32: _SchemaType
+    Float64: _SchemaType
+    Text: _SchemaType
+    Data: _SchemaType
+    AnyPointer: _SchemaType
+
+# Re-export commonly used types
+Server = asyncio.Server

capnp/lib/__init__.pyi

@@ -0,0 +1,8 @@
+"""capnp.lib package."""
+
+from __future__ import annotations
+
+# The lib package just contains the capnp submodule
+from capnp.lib import capnp
+
+__all__ = ["capnp"]