scistudio.blocks.io

Canonical import root: from scistudio.blocks.io import ...

Self-contained public-API reference — 12 symbols from this module's __all__, with signatures and docstrings inlined (ADR-052 §7). Generated; do not hand-edit.

CapabilityDirection — type-alias

Stability: unmarked — see the module source / ADR-052

type-alias — see the module source for the value.

CapabilityValidationError — exception

Stability: stable · Since 0.3.1

class CapabilityValidationError(ValueError)

Base error for an invalid IO format-capability declaration.

Raised when a block declares a FormatCapability, MetadataFidelity, or a scistudio.blocks.io.SimpleLoader / scistudio.blocks.io.SimpleSaver whose fields do not make sense. Catch this (or one of its more specific subclasses below) when you want to detect and recover from a bad declaration yourself instead of letting it propagate.

FormatCapability — class

Stability: stable · Since 0.3.1

class FormatCapability
FormatCapability(id: 'str', direction: 'CapabilityDirection', data_type: 'type[DataObject]', format_id: 'str', extensions: 'tuple[str, ...]', label: 'str', block_type: 'str', handler: 'str', is_default: 'bool' = False, priority: 'int' = 0, roundtrip_group: 'str | None' = None, metadata_fidelity: 'MetadataFidelity' = <factory>, is_synthesized: 'bool' = False) -> None

One file-format conversion an IO block can perform.

Records that a specific block can read (or write) one data type as one file format — for example, "save a DataFrame as a .csv file". A block lists its capabilities in its format_capabilities so the runtime can pick the right block for a given file extension and so the format appears in the UI. Every field is validated and normalized on construction (extensions are lowercased with a leading dot, ids and labels are trimmed).

Example: >>> FormatCapability( ... id="mypkg.MyCsvSaver.save.csv", ... direction="save", ... data_type=DataObject, ... format_id="csv", ... extensions=(".csv",), ... label="CSV", ... block_type="MyCsvSaver", ... handler="save_file", ... )

Members

  • migration_scaffold(self) -> 'bool' — stable · Since 0.3.1 — Whether this capability was generated from a legacy declaration.
  • normalized_extensions(self) -> 'tuple[str, ...]' — stable · Since 0.3.1 — The capability's file extensions, already lowercased with leading dots.

IOBlock — class

Stability: stable · Since 0.3.1

class IOBlock(Block)

Abstract base for a block that loads data from a file or saves it to one.

Inherit from this to build a custom IO block. Choose a direction with the direction class attribute and override the matching method:

  • direction = "input" (a loader): override load to read the configured path and return a DataObject or a Collection. A loader has no data input port — it is a pure source.
  • direction = "output" (a saver): override save to write the object arriving on the data input port to the configured path.

You do not override run; the base class reads direction and calls load or save for you. Declare the file formats the block handles in format_capabilities so the runtime can route files by extension and the UI can list the format. The base config_schema contributes a required path field; subclasses add their own fields.

Example: >>> from pathlib import Path >>> class LoadPlainText(IOBlock): ... direction = "input" ... def load(self, config, output_dir=""): ... text = Path(config.get("path")).read_text(encoding="utf-8") ... return Text(content=text, format="plain")

Members

  • get_format_capabilities(cls) -> 'tuple[FormatCapability, ...]' — stable · Since 0.3.1 — Return the file formats this block supports as capability records.
  • load(self, config: 'BlockConfig', output_dir: 'str' = '') -> 'DataObject | Collection' — stable · Since 0.3.1 — Read the configured file and return its contents as a data object.
  • save(self, obj: 'DataObject | Collection', config: 'BlockConfig') -> 'None' — stable · Since 0.3.1 — Write obj to the configured file path.
  • run(self, inputs: 'dict[str, Collection]', config: 'BlockConfig') -> 'dict[str, Collection]' — stable · Since 0.3.1 — Run the block: call load or save based on direction.

InvalidExtensionError — exception

Stability: stable · Since 0.3.1

class InvalidExtensionError(CapabilityValidationError)

Raised when a file extension cannot be turned into a safe .ext form.

Triggered by, for example, an empty string, a bare ".", or a value that contains a path separator such as "/" or "\".

InvalidFormatCapabilityError — exception

Stability: stable · Since 0.3.1

class InvalidFormatCapabilityError(CapabilityValidationError)

Raised when a FormatCapability record is internally inconsistent.

For example: a blank id or label, a direction other than "load" / "save", a data_type that is not a DataObject subclass, or a "lossless" capability that names no roundtrip_group.

InvalidMetadataFidelityError — exception

Stability: stable · Since 0.3.1

class InvalidMetadataFidelityError(CapabilityValidationError)

Raised when a MetadataFidelity declaration is inconsistent.

For example: an unknown fidelity level, a "pixel_only" level that still lists preserved fields, or a typed-metadata field that the data type's Meta model does not declare.

