parseur.parser_field
====================

.. py:module:: parseur.parser_field


Classes
-------

.. autoapisummary::

   parseur.parser_field.ParserField


Functions
---------

.. autoapisummary::

   parseur.parser_field._to_write
   parseur.parser_field._fmt


Module Contents
---------------

.. py:function:: _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.


.. py:function:: _fmt(field_format: Union[str, parseur.schemas.paserfield.FieldFormat]) -> str

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


.. py:class:: 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 :meth:`delete`).


   .. py:method:: list(mailbox_id: int, *, api_key: Optional[str] = None) -> List[Dict[str, Any]]
      :classmethod:


      Return the parser fields currently configured on a mailbox.



   .. py:method:: _save(mailbox_id: int, fields: List[Dict[str, Any]], *, api_key: Optional[str] = None) -> List[Dict[str, Any]]
      :classmethod:


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



   .. py:method:: add(mailbox_id: int, name: str, field_format: Union[str, parseur.schemas.paserfield.FieldFormat], *, query: Optional[str] = None, is_required: Optional[bool] = None, used_by_ai: Optional[bool] = None, choice_set: Optional[List[str]] = None, parser_object_set: Optional[List[Dict[str, Any]]] = None, api_key: Optional[str] = None) -> List[Dict[str, Any]]
      :classmethod:


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

      :param mailbox_id: ID of the mailbox.
      :param name: Name of the new field.
      :param field_format: Field format (see :class:`FieldFormat`).
      :param query: Optional AI extraction instructions.
      :param is_required: Optional required flag.
      :param used_by_ai: Optional flag controlling AI extraction.
      :param choice_set: Optional list of allowed values.
      :param parser_object_set: Optional nested columns (for TABLE fields).
      :param api_key: Optional API key overriding the global one for this call.
      :return: The updated list of parser fields.



   .. py:method:: update(mailbox_id: int, field_id: str, *, api_key: Optional[str] = None, **changes: Any) -> List[Dict[str, Any]]
      :classmethod:


      Update a single existing field by its id.

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

      :param mailbox_id: ID of the mailbox.
      :param field_id: ID of the field to update (e.g. "PF12345").
      :param api_key: Optional API key overriding the global one for this call.
      :param 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``.
      :return: The updated list of parser fields.
      :raises ValueError: If no field with ``field_id`` exists on the mailbox.



   .. py:method:: delete(mailbox_id: int, field_id: str, *, api_key: Optional[str] = None) -> List[Dict[str, Any]]
      :classmethod:


      Delete a single field from a mailbox by its id.

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

      :param mailbox_id: ID of the mailbox.
      :param field_id: ID of the field to delete (e.g. "PF12345").
      :param api_key: Optional API key overriding the global one for this call.
      :return: The updated list of parser fields.
      :raises ValueError: If no field with ``field_id`` exists on the mailbox.



   .. py:method:: download(mailbox_id: int, field_id: str, fmt: str = 'csv', *, api_key: Optional[str] = None) -> bytes
      :classmethod:


      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
      :meth:`Mailbox.download`; for a custom column selection use
      :class:`ExportConfig`.

      :param mailbox_id: ID of the mailbox.
      :param field_id: ID of the field to export (e.g. "PF12345").
      :param fmt: ``"csv"`` (default), ``"json"`` or ``"xlsx"``.
      :param api_key: Optional API key overriding the global one for this call.
      :return: The export file content as bytes.
      :raises ValueError: If the field is unknown or the format is unavailable.