excelizarr 0.1.0__py3-none-any.whl

excelizarr/__init__.py

@@ -0,0 +1,35 @@
+"""A cloud-native representation of an ``.xlsx`` workbook, in Zarr.
+
+A workbook becomes a zarr group, each sheet a group of aligned, chunked, typed 2D
+arrays. Read a range straight off object storage, ``pd.read_excel`` a store without
+unzipping any XML, and convert back to ``.xlsx`` with formulas and number formats
+intact::
+
+    import excelizarr as xz
+
+    wb = xz.xlsx_to_zarr("model.xlsx", "s3://bucket/model.zarr")
+    wb["Inputs!B2:D10"]
+    df = xz.read_excel("s3://bucket/model.zarr", sheet_name="Inputs")
+    xz.zarr_to_xlsx("s3://bucket/model.zarr", "roundtrip.xlsx")
+"""
+
+from . import _version
+from .api import open_workbook, read_excel, xlsx_to_zarr, zarr_to_xlsx
+from .exceptions import ExcelizarrError, FormatVersionError, InvalidReferenceError
+from .kinds import CellKind
+from .workbook import ZarrSheet, ZarrWorkbook
+
+__all__ = [
+    "CellKind",
+    "ExcelizarrError",
+    "FormatVersionError",
+    "InvalidReferenceError",
+    "ZarrSheet",
+    "ZarrWorkbook",
+    "open_workbook",
+    "read_excel",
+    "xlsx_to_zarr",
+    "zarr_to_xlsx",
+]
+
+__version__ = _version.get_versions()["version"]

excelizarr/_pandas.py

