bytedance / bytedance/pdf-parser

fix: preserve table position in page reading order

Open
#16 1 comment 1 reaction 0 assignees View on GitHub
Dominant language
Python
Stars
14
Forks
9
Avg merge
43m
Merged PRs (30d)
1

Description

## Problem

When table extraction is enabled, `_extract_page_blocks()` appends every table block to `page_blocks` before it walks the page's text and image blocks. As a result, tables are emitted before all surrounding content regardless of their vertical position on the page.

This affects current `main` at `c6478aae9ab50a13fc54c0599a0a459396c15b99` and release `0.0.5`.

## Source evidence

In `hi_pdf_parser/parser.py`:

1. `_extract_table_blocks()` is called and its results are immediately added with `page_blocks.extend(table_blocks)`.
2. Only afterward does the function iterate over `page.get_text("dict")["blocks"]` and append text/image results.
3. `_post_process_blocks()` merges adjacent content but does not sort the combined page blocks by their coordinates.

A page laid out as `introductory paragraph -> table -> concluding paragraph` therefore produces `table -> introductory paragraph -> concluding paragraph`.

## Expected behavior

Extracted blocks should preserve the page's reading order, including the relative position of tables, text, and images.

## Impact

Generated Markdown and API responses can materially change document meaning, especially when prose introduces or explains a table.

## Why there is no PR in this report

A safe fix needs a maintainer-approved ordering policy for multi-column pages, overlapping blocks, figures, and tables, plus representative regression PDFs. The current fixtures do not contain enough table-heavy layouts to validate an ordering algorithm without risking new extraction regressions.

Contributor guide

No contributing guide indexed for this repository

Research direction

Start in hi_pdf_parser/parser.py by reading _extract_page_blocks(), _extract_table_blocks(), and _post_process_blocks(), then inspect the current table-related fixtures and representative PDFs. First clarify the ordering policy for multi-column pages, overlapping blocks, figures, and tables with a maintainer. Done means text, image, and table blocks preserve reading order without introducing extraction regressions.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
backend
Issue type
Bug
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.