"""|Tecplot Engine| State and |Tecplot License| Management

The `session` module contains methods used to manipulate the |Tecplot Engine|
such as notification of a `state change` that was done such as adding or
modifying data. It also contains methods for acquiring and releasing the
|Tecplot License|.

.. _state change:

State Changes
-------------

State changes are the method for propagating information when an event occurs.
A state change can be triggered by many events. Examples include: loading a
data file, changing the color of a mesh plot, creating a new zone, or changing
the plot type.

In general, state changes are already handled internally after each call to the
PyTecplot API. This can cause a script that performs many operations,
especially those that alter data, to run slowly since the |Tecplot Engine| must
update it's internal state every time a state change is received. To speed up
such scripts, it may be necessary to use the `tecplot.session.suspend()`
context. This will collect state changes for any operation performed and will
emit the required state changes only upon exit of the context.

Using the `tecplot.session.suspend()` context in combination with Python's
"-OO" flag which removes many run-time checks in the PyTecplot API is the
recommended way to run a PyTecplot script which requires faster execution
time. The user should be aware that, when using the "-OO" flag, errors may
not be recoverable by the |Tecplot Engine|.

"""

from .aux_data import AuxData
from .session import (acquire_license, clear_suspend, connect, connected, disconnect,
                      license_expiration, release_license, start_roaming, stop,
                      stop_roaming, suspend, suspend_enter, suspend_exit)
from .state_changed import connectivity_altered, data_altered, zone_added
from .style import Style, get_style, set_style

import os
import platform
from ..tecutil import _tecutil_connector


def tecplot_install_directory():
    """|Tecplot 360| installation directory.

    Top-level installation directory for |Tecplot 360|. This will
    typically contain configuration files and the examples directory.

    This directory is platform-dependent and will contain configuration files
    and the examples directory:

    .. code-block:: python
        :emphasize-lines: 4

        import os
        import tecplot

        installdir = tecplot.session.tecplot_install_directory()
        infile = os.path.join(installdir,'examples','SimpleData','SpaceShip.lpk')
        outfile = 'spaceship.png'
        tecplot.load_layout(infile)
        tecplot.export.save_png(outfile, 600, supersample=3)

    .. figure:: /_static/images/spaceship.png
        :width: 300px
        :figwidth: 300px
    """
    if not _tecutil_connector.connected:
        _tecutil_connector.start()
    d = _tecutil_connector.tecsdkhome
    if d:
        if platform.system() in ['Darwin', 'Mac']:
            d = os.path.normpath(os.path.join(d, '..', '..'))
        return d


def tecplot_examples_directory():
    """|Tecplot 360| examples directory.

    Examples directory that is typically installed with |Tecplot 360|.
    This may be overridden with the TECPLOT_EXAMPLES environment variable.

    This directory is platform-dependent and by default contains the various
    examples shipped with |Tecplot 360|:

    .. code-block:: python
        :emphasize-lines: 4

        import os
        import tecplot

        examples_dir = tecplot.session.tecplot_examples_directory()
        infile = os.path.join(examples_dir,'SimpleData','F18.lay')
        outfile = 'load_example.png'
        tecplot.load_layout(infile)
        tecplot.export.save_png(outfile, 600, supersample=3)

    .. figure:: /_static/images/load_example.png
        :width: 300px
        :figwidth: 300px
    """
    d = tecplot_install_directory()
    if d:
        return os.environ.get('TECPLOT_EXAMPLES', os.path.join(d, 'examples'))
