messy-table 0.1.0__tar.gz

messy_table-0.1.0/.gitignore

@@ -0,0 +1,33 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+*.so
+
+# Virtualenvs
+.venv/
+venv/
+env/
+
+# Tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+
+# OS / editor
+.DS_Store
+.idea/
+.vscode/
+*.swp
+
+# Local env (never commit secrets — none expected in a library, but be explicit)
+.env
+.env.*
+!.env.example

messy_table-0.1.0/CHANGELOG.md

@@ -0,0 +1,43 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project adheres
+to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] — 2026-06-06
+
+The first release. A complete, deterministic cleaning pipeline with a full audit
+trail.
+
+### Added
+
+- `clean(source, *, config=None)` — the single public entry point. Accepts a
+  path, raw `bytes`, or a binary/text file-like object.
+- **Readers**: `.xlsx` (openpyxl), `.csv` and `.tsv` with delimiter and encoding
+  (UTF-8 / cp1252 / Latin-1) sniffing.
+- **F1** table-start detection (skips titles, banners, metadata, blank rows).
+- **F2** header detection + normalisation: multi-row merged headers, duplicate
+  (`valor`, `valor_2`), empty (`column_3`) and leading-digit (`col_2024`) names,
+  slugified to `snake_case`.
+- **F3** merged cells: `fill` (propagate) or `first-only`.
+- **F4** Excel serial dates with both 1900 and 1904 epochs.
+- **F5** localised numbers (`1.234,56` vs `1,234.56`) inferred per column.
+- **F6** per-column type inference: `int`, `float`, `date`, `datetime`, `bool`,
+  `str`, with mixed-column handling.
+- **F7** disguised nulls (`-`, `N/A`, `#REF!`, `#DIV/0!`, …) → `None`, extensible.
+- **F8** trailing-junk trimming (totals, signatures, footnotes).
+- **F9** `CleanReport` — JSON-serialisable, every fix recorded with location and
+  confidence; per-cell fixes aggregated per column with counts and samples.
+- `CleanResult.to_pandas()` via the optional `messy-table[pandas]` extra.
+- `Config` for locale, header, sheet, merge mode, extra null tokens, strict mode,
+  and the file-safety limits.
+- `strict=True` raises `AmbiguityError` (always with a `Config` suggestion) where
+  permissive mode would warn.
+
+### Security
+
+- Decompression-bomb defence for `.xlsx`: absolute uncompressed-size and
+  compression-ratio limits checked before openpyxl opens the archive.
+- Hard cell ceiling (`Config.max_cells`) and text-size limit bound memory.
+
+[0.1.0]: https://github.com/messy-table/messy-table/releases/tag/v0.1.0

messy_table-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 messy-table contributors
+
+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.

messy_table-0.1.0/PKG-INFO

