pygrpc-native 0.5.0__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.0 → pygrpc_native-0.5.2}/.github/workflows/ci.yml +13 -1
  2. {pygrpc_native-0.5.0 → pygrpc_native-0.5.2}/CHANGELOG.md +15 -0
  3. {pygrpc_native-0.5.0 → pygrpc_native-0.5.2}/Cargo.lock +1 -1
  4. {pygrpc_native-0.5.0 → 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.0 → pygrpc_native-0.5.2}/pyproject.toml +2 -0
  8. {pygrpc_native-0.5.0 → pygrpc_native-0.5.2}/python/pygrpc_native/__init__.py +5 -6
  9. {pygrpc_native-0.5.0 → pygrpc_native-0.5.2}/python/pygrpc_native/aio.py +9 -3
  10. {pygrpc_native-0.5.0 → pygrpc_native-0.5.2}/tests/test_aio.py +15 -0
  11. {pygrpc_native-0.5.0 → pygrpc_native-0.5.2}/tests/test_connection.py +6 -5
  12. {pygrpc_native-0.5.0 → pygrpc_native-0.5.2}/tests/test_downstream.py +9 -6
  13. {pygrpc_native-0.5.0 → pygrpc_native-0.5.2}/tests/test_interceptors.py +6 -2
  14. pygrpc_native-0.5.0/PKG-INFO +0 -196
  15. pygrpc_native-0.5.0/README.md +0 -181
  16. {pygrpc_native-0.5.0 → pygrpc_native-0.5.2}/.github/CODEOWNERS +0 -0
  17. {pygrpc_native-0.5.0 → pygrpc_native-0.5.2}/.github/ISSUE_TEMPLATE/bug_report.md +0 -0
  18. {pygrpc_native-0.5.0 → pygrpc_native-0.5.2}/.github/ISSUE_TEMPLATE/config.yml +0 -0
  19. {pygrpc_native-0.5.0 → pygrpc_native-0.5.2}/.github/ISSUE_TEMPLATE/feature_request.md +0 -0
  20. {pygrpc_native-0.5.0 → pygrpc_native-0.5.2}/.github/PULL_REQUEST_TEMPLATE.md +0 -0
  21. {pygrpc_native-0.5.0 → pygrpc_native-0.5.2}/.github/dependabot.yml +0 -0
  22. {pygrpc_native-0.5.0 → pygrpc_native-0.5.2}/.github/workflows/dco.yml +0 -0
  23. {pygrpc_native-0.5.0 → pygrpc_native-0.5.2}/.github/workflows/release.yml +0 -0
  24. {pygrpc_native-0.5.0 → pygrpc_native-0.5.2}/.github/workflows/stale.yml +0 -0
  25. {pygrpc_native-0.5.0 → pygrpc_native-0.5.2}/.gitignore +0 -0
  26. {pygrpc_native-0.5.0 → pygrpc_native-0.5.2}/.pre-commit-config.yaml +0 -0
  27. {pygrpc_native-0.5.0 → pygrpc_native-0.5.2}/CODE_OF_CONDUCT.md +0 -0
  28. {pygrpc_native-0.5.0 → pygrpc_native-0.5.2}/CONTRIBUTING.md +0 -0
  29. {pygrpc_native-0.5.0 → pygrpc_native-0.5.2}/DCO +0 -0
  30. {pygrpc_native-0.5.0 → pygrpc_native-0.5.2}/LICENSE +0 -0
  31. {pygrpc_native-0.5.0 → pygrpc_native-0.5.2}/SECURITY.md +0 -0
  32. {pygrpc_native-0.5.0 → pygrpc_native-0.5.2}/benchmarks/README.md +0 -0
  33. {pygrpc_native-0.5.0 → pygrpc_native-0.5.2}/benchmarks/echo.py +0 -0
  34. {pygrpc_native-0.5.0 → pygrpc_native-0.5.2}/docs/low-level-api.md +0 -0
  35. {pygrpc_native-0.5.0 → pygrpc_native-0.5.2}/python/pygrpc_native/_native.pyi +0 -0
  36. {pygrpc_native-0.5.0 → pygrpc_native-0.5.2}/python/pygrpc_native/_server.py +0 -0
  37. {pygrpc_native-0.5.0 → pygrpc_native-0.5.2}/python/pygrpc_native/py.typed +0 -0
  38. {pygrpc_native-0.5.0 → pygrpc_native-0.5.2}/src/lib.rs +0 -0
  39. {pygrpc_native-0.5.0 → pygrpc_native-0.5.2}/src/metrics.rs +0 -0
  40. {pygrpc_native-0.5.0 → pygrpc_native-0.5.2}/src/server.rs +0 -0
  41. {pygrpc_native-0.5.0 → pygrpc_native-0.5.2}/tests/test_add_methods.py +0 -0
  42. {pygrpc_native-0.5.0 → pygrpc_native-0.5.2}/tests/test_api.py +0 -0
  43. {pygrpc_native-0.5.0 → pygrpc_native-0.5.2}/tests/test_bearer_auth.py +0 -0
  44. {pygrpc_native-0.5.0 → pygrpc_native-0.5.2}/tests/test_call_details.py +0 -0
  45. {pygrpc_native-0.5.0 → pygrpc_native-0.5.2}/tests/test_calls.py +0 -0
  46. {pygrpc_native-0.5.0 → pygrpc_native-0.5.2}/tests/test_delay_stream_headers.py +0 -0
  47. {pygrpc_native-0.5.0 → pygrpc_native-0.5.2}/tests/test_fallback.py +0 -0
  48. {pygrpc_native-0.5.0 → pygrpc_native-0.5.2}/tests/test_front.py +0 -0
  49. {pygrpc_native-0.5.0 → pygrpc_native-0.5.2}/tests/test_metrics.py +0 -0
  50. {pygrpc_native-0.5.0 → pygrpc_native-0.5.2}/tests/test_response_metadata.py +0 -0
  51. {pygrpc_native-0.5.0 → pygrpc_native-0.5.2}/tests/test_server.py +0 -0
  52. {pygrpc_native-0.5.0 → pygrpc_native-0.5.2}/tests/test_stream_try_send.py +0 -0
  53. {pygrpc_native-0.5.0 → pygrpc_native-0.5.2}/vendor/http/CHANGELOG.md +0 -0
  54. {pygrpc_native-0.5.0 → pygrpc_native-0.5.2}/vendor/http/Cargo.toml +0 -0
  55. {pygrpc_native-0.5.0 → pygrpc_native-0.5.2}/vendor/http/LICENSE-APACHE +0 -0
  56. {pygrpc_native-0.5.0 → pygrpc_native-0.5.2}/vendor/http/LICENSE-MIT +0 -0
  57. {pygrpc_native-0.5.0 → pygrpc_native-0.5.2}/vendor/http/README.md +0 -0
  58. {pygrpc_native-0.5.0 → pygrpc_native-0.5.2}/vendor/http/src/byte_str.rs +0 -0
  59. {pygrpc_native-0.5.0 → pygrpc_native-0.5.2}/vendor/http/src/convert.rs +0 -0
  60. {pygrpc_native-0.5.0 → pygrpc_native-0.5.2}/vendor/http/src/error.rs +0 -0
  61. {pygrpc_native-0.5.0 → pygrpc_native-0.5.2}/vendor/http/src/extensions.rs +0 -0
  62. {pygrpc_native-0.5.0 → pygrpc_native-0.5.2}/vendor/http/src/header/map.rs +0 -0
  63. {pygrpc_native-0.5.0 → pygrpc_native-0.5.2}/vendor/http/src/header/mod.rs +0 -0
  64. {pygrpc_native-0.5.0 → pygrpc_native-0.5.2}/vendor/http/src/header/name.rs +0 -0
  65. {pygrpc_native-0.5.0 → pygrpc_native-0.5.2}/vendor/http/src/header/value.rs +0 -0
  66. {pygrpc_native-0.5.0 → pygrpc_native-0.5.2}/vendor/http/src/lib.rs +0 -0
  67. {pygrpc_native-0.5.0 → pygrpc_native-0.5.2}/vendor/http/src/method.rs +0 -0
  68. {pygrpc_native-0.5.0 → pygrpc_native-0.5.2}/vendor/http/src/request.rs +0 -0
  69. {pygrpc_native-0.5.0 → pygrpc_native-0.5.2}/vendor/http/src/response.rs +0 -0
  70. {pygrpc_native-0.5.0 → pygrpc_native-0.5.2}/vendor/http/src/status.rs +0 -0
  71. {pygrpc_native-0.5.0 → pygrpc_native-0.5.2}/vendor/http/src/uri/authority.rs +0 -0
  72. {pygrpc_native-0.5.0 → pygrpc_native-0.5.2}/vendor/http/src/uri/builder.rs +0 -0
  73. {pygrpc_native-0.5.0 → pygrpc_native-0.5.2}/vendor/http/src/uri/mod.rs +0 -0
  74. {pygrpc_native-0.5.0 → pygrpc_native-0.5.2}/vendor/http/src/uri/path.rs +0 -0
  75. {pygrpc_native-0.5.0 → pygrpc_native-0.5.2}/vendor/http/src/uri/port.rs +0 -0
  76. {pygrpc_native-0.5.0 → pygrpc_native-0.5.2}/vendor/http/src/uri/scheme.rs +0 -0
  77. {pygrpc_native-0.5.0 → pygrpc_native-0.5.2}/vendor/http/src/uri/tests.rs +0 -0
  78. {pygrpc_native-0.5.0 → pygrpc_native-0.5.2}/vendor/http/src/version.rs +0 -0
  79. {pygrpc_native-0.5.0 → pygrpc_native-0.5.2}/vendor/http/tests/header_map.rs +0 -0
  80. {pygrpc_native-0.5.0 → pygrpc_native-0.5.2}/vendor/http/tests/header_map_fuzz.rs +0 -0
  81. {pygrpc_native-0.5.0 → 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,21 @@ 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
+
15
+ ## 0.5.1 (2026-10-27)
16
+
17
+ ### Fixed
18
+
19
+ - `from pygrpc_native import aio`, and `pygrpc_native.aio` after a plain
20
+ `import pygrpc_native`, no longer fail with `RecursionError`. (#61)
21
+
7
22
  ## 0.5.0 (2026-10-27)
8
23
 
9
24
  Everything here is an addition, so code written for 0.4 keeps working.
@@ -395,7 +395,7 @@ dependencies = [
395
395
 
396
396
  [[package]]
397
397
  name = "pygrpc_native"
398
- version = "0.5.0"
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.0"
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" }]
@@ -1,3 +1,4 @@
1
+ import importlib
1
2
  from typing import TYPE_CHECKING
2
3
 
3
4
  from pygrpc_native._native import (
@@ -30,12 +31,10 @@ __all__ = [
30
31
 
31
32
  def __getattr__(name: str):
32
33
  # The grpcio-compatible servers need grpcio; the low-level API doesn't.
34
+ # import_module, not "from pygrpc_native import ...": that looks the name
35
+ # up on this module first and lands back here.
33
36
  if name in ("Server", "server"):
34
- from pygrpc_native import _server
35
-
36
- return getattr(_server, name)
37
+ return getattr(importlib.import_module("pygrpc_native._server"), name)
37
38
  if name == "aio":
38
- from pygrpc_native import aio
39
-
40
- return aio
39
+ return importlib.import_module("pygrpc_native.aio")
41
40
  raise AttributeError(f"module 'pygrpc_native' has no attribute {name!r}")
@@ -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
@@ -2,6 +2,7 @@
2
2
 
3
3
  import asyncio
4
4
  import importlib
5
+ import subprocess
5
6
  import sys
6
7
  from collections.abc import AsyncIterator, Callable, Iterator
7
8
  from concurrent import futures
@@ -554,6 +555,15 @@ def test_module_attribute() -> None:
554
555
  assert isinstance(pygrpc_native.aio.server(), aio.Server)
555
556
 
556
557
 
558
+ @pytest.mark.parametrize(
559
+ "code",
560
+ ["from pygrpc_native import aio", "import pygrpc_native; pygrpc_native.aio"],
561
+ )
562
+ def test_aio_reached_from_the_package(code: str) -> None:
563
+ # A fresh interpreter: this one has imported pygrpc_native.aio already.
564
+ subprocess.run([sys.executable, "-c", code], check=True, timeout=60)
565
+
566
+
557
567
  def test_slow_reader_gets_every_message(pb: tuple[Any, Any]) -> None:
558
568
  a_pb2, a_pb2_grpc = pb
559
569
  chunk = "x" * (1 << 20)
@@ -646,6 +656,11 @@ def test_sync_handlers_get_grpcio_sync_context() -> None:
646
656
 
647
657
  async def run(factory: Any, stream_abort: bool) -> dict[str, Any]:
648
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
+ )
649
664
  server.add_registered_method_handlers("s.S", handlers)
650
665
  port = server.add_insecure_port("127.0.0.1:0")
651
666
  await server.start()