Usage
=====

The main workflow exports a BusinessObjects document to a parquet file in four
steps, driven by a YAML file. The matching scripts are in the ``examples/``
directory.

Each script accepts ``--env`` (suffix read from ``.env``, default ``qualif``)
and ``--help``.

Step 1: Describe the document parameters
----------------------------------------

Lists the parameters a document accepts: their ``id`` (used as a key under
``filters:`` in the YAML), their type and the allowed values.

.. code-block:: bash

   python examples/01_describe_document.py 123456 --env prod

.. literalinclude:: ../examples/01_describe_document.py
   :language: python
   :caption: examples/01_describe_document.py

Step 2: Generate the YAML file
------------------------------

Produces a ready-to-edit config skeleton: filters pre-filled by parameter
``id`` (with the name as a comment), and, with ``--with-columns``, the document
column names (read from the dataprovider dictionary, without fetching data).

.. code-block:: bash

   python examples/02_generate_config.py 123456 --env prod --with-columns \
       -o config/s_lieuprel.yaml

.. literalinclude:: ../examples/02_generate_config.py
   :language: python
   :caption: examples/02_generate_config.py

Step 3: Refresh and export
--------------------------

Applies the YAML filters (BO refresh), retrieves the data and writes the
output. The output directory is created automatically. Column typing is applied
to ``.parquet`` and ``.json`` outputs (``.csv`` is written raw).

.. code-block:: bash

   python examples/03_export_from_config.py config/s_lieuprel.yaml --env prod

.. literalinclude:: ../examples/03_export_from_config.py
   :language: python
   :caption: examples/03_export_from_config.py

Step 4: Check the parquet
-------------------------

Prints the shape, dtypes and a preview of the produced file.

.. code-block:: bash

   python examples/04_check_parquet.py out/s_lieuprel.parquet

.. literalinclude:: ../examples/04_check_parquet.py
   :language: python
   :caption: examples/04_check_parquet.py