brainhops.io.base.parsers

The base classes that give a format the ability to sniff, read and write itself, and the errors they raise.

Classes

SnifferError

Bases: Exception

Base class for sniffer errors.

SnifferTypeError

Bases: SnifferError, TypeError

Raised when a sniffer encounters an unexpected type.

SnifferExistsError

Bases: SnifferError, FileNotFoundError

Raised when a sniffer encounters an unexpected content.

SnifferContentError

Bases: SnifferError, TypeError

Raised when a sniffer encounters an unexpected content.

SnifferNotImplementedError

Bases: SnifferError, NotImplementedError

Raised when a sniffer function is not implemented.

ParserError

Bases: Exception

Base class for parser errors.

ParserTypeError

Bases: ParserError, TypeError

Raised when a parser encounters an unexpected type.

ParserExistsError

Bases: ParserError, FileNotFoundError

Raised when a parser encounters an unexpected content.

ParserContentError

Bases: ParserError, TypeError

Raised when a parser encounters an unexpected content.

ParserNotImplementedError

Bases: ParserError, NotImplementedError

Raised when a parser function is not implemented.

AmbiguousFormatError

Bases: ParserError

Raised when several parsers claim the same content, equally well.

Reaching this means two parsers agree on the confidence score, the extension they matched, the constraints they declare and their explicit priority, yet build different objects. There is no meaningful way to choose between them, and picking one at random would silently return the wrong kind of object.

