bfabric.operations Module Design

bfabric.operations Module Design#

Purpose and scope#

bfabric.operations is the home for named write capabilities against B-Fabric, organized by domain. It gives bfabricPy a single, supported surface for non-trivial writes and the helpers they need (transforms, validators, diffing), so consumers (REST proxy, landing apps, CLIs) compose writes without each reimplementing them.

Code belongs here when it is a write capability for a B-Fabric entity, or a pure helper that exists primarily to support such capabilities (DataFrame ↔ SOAP transforms, diffing, validation of write-bound inputs) — and it is deployment-agnostic, making no assumption about whose credentials it runs under, what authorization happened beforehand, or what UI surrounds it. Single-SOAP-call writes that need no transform or coordination do not belong here; callers use client.save(...) directly. Authorization assertions, prompting/UI logic, and entity-read helpers also stay out — read helpers live on the read-only entities.

Module layout#

A domain is named after the B-Fabric entity it writes to (workunit, dataset, sample, …) and is implemented as either a single file (<entity>.py) or a sub-package (<entity>/). The choice is purely about readability: start as a file, promote to a sub-package when shared machinery accumulates. Either way the public import path is from bfabric.operations.<entity> import <verb>_<entity> — sub-package __init__.py re-exports so callers never see the internal split.

A few write capabilities operate on any entity, typically via EntityUri or (entity_type, entity_id), and don’t fit under a single entity-named module — update_custom_attributes is the current example. These live at the top level of bfabric.operations and are re-exported from bfabric.operations.__init__, so the import path is from bfabric.operations import update_custom_attributes. The top level is reserved for genuinely cross-entity primitives; anything meaningfully bound to one entity type goes under its entity module.

The operation contract#

Every operation, regardless of domain, follows a small fixed contract:

  • Inputs are validated by a pydantic params model. Where an operation also takes a large payload that pydantic doesn’t validate well (e.g. a Polars DataFrame), the payload is a separate positional argument and the params model stays metadata-only.

  • Outputs are populated read-only entities from bfabric.entities. Operations never invent their own return types and entities never gain write methods.

  • Audit identity is supplied by the caller as audit_attributes: dict[str, str] and written verbatim onto the created entity. The operations module has no opinion about which keys a deployment uses; only delegated writes need this parameter at all.

Compound operations need failure cleanup. Any capability that can leave partial state on error must mark that state as failed (or equivalent) so it is not mistaken for in-progress work. The canonical shape: perform the initial create step and remember the new entity id; wrap the remaining steps in a try returning the completed entity on success; on BaseException (not Exception — KeyboardInterrupt and SystemExit must also trigger cleanup) save the entity with status="failed", wrapping that cleanup save in an inner try / except BaseException that logs and does not re-raise so a cleanup failure cannot mask the original error. Do not delete already-created child entities (resources, parameters, links): they stay attached to the failed parent so the partial state is diagnosable. Copy this shape verbatim for new compound operations; do not invent variants.

Within those rules each domain has latitude over its internal organization, which pure helpers (transforms, validators, diff) it exposes, and whether validators run inside the operation or are left for callers to apply. Caller-side validation enables previews, dry-runs, and test fixtures to skip it, at the cost of every caller remembering to invoke validators first. If that becomes error-prone in practice, the fix is a thin <verb>_<entity>_validated wrapper, not rebundling validation into the primitive.

What the contract leaves to the caller#

Several things look like operations-module concerns but are deliberately left to consumers, recorded here so a future maintainer doesn’t pull them in.

Authorization stays in each consumer — every consumer applies its own check before invoking an operation, and the operations module assumes the caller has already decided the write is allowed. Choosing audit attribute keys is a deployment decision: operations stamp whatever dict[str, str] they’re given. Idempotency / retry safety is also out of scope — retrying a compound create after a transient error may produce a duplicate, and a consumer that needs deduplication adds a wrapper that searches first; building idempotency in would require a stable client-side key that B-Fabric does not currently expose. Orphan child cleanup on failure is similarly the consumer’s call: children attached to a failed parent stay attached and the failed-status mark is enough for diagnosis, but a consumer that wants stricter cleanup (e.g. a sandbox container) does it itself.