geonature.core.imports.checks.sql.utils
=======================================

.. py:module:: geonature.core.imports.checks.sql.utils


Functions
---------

.. autoapisummary::

   geonature.core.imports.checks.sql.utils.get_duplicates_query
   geonature.core.imports.checks.sql.utils.report_erroneous_rows
   geonature.core.imports.checks.sql.utils.print_transient_table
   geonature.core.imports.checks.sql.utils.transient_table_to_dataframe


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

.. py:function:: get_duplicates_query(imprt, dest_field, whereclause=sa.true())

.. py:function:: report_erroneous_rows(imprt, entity, error_type, error_column, whereclause, error_comment=None, level_validity_mapping={'ERROR': False})

   Report erroneous rows in a transient table and update validity of rows based on error level.

   This function reports errors found in imported data based on a WHERE clause, and updates the validity
   column of affected rows if the error level is specified in `level_validity_mapping`.
   By default, errors with the level "ERROR" mark the row as invalid.

   Parameters
   ----------
   imprt : TImport
       The current import object.
   entity : Entity
       The entity associated with the error. Must be defined if the error level is "ERROR".
   error_type : str
       Type of error to report. Must correspond to a record in `ImportUserErrorType`.
   error_column : str
       Name of the column where the error is detected. Can be mapped via `imprt.fieldmapping`.
   whereclause : sqlalchemy.sql.elements.ClauseElement
       SQL clause defining the rows affected by the error.
   error_comment : str, optional
       Optional comment to include extra explanation to describe the error in the current import context.
   level_validity_mapping : dict, optional
       Dictionary mapping error levels to validity values:
       - If the level is not in the dictionary, the row validity remains unchanged.
       - If the level is present, validity is set according to the associated value:
         - `False`: The row is marked as erroneous.
         - `None`: The row is marked as should not be imported.
       By default, only the level "ERROR" is mapped to `False`.

   Raises
   ------
   AssertionError
       If `entity` is not defined for an error of level "ERROR".

   Examples
   --------
   >>> # Example usage for reporting an "ERROR" level error
   >>> report_erroneous_rows(
   ...     imprt=my_import,
   ...     entity=my_entity,
   ...     error_type="MISSING_VALUE",
   ...     error_column="customer_name",
   ...     whereclause=(transient_table.c.customer_name == None),
   ...     error_comment="Customer name missing",
   ... )


.. py:function:: print_transient_table(imprt: geonature.core.imports.models.TImports, columns=None)

   Print the content of the transient table for a given import.

   Parameters
   ----------
   imprt : TImports
       The import to print.
   columns : list, optional
       The columns to print. If None, all columns are printed.



.. py:function:: transient_table_to_dataframe(imprt: geonature.core.imports.models.TImports, columns=None) -> pandas.DataFrame

   Get the content of the transient table for a given import as a pandas DataFrame.

   Parameters
   ----------
   imprt : TImports
       The import to get.
   columns : list, optional
       The columns to include in the DataFrame. If None, all columns are included.

   Returns
   -------
   pd.DataFrame
       The content of the transient table as a DataFrame.