Migrate Existing Report to the Function-Based Model
===================================================

The new model for writing reports relies on plain function - hence the name "Function-Based Report Model". The new model
does not use tables stored in ``TaskContext``, but allows you to manipulate with the DataFrames directly. Additionally,
you can get rid of the nasty ``yield`` extravaganza ad make your code more readable.


Migration requires one simple change and a complete rewrite of the `create_steps` method.


1. Derive the class from :py:class:`ppc_robot_lib.tasks.abstract_task_type.AbstractReportType` instead of
   :py:class:`ppc_robot_lib.tasks.abstract_task_type.AbstractTaskType`.

   Example - replace the import and the base class of your report.

   **Old code:**

   .. code-block:: python

      from ppc_robot_lib.tasks.abstract_task_type import AbstractTaskType

      class TypeNameV1(AbstractTaskType):
          # ... rest of the code ...
          pass


   **New code:**

   .. code-block:: python

      from ppc_robot_lib.tasks.abstract_task_type import AbstractReportType

      class TypeNameV1(AbstractReportType):
          # ... rest of the code ...
          pass

2. Rewrite the ``create_steps()`` method to ``execute()``.

   Example - simple report.

   **Old code:**

   .. code-block:: python

      from ppc_robot_lib.adwords import Query
      from ppc_robot_lib.output.types import Table
      from ppc_robot_lib.steps.input import AdWordsReportStep
      from ppc_robot_lib.steps.output import TablesOutputStep
      from ppc_robot_lib.utils.types import Column

      class TypeNameV1(AbstractTaskType):
          # ... other methods ...

          def create_steps(self, parameters: Dict[str, Any]):
              # Download a report.
              query = Query(
                  select=['AccountDescriptiveName', 'Clicks'],
                  from_report='ACCOUNT_PERFORMANCE_REPORT'
              )
              yield AdWordsReportStep(query, output_table='report')

              # Output the table.
              yield TablesOutputStep([
                  Table(
                      table_name='report',
                      sheet_name='Report',
                      header=[
                          Column('Account Name', 'AccountDescriptiveName'),
                          Column('Total Clicks', 'Clicks'),
                      ]
                  )
              ])


   **New code:**

   .. code-block:: python

      from ppc_robot_lib.adwords import Query
      from ppc_robot_lib.output.types import Table
      from ppc_robot_lib.reporting.input import download_adwords_report
      from ppc_robot_lib.reporting.output import write_tables
      from ppc_robot_lib.utils.types import Column

      class TypeNameV1(AbstractReportType):
          # ... other methods ...

          def execute(self, parameters: Dict[str, Any]):
              # Download a report.
              query = Query(
                  select=['AccountDescriptiveName', 'Clicks'],
                  from_report='ACCOUNT_PERFORMANCE_REPORT'
              )
              report = download_adwords_report(query)

              # Output the table.
              write_tables([
                  Table(
                      report,
                      sheet_name='Report',
                      header=[
                          Column('Account Name', 'AccountDescriptiveName'),
                          Column('Total Clicks', 'Clicks'),
                      ]
                  )
              ])


You can use all functions described in the :doc:`../reporting/index` chapter.


More examples
-------------

This section lists all reports that were rewritten to the new model.

Google Ads Custom Report
    | Before: `Google Ads CustomReportV3 <https://gitlab.com/ppc-robot/ppc-robot/blob/a97dd7a80b456432b5ee9a4c50ec7f39b985aa80/ppc_robot_task_types/adwords/custom_report/custom_report_v3.py>`_
    | After: `Google Ads CustomReportV4 <https://gitlab.com/ppc-robot/ppc-robot/blob/a97dd7a80b456432b5ee9a4c50ec7f39b985aa80/ppc_robot_task_types/adwords/custom_report/custom_report_v4.py>`_

Sklik Custom Report
    | Before: `Sklik CustomReportV4 <https://gitlab.com/ppc-robot/ppc-robot/blob/a97dd7a80b456432b5ee9a4c50ec7f39b985aa80/ppc_robot_task_types/sklik/custom_report/custom_report_v4.py>`_
    | After: `Sklik CustomReportV5 <https://gitlab.com/ppc-robot/ppc-robot/blob/a97dd7a80b456432b5ee9a4c50ec7f39b985aa80/ppc_robot_task_types/sklik/custom_report/custom_report_v5.py>`_