pygrpc-native 0.5.1__tar.gz → 0.5.2__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (81) hide show
  1. {pygrpc_native-0.5.1 → pygrpc_native-0.5.2}/.github/workflows/ci.yml +13 -1
  2. {pygrpc_native-0.5.1 → pygrpc_native-0.5.2}/CHANGELOG.md +8 -0
  3. {pygrpc_native-0.5.1 → pygrpc_native-0.5.2}/Cargo.lock +1 -1
  4. {pygrpc_native-0.5.1 → pygrpc_native-0.5.2}/Cargo.toml +1 -1
  5. pygrpc_native-0.5.2/PKG-INFO +264 -0
  6. pygrpc_native-0.5.2/README.md +249 -0
  7. {pygrpc_native-0.5.1 → pygrpc_native-0.5.2}/pyproject.toml +2 -0
  8. {pygrpc_native-0.5.1 → pygrpc_native-0.5.2}/python/pygrpc_native/aio.py +9 -3
  9. {pygrpc_native-0.5.1 → pygrpc_native-0.5.2}/tests/test_aio.py +5 -0
  10. {pygrpc_native-0.5.1 → pygrpc_native-0.5.2}/tests/test_downstream.py +9 -6
  11. {pygrpc_native-0.5.1 → pygrpc_native-0.5.2}/tests/test_interceptors.py +6 -2
  12. pygrpc_native-0.5.1/PKG-INFO +0 -196
  13. pygrpc_native-0.5.1/README.md +0 -181
  14. {pygrpc_native-0.5.1 → pygrpc_native-0.5.2}/.github/CODEOWNERS +0 -0
  15. {pygrpc_native-0.5.1 → pygrpc_native-0.5.2}/.github/ISSUE_TEMPLATE/bug_report.md +0 -0
  16. {pygrpc_native-0.5.1 → pygrpc_native-0.5.2}/.github/ISSUE_TEMPLATE/config.yml +0 -0
  17. {pygrpc_native-0.5.1 → pygrpc_native-0.5.2}/.github/ISSUE_TEMPLATE/feature_request.md +0 -0
  18. {pygrpc_native-0.5.1 → pygrpc_native-0.5.2}/.github/PULL_REQUEST_TEMPLATE.md +0 -0
  19. {pygrpc_native-0.5.1 → pygrpc_native-0.5.2}/.github/dependabot.yml +0 -0
  20. {pygrpc_native-0.5.1 → pygrpc_native-0.5.2}/.github/workflows/dco.yml +0 -0
  21. {pygrpc_native-0.5.1 → pygrpc_native-0.5.2}/.github/workflows/release.yml +0 -0
  22. {pygrpc_native-0.5.1 → pygrpc_native-0.5.2}/.github/workflows/stale.yml +0 -0
  23. {pygrpc_native-0.5.1 → pygrpc_native-0.5.2}/.gitignore +0 -0
  24. {pygrpc_native-0.5.1 → pygrpc_native-0.5.2}/.pre-commit-config.yaml +0 -0
  25. {pygrpc_native-0.5.1 → pygrpc_native-0.5.2}/CODE_OF_CONDUCT.md +0 -0
  26. {pygrpc_native-0.5.1 → pygrpc_native-0.5.2}/CONTRIBUTING.md +0 -0
  27. {pygrpc_native-0.5.1 → pygrpc_native-0.5.2}/DCO +0 -0
  28. {pygrpc_native-0.5.1 → pygrpc_native-0.5.2}/LICENSE +0 -0
  29. {pygrpc_native-0.5.1 → pygrpc_native-0.5.2}/SECURITY.md +0 -0
  30. {pygrpc_native-0.5.1 → pygrpc_native-0.5.2}/benchmarks/README.md +0 -0
  31. {pygrpc_native-0.5.1 → pygrpc_native-0.5.2}/benchmarks/echo.py +0 -0
  32. {pygrpc_native-0.5.1 → pygrpc_native-0.5.2}/docs/low-level-api.md +0 -0
  33. {pygrpc_native-0.5.1 → pygrpc_native-0.5.2}/python/pygrpc_native/__init__.py +0 -0
  34. {pygrpc_native-0.5.1 → pygrpc_native-0.5.2}/python/pygrpc_native/_native.pyi +0 -0
  35. {pygrpc_native-0.5.1 → pygrpc_native-0.5.2}/python/pygrpc_native/_server.py +0 -0
  36. {pygrpc_native-0.5.1 → pygrpc_native-0.5.2}/python/pygrpc_native/py.typed +0 -0
  37. {pygrpc_native-0.5.1 → pygrpc_native-0.5.2}/src/lib.rs +0 -0
  38. {pygrpc_native-0.5.1 → pygrpc_native-0.5.2}/src/metrics.rs +0 -0
  39. {pygrpc_native-0.5.1 → pygrpc_native-0.5.2}/src/server.rs +0 -0
  40. {pygrpc_native-0.5.1 → pygrpc_native-0.5.2}/tests/test_add_methods.py +0 -0
  41. {pygrpc_native-0.5.1 → pygrpc_native-0.5.2}/tests/test_api.py +0 -0
  42. {pygrpc_native-0.5.1 → pygrpc_native-0.5.2}/tests/test_bearer_auth.py +0 -0
  43. {pygrpc_native-0.5.1 → pygrpc_native-0.5.2}/tests/test_call_details.py +0 -0
  44. {pygrpc_native-0.5.1 → pygrpc_native-0.5.2}/tests/test_calls.py +0 -0
  45. {pygrpc_native-0.5.1 → pygrpc_native-0.5.2}/tests/test_connection.py +0 -0
  46. {pygrpc_native-0.5.1 → pygrpc_native-0.5.2}/tests/test_delay_stream_headers.py +0 -0
  47. {pygrpc_native-0.5.1 → pygrpc_native-0.5.2}/tests/test_fallback.py +0 -0
  48. {pygrpc_native-0.5.1 → pygrpc_native-0.5.2}/tests/test_front.py +0 -0
  49. {pygrpc_native-0.5.1 → pygrpc_native-0.5.2}/tests/test_metrics.py +0 -0
  50. {pygrpc_native-0.5.1 → pygrpc_native-0.5.2}/tests/test_response_metadata.py +0 -0
  51. {pygrpc_native-0.5.1 → pygrpc_native-0.5.2}/tests/test_server.py +0 -0
  52. {pygrpc_native-0.5.1 → pygrpc_native-0.5.2}/tests/test_stream_try_send.py +0 -0
  53. {pygrpc_native-0.5.1 → pygrpc_native-0.5.2}/vendor/http/CHANGELOG.md +0 -0
  54. {pygrpc_native-0.5.1 → pygrpc_native-0.5.2}/vendor/http/Cargo.toml +0 -0
  55. {pygrpc_native-0.5.1 → pygrpc_native-0.5.2}/vendor/http/LICENSE-APACHE +0 -0
  56. {pygrpc_native-0.5.1 → pygrpc_native-0.5.2}/vendor/http/LICENSE-MIT +0 -0
  57. {pygrpc_native-0.5.1 → pygrpc_native-0.5.2}/vendor/http/README.md +0 -0
  58. {pygrpc_native-0.5.1 → pygrpc_native-0.5.2}/vendor/http/src/byte_str.rs +0 -0
  59. {pygrpc_native-0.5.1 → pygrpc_native-0.5.2}/vendor/http/src/convert.rs +0 -0
  60. {pygrpc_native-0.5.1 → pygrpc_native-0.5.2}/vendor/http/src/error.rs +0 -0
  61. {pygrpc_native-0.5.1 → pygrpc_native-0.5.2}/vendor/http/src/extensions.rs +0 -0
  62. {pygrpc_native-0.5.1 → pygrpc_native-0.5.2}/vendor/http/src/header/map.rs +0 -0
  63. {pygrpc_native-0.5.1 → pygrpc_native-0.5.2}/vendor/http/src/header/mod.rs +0 -0
  64. {pygrpc_native-0.5.1 → pygrpc_native-0.5.2}/vendor/http/src/header/name.rs +0 -0
  65. {pygrpc_native-0.5.1 → pygrpc_native-0.5.2}/vendor/http/src/header/value.rs +0 -0
  66. {pygrpc_native-0.5.1 → pygrpc_native-0.5.2}/vendor/http/src/lib.rs +0 -0
  67. {pygrpc_native-0.5.1 → pygrpc_native-0.5.2}/vendor/http/src/method.rs +0 -0
  68. {pygrpc_native-0.5.1 → pygrpc_native-0.5.2}/vendor/http/src/request.rs +0 -0
  69. {pygrpc_native-0.5.1 → pygrpc_native-0.5.2}/vendor/http/src/response.rs +0 -0
  70. {pygrpc_native-0.5.1 → pygrpc_native-0.5.2}/vendor/http/src/status.rs +0 -0
  71. {pygrpc_native-0.5.1 → pygrpc_native-0.5.2}/vendor/http/src/uri/authority.rs +0 -0
  72. {pygrpc_native-0.5.1 → pygrpc_native-0.5.2}/vendor/http/src/uri/builder.rs +0 -0
  73. {pygrpc_native-0.5.1 → pygrpc_native-0.5.2}/vendor/http/src/uri/mod.rs +0 -0
  74. {pygrpc_native-0.5.1 → pygrpc_native-0.5.2}/vendor/http/src/uri/path.rs +0 -0
  75. {pygrpc_native-0.5.1 → pygrpc_native-0.5.2}/vendor/http/src/uri/port.rs +0 -0
  76. {pygrpc_native-0.5.1 → pygrpc_native-0.5.2}/vendor/http/src/uri/scheme.rs +0 -0
  77. {pygrpc_native-0.5.1 → pygrpc_native-0.5.2}/vendor/http/src/uri/tests.rs +0 -0
  78. {pygrpc_native-0.5.1 → pygrpc_native-0.5.2}/vendor/http/src/version.rs +0 -0
  79. {pygrpc_native-0.5.1 → pygrpc_native-0.5.2}/vendor/http/tests/header_map.rs +0 -0
  80. {pygrpc_native-0.5.1 → pygrpc_native-0.5.2}/vendor/http/tests/header_map_fuzz.rs +0 -0
  81. {pygrpc_native-0.5.1 → pygrpc_native-0.5.2}/vendor/http/tests/status_code.rs +0 -0
