Source code for api.postprocessor.evaluations.evaluation_setup

""" Handling of evaluations """

import typing

import more.api.postprocessor.viewers
from abc import abstractmethod, ABC



class EvaluationSetup(ABC):

    def __init__(self, evaluation):
        self._evaluation = evaluation

    def _get_wrapped_object(self):
        return self._evaluation



    @abstractmethod
    def get_name(self) -> str:
        """ Returns the name of the evaluation

        .. admonition:: Example
            :class: note

            ..
                >>> import more.project
                >>> proj = more.project.Project()

            >>> from more.api import ApiGateway
            >>> api = ApiGateway(proj=proj)
            >>> postprocessor_setup = api.create_postprocessor_setup()

            ..
                >>> from more.api_implementations._api_tools.postprocessor.mocking_utils import append_simresult_with_empty_result
                >>> append_simresult_with_empty_result(proj, 'example_simresult')

            >>> simresult_setup = postprocessor_setup.get_simresult(name='example_simresult') # The simresult object must already exist
            >>> evaluation_setup = simresult_setup.create_evaluation(evaluation_type='Custom').set_name(name='new_name')
            >>> evaluation_setup.get_name()
            'new_name'

        Returns
        -------
        name: str
            The name of the evaluation


        """
        pass





    @abstractmethod
    def set_name(self, name: str, resolve_duplicate_name: bool = False) -> 'EvaluationSetup':
        """ Changes the name of the evaluation


        .. admonition:: Example
            :class: note

            ..
                >>> import more.project
                >>> proj = more.project.Project()

            >>> from more.api import ApiGateway
            >>> api = ApiGateway(proj=proj)
            >>> postprocessor_setup = api.create_postprocessor_setup()

            ..
                >>> from more.api_implementations._api_tools.postprocessor.mocking_utils import append_simresult_with_empty_result
                >>> append_simresult_with_empty_result(proj, 'example_simresult')

            >>> simresult_setup = postprocessor_setup.get_simresult(name='example_simresult') # The simresult object must already exist
            >>> evaluation_setup = simresult_setup.create_evaluation(evaluation_type='Custom')
            >>> evaluation_setup.set_name(name='new_name')
            <more...>
            >>> second_evaluation_setup = simresult_setup.create_evaluation(evaluation_type='Custom')\\
            ...     .set_name(name='new_name', resolve_duplicate_name=True)
            >>> second_evaluation_setup.get_name()
            'new_name 1'

            ..
                >>> evaluation_setup._evaluation.name
                'new_name'

                Trying to set the name to a non-string value
                >>> evaluation_setup.set_name(name=None)
                Traceback (most recent call last):
                ...
                TypeError: ...

                Setting a non-unique name
                >>> evaluation_setup.set_name('new_name')
                Traceback (most recent call last):
                ...
                more.api.exceptions.api_exception.NameNotUniqueError: ...

        Parameters
        ----------
        resolve_duplicate_name: bool
            Whether to automatically assign a new name when the chosen one is already taken
        name: str
            The new name of the evaluation

        Returns
        -------
        self: :class:`~api.postprocessor.evaluations.evaluation_setup.EvaluationSetup`


        Raises
        ------
        NameNotUniqueError
            Raised if the given name is not unique
        TypeError
            Raised if the given name is not a string

        """
        pass




    @abstractmethod
    def remove_viewer(self, name: str) -> 'EvaluationSetup':
        """ Removes a viewer object

        .. admonition:: Example
            :class: note

            ..
                >>> import more.project
                >>> proj = more.project.Project()

            >>> from more.api import ApiGateway
            >>> api = ApiGateway(proj=proj)
            >>> postprocessor_setup = api.create_postprocessor_setup()

            ..
                >>> from more.api_implementations._api_tools.postprocessor.mocking_utils import append_simresult_with_empty_result
                >>> append_simresult_with_empty_result(proj, 'example_simresult')

            >>> simresult_setup = postprocessor_setup.get_simresult(name='example_simresult') # The simresult object must already exist
            >>> evaluation_setup = simresult_setup.create_evaluation(evaluation_type='Custom').set_name(name='example_evaluation')
            >>> evaluation_setup.create_viewer(viewer_type='Figure').set_name(name='example_viewer')
            <more...>
            >>> evaluation_setup.remove_viewer(name='example_viewer')
            <more...>

            ..
                >>> len(proj.post.simresults[0].evaluations[0].viewers)
                0
                >>> evaluation_setup.remove_viewer(name='non_existent_example_viewer')
                Traceback (most recent call last):
                ...
                more.api.exceptions.api_exception.NameNotFoundError: ...


        Parameters
        ----------
        name : str
            The name of the viewer object to remove

        Returns
        -------
        self : :class:`~api.postprocessor.evaluations.evaluation_setup.EvaluationSetup`

        Raises
        ------
        NameNotFoundError
            Raised if no viewer with the given name exist

        """
        pass




    @abstractmethod
    def duplicate_viewer(self, name: str) -> 'more.api.postprocessor.viewers.ViewerSetup':
        """ Duplicates a viewer object and returns the :class:`~api.postprocessor.viewers.viewer_setup.ViewerSetup` object for the newly created copy

        .. admonition:: Example
            :class: note

            ..
                >>> import more.project
                >>> proj = more.project.Project()

            >>> from more.api import ApiGateway
            >>> api = ApiGateway(proj=proj)
            >>> postprocessor_setup = api.create_postprocessor_setup()

            ..
                >>> from more.api_implementations._api_tools.postprocessor.mocking_utils import append_simresult_with_empty_result
                >>> append_simresult_with_empty_result(proj, 'example_simresult')

            >>> simresult_setup = postprocessor_setup.get_simresult(name='example_simresult') # The simresult object must already exist
            >>> evaluation_setup = simresult_setup.create_evaluation(evaluation_type='Custom').set_name(name='example_evaluation')
            >>> evaluation_setup.create_viewer(viewer_type='Figure').set_name(name='example_viewer')
            <more...>
            >>> duplicate_viewer = evaluation_setup.duplicate_viewer(name='example_viewer')
            >>> print("Automatically assigned name of the duplicate: {}".format(duplicate_viewer.get_name()))
            Automatically assigned name of the duplicate: ...

            ..
                >>> len(proj.post.simresults[0].evaluations[0].viewers)
                2
                >>> evaluation_setup.duplicate_viewer(name='non_existent_example_viewer')
                Traceback (most recent call last):
                ...
                more.api.exceptions.api_exception.NameNotFoundError: ...

        Parameters
        ----------
        name : str
            The name of the viewer object to duplicate

        Returns
        -------
        :class:`~api.postprocessor.viewers.viewer_setup.ViewerSetup`
            The setup object for the newly created copy

        Raises
        ------
        NameNotFoundError
            Raised if no viewer with the given name exist

        """
        pass




    @abstractmethod
    def get_viewer_names(self) -> typing.List[str]:
        """ Gets the names of existing child viewers


        .. admonition:: Example
            :class: note

            ..
                >>> import more.project
                >>> proj = more.project.Project()

            >>> from more.api import ApiGateway
            >>> api = ApiGateway(proj=proj)
            >>> postprocessor_setup = api.create_postprocessor_setup()

            ..
                >>> from more.api_implementations._api_tools.postprocessor.mocking_utils import append_simresult_with_empty_result
                >>> append_simresult_with_empty_result(proj, 'example_simresult')

            >>> simresult_setup = postprocessor_setup.get_simresult(name='example_simresult') # The simresult object must already exist
            >>> evaluation_setup = simresult_setup.create_evaluation(evaluation_type='Custom')
            >>> evaluation_setup.create_viewer(viewer_type='Figure').set_name(name='example_viewer')
            <more...>
            >>> print("Available viewers: {}".format(evaluation_setup.get_viewer_names()))
            Available viewers: [...]

        Returns
        -------
        list of strings
            Names of existing child viewers

        """
        pass




    @abstractmethod
    def create_viewer(self, viewer_type: str) -> 'more.api.postprocessor.viewers.ViewerSetup':
        """ Creates a viewer and returns a :class:`~api.postprocessor.viewers.viewer_setup.ViewerSetup` object

        .. admonition:: Example
                :class: note

                ..
                    >>> import more.project
                    >>> proj = more.project.Project()

                >>> from more.api import ApiGateway
                >>> api = ApiGateway(proj=proj)
                >>> postprocessor_setup = api.create_postprocessor_setup()

                ..
                    >>> from more.api_implementations._api_tools.postprocessor.mocking_utils import append_simresult_with_empty_result
                    >>> append_simresult_with_empty_result(proj, 'example_simresult')

                >>> simresult_setup = postprocessor_setup.get_simresult(name='example_simresult') # The simresult object must already exist
                >>> evaluation_setup = simresult_setup.create_evaluation(evaluation_type='Custom')
                >>> print("Available viewer types: {}".format(evaluation_setup.get_compatible_viewer_types()))
                Available viewer types: [...]
                >>> viewer_setup = evaluation_setup.create_viewer(viewer_type='Figure')

                 ..
                    >>> from more.api.postprocessor.viewers.viewer_setup import ViewerSetup
                    >>> isinstance(viewer_setup, ViewerSetup)
                    True
                    >>> len(proj.post.simresults[0].evaluations[0].viewers)
                    1
                    >>> evaluation_setup.create_viewer(viewer_type='non_existent_name')
                    Traceback (most recent call last):
                    ...
                    more.api.exceptions.api_exception.NameNotFoundError: ...
                    >>> evaluation_setup.create_viewer(viewer_type='Modal')
                    Traceback (most recent call last):
                    ...
                    more.api.exceptions.api_exception.NotCompatibleError: ...


        Parameters
        ----------
        viewer_type: str
            The name of the evaluation type to add, to check which names are compatible run the :meth:`~get_compatible_viewer_types` method

        Returns
        -------
        :class:`~api.postprocessor.viewers.viewer_setup.ViewerSetup`
            An object for managing viewer setup


        Raises
        ------
        NameNotFoundError
            Raised if no viewer with the given type exists

        NotCompatibleError
            Raised if the viewer is not compatible

        """

        pass




    @abstractmethod
    def get_compatible_viewer_types(self) -> typing.List[str]:
        """ Gets the names of viewer types compatible with this evaluation

        .. admonition:: Example
            :class: note

            ..
                >>> import more.project
                >>> proj = more.project.Project()

            >>> from more.api import ApiGateway
            >>> api = ApiGateway(proj=proj)
            >>> postprocessor_setup = api.create_postprocessor_setup()

            ..
                >>> from more.api_implementations._api_tools.postprocessor.mocking_utils import append_simresult_with_empty_result
                >>> append_simresult_with_empty_result(proj, 'example_simresult')

            >>> simresult_setup = postprocessor_setup.get_simresult(name='example_simresult') # The simresult object must already exist
            >>> evaluation_setup = simresult_setup.create_evaluation(evaluation_type='Custom')
            >>> evaluation_setup.create_viewer(viewer_type='Figure').set_name(name='example_viewer')
            <more...>
            >>> print("Available viewer types: {}".format(evaluation_setup.get_compatible_viewer_types()))
            Available viewer types: [...]

        Returns
        -------
        list of strings
            Names of compatible viewer types

        """
        pass




    @abstractmethod
    def get_result_names(self) -> typing.List:
        """ Gets the names of the results, typically these are the job labels assigned in the study


        .. admonition:: Example
            :class: note

            ..
                >>> import more.project
                >>> proj = more.project.Project()

            >>> from more.api import ApiGateway
            >>> api = ApiGateway(proj=proj)
            >>> postprocessor_setup = api.create_postprocessor_setup()

            ..
                >>> from more.api_implementations._api_tools.postprocessor.mocking_utils import append_simresult_with_empty_result
                >>> append_simresult_with_empty_result(proj, 'example_simresult')

            >>> simresult_setup = postprocessor_setup.get_simresult(name='example_simresult') # The simresult object must already exist
            >>> evaluation_setup = simresult_setup.create_evaluation(evaluation_type='Custom')
            >>> print("Available results: {}".format(evaluation_setup.get_result_names()))
            Available results: [...]


        Returns
        -------
        list of strings
            Names of available results

        """
        pass


    # @abstractmethod
    # def get_parents(self) -> typing.List[typing.Union['EvaluationSetup', 'more.api.postprocessor.simresult_setup.SimresultSetup']]:
    #     """ Gets the parents of this evaluation.
    #
    #     .. admonition:: Example
    #         :class: note
    #
    #         ..
    #             >>> import more.project
    #             >>> proj = more.project.Project()
    #         >>> from more.api import ApiGateway
    #         >>> api = ApiGateway(proj=proj)
    #         >>> postprocessor_setup = api.create_postprocessor_setup()
    #
    #         ..
    #             >>> from more.api_implementations._api_tools.postprocessor.mocking_utils import append_simresult_with_empty_result
    #             >>> append_simresult_with_empty_result(proj, 'example_simresult')
    #         >>> simresult_setup = postprocessor_setup.get_simresult(name='example_simresult') # The simresult object must already exist
    #         >>> evaluation_setup = simresult_setup.create_evaluation(evaluation_type='Custom')
    #         >>> print("Parents: {}".format(evaluation_setup.get_parents()))
    #         Parents: [...]
    #
    #         ..
    #             >>> evaluation_setup.get_parents()[0]._simresult == evaluation_setup._evaluation.parent
    #             True
    #
    #     Returns
    #     -------
    #     list of parents
    #         The list of all parents of this evaluation
    #
    #     """
    #     pass



    @abstractmethod
    def get_viewer(self, name: str) -> 'more.api.postprocessor.viewers.ViewerSetup':
        """ Creates a :class:`~api.postprocessor.viewers.viewer_setup.ViewerSetup`  for an already existing viewer


        .. admonition:: Example
            :class: note

            ..
                >>> import more.project
                >>> proj = more.project.Project()

            >>> from more.api import ApiGateway
            >>> api = ApiGateway(proj=proj)
            >>> postprocessor_setup = api.create_postprocessor_setup()

            ..
                >>> from more.api_implementations._api_tools.postprocessor.mocking_utils import append_simresult_with_empty_result
                >>> append_simresult_with_empty_result(proj, 'example_simresult')

            >>> simresult_setup = postprocessor_setup.get_simresult(name='example_simresult') # The simresult object must already exist
            >>> evaluation_setup = simresult_setup.create_evaluation(evaluation_type='Custom')
            >>> viewer_setup = evaluation_setup.create_viewer(viewer_type='Figure').set_name(name='example_viewer')
            >>> print("Available viewer types: {}".format(evaluation_setup.get_compatible_viewer_types()))
            Available viewer types: [...]
            >>> found_viewer_setup = evaluation_setup.get_viewer(name='example_viewer')

            ..
                >>> found_viewer_setup._viewer == proj.post.simresults[0].evaluations[0].viewers[0]
                True


        Parameters
        ----------
        name : str
            The name of the existing viewer for which to return a :class:`~api.postprocessor.viewers.viewer_setup.ViewerSetup`

        Returns
        -------
        :class:`~api.postprocessor.viewers.viewer_setup.ViewerSetup`
            A :class:`~api.postprocessor.viewers.viewer_setup.ViewerSetup` object for the found viewer

        Raises
        ------
        NameNotFoundError
            Raised if no viewer with the given name was found

        """

        pass



    # def get_evaluation(self, name: str) -> 'EvaluationSetup':
    #     pass
    #
    # def delete_evaluation(self, name: str) -> 'EvaluationSetup':
    #     pass
    #
    # def duplicate_evaluation(self, name: str) -> 'EvaluationSetup':
    #     pass
    #
    # def create_evaluation(self, evaluation_type: str) -> 'EvaluationSetup':
    #     pass
    #
    # def get_evaluation_names(self) -> typing.List[str]:
    #     pass