CoAkka HTTP Runtime for Python
CoAkka HTTP Runtime is an embeddable HTTP server and client for Python. Use Python handlers to serve HTTP APIs, stream responses, handle WebSockets or call upstream services. The wheel includes the shared native HTTP core for your platform.
The CoAkka ecosystem provides polyglot tools for distributed applications, HTTP services and logging. CoAkka HTTP Runtime is the HTTP product and can be adopted independently.
CoAkka ecosystem · Raspberry Pi 5 benchmarks
Install 2.2.1
Run these commands from your application directory with CPython 3.11 or newer.
On macOS or Linux:
python3 -m venv .venv
.venv/bin/python -m pip install coakka-http-runtime-python==2.2.1
On Windows in PowerShell:
py -3 -m venv .venv
.\.venv\Scripts\python.exe -m pip install coakka-http-runtime-python==2.2.1
Install coakka-http-runtime-python with pip and import coakka_http
in your application.
First request
Save this example as server.py.
from coakka_http import Builder, Request, Response
def echo(request: Request) -> Response:
return Response(status=201, body=request.body)
def main() -> None:
service = Builder().listen("127.0.0.1", 8080).post("/echo", echo).start()
with service:
print(f"Listening on http://127.0.0.1:{service.port}")
input("Press Enter to stop. ")
if __name__ == "__main__":
main()
Run .venv/bin/python server.py on macOS or Linux, or
.\.venv\Scripts\python.exe server.py on Windows. From a second terminal,
send a request with the following command.
curl -i --data "hello" http://127.0.0.1:8080/echo
In Windows PowerShell, use curl.exe. The server returns HTTP 201 with
hello in the response body. Press Enter in the server terminal to shut
it down. The service context manager closes the runtime when the block exits.
Requirements
| Platform | Architecture | Requirement |
|---|---|---|
| macOS | ARM64 | macOS 11 or newer |
| Linux | x86-64 and ARM64 | glibc 2.28 or newer |
| Windows | x64 and ARM64 | CPython matching the wheel architecture |
If pip cannot find a matching wheel, run python -VV and
python -c "import platform; print(platform.machine())" with the interpreter
you plan to use. Install and run the package with that interpreter.
Choose an HTTP version
Builder.listen() in the first example starts a plain HTTP/1.1 listener.
For HTTP/2 or HTTP/3, generate the local TLS files
and pass a Listener to the builder instead. For example:
from coakka_http import Builder, Listener, ListenerProtocol, TransportSecurity
builder = Builder().listener(
Listener(
port=8443,
protocol=ListenerProtocol.HTTP_2,
security=TransportSecurity.TLS,
credential_id="local-example",
credential_generation=1,
certificate_chain_file="http-test-tls/server.pem",
private_key_file="http-test-tls/server.key",
)
)
Register your routes on builder, then call start(). Use
ListenerProtocol.HTTP_3 to serve HTTP/3 over UDP. The
complete Python sample runs all 3 modes separately.
Python 2.2.1 does not expose the same-port V1 profile.
HTTP/1.1 · HTTP/2 · HTTP/3 · All 3 on one port
Outbound requests
Keep the first server running. Save this example as client.py and run
it with the same virtual environment's Python. It sends a request to the
configured loopback endpoint and prints 201 hello.
from coakka_http import (
Builder,
OutboundEndpoint,
OutboundReason,
OutboundRequest,
OutboundTarget,
)
def main() -> None:
endpoint = OutboundEndpoint(
node_id="local",
connect_host="127.0.0.1",
connect_port=8080,
http_authority="127.0.0.1:8080",
)
target = OutboundTarget(name="echo", generation=1, endpoints=(endpoint,))
with Builder().outbound_target(target).start() as service:
call = service.outbound_submit(
OutboundRequest("echo", "POST", "/echo", body=b"hello", timeout_ms=3000)
)
result = service.take_outbound(5000)
if result is None:
raise TimeoutError("No outbound result within five seconds")
if result.call != call or result.reason is not OutboundReason.RESPONSE:
raise RuntimeError(f"Outbound request ended with {result.reason.name}")
print(result.response_status, result.response_body.decode("utf-8"))
if __name__ == "__main__":
main()
connect_host selects the connection destination and http_authority
sets the HTTP authority. For TLS, configure the peer identity and trust
for the endpoint. A received HTTP error still arrives as a response with
its HTTP status. Use the terminal reason to distinguish transport and
lifecycle outcomes.
API reference
- Python integration guide
- Runnable Python samples
- Feature recipes and coverage
- URL grammar and glossary
- I/O backend
- Lower-level API
- Ownership and bounds
Builder creates one service. The service supports buffered and streamed
requests, streaming responses and trailers, SSE, WebSockets, static files,
outbound targets, generation-checked route updates, TLS and mTLS, and
bounded monitoring.
service.routes returns the runtime's route generation and binding
revisions. Use effective_limits() and runtime_info() to inspect the
configuration accepted by the runtime. Use
Builder.compression(Compression(CompressionMode.GZIP)) to enable buffered
response compression.
I/O backend
The service uses the platform's default I/O backend. On Linux, applications can request io_uring explicitly.
from coakka_http import Builder, IoBackend, Response
service = (
Builder()
.io_backend(IoBackend.IO_URING)
.get("/health", lambda _request: Response())
.start()
)
try:
info = service.runtime_info()
print(info.io_uring_requested, info.io_uring_effective, info.fallback_reason)
finally:
service.close()
The native runtime checks availability and uses the platform default when
the request cannot be applied. Read io_uring_effective to see the backend
in use and fallback_reason for the outcome of the request.
Lower-level API
Runtime accepts one immutable RuntimeConfig and returns copied events.
from coakka_http import EventKind, Response, Route, Runtime, RuntimeConfig
configuration = RuntimeConfig(routes=(Route(41, "POST", "/items/{id}", 101),))
with Runtime(configuration) as runtime:
runtime.start()
event = runtime.take_event(5_000)
if event is not None and event.kind is EventKind.REQUEST:
runtime.respond(event.exchange, Response(status=202, body=b"accepted"))
Each blocking inbound, WebSocket, outbound, and monitor lane allows one reader.
All native views are copied during the call; no borrowed pointer escapes into
Python. Failures are NativeError values with a stable numeric status and a
bounded diagnostic.
Ownership and bounds
Worker count, queued request count, retained bytes, stream items, handler bindings, active exchanges, monitor pages, and shutdown time are finite. Returning a streaming response gives one callback-scoped writer to its producer. Pressure waits for native recovery credit and retries only the exact rejected item.
Service.close() stops admission, wakes readers, joins connector workers, and
destroys native ownership only when no Python code can still reach it. If a
handler exceeds the deadline, close raises and retains the owner for a safe
retry. The operation is serialized and idempotent.
Monitoring is disabled by default. Enabling it reserves fixed storage during construction. Signals are hints; callers pull immutable snapshots. Monitoring pressure cannot block request handling or change an exchange result.
Metadata
Release files for coakka-http-runtime-python 2.2.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distributions (wheels)
| File | Actions Reset | |||
|---|---|---|---|---|
| coakka_http_runtime_python-2.2.1-cp311-abi3-win_arm64.whl | CPython 3.11 | abi3 | Windows ARM64 | Details for coakka_http_runtime_python-2.2.1-cp311-abi3-win_arm64.whl |
| coakka_http_runtime_python-2.2.1-cp311-abi3-win_amd64.whl | CPython 3.11 | abi3 | Windows x86-64 | Details for coakka_http_runtime_python-2.2.1-cp311-abi3-win_amd64.whl |
| coakka_http_runtime_python-2.2.1-cp311-abi3-manylinux_2_28_x86_64.whl | CPython 3.11 | abi3 | Linux glibc 2.28+ x86-64 | Details for coakka_http_runtime_python-2.2.1-cp311-abi3-manylinux_2_28_x86_64.whl |
| coakka_http_runtime_python-2.2.1-cp311-abi3-manylinux_2_28_aarch64.whl | CPython 3.11 | abi3 | Linux glibc 2.28+ ARM64 | Details for coakka_http_runtime_python-2.2.1-cp311-abi3-manylinux_2_28_aarch64.whl |
| coakka_http_runtime_python-2.2.1-cp311-abi3-macosx_11_0_arm64.whl | CPython 3.11 | abi3 | macOS 11.0+ ARM64 | Details for coakka_http_runtime_python-2.2.1-cp311-abi3-macosx_11_0_arm64.whl |
Total release size: 19.5 MB
Release files / coakka_http_runtime_python-2.2.1-cp311-abi3-win_arm64.whl
| Download URL | coakka_http_runtime_python-2.2.1-cp311-abi3-win_arm64.whl |
|---|---|
| Size | 3.1 MB |
| Tags | CPython 3.11 Windows ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
fcf0857871ca5f16d44ec9e8946d2a50447ba118a818565ccb2ec3fb93771061
|
|
BLAKE2b-256 checksum How to use checksums |
92ae75e332ac20fcf381ff295a612f943c0338a11285a9f9213cff1dce8b757d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.3
|
Release files / coakka_http_runtime_python-2.2.1-cp311-abi3-win_amd64.whl
| Download URL | coakka_http_runtime_python-2.2.1-cp311-abi3-win_amd64.whl |
|---|---|
| Size | 3.8 MB |
| Tags | CPython 3.11 Windows x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
3efe88269355b023cdc9d7392d671f9878ec10ae92d51eae81c97b6add5ca6ce
|
|
BLAKE2b-256 checksum How to use checksums |
6ef97442626a61c72aa0009f67a5951d51201529a5c92beacb713c39282f9e69
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.3
|
Release files / coakka_http_runtime_python-2.2.1-cp311-abi3-manylinux_2_28_x86_64.whl
| Download URL | coakka_http_runtime_python-2.2.1-cp311-abi3-manylinux_2_28_x86_64.whl |
|---|---|
| Size | 4.3 MB |
| Tags | CPython 3.11 Linux glibc 2.28+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
e2709aacd0b2127838a5e9faa90224151eff9c0a3bb62fedd12d4638bc5a4b0e
|
|
BLAKE2b-256 checksum How to use checksums |
93ba9084a73304a406e2eee1990baf6c7f0d2c05b40f618182a7b9d0d9b3d609
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.3
|
Release files / coakka_http_runtime_python-2.2.1-cp311-abi3-manylinux_2_28_aarch64.whl
| Download URL | coakka_http_runtime_python-2.2.1-cp311-abi3-manylinux_2_28_aarch64.whl |
|---|---|
| Size | 4.6 MB |
| Tags | CPython 3.11 Linux glibc 2.28+ ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
c5e0304c73751daee2c79f33172a3daf668e8849809f048af4869872b6f3af6f
|
|
BLAKE2b-256 checksum How to use checksums |
f402d708d7f2b65b7b4fdae1d30c69b8cb402739022c0c8a1f3788d42d425036
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.3
|
Release files / coakka_http_runtime_python-2.2.1-cp311-abi3-macosx_11_0_arm64.whl
| Download URL | coakka_http_runtime_python-2.2.1-cp311-abi3-macosx_11_0_arm64.whl |
|---|---|
| Size | 3.5 MB |
| Tags | CPython 3.11 abi3 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
489083f77c1935be5a441aa6b9064c33c36d43da0adccd1839ae1242e541f511
|
|
BLAKE2b-256 checksum How to use checksums |
ae6a8a601dc06f8a3878eed9a21a8472ed9e2a819cddb63ae08cd2e7aadb9e0c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.3
|
Security for coakka-http-runtime-python 2.2.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.