@@ -33,11 +33,19 @@ jobs:
33
33
  - run: cargo test --locked --no-default-features
34
34
 
35
35
  python:
36
+ # Keeps the names of the jobs that branch protection requires.
37
+ name: python (${{ matrix.os }}, ${{ matrix.python }}${{ matrix.grpcio && format(', grpcio {0}', matrix.grpcio) || '' }})
36
38
  strategy:
37
39
  fail-fast: false
38
40
  matrix:
39
41
  os: [ubuntu-latest, macos-latest]
40
42
  python: ["3.10", "3.13"]
43
+ grpcio: [""]
44
+ include:
45
+ # The first grpcio whose generated code adds registered handlers.
46
+ - os: ubuntu-latest
47
+ python: "3.10"
48
+ grpcio: "1.64.3"
41
49
  runs-on: ${{ matrix.os }}
42
50
  steps:
43
51
  - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
@@ -47,9 +55,13 @@ jobs:
47
55
  - uses: dtolnay/rust-toolchain@stable
48
56
  - name: Build and install
49
57
  run: |
50
- python -m pip install maturin pytest grpcio grpcio-tools grpcio-health-checking grpcio-reflection uvloop
58
+ if [ -n "${{ matrix.grpcio }}" ]; then pin="==${{ matrix.grpcio }}"; fi
59
+ python -m pip install maturin pytest uvloop "grpcio$pin" "grpcio-tools$pin" "grpcio-health-checking$pin" "grpcio-reflection$pin"
51
60
  # Interceptor libraries that downstream servers use, for tests/test_downstream.py.
