Skip to main content

ankka-flow for Python

Write ankka-flow streamlets in Python. You declare ports and parameters and implement process; the sidecar the platform runs beside your container owns everything Kafka.

from collections.abc import Iterable
from ankka_flow import Batch, Emit, IntegerParameter, JsonInlet, JsonOutlet, Streamlet, json, serve

class CartRouter(Streamlet):
    name = "cart-router"
    inlet = JsonInlet("in", schema_name="cart-events.v1")
    valid = JsonOutlet("valid", schema_name="cart-events.v1")
    review = JsonOutlet("review", schema_name="cart-events.v1")
    threshold = IntegerParameter("review-threshold", default=100)

    def process(self, batch: Batch) -> Iterable[Emit]:
        for record in batch:
            event = json.loads(record.value)
            yield (self.review if event["total"] > self.config[self.threshold] else self.valid).emit(record)

if __name__ == "__main__":
    serve(CartRouter())          # 127.0.0.1:$FLOW_PROCESS_PORT (9010), loopback only
  • process runs once per batch on a worker thread. One batch per partition is in flight at a time, so it never runs twice for one partition at once; different partitions run concurrently.
  • Returning acknowledges the batch. Raising fails it, and the sidecar redelivers it from the last commit. Yielding nothing for a record skips it.
  • Records are bytes with a key and headers. The SDK decodes nothing; ankka_flow.json helps.

Descriptor

uv run descriptor writes flow/descriptor.json from the streamlet named by [tool.ankka-flow] streamlet = "module:Class" in your pyproject.toml (or $FLOW_STREAMLET). Commit it. uv run descriptor --check fails when it is stale. The format is proto/DESCRIPTOR.md.

Testing without Kafka

from ankka_flow.testkit import Harness

h = Harness(CartRouter(), config={"review-threshold": 50})
h.inlet("in").put(key=b"cart-1", value=b'{"total": 10}')
h.run()
assert [r.key for r in h.outlet("valid").records] == [b"cart-1"]

Developing the SDK

uv sync
uv run python scripts/proto.py   # copy ../../protocol into proto/ (committed) and generate src/ankka_flow/_proto/
uv run mypy                      # strict
uv run pytest -q                 # fixtures, the server against a scripted sidecar, the harness
uv run conformance               # the reference streamlet against the platform's conformance suite

proto/ must equal ../../protocol byte for byte; CI diffs it. tests/test_descriptor_fixtures.py proves this SDK writes every fixture descriptor exactly.

A new project starts from template/, which carries a compose file with Kafka and the sidecar for the laptop loop.

Conformance

uv run conformance serves the reference streamlet (ankka_flow._conformance) on 127.0.0.1:$FLOW_PROCESS_PORT and runs the sidecar's conformance suite against it from the repository root (sbt and a JDK are needed). Last run: every one of the 18 cases that apply to an SDK passes; the five violation.* and version.* cases are skipped, as they only run against the Scala double.

Two deliberate breaks prove the suite points at what broke:

ANKKA_FLOW_BREAK what it breaks cases that fail
keyless-empty-key a keyless emit carries an empty key exactly run.unkeyed-emit (SC-005)
ack-first the ack is sent before the batch's emits the 12 cases that emit, run.emits-precede-ack among them

Metadata

Release files for ankka-flow 0.3.0

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

Source distribution (sdist)

Source distribution for ankka-flow 0.3.0
File Size Uploaded Provenance Actions
ankka_flow-0.3.0.tar.gz 75.3 kB With provenance Details for ankka_flow-0.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for ankka-flow 0.3.0
File Interpreter ABI Platform Actions
ankka_flow-0.3.0-py3-none-any.whl Python 3 none any Details for ankka_flow-0.3.0-py3-none-any.whl

Total release size: 109.2 kB

Release files / ankka_flow-0.3.0.tar.gz

Download URL ankka_flow-0.3.0.tar.gz
Size 75.3 kB
Tags Source
SHA-256 checksum
How to use checksums
d0a59e62b7cf0dec122177ceb7287382217e0637bc42526a587c07de4bfdf299
BLAKE2b-256 checksum
How to use checksums
cfe6c4ae2efc01859a291ba0ba46dfdec0107b29cedceb2dc3690ff731306c2d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 1, 2026.

Transparency log

Release files / ankka_flow-0.3.0-py3-none-any.whl

Download URL ankka_flow-0.3.0-py3-none-any.whl
Size 33.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
6e87301a409dcf71efe81045f8ad5c5275766987bd6af5ab7876de3bfb29efd3
BLAKE2b-256 checksum
How to use checksums
0489f22a6649b452bdc152352ab1fc28f608f8c1b2bac27f8f5ba1dc3a6efacf
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 1, 2026.

Transparency log

Security for ankka-flow 0.3.0

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.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for ankka_flow-0.3.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 1, 2026.

Transparency log

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