brainhops.io.base.zarr

Adapt the file-based reader and writer surface to a Zarr store.

A Zarr node is a directory-backed store rather than a single file, so the file-handle machinery of the parser base does not apply to it. This mixin opens the store through abczarr instead. It inherits the common parser class so that dispatch, load, and save reach it the same way they reach every other reader, and it routes their file operations to a store path.

The mixin is object-agnostic. An image reader and a transformation reader both mix it in and share its store handling. The public entry points pair an open-node door with a location door in each direction: from_node and [to_node][brainhops.io.base.zarr.ZarrParser.to_node] operate on an opened node, and from_store and [to_store][brainhops.io.base.zarr.ZarrParser.to_store] operate on a store location.

Classes

ZarrParser `magic`

ZarrParser(node: ZarrNode | None = None)

Bases: DataModelBase, FileParser

Read and write a Zarr store through abczarr.

A concrete class mixes this in ahead of the file-based bases, whether it reads an image or a transformation.

Attributes

EXTENSIONS `class-attribute`

EXTENSIONS: tuple[str, ...] = ()

File extensions handled by this parser, e.g. (".nii", ".nii.gz").

Used as a first, cheap dispatch pass. When several parsers match, the longest matching extension wins, so a parser declaring ".nii.gz" takes precedence over one declaring ".gz".

PREFIXES `class-attribute`

PREFIXES: tuple[str, ...] = ()

Filename prefixes required by this parser, e.g. ("y_", "iy_").

An empty tuple means "no constraint". A parser that constrains the prefix is more specific than one that does not, and wins ties.

Declaring EXTENSIONS and PREFIXES separately states the cross-product implicitly, which is how these conventions actually work: SPM's four names are {y_, iy_} x {.nii, .nii.gz}.

PRIORITY `class-attribute`

PRIORITY: int = 0

Explicit tie-breaker, consulted only when specificity cannot decide. Higher wins. Leave at 0 unless two parsers genuinely collide.

Methods:

from_node `classmethod`

from_node(node: Any, **kwargs) -> Self

Read the object from an opened Zarr array or group.

node is an abczarr node, or a driver-native array or group from zarr-python, TensorStore, or zarrista, which is wrapped in an abczarr node before it is read. This is the reading counterpart of [to_node][brainhops.io.base.zarr.ZarrParser.to_node].

from_store `classmethod`

from_store(location: StoreLike, **kwargs) -> Self

Read the object from a store location or an opened store.

location is a path, given as a string or an os.PathLike, or an already-opened abczarr or driver-native store.

sniff `classmethod`

sniff(
    file: FileOrContentLike,
    error: bool | Type[Exception] = False,
    **kwargs,
) -> float

Determine if the given file is of the type that this parser can handle.

Parameters:

Name	Type	Description	Default
`file`	`FileOrContentLike`	The file to sniff.	required
`error`	`bool \| type[Exception]`	If not False, raise an error if the file cannot be sniffed.	`False`
`**kwargs`		Parser-specific options.	`{}`

Returns:

Type	Description
`float`	Confidence that the file is of this type, in `[0, 1]`.

sniff_content `classmethod`

sniff_content(
    content: ContentLike,
    error: bool | Type[Exception] = False,
    **kwargs,
) -> float

Determine if the given content is of the type that this parser can handle.

Parameters:

Name	Type	Description	Default
`content`	`ContentLike`	The content to sniff.	required
`error`	`bool \| type[Exception]`	If not False, raise an error if the content cannot be sniffed.	`False`
`**kwargs`		Parser-specific options.	`{}`

Returns:

Type	Description
`float`	Confidence that the content is of this type, in `[0, 1]`.

sniff_text `classmethod`

sniff_text(
    text: str,
    error: bool | Type[Exception] = False,
    **kwargs,
) -> float

Determine if the given text is of the type that this parser can handle.

Parameters:

Name	Type	Description	Default
`text`	`str`	The text to sniff.	required
`error`	`bool \| type[Exception]`	If not False, raise an error if the content cannot be sniffed.	`False`
`**kwargs`		Parser-specific options.	`{}`

Returns:

Type	Description
`float`	Confidence that the text is of this type, in `[0, 1]`.

sniff_lines `classmethod`

sniff_lines(
    lines: Iterable[str],
    error: bool | Type[Exception] = False,
    **kwargs,
) -> float

Determine if the given lines are of the type that this parser can handle.

Parameters:

Name	Type	Description	Default
`lines`	`Iterable[str]`	The lines to sniff.	required
`error`	`bool \| type[Exception]`	If not False, raise an error if the content cannot be sniffed.	`False`
`**kwargs`		Parser-specific options.	`{}`

Returns:

Type	Description
`float`	Confidence that the lines is of this type, in `[0, 1]`.

sniff_line `classmethod`

sniff_line(
    line: str,
    error: bool | Type[Exception] = False,
    **kwargs,
) -> float

Determine if the given line is of the type that this parser can handle.

Parameters:

Name	Type	Description	Default
`line`	`str`	The line to sniff.	required
`error`	`bool \| type[Exception]`	If not False, raise an error if the content cannot be sniffed.	`False`
`**kwargs`		Parser-specific options.	`{}`

Returns:

Type	Description
`float`	Confidence that the line is of this type, in `[0, 1]`.

load `classmethod`

load(other: FileOrContentLike, **kwargs) -> Self

Build an object from a file (path, file-like object or iterable of lines).

This is the generic front door to the from_* family: it looks at what it was handed and calls the right one.