52
61
  python -m pip install grpc-interceptor opentelemetry-instrumentation-grpc
62
+ if [ -n "$pin" ]; then
63
+ python -c "import grpc; assert grpc.__version__ == '${{ matrix.grpcio }}', grpc.__version__"
64
+ fi
53
65
  maturin build --release --locked --out dist
54
66
  python -m pip install dist/*.whl
55
67
  - run: pytest -q tests
@@ -4,6 +4,14 @@ All notable changes are listed here. The project follows
4
4
  [semantic versioning](https://semver.org); see
5
5
  [Compatibility](README.md#compatibility) for what that covers.
6
6
 
7
+ ## 0.5.2 (2026-10-28)
8
+
9
+ ### Fixed
10
+
11
+ - On grpcio 1.64 through 1.83, the aio server answered client-streaming and
12
+ bidirectional methods of generated code with `UNIMPLEMENTED`. They now reach
13
+ the grpcio fallback. (#69)
14
+
7
15
  ## 0.5.1 (2026-10-27)
8
16
 
9
17
  ### Fixed
@@ -395,7 +395,7 @@ dependencies = [
395
395
 
396
396
  [[package]]
397
397
  name = "pygrpc_native"
398
- version = "0.5.1"
398
+ version = "0.5.2"
399
399
  dependencies = [
400
400
  "bytes",
401
401
  "crossbeam-channel",
@@ -2,7 +2,7 @@
2
2
 
3
3
  [package]
4
4
  name = "pygrpc_native"
5
- version = "0.5.1"
5
+ version = "0.5.2"
6
6
  edition = "2021"
7
7
  license = "Apache-2.0"
8
8
  description = "A gRPC server in Rust that hands calls to Python handlers in batches"
@@ -0,0 +1,264 @@
1
+ Metadata-Version: 2.4
2
+ Name: pygrpc-native
3
+ Version: 0.5.2
4
+ Classifier: Programming Language :: Python :: 3
5
+ Classifier: Programming Language :: Rust
6
+ Classifier: Operating System :: POSIX :: Linux
7
+ Classifier: Operating System :: MacOS
8
+ License-File: LICENSE
9
+ Summary: A drop-in grpcio server whose HTTP/2 and gRPC work runs in Rust, outside the GIL
10
+ License-Expression: Apache-2.0
11
+ Requires-Python: >=3.10
12
+ Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
13
+ Project-URL: Repository, https://github.com/pygrpc/pygrpc-native
14
+
15
+ <p align="center">
16
+ <img src="https://raw.githubusercontent.com/pygrpc/pygrpc-native/main/assets/logo.png" alt="pygrpc-native" width="96">
17
+ </p>
18
+
19
+ <h1 align="center">pygrpc-native</h1>
20
+
21
+ <p align="center">
22
+ A gRPC server for Python that does the HTTP/2 and gRPC work in Rust, outside the GIL.<br>
23
+ Your handlers stay in Python.
24
+ </p>
25
+
26
+ <p align="center">
27
+ <a href="https://pypi.org/project/pygrpc-native/"><img src="https://img.shields.io/pypi/v/pygrpc-native?logo=pypi&logoColor=white&label=PyPI" alt="PyPI"></a>
28
+ <a href="https://pypi.org/project/pygrpc-native/"><img src="https://img.shields.io/pypi/pyversions/pygrpc-native?logo=python&logoColor=white" alt="Python versions"></a>
29
+ <a href="https://github.com/pygrpc/pygrpc-native/actions/workflows/ci.yml"><img src="https://github.com/pygrpc/pygrpc-native/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI"></a>
30
+ <a href="https://github.com/pygrpc/pygrpc-native/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg" alt="License"></a>
31
+ </p>
32
+
33
+ <p align="center">
34
+ <img src="https://raw.githubusercontent.com/pygrpc/pygrpc-native/main/assets/how-it-works-light.svg" alt="With grpc.server(), C-core does HTTP/2 and Python handles each call's events one at a time under the GIL. With pygrpc_native.server(), Rust threads do HTTP/2 and the per-call work outside the GIL and hand calls to Python in batches." width="100%">
35
+ </p>
36
+
37
+ When a Python gRPC server runs short of CPU, the usual answers are more server
38
+ processes or a rewrite in another language. pygrpc-native moves the gRPC work
39
+ itself (HTTP/2, flow control, deadlines, cancellation) into Rust, outside the
40
+ GIL, and leaves your servicers, interceptors and generated code as they are.
41
+
42
+ - **Switching is one line.** `pygrpc_native.server()` and
43
+ `pygrpc_native.aio.server()` take the same arguments as grpcio's servers.
44
+ Clients don't change.
45
+ - **It behaves like grpcio.** Status codes, metadata, deadlines,
46
+ cancellation, interceptors and `ServicerContext` work the same way. The few
47
+ differences are listed below, and anything else is a bug.
48
+ - **Nothing stops working.** Methods it can't serve itself, such as
49
+ bidirectional streaming or server reflection, are passed to a grpcio server
50
+ running behind it.
51
+ - **It's faster under load.** With an empty handler it answers about 1.5x as
52
+ many calls per second as grpcio from one client thread, and about 5x from
53
+ 32. See [Benchmarks](#benchmarks).
54
+
55
+ ## Quick start
56
+
57
+ ```bash
58
+ pip install pygrpc-native
59
+ ```
60
+
61
+ Wheels are available for Linux (x86_64, aarch64) and macOS (arm64, x86_64),
62
+ for CPython 3.10 and later.
63
+
64
+ Change the line that creates the server:
65
+
66
+ ```diff
67
+ from concurrent import futures
68
+ -import grpc
69
+ +import pygrpc_native
70
+
71
+ -server = grpc.server(futures.ThreadPoolExecutor(16))
72
+ +server = pygrpc_native.server(futures.ThreadPoolExecutor(16))
73
+ greeter_pb2_grpc.add_GreeterServicer_to_server(Greeter(), server)
74
+ server.add_insecure_port("[::]:50051")
75
+ server.start()
76
+ server.wait_for_termination()
77
+ ```
78
+
79
+ For `grpc.aio`:
80
+
81
+ ```diff
82
+ +import pygrpc_native.aio
83
+ +
84
+ -server = grpc.aio.server()
85
+ +server = pygrpc_native.aio.server()
86
+ greeter_pb2_grpc.add_GreeterServicer_to_server(Greeter(), server)
87
+ server.add_insecure_port("[::]:50051")
88
+ await server.start()
89
+ await server.wait_for_termination()
90
+ ```
91
+
92
+ To build from source:
93
+
94
+ ```bash
95
+ pip install maturin
96
+ maturin develop --release
97
+ ```
98
+
99
+ ## How it works
100
+
101
+ Every call reaches Python as an event: an id, the method, the request bytes
102
+ and who sent it.
103
+
104
+ ```
105
+ grpc client ──HTTP/2──▶ tokio threads (no GIL)
106
+ │ path → method id
107
+ ▼
108
+ event queue ──▶ recv_batch() in Python
109
+ ◀── respond(call_id, bytes) from any thread
110
+ ```
111
+
112
+ Python picks up calls in batches, so a burst costs one trip across the GIL
113
+ instead of one per call. `server()` and `aio.server()` are built on top of
114
+ this and run your handlers the way grpcio does.
115
+
116
+ ## What runs natively
117
+
118
+ | | Native | grpcio fallback |
119
+ |:--|:-:|:-:|
120
+ | Unary and server-streaming methods | ✓ | |
121
+ | Client-streaming and bidirectional methods | | ✓ |
122
+ | Code generated by grpcio-tools 1.64 or later | ✓ | |
123
+ | Code generated by older grpcio-tools, or anything else added only with `add_generic_rpc_handlers` | | ✓ |
124
+ | Server reflection | | ✓ |
125
+ | Interceptors | ✓ | ✓ |
126
+
127
+ The fallback is a grpcio server listening on a Unix socket behind this one.
128
+ Calls that go there work but aren't any faster, and `peer()` in them returns
129
+ the socket. The native server listens on a single insecure port.
130
+
131
+ <details>
132
+ <summary><b>Server options</b></summary>
133
+
134
+ <br>
135
+
136
+ | | Options |
137
+ |:--|:--|
138
+ | Same as grpcio | `grpc.max_receive_message_length`, `grpc.max_send_message_length`, `grpc.keepalive_time_ms`, `grpc.keepalive_timeout_ms`, `grpc.keepalive_permit_without_calls`, `grpc.max_concurrent_streams`, `grpc.max_metadata_size`, `grpc.absolute_max_metadata_size`, `grpc.so_reuseport` |
139
+ | Raise an error | `grpc.max_connection_age_ms`, `grpc.max_connection_age_grace_ms`, `grpc.max_connection_idle_ms`, `grpc.max_allowed_incoming_connections`, response compression, `maximum_concurrent_rpcs`, TLS |
140
+ | Ignored | Everything else. grpcio also ignores the many options that only clients read. This includes the limits on client pings, which are accepted but not enforced, and `grpc.http2.max_frame_size`, which grpc-core's flow control overrides anyway. |
141
+
142
+ As in grpcio, a value that isn't an integer is ignored.
143
+
144
+ </details>
145
+
146
+ <details>
147
+ <summary><b>Known differences from grpcio</b></summary>
148
+
149
+ <br>
150
+
151
+ - If a unary handler calls `send_initial_metadata()` and then fails, the
152
+ metadata is sent along with the status, so the client sees it as trailing
153
+ metadata.
154
+ - If a client doesn't answer a keepalive ping, the connection is closed after
155
+ `grpc.keepalive_timeout_ms`, as gRPC's keepalive docs describe. grpcio waits
156
+ for `grpc.http2.ping_timeout_ms` instead, which is a minute by default.
157
+
158
+ </details>
159
+
160
+ <details>
161
+ <summary><b>Notes on <code>aio.server()</code></b></summary>
162
+
163
+ <br>
164
+
165
+ - Handlers run on the event loop that called `start()`, including uvloop.
166
+ - `abort()` raises `grpc.aio.AbortError`. If the client cancels or the
167
+ deadline passes, the handler gets `asyncio.CancelledError`, as in grpc.aio.
168
+ - Streaming handlers can yield from an async generator or call
169
+ `context.write()`.
170
+ - Handlers that aren't coroutines run in `migration_thread_pool` with
171
+ grpcio's sync context, where `abort()` returns instead of raising.
172
+ - The fallback, the options and the differences above are the same as for
173
+ the sync server.
174
+
175
+ </details>
176
+
177
+ ## Low-level API
178
+
179
+ `NativeGrpcFront` is the layer under `server()`. You receive each call as an
180
+ event and answer it by id:
181
+
182
+ ```python
183
+ import threading
184
+ from pygrpc_native import EVENT_CALL, NativeGrpcFront
185
+
186
+ front = NativeGrpcFront("0.0.0.0:50051", [("/echo.Echo/Say", False)])
187
+ front.start()
188
+
189
+ def serve():
190
+ while (events := front.recv_batch(64)) is not None:
191
+ for kind, call_id, method_id, payload, client_key in events:
192
+ if kind == EVENT_CALL:
193
+ front.respond(call_id, payload)
194
+
195
+ threading.Thread(target=serve).start()
196
+ ```
197
+
198
+ Streaming, call details, response metadata, bearer tokens and metrics are
199
+ covered in [docs/low-level-api.md](https://github.com/pygrpc/pygrpc-native/blob/main/docs/low-level-api.md).
200
+
201
+ ## Benchmarks
202
+
203
+ <p align="center">
204
+ <img src="https://raw.githubusercontent.com/pygrpc/pygrpc-native/main/assets/benchmark.gif" alt="benchmarks/echo.py against grpc.server(), then against pygrpc_native.server()" width="100%">
205
+ </p>
206
+
207
+ An empty unary handler on an Apple M4 Pro, called by grpcio clients on the
208
+ same machine. Calls per second, median of three runs:
209
+
210
+ | Server | 1 client thread | 32 client threads (8 processes x 4) |
211
+ |:--|--:|--:|
212
+ | `grpc.server()` | 7,739 | 10,955 |
213
+ | `grpc.aio.server()` | 4,804 | 10,322 |
214
+ | `pygrpc_native.server()` | 11,428 | 57,419 |
215
+ | `pygrpc_native.aio.server()` | 9,444 | 58,073 |
216
+ | Low-level API | 12,835 | 63,413 |
217
+
218
+ On a 40-vCPU Linux container, the low-level API answered about 12x as many
219
+ calls as grpcio at 32 threads. The [benchmark README](https://github.com/pygrpc/pygrpc-native/blob/main/benchmarks/README.md)
220
+ has all the numbers and explains how they were measured.
221
+
222
+ ## Limitations
223
+
224
+ - `NativeGrpcFront` only serves unary and server-streaming methods. Other
225
+ kinds can go through the fallback server, and `server()` and `aio.server()`
226
+ send them there for you.
227
+ - There's no TLS yet. `NativeGrpcFront` checks bearer tokens itself, while
228
+ `server()` and `aio.server()` run grpcio interceptors.
229
+ - As with grpc-core, binding a Unix socket path replaces any socket file
230
+ already there.
231
+ - `SO_REUSEPORT` is set only when `grpc.so_reuseport` is 1. grpcio sets it by
232
+ default, so binding a port that another server already uses works with
233
+ grpcio but fails here.
234
+ - Each connection allows up to 1024 concurrent streams unless
235
+ `grpc.max_concurrent_streams` says otherwise. A connection that hasn't
236
+ finished the HTTP/2 preface within 120 s is dropped.
237
+ - A call whose request metadata is over the limit (16 KiB unless set) is
238
+ refused. Between `grpc.max_metadata_size` and that limit, grpcio also
239
+ refuses some calls at random. This server doesn't.
240
+
241
+ ## Compatibility
242
+
243
+ pygrpc-native follows semantic versioning, and the low-level API also stays
244
+ compatible within 0.x:
245
+
246
+ - The 0.1 names, signatures and event tuples of `NativeGrpcFront` won't
247
+ change or go away. `tests/test_api.py` pins them. New parameters are only
248
+ added after the existing ones, with a default.
249
+ - The keys that `metrics()` returns won't be renamed or removed within 0.x,
250
+ though new ones may be added.
251
+ - `server()` and `aio.server()` follow grpcio's API. Any difference from
252
+ grpcio's behavior is a bug unless this README lists it.
253
+
254
+ Changes are listed in [CHANGELOG.md](https://github.com/pygrpc/pygrpc-native/blob/main/CHANGELOG.md).
255
+
256
+ ## Contributing
257
+
258
+ See [CONTRIBUTING.md](https://github.com/pygrpc/pygrpc-native/blob/main/CONTRIBUTING.md).
259
+ Every commit needs a DCO sign-off (`git commit -s`).
260
+
261
+ ## License
262
+
263
+ Apache-2.0
264
+
@@ -0,0 +1,249 @@
1
+ <p align="center">
2
+ <img src="https://raw.githubusercontent.com/pygrpc/pygrpc-native/main/assets/logo.png" alt="pygrpc-native" width="96">
3
+ </p>
4
+
5
+ <h1 align="center">pygrpc-native</h1>
6
+
7
+ <p align="center">
8
+ A gRPC server for Python that does the HTTP/2 and gRPC work in Rust, outside the GIL.<br>
9
+ Your handlers stay in Python.
10
+ </p>
11
+
12
+ <p align="center">
13
+ <a href="https://pypi.org/project/pygrpc-native/"><img src="https://img.shields.io/pypi/v/pygrpc-native?logo=pypi&logoColor=white&label=PyPI" alt="PyPI"></a>
14
+ <a href="https://pypi.org/project/pygrpc-native/"><img src="https://img.shields.io/pypi/pyversions/pygrpc-native?logo=python&logoColor=white" alt="Python versions"></a>
15
+ <a href="https://github.com/pygrpc/pygrpc-native/actions/workflows/ci.yml"><img src="https://github.com/pygrpc/pygrpc-native/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI"></a>
16
+ <a href="https://github.com/pygrpc/pygrpc-native/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg" alt="License"></a>
17
+ </p>
18
+
19
+ <p align="center">
20
+ <img src="https://raw.githubusercontent.com/pygrpc/pygrpc-native/main/assets/how-it-works-light.svg" alt="With grpc.server(), C-core does HTTP/2 and Python handles each call's events one at a time under the GIL. With pygrpc_native.server(), Rust threads do HTTP/2 and the per-call work outside the GIL and hand calls to Python in batches." width="100%">
21
+ </p>
22
+
23
+ When a Python gRPC server runs short of CPU, the usual answers are more server
24
+ processes or a rewrite in another language. pygrpc-native moves the gRPC work
25
+ itself (HTTP/2, flow control, deadlines, cancellation) into Rust, outside the
26
+ GIL, and leaves your servicers, interceptors and generated code as they are.
27
+
28
+ - **Switching is one line.** `pygrpc_native.server()` and
29
+ `pygrpc_native.aio.server()` take the same arguments as grpcio's servers.
30
+ Clients don't change.
31
+ - **It behaves like grpcio.** Status codes, metadata, deadlines,
32
+ cancellation, interceptors and `ServicerContext` work the same way. The few
33
+ differences are listed below, and anything else is a bug.
34
+ - **Nothing stops working.** Methods it can't serve itself, such as
35
+ bidirectional streaming or server reflection, are passed to a grpcio server
36
+ running behind it.
37
+ - **It's faster under load.** With an empty handler it answers about 1.5x as
38
+ many calls per second as grpcio from one client thread, and about 5x from
39
+ 32. See [Benchmarks](#benchmarks).
40
+
41
+ ## Quick start
42
+
43
+ ```bash
44
+ pip install pygrpc-native
45
+ ```
46
+
47
+ Wheels are available for Linux (x86_64, aarch64) and macOS (arm64, x86_64),
48
+ for CPython 3.10 and later.
49
+
50
+ Change the line that creates the server:
51
+
52
+ ```diff
53
+ from concurrent import futures
54
+ -import grpc
55
+ +import pygrpc_native
56
+
57
+ -server = grpc.server(futures.ThreadPoolExecutor(16))
58
+ +server = pygrpc_native.server(futures.ThreadPoolExecutor(16))
59
+ greeter_pb2_grpc.add_GreeterServicer_to_server(Greeter(), server)
60
+ server.add_insecure_port("[::]:50051")
61
+ server.start()
62
+ server.wait_for_termination()
63
+ ```
64
+
65
+ For `grpc.aio`:
66
+
67
+ ```diff
68
+ +import pygrpc_native.aio
69
+ +
70
+ -server = grpc.aio.server()
71
+ +server = pygrpc_native.aio.server()
72
+ greeter_pb2_grpc.add_GreeterServicer_to_server(Greeter(), server)
73
+ server.add_insecure_port("[::]:50051")
74
+ await server.start()
75
+ await server.wait_for_termination()
76
+ ```
77
+
78
+ To build from source:
79
+
80
+ ```bash
81
+ pip install maturin
82
+ maturin develop --release
83
+ ```
84
+
85
+ ## How it works
86
+
87
+ Every call reaches Python as an event: an id, the method, the request bytes
88
+ and who sent it.
89
+
90
+ ```
91
+ grpc client ──HTTP/2──▶ tokio threads (no GIL)
92
+ │ path → method id
93
+ ▼
94
+ event queue ──▶ recv_batch() in Python
95
+ ◀── respond(call_id, bytes) from any thread
96
+ ```
97
+
98
+ Python picks up calls in batches, so a burst costs one trip across the GIL
99
+ instead of one per call. `server()` and `aio.server()` are built on top of
100
+ this and run your handlers the way grpcio does.
101
+
102
+ ## What runs natively
103
+
104
+ | | Native | grpcio fallback |
105
+ |:--|:-:|:-:|
106
+ | Unary and server-streaming methods | ✓ | |
107
+ | Client-streaming and bidirectional methods | | ✓ |
108
+ | Code generated by grpcio-tools 1.64 or later | ✓ | |
109
+ | Code generated by older grpcio-tools, or anything else added only with `add_generic_rpc_handlers` | | ✓ |
110
+ | Server reflection | | ✓ |
111
+ | Interceptors | ✓ | ✓ |
112
+
113
+ The fallback is a grpcio server listening on a Unix socket behind this one.
114
+ Calls that go there work but aren't any faster, and `peer()` in them returns
115
+ the socket. The native server listens on a single insecure port.
116
+
117
+ <details>
118
+ <summary><b>Server options</b></summary>
119
+
120
+ <br>
121
+
122
+ | | Options |
123
+ |:--|:--|
124
+ | Same as grpcio | `grpc.max_receive_message_length`, `grpc.max_send_message_length`, `grpc.keepalive_time_ms`, `grpc.keepalive_timeout_ms`, `grpc.keepalive_permit_without_calls`, `grpc.max_concurrent_streams`, `grpc.max_metadata_size`, `grpc.absolute_max_metadata_size`, `grpc.so_reuseport` |
125
+ | Raise an error | `grpc.max_connection_age_ms`, `grpc.max_connection_age_grace_ms`, `grpc.max_connection_idle_ms`, `grpc.max_allowed_incoming_connections`, response compression, `maximum_concurrent_rpcs`, TLS |
126
+ | Ignored | Everything else. grpcio also ignores the many options that only clients read. This includes the limits on client pings, which are accepted but not enforced, and `grpc.http2.max_frame_size`, which grpc-core's flow control overrides anyway. |
127
+
128
+ As in grpcio, a value that isn't an integer is ignored.
129
+
130
+ </details>
131
+
132
+ <details>
133
+ <summary><b>Known differences from grpcio</b></summary>
134
+
135
+ <br>
136
+
137
+ - If a unary handler calls `send_initial_metadata()` and then fails, the
138
+ metadata is sent along with the status, so the client sees it as trailing
139
+ metadata.
140
+ - If a client doesn't answer a keepalive ping, the connection is closed after
141
+ `grpc.keepalive_timeout_ms`, as gRPC's keepalive docs describe. grpcio waits
142
+ for `grpc.http2.ping_timeout_ms` instead, which is a minute by default.
143
+
144
+ </details>
145
+
146
+ <details>
147
+ <summary><b>Notes on <code>aio.server()</code></b></summary>
148
+
149
+ <br>
150
+
151
+ - Handlers run on the event loop that called `start()`, including uvloop.
152
+ - `abort()` raises `grpc.aio.AbortError`. If the client cancels or the
153
+ deadline passes, the handler gets `asyncio.CancelledError`, as in grpc.aio.
154
+ - Streaming handlers can yield from an async generator or call
155
+ `context.write()`.
156
+ - Handlers that aren't coroutines run in `migration_thread_pool` with
157
+ grpcio's sync context, where `abort()` returns instead of raising.
158
+ - The fallback, the options and the differences above are the same as for
159
+ the sync server.
160
+
161
+ </details>
162
+
163
+ ## Low-level API
164
+
165
+ `NativeGrpcFront` is the layer under `server()`. You receive each call as an
166
+ event and answer it by id:
167
+
168
+ ```python
169
+ import threading
170
+ from pygrpc_native import EVENT_CALL, NativeGrpcFront
171
+
172
+ front = NativeGrpcFront("0.0.0.0:50051", [("/echo.Echo/Say", False)])
173
+ front.start()
174
+
175
+ def serve():
176
+ while (events := front.recv_batch(64)) is not None:
177
+ for kind, call_id, method_id, payload, client_key in events:
178
+ if kind == EVENT_CALL:
179
+ front.respond(call_id, payload)
180
+
181
+ threading.Thread(target=serve).start()
182
+ ```
183
+
184
+ Streaming, call details, response metadata, bearer tokens and metrics are
185
+ covered in [docs/low-level-api.md](https://github.com/pygrpc/pygrpc-native/blob/main/docs/low-level-api.md).
186
+
187
+ ## Benchmarks
188
+
189
+ <p align="center">
190
+ <img src="https://raw.githubusercontent.com/pygrpc/pygrpc-native/main/assets/benchmark.gif" alt="benchmarks/echo.py against grpc.server(), then against pygrpc_native.server()" width="100%">
191
+ </p>
192
+
193
+ An empty unary handler on an Apple M4 Pro, called by grpcio clients on the
194
+ same machine. Calls per second, median of three runs:
195
+
196
+ | Server | 1 client thread | 32 client threads (8 processes x 4) |
197
+ |:--|--:|--:|
198
+ | `grpc.server()` | 7,739 | 10,955 |
199
+ | `grpc.aio.server()` | 4,804 | 10,322 |
200
+ | `pygrpc_native.server()` | 11,428 | 57,419 |
201
+ | `pygrpc_native.aio.server()` | 9,444 | 58,073 |
202
+ | Low-level API | 12,835 | 63,413 |
203
+
204
+ On a 40-vCPU Linux container, the low-level API answered about 12x as many
205
+ calls as grpcio at 32 threads. The [benchmark README](https://github.com/pygrpc/pygrpc-native/blob/main/benchmarks/README.md)
206
+ has all the numbers and explains how they were measured.
207
+
208
+ ## Limitations
209
+
210
+ - `NativeGrpcFront` only serves unary and server-streaming methods. Other
211
+ kinds can go through the fallback server, and `server()` and `aio.server()`
212
+ send them there for you.
213
+ - There's no TLS yet. `NativeGrpcFront` checks bearer tokens itself, while
214
+ `server()` and `aio.server()` run grpcio interceptors.
215
+ - As with grpc-core, binding a Unix socket path replaces any socket file
216
+ already there.
217
+ - `SO_REUSEPORT` is set only when `grpc.so_reuseport` is 1. grpcio sets it by
218
+ default, so binding a port that another server already uses works with
219
+ grpcio but fails here.
220
+ - Each connection allows up to 1024 concurrent streams unless
221
+ `grpc.max_concurrent_streams` says otherwise. A connection that hasn't
222
+ finished the HTTP/2 preface within 120 s is dropped.
223
+ - A call whose request metadata is over the limit (16 KiB unless set) is
224
+ refused. Between `grpc.max_metadata_size` and that limit, grpcio also
225
+ refuses some calls at random. This server doesn't.
226
+
227
+ ## Compatibility
228
+
229
+ pygrpc-native follows semantic versioning, and the low-level API also stays
230
+ compatible within 0.x:
231
+
232
+ - The 0.1 names, signatures and event tuples of `NativeGrpcFront` won't
233
+ change or go away. `tests/test_api.py` pins them. New parameters are only
234
+ added after the existing ones, with a default.
235
+ - The keys that `metrics()` returns won't be renamed or removed within 0.x,
236
+ though new ones may be added.
237
+ - `server()` and `aio.server()` follow grpcio's API. Any difference from
238
+ grpcio's behavior is a bug unless this README lists it.
239
+
240
+ Changes are listed in [CHANGELOG.md](https://github.com/pygrpc/pygrpc-native/blob/main/CHANGELOG.md).
241
+
242
+ ## Contributing
243
+
244
+ See [CONTRIBUTING.md](https://github.com/pygrpc/pygrpc-native/blob/main/CONTRIBUTING.md).
245
+ Every commit needs a DCO sign-off (`git commit -s`).
246
+
247
+ ## License
248
+
249
+ Apache-2.0
@@ -26,3 +26,5 @@ python-source = "python"
26
26
  module-name = "pygrpc_native._native"
27
27
  # The patched http crate (see Cargo.toml) has to ship in the sdist.
28
28
  include = [{ path = "vendor/**/*", format = "sdist" }]
