parseur.document

Attributes

PENDING_STATUSES
FINAL_STATUSES
FAILED_STATUSES
POLL_INTERVAL
MAX_WAIT

Classes

DocumentOrderKey	Enumeration of supported document sorting keys.
Document	Document resource providing class-based API access.

Module Contents

parseur.document.PENDING_STATUSES

parseur.document.FINAL_STATUSES

parseur.document.FAILED_STATUSES

parseur.document.POLL_INTERVAL = 5

parseur.document.MAX_WAIT = 600

class parseur.document.DocumentOrderKey

Bases: str, enum.Enum

Enumeration of supported document sorting keys.

Used with the order_by parameter to specify sorting in list_documents and yield_documents.

Members:

• NAME: Sort by document name.

• CREATED: Sort by created/received date.

• PROCESSED: Sort by processed date.

• STATUS: Sort by document status.

NAME = 'name'

CREATED = 'created'

PROCESSED = 'processed'

STATUS = 'status'

class parseur.document.Document

Document resource providing class-based API access.

classmethod from_response(data: Dict) → Dict

Validate and deserialize a single document dict.

classmethod log_from_response(data: Dict) → Dict

Validate and deserialize a single document log dict.

classmethod upload_from_response(data: Dict) → Dict

Validate and deserialize a document upload response dict.

classmethod notifications_from_response(data: Dict) → Dict

Deserialize the notification_set returned by async actions.

Asynchronous endpoints (reprocess, copy, split, reverse_split) reply with {"notification_set": {<level>: [messages]}} rather than a document; this extracts and validates that inner mapping.

classmethod iter(mailbox_id: int, *, search: str | None = None, order_by: DocumentOrderKey | None = None, ascending: bool = True, received_after: datetime.datetime | None = None, received_before: datetime.datetime | None = None, with_result: bool = False, api_key: str | None = None) → Iterable[Dict]

Yield all documents in a mailbox with pagination and filtering.

Parameters:

• mailbox_id – The mailbox ID to retrieve documents from.

• search (str) –

  Search string to filter documents. The search query parameter searches the following properties:

  • document id (exact match)

  • document name

  • template name

  • from, to, cc, and bcc email addresses

  • document metadata header

• order_by (DocumentOrderKey) – Enum value specifying the sorting field.

• ascending (bool) – Whether to sort in ascending order (True) or descending order (False).

• received_after (datetime.datetime) – Filter for documents received after this date (converted to UTC YYYY-MM-DD).

• received_before (datetime.datetime) – Filter for documents received before this date (converted to UTC YYYY-MM-DD).

• with_result (bool) – Whether to include the parsed result in the returned documents.

• api_key – Optional API key overriding the global one for this call.

Yield dict:

Each yielded dictionary represents a document.

classmethod list(mailbox_id: int, *, search: str | None = None, order_by: DocumentOrderKey | None = None, ascending: bool = True, received_after: datetime.datetime | None = None, received_before: datetime.datetime | None = None, with_result: bool = False, api_key: str | None = None) → List[Dict]

classmethod retrieve(document_id: str, *, api_key: str | None = None) → Dict

Retrieve document details, deserialized.

classmethod reprocess(document_id: str, *, api_key: str | None = None) → Dict

Re-run parsing on a document.

Asynchronous: the API queues the work and returns a notification_set ({<level>: [messages]}), not the document. Poll with wait() or retrieve() to observe the result.

classmethod skip(document_id: str, *, api_key: str | None = None) → Dict

Mark a document as skipped and return the updated document.

classmethod copy(document_id: str, target_mailbox_id: int, *, api_key: str | None = None) → Dict

Copy a document into another mailbox.

Asynchronous: the new document is created in the background, so the API returns a notification_set ({<level>: [messages]}), not a document.

classmethod split(document_id: str, *, api_key: str | None = None) → Dict

Split a multi-page document following the mailbox’s split settings.

Asynchronous: returns a notification_set ({<level>: [messages]}). The mailbox must have at least one splitting method enabled and the document must be splittable, otherwise the API responds with an error.

classmethod reverse_split(document_id: str, *, api_key: str | None = None) → Dict

Undo a previous split of a document.

Asynchronous: returns a notification_set ({<level>: [messages]}). Only valid on a document that was split.

classmethod logs(document_id: str, *, api_key: str | None = None) → List[Dict]

classmethod delete(document_id: str, *, api_key: str | None = None) → bool

classmethod upload_file(mailbox_id: int, file_path: str, *, api_key: str | None = None) → Dict

Upload a local file to a mailbox.

The file is read from the filesystem of the machine running this code (for an MCP server, that is the server’s machine — usually the same as the client when launched locally by Claude Desktop). ~ is expanded.

Raises:

FileNotFoundError – If no readable file exists at file_path.

classmethod batch_upload_files(file_paths: List[str], mailbox_id: int, *, api_key: str | None = None) → Iterable[Dict]

classmethod upload_folder(mailbox_id: int, folder_path: str, *, api_key: str | None = None) → Iterable[Dict]

classmethod upload_text(recipient: str, subject: str, sender: str | None = None, body_html: str | None = None, body_plain: str | None = None, *, api_key: str | None = None) → Dict

static _uploaded_document_id(upload: Dict) → str

Extract the document id from an upload response.

upload_text returns it as DocumentID; file uploads return it as the first entry of attachments.

classmethod wait(document_id: str, *, api_key: str | None = None, on_poll=None) → Dict

Poll a document until it reaches a final (non-pending) status.

A document is still pending while its status is INCOMING, ANALYZING or PROGRESS; any other status (PARSEDOK, PARSEDKO, EXPORTKO, …) is considered final. The cadence (POLL_INTERVAL = 5s) and budget (MAX_WAIT = 10 min) are fixed.

Parameters:

• document_id – ID of the document to poll.

• api_key – Optional API key overriding the global one for this call.

• on_poll – Optional callback on_poll(elapsed_seconds, status) invoked after every status check (e.g. to render progress).

Returns:

The document once it reaches a final status.

Raises:

TimeoutError – If still pending after MAX_WAIT seconds.

classmethod upload_file_and_wait(mailbox_id: int, file_path: str, *, api_key: str | None = None, on_poll=None) → Dict

Upload a file and block until the document reaches a final status.

Returns:

The processed document.

Raises:

TimeoutError – If processing does not finish within MAX_WAIT.

classmethod upload_text_and_wait(recipient: str, subject: str, sender: str | None = None, body_html: str | None = None, body_plain: str | None = None, *, api_key: str | None = None, on_poll=None) → Dict

Upload text/email content and block until the document is final.

Returns:

The processed document.

Raises:

TimeoutError – If processing does not finish within MAX_WAIT.