excelreader-native 2.1.1__py3-none-win_amd64.whl

excelreader/__init__.py

@@ -0,0 +1,13 @@
+"""Python bindings for ExcelReader. Reading only — writing is not exposed yet."""
+
+from excelreader.reader import Workbook, open_bytes, open_workbook
+from excelreader.types import Cell, CellType, ExcelReaderError
+
+__all__ = [
+    "Cell",
+    "CellType",
+    "ExcelReaderError",
+    "Workbook",
+    "open_bytes",
+    "open_workbook",
+]

excelreader/_native.py

@@ -0,0 +1,116 @@
+"""ctypes binding to the ExcelReader NativeAOT shared library.
+
+Everything here mirrors src/ExcelReader.Native/include/excelreader.h. If you change one, change both.
+"""
+
+from __future__ import annotations
+
+import ctypes
+import os
+import platform
+from functools import lru_cache
+from pathlib import Path
+
+XL_OK = 0
+XL_EOF = -1
+XL_BUFFER_TOO_SMALL = -2
+XL_INVALID_HANDLE = -3
+XL_INVALID_ARGUMENT = -4
+XL_ERROR = -5
+
+XL_FORMAT_AUTO = 0
+XL_FORMAT_XLS = 1
+XL_FORMAT_XLSX = 2
+XL_FORMAT_XLSB = 3
+XL_FORMAT_CSV = 4
+
+class NativeRowCell(ctypes.Structure):
+    _fields_ = [
+        ("column", ctypes.c_int32),
+        ("type", ctypes.c_int32),
+        ("value_len", ctypes.c_int32),
+        ("value", ctypes.POINTER(ctypes.c_uint8)),
+    ]
+
+
+class NativeRow(ctypes.Structure):
+    _fields_ = [
+        ("cell_count", ctypes.c_int32),
+        ("cells", ctypes.POINTER(NativeRowCell)),
+    ]
+
+
+class NativeRows(ctypes.Structure):
+    _fields_ = [
+        ("row_count", ctypes.c_int32),
+        ("rows", ctypes.POINTER(NativeRow)),
+    ]
+
+
+_LIB_NAMES = {
+    "Windows": "ExcelReader.Native.dll",
+    "Linux": "ExcelReader.Native.so",
+    "Darwin": "ExcelReader.Native.dylib",
+}
+
+# NativeAOT emits no "lib" prefix, so the filename is the assembly name on every platform.
+def library_filename() -> str:
+    try:
+        return _LIB_NAMES[platform.system()]
+    except KeyError:
+        raise RuntimeError(f"unsupported platform: {platform.system()}") from None
+
+
+def _candidate_paths() -> list[Path]:
+    override = os.environ.get("EXCELREADER_NATIVE_LIB")
+    if override:
+        return [Path(override)]
+    return [Path(__file__).resolve().parent / "_lib" / library_filename()]
+
+
+@lru_cache(maxsize=1)
+def load_library() -> ctypes.CDLL:
+    for path in _candidate_paths():
+        if path.exists():
+            return _bind(ctypes.CDLL(str(path)))
+    raise RuntimeError(
+        f"{library_filename()} not found. Build it with:\n"
+        f"    python python/scripts/build_native.py\n"
+        f"or point EXCELREADER_NATIVE_LIB at an existing binary."
+    )
+
+
+def _bind(lib: ctypes.CDLL) -> ctypes.CDLL:
+    c_int = ctypes.c_int32
+    p_int = ctypes.POINTER(ctypes.c_int32)
+    p_void = ctypes.c_void_p
+    pp_void = ctypes.POINTER(ctypes.c_void_p)
+    p_bytes = ctypes.c_char_p
+
+    lib.xl_open_file.argtypes = [p_bytes, c_int, c_int, pp_void]
+    lib.xl_open_file.restype = c_int
+    lib.xl_open_memory.argtypes = [p_bytes, c_int, c_int, pp_void]
+    lib.xl_open_memory.restype = c_int
+    lib.xl_close.argtypes = [p_void]
+    lib.xl_close.restype = c_int
+    lib.xl_sheet_count.argtypes = [p_void, p_int]
+    lib.xl_sheet_count.restype = c_int
+    # xl_sheet_name / xl_next_row / xl_last_error write INTO their buffer argument.
+    # Callers MUST pass ctypes.create_string_buffer(n), never a bytes literal — bytes
+    # objects are immutable/interned in CPython, and letting native code write into
+    # one is undefined behavior.
+    lib.xl_sheet_name.argtypes = [p_void, p_bytes, c_int, p_int]
+    lib.xl_sheet_name.restype = c_int
+    lib.xl_move_to_sheet.argtypes = [p_void, c_int]
+    lib.xl_move_to_sheet.restype = c_int
+    lib.xl_is_date1904.argtypes = [p_void, p_int]
+    lib.xl_is_date1904.restype = c_int
+    lib.xl_next_row.argtypes = [p_void, p_bytes, c_int, p_int]
+    lib.xl_next_row.restype = c_int
+    lib.xl_last_error.argtypes = [p_bytes, c_int, p_int]
+    lib.xl_last_error.restype = c_int
+    lib.xl_read_all_decoded.argtypes = [p_void, ctypes.POINTER(NativeRows)]
+    lib.xl_read_all_decoded.restype = c_int
+    lib.xl_free_rows.argtypes = [ctypes.POINTER(NativeRows)]
+    lib.xl_free_rows.restype = None
+    return lib