29
+ # The README's images are served from GitHub.
30
+ exclude = [{ path = "assets/**/*", format = "sdist" }]
@@ -400,9 +400,15 @@ class Server(_Codec, aio.Server):
400
400
  fallback = aio.server(
401
401
  self._executor, interceptors=self._interceptors, options=self._options
402
402
  )
403
- fallback.add_generic_rpc_handlers(generic)
404
- for service, handlers in streamed.items():
405
- fallback.add_registered_method_handlers(service, handlers)
403
+ # grpc.aio ignores add_registered_method_handlers() before grpcio 1.84,
404
+ # so these go in as generic handlers, ahead of the others.
405
+ fallback.add_generic_rpc_handlers(
406
+ [
407
+ grpc.method_handlers_generic_handler(service, handlers)
408
+ for service, handlers in streamed.items()
409
+ ]
410
+ + list(generic)
411
+ )
406
412
  fallback.add_insecure_port(f"unix:{path}")
407
413
  await fallback.start()
408
414
  self._fallback = fallback
@@ -656,6 +656,11 @@ def test_sync_handlers_get_grpcio_sync_context() -> None:
656
656
 
657
657
  async def run(factory: Any, stream_abort: bool) -> dict[str, Any]:
658
658
  server = factory(futures.ThreadPoolExecutor(2))
