Table Extraction

The table tool reads HTML and returns a list of table objects. It is intentionally small and uses Python’s standard library HTML parser.

Supported sources

extract_tables and scrape tables accept:

• a local HTML file path

• an HTTP or HTTPS URL

Remote requests use a scrape-smith/<version> user agent and a 30-second timeout. The response charset is read from the HTTP headers when available, otherwise UTF-8 is used.

Output model

Each extracted table is represented as HtmlTable:

caption

The table caption text, or None when no caption exists.

headers

The first row when every cell in that row is a th element.

rows

Data rows as a list of string lists.

Text is normalized by collapsing whitespace inside each cell.

Header behavior

Only the first all-th row is treated as the column header row. Later rows that mix th and td cells stay in rows. This keeps row-header tables usable without silently dropping data.

Nested tables

Nested table content is ignored for the outer table result. If a cell contains a nested table, the outer cell is emitted from the outer table’s own text content.

CSV and JSON output

CSV output writes headers first when present, then rows. Multiple tables are written into one CSV file separated by a blank row.

JSON output writes a list of objects:

[
  {
    "caption": "People",
    "headers": ["Name"],
    "rows": [["Ada"]]
  }
]