python-spreadsheet-reader

A Python library for reading, editing, and saving Excel (.xlsx) workbooks. It wraps openpyxl with a higher-level API for row-by-row reading, cell access, lock detection, and workbook persistence.

Requirements

• Python 3.14+
• Poetry (recommended) or pip

Installation

With Poetry

git clone <repository-url>
cd python-spreadsheet-reader
poetry install

With pip

pip install .

Quick start

from python_spreadsheet_reader.readers.xlsx import XLSXReader

reader = XLSXReader("path/to/workbook.xlsx")

# Read all rows from the active sheet (values only, keyed by cell coordinates)
sheet_data = reader.read_sheet(cell_values_only=True)

# Read a specific sheet
sheet_data = reader.read_sheet("Sheet2", cell_values_only=True)

# Access and modify cells
reader.load_workbook()
reader.set_cell_value(value="Hello", coords="A1")
reader.set_cell_value(value=42, row=2, col=1)

# Save changes
reader.save_spreadsheet()                          # overwrite original
reader.save_spreadsheet("output/copy.xlsx")      # save to a new path

reader.close_workbook()

Note: Close the workbook in Excel or LibreOffice before opening it with this library. If the file is in use, SpreadsheetIsLockedException is raised unless you pass read_locked=True to load_workbook() or read_sheet().

API overview

XLSXReader

Entry point for working with a .xlsx file. Holds the workbook in memory and optionally caches the result of read_sheet().

Constructor

XLSXReader(workbook_path: str | Path)

Public methods

read_sheet() options

Example read_sheet() output

{
    1: {"A1": "ID", "B1": "Title", "C1": "Genre"},
    2: {"A2": 123, "B2": "Alien", "C2": "Science Fiction, Horror"},
    3: {"A3": 124, "B3": "Predator", "C3": "Science Fiction, Action"},
}

Exceptions

All custom exceptions inherit from SpreadsheetReaderException.

Other errors you may encounter:

• FileNotFoundError — workbook path does not exist.
• ValueError — unsupported file extension or missing cell coordinates.

Project structure

python-spreadsheet-reader/
├── python_spreadsheet_reader/
│   └── readers/
│       ├── xlsx.py          # XLSXReader
│       └── exceptions.py    # Custom exceptions
├── pyproject.toml
├── poetry.lock
└── README.md

Dependencies

• openpyxl — read and write .xlsx files
• Pillow — image support for openpyxl
• ipykernel — Jupyter kernel support

License

See the repository maintainers for licensing information.