A str is always a path, whether or not the file exists, so a missing file raises FileNotFoundError whichever way its path was spelled. Text held in memory is read with from_text or from_content.

Parameters:

Name	Type	Description	Default
`other`	`FileOrContentLike`	Input file, or its content.	required
`**kwargs`		Parser-specific options.	`{}`

Returns:

Type	Description
`obj`	The parsed object.

Raises:

Type	Description
`ParserExistsError`	If `other` is a path to a file that does not exist. It is a `FileNotFoundError`.

from_spec `classmethod`

from_spec(spec: SourceSpec, **kwargs) -> Self

Build an object from an unqualified structured source.

from_filename `classmethod`

from_filename(filename: FilenameLike, **kwargs) -> Self

Build an object from a filename.

Parameters:

Name	Type	Description	Default
`filename`	`FilenameLike`	The filename to parse.	required
`**kwargs`		Parser-specific options.	`{}`

Returns:

Type	Description
`obj`	The parsed object.

from_content `classmethod`

from_content(content: ContentLike, **kwargs) -> Self

Build an object from a file content (bytes, str, or iterable of lines).

Parameters:

Name	Type	Description	Default
`content`	`ContentLike`	The content to parse.	required
`**kwargs`		Parser-specific options.	`{}`

Returns:

Type	Description
`obj`	The parsed object.

from_text `classmethod`

from_text(text: str, **kwargs) -> Self

Build an object from a text representation of a file.

Parameters:

Name	Type	Description	Default
`text`	`str`	The text to parse.	required
`**kwargs`		Parser-specific options.	`{}`

Returns:

Type	Description
`obj`	The parsed object.

from_lines `classmethod`

from_lines(lines: Iterable[str], **kwargs) -> Self

Build an object from an iterable of lines (e.g., the content of a file).

Parameters:

Name	Type	Description	Default
`lines`	`Iterable[str]`	The lines to sniff.	required
`**kwargs`		Parser-specific options.	`{}`

Returns:

Type	Description
`obj`	The parsed object.

from_line `classmethod`

from_line(line: str, **kwargs) -> Self

Build an object from a single line of text.

Parameters:

Name	Type	Description	Default
`line`	`str`	The line to parse.	required
`**kwargs`		Parser-specific options.	`{}`

Returns:

Type	Description
`obj`	The parsed object.

from_dict `classmethod`

from_dict(other: Mapping, *args, **kwargs) -> Self

Create an instance of the class from a dictionary-like object.

Only keys in the dictionary that match keyword-like fields of this class, or the keywords its constructor takes without storing them (its InitVars, such as the matrix= of an Affine), will be used. Other keys are ignored, but see from_other, which refuses them.

Additional positional and/or keyword arguments can be provided, and will take precedence over the values in the dictionary.

A key naming a field that this class fixes (a field that cannot be passed to its constructor) is checked instead of used: a dictionary that sets it to anything other than None or the value of this class is refused with a ValueError.

from_instance `classmethod`

from_instance(other: Self, *args, **kwargs) -> Self

Create an instance of the class from an instance of a similar class.

Only attributes of the other instance that match keyword-like fields of this class will be used. An attribute that is None is unset, and leaves the default of this class in place.

Additional positional and/or keyword arguments can be provided, and will take precedence over the attributes in the instance.

Unless the other instance is already an instance of this class, an attribute naming a field that this class fixes (a field that cannot be passed to its constructor) is checked instead of used: an instance that sets it to anything other than None or the value of this class is refused with a ValueError. A generic Axis whose orientation is right-to-left, for example, cannot be read as a LeftToRightAxis.

from_other `classmethod`

from_other(other: Any, *args, **kwargs) -> Self

Create an instance of the class from any object that can be interpreted as a dictionary, or an instance of a similar class, or an arguments to be passed to the constructor.

A similar class is this class or one of its parents within the data model, or another member of a polymorphic family this class belongs to: calling a polymorphic class such as Axis builds the subclass its arguments select, so a "generic" axis is usually an instance of a sibling (a RightToLeftAxis, a TimeAxis) rather than of a parent. Any other object, including an instance of a parent that is not a data model (such as a plain object), is passed to the constructor.

Unlike from_dict, a dictionary with a key that matches no field of this class is refused with a TypeError naming the keys, so that a misspelt key is not silently dropped.

brainhops.io.base.zarr

Classes

ZarrParser magic

Attributes

EXTENSIONS class-attribute

PREFIXES class-attribute

PRIORITY class-attribute

Methods:

from_node classmethod

from_store classmethod

sniff classmethod

sniff_content classmethod

sniff_text classmethod

sniff_lines classmethod

sniff_line classmethod

load classmethod

from_spec classmethod

from_filename classmethod

from_content classmethod

from_text classmethod

from_lines classmethod

from_line classmethod

from_dict classmethod

from_instance classmethod

from_other classmethod

ZarrParser `magic`

EXTENSIONS `class-attribute`

PREFIXES `class-attribute`

PRIORITY `class-attribute`

from_node `classmethod`

from_store `classmethod`

sniff `classmethod`

sniff_content `classmethod`

sniff_text `classmethod`

sniff_lines `classmethod`

sniff_line `classmethod`

load `classmethod`

from_spec `classmethod`

from_filename `classmethod`

from_content `classmethod`

from_text `classmethod`

from_lines `classmethod`

from_line `classmethod`

from_dict `classmethod`

from_instance `classmethod`

from_other `classmethod`