Outputter
=========

A type of :doc:`Callable </Callables/Callable>` that outputs a pipeline result. 

Definition
----------

Constructor
^^^^^^^^^^^

.. py:class:: controller.callable.extractor.Extractor(self, id: str, params: CallableParameters)

    An abstract subclass of :doc:`Callable </Callables/Callable>` where its implementations are Callables that outputs a pipeline result.

    :param id: The unique identifier of this Callable. Also referred to as ``callable_id`` in documentations for specific Callables.
    :type id: str
    :param params: The parameters of this Callable. Refer to the documentation for a specific Callable for details.
    :type params: CallableParameters

Methods
^^^^^^^

.. py:method:: controller.callable.Callable.check_params(self, params: CallableParameters) -> boolean
    :abstractmethod:
    
    See :doc:`Callable </Callables/Callable>`.

.. py:method:: controller.callable.Callable.exec(self, data: pd.DataFrame, **kwargs) -> pd.DataFrame
    :abstractmethod:
    
    See :doc:`Callable </Callables/Callable>`.

Usage
-----

A concrete implementation of a Callable may inherit this class and override its ``check_params()`` and ``exec()`` methods.

Output conventions
------------------

Refer to :doc:`Callable </Callables/Callable>` for conventions on all Callable outputs.

- Outputter output conventions require the output DataFrame to contain **2 columns** only.

    ========================== =========================
    ``<callable_id>.output``   ``<callable_id>.type``
    ========================== =========================
    buffer                     mime type
    ========================== =========================

    - The first column is named ``<callable_id>.output``. It contains a :doc:`BytesIO <python:library/io>` object -- a bytes buffer for streaming binary data -- storing bytes of the data to be outputted as the pipeline result.
    - The second column is named ``<callable_id>.type``. It contains a ``str`` that specifies the MIME type of the output buffer. Refer to https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types for a list of common MIME types.

- An output DataFrame from an Outputter is not designed to be passed into subsequent Callables for further processing.