excelreader/reader.py

@@ -0,0 +1,190 @@
+"""The public reading API. One Workbook wraps one native handle."""
+
+from __future__ import annotations
+
+import ctypes
+import struct
+from collections.abc import Iterator
+from pathlib import Path
+
+from typing_extensions import Self
+
+from excelreader import _native
+from excelreader.types import Cell, CellType, ExcelReaderError
+
+_FORMATS = {
+    "auto": _native.XL_FORMAT_AUTO,
+    "xls": _native.XL_FORMAT_XLS,
+    "xlsx": _native.XL_FORMAT_XLSX,
+    "xlsb": _native.XL_FORMAT_XLSB,
+    "csv": _native.XL_FORMAT_CSV,
+}
+
+_CELL_HEADER = struct.Struct("<iii")
+_INITIAL_ROW_BUFFER = 64 * 1024
+
+
+def _last_error() -> str:
+    lib = _native.load_library()
+    length = ctypes.c_int32()
+    buffer = ctypes.create_string_buffer(1024)
+    if lib.xl_last_error(buffer, len(buffer), ctypes.byref(length)) == _native.XL_BUFFER_TOO_SMALL:
+        buffer = ctypes.create_string_buffer(length.value)
+        lib.xl_last_error(buffer, len(buffer), ctypes.byref(length))
+    return buffer.raw[: length.value].decode("utf-8", errors="replace")
+
+
+def _check(status: int) -> None:
+    if status == _native.XL_OK:
+        return
+    if status == _native.XL_INVALID_HANDLE:
+        raise ExcelReaderError("workbook is closed or the handle is invalid")
+    if status == _native.XL_INVALID_ARGUMENT:
+        raise ExcelReaderError("invalid argument passed to the native library")
+    raise ExcelReaderError(_last_error() or f"native call failed with status {status}")
+
+
+def _resolve_format(name: str | None, path: Path | None) -> int:
+    if name is not None:
+        try:
+            return _FORMATS[name.lower()]
+        except KeyError:
+            raise ValueError(f"unknown format {name!r}; expected one of {sorted(_FORMATS)}") from None
+    # The signature sniffer covers XLS/XLSX/XLSB but CSV has no signature, so the extension is the
+    # only hint available for it.
+    if path is not None and path.suffix.lower() == ".csv":
+        return _native.XL_FORMAT_CSV
+    return _native.XL_FORMAT_AUTO
+
+
+class Workbook:
+    """A read cursor over one workbook. Not thread-safe; use one instance per thread."""
+
+    def __init__(self, handle: ctypes.c_void_p) -> None:
+        self._lib = _native.load_library()
+        self._handle: ctypes.c_void_p | None = handle
+
+    def _require_handle(self) -> ctypes.c_void_p:
+        if self._handle is None:
+            raise ExcelReaderError("workbook is closed")
+        return self._handle
+
+    @property
+    def sheet_count(self) -> int:
+        count = ctypes.c_int32()
+        _check(self._lib.xl_sheet_count(self._require_handle(), ctypes.byref(count)))
+        return count.value
+
+    @property
+    def sheet_name(self) -> str:
+        handle = self._require_handle()
+        length = ctypes.c_int32()
+        buffer = ctypes.create_string_buffer(256)
+        status = self._lib.xl_sheet_name(handle, buffer, len(buffer), ctypes.byref(length))
+        if status == _native.XL_BUFFER_TOO_SMALL:
+            buffer = ctypes.create_string_buffer(length.value)
+            status = self._lib.xl_sheet_name(handle, buffer, len(buffer), ctypes.byref(length))
+        _check(status)
+        return buffer.raw[: length.value].decode("utf-8")
+
+    @property
+    def is_date1904(self) -> bool:
+        flag = ctypes.c_int32()
+        _check(self._lib.xl_is_date1904(self._require_handle(), ctypes.byref(flag)))
+        return flag.value != 0
+
+    def move_to_sheet(self, index: int) -> None:
+        """Selects a sheet and restarts row enumeration from its first row."""
+        _check(self._lib.xl_move_to_sheet(self._require_handle(), index))
+
+    def rows(self) -> Iterator[list[Cell]]:
+        written = ctypes.c_int32()
+        capacity = _INITIAL_ROW_BUFFER
+        buffer = ctypes.create_string_buffer(capacity)
+        while True:
+            handle = self._require_handle()
+            status = self._lib.xl_next_row(handle, buffer, capacity, ctypes.byref(written))
+            if status == _native.XL_EOF:
+                return
+            if status == _native.XL_BUFFER_TOO_SMALL:
+                # The native side holds the row until it fits, so growing loses nothing.
+                capacity = written.value
+                buffer = ctypes.create_string_buffer(capacity)
+                continue
+            _check(status)
+            yield _decode_row(buffer.raw, written.value)
+
+    def read_all(self) -> list[list[Cell]]:
+        """Materializes every remaining row of the current sheet in one native call."""
+        handle = self._require_handle()
+        rows = _native.NativeRows()
+        _check(self._lib.xl_read_all_decoded(handle, ctypes.byref(rows)))
+        try:
+            return [_decode_native_row(rows.rows[index]) for index in range(rows.row_count)]
+        finally:
+            self._lib.xl_free_rows(ctypes.byref(rows))
+
+    def close(self) -> None:
+        if self._handle is None:
+            return
+        handle, self._handle = self._handle, None
+        _check(self._lib.xl_close(handle))
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(self, *_exc_info: object) -> None:
+        self.close()
+
+    def __del__(self) -> None:
+        # Backstop only, not a substitute for explicit close()/`with`: if a Workbook is dropped
+        # without one, this still releases the native handle and the file lock it holds. During
+        # interpreter shutdown or GC, module globals (_native, ctypes) may already be partially torn
+        # down, so a finalizer must never let an exception escape — swallow anything broadly here,
+        # which is the standard, accepted exception to "never bare-except" for __del__ specifically.
+        try:
+            self.close()
+        except Exception:  # noqa: BLE001, S110
+            pass
+
+
+def _decode_row(blob: bytes, length: int) -> list[Cell]:
+    count = struct.unpack_from("<i", blob, 0)[0]
+    cells: list[Cell] = []
+    offset = 4
+    for _ in range(count):
+        column, cell_type, value_length = _CELL_HEADER.unpack_from(blob, offset)
+        offset += _CELL_HEADER.size
+        value = blob[offset : offset + value_length].decode("utf-8")
+        offset += value_length
+        cells.append(Cell(column=column, type=CellType(cell_type), value=value))
+    if offset != length:
+        raise ExcelReaderError(f"row blob is malformed: consumed {offset} of {length} bytes")
+    return cells
+
+
+def _decode_native_row(row: _native.NativeRow) -> list[Cell]:
+    cells: list[Cell] = []
+    for index in range(row.cell_count):
+        cell = row.cells[index]
+        value = ctypes.string_at(cell.value, cell.value_len).decode("utf-8")
+        cells.append(Cell(column=cell.column, type=CellType(cell.type), value=value))
+    return cells
+
+
+def open_workbook(path: str | Path, format: str | None = None) -> Workbook:
+    """Opens a workbook from disk. `format` is one of auto/xls/xlsx/xlsb/csv; None infers it."""
+    resolved = Path(path)
+    encoded = str(resolved).encode("utf-8")
+    handle = ctypes.c_void_p()
+    lib = _native.load_library()
+    _check(lib.xl_open_file(encoded, len(encoded), _resolve_format(format, resolved), ctypes.byref(handle)))
+    return Workbook(handle)
+
+
+def open_bytes(data: bytes, format: str | None = None) -> Workbook:
+    """Opens a workbook from an in-memory buffer. The native side copies `data` immediately."""
+    handle = ctypes.c_void_p()
+    lib = _native.load_library()
+    _check(lib.xl_open_memory(data, len(data), _resolve_format(format, None), ctypes.byref(handle)))
+    return Workbook(handle)

