Python SDK: Document: text and tables
Document holds the parsed file. Check complete() and warnings() before processing everything. The methods below run locally.
Examples are fragments inside def run(ctx):. All SDK methods are synchronous; do not add await.
Obtaining the SDK object
document = ctx.documents().from_bytes('sku,price\nA-1,1250', 'report.csv')
Methods
text()format()tables()rows()pages()links()complete()warnings()sheet_names()sheet()page()matches()chunks()blocks()
text
document.text() -> str
No arguments.
Result: str.
The document text, including available Office headers, footers, and notes. PDF text stays divided by page. DOCX structure and formatting are also available through blocks().
result = document.text()
format
document.format() -> str
No arguments.
Result: str.
The detected format, such as xlsx, docx, pdf, or csv.
result = document.format()
tables
document.tables() -> list[dict[str, Any]]
No arguments.
Result: list[dict[str, Any]].
Excel sheets or Word tables, each with name and rows. Excel numbers remain numbers. Supported XLSX formulas are calculated locally with xlcalculator. External references and macros are never executed. rows() and cell() return the calculated result, formula() returns the original expression, and cached_value() returns the value saved by the document author. Use error() and calculation() to inspect calculation problems.
result = document.tables()
rows
document.rows(sheet=0) -> list[list[Any]]
| Argument | Type | Required | Purpose |
|---|---|---|---|
sheet |
int | str |
No, see the signature default | Zero-based sheet index or exact name. |
Result: list[list[Any]].
Returns rows of the selected sheet by index or name. Missing sheets return an empty array. For PDF, use pages() or text().
result = document.rows()
pages
document.pages() -> list[dict[str, Any]]
No arguments.
Result: list[dict[str, Any]].
PDF pages with number, text, and ocr. Scanned pages are recognized locally in Russian and English. One parse is limited to five image pages and 100 text pages.
result = document.pages()
links
document.links() -> list[str]
No arguments.
Result: list[str].
Links found in the document. The document service does not follow them or download external images. If needed, explicitly request an allowed link through the network SDK.
result = document.links()
complete
document.complete() -> bool
No arguments.
Result: bool.
Returns False if an extraction limit was reached. Check it before saving what should be a complete report. Limits: 20 sheets or tables, 5,000 rows, 100 columns, 50,000 cells in total, and 1 MiB of text.
result = document.complete()
warnings
document.warnings() -> list[str]
No arguments.
Result: list[str].
Codes describing parsing limits or special cases: cached formula values, older Office formats, images in Word or Excel, and OCR limits. Extraction from older DOC/XLS files is limited; embedded dicts are not executed.
result = document.warnings()
sheet_names
document.sheet_names() -> list[str]
No arguments.
Result: list[str].
Names of extracted sheets or tables in their original order. Empty for PDFs and images.
result = document.sheet_names()
sheet
document.sheet(sheet=0) -> Worksheet
| Argument | Type | Required | Purpose |
|---|---|---|---|
sheet |
int | str |
No, see the signature default | Zero-based sheet index or exact name. |
Result: Worksheet. An SDK object; use its methods instead of emitting it directly.
Select a sheet by zero-based index or exact name. Returns a Worksheet. A missing sheet raises a clear error; rows() keeps its earlier behavior and returns an empty array. Worksheet methods run locally without reading the file again.
result = document.sheet()
page
document.page(number) -> str
| Argument | Type | Required | Purpose |
|---|---|---|---|
number |
int |
Yes | One-based row/page number. |
Result: str.
Text from a PDF or raster-image page, using a one-based page number. A missing page returns an empty string; an invalid number raises an error. Use text() for Word documents.
result = document.page(2)
matches
document.matches(expression, limit=100) -> list[list[str]]
| Argument | Type | Required | Purpose |
|---|---|---|---|
expression |
str |
Yes | Python regular expression. |
limit |
int |
No, see the signature default | Maximum match count, 1–1000. |
Result: list[list[str]].
Finds matches using a Python regular expression. Returns arrays of matches and capture groups; PCRE syntax is not used.
result = document.matches(r'(\d+)', 100)
chunks
document.chunks(characters=4000, overlap=200) -> list[str]
| Argument | Type | Required | Purpose |
|---|---|---|---|
characters |
int |
No, see the signature default | Unicode chunk size: 100–16000. |
overlap |
int |
No, see the signature default | Chunk overlap: 0 to characters−1. |
Result: list[str].
Split text into Unicode-character fragments. characters must be 100–16,000, and overlap must be between 0 and characters - 1. This method does not send fragments to external services. Do not pass private fragments to analyze() or transform() without a separate data-processing policy.
result = document.chunks()
blocks
document.blocks() -> list[dict[str, Any]]
No arguments.
Result: list[dict[str, Any]].
DOCX paragraphs and table references in document order. A paragraph includes kind=paragraph, heading level, align, indent, before, after, marker, depth, and runs. Each run has text, bold, italic, underline, and point size. A kind=table block contains the table's index in tables(). Other formats return an empty array. Values are not sent to an external model.
result = document.blocks()
Errors and execution context
All calls are synchronous. Invalid arguments or malformed source data can raise ValueError/TypeError; a platform refusal or unavailable service raises RuntimeError. Missing elements/values return None or an empty collection only where explicitly documented. Do not convert every exception into an empty successful result. External-service methods are unavailable in export transformations; see transformation limits and environment.