frog (version 0.3)
index
/home/djung/lib/frog/__init__.py

Make programs out of your Python functions that can be run from the
command line by simply adding a decorator in front of the function. The
programs will have a commandline interface based on the optparse module,
and load data from and save data to files (HDF5 format).
 
The module name "frog" is meant to be a silly shortcut for
"function program".
 
Simple example:
 
> # file "my_module.py"
> from frog import Frog
> @Frog(inmap=dict(x='$@/dset'), preproc=dict(x=list_of(float)))
> def mean(x):
>   return sum(x)/len(x)
 
Now, you can create a small executable script with the following content:
> import sys, my_module
> sys.exit(my_module._mean())
 
The way the frog is configured in this example, it expects you to specify
a bunch of HDF5 data files, where each file has a dataset called "dset", and
the function will be called with the list [x1, x2, x3, ...]
(length == number of files). By default, the result of the function goes to
STDOUT (displayed on the screen). However, the behavior can be configured in
various ways and of course strongly depends on the user's requirements.
 
Major changes in version 0.3:
--> output mapping is now a dictionary, just like input mapping
--> output mapping can now contain references to metadata, like DATE and
    TIMINGS
 
To do:
--> enable parallel execution if in independent execution mode
--> warn about usage with interactively defined functions? (no __name__)
--> be able to specify a fixed file, so instead of "$1/some/dataset", be able
    to specify "some/file.h5/some/dataset" (for input and output as well)
    setting default values in input mapping would then only be possible for
    non-strings (strings were already restricted before, could not start with
    "$", "%" or "#")
--> allow dynamic mappings, containing placeholders like {option=default}
    (also multiple), so that options can be used to set dsetnames/paths or also
    filenames/paths
--> allow slices in mappings, like "$1:/dset" (all but the first file) or
    "$:4" (the first four arguments) or "$:" (all arguments, equivalent to
    "$@")
--> case dep+@: be able to restrict number of input/output arguments (min/max)?
--> understand combined filename/dataset paths, including patterns in both
    parts of the path (feature which is already provided through h5obj.tools)
--> in addition, access dataset attributes, e.g. inmap=dict(a='$0/dset/attr')
--> enable frog configuration options --preproc and --postproc? (update dict)
--> even if no arguments are expected at all, make sure the function is still
    executed
--> reroute STDOUT and STDERR to file? could be important for parallel
    execution. DENIED!
--> if default value is True (or bool in general), behave accordingly
--> convert Frog class to a function (not really neccessary, but cleaner)
--> enable timings in milliseconds, reformat, make a new _nicetime function
    mapping
--> allow "$0" in output mapping (as a source), e.g. to access filename
--> option to "close gaps", i.e. only execute if output datasets do not yet
    exist
--> enable option to omit missing input datasets also in sequential mode?
--> omit whole file when one input dataset is missing?

 
Package Contents
       

 
Classes
       
__builtin__.object
Frog
apply_all
expressions_of
items_of
list_of
tuple_of

 
class Frog(__builtin__.object)
     Methods defined here:
