Skip to main content
Filesystem boundary helpers that translate raw I/O failures into typed errors. This module centralizes the policy for converting low-level OSError and parser exceptions into BioptimusError with a stable ErrorCode, structured context; remediation text lives centrally with the error code. The two context managers are applied at the exact boundary call (open, yaml.safe_load, Path.mkdir) so that domain logic stays outside the try and the translation policy lives in one place rather than being copy-pasted into every reader and writer. The approach mirrors how mature libraries centralize exception translation, for example httpx’s map_httpcore_exceptions context manager and PyTorch’s _check_seekable boundary validator. To keep this module dependency-light (standard library only), parser exception types that are not built in (for example yaml.YAMLError) are not imported here; callers pass them via the malformed argument of fs_read.

​
fs_read

Translates read and parse failures within the block into typed errors. Wraps the boundary call that reads or parses path. Raw filesystem and parser exceptions are converted into a BioptimusValueError with code ErrorCode.INVALID_CONFIG, attaching the path and errno to the context and an errno-specific remediation hint when available. Already-typed BioptimusError instances raised inside the block propagate unchanged so that domain errors keep their original code.
​
The filesystem path being read, used for structured context.
​
A short noun phrase naming the artifact, for example "cohort CSV manifest". It is interpolated into the message.
​
Additional, non-built-in exception types (for example yaml.YAMLError or csv.Error) that signal malformed content and should be reported as ErrorCode.INVALID_CONFIG. Built-in UnicodeDecodeError is always treated as malformed.
Returns: A context manager that translates read and parse failures raised inside the with block into a typed BioptimusValueError with code ErrorCode.INVALID_CONFIG.

​
fs_write

Translates write failures within the block into typed errors. Wraps the boundary call that writes path. Raw OSError failures are converted into a BioptimusRuntimeError: code ErrorCode.DISK_FULL when the volume is out of space or over quota, or ErrorCode.OUTPUT_WRITE_FAILED otherwise, attaching the path to the context. Already-typed BioptimusError instances raised inside the block propagate unchanged.
​
The destination path being written, used for structured context.
​
A short noun phrase naming the artifact, for example "cohort manifest". It is interpolated into the message.
Returns: A context manager that translates write failures raised inside the with block into a typed BioptimusRuntimeError with code ErrorCode.DISK_FULL or ErrorCode.OUTPUT_WRITE_FAILED.