mindee-lite 5.0.0__py3-none-any.whl

docs/conf.py

@@ -0,0 +1,76 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = "Mindee Python Client"
+copyright = "2022, Mindee"
+author = "Mindee"
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx_autodoc_typehints",
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = "sphinx_rtd_theme"
+html_theme_options = {
+    "body_max_width": "none",
+}
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = []
+
+# A list of paths that contain extra files not directly related to the documentation.
+html_extra_path = ["extras"]
+
+
+# -- autodoc -----------------------------------------------------------------
+
+autodoc_member_order = "groupwise"
+# autodoc_class_signature = "separated" # breaks new syntaxes
+
+# Hides prepended module names wich caused some classes to overflow on the right of the screen.
+add_module_names = False
+autodoc_typehints = "description"
+autodoc_default_options = {"exclude-members": "__init__"}
+
+# -- autodoc-typehints -------------------------------------------------------
+
+typehints_defaults = "comma"
+suppress_warnings = ["ref.python"]

mindee/__init__.py

@@ -0,0 +1,53 @@
+from mindee.client_options.polling_options import PollingOptions
+from mindee.input import PageOptions
+from mindee.input.base_64_input import Base64Input
+from mindee.input.bytes_input import BytesInput
+from mindee.input.file_input import FileInput
+from mindee.input.local_input_source import LocalInputSource
+from mindee.input.local_response import LocalResponse
+from mindee.input.path_input import PathInput
+from mindee.input.url_input_source import URLInputSource
+from mindee.v1 import product
+from mindee.v2.parsing.job.job_response import JobResponse
+from mindee.v2.product.classification.classification_response import (
+    ClassificationResponse,
+)
+from mindee.v2.product.classification.params.classification_parameters import (
+    ClassificationParameters,
+)
+from mindee.v2.product.crop.crop_response import CropResponse
+from mindee.v2.product.crop.params.crop_parameters import CropParameters
+from mindee.v2.product.extraction.extraction_response import ExtractionResponse
+from mindee.v2.product.extraction.extraction_result import ExtractionResult
+from mindee.v2.product.extraction.params.extraction_parameters import (
+    ExtractionParameters,
+)
+from mindee.v2.product.ocr.ocr_response import OCRResponse
+from mindee.v2.product.ocr.params.ocr_parameters import OCRParameters
+from mindee.v2.product.split.params.split_parameters import SplitParameters
+from mindee.v2.product.split.split_response import SplitResponse
+
+__all__ = [
+    "Base64Input",
+    "BytesInput",
+    "ClassificationParameters",
+    "ClassificationResponse",
+    "CropParameters",
+    "CropResponse",
+    "ExtractionParameters",
+    "ExtractionResponse",
+    "ExtractionResult",
+    "FileInput",
+    "JobResponse",
+    "LocalInputSource",
+    "LocalResponse",
+    "OCRParameters",
+    "OCRResponse",
+    "PageOptions",
+    "PathInput",
+    "PollingOptions",
+    "SplitParameters",
+    "SplitResponse",
+    "URLInputSource",
+    "product",
+]

mindee/__main__.py

@@ -0,0 +1,4 @@
+from mindee.cli import main
+
+if __name__ == "__main__":
+    main()

mindee/cli.py

@@ -0,0 +1,7 @@
+from mindee.v1.commands.cli_parser import MindeeParser
+
+
+def main() -> None:
+    """Run the Command Line Interface."""
+    parser = MindeeParser()
+    parser.call_parse()

mindee/client_mixin.py

@@ -0,0 +1,23 @@
+from mindee.error import MindeeClientError
+
+
+class ClientMixin:
+    """Mixin for clients V1 & V2 common static methods."""
+
+    @staticmethod
+    def _validate_async_params(
+        initial_delay_sec: float, delay_sec: float, max_retries: int
+    ) -> None:
+        min_delay = 1
+        min_initial_delay = 1
+        min_retries = 1
+        if delay_sec < min_delay:
+            raise MindeeClientError(
+                f"Cannot set auto-parsing delay to less than {min_delay} second(s)."
+            )
+        if initial_delay_sec < min_initial_delay:
+            raise MindeeClientError(
+                f"Cannot set initial parsing delay to less than {min_initial_delay} second(s)."
+            )
+        if max_retries < min_retries:
+            raise MindeeClientError(f"Cannot set retries to less than {min_retries}.")