excelreader/types.py

@@ -0,0 +1,39 @@
+"""Value types crossing the FFI boundary. Mirrors ExcelReader.Core.Enums.CellType."""
+
+from __future__ import annotations
+
+import datetime
+from enum import IntEnum
+from typing import NamedTuple
+
+
+class CellType(IntEnum):
+    EMPTY = 0
+    STRING = 1
+    NUMBER = 2
+    DATE = 3
+    BOOL = 4
+    FORMULA = 5
+    ERROR = 6
+
+
+class Cell(NamedTuple):
+    """One cell. `value` is the raw text as stored, so DATE cells are Excel serial numbers."""
+
+    column: int
+    type: CellType
+    value: str
+
+    def as_date(self, date1904: bool = False) -> datetime.date | None:
+        """Converts a DATE cell's serial value to a date. Returns None for any other cell type.
+
+        `date1904` should come from `Workbook.is_date1904` for the workbook this cell came from.
+        """
+        if self.type is not CellType.DATE:
+            return None
+        epoch = datetime.date(1904, 1, 1) if date1904 else datetime.date(1899, 12, 30)
+        return epoch + datetime.timedelta(days=int(float(self.value)))
+
+
+class ExcelReaderError(Exception):
+    """Raised when the native library reports a failure."""

excelreader_native-2.1.1.dist-info/METADATA

