Source code for pylada.jobfolder

""" Classes and functions pertaining to job-management. 

    The  :py:mod:`pylada.jobfolder` provides tools for high-throughput calculations.
    It is centered around an object - the job-folder - which organizes calculations
    within a tree of folders, much as one would manually organize calculations
    within a tree of directories. Each folder can be executable, e.g.  there is
    something to compute there, or non-executable. And each folder can further hold
    any number of sub-folders. Furthermore, classes are provided which make it easy
    to manipulate the parameters for the calculations in an executable folder, as
    well as within all subfolders. Finally, a similar infrastructure is provided to
    collect the computational results across all executable sub-folders.

    .. seealso:: :ref:`jobfolder_ug`
"""
__docformat__ = "restructuredtext en"
__all__ = ['JobFolder', 'walk_through', 'save', 'load', 'MassExtract',
           'AbstractMassExtract', 'JobParams' ]

from .jobfolder import JobFolder
from .manipulator import JobParams
from .extract import AbstractMassExtract
from .massextract import MassExtract 

def save(jobfolder, path='jobfolder.dict', overwrite=False, timeout=None): 
  """ Pickles a job-folder to file. 
 
      :param jobfolder:
          A job-dictionary to pickle. 
      :type jobfolder: :py:class:`~jobfolder.JobFolder` 
      :param str path: 
          filename of file to which to save pickle. overwritten. If None then
          saves to "pickled_jobfolder"
      :param int timeout: 
         How long to wait when trying to acquire lock on file.
         Defaults to forever.
      :param bool overwrite:
          if True, then overwrites file.

      This method first acquire an exclusive lock on the file before writing
      (see :py:meth:`pylada.misc.open_exclusive`).  This way not two processes can
      read/write to this file while using this function.
  """ 
  from os.path import exists
  from pickle import dump
  from ..misc import open_exclusive, RelativePath
  from .. import is_interactive
  path = RelativePath(path).path
  if exists(path) and not overwrite: 
    if is_interactive:
      print path, "exists. Please delete first if you want to save the job folder."
      return
    else: raise IOError('{0} already exists. By default, will not overwrite.'.format(path))
  with open_exclusive(path, "wb", timeout=timeout) as file: dump(jobfolder, file)
  if is_interactive: print "Saved job folder to {0}.".format(path)

def load(path='jobfolder.dict', timeout=None): 
  """ Unpickles a job-folder from file. 
 
      :param str path: 
         Filename of a pickled job-folder. 
      :param int timeout: 
         How long to wait when trying to acquire lock on file.
         Defaults to forever.
      :return: Returns a JobFolder object.

      This method first acquire an exclusive lock on the file before reading.
      This way not two processes can read/write to this file while using this
      function.
  """ 
  from os.path import exists
  from pickle import load as load_pickle
  from ..misc import open_exclusive, RelativePath
  from .. import is_interactive
  path = "job.dict" if path is None else RelativePath(path).path
  if not exists(path): raise IOError("File " + path + " does not exist.")
  with open_exclusive(path, "rb", timeout=timeout) as file: result = load_pickle(file)
  if is_interactive: print "Loaded job list from {0}.".format(path)
  return result