File-format declarations

FileFormat is PolyStore’s nominal declaration of storage-format semantics. Each enum member owns four facts:

value

Stable format identity such as "numpy", "tiff", or "json".

extensions

All filename suffixes recognized for that format.

is_pixel_payload

Whether the format represents pixel or array data rather than metadata, tables, text, or ROIs.

is_raster_source

Whether the format is a raster image source suitable for default image-file discovery.

DEFAULT_IMAGE_EXTENSIONS is derived from the members whose is_raster_source declaration is true. Consumers must iterate FileFormat or use that derived set rather than maintain a second extension table.

from polystore import DEFAULT_IMAGE_EXTENSIONS, FileFormat

assert ".tif" in FileFormat.TIFF.extensions
assert FileFormat.TIFF.is_pixel_payload
assert FileFormat.TIFF.is_raster_source
assert ".tif" in DEFAULT_IMAGE_EXTENSIONS

Resolution and runtime availability

polystore.formats.get_format_from_extension performs case-insensitive extension-to-format resolution and raises ValueError for an undeclared extension. It identifies semantics; it does not promise that an installed backend can read or write that format.

Concrete backends own runtime codec availability. For example, DiskStorageBackend builds its local reader/writer registration from the dependencies available in that environment. Callers request the operation from the selected backend and let an unsupported format fail at that boundary. They must not infer another backend or silently substitute a different format.

Extension rule

Adding a format requires extending FileFormat at the declaration boundary, then implementing the relevant backend codec registration and tests. A new extension list in host code is not an alternative declaration mechanism.