Skip to content

Readers API

GpadReader(source, *, errors='strict', on_error=None)

Stream GPAD 2.0 rows as validated Annotation models.

Use the reader as a context manager. Iteration is valid only while the context is open. A GPAD row can expand into multiple annotations when its with/from or annotation-extension column contains pipe alternatives.

Examples:

Read annotations from a plain-text or gzip-compressed path:

from go_standard_annotation_schema.io import GpadReader

with GpadReader("annotations.gpad.gz") as reader:
    for annotation in reader:
        print(annotation.ontology_class_id)
    print(reader.stats.records_yielded)

Skip invalid rows and inspect their issues:

from go_standard_annotation_schema.io import GpadReader, RowIssue

def report(issue):
    print(issue.source, issue.line_number, issue.code)

with GpadReader("annotations.gpad", errors="skip", on_error=report) as reader:
    for annotation in reader:
        pass

Parameters:

  • source (Source) –

    A filesystem path or readable text stream. Paths ending in .gz are decompressed automatically.

  • errors (ErrorMode, default: 'strict' ) –

    "strict" raises the first row error. "skip" skips invalid rows and continues reading.

  • on_error (ErrorCallback | None, default: None ) –

    Optional callback invoked with each skipped RowIssue. It is used only when errors="skip".

Raises:

  • ValueError –

    If errors is neither "strict" nor "skip".

  • HeaderError –

    If the file header is missing, malformed, or has the wrong format version.

  • ReaderStateError –

    If iteration occurs outside the open context or the reader is entered more than once.

  • RowError –

    If a data row is invalid and errors is "strict".

Attributes

metadata property

Metadata read from the file header.

The header is consumed when the reader enters its context manager, so metadata is available before the first data record is yielded.

Returns:

  • FileMetadata –

    The parsed format, version, generation metadata, and header entries.

Raises:

stats property

A snapshot of the reader's current counters.

Counts are updated as the reader consumes lines, parses metadata, and yields records. This property can be accessed at any time, but the counts may not reflect the final state until the reader is exhausted.

Returns:

  • ReaderStats –

    Counts for consumed lines, metadata, data rows, yielded records, skipped rows, blank lines, and ignored comments.

Methods:

parse_line(line, *, line_number=None, source=None) classmethod

Parse one GPAD 2.0 data row into one or more annotations.

Parameters:

  • line (str) –

    A tab-delimited GPAD data row, with or without a line ending.

  • line_number (int | None, default: None ) –

    Optional source line number included in error details.

  • source (str | None, default: None ) –

    Optional source name included in error details.

Returns:

  • tuple[Annotation, ...] –

    One or more validated annotations. The tuple contains multiple annotations when pipe alternatives expand the row.

Raises:

  • RowError –

    If the row has the wrong field count, invalid GPAD syntax, or values rejected by model validation.

Examples:

from go_standard_annotation_schema.io import GpadReader

annotations = GpadReader.parse_line(line)

GpiReader(source, *, errors='strict', on_error=None)

Stream GPI 2.0 rows as validated Entity models.

Use the reader as a context manager. The header is parsed on entry, and iteration is valid only while the context is open.

Examples:

from go_standard_annotation_schema.io import GpiReader

with GpiReader("entities.gpi") as reader:
    for entity in reader:
        print(entity.db_object_id)
    print(reader.metadata.version)

Parameters:

  • source (Source) –

    A filesystem path or readable text stream. Paths ending in .gz are decompressed automatically.

  • errors (ErrorMode, default: 'strict' ) –

    "strict" raises the first row error. "skip" skips invalid rows and continues reading.

  • on_error (ErrorCallback | None, default: None ) –

    Optional callback invoked with each skipped RowIssue. It is used only when errors="skip".

Raises:

  • ValueError –

    If errors is neither "strict" nor "skip".

  • HeaderError –

    If the file header is missing, malformed, or has the wrong format version.

  • ReaderStateError –

    If iteration occurs outside the open context or the reader is entered more than once.

  • RowError –

    If a data row is invalid and errors is "strict".

Attributes

metadata property

Metadata read from the file header.

The header is consumed when the reader enters its context manager, so metadata is available before the first data record is yielded.

Returns:

  • FileMetadata –

    The parsed format, version, generation metadata, and header entries.

Raises:

stats property

A snapshot of the reader's current counters.

Counts are updated as the reader consumes lines, parses metadata, and yields records. This property can be accessed at any time, but the counts may not reflect the final state until the reader is exhausted.

Returns:

  • ReaderStats –

    Counts for consumed lines, metadata, data rows, yielded records, skipped rows, blank lines, and ignored comments.

Methods:

parse_line(line, *, line_number=None, source=None) classmethod

Parse one GPI 2.0 data row into an entity.

Parameters:

  • line (str) –

    A tab-delimited GPI data row, with or without a line ending.

  • line_number (int | None, default: None ) –

    Optional source line number included in error details.

  • source (str | None, default: None ) –

    Optional source name included in error details.

Returns:

  • Entity –

    The validated entity represented by the row.

Raises:

  • RowError –

    If the row has the wrong field count, invalid GPI syntax, or values rejected by model validation.

Examples:

from go_standard_annotation_schema.io import GpiReader

entity = GpiReader.parse_line(line)

types

Attributes

ErrorCallback = Callable[[RowIssue], None] module-attribute

A callback function for handling row issues.

ErrorMode = Literal['strict', 'skip'] module-attribute

The error handling mode for a reader.

Source = str | os.PathLike[str] | TextIO module-attribute

A source of data for the reader.

Classes

FileMetadata(format, version, generated_by, date_generated, entries) dataclass

Representation of a file's header, including required and custom fields.

HeaderError

Raised when required file metadata is invalid.

MetadataEntry(key, value) dataclass

A single key-value pair from a file's header.

ReaderError

Base class for GPAD/GPI reader failures.

ReaderStateError

Raised when a reader is used outside its valid lifecycle.

ReaderStats(lines_read=0, metadata_entries=0, data_rows=0, records_yielded=0, rows_skipped=0, blank_lines=0, comments_ignored=0) dataclass

Statistics about the reader's progress and results.

RowError(issue)

Raised when a data row is invalid.

RowIssue(source, line_number, format, code, raw_line, cause) dataclass

Information about a problem with a data row.