@@ -0,0 +1,185 @@
+"""``pandas.read_excel``, but the "Excel file" is a zarr store.
+
+Rather than re-implementing ``read_excel``'s argument handling (``header``,
+``index_col``, ``usecols``, ``skiprows``, ``nrows``, ``parse_dates``, ``dtype``, ...),
+this plugs a zarr-backed sheet source into pandas' own ``BaseExcelReader``. pandas then
+does everything it does for a real ``.xlsx`` after the cells have been read, so the
+result matches ``pd.read_excel(path, engine="openpyxl")`` by construction, and the
+test suite checks that it does.
+
+The one thing pandas asks of a reader is ``get_sheet_data``: rows of Python values,
+converted the way its openpyxl reader converts them (empty → ``""``, error → ``NaN``,
+integral numbers → ``int``), with trailing empty cells and rows trimmed. When pandas
+only needs the first ``n`` rows (``nrows``), only those rows are read from the store.
+
+``BaseExcelReader`` is pandas-internal API. It has been stable for years, but if a
+pandas release moves it, this module is the only place that needs to change.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+from pandas.io.excel._base import BaseExcelReader  # type: ignore[attr-defined]
+
+from .kinds import CellKind, Slot
+from .model import as_ints, decode, value_slots
+from .workbook import ZarrSheet, ZarrWorkbook
+
+__all__ = ["ZarrExcelReader", "sheet_data"]
+
+
+def sheet_data(
+    sheet: ZarrSheet, file_rows_needed: int | None = None
+) -> list[list[Any]]:
+    """Read a sheet as pandas' openpyxl reader would hand it to its parser.
+
+    Parameters
+    ----------
+    sheet : ZarrSheet
+        The sheet.
+    file_rows_needed : int, optional
+        Read at most this many rows from the top.
+
+    Returns
+    -------
+    list of list
+        Row-major cell values, rectangular, trailing empties trimmed.
+    """
+    nrows, ncols = sheet.shape
+    if file_rows_needed is not None:
+        nrows = min(nrows, file_rows_needed)
+    if nrows == 0 or ncols == 0:
+        return []
+    slots = sheet.slots((slice(0, nrows), slice(0, ncols)))
+    kind = slots[Slot.KIND]
+    slots.prefetch(value_slots(kind))
+    vals = decode(slots)
+
+    # pandas' openpyxl reader: whole-number floats come back as ints, errors as NaN
+    is_float = kind == CellKind.FLOAT
+    if is_float.any():
+        number = slots[Slot.NUMBER]
+        whole = is_float & (number == np.floor(number))
+        if whole.any():
+            vals[whole] = as_ints(number[whole])
+    vals[kind == CellKind.ERROR] = np.nan
+
+    # pandas' openpyxl reader spells an empty cell "", and trims on that
+    empty = kind == CellKind.EMPTY
+    vals[empty] = ""
+
+    filled = ~empty
+    if not filled.any():
+        return []
+    last_row = int(np.flatnonzero(filled.any(axis=1))[-1]) + 1
+    last_col = int(np.flatnonzero(filled.any(axis=0))[-1]) + 1
+    rows: list[list[Any]] = vals[:last_row, :last_col].tolist()
+    return rows
+
+
+class ZarrExcelReader(BaseExcelReader[ZarrWorkbook]):
+    """A pandas Excel reader whose "file" is a :class:`~.workbook.ZarrWorkbook`.
+
+    Parameters
+    ----------
+    workbook : ZarrWorkbook
+        The workbook to read sheets from.
+    """
+
+    def __init__(self, workbook: ZarrWorkbook) -> None:
+        super().__init__(workbook)
+
+    @property
+    def _workbook_class(self) -> type[ZarrWorkbook]:
+        return ZarrWorkbook
+
+    def load_workbook(
+        self, filepath_or_buffer: Any, engine_kwargs: Any
+    ) -> ZarrWorkbook:
+        """Never called: the workbook is always handed over already open.
+
+        Parameters
+        ----------
+        filepath_or_buffer : object
+            Unused.
+        engine_kwargs : object
+            Unused.
+
+        Returns
+        -------
+        ZarrWorkbook
+            Never returns.
+
+        Raises
+        ------
+        TypeError
+            Always.
+        """
+        raise TypeError("ZarrExcelReader takes an open ZarrWorkbook")
+
+    @property
+    def sheet_names(self) -> list[str]:
+        """Return the workbook's sheet names, in tab order.
+
+        Returns
+        -------
+        list of str
+            Sheet names, in tab order.
+        """
+        book: ZarrWorkbook = self.book
+        return book.sheet_names
+
+    def get_sheet_by_name(self, name: str) -> ZarrSheet:
+        """Return a sheet by name, with pandas' error for a missing one.
+
+        Parameters
+        ----------
+        name : str
+            The sheet name.
+
+        Returns
+        -------
+        ZarrSheet
+            The sheet.
+        """
+        self.raise_if_bad_sheet_by_name(name)
+        book: ZarrWorkbook = self.book
+        return book.sheet(name)
+
+    def get_sheet_by_index(self, index: int) -> ZarrSheet:
+        """Return a sheet by tab position, with pandas' error for a missing one.
+
+        Parameters
+        ----------
+        index : int
+            Zero-based tab position.
+
+        Returns
+        -------
+        ZarrSheet
+            The sheet.
+        """
+        self.raise_if_bad_sheet_by_index(index)
+        book: ZarrWorkbook = self.book
+        return book.sheet(index)
+
+    def get_sheet_data(
+        self, sheet: ZarrSheet, file_rows_needed: int | None = None
+    ) -> list[list[Any]]:
+        """Rows of Python values for pandas' parser; see :func:`sheet_data`.
+
+        Parameters
+        ----------
+        sheet : ZarrSheet
+            The sheet.
+        file_rows_needed : int, optional
+            Read at most this many rows from the top.
+
+        Returns
+        -------
+        list of list
+            Row-major cell values.
+        """
+        return sheet_data(sheet, file_rows_needed)

excelizarr/_refs.py

@@ -0,0 +1,226 @@
+"""A1-style references: ``"B2"``, ``"A:C"``, ``"'My Sheet'!$B$2:D10"``.
+
+Everything here works in **zero-based, half-open** coordinates, which is what the zarr
+arrays are indexed in: ``"B2:D10"`` is rows ``1:10`` and columns ``1:4``. Whole-column
+and whole-row ranges (``"A:C"``, ``"2:5"``) leave the other axis open (``None``), and
+it is the caller's job to clip that to the sheet's shape.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+from .exceptions import InvalidReferenceError
+
+__all__ = [
+    "MAX_COLS",
+    "MAX_ROWS",
+    "RangeRef",
+    "col_to_index",
+    "format_range",
+    "index_to_col",
+    "parse_range",
+]
+
+#: Excel's own limits: ``XFD1048576`` is the last cell of a sheet.
+MAX_ROWS = 1_048_576
+MAX_COLS = 16_384
+
+_CELL = re.compile(r"^\$?([A-Za-z]{1,3})\$?([0-9]+)$")
+_COL = re.compile(r"^\$?([A-Za-z]{1,3})$")
+_ROW = re.compile(r"^\$?([0-9]+)$")
+
+
+def col_to_index(letters: str) -> int:
+    """Convert column letters to a zero-based index (``"A"`` is 0, ``"AA"`` is 26).
+
+    Parameters
+    ----------
+    letters : str
+        One to three letters, either case.
+
+    Returns
+    -------
+    int
+        The zero-based column index.
+
+    Raises
+    ------
+    InvalidReferenceError
+        If ``letters`` isn't a column Excel could have.
+    """
+    if (
+        not letters
+        or not letters.isascii()
+        or not letters.isalpha()
+        or len(letters) > 3
+    ):
+        raise InvalidReferenceError(f"not a column: {letters!r}")
+    n = 0
+    for ch in letters.upper():
+        n = n * 26 + (ord(ch) - ord("A") + 1)
+    if n > MAX_COLS:
+        raise InvalidReferenceError(f"column {letters!r} is past XFD")
+    return n - 1
+
+
+def index_to_col(index: int) -> str:
+    """Convert a zero-based column index to letters (0 is ``"A"``, 26 is ``"AA"``).
+
+    Parameters
+    ----------
+    index : int
+        A column index in ``[0, MAX_COLS)``.
+
+    Returns
+    -------
+    str
+        The upper-case column letters.
+
+    Raises
+    ------
+    InvalidReferenceError
+        If ``index`` is outside the sheet.
+    """
+    if not 0 <= index < MAX_COLS:
+        raise InvalidReferenceError(f"column index {index} is outside the sheet")
+    out = ""
+    n = index + 1
+    while n:
+        n, rem = divmod(n - 1, 26)
+        out = chr(ord("A") + rem) + out
+    return out
+
+
+@dataclass(frozen=True)
+class RangeRef:
+    """A parsed range: an optional sheet plus half-open, zero-based row/col bounds.
+
+    ``None`` on a bound means "open on that side": ``"A:C"`` has ``row_start`` and
+    ``row_stop`` both ``None``.
+    """
+
+    sheet: str | None
+    row_start: int | None
+    row_stop: int | None
+    col_start: int | None
+    col_stop: int | None
+
+    def resolve(self, shape: tuple[int, int]) -> tuple[slice, slice]:
+        """Clip the open bounds to a sheet ``shape`` and return two slices.
+
+        Parameters
+        ----------
+        shape : tuple of int
+            The ``(rows, cols)`` extent of the sheet.
+
+        Returns
+        -------
+        tuple of slice
+            ``(rows, cols)`` slices, never reaching past ``shape``.
+        """
+        nrows, ncols = shape
+        r0 = 0 if self.row_start is None else min(self.row_start, nrows)
+        r1 = nrows if self.row_stop is None else min(self.row_stop, nrows)
+        c0 = 0 if self.col_start is None else min(self.col_start, ncols)
+        c1 = ncols if self.col_stop is None else min(self.col_stop, ncols)
+        return slice(r0, max(r0, r1)), slice(c0, max(c0, c1))
+
+
+def _split_sheet(ref: str) -> tuple[str | None, str]:
+    if "!" not in ref:
+        return None, ref
+    sheet, _, rest = ref.rpartition("!")
+    if len(sheet) >= 2 and sheet[0] == sheet[-1] == "'":
+        sheet = sheet[1:-1].replace("''", "'")
+    if not sheet:
+        raise InvalidReferenceError(f"empty sheet name in {ref!r}")
+    return sheet, rest
+
+
+def _parse_endpoint(part: str) -> tuple[int | None, int | None]:
+    """Parse one side of a range into (row, col), either of which may be open."""
+    if m := _CELL.match(part):
+        row = int(m.group(2))
+        if not 1 <= row <= MAX_ROWS:
+            raise InvalidReferenceError(f"row {row} is outside the sheet")
+        return row - 1, col_to_index(m.group(1))
+    if m := _COL.match(part):
+        return None, col_to_index(m.group(1))
+    if m := _ROW.match(part):
+        row = int(m.group(1))
+        if not 1 <= row <= MAX_ROWS:
+            raise InvalidReferenceError(f"row {row} is outside the sheet")
+        return row - 1, None
+    raise InvalidReferenceError(f"not a cell, column or row: {part!r}")
+
+
+def parse_range(ref: str) -> RangeRef:
+    """Parse an A1-style reference into a :class:`RangeRef`.
+
+    Accepts a single cell (``"B2"``), a rectangle (``"B2:D10"``, either corner first),
+    whole columns (``"A:C"``), whole rows (``"2:5"``), ``$`` absolute markers and an
+    optional sheet prefix, quoted the way Excel quotes it (``"'Q1 ''24'!A1"``).
+
+    Parameters
+    ----------
+    ref : str
+        The reference to parse.
+
+    Returns
+    -------
+    RangeRef
+        Zero-based, half-open bounds.
+
+    Raises
+    ------
+    InvalidReferenceError
+        If ``ref`` doesn't parse, or mixes a column-only end with a row-only end.
+    """
+    sheet, body = _split_sheet(ref.strip())
+    parts = body.split(":")
+    if len(parts) == 1:
+        if not _CELL.match(parts[0]):
+            raise InvalidReferenceError(f"not a cell reference: {ref!r}")
+        parts = [parts[0], parts[0]]
+    if len(parts) != 2:
+        raise InvalidReferenceError(f"too many ':' in {ref!r}")
+    (ra, ca), (rb, cb) = (_parse_endpoint(p) for p in parts)
+    if (ra is None) != (rb is None) or (ca is None) != (cb is None):
+        raise InvalidReferenceError(f"mismatched range ends in {ref!r}")
+    if ra is None and ca is None:  # pragma: no cover - unreachable by the regexes
+        raise InvalidReferenceError(f"empty range {ref!r}")
+
+    def bounds(a: int | None, b: int | None) -> tuple[int | None, int | None]:
+        if a is None or b is None:
+            return None, None
+        return min(a, b), max(a, b) + 1
+
+    r0, r1 = bounds(ra, rb)
+    c0, c1 = bounds(ca, cb)
+    return RangeRef(sheet, r0, r1, c0, c1)
+
+
+def format_range(row_start: int, row_stop: int, col_start: int, col_stop: int) -> str:
+    """Format half-open zero-based bounds back to an A1 range (``"B2:D10"``).
+
+    Parameters
+    ----------
+    row_start : int
+        First row, zero-based.
+    row_stop : int
+        One past the last row.
+    col_start : int
+        First column, zero-based.
+    col_stop : int
+        One past the last column.
+
+    Returns
+    -------
+    str
+        The A1 range, or a single cell reference when the range is one cell.
+    """
+    top_left = f"{index_to_col(col_start)}{row_start + 1}"
+    bottom_right = f"{index_to_col(col_stop - 1)}{row_stop}"
+    return top_left if top_left == bottom_right else f"{top_left}:{bottom_right}"

