biffo-plugin-sdk

The Python SDK for building Biffo plugins: manifest validation, a Core API client, and the event subscription system.

A Biffo plugin is a Lambda-deployed Python package that extends a Biffo instance. It declares its tables, routes and event subscriptions in a biffo.plugin.json manifest, and reaches platform data only through the Core API — never through a database client of its own (ADR-0002). This SDK is the supported way to do both.

Install

pip install biffo-plugin-sdk

Outside AWS Lambda, install the sigv4 extra as well:

pip install "biffo-plugin-sdk[sigv4]"

botocore — needed to sign requests to the Core API — is an extra rather than a hard dependency because it is preinstalled in the AWS Lambda Python runtime, so a deployed plugin already has it. The SDK imports it lazily, so import biffo_plugin_sdk works without it.

Versioning

This package carries its own semantic version, independent of the Biffo template's core.version. It is a public API contract for plugin authors: a major bump here means the plugin API broke, and nothing else. Plugin manifests declare "biffo-plugin-sdk": "^1.0" and plugin pyproject.toml files pin biffo-plugin-sdk>=1.0,<2.0.

Quick start

from biffo_plugin_sdk import BiffoEvent, BiffoPluginBase, load_manifest


class MyPlugin(BiffoPluginBase):
    def __init__(self) -> None:
        super().__init__(load_manifest("biffo.plugin.json"))

        @self.subscribe("user.created")
        async def on_user_created(event: BiffoEvent) -> None:
            await self.api.post(
                "/api/v1/internal/welcome", json={"user": event.detail}
            )

    def on_install(self) -> None: ...

    def on_uninstall(self) -> None: ...

Handlers are registered against self.events, an EventSubscriber private to the instance. In the Lambda entrypoint, turn the raw EventBridge payload into a BiffoEvent and dispatch it:

from biffo_plugin_sdk import create_event_handler

plugin = MyPlugin()


async def handler(raw_event: dict, context: object) -> None:
    await plugin.events.dispatch(create_event_handler(raw_event))

self.api is built by create_core_client() and defaults to a SignedCoreClient — every request is signed with AWS SigV4 using the plugin Lambda's role, which is the plugin→Core auth mechanism (ADR-0009). Set BIFFO_CORE_AUTH_MODE=none for an unsigned client in local runs and tests.

Public API

Export	What it is
`BiffoPluginBase`	Base class for a plugin; owns `self.api` and the `subscribe`/`subscribe_all` decorators
`PluginManifest`, `load_manifest`, `register_plugin`	Manifest model and loaders — the authoritative validator for `biffo.plugin.json`
`TableDefinition`, `ColumnDefinition`, `IndexDefinition`, `TablePermissions`, `PermissionRule`, `RouteDef`	Manifest sub-models
`BiffoAPIClient`, `BiffoAPIError`	Unauthenticated async Core API transport, and its single error type
`SignedCoreClient`, `create_core_client`	SigV4-signing client (ADR-0009) and the factory that picks it by default
`BiffoEvent`, `EventSubscriber`, `create_event_handler`	Event model, dispatch registry, and the raw-EventBridge-payload parser

Environment

Variable	Read by	Purpose
`BIFFO_CORE_API_URL`	`BiffoAPIClient`	Core API base URL; injected into the plugin Lambda by `modules/plugins/_template`
`AWS_REGION`	`SignedCoreClient`	Region to sign for
`BIFFO_CORE_AUTH_MODE`	`create_core_client`	`sigv4` (default) or `none`

Documentation

License

MIT — see LICENSE.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

biffo_plugin_sdk-1.0.0.tar.gz (27.3 kB view details)

Uploaded Jul 20, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

biffo_plugin_sdk-1.0.0-py3-none-any.whl (18.3 kB view details)

Uploaded Jul 20, 2026 Python 3

File details

Details for the file biffo_plugin_sdk-1.0.0.tar.gz.

File metadata

Download URL: biffo_plugin_sdk-1.0.0.tar.gz
Upload date: Jul 20, 2026
Size: 27.3 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for biffo_plugin_sdk-1.0.0.tar.gz
Algorithm	Hash digest
SHA256	`7568f3867109b452be3bfa787290d0eb92ff7af0476681ffc83c8677992b25ba`
MD5	`5233af05ad946b36dd8613c1008ad147`
BLAKE2b-256	`89c8a82bd500c12a5923f85286dea8a29e8e830a432c9353e755b22af2ffb178`

See more details on using hashes here.

Provenance

The following attestation bundles were made for biffo_plugin_sdk-1.0.0.tar.gz:

Publisher: publish-sdk.yml on keiranholloway/biffo-template

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: biffo_plugin_sdk-1.0.0.tar.gz
- Subject digest: 7568f3867109b452be3bfa787290d0eb92ff7af0476681ffc83c8677992b25ba
- Sigstore transparency entry: 2205901891
- Sigstore integration time: Jul 20, 2026
Source repository:
- Permalink: keiranholloway/biffo-template@efe7a9ac007bb31cfd01cd15830d0ebc4615e3e7
- Branch / Tag: refs/tags/sdk-v1.0.0
- Owner: https://github.com/keiranholloway
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish-sdk.yml@efe7a9ac007bb31cfd01cd15830d0ebc4615e3e7
- Trigger Event: workflow_dispatch