From 7e7616722eb0dccf1401317323b9aa7c40da4471 Mon Sep 17 00:00:00 2001 From: Xuan Wang Date: Tue, 25 Oct 2022 17:54:06 +0000 Subject: [PATCH 1/3] L103 Draft: Add Typing to gRPC Python Sync APIs --- L103-python-add-typing-to-sync-api.md | 79 +++++++++++++++++++++++++++ 1 file changed, 79 insertions(+) create mode 100644 L103-python-add-typing-to-sync-api.md diff --git a/L103-python-add-typing-to-sync-api.md b/L103-python-add-typing-to-sync-api.md new file mode 100644 index 000000000..6984eb15f --- /dev/null +++ b/L103-python-add-typing-to-sync-api.md @@ -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: (filled after thread exists) + +## Abstract + +Add type annotation to Python Sync API. + +## 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 + * 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): + * [PR link holder] +* `grpc/src/python/grpcio/grpc/_runtime_protos.py` +```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 + +1. Add typing to internal APIs. +2. Add typing to public API and test though pre-release. +3. Add typing to public APIs. + +## Open issues (if applicable) + +N/A From 0a0e8358a816c5c935f35fb659f9e0a846dbc9b8 Mon Sep 17 00:00:00 2001 From: Xuan Wang Date: Thu, 10 Nov 2022 18:12:37 +0000 Subject: [PATCH 2/3] Changes based on feedback --- L103-python-add-typing-to-sync-api.md | 33 ++++++++++++--------------- 1 file changed, 14 insertions(+), 19 deletions(-) diff --git a/L103-python-add-typing-to-sync-api.md b/L103-python-add-typing-to-sync-api.md index 6984eb15f..a99119b13 100644 --- a/L103-python-add-typing-to-sync-api.md +++ b/L103-python-add-typing-to-sync-api.md @@ -4,12 +4,12 @@ Add Typing to gRPC Python Sync API * Approver: gnossen * Status: Draft * Implemented in: Python -* Last updated: 11/09/2022 +* Last updated: 11/10/2022 * Discussion at: (filled after thread exists) ## Abstract -Add type annotation to Python Sync API. +Add type annotations to the remainder of the gRPC Python API. ## Background @@ -19,26 +19,19 @@ This proposal plans to add type annotation to python Sync public APIs which allo ### Related Proposals: -* Loosely related: https://github.com/lidizheng/proposal/blob/grpc-python-async-api/L58-python-async-api.md#introduce-typing-to-generated-code +* Loosely related to [Async API proposal](https://github.com/lidizheng/proposal/blob/grpc-python-async-api/L58-python-async-api.md#introduce-typing-to-generated-code). * 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): +Add type annotation to the following: +* All public Python APIs listed in [`__all__` variable](https://github.com/grpc/grpc/blob/54dd7563c2d563bff74e4b558f2e985db4a01f2d/src/python/grpcio/grpc/__init__.py#L2100) (the actuall list is too long, please refer to the following PR for changes): + * [PR link holder] +* gRPC Python generated Code. + * [PR Link holder] +* Python ancillary packages. * [PR link holder] -* `grpc/src/python/grpcio/grpc/_runtime_protos.py` -```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 @@ -70,9 +63,11 @@ def __call__(self, ## Implementation -1. Add typing to internal APIs. -2. Add typing to public API and test though pre-release. -3. Add typing to public APIs. +* Add typing to internal APIs. + * [PR1: Add typing for some internal python files.](https://github.com/grpc/grpc/pull/31514) +* Add typing to public API and test though pre-release. + * [PR link holder] +* Release typed public APIs. ## Open issues (if applicable) From abaf7352c70080ff1ae977291c0ec3e08e5976fb Mon Sep 17 00:00:00 2001 From: Xuan Wang Date: Mon, 14 Nov 2022 18:23:25 +0000 Subject: [PATCH 3/3] Changes based on comments --- L103-python-add-typing-to-sync-api.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/L103-python-add-typing-to-sync-api.md b/L103-python-add-typing-to-sync-api.md index a99119b13..0aedcac06 100644 --- a/L103-python-add-typing-to-sync-api.md +++ b/L103-python-add-typing-to-sync-api.md @@ -30,8 +30,14 @@ Add type annotation to the following: * [PR link holder] * gRPC Python generated Code. * [PR Link holder] -* Python ancillary packages. - * [PR link holder] +* Python ancillary packages, including: + * grpcio-admin + * grpcio-channelz + * grpcio-csds + * grpcio-health-checking + * grpcio-reflection + * grpcio-status + * grpcio-testing ## Rationale @@ -65,7 +71,7 @@ def __call__(self, * Add typing to internal APIs. * [PR1: Add typing for some internal python files.](https://github.com/grpc/grpc/pull/31514) -* Add typing to public API and test though pre-release. +* Add typing to public API and mark it as experimental for at least one release. * [PR link holder] * Release typed public APIs.