.. _api:

===
API
===

This page documents the inheritable classes provided by the ATK, and their various attributes and public functions.

.. class:: Algorithm([cl=None[, params=None]])

    :param ChainLedger cl: ChainLedger object instantiation
    :param dict params: Python dictionary containing values for algorithm inputs
    :param list errors: List of errors generated by an algorithm
    :param logger: Python ``logging`` object
    :param string name: Name of algorithm

    .. function:: run()

        Override this function with your algorithm logic.

    .. function:: raise_client_error(err)

        :param string err: String containing the error message
        :returns: AlgorithmException object
        :return type: AlgorithmException

        Raise an error to the calling application, such as a web browser.

.. class:: AlgorithmChain(path, passed_chain)

    :param string atk_path: Folder location for the current algorithm project
    :param string chain_name: Name of the algorithm chain as it appears in the chain definition
    :param dict chain_definition: Python dictionary containing chain definition

    .. function:: get_request_dict()

        :return type: dict

        Return a dict containing all algorithms in the current chain and their default parameter values as if making a request to run a chain (e.g.: from a web form).

    .. class:: ChainLedger(status_key)

        :param string status_key: Unique ID for chain run, used for obtaining status and history
        :param dict metadata: key, value pairs placed on the Check Ledger by algorithms
        :param list history: array of metadata, ordered by chain run order
        :param int chain_percent: percent progress of chain run
        :param int batch_percent: percent progress of batch run

        .. function:: add_to_metadata(key, value)

            :param string key: metadata key used for later retrieval
            :param any value: value to be saved with the key

            Add a key, value pair to the Chain Ledger

        .. function:: get_from_metadata(key)

            :param string key: metadata key used to retrieve the item
            :returns: value of key in metadata
            :return type: any

            Return a value placed in Chain Ledger metadata under *key*.

        .. function:: get_from_history(history_index, key)

            :param int history_index: position in the Chain Ledger history for the algorithm sought
            :param string key: key to be located in metadata
            :returns: value in metadata history under key
            :return type: any

            Search the Chain Ledger history for a key in metadata, based on the index of the algorithm in the history list.

        .. function:: search_history(key, algorithm_name)

            :param string key: key to search for
            :param string algorithm_name: name of algorithm to to find in history
            :returns: a set of items matching the algorithm, key pair
            :return type: list

            Search the history for a particular metadata key coming from an algorithm, however many times it occurs.

        .. function:: is_algo_in_history(algorithm_name)

            :param string algorithm_name: name of algorithm to search
            :return type: boolean

            Return True if algorithm name appears in the history, otherwise return False.

        .. function:: set_status(status[, percent=0])

            :param string status: status message for calling application

            Set a key in app.config with the Chain Ledger status_key as its name, and create a dictionary of status information, setting the app.config[key] value equal to that dictionary. Example::

                {
                    "all_msg": "",
                    "latest_msg": "",
                    "algorithm_percent_complete": 0,
                    "chain_percent_complete": 0,
                    "batch_percent_complete": 0
                }

        .. function:: get_results_folder()

            :returns: location of results folder
            :return type: string

            Provide the location of the results folder for files to be saved during an algorithm chain run

        .. function:: get_temp_folder()

            :returns: location of temp folder
            :return type: string

            Provide the location of the temp folder for files to be saved during an algorithm chain run. These files will be deleted at the end of the chain run.

        .. function:: clear_temp_folder()

            Delete all files and folders within the chain temp folder

.. class:: AlgorithmTestCase()

    Test Case template class to use for conducting unit tests of algorithms. Inherits from ``unittest.TestCase``.

    .. function:: check_metadata(key, value)

        :param string key: key in metadata to validate by
        :param any value: value to validate
        :return type: boolean

        Return True if value is the same as that found on the metadata. Otherwise return False.


    .. function:: check_status(status)

        :param string status: string to validate
        :return type: boolean

        Return True if status is the same as that found on the app.config dictionary under the Chain Ledger status key. Otherwise return False.