@@ -0,0 +1,87 @@
+Metadata-Version: 2.5
+Name: excelreader-native
+Version: 2.1.1
+Summary: Read XLSX, XLSB, XLS and CSV through the ExcelReader NativeAOT library
+Project-URL: Homepage, https://github.com/GabrielMarquezMatte/ExcelReader
+Author: Gabriel Matte
+License: MIT
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.9
+Requires-Dist: typing-extensions>=4.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# excelreader (Python)
+
+Read XLSX, XLSB, XLS and CSV through ExcelReader's NativeAOT library. No .NET runtime required —
+the shared library is self-contained. Reading only; writing is not exposed yet.
+
+## Install (from source)
+
+```bash
+python python/scripts/build_native.py   # requires the .NET 10 SDK, once per machine
+pip install -e "python[dev]"
+```
+
+`build_native.py` publishes `src/ExcelReader.Native` for your platform and copies the resulting
+`ExcelReader.Native.{dll,so,dylib}` into `excelreader/_lib/`. To point at a binary you built
+elsewhere, set `EXCELREADER_NATIVE_LIB` to its full path.
+
+## Usage
+
+```python
+from excelreader import open_workbook
+
+with open_workbook("book.xlsx") as workbook:
+    print(workbook.sheet_count, workbook.sheet_name)
+    for row in workbook.rows():
+        for cell in row:
+            print(cell.column, cell.type.name, cell.value)
+```
+
+### Formats
+
+`open_workbook` sniffs XLS/XLSX/XLSB by file signature. CSV has no signature, so it is chosen by the
+`.csv` extension — or explicitly:
+
+```python
+open_workbook("data.txt", format="csv")
+```
+
+### Dates
+
+`cell.value` is always the raw text as stored, so `CellType.DATE` cells hold Excel serial numbers.
+Use `Cell.as_date()` to convert, passing the workbook's epoch flag:
+
+```python
+as_date = cell.as_date(workbook.is_date1904)
+```
+
+`as_date()` returns `None` for any cell that isn't `CellType.DATE`.
+
+### Reading everything at once
+
+`rows()` iterates row-by-row; `read_all()` materializes the whole sheet in one call:
+
+```python
+all_rows = workbook.read_all()
+```
+
+This holds every row in memory at once, so prefer `rows()` for very large sheets.
+
+### From memory
+
+```python
+from excelreader import open_bytes
+
+with open_bytes(payload) as workbook:
+    ...
+```
+
+## Notes
+
+- A `Workbook` is **not** thread-safe. Use one per thread.
+- Empty cells are skipped, so `cell.column` may skip indices. Do not assume `row[i].column == i`.
+- The ABI is documented in `src/ExcelReader.Native/include/excelreader.h`.

excelreader_native-2.1.1.dist-info/RECORD

@@ -0,0 +1,10 @@
+excelreader/__init__.py,sha256=Env8EiLc1AZbZrzm9b-LXcvsFX8pZaThOYVGSjnDwEk,337
+excelreader/_native.py,sha256=m1Cc9EhLNd-m-DXHsRcPXMHoXoNaiJGxWs0lstVTAiE,3637
+excelreader/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+excelreader/reader.py,sha256=B6vJZAN4lubsIvouIpSgavSWsXxZAaT7F6w0LkMvuI8,7467
+excelreader/types.py,sha256=Xa8CoIq2U7N-0DM2GwWRIxKm1-N0rNR9aNQg11zxvbI,1093
+excelreader/_lib/.gitkeep,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+excelreader/_lib/ExcelReader.Native.dll,sha256=H28ji4Mk_aR8zq30DVxjeXVb8i1IAsaHoZG60uiBh1c,2506752
+excelreader_native-2.1.1.dist-info/METADATA,sha256=QTgO1doyB7rvj2_NHBm4m-jJfek1BKi2lXiDvm0dBBw,2515
+excelreader_native-2.1.1.dist-info/WHEEL,sha256=OA-gEgWbLnh0Tf6JrLOMFR4vOWY4QbBMSZuN6osy-Q0,94
+excelreader_native-2.1.1.dist-info/RECORD,,

excelreader_native-2.1.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: false
+Tag: py3-none-win_amd64