docx2csv 0.1.1__tar.gz → 0.1.4__tar.gz

docx2csv-0.1.4/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.4
+Name: docx2csv
+Version: 0.1.4
+Summary: Extracts tables from .docx files and saves them as csv or xlsx
+Author-email: Ivan Begtin <ivan@begtin.tech>
+License: BSD-3-Clause
+Project-URL: Homepage, https://github.com/ivbeg/docx2csv
+Keywords: docx,converter,tables
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Natural Language :: English
+Classifier: Programming Language :: Python :: 3
+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
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.1.6
+Requires-Dist: openpyxl>=3.1.2
+Requires-Dist: python-docx>=0.8.11
+Provides-Extra: xls
+Requires-Dist: xlwt>=1.3.0; extra == "xls"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: flake8; extra == "dev"
+Dynamic: license-file
+
+# docx2csv
+
+Extracts tables from .docx files and saves them as CSV, TSV, XLSX, or JSON.
+
+[![CI](https://github.com/ivbeg/docx2csv/actions/workflows/ci.yml/badge.svg)](https://github.com/ivbeg/docx2csv/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/docx2csv.svg)](https://pypi.org/project/docx2csv/)
+[![Python](https://img.shields.io/pypi/pyversions/docx2csv.svg)](https://pypi.org/project/docx2csv/)
+
+## Installation
+
+```bash
+pip install docx2csv
+```
+
+For XLS (Excel 97) output support:
+
+```bash
+pip install docx2csv[xls]
+```
+
+## Quick Start
+
+### Command Line
+
+```bash
+# Extract all tables as separate CSV files
+docx2csv extract document.docx
+
+# Extract as XLSX
+docx2csv extract document.docx --format xlsx
+
+# Extract as single CSV file with all tables
+docx2csv extract document.docx --format csv --singlefile
+
+# Filter tables by minimum row count
+docx2csv extract document.docx --sizefilter 3
+
+# Specify output location
+docx2csv extract document.docx --output results.csv
+
+# Analyze a document (list tables without extracting)
+docx2csv analyze document.docx
+```
+
+### Python API
+
+```python
+from docx2csv import extract_tables, extract, analyze
+
+# Get table data as Python objects
+tables = extract_tables('document.docx')
+for table in tables:
+    print(f"Table {table['id']}: {table['num_rows']} rows x {table['num_cols']} cols")
+    for row in table['data']:
+        print(row)
+
+# Extract to file
+extract('document.docx', format='xlsx', output='output.xlsx')
+
+# Analyze document structure
+info = analyze('document.docx')
+```
+
+## Output Formats
+
+| Format | Extension | Description |
+|--------|-----------|-------------|
+| CSV    | `.csv`    | Comma-separated values |
+| TSV    | `.tsv`    | Tab-separated values |
+| XLSX   | `.xlsx`   | Excel 2007+ (via openpyxl) |
+| XLS    | `.xls`    | Excel 97 (requires `pip install docx2csv[xls]`) |
+| JSON   | `.json`   | Structured JSON with metadata |
+
+## Requirements
+
+- [click](https://github.com/pallets/click)
+- [python-docx](https://github.com/python-openxml/python-docx)
+- [openpyxl](https://openpyxl.readthedocs.io/)
+
+## Contributing
+
+Contributions are welcome! Every little bit helps.
+
+1. Fork the repo on GitHub
+2. Clone your fork: `git clone https://github.com/your-username/docx2csv.git`
+3. Create a branch: `git checkout -b name-of-your-bugfix-or-feature`
+4. Make your changes and add tests
+5. Run tests: `pytest`
+6. Commit and push: `git commit -m "Your message" && git push origin your-branch`
+7. Submit a pull request
+
+## Credits
+
+- **Ivan Begtin** - Author and maintainer
+- **Vsevolod Oparin** - Optimized table extraction code
+
+## License
+
+BSD 3-Clause License. See [LICENSE](LICENSE) for details.

docx2csv-0.1.4/README.md

@@ -0,0 +1,99 @@
+# docx2csv
+
+Extracts tables from .docx files and saves them as CSV, TSV, XLSX, or JSON.
+
+[![CI](https://github.com/ivbeg/docx2csv/actions/workflows/ci.yml/badge.svg)](https://github.com/ivbeg/docx2csv/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/docx2csv.svg)](https://pypi.org/project/docx2csv/)
+[![Python](https://img.shields.io/pypi/pyversions/docx2csv.svg)](https://pypi.org/project/docx2csv/)
+
+## Installation
+
+```bash
+pip install docx2csv
+```
+
+For XLS (Excel 97) output support:
+
+```bash
+pip install docx2csv[xls]
+```
+
+## Quick Start
+
+### Command Line
+
+```bash
+# Extract all tables as separate CSV files
+docx2csv extract document.docx
+
+# Extract as XLSX
+docx2csv extract document.docx --format xlsx
+
+# Extract as single CSV file with all tables
+docx2csv extract document.docx --format csv --singlefile
+
+# Filter tables by minimum row count
+docx2csv extract document.docx --sizefilter 3
+
+# Specify output location
+docx2csv extract document.docx --output results.csv
+
+# Analyze a document (list tables without extracting)
+docx2csv analyze document.docx
+```
+
+### Python API
+
+```python
+from docx2csv import extract_tables, extract, analyze
+
+# Get table data as Python objects
+tables = extract_tables('document.docx')
+for table in tables:
+    print(f"Table {table['id']}: {table['num_rows']} rows x {table['num_cols']} cols")
+    for row in table['data']:
+        print(row)
+
+# Extract to file
+extract('document.docx', format='xlsx', output='output.xlsx')
+
+# Analyze document structure
+info = analyze('document.docx')
+```
+
+## Output Formats
+
+| Format | Extension | Description |
+|--------|-----------|-------------|
+| CSV    | `.csv`    | Comma-separated values |
+| TSV    | `.tsv`    | Tab-separated values |
+| XLSX   | `.xlsx`   | Excel 2007+ (via openpyxl) |
+| XLS    | `.xls`    | Excel 97 (requires `pip install docx2csv[xls]`) |
+| JSON   | `.json`   | Structured JSON with metadata |
+
+## Requirements
+
+- [click](https://github.com/pallets/click)
+- [python-docx](https://github.com/python-openxml/python-docx)
+- [openpyxl](https://openpyxl.readthedocs.io/)
+
+## Contributing
+
+Contributions are welcome! Every little bit helps.
+
+1. Fork the repo on GitHub
+2. Clone your fork: `git clone https://github.com/your-username/docx2csv.git`
+3. Create a branch: `git checkout -b name-of-your-bugfix-or-feature`
+4. Make your changes and add tests
+5. Run tests: `pytest`
+6. Commit and push: `git commit -m "Your message" && git push origin your-branch`
+7. Submit a pull request
+
+## Credits
+
+- **Ivan Begtin** - Author and maintainer
+- **Vsevolod Oparin** - Optimized table extraction code
+
+## License
+
+BSD 3-Clause License. See [LICENSE](LICENSE) for details.

docx2csv-0.1.4/docx2csv/__init__.py

@@ -0,0 +1,10 @@
+# -*- coding: utf-8 -*-
+__version__ = '0.1.4'
+__author__ = "Ivan Begtin (ivan@begtin.tech)"
+__license__ = "BSD"
+
+
+from .converter import extract, extract_tables, analyze
+
+
+__all__ = ["extract", "extract_tables", "analyze"]

docx2csv-0.1.4/docx2csv/__main__.py

@@ -0,0 +1,18 @@
+#!/usr/bin/env python
+"""The main entry point.
+
+"""
+import sys
+
+
+def main():
+    try:
+        from .core import cli
+        exit_status = cli()
+    except KeyboardInterrupt:
+        print("Ctrl-C pressed. Aborting")
+    sys.exit(0)
+
+
+if __name__ == '__main__':
+    main()

docx2csv-0.1.4/docx2csv/converter.py

@@ -0,0 +1,263 @@
+# -*- coding: utf8 -*-
+
+import csv
+import os
+import json
+import datetime
+import warnings
+
+from typing import List, Dict, Any, Optional
+
+import openpyxl
+
+from docx import Document
+from docx.table import Table
+
+
+def _validate_input(filename: str) -> None:
+    """Validate that filename is a readable .docx file."""
+    if not os.path.exists(filename):
+        raise FileNotFoundError("File not found: %s" % filename)
+    if not os.path.isfile(filename):
+        raise ValueError("Path is not a file: %s" % filename)
+    if not filename.lower().endswith('.docx'):
+        warnings.warn("File does not have .docx extension: %s" % filename)
+
+
+def __extract_table(table: Table, strip_space: bool = False) -> List[List[str]]:
+    """Extracts table data from a table object using the public API.
+
+    Uses table.rows and row.cells instead of private XML attributes
+    (_tbl.tr_lst, tc_lst, grid_span, vMerge) for compatibility with
+    future python-docx releases.
+
+    Note: Merged cells are handled by tracking cell identity. Vertically
+    merged continuation cells replicate the value of the merge origin.
+    Horizontally duplicated cells (from gridSpan) are deduplicated.
+    """
+    results: List[List[str]] = []
+    # Track the last value per column for vertical merge continuation
+    col_values: Dict[int, str] = {}
+
+    for row in table.rows:
+        r: List[str] = []
+        seen_tcs: set = set()
+        col_idx: int = 0
+
+        for cell in row.cells:
+            tc_id: int = id(cell._tc)
+
+            # Skip duplicates from horizontal merge (gridSpan)
+            if tc_id in seen_tcs:
+                continue
+            seen_tcs.add(tc_id)
+
+            # Check for vertical merge continuation by examining the
+            # cell's XML for the vMerge element with no val attribute
+            # (which means "continue" in OOXML)
+            tc_element = cell._tc
+            vmerge = tc_element.find(
+                '{http://schemas.openxmlformats.org/wordprocessingml/2006/main}vMerge'
+            )
+
+            if vmerge is not None and vmerge.get(
+                '{http://schemas.openxmlformats.org/wordprocessingml/2006/main}val'
+            ) is None:
+                # vMerge continuation — reuse the value from the same column
+                # in a previous row
+                if col_idx in col_values:
+                    value = col_values[col_idx]
+                else:
+                    value = cell.text.replace("\n", " ")
+            else:
+                value = cell.text.replace("\n", " ")
+
+            if strip_space:
+                value = value.strip()
+
+            col_values[col_idx] = value
+            r.append(value)
+            col_idx += 1
+
+        results.append(r)
+
+    return results
+
+
+def __store_table(tabdata: List[List[str]], filename: str, format: str = "csv") -> None:
+    """Saves table data as csv/tsv/xls/xlsx file."""
+    if format == "csv":
+        with open(filename, "w", encoding='utf8') as f:
+            w = csv.writer(f, delimiter=",")
+            for row in tabdata:
+                w.writerow(row)
+    elif format == 'tsv':
+        with open(filename, 'w', encoding='utf8') as f:
+            w = csv.writer(f, delimiter='\t')
+            for row in tabdata:
+                w.writerow(row)
+    elif format == 'xls':
+        try:
+            import xlwt
+        except ImportError:
+            raise ImportError(
+                "XLS output requires xlwt. Install with: pip install docx2csv[xls]"
+            )
+        workbook = xlwt.Workbook()
+        ws = __xls_table_to_sheet(tabdata, workbook.add_sheet("0"))
+        workbook.save(filename)
+    elif format == "xlsx":
+        workbook = openpyxl.Workbook()
+        ws = __xlsx_table_to_sheet(tabdata, workbook.create_sheet("0"))
+        workbook.save(filename)
+
+
+def __xls_table_to_sheet(table: List[List[str]], ws: Any) -> Any:
+    """Write table data to an XLS worksheet."""
+    rn: int = 0
+    for row in table:
+        cn: int = 0
+        for c in row:
+            ws.write(rn, cn, c)
+            cn += 1
+        rn += 1
+    return ws
+
+
+def __xlsx_table_to_sheet(table: List[List[str]], ws: Any) -> Any:
+    """Write table data to an XLSX worksheet."""
+    for row in table:
+        ws.append(row)
+    return ws
+
+
+def extract_tables(filename: str, strip_space: bool = True) -> List[Dict[str, Any]]:
+    """Extracts tables from .DOCX files.
+
+    Args:
+        filename: Path to the .docx file.
+        strip_space: If True, strip leading/trailing whitespace from cell values.
+
+    Returns:
+        List of dicts with keys: id, num_cols, num_rows, style, data.
+    """
+    _validate_input(filename)
+    tables: List[Dict[str, Any]] = []
+    document = Document(filename)
+    n: int = 0
+    for table in document.tables:
+        n += 1
+        info: Dict[str, Any] = {}
+        info['id'] = n
+        info['num_cols'] = len(table.columns)
+        info['num_rows'] = len(table.rows)
+        info['style'] = table.style.name
+        tdata = __extract_table(table, strip_space=strip_space)
+        info['data'] = tdata
+        tables.append(info)
+    return tables
+
+
+def extract(
+    filename: str,
+    format: str = "csv",
+    sizefilter: int = 0,
+    singlefile: bool = False,
+    output: Optional[str] = None,
+    strip_space: bool = True,
+) -> None:
+    """Extracts tables from .docx files and saves them as csv, xls or xlsx files.
+
+    Args:
+        filename: Path to the .docx file.
+        format: Output format — 'csv', 'tsv', 'xls', 'xlsx', or 'json'.
+        sizefilter: Exclude tables with fewer than this many rows.
+        singlefile: If True, write all tables to a single file.
+        output: Output file path. Default: same directory as input.
+        strip_space: If True, strip leading/trailing whitespace from cell values.
+    """
+    _validate_input(filename)
+    tables = extract_tables(filename, strip_space=strip_space)
+    name: str = filename.rsplit(".", 1)[0]
+    fmt: str = format.lower()
+    n: int = 0
+    lfilter: int = int(sizefilter)
+
+    if singlefile:
+        if fmt == "xls":
+            try:
+                import xlwt
+            except ImportError:
+                raise ImportError(
+                    "XLS output requires xlwt. Install with: pip install docx2csv[xls]"
+                )
+            workbook = xlwt.Workbook()
+            for t in tables:
+                if lfilter > len(t['data']):
+                    continue
+                n += 1
+                __xls_table_to_sheet(t['data'], workbook.add_sheet(str(n)))
+            destname = output if output else name + ".%s" % (fmt)
+            workbook.save(destname)
+        elif fmt == "xlsx":
+            workbook = openpyxl.Workbook()
+            for t in tables:
+                if lfilter > len(t['data']):
+                    continue
+                n += 1
+                __xlsx_table_to_sheet(t['data'], workbook.create_sheet(str(n)))
+            destname = output if output else name + ".%s" % (fmt)
+            workbook.save(destname)
+        elif fmt == "json":
+            report: Dict[str, Any] = {
+                'filename': filename,
+                'timestamp': datetime.datetime.now().isoformat(),
+                'num_tables': len(tables),
+                'tables': tables,
+            }
+            destname = output if output else name + ".%s" % (fmt)
+            with open(destname, 'w', encoding='utf8') as f:
+                json.dump(report, f, ensure_ascii=False, indent=4)
+        elif fmt in ("csv", "tsv"):
+            delimiter: str = "," if fmt == "csv" else "\t"
+            destname = output if output else name + ".%s" % fmt
+            with open(destname, "w", encoding='utf8') as f:
+                w = csv.writer(f, delimiter=delimiter)
+                for i, t in enumerate(tables):
+                    if lfilter > len(t['data']):
+                        continue
+                    if i > 0:
+                        w.writerow([])
+                    for row in t['data']:
+                        w.writerow(row)
+    else:
+        for t in tables:
+            if lfilter > len(t['data']):
+                continue
+            n += 1
+            destname = output if output else name + "_%d.%s" % (n, fmt)
+            __store_table(t['data'], destname, fmt)
+
+
+def analyze(filename: str) -> List[Dict[str, Any]]:
+    """Analyzes .docx file and returns table metadata.
+
+    Args:
+        filename: Path to the .docx file.
+
+    Returns:
+        List of dicts with keys: id, num_cols, num_rows, style.
+    """
+    _validate_input(filename)
+    tableinfo: List[Dict[str, Any]] = []
+    document = Document(filename)
+    n: int = 0
+    for table in document.tables:
+        n += 1
+        info: Dict[str, Any] = {}
+        info['id'] = n
+        info['num_cols'] = len(table.columns)
+        info['num_rows'] = len(table.rows)
+        info['style'] = table.style.name
+        tableinfo.append(info)
+    return tableinfo

docx2csv-0.1.4/docx2csv/core.py

@@ -0,0 +1,77 @@
+#!/usr/bin/env python
+# -*- coding: utf8 -*-
+
+import sys
+
+import click
+
+import docx2csv
+from docx.opc.exceptions import PackageNotFoundError
+
+
+@click.group()
+def cli1():
+    """Extracts tables from DOCX files as CSV or XLSX.
+
+        Use command: "docx2csv extract <filename>" to run extraction.
+        It will create files like filename_1.csv, filename_2.csv for each table found.
+
+    """
+    pass
+
+
+@cli1.command()
+@click.argument('filename')
+@click.option('--format', '-f', default='csv', help='Output format: CSV, TSV, XLSX')
+@click.option('--singlefile', '-s', is_flag=True, show_default=True, default=False, help='Outputs single file with multiple tables')
+@click.option('--sizefilter', '-i', default=0, help='Filters table by minimum number of rows')
+@click.option('--output', '-o', default=None, help='Choose location of output file, default same location as input')
+def extract(filename, format, sizefilter, singlefile, output):
+    """
+        Extracts tables from DOCX files as CSV or TSV or XLSX.
+
+        Use command: "docx2csv extract <filename>" to run extraction.
+        It will create files like filename_1.csv, filename_2.csv for each table found.
+    """
+    try:
+        docx2csv.extract(filename, format, sizefilter, singlefile, output)
+    except FileNotFoundError as e:
+        click.echo("Error: %s" % e, err=True)
+        sys.exit(1)
+    except ValueError as e:
+        click.echo("Error: %s" % e, err=True)
+        sys.exit(1)
+    except PackageNotFoundError:
+        click.echo("Error: '%s' is not a valid .docx file." % filename, err=True)
+        sys.exit(1)
+
+
+@click.group()
+def cli2():
+    """Analyses of DOCX file, lists all existing tables
+    """
+    pass
+
+
+@cli2.command()
+@click.argument('filename')
+def analyze(filename):
+    """
+        Analyzes .docx file and finds tables
+    """
+    from pprint import pprint
+    try:
+        tableinfo = docx2csv.analyze(filename)
+        pprint(tableinfo)
+    except FileNotFoundError as e:
+        click.echo("Error: %s" % e, err=True)
+        sys.exit(1)
+    except ValueError as e:
+        click.echo("Error: %s" % e, err=True)
+        sys.exit(1)
+    except PackageNotFoundError:
+        click.echo("Error: '%s' is not a valid .docx file." % filename, err=True)
+        sys.exit(1)
+
+
+cli = click.CommandCollection(sources=[cli1, cli2])