This case module describes a modelling case that might involve running a set of programs in sequence, transferring output from one program to input to the others, etc.
The main component in this module is the Case class, which can be accessed in the following ways:
Create an instance and call its methods (might be useful in interactive sessions and simple scripts), e.g.:
c = Case('mycase') c.start() c.add_file('my_inputfile.txt') status = c.execute('myprogram') assert status.returncode == 0 c.close()You have to call the close() method to clean up the working directory. Use try.. finally to ensure that close() is called even if an unhandled exception is raised.
This method cannot be used to run cases in a background thread using the BgCase class.
Provide a target argument to the constructor (useful in test scripts and simple programs), e.g.:
def target(c): c.add_file('my_inputfile.txt') ... c = case('mycase, target=target) c.start()This calls the close() method automatically when target() returns.
subclassing and overwrite the run() method (useful in larger frameworks or when you need more control), e.g.:
class MyCase(Case): def run(self): self.add_file('my_inputfile.txt') ... c = MyCase() c.start()This calls the close() method automatically when the run() method returns.
This module defines the following objects:
A class for running a modelling case.
| Parameters : | casename : string
casedir : None | string
workdir : None | string
tmpdir : None | string
cleanup : None, bool | “on_success”
target : None | callable
|
|---|
Notes
A new logger named casename is created for each subclass instance, with a default handler that logs to the file casename.log in workdir.
See https://docs.python.org/2/howto/logging.html#configuring-logging for global logging configurations to customize the logging after your needs.
Adds file to working directory.
Copies the input file src to working directory.
| Parameters : | src : string
dest : None | string
symlink : bool
literal : bool
|
|---|
Calls function func in a separate process and wait for it to finish. The current working directory of func is set to self.workdir.
| Parameters : | func : callable
args : tuple
kwargs : dict
conditions : None | sequence
maxtime : float
full_output : bool
|
|---|---|
| Returns : | retval : object
returncode : int (optional)
exectime : float (optional)
|
Name of case directory (read only).
Name of this case (read only).
Dict with parameter-value pairs set by the caller. This is e.g. used by caseset.
Whether to remove workdir when closing the case.
Explicitely tears down the case.
Notes
The logger will be deleted the first time this function is called. However it is possible to call close() with cleanup=False to close the case but keep the output, and then at a later stage call it again with cleanup=True to clean up the working directory.
Whether close() has been called (read only).
Executes command and wait for it to finish.
The command is executed in the working directory and its standard output and error are stored in the files stdout<n>.txt and stderr<n>.txt in the working directory, where <n> is the number of times execute() has been called for this case instance.
| Parameters : | command : string | sequence
expected_returncode : None | int
conditions : None | sequence
env : None | dict
shell : bool
stdin : None | string | file-like
maxtime : float
bufsize : int
|
|---|---|
| Returns : | status : ExeStatus instance
|
Retrives a file from working directory.
Copies src to dest, where src and dest are relative to the working and case directories, respectively.
If dest is None, src is copied to the case directory.
If dest is an existing directory or ends with “/”, src is copied to this directory (possibly creating it).
Returns the value of a given parameter from a parameter file.
| Parameters : | fname : string | file-like
name : string
fmt : None | string
|
|---|
Number of times execute() has been called (read only).
Reads data from files and return it as a list of 1d numpy arrays.
filespec is a comma-separated list of one or more file names, followed by a colon-separated list of colum names and option-value pairs.
If the filename are relative, they will be relative to the directory cwd.
The grammar for filespec can formally be written as:
filespec ::= filename (":" columnspec | ":" option)* ["," filespec]
columnspec ::= column_id [ "[" indexspec "]" ]
option ::= name "=" value
indexspec ::= integer | slice | column_id "=" val ("," val)*
column_id ::= integer | string
Comma, colon, equal and backslash characters can be backslash-escaped.
Columns can be specified either by name or by number and optionally followed by a pair of bracket ([]) supporting standard indexing.
If your data file has columns ‘year’ and ‘population’ it is also possible to write population[year=2012,2014]. This will return the population at 2012 and 2014 using linearly interpolation. The column ‘year’ must be increasing. The options left and right (described below) are used if a specified year is outside the range of the data.
The name=value options are passed to recio.read() as keyword arguments to the reader. However, a few options are interpreated by readdata() and not passed further.
Notes
This function uses eval() for the bracket indexing, which might be a security risk if filespec comes from an untrusted user.
Examples
Read ‘col1’ and ‘col2’ from ‘filename’ and return them:
filename:col1:col2
Read ‘col1’ and ‘col2’ from both ‘file1’ and ‘file2’ (returning four columns) and pass opt=val as keyword argument to recio.read() when reading the files:
file1,file2:col1:col2:opt=val
Read 3 columns, two from file1 and one from ‘file2’, passing opt1=val1 and opt2=val2 to recio.read():
file1:col1:col2:opt1=val1:opt2=val2,file2:col3
Read element 1 to 10 from column ‘col’ in ‘file’:
file:col[1:10]
Read the columns ‘year’ and ‘population’ from ‘population.txt’ and return interpolated population at 2012 and 2014:
population.txt:population[year=2012,2014]
Returns a Parameters object from file or data.
This is a wrapper around pario.recio.read.
If fname is a file name and not an absolute path, it will be relative cwd. cwd defaults to the working directory.
cls is given, it must be a subclass of Parameters, usually defining another file format.
See also
Reads filename and return a NumPy record array.
This is a wrapper around pario.recio.read. If filename is not an absolute path, it will be relative cwd, where cwd defaults to the working directory.
See also
Method defining the case actions.
You can override this method in your subclass. The default implementation calls the target provided in the constructor with arguments (self, *args, **kwargs).
Note
CaseSet objects might call run() with a keyword argument parameters set to a dictionary holding the names and new values of not already handled parameters that should be changed from their default values in this case.
Whether run() is running (read only).
Sets the value of a parameter in a parameter file.
| Parameters : | filename : string
name : string
value : correct type for this parameter
fmt : None | string
options : keywords
|
|---|
Whether start() has been called (read only).
Evaluates a condition.
This function is typically used for checking whether the output of a program is up-to-date.
| Parameters : | op : callable | string
args : sequence
prefix : string
|
|---|---|
| Returns : | status: bool
|
Notes
The docstring for this method is automatically created from condition(). For this method the prefix argument defaults to workdir.
Name of working directory (read only).
Write NumPy record array rec to filename.
| Parameters : | filename : string
rec : record array
fmt : None | ‘csv’ | ‘xls’ | ‘txt’
lang : None | string
kwargs :
|
|---|
Class for running a case in a background thread.
This is a subclass of Case defining a few extra methods for dealing with threads.
BgCase objects must be subclassed or instantiated with a target. If you want to transfer data from a running BgCase instance to a calling framework, you can use the Queue module documented in https://docs.python.org/2/library/queue.html.
Returns whether this is a daemon thread. The entire Python program exists when no more alive non-daemon threads are left.
Wait until the thread terminates.
This blocks the calling thread until the thread whose join() method is called terminates – either normally or through an unhandled exception or until the optional timeout occurs.
When the timeout argument is present and not None, it should be a floating point number specifying a timeout for the operation in seconds (or fractions thereof). As join() always returns None, you must call isAlive() after join() to decide whether a timeout happened – if the thread is still alive, the join() call timed out.
When the timeout argument is not present or None, the operation will block until the thread terminates.
A thread can be join()ed many times.
join() raises a RuntimeError if an attempt is made to join the current thread as that would cause a deadlock. It is also an error to join() a thread before it has been started and attempts to do so raises the same exception.
The status after program execution returned by Case.execute().
It has the following attributes: