Source code for mmf

"""PyMMF package.

This package first checks to see if a flag `sys._pymmf_no_init` is set.  If so,
it skips all initializations (this is useful for scripts etc. to disable logging
before importing any of :pkg:`pymmf` for example).  If initializations are okay,
then the package first reads customizations in the file `~/.mmfrc.py`
as expanded by :func:`os.path.expanduser`.  This may define the
following which control the behaviour of the import.  The defaults are
shown here:

  `start_remote_debug = True`:
    If `True`, this will also call
    :func:`mmf.async.remote_debug.listen()` to set a trap for the
    `SIGUSR1` and `SIGUSR2` signals which start the debugger.  You can
    then attach to the process with the `winpdb` debugger.
  `using_sphinx = False`:
    If `True`, then generated documentation (primarily in
    :class:`mmf.objects.StateVars` subclasses) will use sphinx
    conventions.  See also :func:`mmf.setup_sphinx`.
  `check_for_sphinx = True`:
    If `True`, then, if the command (`sys.argv[0]`) used to start python ends
    with `'sphinx-build`, `use_sphinx` will be set to `True`.
  `pp_hosts = <undefined>`:
    If defined, then :attr:`mmf.async.pp._HOSTS` is set to this value which
    specifies a set of servers to use for parallel processing.  See the
    :mod:`mmf.async.pp` module for details.
  `start_logger = True`:
    If specified, then :func:`mmf.utils.logging.start_logging` is called and
    passed the `logging_options` dictionary as a set of keyword arguments to
    start the logging services.  See :mod:`mmf.utils.logging`.
  `logging_options = {}`:
    Passed to :func:`mmf.utils.logging.start_logging` if `start_logger` is
    `True`.

.. autofunction:: setup_sphinx

The submodules of :mod:`mmf` are not loaded by default: you must
explicitly import them to use them.  (This is done to improve the
import speed.)
"""
from __future__ import division

import os.path
import warnings
import sys

skip_initialization = getattr(sys, '_pymmf_no_init', False)

if skip_initialization:
    using_sphinx = False
else:
    _initializations = {}
    try:
        execfile(os.path.expanduser("~/.mmfrc.py"), _initializations)
    except Exception, err:
        if sys.exc_traceback.tb_next is None:
            warnings.warn(("No MMF initialization file '%s' " + 
                           "found (or could not load)\n%s") % (

                    os.path.expanduser("~/.mmfrc.py"),
                    str(err)))
        else:
            warnings.warn(("MMF initialization error on line %i " + 
                          "of '%s':\n%s") % (
                    sys.exc_traceback.tb_next.tb_lineno,
                    os.path.expanduser('~/.mmfrc.py'),
                    str(err)))

    using_sphinx = _initializations.get('using_sphinx', False)

    if (_initializations.get('check_for_sphinx', True)
        and sys.argv[0].endswith('sphinx-build')):
        using_sphinx = True

    _start_remote_debug = _initializations.get('start_remote_debug', 
                                               not using_sphinx)

    if _start_remote_debug:
        import async.remote_debug as rd
        rd.listen(verbose=not _initializations.get('quiet', False))
        del rd
        del _start_remote_debug

    if _initializations.get('start_logging', not using_sphinx):
        import utils.logging
        utils.logging.start_logging(
            **(_initializations.get('logging_options', {})))

    if 'pp_hosts' in _initializations and not using_sphinx:
        import async.pp as pp
        pp._HOSTS = _initializations['pp_hosts']
        del pp

    def setup_sphinx(format_for_sphinx=True):
        r"""Setup package for sphinx documentation.

        1) Import :mod:`mmf.sphinx`
        2) Set or unset documentation format to support sphinx reST extensions
           in docstrings depending on `format_for_sphinx`.  These affect
           the documentation generated for attributes etc. in the
           :class:`mmf.objects.StateVars` class.
        3) Return a string that can be executed from within the sphinx
           `conf.py` file to customize the sphinx configuration.
        """
        import mmf.sphinx
        global using_sphinx
        using_sphinx = format_for_sphinx
        return mmf.sphinx.get_conf_string()

    del _initializations
del os, sys, warnings
del skip_initialization

from mmf.utils.init import get_imports as __get_imports
__all__, __doc__, __imports = __get_imports(globals())
# We don't import anything here: everything is delayed unless
# explicitly specified.
# exec(__imports)
del __get_imports, __imports