parseur.parser_field

Classes

ParserField

Manage the fields (parser_object_set) extracted by a mailbox.

Functions

_to_write(→ List[Dict[str, Any]])	Reshape API fields to their writable form (drops read-only properties).
_fmt(→ str)	Normalize a field format (enum or string) to its string value.

Module Contents

parseur.parser_field._to_write(fields: List[Dict[str, Any]]) → List[Dict[str, Any]]

Reshape API fields to their writable form (drops read-only properties).

Dumping through ParserFieldWriteSchema emits only the writable fields and handles the nested columns of TABLE fields automatically.

parseur.parser_field._fmt(field_format: str | parseur.schemas.paserfield.FieldFormat) → str

Normalize a field format (enum or string) to its string value.

class parseur.parser_field.ParserField

Manage the fields (parser_object_set) extracted by a mailbox.

Parseur has no per-field endpoint: fields are read from the mailbox and written back via PUT /parser/{id}. These helpers read the current fields, apply a change, and persist it. All writes are validated and serialized through ParserFieldWriteSchema. A PUT upserts the submitted fields and leaves the others untouched; deletion is requested with a _destroy marker (see delete()).

classmethod list(mailbox_id: int, *, api_key: str | None = None) → List[Dict[str, Any]]

Return the parser fields currently configured on a mailbox.

classmethod _save(mailbox_id: int, fields: List[Dict[str, Any]], *, api_key: str | None = None) → List[Dict[str, Any]]

Persist a field list via the mailbox and return the result.

classmethod add(mailbox_id: int, name: str, field_format: str | parseur.schemas.paserfield.FieldFormat, *, query: str | None = None, is_required: bool | None = None, used_by_ai: bool | None = None, choice_set: List[str] | None = None, parser_object_set: List[Dict[str, Any]] | None = None, api_key: str | None = None) → List[Dict[str, Any]]

Add a new field to a mailbox, keeping the existing ones.

Parameters:

• mailbox_id – ID of the mailbox.

• name – Name of the new field.

• field_format – Field format (see FieldFormat).

• query – Optional AI extraction instructions.

• is_required – Optional required flag.

• used_by_ai – Optional flag controlling AI extraction.

• choice_set – Optional list of allowed values.

• parser_object_set – Optional nested columns (for TABLE fields).

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

Returns:

The updated list of parser fields.

classmethod update(mailbox_id: int, field_id: str, *, api_key: str | None = None, **changes: Any) → List[Dict[str, Any]]

Update a single existing field by its id.

Only the provided keys are changed; the other fields are preserved.

Parameters:

• mailbox_id – ID of the mailbox.

• field_id – ID of the field to update (e.g. “PF12345”).

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

• changes – Writable field properties to change (name, format, query, is_required, used_by_ai, choice_set, parser_object_set). field_format is accepted as an alias for format.

Returns:

The updated list of parser fields.

Raises:

ValueError – If no field with field_id exists on the mailbox.

classmethod delete(mailbox_id: int, field_id: str, *, api_key: str | None = None) → List[Dict[str, Any]]

Delete a single field from a mailbox by its id.

Sends a _destroy marker for the field; the other fields are left untouched.

Parameters:

• mailbox_id – ID of the mailbox.

• field_id – ID of the field to delete (e.g. “PF12345”).

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

Returns:

The updated list of parser fields.

Raises:

ValueError – If no field with field_id exists on the mailbox.

classmethod download(mailbox_id: int, field_id: str, fmt: str = 'csv', *, api_key: str | None = None) → bytes

Download the rows of a field as a single file.

This is the table-level export, meant for TABLE fields: one row per line item, with the table columns as columns. For the whole mailbox use Mailbox.download(); for a custom column selection use ExportConfig.

Parameters:

• mailbox_id – ID of the mailbox.

• field_id – ID of the field to export (e.g. “PF12345”).

• fmt – "csv" (default), "json" or "xlsx".

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

Returns:

The export file content as bytes.

Raises:

ValueError – If the field is unknown or the format is unavailable.