mindee/client_options/polling_options.py

@@ -0,0 +1,19 @@
+class PollingOptions:
+    """Options for asynchronous polling."""
+
+    initial_delay_sec: float
+    """Initial delay before the first polling attempt."""
+    delay_sec: float
+    """Delay between each polling attempt."""
+    max_retries: int
+    """Total number of polling attempts."""
+
+    def __init__(
+        self,
+        initial_delay_sec: float = 2,
+        delay_sec: float = 1.5,
+        max_retries: int = 80,
+    ):
+        self.initial_delay_sec = initial_delay_sec
+        self.delay_sec = delay_sec
+        self.max_retries = max_retries

mindee/dependencies/__init__.py

@@ -0,0 +1,9 @@
+from mindee.dependencies.checkers import PILLOW_AVAILABLE, PYPDFIUM2_AVAILABLE
+from mindee.dependencies.decorators import requires_pillow, requires_pypdfium2
+
+__all__ = [
+    "PILLOW_AVAILABLE",
+    "PYPDFIUM2_AVAILABLE",
+    "requires_pillow",
+    "requires_pypdfium2",
+]

mindee/dependencies/checkers.py

@@ -0,0 +1,33 @@
+from mindee.error.mindee_dependency_error import MindeeDependencyError
+
+try:
+    import PIL  # noqa: F401 #pylint: disable=unused-import
+
+    PILLOW_AVAILABLE = True
+except ImportError:
+    PILLOW_AVAILABLE = False
+
+try:
+    import pypdfium2  # noqa: F401 #pylint: disable=unused-import
+
+    PYPDFIUM2_AVAILABLE = True
+except ImportError:
+    PYPDFIUM2_AVAILABLE = False
+
+
+def require_pillow() -> None:
+    """Raises a clear error if Pillow is not installed."""
+    if not PILLOW_AVAILABLE:
+        raise MindeeDependencyError(
+            "This feature requires the 'Pillow' library. "
+            "Install it directly or run `pip install mindee` instead of `mindee-lite`."
+        )
+
+
+def require_pypdfium2() -> None:
+    """Raises a clear error if PyPDFium2 is not installed."""
+    if not PYPDFIUM2_AVAILABLE:
+        raise MindeeDependencyError(
+            "This feature requires the 'PyPDFium2' library. "
+            "Install it directly or run `pip install mindee` instead of `mindee-lite`."
+        )

mindee/dependencies/decorators.py

@@ -0,0 +1,30 @@
+import functools
+from collections.abc import Callable
+from typing import ParamSpec, TypeVar
+
+from mindee.dependencies.checkers import require_pillow, require_pypdfium2
+
+P = ParamSpec("P")
+R = TypeVar("R")
+
+
+def requires_pillow(func: Callable[P, R]) -> Callable[P, R]:
+    """Decorator to enforce Pillow availability on a function/method."""
+
+    @functools.wraps(func)
+    def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+        require_pillow()
+        return func(*args, **kwargs)
+
+    return wrapper
+
+
+def requires_pypdfium2(func: Callable[P, R]) -> Callable[P, R]:
+    """Decorator to enforce PyPDFium2 availability on a function/method."""
+
+    @functools.wraps(func)
+    def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+        require_pypdfium2()
+        return func(*args, **kwargs)
+
+    return wrapper

mindee/error/__init__.py

@@ -0,0 +1,27 @@
+from mindee.error.geometry_error import MindeeGeometryError
+from mindee.error.mimetype_error import MimeTypeError
+from mindee.error.mindee_error import (
+    MindeeClientError,
+    MindeeError,
+)
+from mindee.error.mindee_http_error import (
+    MindeeHTTPClientError,
+    MindeeHTTPError,
+    MindeeHTTPServerError,
+    handle_error,
+)
+from mindee.error.mindee_image_error import MindeeImageError
+from mindee.error.mindee_pdf_error import MindeePDFError
+
+__all__ = [
+    "MimeTypeError",
+    "MindeeClientError",
+    "MindeeError",
+    "MindeeGeometryError",
+    "MindeeHTTPClientError",
+    "MindeeHTTPError",
+    "MindeeHTTPServerError",
+    "MindeeImageError",
+    "MindeePDFError",
+    "handle_error",
+]

