Benzene for Python — Documentation

A Python port of Benzene, the middleware-based framework for hexagonal (ports-and-adapters) architecture: write your message handlers once, host them anywhere. This port is spec-first — it implements the language-neutral Benzene specification idiomatically in Python and interoperates on the wire with the .NET, Go, and TypeScript ports.

Start here

• Getting started — from an empty folder to a running HTTP service in a few minutes.
• Packages & adoption levels — how Benzene is split into layered PyPI packages, why, and which ones to install.

Reference

• benzene.results — the Result type and the status vocabulary.
• benzene.core — handlers, the @message decorator, the registry, the middleware pipeline, dependency injection, the outbound client port, and the BenzeneMessage envelope.
• benzene.http — the inbound HTTP (ASGI) transport binding.
• benzene.gcp — the Google Cloud Functions host (HTTP + Pub/Sub).
• benzene.aws — the AWS Lambda host (API Gateway + SQS + SNS).
• benzene.azure — the Azure Functions host (HTTP + Service Bus + Event Hub).
• benzene.testing — the in-memory test host and test doubles.

Guides & cookbooks

• Hosting on Google Cloud Functions — one set of handlers behind HTTP + Pub/Sub triggers, with Pub/Sub egress.
• Hosting on AWS Lambda — one function across API Gateway + SQS + SNS, with SNS egress.
• Hosting on Azure Functions — HTTP + Service Bus + Event Hub triggers, with Service Bus egress.
• Examples — runnable, multi-transport cloud examples, each with dogfooded tests.

Concepts & the spec

Benzene Python is faithful to the language-neutral specification. The authoritative documents live in the main Benzene repository:

• core-concepts — Result, Topic, the middleware pipeline, DI, the lifecycle.
• wire-contracts — the message envelope, the status vocabulary, and the HTTP status mapping.
• transport-bindings — what a transport binding must satisfy (the HTTP binding is the first one ported here).

Status

Core + the inbound HTTP binding are implemented and conformance-green. A cloud host, the mesh module, and payload versioning are on the roadmap.