pyhandlexl 0.2.0__py3-none-any.whl

pyhandlexl/__init__.py

@@ -0,0 +1,46 @@
+"""pyhandlexl — read and write raw cell values in Excel .xlsx files."""
+
+from pyhandlexl.core import (
+    append_rows,
+    create_sheet,
+    delete_sheet,
+    list_sheets,
+    read_sheet,
+    rename_sheet,
+    sheet_exists,
+    write_sheet,
+)
+from pyhandlexl.errors import (
+    DimensionError,
+    FileLockedError,
+    InvalidFileError,
+    PyhandlexlError,
+    SheetNameError,
+    SheetNotFoundError,
+)
+from pyhandlexl.table import Table, TableData
+from pyhandlexl.validate import check_dimensions, check_sheet_name, is_valid_xlsx
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "DimensionError",
+    "FileLockedError",
+    "InvalidFileError",
+    "PyhandlexlError",
+    "SheetNameError",
+    "SheetNotFoundError",
+    "Table",
+    "TableData",
+    "append_rows",
+    "check_dimensions",
+    "check_sheet_name",
+    "create_sheet",
+    "delete_sheet",
+    "is_valid_xlsx",
+    "list_sheets",
+    "read_sheet",
+    "rename_sheet",
+    "sheet_exists",
+    "write_sheet",
+]

pyhandlexl/_safety.py

