Metadata-Version: 2.5
Name: tablelint
Version: 0.1.0
Summary: Lint academic tables before submission.
Project-URL: Homepage, https://github.com/coocoomaomao/TableLint
Project-URL: Repository, https://github.com/coocoomaomao/TableLint
Project-URL: Issues, https://github.com/coocoomaomao/TableLint/issues
Project-URL: Changelog, https://github.com/coocoomaomao/TableLint/blob/main/CHANGELOG.md
Author: coocoomaomao
License: MIT License
        
        Copyright (c) 2026 coocoomaomao
        
        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.
License-File: LICENSE
Keywords: academic,csv,latex,linter,publication,research,tables,xlsx
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.10
Requires-Dist: openpyxl>=3.1
Requires-Dist: rich>=13.7
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: pytest>=8.2; extra == 'dev'
Provides-Extra: release
Requires-Dist: build>=1.2; extra == 'release'
Requires-Dist: twine>=5.1; extra == 'release'
Description-Content-Type: text/markdown

# TableLint 🐈‍⬛📊

> **ESLint for academic tables.**

**TableLint** is an open-source linter for academic tables. It helps researchers catch deterministic data-quality and formatting problems before submission.

Part of **喵造实验室 / MeowBuild Lab** and the Academic Lint family:

- **FigureLint** — figure QA
- **RefLint** — reference QA
- **TableLint** — table QA
- **ManuscriptLint** — manuscript preflight

## Current checks

### CSV / XLSX

- empty column headers
- duplicate column headers
- entirely empty columns
- leftover placeholders such as `TODO`, `TBD`, `???`, and `FIXME`
- exact duplicate data rows (informational)
- explicit percentage values outside 0–100%
- numeric p-values outside 0–1 in clearly named p-value columns
- mixed decimal precision when one precision clearly dominates (informational)
- **header-declared Mean ± SD / SEM formatting**
- **header-declared Mean (SD / SEM) formatting**
- negative SD / SEM spread values
- **confidence-interval syntax and bound ordering**
- paired CI lower / upper column ordering
- opt-in significance-star ↔ exact p-value consistency checks

Summary-statistic checks only activate when the column header explicitly declares a combined representation such as `Mean ± SD` or `Mean (SEM)`. Confidence-interval checks only activate for headers that explicitly contain `CI` or `confidence interval`.

### LaTeX

- `table` environments without captions
- missing table labels (informational)
- missing `tabular` inside a table
- inconsistent simple row widths
- standalone `tabular` environments
- summary-statistic / CI cell checks when headers explicitly declare them

TableLint deliberately avoids claiming that a duplicated row or mixed decimal precision is scientifically wrong. Those cases are surfaced as information because they may be intentional.

## Install

Requires Python 3.10+.

The first public release is prepared for PyPI. After v0.1.0 is published:

~~~bash
pip install tablelint
~~~

### From source

~~~bash
git clone https://github.com/coocoomaomao/TableLint.git
cd TableLint
python -m venv .venv
pip install -e .
~~~

For development:

~~~bash
pip install -e ".[dev]"
pytest
~~~

## Usage

~~~bash
tablelint check results.csv
tablelint check results.xlsx
tablelint check tables.tex
tablelint check tables/
~~~

Fail CI when warnings exist:

~~~bash
tablelint check tables/ --strict
~~~

Machine-readable output:

~~~bash
tablelint check tables/ --format json
~~~

Enable a project-specific significance-star convention explicitly:

~~~bash
tablelint check results.csv --star-thresholds 0.05,0.01,0.001
~~~

The thresholds map to `*`, `**`, and `***` using strict `p < threshold` comparisons. Comparator p-values such as `<0.05` are skipped by this rule when they do not determine a unique star count.

Emit native GitHub Actions annotations:

~~~bash
tablelint check tables/ --github-annotations
~~~

### GitHub Actions

Before the first tagged release, use `@main`:

~~~yaml
- uses: coocoomaomao/TableLint@main
  with:
    path: tables/
    strict: "true"
~~~

After v0.1.0, pin the Action to `@v0.1.0`.

See [GitHub Action usage](docs/GITHUB_ACTION.md).

## Exit codes

- `0`: no structural errors; warnings are allowed unless `--strict` is used
- `1`: warnings found in strict mode
- `2`: unreadable / structural file errors

## Philosophy

TableLint separates:

1. **deterministic problems** — malformed/unreadable files, impossible ranges, reversed CI bounds, negative SD/SEM,
2. **likely formatting issues** — empty headers, placeholders, declared summary-statistic/CI syntax mismatches, LaTeX structure,
3. **context-dependent signals** — duplicates and precision consistency.

The third category stays informational by default. TableLint does not judge whether a reported mean, SD, SEM, CI width, or p-value is scientifically plausible.

## Release

The first public release is **v0.1.0**.

- [v0.1.0 release notes](docs/releases/v0.1.0.md)
- [Publishing guide](docs/PUBLISHING.md)

## Planned next

- optional unit consistency
- configurable missing-value policy
- ManuscriptLint integration

## License

MIT
