Skip to content

Releases

v2.0.0

Choose a tag to compare

@bosd bosd released this 04 Jun 16:30
eef30ac

[2.0.0] — 2026-06-04

The 2.0 release rolls up a substantial backend migration, the resulting
performance work, an optional neural (Table Transformer) backend for
borderless and scanned tables, and a handful of small but user-visible
breaking changes. Heads-up if upgrading from 1.0.x — see the
migration guide:

Breaking

  • Dropped Python 3.9 (EOL October 2025). Minimum supported is now
    Python 3.10. (#740)
  • flavor="lattice" default line_scale changed from 40 to 15 to match
    the long-standing implementation (the CLI and read_pdf docstring used
    to say 40 but the Lattice parser always defaulted to 15). Tables that
    relied on the documented-but-unimplemented 40 will need
    read_pdf(..., line_scale=40) explicitly. (#709)
  • Table.to_excel now defaults to index=False, header=False to match
    Table.to_csv. Excel exports no longer carry the pandas auto-generated
    row index / column header by default. Opt back in with
    table.to_excel(path, index=True, header=True). (#711)
  • TableList constructor materialises its iterable input to a list
    immediately, so bool() and len() work on TableList(generator())
    inputs. A generator passed in will be exhausted at construction time
    rather than at first access. (#710)
  • PDFHandler.pages is a property (was an attribute). Reads work
    unchanged; the value is now resolved lazily on first access. No callers
    in the wild set it, but if you subclassed and overrode it as an
    attribute, that no longer works. (#732)
  • PDF backend swapped from pypdf + pdfminer.six to
    playa-pdf
    . The dependency
    install set is smaller, encrypted-PDF handling is more accurate, and
    parser hot paths shed several layers of per-page-temp-PDF dance. Pure
    import camelot callers should see no API change.

Added

  • Optional neural flavor="ml" backend (Table Transformer / TATR). A
    neural model supplies the row/column/spanning-cell structure while cell
    text is filled from the PDF's own text layer — the model never emits cell
    text, so it cannot hallucinate or alter a value. Aimed at borderless tables,
    where the heuristic parsers plateau: on the FinTabNet borderless benchmark it
    roughly doubles TEDS (~0.20 → ~0.37) over network/hybrid. Heavy
    dependencies are optional and imported lazily — pip install "camelot-py[ml]"
    — so import camelot and the other flavors never load PyTorch. The box→grid
    post-processing and image→PDF mapping are pure (torch-free) and unit-tested.
    (#809)
  • flavor="ml" reads scanned / image-only PDFs via optional OCR. With no
    text layer (ocr="auto", the default) — or always with ocr=True — cell
    text comes from OCR of the rendered page instead of the PDF text layer;
    structure still comes from the model. This lifts Camelot's long-standing
    "needs a text layer" limitation. Opt in with pip install "camelot-py[ocr]".
    Still geometry + recognised text (no invented cells); split_text /
    flag_size aren't supported in OCR mode. (#809)
  • TableList.filter(...) — post-extraction convenience to drop noise /
    low-quality tables by min_rows, min_columns, min_accuracy,
    max_whitespace. Returns a new TableList (composable); all thresholds
    default to a no-op so nothing is dropped unless asked.
  • engine="combined" for flavor="lattice" (and the lattice half of
    flavor="hybrid"): unions the PDF's native vector ruled lines into the
    rasterised OpenCV line masks before contour/joint detection, so tables
    whose rules render faintly (vector strokes, anti-aliasing) are still
    found. Safe by construction — raster always runs, vector lines can only
    add, so output is never worse than engine="raster". It is now the
    default lattice engine and vector lines are clipped to
    table_regions. (#763)
  • engine="vector" for flavor="lattice": detects tables purely from
    the PDF's native vector ruled lines, skipping page rasterisation and
    OpenCV entirely
    — the fastest path for PDFs whose tables are drawn
    with real vector strokes. (#763)
  • engine="vector" for flavor="hybrid" — the render-free hybrid.
    Hybrid's lattice half now also accepts engine="vector", so the network
    text-edge alignment is merged (via the completeness-gated combine) with
    ruled lines read straight from the PDF's vector graphics — no page
    render, no OpenCV
    . On the in-repo ICDAR-2013 benchmark it matches or
    beats engine="raster" hybrid on every metric (F1 0.702→0.726, TEDS
    0.724→0.755, row 0.417→0.464, col 0.689→0.715) at ~6× less time
    (113s→19s); on FinTabNet.c (borderless) it matches raster hybrid's
    quality at ~2.4× less time. Hybrid also now drops empty tables the vector
    ruled-line set can raise from decorative page borders / form rules (which
    in turn lifts engine="raster" hybrid F1 from removing those spurious
    detections). (#39)
  • flavor="auto": render the first requested page, count ruled
    horizontal/vertical lines, pick lattice when ruled and network
    otherwise. Emits a UserWarning naming the chosen flavor. (#737)
  • Table.confidence — unified per-table quality score in [0, 1]
    computed as (accuracy / 100) * (1 - whitespace / 100). Now appears as
    a "confidence" key in Table.parsing_report alongside the existing
    accuracy / whitespace / page / order. Suitable for production
    filtering. The whole parsing_report schema is now documented in the
    property docstring. (#739)
  • per_page parameter on read_pdf(..., per_page={...}) — apply
    per-page kwarg overrides (including flavor) on top of the global
    kwargs. Useful for multi-layout PDFs where some pages need different
    table_areas / columns / flavor than the rest. Concept originally
    proposed by @sverma25 in #41. (#41)
  • strip_text= now accepts a list/tuple of substrings alongside the
    long-standing per-character str form. strip_text=["[1]", "[2]"]
    strips those footnote markers as whole substrings;
    strip_text="[]" keeps the existing per-character behaviour. (#484)
  • replace_text parameter on read_pdf — dict of substring →
    replacement applied to every cell's text just before assignment.
    Unlike strip_text (which can only remove), replace_text rewrites
    with arbitrary text — useful for collapsing soft-broken words
    ({" \n": " "}), normalising abbreviations, or rewriting unit
    names. Keys are matched as literal substrings; when several keys
    could match at the same position the longest one wins. (#482)
  • read_pdf accepts bytes and binary file-like objects as
    filepath, in addition to str/Path and URLs. io.BytesIO, an open
    "rb" handle, requests response .raw, etc. all work. The bytes
    are spilled to a temp file once (so the Lattice OpenCV image
    conversion keeps working) and cleaned up on context-manager exit.
    Long-standing requests #170, #245. (#270)
  • cpu_count parameter on read_pdf(..., parallel=True, cpu_count=N)
    and PDFHandler.parse(...) — caps the worker count when running in
    parallel. Defaults to all cores; clamped to
    [1, multiprocessing.cpu_count()]. (#712)
  • camelot-py CLI alias matching the PyPI package name —
    uvx camelot-py … works directly without the --from camelot-py
    prefix. (#738)
  • --format is now optional in the CLI: when omitted, the format is
    inferred from the --output extension (.csv, .xlsx, .html,
    .json, .md, .sqlite, etc.). (#738)
  • Table.to_excel defaults to index=False, header=False (under
    Breaking but worth calling out under Added too — most users will
    prefer the new shape).
  • Python 3.14 stable + 3.15 experimental rows added to the CI matrix.
    Wheels for both Pythons install correctly on Linux/macOS/Windows. (#706)

Changed

  • Default lattice engine is now "combined" (was "raster"); the
    transient engine="auto" introduced earlier in the 2.0 cycle was removed.
    Existing flavor="lattice" calls pick up combined automatically and it is
    never worse than raster. engine stays lattice-only and is rejected for the
    text-based flavors. (#803)
  • flavor="hybrid" runs its lattice half with engine="combined" too
    (was "raster"). With the completeness gating this lifts hybrid on ruled
    documents — in-repo ICDAR-2013 TEDS 0.724→0.806, row 0.417→0.659,
    col 0.689→0.868. (#807)

Changed (performance)

  • Lattice raster render skips the PNG round-trip (~20-26% faster). The
    page was rendered to a PIL image, saved to a PNG, then immediately
    cv2.imread-ed back
    — the encode alone was ~a quarter of the raster
    time. The Lattice engine now renders straight to an in-memory BGR array
    (ImageConversionBackend.to_array, pdfium-native; other backends fall
    back to convert+imread). Output is byte-identical (PNG was lossless).
    (#40)

  • text_in_bbox ≈ 30× faster on busy lattice pages. The original
    O(n³) duplicate-discard pass became O(n²) in #718, then the whole
    function was NumPy-vectorised in #731 — a 3-4× win on top of #718 on
    realistic 50-500-text-line bboxes. Memory-safe fallback at n > 1500.

  • get_table_index 3-13×. #727 collapsed the row scan + best-overlap
    tracking, #733 added a lazy NumPy + bisect row-band lookup
    (O(log rows)) plus per-table caches on Table (_rows_np,
    _cols_np, _rows_disjoint).

  • read_pdf opens the PDF once per call instead of twice. Page
    resolution is deferred until the parse already has the playa handle
    open. Doubles throughput on workloads that loop over many short PDFs.
    (#732)

  • random_string 4× (#718) and compute_whitespace cleanup (#727) —
    small, mostly readability.

  • A bench/ directory now ships a couple of standalone microbenchmarks
    (bench_get_table_index.py) and a negative-result bench
    (bench_negative_results.py) documenting cases where NumPy did not
    ...

Read more

v2.0.0rc1

v2.0.0rc1 Pre-release
Pre-release

Choose a tag to compare

@bosd bosd released this 25 May 13:15
c227afd

First release candidate for Camelot 2.0 — please test and report issues before the final 2.0.0.

Highlights

  • New PDF backend — pypdf + pdfminer.six → playa-pdf: smaller install, accurate encrypted-PDF handling, faster hot paths.
  • Optional neural flavor="ml" (Table Transformer) for borderless tables, with optional OCR for scanned / image-only PDFs — pip install "camelot-py[ml,ocr]". Structure from the model, text from the PDF (no hallucinated values).
  • engine="combined" (default) and render-free engine="vector" lattice detection; flavor="auto" per-page routing; flavor="hybrid".
  • Performance — lattice render skips the PNG round-trip, get_table_index/text_in_bbox vectorised, one PDF open per call.
  • Quality-of-life: Table.confidence, TableList.filter()/stack_contiguous(), per_page=, replace_text=, bytes/file-like input.

Upgrading from 1.0.x

See the migration guide for breaking changes (Python 3.10+, line_scale 40→15, to_excel defaults, default engine="combined", …). Full details in CHANGELOG.md.

Install

pip install --pre camelot-py==2.0.0rc1

v1.0.9

Choose a tag to compare

@github-actions github-actions released this 10 Aug 18:14

Changes

👷 Continuous Integration

v1.0.8

Choose a tag to compare

@github-actions github-actions released this 10 Aug 18:09

Changes

👷 Continuous Integration

v1.0.7

Choose a tag to compare

@github-actions github-actions released this 10 Aug 18:00

Changes

👷 Continuous Integration

v1.0.6

Choose a tag to compare

@github-actions github-actions released this 10 Aug 17:52

Changes

🚨 Testing

👷 Continuous Integration

📦 Dependencies

v1.0.4

Choose a tag to compare

@bosd bosd released this 10 Aug 17:08
"Fixup workflow, only upload files pypi can handle"

v1.0.3

Choose a tag to compare

@bosd bosd released this 10 Aug 16:53
Release 1.0.3

v1.0.2

Choose a tag to compare

@github-actions github-actions released this 10 Aug 17:34

Changes

v1.0.1

Choose a tag to compare

@github-actions github-actions released this 09 Aug 20:19

Changes

🪲 Fixes

📚 Documentation

📦 Dependencies