Skip to content

🖥️ How to Use

Every format follows the same pipeline: scrape → Content → parse. This page shows each supported format with working patterns.

🌐 HTML

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
from omniread import HTMLScraper, HTMLParser

class TitleParser(HTMLParser[str]):
    def parse(self) -> str:
        return self._soup.title.string

scraper = HTMLScraper()                     # httpx under the hood
content = scraper.fetch("https://example.com")

title = TitleParser(content).parse()

HTMLScraper accepts an optional client (an httpx.Client) for transport control — the test suite wires one to a mock transport.

📕 PDF

PDFs need a client to supply raw bytes before parsing:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
from pathlib import Path
from omniread import FileSystemPDFClient, PDFScraper, PDFParser

class TextPDFParser(PDFParser[str]):
    def parse(self) -> str:
        # implement your extraction logic
        return self.content.raw  # bytes, decode as needed

client = FileSystemPDFClient()
scraper = PDFScraper(client=client)
content = scraper.fetch(Path("document.pdf"))

result = TextPDFParser(content).parse()

PDFParser subclasses receive self.content and implement parse().

📊 CSV

1
2
3
4
5
6
7
8
from omniread import FileSystemCsvClient, CsvScraper, CsvParser

scraper = CsvScraper(client=FileSystemCsvClient())
content = scraper.fetch("data.csv")

parser = CsvParser(content)
for row in parser.rows():
    print(row)

CsvParser.rows() yields string rows trimmed of empties by default (skip_empty=True).

📑 XLSX

1
2
3
4
5
6
7
8
9
from omniread import FileSystemXlsxClient, XlsxScraper, XlsxParser

scraper = XlsxScraper(client=FileSystemXlsxClient())
content = scraper.fetch("statement.xlsx")

parser = XlsxParser(content)
print(parser.sheet_names)                 # e.g. ["Statement"]
rows = parser.rows(sheet="Statement")     # by name or index
all_rows = parser.parse()                 # alias for rows()

Key behaviors:

  • rows(skip_empty=False) keeps blank rows (off by default).
  • Cells render as trimmed strings; date cells convert to ISO format (2026-06-01T00:00:00).
  • rows(sheet="Missing") raises for an unknown sheet.

🔀 End-to-end flow

1
2
3
4
5
6
content = scraper.fetch(source)   # 1. acquire → Content
assert isinstance(content.raw, bytes)
assert content.content_type is not None

parser = MyParser(content)        # 2. interpret → T
result = parser.parse()