mindee/error/geometry_error.py

@@ -0,0 +1,2 @@
+class MindeeGeometryError(RuntimeError):
+    """An error related to geometry operations."""

mindee/error/mimetype_error.py

@@ -0,0 +1,2 @@
+class MimeTypeError(AssertionError):
+    """The MIME Type is not valid."""

mindee/error/mindee_dependency_error.py

@@ -0,0 +1,5 @@
+from mindee.error import MindeeError
+
+
+class MindeeDependencyError(MindeeError, ImportError):
+    """An exception relating to missing dependencies."""

mindee/error/mindee_error.py

@@ -0,0 +1,14 @@
+class MindeeError(RuntimeError):
+    """A generic exception relating to various HTTP errors."""
+
+
+class MindeeClientError(MindeeError):
+    """
+    An exception relating to document parsing errors.
+
+    Not to be confused with `MindeeHTTPClientError`.
+    """
+
+
+class MindeeSourceError(MindeeError):
+    """An exception relating to document loading."""

mindee/error/mindee_http_error.py

@@ -0,0 +1,115 @@
+from mindee.error.mindee_error import MindeeError
+from mindee.parsing.common.string_dict import StringDict
+
+
+class MindeeHTTPError(RuntimeError):
+    """An exception relating to HTTP calls."""
+
+    status_code: int
+    api_code: str | None
+    api_details: str | None
+    api_message: str | None
+
+    def __init__(self, http_error: StringDict, url: str, code: int) -> None:
+        """
+        Base exception for HTTP calls.
+
+        :param http_error: formatted & parsed error
+        :param url: url/endpoint the exception was raised on
+        :param code: HTTP code for the error
+        """
+        self.status_code = code
+        self.api_code = http_error.get("code", None) if "code" in http_error else None
+        self.api_details = (
+            http_error.get("details", None) if "details" in http_error else None
+        )
+        self.api_message = (
+            http_error.get("message", None) if "message" in http_error else None
+        )
+        super().__init__(
+            f"{url} {self.status_code} HTTP error: {self.api_details} - {self.api_message}"
+        )
+
+
+def create_error_obj(response: StringDict | str) -> StringDict:
+    """
+    Creates an error object based on a requests' payload.
+
+    :param response: response as sent by the server, as a dict.
+        In _very_ rare instances, this can be an html string.
+    """
+    if not isinstance(response, str):
+        if "api_request" in response and "error" in response["api_request"]:
+            return response["api_request"]["error"]
+        raise MindeeError(f"Could not build specific HTTP exception from '{response}'")
+    error_dict = {}
+    if "Maximum pdf pages" in response:
+        error_dict = {
+            "code": "TooManyPages",
+            "message": "Maximum amound of pdf pages reached.",
+            "details": response,
+        }
+    elif "Max file size is" in response:
+        error_dict = {
+            "code": "FileTooLarge",
+            "message": "Maximum file size reached.",
+            "details": response,
+        }
+    elif "Invalid file type" in response:
+        error_dict = {
+            "code": "InvalidFiletype",
+            "message": "Invalid file type.",
+            "details": response,
+        }
+    elif "Gateway timeout" in response:
+        error_dict = {
+            "code": "RequestTimeout",
+            "message": "Request timed out.",
+            "details": response,
+        }
+    elif "Too Many Requests" in response:
+        error_dict = {
+            "code": "TooManyRequests",
+            "message": "Too Many Requests.",
+            "details": response,
+        }
+    else:
+        error_dict = {
+            "code": "UnknownError",
+            "message": "Server sent back an unexpected reply.",
+            "details": response,
+        }
+    return error_dict
+
+
+class MindeeHTTPClientError(MindeeHTTPError):
+    """API Client HTTP exception."""
+
+
+class MindeeHTTPServerError(MindeeHTTPError):
+    """API Server HTTP exception."""
+
+
+def handle_error(url: str, response: StringDict) -> MindeeHTTPError:
+    """
+    Creates an appropriate HTTP error exception, based on retrieved HTTP error code.
+
+    :param url: url of the product
+    :param response: StringDict
+    """
+    error_obj = create_error_obj(response)
+    if not isinstance(response, str) and (  # type: ignore
+        "status_code" in response
+        and (
+            isinstance(response["status_code"], int)
+            or response["status_code"].isdigit()
+        )
+    ):
+        code = int(response["status_code"])
+    else:
+        code = 500
+    if 400 <= code <= 499:
+        return MindeeHTTPClientError(error_obj, url, code)
+    if 500 <= code <= 599:
+        return MindeeHTTPServerError(error_obj, url, code)
+    return MindeeHTTPError(error_obj, url, code)