The message is written for the user who hit it: it names each candidate format, and the hint= value (or the format's own load) that reads the content as that format.

If the formats should be able to tell such content apart, the fix belongs in the parsers, not in the caller: give one of them a sniffer that can tell the two apart (a magic number, an intent code, a filename constraint), or set an explicit PRIORITY.

WriterError

Bases: ParserError

Base class for writer errors.

WriterNotImplementedError

Bases: WriterError, NotImplementedError

Raised when a writer function is not implemented.

UnrepresentableTransformationError

Bases: WriterError

Raised when a transformation cannot be encoded in the target format.

A format that stores only affine geometry, such as NIfTI, cannot hold an arbitrary transformation. When the object being written carries one that the format has no way to represent, the writer raises this error rather than resampling the data or discarding the transformation. The message names the transformation that could not be written.

Confidence

Named confidence levels for sniffers.

These are plain floats; a sniffer may return any value in [0, 1].

Attributes

NO `class-attribute` `instance-attribute`

NO: float = 0.0

The content is definitely not of this type.

WEAK `class-attribute` `instance-attribute`

WEAK: float = 0.25

The content can be read as this type, but probably is not one.

MAYBE `class-attribute` `instance-attribute`

MAYBE: float = 0.5

The content is plausibly of this type.

LIKELY `class-attribute` `instance-attribute`

LIKELY: float = 0.75

The content is very likely of this type.

CERTAIN `class-attribute` `instance-attribute`

CERTAIN: float = 1.0

The content is definitely of this type.

FileSniffer

A class that can sniff files to determine if they are of a certain type.

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:

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_file `classmethod`

sniff_file(
    file: FileLike,
    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`	`FileLike`	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_filename `classmethod`

sniff_filename(
    filename: FilenameLike,
    error: bool | Type[Exception] = False,
    **kwargs,
) -> float

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

Parameters:

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

Returns:

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

sniff_fileobj `classmethod`

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

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

Parameters:

Name	Type	Description	Default
`file`	`IO`	A file object open for reading.	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_bytes `classmethod`

sniff_bytes(
    content: BinaryContentLike,
    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
`content`	`BinaryContentLike`	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]`.

FileParser

Bases: FileSniffer

A class that can read files of a certain type.

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:

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_file `classmethod`

from_file(file: FileLike, **kwargs) -> Self

Build an object from a file (path or file-like object).

Parameters:

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

Returns:

Type	Description
`obj`	The parsed object.

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_fileobj `classmethod`

from_fileobj(file: IO, **kwargs) -> Self

Build an object from a file-like object.

The default implementation reads the whole stream and hands its content to from_content (hence to from_bytes for binary streams). Parsers that only need part of the stream (e.g., a header) should override this method; from_bytes then falls back to it.

Parameters:

Name	Type	Description	Default
`file`	`IO`	A file object open for reading.	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_bytes `classmethod`

from_bytes(content: BinaryContentLike, **kwargs) -> Self

Build an object from a binary representation of a file.

If the class implements from_fileobj itself, the bytes are wrapped in an io.BytesIO stream and handed to from_fileobj. Otherwise, this raises ParserNotImplementedError: the default from_fileobj delegates to from_bytes, so falling back to it would recurse. A from_fileobj override that only forwards to super().from_fileobj should be decorated with _passthrough_from_fileobj; if it is not, the loop is still detected when from_bytes is re-entered for the same class, and ParserNotImplementedError is raised.

Parameters:

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

Returns:

Type	Description
`obj`	The parsed object.

Raises:

Type	Description
`ParserNotImplementedError`	If neither `from_bytes` nor `from_fileobj` is implemented.

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.

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_file `classmethod`

sniff_file(
    file: FileLike,
    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`	`FileLike`	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_filename `classmethod`

sniff_filename(
    filename: FilenameLike,
    error: bool | Type[Exception] = False,
    **kwargs,
) -> float

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

Parameters:

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

Returns:

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

sniff_fileobj `classmethod`

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

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

Parameters:

Name	Type	Description	Default
`file`	`IO`	A file object open for reading.	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_bytes `classmethod`

sniff_bytes(
    content: BinaryContentLike,
    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
`content`	`BinaryContentLike`	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]`.

FileParserWriter

Bases: FileParser

A class that can read and write files of a certain type.

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:

save

save(file: FileLike, **kwargs) -> None

Write the object to a file (path or file-like object).

This is the generic front door to the to_* family. It is named save rather than to because to already means something else on the data models these parsers are mixed into: Transformation.to converts an object to another type. A writer's to was shadowed by it on every writable transformation.

Parameters:

Name	Type	Description	Default
`file`	`FileLike`	The file to write to.	required
`**kwargs`		Parser-specific options.	`{}`

to_file

to_file(file: FileLike, **kwargs) -> None

Write the object to a file (path or file-like object).

Parameters:

Name	Type	Description	Default
`file`	`FileLike`	The file to write to.	required
`**kwargs`		Parser-specific options.	`{}`

to_filename

to_filename(filename: FilenameLike, **kwargs) -> None

Write the object to a filename.

Parameters:

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

to_fileobj

to_fileobj(file: IO, **kwargs) -> None

Write the object to a file-like object open for writing.

Parameters:

Name	Type	Description	Default
`file`	`IO`	A file object open for writing.	required
`**kwargs`		Parser-specific options.	`{}`

to_bytes

to_bytes(**kwargs) -> bytes

Return a binary version of the file.

Parameters:

Name	Type	Description	Default
`**kwargs`		Parser-specific options.	`{}`

Returns:

Type	Description
`bytes`	A binary version of the file.

to_text

to_text(**kwargs) -> str

Return a text version of the file.

Parameters:

Name	Type	Description	Default
`**kwargs`		Parser-specific options.	`{}`

Returns:

Type	Description
`str`	A text version of the file.

to_lines

to_lines(**kwargs) -> Iterator[str]

Return a text version of the file as an iterable of lines.

Parameters:

Name	Type	Description	Default
`**kwargs`		Parser-specific options.	`{}`

Returns:

Type	Description
`Iterator[str]`	An iterable of lines representing the object.

to_line

to_line(**kwargs) -> str

Return a line representing the object.

Parameters:

Name	Type	Description	Default
`**kwargs`		Parser-specific options.	`{}`

Returns:

Type	Description
`str`	A line representing the object.

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_file `classmethod`

sniff_file(
    file: FileLike,
    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`	`FileLike`	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_filename `classmethod`

sniff_filename(
    filename: FilenameLike,
    error: bool | Type[Exception] = False,
    **kwargs,
) -> float

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

Parameters:

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

Returns:

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

sniff_fileobj `classmethod`

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

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

Parameters:

Name	Type	Description	Default
`file`	`IO`	A file object open for reading.	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_bytes `classmethod`

sniff_bytes(
    content: BinaryContentLike,
    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
`content`	`BinaryContentLike`	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_file `classmethod`

from_file(file: FileLike, **kwargs) -> Self

Build an object from a file (path or file-like object).

Parameters:

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

Returns:

Type	Description
`obj`	The parsed object.

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_fileobj `classmethod`

from_fileobj(file: IO, **kwargs) -> Self

Build an object from a file-like object.

The default implementation reads the whole stream and hands its content to from_content (hence to from_bytes for binary streams). Parsers that only need part of the stream (e.g., a header) should override this method; from_bytes then falls back to it.

Parameters:

Name	Type	Description	Default
`file`	`IO`	A file object open for reading.	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_bytes `classmethod`

from_bytes(content: BinaryContentLike, **kwargs) -> Self

Build an object from a binary representation of a file.

If the class implements from_fileobj itself, the bytes are wrapped in an io.BytesIO stream and handed to from_fileobj. Otherwise, this raises ParserNotImplementedError: the default from_fileobj delegates to from_bytes, so falling back to it would recurse. A from_fileobj override that only forwards to super().from_fileobj should be decorated with _passthrough_from_fileobj; if it is not, the loop is still detected when from_bytes is re-entered for the same class, and ParserNotImplementedError is raised.

Parameters:

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

Returns:

Type	Description
`obj`	The parsed object.

Raises:

Type	Description
`ParserNotImplementedError`	If neither `from_bytes` nor `from_fileobj` is implemented.

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.

TextFileSniffer

Bases: FileSniffer

A class that can sniff text files to determine if they are of a certain type.

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:

sniff_fileobj `classmethod`

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

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

A text stream decodes as it is read, so content that is not text -- a binary file that shares an extension with a text format -- fails there. That is a "no", not a failure to sniff.

Parameters:

Name	Type	Description	Default
`file`	`IO`	A file object open for reading.	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_bytes `classmethod`

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

Determine if the given bytes are of the type that this parser can handle, by decoding them to text and delegating to sniff_text. Bytes that do not decode are not text, so they score NO.

Parameters:

Name	Type	Description	Default
`content`	`BinaryContentLike`	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, plus `encoding` (default `"utf-8"`) for decoding `content`.	`{}`

Returns:

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

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_file `classmethod`

sniff_file(
    file: FileLike,
    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`	`FileLike`	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_filename `classmethod`

sniff_filename(
    filename: FilenameLike,
    error: bool | Type[Exception] = False,
    **kwargs,
) -> float

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

Parameters:

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

Returns:

Type	Description
`float`	Confidence that the filename 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]`.

TextFileParser

Bases: TextFileSniffer, FileParser

A class that can read text files of a certain type.

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_bytes `classmethod`

from_bytes(content: BinaryContentLike, **kwargs) -> Self

Build an object from bytes, by decoding them to text and delegating to from_text.

Parameters:

Name	Type	Description	Default
`content`	`BinaryContentLike`	The content to parse.	required
`**kwargs`		Parser-specific options, plus `encoding` (default `"utf-8"`) for decoding `content`.	`{}`

Returns:

Type	Description
`obj`	The parsed object.

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_file `classmethod`

sniff_file(
    file: FileLike,
    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`	`FileLike`	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_filename `classmethod`

sniff_filename(
    filename: FilenameLike,
    error: bool | Type[Exception] = False,
    **kwargs,
) -> float

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

Parameters:

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

Returns:

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

sniff_fileobj `classmethod`

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

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

A text stream decodes as it is read, so content that is not text -- a binary file that shares an extension with a text format -- fails there. That is a "no", not a failure to sniff.

Parameters:

Name	Type	Description	Default
`file`	`IO`	A file object open for reading.	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_bytes `classmethod`

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

Determine if the given bytes are of the type that this parser can handle, by decoding them to text and delegating to sniff_text. Bytes that do not decode are not text, so they score NO.

Parameters:

Name	Type	Description	Default
`content`	`BinaryContentLike`	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, plus `encoding` (default `"utf-8"`) for decoding `content`.	`{}`

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_file `classmethod`

from_file(file: FileLike, **kwargs) -> Self

Build an object from a file (path or file-like object).

Parameters:

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

Returns:

Type	Description
`obj`	The parsed object.

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_fileobj `classmethod`

from_fileobj(file: IO, **kwargs) -> Self

Build an object from a file-like object.

The default implementation reads the whole stream and hands its content to from_content (hence to from_bytes for binary streams). Parsers that only need part of the stream (e.g., a header) should override this method; from_bytes then falls back to it.

Parameters:

Name	Type	Description	Default
`file`	`IO`	A file object open for reading.	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.

TextFileParserWriter

Bases: TextFileParser, FileParserWriter

A class that can read and write text files of a certain type.

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:

to_bytes

to_bytes(**kwargs) -> bytes

Convert the object to bytes, by converting it to text and encoding the result.

Parameters:

Name	Type	Description	Default
`**kwargs`		Writer-specific options, plus `encoding` (default `"utf-8"`) for encoding the text.	`{}`

Returns:

Type	Description
`bytes`	The byte representation of the object.

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_file `classmethod`

sniff_file(
    file: FileLike,
    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`	`FileLike`	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_filename `classmethod`

sniff_filename(
    filename: FilenameLike,
    error: bool | Type[Exception] = False,
    **kwargs,
) -> float

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

Parameters:

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

Returns:

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

sniff_fileobj `classmethod`

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

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

A text stream decodes as it is read, so content that is not text -- a binary file that shares an extension with a text format -- fails there. That is a "no", not a failure to sniff.

Parameters:

Name	Type	Description	Default
`file`	`IO`	A file object open for reading.	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_bytes `classmethod`

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

Determine if the given bytes are of the type that this parser can handle, by decoding them to text and delegating to sniff_text. Bytes that do not decode are not text, so they score NO.

Parameters:

Name	Type	Description	Default
`content`	`BinaryContentLike`	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, plus `encoding` (default `"utf-8"`) for decoding `content`.	`{}`

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_file `classmethod`

from_file(file: FileLike, **kwargs) -> Self

Build an object from a file (path or file-like object).

Parameters:

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

Returns:

Type	Description
`obj`	The parsed object.

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_fileobj `classmethod`

from_fileobj(file: IO, **kwargs) -> Self

Build an object from a file-like object.

The default implementation reads the whole stream and hands its content to from_content (hence to from_bytes for binary streams). Parsers that only need part of the stream (e.g., a header) should override this method; from_bytes then falls back to it.

Parameters:

Name	Type	Description	Default
`file`	`IO`	A file object open for reading.	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_bytes `classmethod`

from_bytes(content: BinaryContentLike, **kwargs) -> Self

Build an object from bytes, by decoding them to text and delegating to from_text.

Parameters:

Name	Type	Description	Default
`content`	`BinaryContentLike`	The content to parse.	required
`**kwargs`		Parser-specific options, plus `encoding` (default `"utf-8"`) for decoding `content`.	`{}`

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.

save

save(file: FileLike, **kwargs) -> None

Write the object to a file (path or file-like object).

This is the generic front door to the to_* family. It is named save rather than to because to already means something else on the data models these parsers are mixed into: Transformation.to converts an object to another type. A writer's to was shadowed by it on every writable transformation.

Parameters:

Name	Type	Description	Default
`file`	`FileLike`	The file to write to.	required
`**kwargs`		Parser-specific options.	`{}`

to_file

to_file(file: FileLike, **kwargs) -> None

Write the object to a file (path or file-like object).

Parameters:

Name	Type	Description	Default
`file`	`FileLike`	The file to write to.	required
`**kwargs`		Parser-specific options.	`{}`

to_filename

to_filename(filename: FilenameLike, **kwargs) -> None

Write the object to a filename.

Parameters:

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

to_fileobj

to_fileobj(file: IO, **kwargs) -> None

Write the object to a file-like object open for writing.

Parameters:

Name	Type	Description	Default
`file`	`IO`	A file object open for writing.	required
`**kwargs`		Parser-specific options.	`{}`

to_text

to_text(**kwargs) -> str

Return a text version of the file.

Parameters:

Name	Type	Description	Default
`**kwargs`		Parser-specific options.	`{}`

Returns:

Type	Description
`str`	A text version of the file.

to_lines

to_lines(**kwargs) -> Iterator[str]

Return a text version of the file as an iterable of lines.

Parameters:

Name	Type	Description	Default
`**kwargs`		Parser-specific options.	`{}`

Returns:

Type	Description
`Iterator[str]`	An iterable of lines representing the object.

to_line

to_line(**kwargs) -> str

Return a line representing the object.

Parameters:

Name	Type	Description	Default
`**kwargs`		Parser-specific options.	`{}`

Returns:

Type	Description
`str`	A line representing the object.

BinaryFileSniffer

Bases: FileSniffer

A class that can sniff binary files to determine if they are of a certain type.

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:

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_file `classmethod`

sniff_file(
    file: FileLike,
    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`	`FileLike`	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_filename `classmethod`

sniff_filename(
    filename: FilenameLike,
    error: bool | Type[Exception] = False,
    **kwargs,
) -> float

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

Parameters:

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

Returns:

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

sniff_fileobj `classmethod`

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

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

Parameters:

Name	Type	Description	Default
`file`	`IO`	A file object open for reading.	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_bytes `classmethod`

sniff_bytes(
    content: BinaryContentLike,
    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
`content`	`BinaryContentLike`	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]`.

BinaryFileParser

Bases: BinaryFileSniffer, FileParser

A class that can read binary files of a certain type.

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:

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_file `classmethod`

sniff_file(
    file: FileLike,
    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`	`FileLike`	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_filename `classmethod`

sniff_filename(
    filename: FilenameLike,
    error: bool | Type[Exception] = False,
    **kwargs,
) -> float

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

Parameters:

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

Returns:

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

sniff_fileobj `classmethod`

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

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

Parameters:

Name	Type	Description	Default
`file`	`IO`	A file object open for reading.	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_bytes `classmethod`

sniff_bytes(
    content: BinaryContentLike,
    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
`content`	`BinaryContentLike`	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_file `classmethod`

from_file(file: FileLike, **kwargs) -> Self

Build an object from a file (path or file-like object).

Parameters:

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

Returns:

Type	Description
`obj`	The parsed object.

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_fileobj `classmethod`

from_fileobj(file: IO, **kwargs) -> Self

Build an object from a file-like object.

The default implementation reads the whole stream and hands its content to from_content (hence to from_bytes for binary streams). Parsers that only need part of the stream (e.g., a header) should override this method; from_bytes then falls back to it.

Parameters:

Name	Type	Description	Default
`file`	`IO`	A file object open for reading.	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_bytes `classmethod`

from_bytes(content: BinaryContentLike, **kwargs) -> Self

Build an object from a binary representation of a file.

If the class implements from_fileobj itself, the bytes are wrapped in an io.BytesIO stream and handed to from_fileobj. Otherwise, this raises ParserNotImplementedError: the default from_fileobj delegates to from_bytes, so falling back to it would recurse. A from_fileobj override that only forwards to super().from_fileobj should be decorated with _passthrough_from_fileobj; if it is not, the loop is still detected when from_bytes is re-entered for the same class, and ParserNotImplementedError is raised.

Parameters:

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

Returns:

Type	Description
`obj`	The parsed object.

Raises:

Type	Description
`ParserNotImplementedError`	If neither `from_bytes` nor `from_fileobj` is implemented.

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.

BinaryFileParserWriter

Bases: BinaryFileParser, FileParserWriter

A class that can read and write binary files of a certain type.

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:

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_file `classmethod`

sniff_file(
    file: FileLike,
    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`	`FileLike`	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_filename `classmethod`

sniff_filename(
    filename: FilenameLike,
    error: bool | Type[Exception] = False,
    **kwargs,
) -> float

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

Parameters:

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

Returns:

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

sniff_fileobj `classmethod`

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

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

Parameters:

Name	Type	Description	Default
`file`	`IO`	A file object open for reading.	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_bytes `classmethod`

sniff_bytes(
    content: BinaryContentLike,
    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
`content`	`BinaryContentLike`	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_file `classmethod`

from_file(file: FileLike, **kwargs) -> Self

Build an object from a file (path or file-like object).

Parameters:

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

Returns:

Type	Description
`obj`	The parsed object.

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_fileobj `classmethod`

from_fileobj(file: IO, **kwargs) -> Self

Build an object from a file-like object.

The default implementation reads the whole stream and hands its content to from_content (hence to from_bytes for binary streams). Parsers that only need part of the stream (e.g., a header) should override this method; from_bytes then falls back to it.

Parameters:

Name	Type	Description	Default
`file`	`IO`	A file object open for reading.	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_bytes `classmethod`

from_bytes(content: BinaryContentLike, **kwargs) -> Self

Build an object from a binary representation of a file.

If the class implements from_fileobj itself, the bytes are wrapped in an io.BytesIO stream and handed to from_fileobj. Otherwise, this raises ParserNotImplementedError: the default from_fileobj delegates to from_bytes, so falling back to it would recurse. A from_fileobj override that only forwards to super().from_fileobj should be decorated with _passthrough_from_fileobj; if it is not, the loop is still detected when from_bytes is re-entered for the same class, and ParserNotImplementedError is raised.

Parameters:

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

Returns:

Type	Description
`obj`	The parsed object.

Raises:

Type	Description
`ParserNotImplementedError`	If neither `from_bytes` nor `from_fileobj` is implemented.

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.

save

save(file: FileLike, **kwargs) -> None

Write the object to a file (path or file-like object).

This is the generic front door to the to_* family. It is named save rather than to because to already means something else on the data models these parsers are mixed into: Transformation.to converts an object to another type. A writer's to was shadowed by it on every writable transformation.

Parameters:

Name	Type	Description	Default
`file`	`FileLike`	The file to write to.	required
`**kwargs`		Parser-specific options.	`{}`

to_file

to_file(file: FileLike, **kwargs) -> None

Write the object to a file (path or file-like object).

Parameters:

Name	Type	Description	Default
`file`	`FileLike`	The file to write to.	required
`**kwargs`		Parser-specific options.	`{}`

to_filename

to_filename(filename: FilenameLike, **kwargs) -> None

Write the object to a filename.

Parameters:

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

to_fileobj

to_fileobj(file: IO, **kwargs) -> None

Write the object to a file-like object open for writing.

Parameters:

Name	Type	Description	Default
`file`	`IO`	A file object open for writing.	required
`**kwargs`		Parser-specific options.	`{}`

to_bytes

to_bytes(**kwargs) -> bytes

Return a binary version of the file.

Parameters:

Name	Type	Description	Default
`**kwargs`		Parser-specific options.	`{}`

Returns:

Type	Description
`bytes`	A binary version of the file.

to_text

to_text(**kwargs) -> str

Return a text version of the file.

Parameters:

Name	Type	Description	Default
`**kwargs`		Parser-specific options.	`{}`

Returns:

Type	Description
`str`	A text version of the file.

to_lines

to_lines(**kwargs) -> Iterator[str]

Return a text version of the file as an iterable of lines.

Parameters:

Name	Type	Description	Default
`**kwargs`		Parser-specific options.	`{}`

Returns:

Type	Description
`Iterator[str]`	An iterable of lines representing the object.

to_line

to_line(**kwargs) -> str

Return a line representing the object.

Parameters:

Name	Type	Description	Default
`**kwargs`		Parser-specific options.	`{}`

Returns:

Type	Description
`str`	A line representing the object.

brainhops.io.base.parsers

Classes

SnifferError

SnifferTypeError

SnifferExistsError

SnifferContentError

SnifferNotImplementedError

ParserError

ParserTypeError

ParserExistsError

ParserContentError

ParserNotImplementedError

AmbiguousFormatError

WriterError

WriterNotImplementedError

UnrepresentableTransformationError

Confidence

Attributes

NO class-attribute instance-attribute

WEAK class-attribute instance-attribute

MAYBE class-attribute instance-attribute

LIKELY class-attribute instance-attribute

CERTAIN class-attribute instance-attribute

FileSniffer

Attributes

EXTENSIONS class-attribute

PREFIXES class-attribute

PRIORITY class-attribute

Methods:

sniff classmethod

sniff_file classmethod

sniff_filename classmethod

sniff_fileobj classmethod

sniff_content classmethod

sniff_bytes classmethod

sniff_text classmethod

sniff_lines classmethod

sniff_line classmethod

FileParser

Attributes

EXTENSIONS class-attribute

PREFIXES class-attribute

PRIORITY class-attribute

Methods:

load classmethod

from_spec classmethod

from_file classmethod

from_filename classmethod

from_fileobj classmethod

from_content classmethod

from_bytes classmethod

from_text classmethod

from_lines classmethod

from_line classmethod

sniff classmethod

sniff_file classmethod

sniff_filename classmethod

sniff_fileobj classmethod

sniff_content classmethod

sniff_bytes classmethod

sniff_text classmethod

sniff_lines classmethod

sniff_line classmethod

FileParserWriter

Attributes

EXTENSIONS class-attribute

PREFIXES class-attribute

PRIORITY class-attribute

Methods:

save

to_file

to_filename

to_fileobj

to_bytes

to_text

to_lines

to_line

sniff classmethod

sniff_file classmethod

sniff_filename classmethod

NO `class-attribute` `instance-attribute`

WEAK `class-attribute` `instance-attribute`

MAYBE `class-attribute` `instance-attribute`

LIKELY `class-attribute` `instance-attribute`

CERTAIN `class-attribute` `instance-attribute`

EXTENSIONS `class-attribute`

PREFIXES `class-attribute`

PRIORITY `class-attribute`

sniff `classmethod`

sniff_file `classmethod`

sniff_filename `classmethod`

sniff_fileobj `classmethod`

sniff_content `classmethod`

sniff_bytes `classmethod`

sniff_text `classmethod`

sniff_lines `classmethod`

sniff_line `classmethod`

EXTENSIONS `class-attribute`

PREFIXES `class-attribute`

PRIORITY `class-attribute`

load `classmethod`

from_spec `classmethod`

from_file `classmethod`

from_filename `classmethod`

from_fileobj `classmethod`

from_content `classmethod`

from_bytes `classmethod`

from_text `classmethod`

from_lines `classmethod`

from_line `classmethod`

sniff `classmethod`

sniff_file `classmethod`

sniff_filename `classmethod`

sniff_fileobj `classmethod`

sniff_content `classmethod`

sniff_bytes `classmethod`

sniff_text `classmethod`

sniff_lines `classmethod`

sniff_line `classmethod`

EXTENSIONS `class-attribute`

PREFIXES `class-attribute`

PRIORITY `class-attribute`

sniff `classmethod`

sniff_file `classmethod`

sniff_filename `classmethod`

sniff_fileobj `classmethod`

sniff_content `classmethod`

sniff_bytes `classmethod`

sniff_text `classmethod`

sniff_lines `classmethod`

sniff_line `classmethod`

load `classmethod`

from_spec `classmethod`

from_file `classmethod`

from_filename `classmethod`

from_fileobj `classmethod`

from_content `classmethod`

from_bytes `classmethod`

from_text `classmethod`

from_lines `classmethod`

from_line `classmethod`

EXTENSIONS `class-attribute`

PREFIXES `class-attribute`

PRIORITY `class-attribute`

sniff_fileobj `classmethod`

sniff_bytes `classmethod`

sniff `classmethod`

sniff_file `classmethod`

sniff_filename `classmethod`

sniff_content `classmethod`

sniff_text `classmethod`

sniff_lines `classmethod`

sniff_line `classmethod`

EXTENSIONS `class-attribute`

PREFIXES `class-attribute`

PRIORITY `class-attribute`

from_bytes `classmethod`

sniff `classmethod`

sniff_file `classmethod`

sniff_filename `classmethod`