Metadata-Version: 2.4
Name: tabwrap
Version: 1.5.0
Summary: Wrap LaTeX table fragments into complete documents for research workflows
Project-URL: Homepage, https://github.com/janfasnacht/tabwrap
Project-URL: Repository, https://github.com/janfasnacht/tabwrap
Project-URL: Documentation, https://github.com/janfasnacht/tabwrap#readme
Author-email: Jan Fasnacht <jan.fasnacht@gmail.com>
License-File: LICENSE
Keywords: academic,latex,research,statistics,tables
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
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
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Text Processing :: Markup :: LaTeX
Requires-Python: >=3.10
Requires-Dist: click>=8.1.7
Requires-Dist: numpy>=2.1.2
Requires-Dist: pymupdf>=1.24.11
Provides-Extra: api
Requires-Dist: fastapi>=0.115.0; extra == 'api'
Requires-Dist: gunicorn>=23.0.0; extra == 'api'
Requires-Dist: pydantic-settings>=2.6.1; extra == 'api'
Requires-Dist: python-multipart>=0.0.12; extra == 'api'
Requires-Dist: slowapi>=0.1.9; extra == 'api'
Requires-Dist: uvicorn>=0.32.0; extra == 'api'
Description-Content-Type: text/markdown

# tabwrap