mindee/error/mindee_image_error.py

@@ -0,0 +1,2 @@
+class MindeeImageError(RuntimeError):
+    """An exception relating to errors during image operations."""

mindee/error/mindee_pdf_error.py

@@ -0,0 +1,2 @@
+class MindeePDFError(RuntimeError):
+    """An exception relating to errors during PDF operations."""

mindee/geometry/__init__.py

@@ -0,0 +1,31 @@
+from mindee.geometry.bbox import BBox, get_bbox
+from mindee.geometry.minmax import MinMax, get_min_max_x, get_min_max_y
+from mindee.geometry.point import Point, Points
+from mindee.geometry.polygon import (
+    Polygon,
+    merge_polygons,
+)
+from mindee.geometry.polygon_utils import get_centroid, is_point_in_x, is_point_in_y
+from mindee.geometry.quadrilateral import (
+    Quadrilateral,
+    get_bounding_box,
+    quadrilateral_from_prediction,
+)
+
+__all__ = [
+    "BBox",
+    "MinMax",
+    "Point",
+    "Points",
+    "Polygon",
+    "Quadrilateral",
+    "get_bbox",
+    "get_bounding_box",
+    "get_centroid",
+    "get_min_max_x",
+    "get_min_max_y",
+    "is_point_in_x",
+    "is_point_in_y",
+    "merge_polygons",
+    "quadrilateral_from_prediction",
+]

mindee/geometry/bbox.py

@@ -0,0 +1,73 @@
+from typing import NamedTuple
+
+from mindee.geometry.point import Points
+
+
+class BBox(NamedTuple):
+    """Contains exactly 4 coordinates."""
+
+    x_min: float
+    """Minimum X coordinate."""
+    y_min: float
+    """Minimum Y coordinate."""
+    x_max: float
+    """Maximum X coordinate."""
+    y_max: float
+    """Maximum Y coordinate."""
+
+    @property
+    def width(self) -> float:
+        """The width of the BBox."""
+        return self.x_max - self.x_min
+
+    @property
+    def height(self) -> float:
+        """The height of the BBox."""
+        return self.y_max - self.y_min
+
+    @property
+    def area(self) -> float:
+        """The area of the BBox."""
+        return self.width * self.height
+
+
+def get_bbox(points: Points) -> BBox:
+    """
+    Given a sequence of points, calculate a bbox that encompasses all points.
+
+    :param points: Polygon to process.
+    :return: A bbox that encompasses all points
+    """
+    y_min = min(v[1] for v in points)
+    y_max = max(v[1] for v in points)
+    x_min = min(v[0] for v in points)
+    x_max = max(v[0] for v in points)
+    return BBox(x_min, y_min, x_max, y_max)
+
+
+def merge_bbox(bbox_1: BBox, bbox_2: BBox) -> BBox:
+    """Merges two BBox."""
+    return BBox(
+        min(bbox_1.x_min, bbox_2.x_min),
+        min(bbox_1.y_min, bbox_2.y_min),
+        max(bbox_1.x_max, bbox_2.x_max),
+        max(bbox_1.y_max, bbox_2.y_max),
+    )
+
+
+def extend_bbox(bbox: BBox, points: Points) -> BBox:
+    """
+    Given a BBox and a sequence of points, calculate the surrounding bbox that encompasses all.
+
+    :param bbox: initial BBox to extend.
+    :param points: Sequence of points to process. Accepts polygons and similar
+    """
+    all_points = []
+    for point in points:
+        all_points.append(point)
+
+    y_min = min(v[1] for v in all_points)
+    y_max = max(v[1] for v in all_points)
+    x_min = min(v[0] for v in all_points)
+    x_max = max(v[0] for v in all_points)
+    return merge_bbox(bbox, BBox(x_min, y_min, x_max, y_max))

mindee/geometry/minmax.py

@@ -0,0 +1,32 @@
+from typing import NamedTuple
+
+from mindee.geometry.point import Points
+
+
+class MinMax(NamedTuple):
+    """A set of minimum and maximum values."""
+
+    min: float
+    """Minimum"""
+    max: float
+    """Maximum"""
+
+
+def get_min_max_y(points: Points) -> MinMax:
+    """
+    Get the maximum and minimum Y value given a sequence of points.
+
+    :param points: List of points
+    """
+    y_coords = [y for _, y in points]
+    return MinMax(min=min(y_coords), max=max(y_coords))
+
+
+def get_min_max_x(points: Points) -> MinMax:
+    """
+    Get the maximum and minimum Y value given a sequence of points.
+
+    :param points: List of points
+    """
+    x_coords = [x for x, _ in points]
+    return MinMax(min=min(x_coords), max=max(x_coords))

mindee/geometry/point.py

@@ -0,0 +1,17 @@
+from collections.abc import Sequence
+from typing import NamedTuple
+
+
+class Point(NamedTuple):
+    """A relative set of coordinates (X, Y) on the document."""
+
+    x: float
+    """X coordinate"""
+    y: float
+    """Y coordinate"""
+
+    def __str__(self) -> str:
+        return f"({self.x},{self.y})"
+
+
+Points = Sequence[Point]

mindee/geometry/polygon.py

@@ -0,0 +1,76 @@
+from collections.abc import Sequence
+
+from mindee.error.geometry_error import MindeeGeometryError
+from mindee.geometry.minmax import get_min_max_x, get_min_max_y
+from mindee.geometry.point import Point
+from mindee.geometry.polygon_utils import get_centroid, is_point_in_x, is_point_in_y
+
+
+class Polygon(list[Point]):
+    """
+    Contains any number of vertex coordinates (Points).
+
+    Inherits from base class ``list`` so is compatible with type ``Points``.
+    """
+
+    def __init__(self, vertices: list | None = None):
+        # we should NOT allow the creation of invalid polygons, but it would be a breaking change
+        if not vertices:
+            vertices = []
+        else:
+            vertices = [Point(point[0], point[1]) for point in vertices]
+        super().__init__(vertices)
+
+    def _raise_if_invalid(self) -> None:
+        if len(self) < 3:
+            raise MindeeGeometryError("A polygon must have at least 3 vertices")
+
+    @property
+    def centroid(self) -> Point:
+        """The central point (centroid) of the polygon."""
+        self._raise_if_invalid()
+        return get_centroid(self)
+
+    def is_point_in_x(self, point: Point) -> bool:
+        """
+        Determine if the Point is in the Polygon's X-axis.
+
+        :param point: Point to compare
+        """
+        self._raise_if_invalid()
+        min_x, max_x = get_min_max_x(self)
+        return is_point_in_x(point, min_x, max_x)
+
+    def is_point_in_y(self, point: Point) -> bool:
+        """
+        Determine if the Point is in the Polygon's Y-axis.
+
+        :param point: Point to compare
+        """
+        self._raise_if_invalid()
+        min_y, max_y = get_min_max_y(self)
+        return is_point_in_y(point, min_y, max_y)
+
+    def __str__(self):
+        return "(" + ", ".join(str(p) for p in self) + ")"
+
+
+def merge_polygons(vertices: Sequence[Polygon]) -> Polygon:
+    """
+    Given a sequence of polygons, calculate a polygon box that encompasses all polygons.
+
+    :param vertices: List of polygons
+    :return: A bounding box that encompasses all polygons
+    """
+    y_min = min(y for v in vertices for _, y in v)
+    y_max = max(y for v in vertices for _, y in v)
+    x_min = min(x for v in vertices for x, _ in v)
+    x_max = max(x for v in vertices for x, _ in v)
+    return Polygon(
+        [
+            Point(x_min, y_min),
+            Point(x_max, y_min),
+            Point(x_max, y_max),
+            Point(x_min, y_max),
+        ]
+    )