PEP 561 typing support and pyproject.toml packaging

pyproject.toml

@@ -0,0 +1,90 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "amazon-textract-textractor"
+version = "1.10.0"
+description = "A package to use AWS Textract services."
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.10,<3.15"
+keywords = ["amazon", "textract", "aws", "ocr", "document"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Typing :: Typed",
+]
+dependencies = [
+    "amazon-textract-caller>=0.2.4,<1",
+    "Pillow>=12.3.0",
+    "tabulate>=0.9,<0.10",
+    "XlsxWriter>=3.0,<4",
+    "rapidfuzz>=3.9.6,<4",
+    "PyYAML>=5.1,<7",
+]
+
+[dependency-groups]
+test = [
+    "pytest",
+    "pytest-cov",
+]
+docs = [
+    "sphinx",
+    "sphinx-rtd-theme",
+	"jupyterlab",
+	"pandas",
+	"pdf2image>=1.16,<1.17",
+	"pytest",
+	"Sphinx>=5.1,<5.2",
+	"nbsphinx>=0.8,<0.9",
+	"sphinx-rtd-theme>=2.0,<3.0",
+	"sphinx-argparse>=0.5.1",
+	"sphinxcontrib-applehelp>=1.0,<1.1",
+	"sphinxcontrib-devhelp>=1.0,<1.1",
+	"sphinxcontrib-htmlhelp>=2.0,<2.1",
+	"sphinxcontrib-jsmath>=1.0,<1.1",
+	"sphinxcontrib-qthelp>=1.0,<1.1",
+	"sphinxcontrib-serializinghtml>=1.1,<1.2",
+]
+dev = [
+	{ include-group = "test" },
+	{ include-group = "docs" },
+    "jupyterlab",
+    "pandas",
+    "pdf2image>=1.16,<1.17",
+    "pytest",
+    "lxml",
+    "sentence-transformers>=5.6.0",
+]
+
+[project.optional-dependencies]
+pandas = ["pandas"]
+pdf = ["pdf2image>=1.16,<1.17"]
+pdfium = ["pypdfium2"]
+torch = ["sentence-transformers>=5.6.0"]
+
+[project.urls]
+Homepage = "https://github.com/aws-samples/amazon-textract-textractor"
+
+[project.scripts]
+textractor = "textractor.cli.cli:textractor_cli"
+
+[tool.setuptools]
+include-package-data = true
+
+[tool.setuptools.packages.find]
+exclude = ["docs*", "tests*"]
+
+[tool.setuptools.package-data]
+textractor = ["py.typed"]
+
+[tool.flake8]
+max-line-length = 120
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

tests/test_typing_packaging.py

@@ -0,0 +1,15 @@
+from pathlib import Path
+
+
+def test_py_typed_marker_exists():
+    marker = Path(__file__).resolve().parents[1] / "textractor" / "py.typed"
+    assert marker.is_file()
+
+
+def test_public_api_exports():
+    import textractor
+
+    assert textractor.__all__ == ["Document", "LazyDocument", "Textractor"]
+    assert textractor.Textractor is not None
+    assert textractor.Document is not None
+    assert textractor.LazyDocument is not None

textractor/__init__.py

@@ -1,3 +1,7 @@
 __version__ = "1.10.0"
 
+from .entities.document import Document
+from .entities.lazy_document import LazyDocument
 from .textractor import Textractor
+
+__all__ = ["Document", "LazyDocument", "Textractor"]

textractor/entities/lazy_document.py

@@ -6,6 +6,7 @@
 from typing import Any
 
 from textractor.entities.document import Document
+from textractor.entities.page import Page
 from textractor.parsers.response_parser import parse
 from textractor.data.constants import TextractAPI
 from textractor.utils.results_utils import results_exist, get_full_json_from_output_config
@@ -91,6 +92,11 @@ def document(self) -> Document:
         """
         return object.__getattribute__(self, "_document")
 
+    @property
+    def pages(self) -> list[Page]:
+        """Document pages; loads the Textract job result on first access."""
+        return self.__getattr__("pages")
+
     def __getattr__(self, __name: str) -> Any:
         """Proxy that gets the Document result when a document property is
         accessed. This a blocking call.

textractor/textractor.py

@@ -25,7 +25,7 @@
 from botocore.config import Config
 from PIL import Image
 from copy import deepcopy
-from typing import List, Union
+from typing import List, Sequence, Union
 from textractcaller import (
     call_textract,
     call_textract_analyzeid,
@@ -55,6 +55,9 @@
 
 logger = logging.getLogger(__name__)
 
+FileSource = str | bytes | Image.Image
+TextractFeatureInput = TextractFeatures | Sequence[TextractFeatures]
+
 try:
     try:
         import pypdfium2
@@ -87,10 +90,10 @@ class Textractor:
 
     def __init__(
         self,
-        profile_name: str = None,
-        region_name: str = None,
+        profile_name: str | None = None,
+        region_name: str | None = None,
         kms_key_id: str = "",
-        config: Config = None,
+        config: Config | None = None,
     ):
         self.profile_name = profile_name
         self.region_name = region_name
@@ -161,7 +164,7 @@ def _get_document_images_from_path(self, filepath: str) -> List[Image.Image]:
         return images
 
     def detect_document_text(
-        self, file_source, save_image: bool = True
+        self, file_source: FileSource, save_image: bool = True
     ) -> Document:
         """
         Make a call to the SYNC DetectDocumentText API, implicitly parses the response and produces a :class:`Document` object.
@@ -346,9 +349,9 @@ def start_document_text_detection(
 
     def analyze_document(
         self,
-        file_source,
-        features,
-        queries: Union[QueriesConfig, List[Query], List[str]] = None,
+        file_source: FileSource,
+        features: TextractFeatureInput,
+        queries: Union[QueriesConfig, List[Query], List[str]] | None = None,
         save_image: bool = True,
     ) -> Document:
         """
@@ -459,11 +462,11 @@ def analyze_document(
 
     def start_document_analysis(
         self,
-        file_source: Union[str, bytes, Image.Image],
-        features,
+        file_source: FileSource,
+        features: TextractFeatureInput,
         s3_output_path: str = "",
         s3_upload_path: str = "",
-        queries: Union[QueriesConfig, List[Query], List[str]] = None,
+        queries: Union[QueriesConfig, List[Query], List[str]] | None = None,
         client_request_token: str = "",
         job_tag: str = "",
         save_image: bool = True,