@@ -0,0 +1,176 @@
+Metadata-Version: 2.4
+Name: messy-table
+Version: 0.1.0
+Summary: Turn messy real-world spreadsheets into clean, typed data — with an auditable report of every fix.
+Project-URL: Homepage, https://github.com/messy-table/messy-table
+Project-URL: Repository, https://github.com/messy-table/messy-table
+Project-URL: Changelog, https://github.com/messy-table/messy-table/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/messy-table/messy-table/issues
+Author: messy-table contributors
+License: MIT
+License-File: LICENSE
+Keywords: csv,data-cleaning,data-ingestion,etl,excel,pandas,spreadsheet,xlsx
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+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: Topic :: Office/Business :: Financial :: Spreadsheet
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: openpyxl>=3.1.3
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pandas-stubs>=2.0; extra == 'dev'
+Requires-Dist: pandas>=2.0; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: pandas
+Requires-Dist: pandas>=2.0; extra == 'pandas'
+Description-Content-Type: text/markdown
+
+# messy-table
+
+> `pandas.read_excel` assumes your spreadsheet is well-behaved. **messy-table assumes it is not.**
+
+Turn messy real-world spreadsheets — Excel/CSV exported from ERPs, legacy systems,
+hand-made reports — into clean, typed data, and get back an **auditable report of
+every fix that was applied**.
+
+```python
+from messy_table import clean
+
+result = clean("relatorio_vendas.xlsx")
+
+result.data        # list[dict] — clean, typed rows
+result.columns     # per-column name / dtype / null summary
+result.report      # every transformation that was applied
+result.warnings    # low-confidence decisions
+result.to_pandas() # DataFrame (optional extra)
+```
+
+## Why
+
+AI agents and data pipelines receive arbitrary spreadsheets from users and today
+re-implement, by hand and fragilely, the same heuristics: find where the table
+starts, fix the headers, convert Excel serial dates, interpret `1.234,56`.
+messy-table is the canonical answer to that step — deterministic, dependency-light,
+and fully auditable.
+
+## Install
+
+```bash
+pip install messy-table            # core — depends only on openpyxl
+pip install 'messy-table[pandas]'  # adds result.to_pandas()
+```
+
+Python ≥ 3.10. Ships `py.typed` — fully type-checked.
+
+## Before & after
+
+A typical ERP export — a title banner, a blank row, pt-BR numbers, an `N/A`, and a
+trailing totals row:
+
+```
+Relatório de Vendas 2024
+(gerado em 01/02/2024)
+
+Produto      | Valor (R$) | Qtd | Ativo
+Café         | 1.234,56   | 10  | sim
+Chá          | 2.000,00   | 5   | nao
+Açúcar       | -          | 3   | sim
+TOTAL        | 3.234,56   | 18  |
+```
+
+```python
+>>> result = clean("vendas.xlsx")
+>>> result.data
+[{'produto': 'Café',   'valor_r': 1234.56, 'qtd': 10, 'ativo': True},
+ {'produto': 'Chá',    'valor_r': 2000.0,  'qtd': 5,  'ativo': False},
+ {'produto': 'Açúcar', 'valor_r': None,    'qtd': 3,  'ativo': True}]
+>>> [(c.name, c.dtype) for c in result.columns]
+[('produto', 'str'), ('valor_r', 'float'), ('qtd', 'int'), ('ativo', 'bool')]
+```
+
+The title, blank row and `TOTAL` line are gone; numbers are parsed in the column's
+inferred locale; `-` is a null; `sim/nao` became booleans — and the report says so.
+
+## Features (v0.1)
+
+| Feature | What it does |
+|---|---|
+| **Table-start detection** | Skips titles, logos, stray cells and metadata before the real header. |
+| **Header detection & normalisation** | Finds the header (or its absence); resolves duplicate/empty/multi-row headers; slugifies to `snake_case`. |
+| **Merged cells** | Propagates a merged value across its range (`fill`) or keeps it top-left only (`first-only`). |
+| **Excel serial dates** | Converts `45123` → a real date when the column has a date profile (both 1900 and 1904 epochs). |
+| **Localised numbers** | `1.234,56` (pt-BR/EU) vs `1,234.56` (en-US), inferred per **column**, never per cell. |
+| **Column type inference** | `int`/`float`/`date`/`datetime`/`bool`/`str`, with mixed-column handling. |
+| **Disguised nulls** | `-`, `N/A`, `n/d`, `#REF!`, `#DIV/0!`, blanks → `None` (extensible). |
+| **Trailing junk** | Removes totals, signatures and footnotes after the data ends. |
+| **Cleaning report** | Structured, JSON-serialisable record of every correction with location and confidence. |
+| **Input formats** | `.xlsx`, `.csv` (delimiter + encoding sniffing), `.tsv`. |
+
+## The report
+
+Nothing changes without a record. Per-cell fixes are aggregated per column with a
+count and sample locations, so the report stays small even on huge files:
+
+```python
+>>> print(result.report.to_json())
+{
+  "summary": {"table_start_detected": 1, "table_end_trimmed": 1,
+              "header_renamed": 1, "null_normalized": 1,
+              "number_parsed": 4, "type_coerced": 2},
+  "actions": [
+    {"kind": "table_start_detected", "rule": "density", "confidence": 0.8,
+     "detail": "skipped 3 leading row(s) (title/metadata/blank); table starts at row 3"},
+    {"kind": "number_parsed", "rule": "locale:pt_BR", "column": "valor_r",
+     "count": 4, "confidence": 1.0,
+     "examples": [{"row": 0, "original": "1.234,56", "final": 1234.56}]},
+    ...
+  ]
+}
+```
+
+## Configuration
+
+The 80% case needs no config. For the rest:
+
+```python
+from messy_table import clean, Config
+
+result = clean(
+    "dados.csv",
+    config=Config(
+        locale="pt_BR",            # force number/date interpretation; default "auto"
+        header="auto",             # "auto" | int (row index) | None (no header)
+        sheet=0,                   # index or name of the worksheet
+        merged_cells="fill",       # "fill" | "first-only"
+        null_values_extra=["s/i"], # add to the built-in null list
+        strict=False,              # True: raise AmbiguityError instead of warning
+    ),
+)
+```
+
+In `strict=True`, a low-confidence decision raises `AmbiguityError` — always with a
+copy-pasteable `Config` suggestion to resolve it.
+
+## Security
+
+messy-table parses untrusted files, so it defends against it: `.xlsx` archives are
+checked for decompression-bomb shape (absolute size and ratio) **before** they are
+opened, and a hard cell ceiling bounds memory. See [ARCHITECTURE.md](ARCHITECTURE.md).
+
+## Docs
+
+- [ARCHITECTURE.md](ARCHITECTURE.md) — pipeline, stack rationale, security decisions.
+- [docs/heuristics.md](docs/heuristics.md) — every heuristic and its thresholds.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

