Csv

omniread.csv

Summary

CSV subpackage for OmniRead.

Provides acquisition and parsing of comma-separated-value content:

• BaseCsvClient: abstract backing-store client for csv bytes.
• FileSystemCsvClient: local filesystem implementation.
• CsvScraper: wraps fetched bytes into canonical Content.
• CsvParserBase: content-type-enforcing parser contract.
• CsvParser: generic string-row parser built on the standard csv module.

Classes

BaseCsvClient

Bases: ABC

Abstract client responsible for retrieving csv bytes.

Retrieves bytes from a specific backing store (filesystem, S3, FTP, etc.).

Notes

Responsibilities:

- Implementations must accept a source identifier appropriate to
  the backing store.
- Return the full csv binary payload.
- Raise retrieval-specific errors on failure.

Functions

fetch abstractmethod

fetch(source: Any) -> bytes

Fetch raw csv bytes from the given source.

Parameters:

Name	Type	Description	Default
source	Any	Identifier of the csv location, such as a file path, object storage key, or remote reference.	required

Returns:

Name	Type	Description
bytes	bytes	Raw csv bytes.

Raises:

Type	Description
Exception	Retrieval-specific errors defined by the implementation.

CsvParser

CsvParser(content: Content)

Bases: CsvParserBase[list[list[str]]]

Generic csv parser producing string rows from the document.

Notes

Responsibilities:

- Decode the payload (UTF-8 with BOM support, Latin-1 fallback).
- Detect the delimiter from a leading sample (`,` `;` tab `|`),
  defaulting to `,`.
- Normalize cells into deterministic stripped string values.
- Expose row extraction helpers mirroring `XlsxParser.rows`.

Constraints:

- All values are strings; consumers requiring typed values must
  convert on their side.
- Quoted fields containing delimiters/newlines are handled by
  the standard ``csv`` module.

Initialize the parser.

Parameters:

Name	Type	Description	Default
content	Content	CSV content to parse; its type must be supported.	required

Attributes

supported_types class-attribute instance-attribute

supported_types: set[ContentType] = {CSV}

Set of content types supported by this parser (CSV only).

Functions

parse

parse() -> list[list[str]]

Parse the document into normalized string rows.

Returns:

Type	Description
list[list[str]]	list[list[str]]: Rows of the document.

rows

rows(*, skip_empty: bool = True) -> list[list[str]]

Extract normalized string rows from the document.

Parameters:

Name	Type	Description	Default
skip_empty	bool	When True (default), rows whose cells are all blank are omitted.	True

Returns:

Type	Description
list[list[str]]	list[list[str]]: Normalized rows; trailing blank cells are trimmed per row.

supports

supports() -> bool

Check whether this parser supports the content's type.

Returns:

Name	Type	Description
bool	bool	True if the content type is supported; False otherwise.

CsvParserBase

CsvParserBase(content: Content)

Bases: BaseParser[T], Generic[T]

Base csv parser.

Notes

Responsibilities:

- This class enforces csv content-type compatibility and provides
  the extension point for implementing concrete csv parsing
  strategies.

Constraints:

- Concrete implementations must define the output type `T` and
  implement the `parse()` method.

Initialize the parser with content to be parsed.

Parameters:

Name	Type	Description	Default
content	Content	Content instance to be parsed.	required

Raises:

Type	Description
ValueError	If the content type is not supported by this parser.

Attributes

supported_types class-attribute instance-attribute

supported_types: set[ContentType] = {CSV}

Set of content types supported by this parser (CSV only).

Functions

parse abstractmethod

parse() -> T

Parse csv content into a structured output.

Returns:

Name	Type	Description
T	T	Parsed representation of type T.

Raises:

Type	Description
Exception	Parsing-specific errors as defined by the implementation.

supports

supports() -> bool

Check whether this parser supports the content's type.

Returns:

Name	Type	Description
bool	bool	True if the content type is supported; False otherwise.

CsvScraper

CsvScraper(*, client: BaseCsvClient)

Scraper for csv documents.

Notes

Responsibilities:

- Fetch raw csv bytes via the configured client.
- Wrap the payload in a canonical `Content` instance with the
  CSV content type and source identifier.

Constraints:

- The scraper does not perform parsing or interpretation.
- Does not assume a specific storage backend.

Initialize the CSV scraper.

Parameters:

Name	Type	Description	Default
client	BaseCsvClient	Client responsible for retrieving raw csv bytes.	required

Functions

fetch

fetch(
    source: Any,
    *,
    metadata: Mapping[str, Any] | None = None
) -> Content

Fetch a csv document from the given source.

Parameters:

Name	Type	Description	Default
source	Any	Identifier of the csv source as understood by the configured client.	required
metadata	Mapping[str, Any] | None	Optional metadata to attach to the returned content.	None

Returns:

Name	Type	Description
Content	Content	A Content instance containing raw csv bytes, source identifier, CSV content type, and optional metadata.

Raises:

Type	Description
Exception	Retrieval-specific errors raised by the client.

FileSystemCsvClient

Bases: BaseCsvClient

CSV client that reads from the local filesystem.

Notes

Guarantees:

- This client reads csv files directly from the disk and
  returns their raw binary contents.

Functions

fetch

fetch(path: Path) -> bytes

Read a csv file from the local filesystem.

Parameters:

Name	Type	Description	Default
path	Path	Filesystem path to the csv file.	required

Returns:

Name	Type	Description
bytes	bytes	Raw csv bytes.

Raises:

Type	Description
FileNotFoundError	If the path does not exist.
ValueError	If the path exists but is not a file.