@@ -0,0 +1,116 @@
+"""Resilient workbook I/O: retry-on-lock loading and atomic saving.
+
+Internal module — not part of the public API.
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Callable
+from pathlib import Path
+from secrets import token_hex
+from time import sleep
+from typing import TypeVar
+from zipfile import BadZipFile
+
+from openpyxl import Workbook, load_workbook
+
+from pyhandlexl.errors import FileLockedError, InvalidFileError
+from pyhandlexl.validate import is_valid_xlsx
+
+_T = TypeVar("_T")
+
+DEFAULT_RETRIES = 5
+DEFAULT_DELAY = 0.5
+
+# Raised when a file is briefly unavailable: open in Excel, or a competing
+# writer has not finished flushing it yet. Worth retrying.
+_TRANSIENT_ERRORS = (PermissionError, BadZipFile, EOFError)
+
+
+def _retry(
+    operation: Callable[[], _T],
+    *,
+    path: Path,
+    retries: int = DEFAULT_RETRIES,
+    delay: float = DEFAULT_DELAY,
+) -> _T:
+    """Run *operation*, retrying on transient file errors.
+
+    Raises FileLockedError if it never succeeds.
+    """
+    last_error: Exception | None = None
+    for attempt in range(1, retries + 1):
+        try:
+            return operation()
+        except _TRANSIENT_ERRORS as error:
+            last_error = error
+            if attempt < retries:
+                sleep(delay)
+    raise FileLockedError(
+        f"could not access {path} after {retries} attempt(s): {last_error}"
+    ) from last_error
+
+
+def safe_load(
+    path: str | Path,
+    *,
+    retries: int = DEFAULT_RETRIES,
+    delay: float = DEFAULT_DELAY,
+) -> Workbook:
+    """Load an existing workbook, retrying while the file is locked.
+
+    Raises:
+        FileNotFoundError: no file at *path*.
+        InvalidFileError: the file exists but is not a readable .xlsx.
+        FileLockedError: the file stayed locked through every retry.
+    """
+    path = Path(path)
+    if not path.exists():
+        raise FileNotFoundError(f"no file at {path}")
+    if not is_valid_xlsx(path):
+        raise InvalidFileError(f"{path} is not a readable .xlsx workbook")
+    return _retry(lambda: load_workbook(path), path=path, retries=retries, delay=delay)
+
+
+def load_or_create(
+    path: str | Path,
+    *,
+    retries: int = DEFAULT_RETRIES,
+    delay: float = DEFAULT_DELAY,
+) -> Workbook:
+    """Load the workbook at *path*, or return a new empty one if it does not exist."""
+    path = Path(path)
+    if not path.exists():
+        return Workbook()
+    return safe_load(path, retries=retries, delay=delay)
+
+
+def atomic_save(
+    workbook: Workbook,
+    path: str | Path,
+    *,
+    retries: int = DEFAULT_RETRIES,
+    delay: float = DEFAULT_DELAY,
+) -> None:
+    """Save *workbook* to *path* without risking the file already there.
+
+    Writes to a temporary file in the same directory, verifies it is a
+    readable .xlsx, then atomically replaces the target. On any failure the
+    temporary file is removed and the original is left untouched.
+
+    Raises:
+        InvalidFileError: the freshly written file failed validation.
+        FileLockedError: the target stayed locked through every retry.
+    """
+    path = Path(path)
+    tmp = path.parent / f".{path.stem}.{token_hex(6)}.tmp.xlsx"
+    try:
+        _retry(lambda: workbook.save(tmp), path=path, retries=retries, delay=delay)
+        if not is_valid_xlsx(tmp):
+            raise InvalidFileError(
+                f"wrote a temporary file for {path} but it failed validation; {path} left unchanged"
+            )
+        _retry(lambda: os.replace(tmp, path), path=path, retries=retries, delay=delay)
+    finally:
+        tmp.unlink(missing_ok=True)

pyhandlexl/core.py

@@ -0,0 +1,250 @@
+"""Public functions for reading and writing whole sheets of raw values."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from itertools import zip_longest
+from pathlib import Path
+from typing import Literal
+
+from pyhandlexl._safety import atomic_save, load_or_create, safe_load
+from pyhandlexl.errors import SheetNotFoundError
+from pyhandlexl.validate import check_dimensions, check_sheet_name
+
+Orientation = Literal["rows", "columns"]
+
+
+def _cell_to_str(value: object) -> str:
+    """Coerce a cell value to a string; ``None`` becomes ``""``."""
+    return "" if value is None else str(value)
+
+
+def read_sheet(
+    path: str | Path,
+    sheet: str | None = None,
+    *,
+    pad: bool = False,
+) -> list[list[str]]:
+    """Read a worksheet as a list of rows of strings.
+
+    Every value is converted to ``str``; empty cells become ``""``. Trailing
+    empty cells are trimmed from each row, so a fully empty row becomes ``[]``.
+
+    Args:
+        path: the .xlsx file.
+        sheet: worksheet name, or ``None`` for the active sheet.
+        pad: if true, right-pad every row with ``""`` to the length of the
+            longest row, making the result rectangular.
+
+    Raises:
+        FileNotFoundError: no file at *path*.
+        InvalidFileError: the file is not a readable .xlsx.
+        SheetNotFoundError: *sheet* names a worksheet that does not exist.
+    """
+    workbook = safe_load(path)
+    try:
+        if sheet is None:
+            worksheet = workbook.active
+        elif sheet in workbook.sheetnames:
+            worksheet = workbook[sheet]
+        else:
+            raise SheetNotFoundError(sheet)
+
+        rows: list[list[str]] = []
+        for raw_row in worksheet.iter_rows(values_only=True):
+            row = [_cell_to_str(value) for value in raw_row]
+            while row and row[-1] == "":
+                row.pop()
+            rows.append(row)
+    finally:
+        workbook.close()
+
+    if pad and rows:
+        width = max(len(row) for row in rows)
+        rows = [row + [""] * (width - len(row)) for row in rows]
+    return rows
+
+
+def write_sheet(
+    path: str | Path,
+    rows: Iterable[Iterable[object]],
+    sheet: str | None = None,
+    *,
+    orientation: Orientation = "rows",
+) -> None:
+    """Replace a worksheet's contents with *rows*.
+
+    Other worksheets in the file are left untouched. The file is created if it
+    does not exist, and *sheet* is added if it does not exist.
+
+    Values are written as-is (``str``, ``int``, ``float``, ``bool``); ``None``
+    leaves the cell empty. No string-to-number conversion is performed.
+
+    Args:
+        path: the .xlsx file.
+        rows: an iterable of iterables of cell values.
+        sheet: worksheet name, or ``None`` for the active sheet.
+        orientation: ``"rows"`` writes each inner iterable as a row;
+            ``"columns"`` writes each inner iterable down a column.
+
+    Raises:
+        SheetNameError: *sheet* is not a valid worksheet name.
+        DimensionError: the data exceeds the .xlsx row or column limits.
+        ValueError: *orientation* is not ``"rows"`` or ``"columns"``.
+    """
+    if orientation not in ("rows", "columns"):
+        raise ValueError(f"orientation must be 'rows' or 'columns', got {orientation!r}")
+
+    grid = [list(row) for row in rows]
+    if orientation == "columns":
+        grid = [list(column) for column in zip_longest(*grid, fillvalue="")]
+
+    check_dimensions(len(grid), max((len(row) for row in grid), default=0))
+
+    if sheet is not None:
+        check_sheet_name(sheet)
+
+    file_existed = Path(path).is_file()
+    workbook = load_or_create(path)
+    try:
+        if not file_existed:
+            for name in list(workbook.sheetnames):
+                workbook.remove(workbook[name])
+            worksheet = workbook.create_sheet(title=sheet or "Sheet")
+        else:
+            name = sheet if sheet is not None else workbook.active.title
+            if name in workbook.sheetnames:
+                index = workbook.sheetnames.index(name)
+                workbook.remove(workbook[name])
+                worksheet = workbook.create_sheet(title=name, index=index)
+            else:
+                worksheet = workbook.create_sheet(title=name)
+
+        for row in grid:
+            worksheet.append(row)
+        atomic_save(workbook, path)
+    finally:
+        workbook.close()
+
+
+def append_rows(
+    path: str | Path,
+    rows: Iterable[Iterable[object]],
+    sheet: str | None = None,
+) -> None:
+    """Append *rows* to the end of a worksheet.
+
+    The file and *sheet* are created if they do not exist. An empty *rows* is
+    a no-op. Values follow the same rules as :func:`write_sheet`.
+
+    Raises:
+        SheetNameError: *sheet* is not a valid worksheet name.
+        DimensionError: appending would exceed the .xlsx row or column limits.
+    """
+    grid = [list(row) for row in rows]
+    if not grid:
+        return
+
+    if sheet is not None:
+        check_sheet_name(sheet)
+
+    workbook = load_or_create(path)
+    try:
+        if sheet is None:
+            worksheet = workbook.active
+        elif sheet in workbook.sheetnames:
+            worksheet = workbook[sheet]
+        else:
+            worksheet = workbook.create_sheet(title=sheet)
+
+        widest = max(len(row) for row in grid)
+        check_dimensions(worksheet.max_row + len(grid), max(widest, worksheet.max_column))
+
+        for row in grid:
+            worksheet.append(row)
+        atomic_save(workbook, path)
+    finally:
+        workbook.close()
+
+
+def list_sheets(path: str | Path) -> list[str]:
+    """Return the worksheet names in *path*, in order.
+
+    Raises:
+        FileNotFoundError: no file at *path*.
+        InvalidFileError: the file is not a readable .xlsx.
+    """
+    workbook = safe_load(path)
+    try:
+        return list(workbook.sheetnames)
+    finally:
+        workbook.close()
+
+
+def sheet_exists(path: str | Path, name: str) -> bool:
+    """Return whether *path* contains a worksheet called *name*."""
+    return name in list_sheets(path)
+
+
+def create_sheet(path: str | Path, name: str) -> None:
+    """Add an empty worksheet called *name*, creating the file if needed.
+
+    Raises:
+        SheetNameError: *name* is not a valid worksheet name.
+        ValueError: a worksheet called *name* already exists.
+    """
+    check_sheet_name(name)
+    file_existed = Path(path).is_file()
+    workbook = load_or_create(path)
+    try:
+        if name in workbook.sheetnames:
+            raise ValueError(f"sheet {name!r} already exists")
+        if file_existed:
+            workbook.create_sheet(title=name)
+        else:
+            workbook.active.title = name
+        atomic_save(workbook, path)
+    finally:
+        workbook.close()
+
+
+def delete_sheet(path: str | Path, name: str) -> None:
+    """Remove the worksheet called *name*.
+
+    Raises:
+        FileNotFoundError: no file at *path*.
+        SheetNotFoundError: no worksheet called *name*.
+        ValueError: *name* is the only worksheet (a workbook needs at least one).
+    """
+    workbook = safe_load(path)
+    try:
+        if name not in workbook.sheetnames:
+            raise SheetNotFoundError(name)
+        if len(workbook.sheetnames) == 1:
+            raise ValueError("cannot delete the only sheet in the workbook")
+        del workbook[name]
+        atomic_save(workbook, path)
+    finally:
+        workbook.close()
+
+
+def rename_sheet(path: str | Path, old: str, new: str) -> None:
+    """Rename worksheet *old* to *new*.
+
+    Raises:
+        SheetNameError: *new* is not a valid worksheet name.
+        FileNotFoundError: no file at *path*.
+        SheetNotFoundError: no worksheet called *old*.
+        ValueError: a different worksheet called *new* already exists.
+    """
+    check_sheet_name(new)
+    workbook = safe_load(path)
+    try:
+        if old not in workbook.sheetnames:
+            raise SheetNotFoundError(old)
+        if new != old and new in workbook.sheetnames:
+            raise ValueError(f"sheet {new!r} already exists")
+        workbook[old].title = new
+        atomic_save(workbook, path)
+    finally:
+        workbook.close()