MetadataFidelity — class

Stability: stable · Since 0.3.1

class MetadataFidelity
MetadataFidelity(level: 'MetadataFidelityLevel' = 'pixel_only', typed_meta_reads: 'tuple[str, ...]' = (), typed_meta_writes: 'tuple[str, ...]' = (), format_metadata_reads: 'tuple[str, ...]' = (), format_metadata_writes: 'tuple[str, ...]' = (), notes: 'str | None' = None) -> None

How much of a file's metadata one IO capability preserves.

Attach this to a FormatCapability to record what survives a read or write: just the raw values, the data object's typed meta fields, extra format-native metadata, or a fully lossless round trip. On construction the declared fields are checked for consistency (for example, a "pixel_only" capability may not also list preserved fields).

Example: >>> MetadataFidelity(level="pixel_only") # keep only the values >>> MetadataFidelity( ... level="typed_meta", ... typed_meta_writes=("exposure_time",), ... )

Members

  • typed_meta_fields(self) -> 'tuple[str, ...]' — stable · Since 0.3.1 — All typed meta field names this capability touches, de-duplicated.
  • format_metadata_fields(self) -> 'tuple[str, ...]' — stable · Since 0.3.1 — All format-native metadata keys this capability touches, de-duplicated.
  • validate_typed_meta_fields(self, data_type: 'type[DataObject]') -> 'None' — stable · Since 0.3.1 — Check that every declared typed meta field exists on the data type.

MetadataFidelityLevel — type-alias

Stability: unmarked — see the module source / ADR-052

type-alias — see the module source for the value.

SimpleIODeclarationError — exception

Stability: stable · Since 0.3.1

class SimpleIODeclarationError(CapabilityValidationError)

Raised when a scistudio.blocks.io.SimpleLoader or scistudio.blocks.io.SimpleSaver subclass omits a required field.

These ergonomic bases require the subclass to set format_id, extensions, and the output_type (loader) or input_type (saver). The error names the field that is missing or has the wrong type.

SimpleLoader — class

Stability: stable · Since 0.3.1

class SimpleLoader(IOBlock)

Base class for a loader that reads one file into one data object.

Subclass this for the common case of "load this file format into this data type". Set the class attributes output_type, format_id, and extensions, then implement load_file. The base wires up the rest: it declares one scistudio.blocks.io.FormatCapability from those attributes, reads the path from config, and calls your load_file. This is an input-only block; save always raises.

Example: >>> class LoadJsonText(SimpleLoader): ... output_type = Text ... format_id = "json" ... extensions = (".json",) ... def load_file(self, path, config): ... return Text(content=path.read_text(encoding="utf-8"), format="json")

Members

  • get_format_capabilities(cls) -> 'tuple[FormatCapability, ...]' — stable · Since 0.3.1 — Return the single capability synthesized from this loader's attributes.
  • load(self, config: 'BlockConfig', output_dir: 'str' = '') -> 'DataObject | Collection' — unmarked — see the module source / ADR-052 — Read the configured path and return the loaded object.
  • save(self, obj: 'DataObject | Collection', config: 'BlockConfig') -> 'None' — unmarked — see the module source / ADR-052 — Always raises — a SimpleLoader cannot save.
  • load_file(self, path: 'Path', config: 'dict[str, Any]') -> 'DataObject' — stable · Since 0.3.1 — Read one object from path. Implement this in your loader.

SimpleSaver — class

Stability: stable · Since 0.3.1

class SimpleSaver(IOBlock)

Base class for a saver that writes one data object to one file.

Subclass this for the common case of "write this data type to this file format". Set the class attributes input_type, format_id, and extensions, then implement save_file. The base declares one scistudio.blocks.io.FormatCapability, checks the incoming object's type, resolves the path, and calls your save_file. This is an output-only block; load always raises.

Example: >>> class SaveJsonText(SimpleSaver): ... input_type = Text ... format_id = "json" ... extensions = (".json",) ... def save_file(self, obj, path, config): ... path.write_text(obj.content, encoding="utf-8")

Members

  • get_format_capabilities(cls) -> 'tuple[FormatCapability, ...]' — stable · Since 0.3.1 — Return the single capability synthesized from this saver's attributes.
  • load(self, config: 'BlockConfig', output_dir: 'str' = '') -> 'DataObject | Collection' — unmarked — see the module source / ADR-052 — Always raises — a SimpleSaver cannot load.
  • save(self, obj: 'DataObject | Collection', config: 'BlockConfig') -> 'None' — unmarked — see the module source / ADR-052 — Validate the incoming object and write it to the configured path.
  • save_file(self, obj: 'DataObject', path: 'Path', config: 'dict[str, Any]') -> 'None' — stable · Since 0.3.1 — Write one object to path. Implement this in your saver.