:orphan:

..
    TODO: add links to documentation for mentioned modules.

Factories Module Description
""""""""""""""""""""""""""""

Brief description
'''''''''''''''''
Modin has several execution engines and storage formats, combining them together forms certain executions. 
Calling any :py:class:`~modin.pandas.dataframe.DataFrame` API function will end up in some execution-specific method. The responsibility of dispatching high-level API calls to
execution-specific function belongs to the :ref:`QueryCompiler <query_compiler_def>`, which is determined at the time of the dataframe's creation by the factory of
the corresponding execution. The mission of this module is to route IO function calls from
the API level to its actual execution-specific implementations, which builds the
`QueryCompiler` of the appropriate execution.

Execution representation via Factories
''''''''''''''''''''''''''''''''''''''
Execution is a combination of the :doc:`storage format </flow/modin/core/storage_formats/index>` and an actual execution engine.
For example, ``PandasOnRay`` execution means the combination of the `pandas storage format` and `Ray` engine.

Each storage format has its own :ref:`Query Compiler <query_compiler_def>` which compiles the most efficient queries
for the corresponding :doc:`Core Modin Dataframe </flow/modin/core/dataframe/index>` implementation. Speaking about ``PandasOnRay``
execution, its Query Compiler is :doc:`PandasQueryCompiler </flow/modin/core/storage_formats/pandas/query_compiler>` and the
Dataframe implementation is :doc:`PandasDataframe </flow/modin/core/dataframe/pandas/dataframe>`,
which is general implementation for every execution of the pandas storage format. The actual implementation of ``PandasOnRay`` dataframe
is defined by the :doc:`PandasOnRayDataframe </flow/modin/core/execution/ray/implementations/pandas_on_ray/dataframe>` class that
extends ``PandasDataframe``.

In the scope of this module, each execution is represented with a factory class located in
``modin/core/execution/dispatching/factories/factories.py``. Each factory contains a field that identifies the IO module of the corresponding execution. This IO module is
responsible for dispatching calls of IO functions to their actual implementations in the
underlying IO module. For more information about IO module visit :doc:`IO </flow/modin/core/io/index>` page.

Factory Dispatcher
''''''''''''''''''
The :py:class:`~modin.core.execution.dispatching.factories.dispatcher.FactoryDispatcher` class provides 
public methods whose interface corresponds to pandas IO functions, the only difference is that they return `QueryCompiler` of the
selected storage format instead of high-level :py:class:`~modin.pandas.dataframe.DataFrame`. ``FactoryDispatcher`` is responsible for routing
these IO calls to the factory which represents the selected execution.

So when you call ``read_csv()`` function and your execution is ``PandasOnRay`` then the
trace would be the following:

.. figure:: /img/factory_dispatching.svg
    :align: center

``modin.pandas.read_csv`` calls ``FactoryDispatcher.read_csv``, which calls ``._read_csv``
function of the factory of the selected execution, in our case it's ``PandasOnRayFactory._read_csv``,
which in turn forwards this call to the actual implementation of ``read_csv`` — to the
``PandasOnRayIO.read_csv``. The result of ``modin.pandas.read_csv`` will return a high-level Modin
DataFrame with the appropriate `QueryCompiler` bound to it, which is responsible for
dispatching all of the further function calls.

Public API
''''''''''

.. automodule:: modin.core.execution.dispatching.factories.factories
    :members: