Xlsx

omniread.xlsx

Summary

XLSX subpackage for OmniRead.

Provides acquisition and parsing of Office Open XML spreadsheet (xlsx) content:

• BaseXlsxClient: abstract backing-store client for xlsx bytes.
• FileSystemXlsxClient: local filesystem implementation.
• XlsxScraper: wraps fetched bytes into canonical Content.
• XlsxParserBase: content-type-enforcing parser contract.
• XlsxParser: generic string-row parser built on openpyxl.

Classes

BaseXlsxClient

Bases: ABC

Abstract client responsible for retrieving spreadsheet 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 xlsx binary payload.
- Raise retrieval-specific errors on failure.

Functions

fetch abstractmethod

fetch(source: Any) -> bytes

Fetch raw xlsx bytes from the given source.

Parameters:

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

Returns:

Name	Type	Description
bytes	bytes	Raw xlsx bytes.

Raises:

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

FileSystemXlsxClient

Bases: BaseXlsxClient

XLSX client that reads from the local filesystem.

Notes

Guarantees:

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

Functions

fetch

fetch(path: Path) -> bytes

Read an xlsx file from the local filesystem.

Parameters:

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

Returns:

Name	Type	Description
bytes	bytes	Raw xlsx bytes.

Raises:

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

XlsxParser

XlsxParser(
    content: Content,
    *,
    data_only: bool = True,
    read_only: bool = True
)

Bases: XlsxParserBase[list[list[str]]]

Generic xlsx parser producing string rows from a worksheet.

Notes

Responsibilities:

- Lazily load the workbook owned by the parser's content.
- Normalize cells (including dates and numeric values) into
  deterministic string representations.
- Expose sheet discovery and row extraction helpers.

Constraints:

- Cells are rendered with ``str(value)`` after trimming; date and
  datetime values are rendered in ISO format. Consumers requiring
  locale-specific formatting must convert on their side.

Initialize the parser.

Parameters:

Name	Type	Description	Default
content	Content	XLSX content to parse; its type must be supported.	required
data_only	bool	Passed to openpyxl: when True, formula cells yield their last computed value instead of the formula string.	True
read_only	bool	Passed to openpyxl: streaming mode for lower memory usage.	True

Attributes

sheet_names property

sheet_names: list[str]

Names of all worksheets contained in the workbook.

supported_types class-attribute instance-attribute

supported_types: set[ContentType] = {XLSX}

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

workbook property

workbook: Workbook

The lazily loaded workbook backing this parser's content.

Functions

parse

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

Parse the first worksheet into normalized string rows.

Returns:

Type	Description
list[list[str]]	list[list[str]]: Rows of the default (first) worksheet.

rows

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

Extract normalized string rows from a worksheet.

Parameters:

Name	Type	Description	Default
sheet	int | str | None	Worksheet index or title; defaults to the first worksheet.	None
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.

Raises:

Type	Description
ValueError	If the requested sheet does not exist.

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.

XlsxParserBase

XlsxParserBase(content: Content)

Bases: BaseParser[T], Generic[T]

Base xlsx parser.

Notes

Responsibilities:

- This class enforces xlsx content-type compatibility and provides
  the extension point for implementing concrete xlsx 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] = {XLSX}

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

Functions

parse abstractmethod

parse() -> T

Parse xlsx 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.

XlsxScraper

XlsxScraper(*, client: BaseXlsxClient)

Scraper for xlsx spreadsheet documents.

Notes

Responsibilities:

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

Constraints:

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

Initialize the XLSX scraper.

Parameters:

Name	Type	Description	Default
client	BaseXlsxClient	Client responsible for retrieving raw spreadsheet bytes.	required

Functions

fetch

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

Fetch an xlsx document from the given source.

Parameters:

Name	Type	Description	Default
source	Any	Identifier of the spreadsheet 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 xlsx bytes, source identifier, XLSX content type, and optional metadata.

Raises:

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