-
Notifications
You must be signed in to change notification settings - Fork 225
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.
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
L103 Draft: Add Types to the remainder of the gRPC Python API Surface #337
Open
XuanWang-Amos
wants to merge
3
commits into
grpc:master
Choose a base branch
from
XuanWang-Amos:PyTypingGRFC
base: master
Could not load branches
Branch not found: {{ refName }}
Could not load tags
Nothing to show
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Changes from 1 commit
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,79 @@ | ||
Add Typing to gRPC Python Sync API | ||
---- | ||
* Author(s): XuanWnag-Amos | ||
* Approver: gnossen | ||
* Status: Draft | ||
* Implemented in: Python | ||
* Last updated: 11/09/2022 | ||
* Discussion at: <google group thread> (filled after thread exists) | ||
|
||
## Abstract | ||
|
||
Add type annotation to Python Sync API. | ||
XuanWang-Amos marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
## Background | ||
|
||
[Type Hints](https://peps.python.org/pep-0484/#union-types) was introduced for a while now, we already added type annotation to python Async APIs since it has a high enough version floor. Now it's time to do the same for Sync APIs. | ||
|
||
This proposal plans to add type annotation to python Sync public APIs which allows users to build safer code by running static type analysis tools. | ||
|
||
|
||
### Related Proposals: | ||
* Loosely related: https://github.com/lidizheng/proposal/blob/grpc-python-async-api/L58-python-async-api.md#introduce-typing-to-generated-code | ||
XuanWang-Amos marked this conversation as resolved.
Show resolved
Hide resolved
|
||
* The proposal includes the part to introduce typing to gRPC Python Async APIs. | ||
|
||
|
||
## Proposal | ||
|
||
Add type annotation to the following Python APIs: | ||
* All APIs in `__init__.py` (the actuall list is too long, please refer to following PR for changes): | ||
XuanWang-Amos marked this conversation as resolved.
Show resolved
Hide resolved
XuanWang-Amos marked this conversation as resolved.
Show resolved
Hide resolved
|
||
* [PR link holder] | ||
* `grpc/src/python/grpcio/grpc/_runtime_protos.py` | ||
XuanWang-Amos marked this conversation as resolved.
Show resolved
Hide resolved
|
||
```python | ||
def protos(protobuf_path): # pylint: disable=unused-argument | ||
... | ||
|
||
def services(protobuf_path): # pylint: disable=unused-argument | ||
... | ||
|
||
def protos_and_services(protobuf_path): # pylint: disable=unused-argument | ||
... | ||
``` | ||
|
||
## Rationale | ||
|
||
The alternative is keep APIs in Sync stack unchanged and without type annotation, this way users won't be able to know if their implementation is correct or not without actually running the code. | ||
|
||
After add type annotation, instead of original un-typed API (`UnaryUnaryMultiCallable.__call__`): | ||
```python | ||
@abc.abstractmethod | ||
def __call__(self, | ||
request, | ||
timeout=None, | ||
metadata=None, | ||
credentials=None, | ||
wait_for_ready=None, | ||
compression=None): | ||
``` | ||
|
||
We'll have typed API which will looks like this: | ||
```python | ||
@abc.abstractmethod | ||
def __call__(self, | ||
request: RequestType, | ||
timeout: Optional[float] = None, | ||
metadata: Optional[MetadataType] = None, | ||
credentials: Optional[CallCredentials] = None, | ||
wait_for_ready: Optional[bool] = None, | ||
compression: Optional[Compression] = None) -> ResponseType: | ||
``` | ||
|
||
## Implementation | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Once it exists, the implementation PR should be linked to here. |
||
|
||
1. Add typing to internal APIs. | ||
2. Add typing to public API and test though pre-release. | ||
3. Add typing to public APIs. | ||
XuanWang-Amos marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
## Open issues (if applicable) | ||
|
||
N/A |
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Reminder to create the Google group thread once the gRFC is in a presentable state.