Skip to main content

CoAkka HTTP Runtime for Python

CoAkka

CoAkka HTTP Runtime provides HTTP server and client APIs for Python. Use it to serve routes, stream responses, handle WebSockets, or call configured upstream services. The wheel includes the native library for your platform.

Install 2.0.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.0.1

On Windows in PowerShell:

py -3 -m venv .venv
.\.venv\Scripts\python.exe -m pip install coakka-http-runtime-python==2.0.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.

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

Builder creates one service. The service supports buffered and streamed requests, streaming responses and trailers, SSE, WebSockets, static files, outbound targets, route updates, and 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.

HTTP Runtime documentation

Metadata

Release files for coakka-http-runtime-python 2.0.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distributions (wheels)

Table of built distributions (wheels) for coakka-http-runtime-python 2.0.1
File Actions
coakka_http_runtime_python-2.0.1-cp311-abi3-win_arm64.whl CPython 3.11 abi3 Windows ARM64 Details for coakka_http_runtime_python-2.0.1-cp311-abi3-win_arm64.whl
coakka_http_runtime_python-2.0.1-cp311-abi3-win_amd64.whl CPython 3.11 abi3 Windows x86-64 Details for coakka_http_runtime_python-2.0.1-cp311-abi3-win_amd64.whl
coakka_http_runtime_python-2.0.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.0.1-cp311-abi3-manylinux_2_28_x86_64.whl
coakka_http_runtime_python-2.0.1-cp311-abi3-manylinux_2_28_aarch64.whl CPython 3.11 abi3 Linux glibc 2.28+ ARM64 Details for coakka_http_runtime_python-2.0.1-cp311-abi3-manylinux_2_28_aarch64.whl
coakka_http_runtime_python-2.0.1-cp311-abi3-macosx_11_0_arm64.whl CPython 3.11 abi3 macOS 11.0+ ARM64 Details for coakka_http_runtime_python-2.0.1-cp311-abi3-macosx_11_0_arm64.whl

Total release size: 19.0 MB

Release files / coakka_http_runtime_python-2.0.1-cp311-abi3-win_arm64.whl

Download URL coakka_http_runtime_python-2.0.1-cp311-abi3-win_arm64.whl
Size 3.1 MB
Tags CPython 3.11 Windows ARM64 abi3
SHA-256 checksum
How to use checksums
fa2c50ba5dbe262ac53f18d78007d63805e0517d70de216e4c224acb1f73bf45
BLAKE2b-256 checksum
How to use checksums
bcf5ba451fdd30b592ba0899a24ddda0c2886a4106fe1d721b234f2f24c4e8b2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.4

Release files / coakka_http_runtime_python-2.0.1-cp311-abi3-win_amd64.whl

Download URL coakka_http_runtime_python-2.0.1-cp311-abi3-win_amd64.whl
Size 3.7 MB
Tags CPython 3.11 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
8232d98d13e734718df9bec51363d6874cef118126f6fd9fc21bc18c00b442b8
BLAKE2b-256 checksum
How to use checksums
6b8f44e7438a085a8ee30d6f5e21e7958b83f8d3522c9fb1023674970dbf5423
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.4

Release files / coakka_http_runtime_python-2.0.1-cp311-abi3-manylinux_2_28_x86_64.whl

Download URL coakka_http_runtime_python-2.0.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
8442be7cbd094cb33f0e04d1757f00b4899ac47d5a4d04c5ac77d13e1859515a
BLAKE2b-256 checksum
How to use checksums
1f081d103572b235d6050f5736cc17e4cfb8a3254cecae67aaa2d6002f733b6d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.4

Release files / coakka_http_runtime_python-2.0.1-cp311-abi3-manylinux_2_28_aarch64.whl

Download URL coakka_http_runtime_python-2.0.1-cp311-abi3-manylinux_2_28_aarch64.whl
Size 4.5 MB
Tags CPython 3.11 Linux glibc 2.28+ ARM64 abi3
SHA-256 checksum
How to use checksums
a09df03e8757ce961f89be1410404ef8c66ee8f2e32b93470da9e28b611c35f0
BLAKE2b-256 checksum
How to use checksums
6877e80144b90fd29b21a30795a907ddbe80da1c684f4c4e4ce64cfbcf5aa3a3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.4

Release files / coakka_http_runtime_python-2.0.1-cp311-abi3-macosx_11_0_arm64.whl

Download URL coakka_http_runtime_python-2.0.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
4086c0c3aeeb1241e5f90f0e197f82cdbd0d8606fd10d151edbddc36d4f9bdf9
BLAKE2b-256 checksum
How to use checksums
90dbd4d4efe88beb450fc98e00cacc184f16281932575aecc3ad76d2f7fd91b4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.4

Security for coakka-http-runtime-python 2.0.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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page