pyhandlexl/errors.py

@@ -0,0 +1,28 @@
+"""Exception types raised by pyhandlexl."""
+
+
+class PyhandlexlError(Exception):
+    """Base class for every error raised by pyhandlexl.
+
+    Catch this to handle any failure from the library.
+    """
+
+
+class SheetNameError(PyhandlexlError, ValueError):
+    """A worksheet name is empty, too long, or contains illegal characters."""
+
+
+class DimensionError(PyhandlexlError, ValueError):
+    """The data has more rows or columns than the .xlsx format allows."""
+
+
+class InvalidFileError(PyhandlexlError):
+    """The file is missing, not a zip, or not a readable .xlsx workbook."""
+
+
+class FileLockedError(PyhandlexlError, OSError):
+    """The file stayed locked (e.g. open in Excel) after every retry."""
+
+
+class SheetNotFoundError(PyhandlexlError, KeyError):
+    """No worksheet with the requested name exists in the workbook."""

pyhandlexl/table.py

@@ -0,0 +1,373 @@
+"""The Table class: a worksheet read as column headers, row labels, and a data grid.
+
+Layout convention: row 1 holds the column headers, column A holds the row
+labels, cell A1 is the "corner", and the data region is everything from B2
+onward. Row labels and column headers are always strings. Positional access
+uses Excel coordinates (row 1 is the header row, column 1 is the label column).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from dataclasses import dataclass
+from pathlib import Path
+
+from openpyxl.utils import coordinate_to_tuple
+
+from pyhandlexl.core import read_sheet, write_sheet
+
+
+@dataclass(frozen=True)
+class TableData:
+    """A read-only snapshot of a Table's content."""
+
+    rows: list[list[object]]
+    columns: list[list[object]]
+    row_labels: list[str]
+    column_headers: list[str]
+    corner: object
+
+
+class Table:
+    """A labeled table backed by a worksheet.
+
+    Construct directly from parts, or with :meth:`read` from a file. Mutation
+    methods edit the table in place and return ``None``. Row labels and column
+    headers are always ``str``.
+    """
+
+    def __init__(
+        self,
+        data: Iterable[Iterable[object]],
+        column_headers: Iterable[str] = (),
+        row_labels: Iterable[str] = (),
+        corner: object = "",
+    ) -> None:
+        self._data: list[list[object]] = [list(row) for row in data]
+        self._column_headers: list[str] = list(column_headers)
+        self._row_labels: list[str] = list(row_labels)
+        self._corner: object = corner
+        self._validate()
+
+    def _validate(self) -> None:
+        for label in self._row_labels:
+            if not isinstance(label, str):
+                raise TypeError(f"row labels must be str, got {type(label).__name__}: {label!r}")
+        for header in self._column_headers:
+            if not isinstance(header, str):
+                raise TypeError(
+                    f"column headers must be str, got {type(header).__name__}: {header!r}"
+                )
+        if self._row_labels and len(self._row_labels) != len(self._data):
+            raise ValueError(f"{len(self._data)} data rows but {len(self._row_labels)} row labels")
+        if self._column_headers:
+            width = len(self._column_headers)
+            for i, row in enumerate(self._data):
+                if len(row) != width:
+                    raise ValueError(
+                        f"data row {i} has {len(row)} values but there are {width} column headers"
+                    )
+
+    # ------------------------------------------------------------------ read
+
+    @classmethod
+    def read(
+        cls,
+        path: str | Path,
+        sheet: str | None = None,
+        *,
+        column_headers: bool = True,
+        row_labels: bool = True,
+    ) -> Table:
+        """Read a worksheet into a Table.
+
+        Args:
+            path: the .xlsx file.
+            sheet: worksheet name, or ``None`` for the active sheet.
+            column_headers: treat row 1 as column headers.
+            row_labels: treat column A as row labels.
+        """
+        grid = read_sheet(path, sheet, pad=True)
+        if not grid:
+            return cls([], [], [], "")
+
+        row_start = 1 if column_headers else 0
+        col_start = 1 if row_labels else 0
+
+        corner = grid[0][0] if (column_headers and row_labels) else ""
+        headers = grid[0][col_start:] if column_headers else []
+        labels = [grid[r][0] for r in range(row_start, len(grid))] if row_labels else []
+        data = [grid[r][col_start:] for r in range(row_start, len(grid))]
+
+        return cls(data, headers, labels, corner)
+
+    # ------------------------------------------------------------ properties
+
+    @property
+    def corner(self) -> object:
+        """The value of cell A1. Settable — this is how you change it."""
+        return self._corner
+
+    @corner.setter
+    def corner(self, value: object) -> None:
+        self._corner = value
+
+    @property
+    def data(self) -> TableData:
+        """A snapshot of the table's rows, columns, row labels, column headers, and corner."""
+        return TableData(
+            rows=[list(row) for row in self._data],
+            columns=[list(column) for column in zip(*self._data, strict=True)],
+            row_labels=list(self._row_labels),
+            column_headers=list(self._column_headers),
+            corner=self._corner,
+        )
+
+    # ---------------------------------------------------------- label access
+
+    def _row_index(self, label: str) -> int:
+        try:
+            return self._row_labels.index(label)
+        except ValueError:
+            raise KeyError(f"no row labeled {label!r}") from None
+
+    def _column_index(self, header: str) -> int:
+        try:
+            return self._column_headers.index(header)
+        except ValueError:
+            raise KeyError(f"no column headed {header!r}") from None
+
+    def read_row(self, row_label: str) -> list[object]:
+        """The data row for *row_label* (labels not included)."""
+        return list(self._data[self._row_index(row_label)])
+
+    def read_column(self, column_header: str) -> list[object]:
+        """The data column for *column_header* (headers not included)."""
+        j = self._column_index(column_header)
+        return [row[j] for row in self._data]
+
+    # ------------------------------------------------- position/label access
+
+    def _width(self) -> int:
+        if self._column_headers:
+            return len(self._column_headers)
+        return len(self._data[0]) if self._data else 0
+
+    def _dimensions(self) -> tuple[int, int, int, int]:
+        row_start = 1 if self._column_headers else 0
+        col_start = 1 if self._row_labels else 0
+        n_rows = row_start + len(self._data)
+        n_cols = col_start + self._width()
+        return row_start, col_start, n_rows, n_cols
+
+    def _classify(self, row: int, col_num: int) -> tuple[str, int, int]:
+        """Return ``(kind, i, j)`` where *kind* is corner/header/label/data.
+
+        *i* and *j* are indices into the relevant list (``_data`` is indexed
+        by both).
+        """
+        row_start, col_start, n_rows, n_cols = self._dimensions()
+        if not (1 <= row <= n_rows and 1 <= col_num <= n_cols):
+            raise IndexError(f"cell ({row}, {col_num}) is outside the {n_rows}x{n_cols} table")
+
+        in_header_row = bool(self._column_headers) and row == 1
+        in_label_column = bool(self._row_labels) and col_num == 1
+        if in_header_row and in_label_column:
+            return "corner", 0, 0
+        if in_header_row:
+            return "header", 0, col_num - 1 - col_start
+        if in_label_column:
+            return "label", row - 1 - row_start, 0
+        return "data", row - 1 - row_start, col_num - 1 - col_start
+
+    def _dispatch(
+        self, ref: str | None, row: int | str | None, column: int | str | None
+    ) -> tuple[bool, int | str, int | str]:
+        """Resolve ``ref``/``row``/``column`` into ``(is_position, row_val, col_val)``.
+
+        ``is_position=True`` — ``row_val``/``col_val`` are 1-based Excel ints.
+        ``is_position=False`` — they are a row label / column header string.
+        """
+        if ref is not None:
+            if row is not None or column is not None:
+                raise TypeError("give either ref or row=/column=, not both")
+            r, c = coordinate_to_tuple(ref)
+            return True, r, c
+
+        if row is None or column is None:
+            raise TypeError("give a ref like 'B2', or both row= and column=")
+
+        if isinstance(row, int) and isinstance(column, int):
+            return True, row, column
+        if isinstance(row, str) and isinstance(column, str):
+            return False, row, column
+        raise TypeError("row and column must both be int (position) or both be str (label)")
+
+    def read_cell(
+        self,
+        ref: str | None = None,
+        *,
+        row: int | str | None = None,
+        column: int | str | None = None,
+    ) -> object:
+        """A single value, addressed either by position or by label.
+
+        Give either a ref like ``"B2"``, or ``row=``/``column=`` as a matching
+        pair: both ints for a 1-based Excel position (row 1 is the header row,
+        column 1 is the label column, so ``read_cell(row=2, column=2)`` is the
+        first data cell), or both strings for a row label / column header pair
+        — e.g. ``read_cell(row="Alice", column="q1")``.
+
+        By position, ``read_cell`` can reach any cell — header, label, corner,
+        or data. By label it always reads data (the label-addressed equivalent
+        of ``read_cell(row=2, column=2)``, wherever that intersection lives).
+        """
+        is_position, r, c = self._dispatch(ref, row, column)
+        if is_position:
+            kind, i, j = self._classify(r, c)
+            if kind == "corner":
+                return self._corner
+            if kind == "header":
+                return self._column_headers[j]
+            if kind == "label":
+                return self._row_labels[i]
+            return self._data[i][j]
+        return self._data[self._row_index(r)][self._column_index(c)]
+
+    # -------------------------------------------------------------- mutation
+
+    def set_cell(
+        self,
+        ref: str | None = None,
+        *,
+        row: int | str | None = None,
+        column: int | str | None = None,
+        value: object,
+    ) -> None:
+        """Set a single **data** value, addressed by position or by label.
+
+        Same addressing as :meth:`read_cell`. Only ever sets data — by
+        position, addressing a header, row label, or the corner raises
+        ``ValueError``; use :meth:`rename_column`, :meth:`rename_row`, or the
+        ``corner`` property for those. By label there's no other kind of cell
+        to reach, so it always sets data.
+        """
+        is_position, r, c = self._dispatch(ref, row, column)
+        if is_position:
+            self._set_by_position(r, c, value)
+        else:
+            self._data[self._row_index(r)][self._column_index(c)] = value
+
+    def _set_by_position(self, row: int, col_num: int, value: object) -> None:
+        kind, i, j = self._classify(row, col_num)
+        if kind == "corner":
+            raise ValueError("that cell is the corner — set it with table.corner = value")
+        if kind == "header":
+            raise ValueError("that cell is a column header — rename it with rename_column()")
+        if kind == "label":
+            raise ValueError("that cell is a row label — rename it with rename_row()")
+        self._data[i][j] = value
+
+    def set_row(self, row_label: str, values: Iterable[object]) -> None:
+        """Replace the data row for *row_label*; ``len(values)`` must match the column count."""
+        new_row = list(values)
+        i = self._row_index(row_label)
+        expected = self._width()
+        if len(new_row) != expected:
+            raise ValueError(f"expected {expected} values, got {len(new_row)}")
+        self._data[i] = new_row
+
+    def set_column(self, column_header: str, values: Iterable[object]) -> None:
+        """Replace the data column for *column_header*; ``len(values)`` must match the row count."""
+        new_col = list(values)
+        j = self._column_index(column_header)
+        if len(new_col) != len(self._data):
+            raise ValueError(f"expected {len(self._data)} values, got {len(new_col)}")
+        for data_row, value in zip(self._data, new_col, strict=True):
+            data_row[j] = value
+
+    def add_row(self, label: str, values: Iterable[object]) -> None:
+        """Append a labeled data row; ``len(values)`` must match the column count."""
+        if not isinstance(label, str):
+            raise TypeError(f"row label must be str, got {type(label).__name__}: {label!r}")
+        new_row = list(values)
+        if self._data and not self._row_labels:
+            raise ValueError("this table has no row labels; use the raw layer to add rows")
+        if (self._data or self._column_headers) and len(new_row) != self._width():
+            raise ValueError(f"expected {self._width()} values, got {len(new_row)}")
+        self._data.append(new_row)
+        self._row_labels.append(label)
+
+    def add_column(self, header: str, values: Iterable[object]) -> None:
+        """Append a labeled data column; ``len(values)`` must match the row count."""
+        if not isinstance(header, str):
+            raise TypeError(f"column header must be str, got {type(header).__name__}: {header!r}")
+        new_col = list(values)
+        if any(self._data) and not self._column_headers:
+            raise ValueError("this table has no column headers; use the raw layer to add columns")
+        if len(new_col) != len(self._data):
+            raise ValueError(f"expected {len(self._data)} values, got {len(new_col)}")
+        for data_row, value in zip(self._data, new_col, strict=True):
+            data_row.append(value)
+        self._column_headers.append(header)
+
+    def drop_row(self, label: str) -> None:
+        """Remove the row labeled *label*."""
+        i = self._row_index(label)
+        del self._data[i]
+        del self._row_labels[i]
+
+    def drop_column(self, header: str) -> None:
+        """Remove the column headed *header*."""
+        j = self._column_index(header)
+        del self._column_headers[j]
+        for data_row in self._data:
+            del data_row[j]
+
+    def rename_row(self, old: str, new: str) -> None:
+        """Change a row label."""
+        if not isinstance(new, str):
+            raise TypeError(f"row label must be str, got {type(new).__name__}: {new!r}")
+        self._row_labels[self._row_index(old)] = new
+
+    def rename_column(self, old: str, new: str) -> None:
+        """Change a column header."""
+        if not isinstance(new, str):
+            raise TypeError(f"column header must be str, got {type(new).__name__}: {new!r}")
+        self._column_headers[self._column_index(old)] = new
+
+    # ----------------------------------------------------------------- write
+
+    def _assemble(self) -> list[list[object]]:
+        grid: list[list[object]] = []
+        if self._column_headers:
+            header_row: list[object] = [self._corner] if self._row_labels else []
+            header_row.extend(self._column_headers)
+            grid.append(header_row)
+        for i, data_row in enumerate(self._data):
+            out_row: list[object] = [self._row_labels[i]] if self._row_labels else []
+            out_row.extend(data_row)
+            grid.append(out_row)
+        return grid
+
+    def write(self, path: str | Path, sheet: str | None = None) -> None:
+        """Write the table to *path*, reassembling headers into row 1 and labels into column A."""
+        write_sheet(path, self._assemble(), sheet)
+
+    # --------------------------------------------------------------- dunders
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, Table):
+            return NotImplemented
+        return (
+            self._data == other._data
+            and self._column_headers == other._column_headers
+            and self._row_labels == other._row_labels
+            and self._corner == other._corner
+        )
+
+    def __repr__(self) -> str:
+        return (
+            f"Table(rows={len(self._data)}, columns={len(self._column_headers)}, "
+            f"corner={self._corner!r})"
+        )

