#+TITLE: tabular-reader

tabular_reader

Description

A module that maps information from each row in XLSX, XLS, or CSV files to a SimpleNamespace object, providing a uniform interface across different spreadsheet and data formats. Similar to Python’s native csv.DictReader but with support for multiple file types.

Installing

pip install tabular-reader

Examples

Basic usage with XLSX

from tabular_reader import TabularReader

reader = TabularReader("names.xlsx", worksheet="Sheet1")
for row in reader:
    print(row.first_name, row.last_name)

Output:

Boris Johnson
Donald Trump
Mark Rutte

Reading CSV files

from tabular_reader import TabularReader

reader = TabularReader("data.csv")
for row in reader:
    print(row.email, row.phone)

Reading XLS files

from tabular_reader import TabularReader

reader = TabularReader("legacy_data.xls")
for row in reader:
    print(row.id, row.name)

Custom fieldnames

You can specify fieldnames manually:

reader = TabularReader(
    "data.xlsx",
    fieldnames=["id", "email", "username"]
)
for row in reader:
    print(row.id, row.email)

Skip blank lines

Filter out empty rows:

reader = TabularReader(
    "data.csv",
    skip_blank_lines=True
)
for row in reader:
    print(row)

Keyword arguments

For Excel files (XLSX/XLS)

Pass any openpyxl.load_workbook keyword arguments:

reader = TabularReader(
    "names.xlsx",
    worksheet="Sheet1",
    read_only=False,
    keep_vba=False,
    data_only=False,
    keep_links=True
)

For CSV files

Pass any csv.reader keyword arguments:

reader = TabularReader(
    "data.csv",
    delimiter=";",
    quotechar='"',
    encoding="utf-8"
)

Features

• Automatic format detection by file extension
• Empty column filtering (only processes columns with headers)
• Uniform interface across XLSX, XLS, and CSV
• SimpleNamespace objects with attribute access (row.field_name)
• Python 3.6 - 3.14 support

Supported formats

Format	Extension	Status
Excel	.xlsx	✓ Supported
Excel	.xls	✓ Supported
CSV	.csv	✓ Supported

Acknowledgements

• openpyxl
• csv - Python’s standard library