messy_table-0.1.0/README.md

@@ -0,0 +1,140 @@
+# messy-table
+
+> `pandas.read_excel` assumes your spreadsheet is well-behaved. **messy-table assumes it is not.**
+
+Turn messy real-world spreadsheets — Excel/CSV exported from ERPs, legacy systems,
+hand-made reports — into clean, typed data, and get back an **auditable report of
+every fix that was applied**.
+
+```python
+from messy_table import clean
+
+result = clean("relatorio_vendas.xlsx")
+
+result.data        # list[dict] — clean, typed rows
+result.columns     # per-column name / dtype / null summary
+result.report      # every transformation that was applied
+result.warnings    # low-confidence decisions
+result.to_pandas() # DataFrame (optional extra)
+```
+
+## Why
+
+AI agents and data pipelines receive arbitrary spreadsheets from users and today
+re-implement, by hand and fragilely, the same heuristics: find where the table
+starts, fix the headers, convert Excel serial dates, interpret `1.234,56`.
+messy-table is the canonical answer to that step — deterministic, dependency-light,
+and fully auditable.
+
+## Install
+
+```bash
+pip install messy-table            # core — depends only on openpyxl
+pip install 'messy-table[pandas]'  # adds result.to_pandas()
+```
+
+Python ≥ 3.10. Ships `py.typed` — fully type-checked.
+
+## Before & after
+
+A typical ERP export — a title banner, a blank row, pt-BR numbers, an `N/A`, and a
+trailing totals row:
+
+```
+Relatório de Vendas 2024
+(gerado em 01/02/2024)
+
+Produto      | Valor (R$) | Qtd | Ativo
+Café         | 1.234,56   | 10  | sim
+Chá          | 2.000,00   | 5   | nao
+Açúcar       | -          | 3   | sim
+TOTAL        | 3.234,56   | 18  |
+```
+
+```python
+>>> result = clean("vendas.xlsx")
+>>> result.data
+[{'produto': 'Café',   'valor_r': 1234.56, 'qtd': 10, 'ativo': True},
+ {'produto': 'Chá',    'valor_r': 2000.0,  'qtd': 5,  'ativo': False},
+ {'produto': 'Açúcar', 'valor_r': None,    'qtd': 3,  'ativo': True}]
+>>> [(c.name, c.dtype) for c in result.columns]
+[('produto', 'str'), ('valor_r', 'float'), ('qtd', 'int'), ('ativo', 'bool')]
+```
+
+The title, blank row and `TOTAL` line are gone; numbers are parsed in the column's
+inferred locale; `-` is a null; `sim/nao` became booleans — and the report says so.
+
+## Features (v0.1)
+
+| Feature | What it does |
+|---|---|
+| **Table-start detection** | Skips titles, logos, stray cells and metadata before the real header. |
+| **Header detection & normalisation** | Finds the header (or its absence); resolves duplicate/empty/multi-row headers; slugifies to `snake_case`. |
+| **Merged cells** | Propagates a merged value across its range (`fill`) or keeps it top-left only (`first-only`). |
+| **Excel serial dates** | Converts `45123` → a real date when the column has a date profile (both 1900 and 1904 epochs). |
+| **Localised numbers** | `1.234,56` (pt-BR/EU) vs `1,234.56` (en-US), inferred per **column**, never per cell. |
+| **Column type inference** | `int`/`float`/`date`/`datetime`/`bool`/`str`, with mixed-column handling. |
+| **Disguised nulls** | `-`, `N/A`, `n/d`, `#REF!`, `#DIV/0!`, blanks → `None` (extensible). |
+| **Trailing junk** | Removes totals, signatures and footnotes after the data ends. |
+| **Cleaning report** | Structured, JSON-serialisable record of every correction with location and confidence. |
+| **Input formats** | `.xlsx`, `.csv` (delimiter + encoding sniffing), `.tsv`. |
+
+## The report
+
+Nothing changes without a record. Per-cell fixes are aggregated per column with a
+count and sample locations, so the report stays small even on huge files:
+
+```python
+>>> print(result.report.to_json())
+{
+  "summary": {"table_start_detected": 1, "table_end_trimmed": 1,
+              "header_renamed": 1, "null_normalized": 1,
+              "number_parsed": 4, "type_coerced": 2},
+  "actions": [
+    {"kind": "table_start_detected", "rule": "density", "confidence": 0.8,
+     "detail": "skipped 3 leading row(s) (title/metadata/blank); table starts at row 3"},
+    {"kind": "number_parsed", "rule": "locale:pt_BR", "column": "valor_r",
+     "count": 4, "confidence": 1.0,
+     "examples": [{"row": 0, "original": "1.234,56", "final": 1234.56}]},
+    ...
+  ]
+}
+```
+
+## Configuration
+
+The 80% case needs no config. For the rest:
+
+```python
+from messy_table import clean, Config
+
+result = clean(
+    "dados.csv",
+    config=Config(
+        locale="pt_BR",            # force number/date interpretation; default "auto"
+        header="auto",             # "auto" | int (row index) | None (no header)
+        sheet=0,                   # index or name of the worksheet
+        merged_cells="fill",       # "fill" | "first-only"
+        null_values_extra=["s/i"], # add to the built-in null list
+        strict=False,              # True: raise AmbiguityError instead of warning
+    ),
+)
+```
+
+In `strict=True`, a low-confidence decision raises `AmbiguityError` — always with a
+copy-pasteable `Config` suggestion to resolve it.
+
+## Security
+
+messy-table parses untrusted files, so it defends against it: `.xlsx` archives are
+checked for decompression-bomb shape (absolute size and ratio) **before** they are
+opened, and a hard cell ceiling bounds memory. See [ARCHITECTURE.md](ARCHITECTURE.md).
+
+## Docs
+
+- [ARCHITECTURE.md](ARCHITECTURE.md) — pipeline, stack rationale, security decisions.
+- [docs/heuristics.md](docs/heuristics.md) — every heuristic and its thresholds.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

