Skip to content

[Python] Sync APIs Type Hints Proposal #545

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
asheshvidyut wants to merge 2 commits into
base: master
Choose a base branch
from
Draft

[Python] Sync APIs Type Hints Proposal #545

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4f98a86
sync stack type hints proposal
asheshvidyut Mar 25, 2026
49df862
fix english
asheshvidyut Mar 25, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 48 additions & 0 deletions L125-python-add-typehints-to-sync-apis.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
Add Typing to gRPC Python Sync API
----
* Author(s): asheshvidyut
* Approver: sergiitk
* Status: In Review
* Implemented in: Python
* Last updated: 2026/03/25
* Discussion at:

## Abstract

This proposal aims to add inline type annotations (or type hints) to the untyped gRPC Python API.
These annotations are added in accordance with [PEP-484](https://peps.python.org/pep-0484/) and [PEP-526](https://peps.python.org/pep-0526/).
The proposal also introduces [Pyright](https://github.com/microsoft/pyright), a static type checker that will run in CI to verify the correctness of the type hints added to the gRPC Python source code.

## Background

Type annotations are already present in the gRPC Python AsyncIO APIs. This proposal extends type hints to the synchronous APIs.
Type hints benefit users and developers in the following ways:
* Better IDE support with intelligent autocomplete
* Catching bugs before they happen
* Code as documentation

Additionally, this proposal includes the addition of `Pyright`, a static type checker for Python, to verify the correctness of these hints.

### Related Proposals:
* Related to [Sync API Type Hints](https://github.com/grpc/proposal/pull/459)

## Proposal

* This proposal primarily targets adding inline type annotations to the file `src/python/grpcio/grpc/__init__.py`.
* It ensures all type annotations in the folder `src/python/grpcio` pass validation using `Pyright`.
* It adds missing inline type annotations to `.py` files inside `src/python/grpcio/grpc`.

## Rationale

Adding type annotations to the gRPC Python Sync API would provide several benefits:

* **Improved Developer Productivity:** Type annotations would help developers catch errors early in the development process, reducing the time spent on debugging.
* **Enhanced Code Maintainability:** Type annotations would ensure type consistency across the codebase, making it easier to maintain and update the code.
* **Enabled Static Analysis:** Type annotations would allow static analysis tools like MyPy to effectively analyze gRPC code, leading to earlier detection of potential issues.


## Implementation

* PR corresponding to this proposal - https://github.com/grpc/grpc/pull/41210