excelizarr/_version.py

@@ -0,0 +1,21 @@
+
+# This file was generated by 'versioneer.py' (0.29) from
+# revision-control system data, or from the parent directory name of an
+# unpacked source archive. Distribution tarballs contain a pre-generated copy
+# of this file.
+
+import json
+
+version_json = '''
+{
+ "date": "2026-10-12T17:45:19+1100",
+ "dirty": false,
+ "error": null,
+ "full-revisionid": "803bf2468fccbd6a42dd13476df85b208c3a2899",
+ "version": "0.1.0"
+}
+'''  # END VERSION_JSON
+
+
+def get_versions():
+    return json.loads(version_json)

excelizarr/api.py

@@ -0,0 +1,155 @@
+"""The top-level verbs: convert, open, read, convert back."""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+import zarr
+from zarr.storage import StoreLike
+
+from .io_xlsx import Engine, load_xlsx
+from .io_zarr import DEFAULT_CHUNKS, DEFAULT_SHARDS, open_root, write_model
+from .workbook import ZarrWorkbook
+
+__all__ = ["open_workbook", "read_excel", "xlsx_to_zarr", "zarr_to_xlsx"]
+
+
+def xlsx_to_zarr(
+    src: str | os.PathLike[str],
+    store: StoreLike,
+    *,
+    engine: Engine = "openpyxl",
+    chunks: tuple[int, int] = DEFAULT_CHUNKS,
+    shards: tuple[int, int] | None = DEFAULT_SHARDS,
+    mode: str = "w-",
+    storage_options: dict[str, Any] | None = None,
+) -> ZarrWorkbook:
+    """Convert an ``.xlsx`` file into a zarr workbook store.
+
+    Parameters
+    ----------
+    src : str or os.PathLike
+        The ``.xlsx`` file.
+    store : StoreLike
+        Where to write: a path, an ``s3://``/``gs://`` URL, a ``MemoryStore``, a
+        ``ZipStore``, an Icechunk session's ``store``, ...
+    engine : {"openpyxl", "calamine"}
+        ``openpyxl`` keeps formulas, number formats and layout; ``calamine`` (the
+        ``fast`` extra) keeps values only, and is much faster.
+    chunks : tuple of int
+        ``(rows, cols)`` per chunk.
+    shards : tuple of int or None
+        ``(rows, cols)`` per shard, or ``None`` to write every chunk as its own
+        object.
+    mode : str
+        ``"w-"`` (default) refuses to overwrite an existing store; ``"w"`` replaces it.
+    storage_options : dict, optional
+        Passed through to fsspec for URL stores.
+
+    Returns
+    -------
+    ZarrWorkbook
+        The written workbook, open for reading.
+    """
+    model = load_xlsx(src, engine=engine)
+    root = write_model(
+        model,
+        store,
+        chunks=chunks,
+        shards=shards,
+        mode=mode,
+        storage_options=storage_options,
+    )
+    return ZarrWorkbook(root)
+
+
+def open_workbook(
+    store: StoreLike | zarr.Group,
+    *,
+    mode: str = "r",
+    storage_options: dict[str, Any] | None = None,
+) -> ZarrWorkbook:
+    """Open a zarr workbook store lazily.
+
+    Parameters
+    ----------
+    store : StoreLike or zarr.Group
+        The store, or its already-open root group.
+    mode : str
+        ``"r"`` (default) for read-only; ``"r+"`` to allow in-place cell writes.
+    storage_options : dict, optional
+        Passed through to fsspec for URL stores.
+
+    Returns
+    -------
+    ZarrWorkbook
+        The workbook. Nothing but its root attributes has been read yet.
+    """
+    return ZarrWorkbook(open_root(store, mode=mode, storage_options=storage_options))
+
+
+def read_excel(
+    store: StoreLike | zarr.Group | ZarrWorkbook,
+    sheet_name: str | int | list[str | int] | None = 0,
+    *,
+    storage_options: dict[str, Any] | None = None,
+    **kwargs: Any,
+) -> Any:
+    """``pandas.read_excel``, reading from a zarr workbook store instead of ``.xlsx``.
+
+    pandas' own argument handling runs on the cells, so every keyword ``read_excel``
+    takes works the same way here, and the frame you get is the frame you'd have got
+    from the original file.
+
+    Parameters
+    ----------
+    store : StoreLike, zarr.Group or ZarrWorkbook
+        The workbook.
+    sheet_name : str, int, list or None
+        As for ``pandas.read_excel``: a name, a position, a list of either (returns a
+        dict), or ``None`` for every sheet (returns a dict).
+    storage_options : dict, optional
+        Passed through to fsspec for URL stores.
+    **kwargs
+        Anything else ``pandas.read_excel`` takes: ``header``, ``index_col``,
+        ``usecols``, ``skiprows``, ``nrows``, ``dtype``, ``parse_dates``, ...
+
+    Returns
+    -------
+    pandas.DataFrame or dict of pandas.DataFrame
+        As ``pandas.read_excel`` would return.
+    """
+    from ._pandas import ZarrExcelReader
+
+    wb = (
+        store
+        if isinstance(store, ZarrWorkbook)
+        else open_workbook(store, storage_options=storage_options)
+    )
+    return ZarrExcelReader(wb).parse(sheet_name=sheet_name, **kwargs)
+
+
+def zarr_to_xlsx(
+    store: StoreLike | zarr.Group | ZarrWorkbook,
+    dst: str | os.PathLike[str],
+    *,
+    storage_options: dict[str, Any] | None = None,
+) -> None:
+    """Convert a zarr workbook store back into an ``.xlsx`` file.
+
+    Parameters
+    ----------
+    store : StoreLike, zarr.Group or ZarrWorkbook
+        The workbook.
+    dst : str or os.PathLike
+        The ``.xlsx`` file to write.
+    storage_options : dict, optional
+        Passed through to fsspec for URL stores.
+    """
+    wb = (
+        store
+        if isinstance(store, ZarrWorkbook)
+        else open_workbook(store, storage_options=storage_options)
+    )
+    wb.to_xlsx(dst)

excelizarr/exceptions.py

@@ -0,0 +1,15 @@
+"""The exceptions excelizarr raises on purpose."""
+
+__all__ = ["ExcelizarrError", "FormatVersionError", "InvalidReferenceError"]
+
+
+class ExcelizarrError(Exception):
+    """Base class for every error excelizarr raises deliberately."""
+
+
+class InvalidReferenceError(ExcelizarrError, ValueError):
+    """An A1-style cell or range reference that doesn't parse, or names no sheet."""
+
+
+class FormatVersionError(ExcelizarrError):
+    """A store that isn't an excelizarr workbook, or is one from a format we can't read."""