Amazon Textract Textractor

Warnings

• breaking In v1.8.3, a breaking change was introduced where `LAYOUT_TABLE` elements generated for HTML output no longer share the same ID as the original `TABLE` prediction. This affects scenarios where you relied on ID matching between Textract's TABLE block and Textractor's HTML representation of the table layout.
  Fix: Review any code that processes Textractor's HTML output and relies on consistent IDs between the `TABLE` block and the `LAYOUT_TABLE` representation. Adjust your parsing logic to account for this ID divergence if necessary.
• gotcha Processing local PDF files requires additional dependencies. While `pypdfium2` is the recommended and automatically installed default for PDF support (via `pip install amazon-textract-textractor[pdf]`), the library might fall back to `pdf2image`. `pdf2image`, in turn, requires Poppler (e.g., `poppler-utils` on Linux, `brew install poppler` on macOS, or pre-compiled binaries on Windows) to be installed on the operating system, which can be a common source of installation issues.
  Fix: For local PDF processing, always install with `pip install amazon-textract-textractor[pdf]`. If you encounter errors, verify `pypdfium2` is correctly installed and working. If `pdf2image` is used, ensure Poppler is installed and correctly configured in your system's PATH.
• gotcha Textractor relies on `boto3` for AWS authentication and region configuration. Common issues arise from misconfigured AWS credentials (e.g., missing environment variables, incorrect `~/.aws/credentials` file, or IAM role not properly attached/assumed) or specifying an incorrect `region_name` when initializing `Textractor`, leading to 'Access Denied' or 'Region Not Found' errors.
  Fix: Ensure your AWS credentials are correctly configured for `boto3` (e.g., `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_DEFAULT_REGION` environment variables, or `~/.aws/credentials` file). Always specify `region_name` in the `Textractor` constructor, matching the region where your S3 buckets are located and where Textract is available.
• gotcha For larger documents (e.g., multi-page PDFs), Textract operations are asynchronous. Textractor simplifies this with `start_document_analysis` and `start_document_text_detection` methods, but under the hood, it polls for job completion. Long-running jobs can lead to timeouts or perceived hangs if not handled carefully, and `Textract` service limits should be considered.
  Fix: Increase the `polling_interval` or `timeout` parameters when calling `start_document_analysis` or `start_document_text_detection` for very large documents if you experience timeouts. Be aware of Textract service limits regarding document size and number of pages.

Install

• pip install amazon-textract-textractor Install core library
• pip install amazon-textract-textractor[pdf] Install with PDF processing support

Imports

• Textractor

  from textractor import Textractor

  The package name on PyPI is `amazon-textract-textractor`, but the top-level importable module is `textractor`.
• Document

  from textractor.data.document import Document

  The Document class holds the parsed results from Textract.

Quickstart

This quickstart demonstrates how to initialize the Textractor client, process a PDF document located in an S3 bucket using `start_document_analysis` to extract forms and tables, and then print the extracted data. Ensure your AWS credentials and default region are configured for boto3.

import os
from textractor import Textractor
from textractor.data.constants import TextractFeatures

# Ensure AWS credentials are configured (e.g., via AWS CLI, env vars, IAM roles)
# textractor uses boto3, which automatically picks up credentials.
# Example: os.environ['AWS_ACCESS_KEY_ID'] = 'YOUR_ACCESS_KEY'
# os.environ['AWS_SECRET_ACCESS_KEY'] = 'YOUR_SECRET_KEY'
# os.environ['AWS_DEFAULT_REGION'] = 'us-east-1'

# Initialize Textractor client
# Make sure the region matches your S3 bucket and Textract service availability
tractor = Textractor(region_name=os.environ.get('AWS_DEFAULT_REGION', 'us-east-1'))

# Example: Process a document from an S3 path
s3_path = "s3://amazon-textract-public-content/samples/sample.pdf"
print(f"Processing document: {s3_path}")

document = tractor.start_document_analysis(
    file_source=s3_path,
    features=[TextractFeatures.FORMS, TextractFeatures.TABLES]
)

# Print extracted forms
print("\n--- Forms ---")
for key_value in document.key_values:
    print(f"{key_value.key}: {key_value.value}")

# Print extracted tables
print("\n--- Tables ---")
for i, table in enumerate(document.tables):
    print(f"Table {i+1}:\n{table.to_csv(include_box=False)}\n")