tabular-reader 0.1.0__tar.gz

tabular_reader-0.1.0/LICENSE

@@ -0,0 +1,9 @@
+ The MIT License (MIT)
+
+Copyright © 2025 arkhan
+
+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.

tabular_reader-0.1.0/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: tabular-reader
+Version: 0.1.0
+Summary: Read XLSX, XLS and CSV files with a uniform interface Read XLSX, XLS and CSV files with a uniform interface
+License: MIT
+License-File: LICENSE
+Keywords: spreadsheet,csv,xlsx,xls,reader
+Author: arkhan
+Author-email: arkhan@riseup.net
+Requires-Python: >=3.6,<4.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.6
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+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: Programming Language :: Python :: 3.14
+Requires-Dist: openpyxl (>=3.0,<3.1)
+Project-URL: Repository, https://github.com/arkhan/tabular-reader
+Description-Content-Type: text/plain
+
+* 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
+

tabular_reader-0.1.0/README.org

@@ -0,0 +1,118 @@
+* 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

tabular_reader-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[tool.poetry]
+name = "tabular-reader"
+version = "0.1.0"
+description = "Read XLSX, XLS and CSV files with a uniform interface Read XLSX, XLS and CSV files with a uniform interface"
+authors = ["arkhan <arkhan@riseup.net>"]
+license = "MIT"
+readme = "README.org"
+repository = "https://github.com/arkhan/tabular-reader"
+keywords = ["spreadsheet", "csv", "xlsx", "xls", "reader"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.6",
+    "Programming Language :: Python :: 3.7",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+]
+
+[tool.poetry.dependencies]
+python = "^3.6"
+openpyxl = ">=3.0,<3.1"
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^6.2"
+black = "^21.0"
+flake8 = "^3.9"
+
+[build-system]
+requires = ["poetry-core>=1.0.0"]
+build-backend = "poetry.core.masonry.api"

tabular_reader-0.1.0/tabular_reader/__init__.py

@@ -0,0 +1,6 @@
+#!/usr/bin/env python
+
+from .reader import TabularReader
+
+__version__ = "0.1.0"
+__all__ = ["TabularReader"]

tabular_reader-0.1.0/tabular_reader/reader.py

@@ -0,0 +1,103 @@
+#!/usr/bin/env python
+import csv
+import os
+from types import SimpleNamespace
+
+from openpyxl import load_workbook
+
+
+def get_file_format(filename):
+    _, ext = os.path.splitext(filename)
+    return ext.lower().lstrip(".")
+
+
+def read_csv(filename, **kwargs):
+    csv_kwargs = {
+        k: v for k, v in kwargs.items() if k in ["delimiter", "quotechar", "encoding"]
+    }
+    with open(filename, "r", encoding=csv_kwargs.pop("encoding", "utf-8-sig")) as f:
+        reader = csv.reader(f, **csv_kwargs)
+        total = list(reader)
+
+    header = total[0] if total else []
+    filtered_indices = [
+        i for i, val in enumerate(header) if val is not None and str(val).strip() != ""
+    ]
+    return [
+        [row[i] if i < len(row) else None for i in filtered_indices] for row in total
+    ]
+
+
+def read_xlsx(filename, worksheet="", **kwargs):
+    excel_kwargs = {
+        k: v for k, v in kwargs.items() if k not in ["delimiter", "encoding"]
+    }
+    wb = load_workbook(filename, **excel_kwargs)
+    ws = worksheet and wb[worksheet] or wb.active
+
+    total = [[col.value for col in row] for row in ws]
+    header = total[0] if total else []
+    filtered_indices = [
+        i for i, val in enumerate(header) if val is not None and str(val).strip() != ""
+    ]
+    return [
+        [row[i] if i < len(row) else None for i in filtered_indices] for row in total
+    ]
+
+
+class TabularReader:
+    def __init__(
+        self,
+        filename,
+        worksheet="",
+        fieldnames=None,
+        restval=None,
+        restkey=None,
+        skip_blank_lines=False,
+        *args,
+        **kwargs,
+    ):
+        file_format = get_file_format(filename)
+
+        if file_format == "csv":
+            filtered_data = read_csv(filename, **kwargs)
+        elif file_format in ("xlsx", "xls"):
+            filtered_data = read_xlsx(filename, worksheet, **kwargs)
+        else:
+            raise ValueError(f"Unsupported format: {file_format}")
+
+        self.reader = iter(filtered_data)
+        self._fieldnames = fieldnames
+        self.restkey = restkey
+        self.restval = restval
+        self.skip_blank_lines = skip_blank_lines
+        self.line_num = 0
+
+    @property
+    def fieldnames(self):
+        if self._fieldnames is None:
+            try:
+                self._fieldnames = next(self.reader)
+            except StopIteration:
+                pass
+        self.line_num += 1
+        return self._fieldnames
+
+    @fieldnames.setter
+    def fieldnames(self, value):
+        self._fieldnames = value
+
+    def __iter__(self):
+        return self
+
+    def __next__(self):
+        if self.line_num == 0:
+            self.fieldnames
+        row = next(self.reader)
+        self.line_num += 1
+        while self.skip_blank_lines and all(cell is None for cell in row):
+            row = next(self.reader)
+        record = SimpleNamespace(**dict(zip(self.fieldnames, row)))
+        return record
+
+    next = __next__