__call__(self, func)
When the decorator is applied to the user's function, this method is
called with the function object. It will not touch the function object
itself and return it in the end. But an additional wrapper function
will be created in the same module which has the same name as the
user's function but with a leading underscore. Further more, the
wrapper function will have the attribute "__frog__" which is set to
True. In this way, it may be checked which of the functions defined in
a module are frog wrappers. The executable script is supposed to call
that wrapper function, i.e. using "sys.exit(my_module._my_wrapper())".
__init__(self, inmap=None, outmap=None, preproc=None, postproc=None, opttypes=None, optdoc=None, shortopts=None, longopts=None, prolog='', epilog='', usage='', version='', wrapname='', overwrite=None, bar=False, stdin_sep=None, stdout_sep=None, first=None, last=None, omit_missing=False)
Initialize and configure frog decorator.
apply_postproc(self, outdata)
Apply postprocessors to output data.
apply_preproc(self, indata)
Apply preprocessors to input data.
auto_outmap(self, outmap, outdata)
Automatically fill output mapping with standard mappings if it is
still empty.
auto_usage(self, tninargs, tnoutargs, indep, inmap, outmap)
Generate a suitable usage string based on frog configuration.
display_keywords(self, dictionary)
display_list(self, iterable)
display_object(self, obj)
divide_args(self, args, tninargs, tnoutargs, indep)
Divide arguments into two parts (input and output). If an error is
found, return the error code. Otherwise, return a tuple of two
lists.
error_arg_pairs(self)
error_dset_exists(self, dsetname, filename)
error_dset_not_found(self, dsetname, filename)
error_dset_omit(self, dsetname, filename)
error_file(self, filename)
error_nargs(self, nargs)
error_nargs_min(self, nargs)
error_pairs(self)
error_shortopt(self, shortopt)
error_stdin_len(self, nlines)
exec_once(self, inargs, outargs, opts, func)
Load and save all data, function has access to all the data at
once.
exec_seq(self, inargs, outargs, opts, func, indep, tninargs, tnoutargs)
Load and save data one by one, function works on each chunk
(argument or argument pair or file or file pair or STDIN/STDOUT line
separately.
expand_inmap(self, inmap, fdefaults)
expand_outmap(self, outmap, fdefaults)
get_exec_mode(self, tninargs, tnoutargs, indep, parallel)
Determine execution mode (sequential, parallel or all at once).
Returns "para", "seq" or "once".
get_from_outdata(self, source, outdata, indata)
get_indep(self, inmap, outmap)
Determine independent mode, i.e. find out if function only depends
on maximal one input and maximal one output argument, so that it can be
applied independently (sequential or parallel) on all the arguments or
data files.
get_tninargs(self, inmap, indep)
get_tnoutargs(self, outmap, tninargs, indep)
load_indata_once(self, inargs, inmap)
Load all input data at once (execution mode "all-at-once").
load_indata_seq(self, inarg, inmap)
Load only one chunk of data (belonging to one command line argument,
one input file, or one line of standard input) (execution mode
"sequential" or "parallel").
raise_outmap_len(self, noutdata)
read_stdin_line(self)
save_dset(self, filename, dsetname, data, overwrite=None, mode='a')
Save dataset to file. Overwrite if self.overwrite is True, never
overwrite if self.overwrite is False, and if it is None, prompt the
user to decide.
save_outdata_once(self, outargs, outmap, outdata, inargs, indata)
Save all output data at once (execution mode "all-at-once").
save_outdata_seq(self, outarg, outmap, outdata, inarg, indata)
Save a single chunk of output data (belonging to at most one
output file or one line of standard output) (execution mode
"sequential" or "parallel").
split_indata(self, indata)
Convert input data (already preprocessed) into a variable list of
arguments (inargs) and a dictionary of keyword arguments (inkwargs),
ready to be passed to the function.
update_inmap(self, inmap)
update_outmap(self, outmap)
Update output mapping with user-defined content from the --outmap
command line option.

Static methods defined here:
any_startswith(objects, string)
Return true if any of the given objects starts with the given
string. Non-strings among the objects are ignored.
get_argind(mapping, symbol='$')
Extract the argument index from a mapping, i.e. the number in "$1"
or "$2/any_dataset". Return None if mapping is not string, or doesn't
start with "$", or starts with "$@". Instead of "$", another symbol can
be chosen.
in_any(obj, iterable)
is_even(number)
plural(number)
raise_argind(mapping)
raise_exec_mode()
raise_indep()
raise_inmap(mapping)
raise_outdata(outlen)
raise_outdata_iterable(mapping)
raise_outdata_len(nexpected)
raise_outmap(mapping)
raise_parallel()
raise_percent_in_inmap(mapping)
raise_postproc_iter()
raise_postproc_len(outlen)
raise_preproc()
raise_reqarg_not_in_inmap(reqarg)
raise_stdin_structure()
raise_stdout_structure()
startswith_one_of(string, chars)

Data descriptors defined here:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)

 
class apply_all(__builtin__.object)
    Instances of this class are callables which apply a list of functions to
the given object.
 
  Methods defined here:
__call__(self, obj)
__init__(self, *funcs)

Data descriptors defined here:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)

 
class expressions_of(__builtin__.object)
    Instances of this class are callables which evaluate a certain
expression for each element of a given iterable, and returns the results as
in form of a new iterable. In the expression, "x" indicates the respective
item.
 
  Methods defined here:
__call__(self, iterable)
__init__(self, expr='x', dtype=None)

Data descriptors defined here:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)

 
class items_of(__builtin__.object)
    Instances of this class are callables which get a certain item of each
element of a given iterable, and returns all items in form of a new
iterable. If item does not exist and a default value is given, return that
value.
 
  Methods defined here:
__call__(self, iterable)
__init__(self, itemname, default=None, dtype=None)

Data descriptors defined here:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)

 
class list_of(__builtin__.object)
    Instances of this class are callables which turn a given iterable into
a list of items with the specified data type.
 
  Methods defined here:
__call__(self, iterable)
__init__(self, dtype)

Data descriptors defined here:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)

 
class tuple_of(__builtin__.object)
    Instances of this class are callables which turn a given iterable into
a tuple of items with the specified data type.
 
  Methods defined here:
__call__(self, iterable)
__init__(self, dtype)

Data descriptors defined here:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)

 
Functions
       
eval_if_str(obj)
Evaluate given expression only if string is given, otherwise, leave the
given object unchanged.
frogexec(frog, name=None, dir='.')
Create a small executable script that calls the specified frog wrapper.
Expect either the function object of the frog wrapper itself, or a string
containing the full module path to the frog wrapper.
 
The executable script is created in the directory "dir". Default is the
current working directory. The script will be named according to "name",
otherwise it will be based on the name of the function object of the frog
wrapper.
 
An attempt to make the script executable is made, using "chmod +x".
froglist(module)
List all frogs defined in a certain module. The module can be a string
(module path) or the module object itself.
isfrog(func)
Check if given function object is that of a frog wrapper.
print_timings(timings)
sentence(iterable)
Convert all items of the iterable to strings and join them with space
characters in between. Return the newly formed string.

 
Data
        __created__ = '2013-06-28'
__modified__ = '2014-02-07'
__version__ = '0.3'