659
+ # Both, as generated code does: grpc.aio ignores registered handlers
660
+ # before grpcio 1.84.
661
+ server.add_generic_rpc_handlers(
662
+ (grpc.method_handlers_generic_handler("s.S", handlers),)
663
+ )
659
664
  server.add_registered_method_handlers("s.S", handlers)
660
665
  port = server.add_insecure_port("127.0.0.1:0")
661
666
  await server.start()
@@ -359,13 +359,16 @@ def _run(name: str, native: bool) -> dict[str, Any]:
359
359
  async def serve() -> dict[str, Any]:
360
360
  factory = pygrpc_native.aio.server if native else aio.server
361
361
  server = factory(**kwargs)
362
- server.add_registered_method_handlers(
363
- "t.S",
364
- {
365
- "U": grpc.unary_unary_rpc_method_handler(_echo_async),
366
- "S": grpc.unary_stream_rpc_method_handler(_echo_stream_async),
367
- },
362
+ handlers = {
363
+ "U": grpc.unary_unary_rpc_method_handler(_echo_async),
364
+ "S": grpc.unary_stream_rpc_method_handler(_echo_stream_async),
365
+ }
366
+ # Both, as generated code does: grpc.aio ignores registered
367
+ # handlers before grpcio 1.84.
368
+ server.add_generic_rpc_handlers(
369
+ (grpc.method_handlers_generic_handler("t.S", handlers),)
368
370
  )
371
+ server.add_registered_method_handlers("t.S", handlers)
369
372
  port = server.add_insecure_port(bind)
370
373
  await server.start()
371
374
  try:
@@ -353,9 +353,13 @@ def test_aio_interceptors_see_unknown_methods() -> None:
353
353
 
354
354
  async def results(factory: Any) -> dict[str, Any]:
355
355
  server = factory(interceptors=[AioAuth(False)])
356
- server.add_registered_method_handlers(
357
- "i.S", {"Unary": grpc.unary_unary_rpc_method_handler(unary)}
356
+ handlers = {"Unary": grpc.unary_unary_rpc_method_handler(unary)}
357
+ # Both, as generated code does: grpc.aio ignores registered handlers
358
+ # before grpcio 1.84.
359
+ server.add_generic_rpc_handlers(
360
+ (grpc.method_handlers_generic_handler("i.S", handlers),)
358
361
  )
362
+ server.add_registered_method_handlers("i.S", handlers)
359
363
  port = server.add_insecure_port("127.0.0.1:0")
360
364
  await server.start()
361
365
  try: