✨ Use objects for custom doc fields

Author: ianardee

README.md

@@ -17,10 +17,10 @@ Finally, Python away!
 ```python
 from mindee import Client
 
-# Init a new client and configure the Invoice API
-mindee_client = Client(api_key="my-api-key").config_invoice()
+# Init a new client
+mindee_client = Client(api_key="my-api-key")
 
-# Load a file from disk and parse it
+# Load a file from disk and parse it as an invoice
 api_response = mindee_client.doc_from_path("/path/to/the/invoice.pdf").parse("invoice")
 
 # Print a brief summary of the parsed data
@@ -32,8 +32,8 @@ print(api_response.document)
 ```python
 from mindee import Client
 
-# Init a new client and configure your custom document
-mindee_client = Client(api_key="my-api-key").config_custom_doc(
+# Init a new client and add your custom endpoint (document)
+mindee_client = Client(api_key="my-api-key").add_endpoint(
     account_name="john",
     endpoint_name="wnine",
 )

mindee/__main__.py

@@ -30,22 +30,6 @@
 }
 
 
-def _ots_client(args: Namespace, info: dict):
-    client = Client(api_key=args.api_key, raise_on_error=args.raise_on_error)
-    func = getattr(client, f"config_{info['doc_type']}")
-    func()
-    return client
-
-
-def _custom_client(args: Namespace):
-    client = Client(api_key=args.api_key, raise_on_error=args.raise_on_error)
-    client.config_custom_doc(
-        endpoint_name=args.doc_type,
-        account_name=args.username,
-    )
-    return client
-
-
 def _get_input_doc(client, args) -> DocumentClient:
     if args.input_type == "file":
         with open(args.path, "rb", buffering=30) as file_handle:
@@ -61,12 +45,15 @@ def _get_input_doc(client, args) -> DocumentClient:
 
 def call_endpoint(args: Namespace):
     """Call the endpoint given passed arguments."""
+    client = Client(api_key=args.api_key, raise_on_error=args.raise_on_error)
     if args.product_name == "custom":
-        client = _custom_client(args)
+        client.add_endpoint(
+            endpoint_name=args.doc_type,
+            account_name=args.username,
+        )
         doc_type = args.doc_type
     else:
         info = DOCUMENTS[args.product_name]
-        client = _ots_client(args, info)
         doc_type = info["doc_type"]
 
     input_doc = _get_input_doc(client, args)

mindee/client.py

@@ -8,15 +8,7 @@
 from mindee.documents.invoice import Invoice
 from mindee.documents.passport import Passport
 from mindee.documents.receipt import Receipt
-from mindee.endpoints import (
-    OTS_OWNER,
-    BankCheckEndpoint,
-    CustomEndpoint,
-    HTTPException,
-    InvoiceEndpoint,
-    PassportEndpoint,
-    ReceiptEndpoint,
-)
+from mindee.endpoints import OTS_OWNER, CustomEndpoint, HTTPException, StandardEndpoint
 from mindee.input.page_options import PageOptions
 from mindee.input.sources import (
     Base64Input,
@@ -91,7 +83,7 @@ def parse(
         doc_config.check_api_keys()
         if page_options and self.input_doc.is_pdf():
             self.input_doc.process_pdf(
-                page_options.behavior,
+                page_options.operation,
                 page_options.on_min_pages,
                 page_options.page_indexes,
             )
@@ -100,7 +92,7 @@ def parse(
     def _make_request(
         self, doc_config: DocumentConfig, include_words: bool, close_file: bool
     ) -> PredictResponse:
-        response = doc_config.constructor.request(
+        response = doc_config.document_class.request(
             doc_config.endpoints,
             self.input_doc,
             include_words=include_words,
@@ -147,15 +139,68 @@ def __init__(self, api_key: str = "", raise_on_error: bool = True):
         self._doc_configs: Dict[tuple, DocumentConfig] = {}
         self.raise_on_error = raise_on_error
         self.api_key = api_key
-
-    def config_custom_doc(
+        self._init_default_endpoints()
+
+    def _init_default_endpoints(self) -> None:
+        self._doc_configs = {
+            (OTS_OWNER, "invoice"): DocumentConfig(
+                document_type="invoice",
+                constructor=Invoice,
+                endpoints=[
+                    StandardEndpoint(
+                        url_name="invoices", version="3", api_key=self.api_key
+                    )
+                ],
+            ),
+            (OTS_OWNER, "receipt"): DocumentConfig(
+                document_type="receipt",
+                constructor=Receipt,
+                endpoints=[
+                    StandardEndpoint(
+                        url_name="expense_receipts", version="3", api_key=self.api_key
+                    )
+                ],
+            ),
+            (OTS_OWNER, "financial_doc"): DocumentConfig(
+                document_type="financial_doc",
+                constructor=FinancialDocument,
+                endpoints=[
+                    StandardEndpoint(
+                        url_name="invoices", version="3", api_key=self.api_key
+                    ),
+                    StandardEndpoint(
+                        url_name="expense_receipts", version="3", api_key=self.api_key
+                    ),
+                ],
+            ),
+            (OTS_OWNER, "passport"): DocumentConfig(
+                document_type="passport",
+                constructor=Passport,
+                endpoints=[
+                    StandardEndpoint(
+                        url_name="passport", version="1", api_key=self.api_key
+                    )
+                ],
+            ),
+            (OTS_OWNER, "bank_check"): DocumentConfig(
+                document_type="bank_check",
+                constructor=BankCheck,
+                endpoints=[
+                    StandardEndpoint(
+                        url_name="bank_check", version="1", api_key=self.api_key
+                    )
+                ],
+            ),
+        }
+
+    def add_endpoint(
         self,
         account_name: str,
         endpoint_name: str,
         version: str = "1",
     ) -> "Client":
         """
-        Configure a custom document using the Mindee API Builder.
+        Add a custom endpoint, created using the Mindee API Builder.
 
         :param endpoint_name: The "API name" field in the "Settings" page of the API Builder
         :param account_name: Your organization's username on the API Builder
@@ -176,61 +221,6 @@ def config_custom_doc(
         )
         return self
 
-    def config_invoice(self) -> "Client":
-        """Configure a Mindee Invoice document."""
-        config = DocumentConfig(
-            document_type="invoice",
-            constructor=Invoice,
-            endpoints=[InvoiceEndpoint(api_key=self.api_key)],
-        )
-        self._doc_configs[(OTS_OWNER, "invoice")] = config
-        return self
-
-    def config_receipt(self) -> "Client":
-        """Configure a Mindee Expense Receipts document."""
-        config = DocumentConfig(
-            document_type="receipt",
-            constructor=Receipt,
-            endpoints=[ReceiptEndpoint(api_key=self.api_key)],
-        )
-        self._doc_configs[(OTS_OWNER, "receipt")] = config
-        return self
-
-    def config_financial_doc(
-        self,
-    ) -> "Client":
-        """Configure a Mindee Financial document. Uses Invoice and Expense Receipt internally."""
-        config = DocumentConfig(
-            document_type="financial_doc",
-            constructor=FinancialDocument,
-            endpoints=[
-                InvoiceEndpoint(api_key=self.api_key),
-                ReceiptEndpoint(api_key=self.api_key),
-            ],
-        )
-        self._doc_configs[(OTS_OWNER, "financial_doc")] = config
-        return self
-
-    def config_passport(self) -> "Client":
-        """Configure a Mindee Passport document."""
-        config = DocumentConfig(
-            document_type="passport",
-            constructor=Passport,
-            endpoints=[PassportEndpoint(api_key=self.api_key)],
-        )
-        self._doc_configs[(OTS_OWNER, "passport")] = config
-        return self
-
-    def config_bank_check(self) -> "Client":
-        """Configure a Mindee Bank check document."""
-        config = DocumentConfig(
-            document_type="bank_check",
-            constructor=BankCheck,
-            endpoints=[BankCheckEndpoint(api_key=self.api_key)],
-        )
-        self._doc_configs[(OTS_OWNER, "bank_check")] = config
-        return self
-
     def doc_from_path(
         self,
         input_path: str,

mindee/document_config.py

@@ -7,7 +7,7 @@
 class DocumentConfig:
     document_type: str
     endpoints: List[Endpoint]
-    constructor: TypeDocument
+    document_class: TypeDocument
 
     def __init__(
         self,
@@ -16,7 +16,7 @@ def __init__(
         endpoints: List[Endpoint],
     ):
         self.document_type = document_type
-        self.constructor = constructor
+        self.document_class = constructor
         self.endpoints = endpoints
 
     def check_api_keys(self) -> None:
@@ -25,7 +25,7 @@ def check_api_keys(self) -> None:
             if not endpoint.api_key:
                 raise RuntimeError(
                     (
-                        f"Missing API key for '{endpoint.key_name}',"
+                        f"Missing API key for '{self.document_type}',"
                         "check your Client configuration.\n"
                         "You can set this using the "
                         f"'{MINDEE_API_KEY_NAME}' environment variable."

mindee/documents/bank_check.py

@@ -1,29 +1,29 @@
 from typing import List, Optional
 
 from mindee.documents.base import Document, TypeApiPrediction
-from mindee.fields.amount import Amount
-from mindee.fields.base import Field
-from mindee.fields.date import Date
+from mindee.fields.amount import AmountField
+from mindee.fields.date import DateField
 from mindee.fields.orientation import Orientation
 from mindee.fields.position import Position
+from mindee.fields.text import TextField
 
 
 class BankCheck(Document):
-    date: Date
+    date: DateField
     """Date the check was issued"""
-    amount: Amount
+    amount: AmountField
     """Total including taxes"""
-    payees: List[Field]
+    payees: List[TextField]
     """List of payees (full name or company name)"""
-    check_number: Field
+    check_number: TextField
     """Check number"""
-    routing_number: Field
+    routing_number: TextField
     """Payer's bank account routing number"""
-    account_number: Field
+    account_number: TextField
     """Payer's bank account number"""
-    check_position: Field
+    check_position: Position
     """Check's position in the image"""
-    signatures_positions: List[Field]
+    signatures_positions: List[Position]
     """Signatures' positions in the image"""
     # orientation is only present on page-level, not document-level
     orientation: Optional[Orientation] = None
@@ -62,13 +62,15 @@ def _build_from_api_prediction(
         if page_n is not None:
             self.orientation = Orientation(api_prediction["orientation"], page_n=page_n)
 
-        self.routing_number = Field(api_prediction["routing_number"], page_n=page_n)
-        self.account_number = Field(api_prediction["account_number"], page_n=page_n)
-        self.check_number = Field(api_prediction["check_number"], page_n=page_n)
-        self.date = Date(api_prediction["date"], "value", page_n=page_n)
-        self.amount = Amount(api_prediction["amount"], value_key="value", page_n=page_n)
+        self.routing_number = TextField(api_prediction["routing_number"], page_n=page_n)
+        self.account_number = TextField(api_prediction["account_number"], page_n=page_n)
+        self.check_number = TextField(api_prediction["check_number"], page_n=page_n)
+        self.date = DateField(api_prediction["date"], "value", page_n=page_n)
+        self.amount = AmountField(
+            api_prediction["amount"], value_key="value", page_n=page_n
+        )
         self.payees = [
-            Field(payee, page_n=page_n) for payee in api_prediction["payees"]
+            TextField(payee, page_n=page_n) for payee in api_prediction["payees"]
         ]
         self.check_position = Position(api_prediction["check_position"], page_n=page_n)
         self.signatures_positions = [

mindee/documents/custom_document.py

@@ -1,12 +1,13 @@
 from typing import Dict, Optional
 
 from mindee.documents.base import Document, TypeApiPrediction
+from mindee.fields.api_builder import ClassificationField, ListField
 
 
 class CustomDocument(Document):
-    fields: Dict[str, dict]
+    fields: Dict[str, ListField]
     """Dictionary of all fields in the document"""
-    classifications: Dict[str, dict]
+    classifications: Dict[str, ClassificationField]
     """Dictionary of all classifications in the document"""
 
     def __init__(
@@ -46,24 +47,20 @@ def _build_from_api_prediction(
             field = api_prediction[field_name]
             # Only classifications have the 'value' attribute.
             if "value" in field:
-                self.classifications[field_name] = field
+                self.classifications[field_name] = ClassificationField(prediction=field)
             # Only value lists have the 'values' attribute.
             elif "values" in field:
                 field["page_n"] = page_n
-                self.fields[field_name] = field
-            setattr(self, field_name, field)
+                self.fields[field_name] = ListField(prediction=field, page_n=page_n)
 
     def __str__(self) -> str:
         custom_doc_str = (
             f"----- {self.type} -----\nFilename: {self.filename or ''}".rstrip() + "\n"
         )
-        for name, info in self.classifications.items():
-            custom_doc_str += f"{name}: {info['value']}\n"
-        for name, info in self.fields.items():
-            custom_doc_str += "%s: %s\n" % (
-                name,
-                " ".join([value["content"] for value in info["values"]]),
-            )
+        for class_name, class_info in self.classifications.items():
+            custom_doc_str += f"{class_name}: {class_info}\n"
+        for field_name, field_info in self.fields.items():
+            custom_doc_str += f"{field_name}: {field_info}\n"
         custom_doc_str += "----------------------"
         return custom_doc_str