[![PyPI version](https://badge.fury.io/py/tabwrap.svg)](https://pypi.org/project/tabwrap/)
[![Python](https://img.shields.io/pypi/pyversions/tabwrap.svg)](https://pypi.org/project/tabwrap/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**Wrap LaTeX table fragments into complete documents for research workflows**

A simple Python tool that transforms statistical programming output (LaTeX table fragments) into compiled PDFs, PNGs, or SVGs. Perfect for researchers who need to quickly inspect, share, and explore tables from Stata, R, Python, and other statistical tools.

**Web Interface**: [tabwrap.janfasnacht.com](https://tabwrap.janfasnacht.com)

## What it does

`tabwrap` takes incomplete LaTeX table fragments like this:
```latex
\begin{tabular}{lcr}
\toprule
Variable & Coefficient & P-value \\
\midrule
Intercept & 1.23 & 0.045 \\
\bottomrule
\end{tabular}
```

And automatically wraps them into complete, compilable LaTeX documents with:
- Auto-detected packages (booktabs, tabularx, siunitx, etc.)
- Proper document structure and preambles
- Auto-fit page sized to the table
- Multi-file batch processing with error recovery
- Combined PDFs with table of contents
- PNG output with automatic cropping, SVG support
- Enhanced error reporting with suggestions

## Quick Start

### Prerequisites

**LaTeX Distribution Required:** tabwrap needs a LaTeX installation to compile documents.

- **Windows**: [MiKTeX](https://miktex.org/download) or [TeX Live](https://tug.org/texlive/)
- **macOS**: [MacTeX](https://tug.org/mactex/) or `brew install --cask mactex`
- **Linux**: `sudo apt-get install texlive-full` or equivalent

**Optional for PNG output**: [ImageMagick](https://imagemagick.org/script/download.php)

### Installation

#### Recommended (CLI tools):

```bash
pipx install tabwrap
```

#### Standard Python installation:

```bash
pip install tabwrap
```

#### With API support:

```bash
pip install tabwrap[api]
```

### Basic Usage

```bash
# Compile a single table
tabwrap regression_table.tex

# Process all tables in a folder
tabwrap ./results_tables/

# Output PNG
tabwrap table.tex -p

# Batch process with combined PDF
tabwrap ./tables/ -r -c    # recursive + combine PDFs

# Show filename headers and keep intermediate files
tabwrap data/ --header --keep-tex
```

## Features

### Error Handling

```
⚠️  1 of 3 files failed to compile:

📋 Failed files:
   • bad_table.tex
     Invalid tabular content: No tabular environment found

✅ Successfully compiled: table1.tex, table2.tex
```

### Smart Package Detection

Automatically detects and includes required packages:
- `booktabs` for \\toprule, \\midrule, \\bottomrule
- `tabularx` for \\begin{tabularx}
- `siunitx` for \\SI{}{}, \\num{}
- `multirow` for \\multirow
- And many more...

For commands that need a `\newcommand` rather than a package, tabwrap injects
the definition directly. For example, `\sym{**}` from Stata's `esttab` gets a
matching `\newcommand{\sym}` in the preamble. Use `--preamble` for arbitrary
preamble lines outside the curated rule set.

### Flexible Output Options

```bash
# Output formats
tabwrap table.tex                     # PDF output (default)
tabwrap table.tex -p                  # PNG output with auto-cropping
tabwrap table.tex --svg               # SVG output (vector graphics)

# Batch processing
tabwrap folder/ -r                    # Process subdirectories recursively
tabwrap folder/ -j                    # Parallel processing (4-6x faster)
tabwrap folder/ -c                    # Combine into single PDF with TOC

# Layout and formatting
tabwrap table.tex --header            # Show filename as header
```

### Shell Completion

tabwrap supports shell completion for bash, zsh, and fish:

```bash
# Bash - add to ~/.bashrc
tabwrap --completion bash >> ~/.bashrc

# Zsh - add to ~/.zshrc
tabwrap --completion zsh >> ~/.zshrc

# Fish - save to completions directory
tabwrap --completion fish > ~/.config/fish/completions/tabwrap.fish
```

## CLI Reference

```
Usage: tabwrap [OPTIONS] [INPUT_PATH]

Arguments:
  INPUT_PATH               .tex file or directory to process [default: current directory]

Output Options:
  -o, --output PATH        Output directory [default: current directory]
  --suffix TEXT            Output filename suffix [default: _compiled]
  -p, --png                Output PNG instead of PDF
  --svg                    Output SVG instead of PDF

Processing Options:
  -r, --recursive          Process subdirectories recursively
  -j, --parallel           Process files in parallel for faster batch compilation
  --max-workers INTEGER    Maximum number of parallel workers [default: CPU cores]
  -c, --combine            Combine multiple PDFs with table of contents

Formatting Options:
  --header                 Show filename as header in output
  --packages TEXT          Comma-separated LaTeX packages (auto-detected if empty)
  --preamble TEXT          Extra preamble lines (e.g. \newcommand) inserted verbatim after \usepackage

Advanced Options:
  --keep-tex               Keep generated LaTeX files and compilation logs for debugging
  --completion [bash|zsh|fish]  Generate shell completion script
  --help                   Show this message and exit
```

### Common Usage Patterns

```bash
# Basic compilation
tabwrap table.tex                     # PDF output
tabwrap table.tex -p                  # PNG output
tabwrap table.tex --svg               # SVG output

# Batch processing
tabwrap folder/                       # All .tex files in folder
tabwrap folder/ -r                    # Include subdirectories
tabwrap folder/ -j                    # Parallel processing (faster)
tabwrap folder/ -c                    # Combined PDF with TOC

# Formatting options
tabwrap table.tex --header            # Show filename header
tabwrap table.tex --preamble '\newcommand{\sig}[1]{\textbf{#1}}'  # Inject preamble lines (e.g. custom \newcommand)

# Output control
tabwrap table.tex -o output/          # Custom output directory
tabwrap table.tex --suffix _final     # Custom filename suffix
```

## API Usage

### Python Library
For programmatic access:

```python
from tabwrap import TabWrap

compiler = TabWrap()
result = compiler.compile_tex(
    input_path="table.tex",
    output_dir="output/",
    png=True,
)
print(f"Compiled to: {result}")
```

### Web API
Run the FastAPI server for web applications:

```bash
# Install with API dependencies
pip install tabwrap[api]

# Start the API server
python -m tabwrap.api

# API endpoints
# GET  /api/health - Service health check
# POST /api/compile - Compile LaTeX table fragment
```

## Research Workflow Integration

### Stata

```stata
esttab using "regression_results.tex", replace booktabs
! tabwrap regression_results.tex -p
```

### R

```r
library(xtable)
xtable(model) %>%
  print(file = "model_table.tex", include.rownames = FALSE)
system("tabwrap model_table.tex")
```

### Python

```python
df.to_latex("data_summary.tex", index=False)
os.system("tabwrap data_summary.tex -p")
```

## Development

### Contributing

1. Fork the repository
2. Create a feature branch: `git checkout -b feature-name`
3. Make changes and add tests
4. Run tests: `uv run pytest`
5. Submit a pull request

### Development Setup

```bash
git clone https://github.com/janfasnacht/tabwrap.git
cd tabwrap
uv sync --extra api
uv run pytest  # Run tests
```

### Building and Testing

```bash
uv build                       # Build distribution packages
uv run tabwrap --help         # Test CLI
make test                       # Run full test suite
make test-coverage              # Generate coverage report
```

## License

MIT License - see [LICENSE](LICENSE) file for details.
