tabular-reader 0.1.4

#+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 [[https://docs.python.org/3/library/csv.html#csv.DictReader][csv.DictReader]] but with support for multiple file types.

** Installing
#+begin_src bash
pip install tabular-reader
#+end_src

** Examples

*** Basic usage with XLSX
#+begin_src python
from tabular_reader import TabularReader

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

Output:
#+begin_src
Boris Johnson
Donald Trump
Mark Rutte
#+end_src

*** Reading CSV files
#+begin_src python
from tabular_reader import TabularReader

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

*** Reading XLS files
#+begin_src python
from tabular_reader import TabularReader

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

** Custom fieldnames
You can specify fieldnames manually:

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

** Skip blank lines
Filter out empty rows:

#+begin_src python
reader = TabularReader(
    "data.csv",
    skip_blank_lines=True
)
for row in reader:
    print(row)
#+end_src

** Keyword arguments

*** For Excel files (XLSX/XLS)
Pass any ~openpyxl.load_workbook~ keyword arguments:

#+begin_src python
reader = TabularReader(
    "names.xlsx",
    worksheet="Sheet1",
    read_only=False,
    keep_vba=False,
    data_only=False,
    keep_links=True
)
#+end_src

*** For CSV files
Pass any ~csv.reader~ keyword arguments:

#+begin_src python
reader = TabularReader(
    "data.csv",
    delimiter=";",
    quotechar='"',
    encoding="utf-8"
)
#+end_src

** 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
- [[https://openpyxl.readthedocs.io/][openpyxl]]
- [[https://docs.python.org/3/library/csv.html][csv]] - Python's standard library