pyhandlexl/validate.py

@@ -0,0 +1,75 @@
+"""Validation helpers: sheet names, data dimensions, and file integrity."""
+
+from __future__ import annotations
+
+import zipfile
+from pathlib import Path
+
+from openpyxl import load_workbook
+
+from pyhandlexl.errors import DimensionError, SheetNameError
+
+# Excel's hard limits for the .xlsx format.
+MAX_ROWS = 1_048_576
+MAX_COLUMNS = 16_384
+
+# Characters Excel forbids in a worksheet name.
+ILLEGAL_SHEET_CHARS = frozenset(r"\/?*[]:")
+
+# Files every valid .xlsx zip must contain.
+_REQUIRED_PARTS = frozenset({"xl/workbook.xml", "[Content_Types].xml"})
+
+
+def check_dimensions(n_rows: int, n_cols: int) -> None:
+    """Raise DimensionError if a grid of this size won't fit in an .xlsx sheet."""
+    if n_rows > MAX_ROWS:
+        raise DimensionError(f"{n_rows} rows exceeds the .xlsx limit of {MAX_ROWS}")
+    if n_cols > MAX_COLUMNS:
+        raise DimensionError(f"{n_cols} columns exceeds the .xlsx limit of {MAX_COLUMNS}")
+
+
+def check_sheet_name(sheet_name: str) -> None:
+    """Raise SheetNameError if *sheet_name* is not a valid Excel worksheet name."""
+    if not isinstance(sheet_name, str):
+        raise SheetNameError(f"sheet name must be a string, got {type(sheet_name).__name__}")
+
+    if sheet_name == "":
+        raise SheetNameError("sheet name must not be empty")
+
+    if len(sheet_name) > 31:
+        raise SheetNameError(f"sheet name is longer than 31 characters: {sheet_name!r}")
+
+    illegal = sorted(set(sheet_name) & ILLEGAL_SHEET_CHARS)
+    if illegal:
+        raise SheetNameError(f"sheet name {sheet_name!r} contains illegal character(s): {illegal}")
+
+    if sheet_name.lower() == "history":
+        raise SheetNameError("'History' is reserved by Excel and cannot be used as a sheet name")
+
+
+def is_valid_xlsx(path: str | Path) -> bool:
+    """Return True only if *path* is a readable .xlsx workbook.
+
+    Never raises: every failure mode returns False.
+    """
+    path = Path(path)
+    if not path.is_file():
+        return False
+
+    try:
+        with zipfile.ZipFile(path) as zf:
+            if not _REQUIRED_PARTS.issubset(zf.namelist()):
+                return False
+            if zf.testzip() is not None:
+                return False
+    except (zipfile.BadZipFile, OSError):
+        return False
+
+    # openpyxl raises several unrelated exception types for a malformed
+    # workbook; this function's job is to answer yes/no, not to blow up.
+    try:
+        load_workbook(path, read_only=True).close()
+    except Exception:
+        return False
+
+    return True

