sda.api.parse_test_file
=======================

.. py:module:: sda.api.parse_test_file


Attributes
----------

.. autoapisummary::

   sda.api.parse_test_file.param_dict


Functions
---------

.. autoapisummary::

   sda.api.parse_test_file.parse_test_files


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

.. py:data:: param_dict

.. py:function:: parse_test_files(files, drop_unnamed_columns=True, command=None, dropna=True, columns_to_keep=None, verbose=1, column_not_found='raise', table_not_found='raise', suppress_polars_warnings=False)

   Parse experiment files using unified Excel table detection.

   Uses ExcelFileHandler with XML Discovery + Polars reading for maximum performance and accuracy.
   Automatically detects Excel Table objects (Insert > Table in Excel) for robust data loading.

   :param files: Files to parse. Can be:

                 - str: filename
                 - Path: filename
                 - list: list of filenames
                 - dict: {filename : special_reading_commands} (legacy parameter, mostly ignored)

                     - filename: str
                     - special_reading_commands: dict (legacy, mostly ignored in favor of table detection)
   :type files: :py:class:`str | Path | list | dict[str`, :py:class:`dict] | dict[Path`, :py:class:`dict]`
   :param drop_unnamed_columns: If True, drop unnamed columns (columns with no name), default to True.
   :type drop_unnamed_columns: :py:class:`bool`, *optional*
   :param command: Legacy reading commands. Now largely ignored in favor of automatic Excel table detection.
                   For CSV files, standard pandas parameters still apply.
   :type command: :py:class:`dict`, *optional*
   :param dropna: Drop rows with all NaN, default to True.
   :type dropna: :py:class:`bool`
   :param columns_to_keep: List of columns to keep for filtering (default: None)
   :type columns_to_keep: :py:class:`list`
   :param verbose: Verbosity level (default: 1).
                   If 0, no output.
                   If 1, print progress with basic information.
                   If 2, print detailed file processing information.
   :type verbose: :py:class:`int`
   :param column_not_found: What to do if a column is not found in the file. Can be 'raise', 'warn', or 'ignore'.

                            - 'raise': raise an error if a column is not found.
                            - 'warn': print a warning if a column is not found.
                            - 'ignore': do nothing if a column is not found.
   :type column_not_found: :py:class:`str`
   :param table_not_found: What to do if no Excel tables are found in a file. Can be 'raise' or 'warn'.

                           - 'raise': raise a TableNotFoundError if no tables are found (default).
                           - 'warn': print a warning if no tables are found and skip the file.
   :type table_not_found: :py:class:`str`
   :param suppress_polars_warnings: If True, suppress Polars dtype warning messages during reading (default: False).
   :type suppress_polars_warnings: :py:class:`bool`

   :returns: Combined DataFrame from all processed files with automatic table detection
   :rtype: :py:class:`pd.DataFrame`

   .. rubric:: Examples

   >>> files = ["T137.xlsx", "T153.xlsx"]
   >>> df = parse_test_files(files)

   >>> files = {"test_data.xlsx": {}}  # Empty dict uses table detection
   >>> df = parse_test_files(files)

   .. rubric:: Notes

   Uses ExcelFileHandler with XML-based table discovery and Polars reading engine
   for optimal performance. Legacy pandas sheet-based reading is deprecated.