messy_table-0.1.0/docs/heuristics.md

@@ -0,0 +1,123 @@
+# Heuristics
+
+Every heuristic in messy-table, what signal it uses, and the thresholds it trips
+on. Thresholds live as named constants in code; this file is the prose companion.
+When you change a threshold, update both.
+
+A shared idea runs through all of them: produce a **confidence** in `[0, 1]`.
+Below `Config.confidence_threshold` (default **0.6**) the decision is *ambiguous*
+— a warning in permissive mode, an `AmbiguityError` (with a `Config` suggestion)
+in strict mode.
+
+## Density, merge-aware (shared primitive)
+
+`util.merge_covered_cells` + `util.density_threshold`.
+
+A row's *filled count* = non-blank cells **plus** cells covered by a **row-spanning**
+merge (vertical/block). Horizontal one-row merges (banners) are excluded so titles
+stay sparse.
+
+`density_threshold(width, ratio=0.5)`:
+- width 1 → **1** (single-column tables are real).
+- width ≥ 2 → `max(2, ceil(0.5 · width))` (a lone stray cell never counts as data).
+
+## F1 — table start (`detectors/table_start.py`)
+
+- Compute the merge-aware filled count per row; `width` = the max across rows.
+- A row is *substantial* if its filled count ≥ `density_threshold(width)`.
+- The table starts at the first row of the **longest contiguous run** of
+  substantial rows. (A blank row between a metadata block and the table breaks the
+  run, so the longer table run wins.)
+- Confidence = `clamp(body_density − above_density + 0.5)`. Skipping rows with a
+  sparse preamble is high-confidence; skipping into a still-dense region is not.
+- `Config(header=<int>)` pins the start and bypasses detection.
+
+**Known limit:** a metadata block *immediately* above the table with no blank
+separator and the same column count can be absorbed. A blank separator (the common
+real case) resolves it; otherwise pin `header`.
+
+## F2 — header (`detectors/header.py` + `transformers/header_names.py`)
+
+Detection (grid already body-sliced and unmerged, so the header is at row 0):
+
+- **Headerless?** If row 0 is not text-heavy (`text_ratio < 0.5`), has no
+  horizontal merge, and shares the exact per-column category signature of row 1,
+  there is no header → synthesise `column_1…` and start data at row 0 (warned).
+- **How many header rows?** Start at 1. While the current top header row intersects
+  a **horizontal merge** (a spanned group cell), consume the next row too — up to
+  `MAX_HEADER_ROWS` (3). This ties multi-row detection to real structure rather
+  than a fragile text test.
+- Confidence: 0.9 if row 0 is text-heavy, else 0.55.
+
+Naming (`header_names.py`): NFKD accent-strip → lowercase → non-word → `_` →
+collapse/trim. Empty → `column_{i}`; leading digit → `col_…`; duplicates get
+`_2`, `_3`. Every rename is recorded.
+
+## F3 — merged cells (`transformers/merged_cells.py`)
+
+`fill` (default): copy each merge's anchor value to every other cell in its range.
+`first-only`: leave them `None` (openpyxl's default) — a no-op. Each filled cell is
+recorded. Skipped on very large (streaming) sheets, with a warning.
+
+## F4 — Excel serial dates (`transformers/dates.py`)
+
+Date-formatted xlsx cells already arrive as `datetime` (openpyxl applies the
+epoch). F4 targets the *messy* case: a column of **bare numbers** that are really
+dates. Converted only when **both** hold:
+
+1. every value sits in the serial range **20000–60000** (≈ 1954–2064), **and**
+2. there is corroboration — the cell's number format looks like a date
+   (`fmt_is_date`, confidence **0.9**) **or** the column name hints at a date
+   (`data`, `vencimento`, `date`, … → confidence **0.7**).
+
+Bare numbers with no hint are left numeric (so an `ano`/`year` column survives).
+Conversion uses the workbook epoch (1899-12-30 base absorbs the 1900 leap bug;
+1904-01-01 for Mac). Integer serial → `date`; fractional → `datetime`.
+
+## F5 — localised numbers (`transformers/numbers.py`)
+
+Only columns where ≥ **70%** (`NUMERIC_COLUMN_RATIO`) of non-blank string cells look
+numeric are treated as numeric. Per-value *decimal vote*:
+
+- both `.` and `,` present → the **last** one is the decimal point;
+- one separator present → it is *thousands grouping* only if it splits into clean
+  3-digit runs (`1.234`, `12.345.678`), otherwise it is the decimal point.
+
+The column's majority vote picks the convention; confidence = winner / total votes
+(so a 50/50 split → 0.5, below threshold → ambiguous). `Config(locale=…)` overrides
+the vote (confidence 1.0). Currency symbols, spaces, NBSP, apostrophes and a
+trailing `%` (divide by 100) are handled.
+
+## F6 — column types (`transformers/types.py`)
+
+Per column, over surviving non-null values:
+
+- all `date`/`datetime` → `date`, or `datetime` if any carry a time (bare dates are
+  promoted to datetime for uniformity);
+- all `int` → `int`; any fractional → `float`;
+- all boolean (native or text tokens `true/false/sim/não/yes/no/…`) → `bool`;
+- otherwise → `str` (lossless fallback, with a "mixes types" warning when the column
+  genuinely mixed numbers and text).
+
+## F7 — disguised nulls (`transformers/nulls.py`)
+
+Case-insensitive, trimmed match against the built-in token set (`-`, `--`, `n/a`,
+`n/d`, `null`, `none`, `nil`, `nan`, and the Excel error literals `#REF!`,
+`#DIV/0!`, `#VALUE!`, …) plus `Config.null_values_extra`. Matches become `None`.
+
+## F8 — trailing junk (`detectors/table_end.py`)
+
+Walk up from the bottom; trim a row while it is **sparse** (below the body density
+threshold), **empty**, or starts with a **summary keyword** (`total`, `subtotal`,
+`soma`, `fonte`, `gerado em`, `assinatura`, …). Stop at the first real data row.
+Confidence 0.85 when a keyword matched, else 0.7.
+
+## CSV delimiter & encoding (`readers/csv.py`)
+
+- **Encoding:** decode cascade `utf-8-sig` → `cp1252` → `latin-1` (the last never
+  fails). The first that decodes wins.
+- **Delimiter:** structural, not `csv.Sniffer` (which preamble rows fool). For each
+  candidate (`, ; \t |`) score by how many lines share a modal field count ≥ 2,
+  requiring at least half the lines to split. Best agreement wins; ties broken by
+  more fields. If nothing qualifies → **single column** (a lone decimal comma is not
+  a delimiter). `.tsv` forces tab.

messy_table-0.1.0/pyproject.toml

@@ -0,0 +1,136 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "messy-table"
+version = "0.1.0"
+description = "Turn messy real-world spreadsheets into clean, typed data — with an auditable report of every fix."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "messy-table contributors" }]
+keywords = ["excel", "xlsx", "csv", "data-cleaning", "spreadsheet", "etl", "pandas", "data-ingestion"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Office/Business :: Financial :: Spreadsheet",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+# openpyxl is the ONLY mandatory dependency. >=3.1.3 pulls in the read-only
+# date handling fixes and the et-xmlfile pin that closes the XML entity issues.
+dependencies = ["openpyxl>=3.1.3"]
+
+[project.urls]
+Homepage = "https://github.com/messy-table/messy-table"
+Repository = "https://github.com/messy-table/messy-table"
+Changelog = "https://github.com/messy-table/messy-table/blob/main/CHANGELOG.md"
+Issues = "https://github.com/messy-table/messy-table/issues"
+
+[project.optional-dependencies]
+# `pip install messy-table[pandas]` enables CleanResult.to_pandas().
+pandas = ["pandas>=2.0"]
+dev = [
+    "pytest>=8.0",
+    "pytest-cov>=5.0",
+    "ruff>=0.6",
+    "mypy>=1.11",
+    "pandas>=2.0",
+    "pandas-stubs>=2.0",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/messy_table"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/messy_table", "tests", "docs", "README.md", "CHANGELOG.md", "LICENSE"]
+
+# ----------------------------------------------------------------------------
+# Ruff — lint + format. Opinionated, strict, zero tolerance for the basics.
+# ----------------------------------------------------------------------------
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = [
+    "E", "W",    # pycodestyle
+    "F",         # pyflakes
+    "I",         # isort
+    "N",         # pep8-naming
+    "UP",        # pyupgrade
+    "B",         # flake8-bugbear
+    "C4",        # comprehensions
+    "SIM",       # simplify
+    "RUF",       # ruff-specific
+    "PTH",       # use pathlib
+    "TID",       # tidy imports
+    "BLE",       # blind-except — no bare/broad except in the core
+    "S",         # bandit security checks
+]
+ignore = [
+    "S101",  # asserts are fine in tests
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["S", "N802", "N806"]
+"tests/_fixtures_gen.py" = ["S", "N802", "N806"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["messy_table"]
+
+# ----------------------------------------------------------------------------
+# mypy — strict. The library ships py.typed; the public surface is fully typed.
+# ----------------------------------------------------------------------------
+[tool.mypy]
+python_version = "3.10"
+strict = true
+warn_unreachable = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+disallow_untyped_defs = true
+disallow_any_generics = true
+no_implicit_reexport = true
+show_error_codes = true
+files = ["src/messy_table"]
+
+[[tool.mypy.overrides]]
+# openpyxl ships no type stubs upstream; we isolate the untyped boundary in
+# the readers and treat it as the only place `Any` may legitimately enter.
+module = ["openpyxl.*"]
+ignore_missing_imports = true
+
+# ----------------------------------------------------------------------------
+# pytest + coverage
+# ----------------------------------------------------------------------------
+[tool.pytest.ini_options]
+minversion = "8.0"
+testpaths = ["tests"]
+addopts = "-q --strict-markers --strict-config"
+markers = [
+    "perf: performance-gate tests (may be slow); run with -m perf",
+]
+
+[tool.coverage.run]
+branch = true
+source = ["messy_table"]
+omit = ["*/tests/*"]
+
+[tool.coverage.report]
+# Acceptance criterion: 90% minimum on the core. Hardened, not loosened.
+fail_under = 90
+show_missing = true
+exclude_lines = [
+    "pragma: no cover",
+    "if TYPE_CHECKING:",
+    "raise NotImplementedError",
+    "\\.\\.\\.",
+]