pyhandlexl-0.2.0.dist-info/METADATA

@@ -0,0 +1,302 @@
+Metadata-Version: 2.4
+Name: pyhandlexl
+Version: 0.2.0
+Summary: Use an Excel file as the database for your next project.
+Author-email: Lewis Wainaina <lewyamendi@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/LewyAmendi/pyhandlexl
+Project-URL: Repository, https://github.com/LewyAmendi/pyhandlexl
+Project-URL: Issues, https://github.com/LewyAmendi/pyhandlexl/issues
+Project-URL: Changelog, https://github.com/LewyAmendi/pyhandlexl/blob/main/CHANGELOG.md
+Keywords: excel,xlsx,openpyxl,spreadsheet,xl
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial :: Spreadsheet
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: openpyxl>=3.1
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Dynamic: license-file
+
+# pyhandlexl
+
+[![CI](https://github.com/LewyAmendi/pyhandlexl/actions/workflows/ci.yml/badge.svg)](https://github.com/LewyAmendi/pyhandlexl/actions/workflows/ci.yml)
+
+**Make an Excel file the database for your next project.**
+
+A spreadsheet is the most portable data store there is: every machine opens it,
+anyone can read or edit it without knowing a query language, it versions as a
+single file, and there is no server to run. `pyhandlexl` makes driving one from
+Python dependable — read and write raw cell values in a known order, with writes
+that leave the file intact even when things go wrong.
+
+Built on [openpyxl](https://openpyxl.readthedocs.io/) and built to grow.
+
+- **`Table`** — the main way in. Row 1 holds your column headers, column A holds
+  your row labels, and everything from `B2` on is data. Read it, edit it by name,
+  write it back.
+- **`read_sheet` / `write_sheet`** — direct grid access for sheets that aren't a
+  labelled table.
+
+> **Version 0.1.0.** Usable today and under active development — expect new
+> capabilities with each release, and some API changes as it matures.
+
+## Install
+
+Not on PyPI yet. From source:
+
+```bash
+git clone https://github.com/LewyAmendi/pyhandlexl
+cd pyhandlexl
+pip install -e .
+```
+
+Requires Python 3.10+.
+
+## Quickstart
+
+Given `budget.xlsx`:
+
+|        | q1 | q2 |
+|--------|----|----|
+| **Alice** | 10 | 20 |
+| **Bob**   | 30 | 40 |
+
+```python
+from pyhandlexl import Table
+
+t = Table.read("budget.xlsx")
+
+t.read_cell(row="Alice", column="q2")   # '20'
+t.read_row("Bob")                       # ['30', '40']
+t.read_column("q1")                     # ['10', '30']
+
+t.set_cell(row="Alice", column="q1", value=99)   # edit in place
+t.add_row("Carol", [1, 2])
+t.write("budget.xlsx")     # one safe, atomic write
+```
+
+> **Values are always strings.** `read_sheet` and `Table` coerce every cell to
+> `str` (empty cells become `""`). Convert to numbers yourself where you need to.
+
+## The `Table` class
+
+### Reading
+
+```python
+Table.read(path, sheet=None, *, column_headers=True, row_labels=True)
+```
+
+- `sheet=None` reads the active sheet; pass a name for a specific one.
+- `column_headers=False` — row 1 is ordinary data, `column_headers` is empty.
+- `row_labels=False` — column A is ordinary data, `row_labels` is empty.
+
+Row labels and column headers are always `str` — required if you build a
+`Table` by hand, too (`Table(..., column_headers=[1, 2])` raises `TypeError`).
+
+### The whole table at once
+
+```python
+t.corner       # value of cell A1 (settable: t.corner = "name")
+t.data         # a TableData snapshot
+```
+
+```python
+d = t.data
+d.rows              # [['10', '20'], ['30', '40']]   (B2 onward, by row)
+d.columns           # [['10', '30'], ['20', '40']]   (same data, by column)
+d.row_labels        # ['Alice', 'Bob']   (column A, from A2)
+d.column_headers    # ['q1', 'q2']       (row 1, from B1)
+d.corner            # value of cell A1
+```
+
+Every field is a fresh copy — mutating `t.data.rows` does not change the table.
+
+### Access by label
+
+```python
+t.read_row("Bob")            # a data row (no label)
+t.read_column("q1")          # a data column (no header)
+```
+
+Unknown labels raise `KeyError`. If a label appears twice, the first match wins.
+
+### `read_cell` / `set_cell` — a single value, by position or by label
+
+Both take the same addressing: a ref like `"B2"`, or `row=`/`column=` as a
+matching pair — **both ints** for a 1-based Excel position (row 1 is the
+header row, column 1 is the label column), or **both strings** for a row
+label / column header pair. Mixing types raises `TypeError`.
+
+```python
+t.read_cell("B2")                       # '10' — first data cell, by position
+t.read_cell(row=2, column=2)            # '10' — same thing, spelled out
+t.read_cell(row="Alice", column="q1")   # '10' — same value, by label
+
+t.read_cell(row=1, column=2)   # 'q1'    — a column header
+t.read_cell(row=2, column=1)   # 'Alice' — a row label
+t.read_cell("A1")               # the corner
+```
+
+By position, `read_cell` can reach *any* cell — header, label, corner, or
+data. By label it always reads data, wherever that row/column intersection
+actually lives.
+
+A string given through `row=`/`column=` is always a label lookup — it does
+**not** accept a column letter like `"B"` for a position. Use a plain number
+(`column=2`) or `ref="B2"` for letter-based positions.
+
+### Editing (in place, returns `None`)
+
+```python
+t.set_cell("B2", value=99)                       # by position — ref
+t.set_cell(row=2, column=2, value=99)            # by position — row=/column= as ints
+t.set_cell(row="Alice", column="q1", value=99)   # by label    — row=/column= as strings
+t.set_row("Bob", [50, 60])          # replace a row   (length must match)
+t.set_column("q1", [1, 2])          # replace a column (length must match)
+
+t.add_row("Carol", [1, 2])          # append a labelled row
+t.add_column("q3", [5, 6])          # append a labelled column
+
+t.drop_row("Bob")
+t.drop_column("q2")
+
+t.rename_row("Alice", "ALICE")
+t.rename_column("q1", "Q1")
+t.corner = "name"
+```
+
+`set_cell` only ever touches **data** — addressing a header, row label, or the
+corner by position raises `ValueError`; use `rename_row`, `rename_column`, or
+`t.corner = value` for those. Wrong-length values raise `ValueError`; unknown
+labels raise `KeyError`; a non-`str` row label or column header (in `add_row`,
+`add_column`, `rename_row`, `rename_column`) raises `TypeError`.
+
+You can also build a table from nothing:
+
+```python
+t = Table([], column_headers=["q1", "q2"])
+t.add_row("Alice", [10, 20])
+t.write("new.xlsx")
+```
+
+### Writing
+
+```python
+t.write(path, sheet=None)
+```
+
+Reassembles headers into row 1 and labels into column A, then writes the whole
+sheet. Other sheets in the file are left untouched.
+
+### Equality
+
+```python
+t1 == t2            # compares data, headers, labels, corner
+```
+
+Row count and row-label membership go through `t.data` instead of `len()`/`in`,
+so the call site says what's being checked: `len(t.data.rows)`,
+`"Bob" in t.data.row_labels`.
+
+## The raw layer
+
+For sheets that are not a labelled table — plain grids, exports, odd layouts.
+
+```python
+from pyhandlexl import read_sheet, write_sheet, append_rows
+
+read_sheet(path, sheet=None, *, pad=False)
+```
+
+Returns `list[list[str]]`. Trailing empty cells are trimmed from each row (a
+fully empty row becomes `[]`); `pad=True` right-pads every row to the widest
+row's length instead.
+
+```python
+write_sheet(path, rows, sheet=None, *, orientation="rows")
+```
+
+Replaces the target sheet with `rows` (other sheets untouched), creating the
+file and sheet if needed. Values are written as-is — `str` stays `str`, `int`
+stays `int`, `None` leaves the cell empty; there is no string-to-number
+conversion. `orientation="columns"` writes each inner list *down a column*
+instead of across a row.
+
+```python
+append_rows(path, rows, sheet=None)
+```
+
+Appends after the last row. Empty input is a no-op.
+
+## Sheet management
+
+```python
+from pyhandlexl import (
+    list_sheets, sheet_exists, create_sheet, delete_sheet, rename_sheet,
+)
+
+list_sheets(path)                 # ['Sheet1', 'Data']
+sheet_exists(path, "Data")        # True
+create_sheet(path, "Results")     # ValueError if it already exists
+delete_sheet(path, "Old")         # refuses to delete the last sheet
+rename_sheet(path, "Old", "New")
+```
+
+Sheet names are validated everywhere: max 31 characters, none of `\ / ? * [ ] :`,
+and `"History"` is reserved by Excel.
+
+## Safe writes
+
+Every write goes through the same steps:
+
+1. Save to a temporary file in the same directory.
+2. Verify it is a readable `.xlsx`.
+3. Atomically replace the original (`os.replace`).
+
+If any step fails the temporary file is removed and the original is left exactly
+as it was. If the target is locked (open in Excel), writes retry briefly before
+raising `FileLockedError`.
+
+## Errors
+
+All raised exceptions derive from `PyhandlexlError`:
+
+| Exception | Also a | Meaning |
+|---|---|---|
+| `SheetNameError` | `ValueError` | invalid worksheet name |
+| `DimensionError` | `ValueError` | data exceeds Excel's 1,048,576 × 16,384 grid |
+| `SheetNotFoundError` | `KeyError` | no worksheet with that name |
+| `FileLockedError` | `OSError` | file stayed locked through every retry |
+| `InvalidFileError` | — | file is missing or not a readable `.xlsx` |
+
+## Not in scope
+
+`pyhandlexl` deliberately does **not** handle: cell formatting, styles, fonts,
+formulas, charts, images, merged cells, `.xls` (old format), or password
+protection / encryption. For any of that, use openpyxl directly.
+
+## Development
+
+```bash
+python -m venv .venv
+source .venv/bin/activate        # Windows: .venv\Scripts\Activate.ps1
+pip install -e ".[dev]"
+pytest
+ruff check . && ruff format --check .
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

pyhandlexl-0.2.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+pyhandlexl/__init__.py,sha256=GJdaBC0sGOE-t0ib6aqNnUh1K4RvcZf04QRqimogL2Y,968
+pyhandlexl/_safety.py,sha256=hsT5ZWTQG5nqSnhbnn4MwHb4X7dNbbsVXaEbmOX7TG4,3569
+pyhandlexl/core.py,sha256=9-mmAQbTHl-o92ro8jc_FJ3HK_bInL9uaHuxyzEMhAQ,8089
+pyhandlexl/errors.py,sha256=92b69FELB8gXMSdzKaECusSwgnrSt2FQmeoTeesj29M,828
+pyhandlexl/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pyhandlexl/table.py,sha256=_Gp3MCSUhZ0OwW9aNG7_xfI_IzbTwsendZBM6Zrvj9k,15385
+pyhandlexl/validate.py,sha256=JGALihqR72V69uB6dmmivY7PG-xTFq-j8YRpY6xsWrQ,2492
+pyhandlexl-0.2.0.dist-info/licenses/LICENSE,sha256=wW_wwDfDJzKBJB_4uifSG5f4AyyF7m-WMurztbxDx2Q,1070
+pyhandlexl-0.2.0.dist-info/METADATA,sha256=N_3nkRJuqwkSnnurSgFg6_MQB8zTvrxLqBkPkAJ85_c,10137
+pyhandlexl-0.2.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+pyhandlexl-0.2.0.dist-info/top_level.txt,sha256=VudupJVAGQn04F8AY6kUH4FsDOiX_AhkNpp80Tb80z4,11
+pyhandlexl-0.2.0.dist-info/RECORD,,

pyhandlexl-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pyhandlexl-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lewis Wainaina
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pyhandlexl-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+pyhandlexl