natcap.invest.iui package

Submodules

natcap.invest.iui.base_widgets module

natcap.invest.iui.cli module

Single entry point for all InVEST applications.

natcap.invest.iui.cli.iui_dir()

Return the path to the IUI folder.

natcap.invest.iui.cli.list_models()

List all models that have .json files defined in the iui dir.

Returns:A sorted list of model names.
natcap.invest.iui.cli.load_config()

Load configuration options from a config file and assume defaults if they aren’t there.

natcap.invest.iui.cli.main()

Single entry point for all InVEST model user interfaces.

This function provides a CLI for calling InVEST models, though it it very primitive. Apart from displaying a help messsage and the version, this function will also (optionally) list the known models (based on the found json filenames) and will fire up an IUI interface based on the model name provided.

natcap.invest.iui.cli.print_models()

Pretty-print available models.

natcap.invest.iui.cli.write_console_files(out_dir, extension)

Write out console files for each of the target models to the output dir.

Parameters:
  • out_dir – The directory in which to save the console files.
  • extension – The extension of the output files (e.g. ‘bat’, ‘sh’)
Returns:

Nothing. Writes files to out_dir, though.

natcap.invest.iui.executor module

executor module for natcap.invest.iui

class natcap.invest.iui.executor.Controller

Bases: object

The Controller class manages two Thread objects: Executor and PrintQueueChecker. Executor runs models and queues up print statements in a local printqueue list. Printqueue checks on Executor’s printqueue and fetches the next message at a specified interval.

The printqueuechecker exists to offload the work of list-related operations from the main thread, which leaves the main thread free to perform UI-related tasks.

add_operation(op, args=None, uri=None, index=None)

Wrapper method for Executor.addOperation. Creates new executor and message checker thread instances if necessary.

Returns nothing.

cancel_executor()

Trigger the executor’s cancel event. Returns nothing.

finished()

Set the executor and message checker thread objects to none and set the thread_finished variable to True.

Returns nothing.

get_message()

Check to see if the message checker thread is alive and returns the current message if so. If the message checker thread is not alive, None is returned and self.finished() is called.

is_finished()

Returns True if the threads are finished. False if not.

start_executor()

Starts the executor and message checker threads. Returns nothing.

class natcap.invest.iui.executor.Executor

Bases: threading.Thread

addOperation(op, args=None, uri=None, index=None)
cancel()
flush()
format_time(seconds)

Render the integer number of seconds in a string. Returns a string.

getMessage()
hasMessages()
isCancelled()
isThreadFailed()
printTraceback()
print_args(args_dict)
Write args_dict to a formatted string to the self.write() function.
args_dict - a dictionary.

returns noting

print_system_info(function=None)
run()
runModel(module, args)
runValidator(uri, args)
saveParamsToDisk(data=None)
setThreadFailed(state, exception=None)

Set the flag of whether the thread has failed. exception should be a pointer to a python Exception or a boolean.

write(string)
exception natcap.invest.iui.executor.InsufficientDiskSpace

Bases: exceptions.Exception

This class is to be used if certain WindowsErrors or IOErrors are encountered.

class natcap.invest.iui.executor.PrintQueueChecker(executor_object)

Bases: threading.Thread

PrintQueueChecker is a thread class that checks on a specified executor thread object. By placing the responsibility of this operation in a separate thread, we allow the main thread to attend to more pressing UI related tasks.

get_message()

Check to see if there is a new message available.

Returns the string message, if one is available. None if not.

run()

Fetch messages as long as the executor is alive or has messages.

This method is reimplemented from threading.Thread and is started by calling self.start().

This function calls the executor object function getMessage(), which uses the collections.deque queue object to manage the printqueue.

The new message is only fetched from the executor if the main thread has fetched the current message from this PrintQueueChecker instance.

returns nothing.

natcap.invest.iui.executor.locate_module(module_list, path=None)

Search for and return an executable module object as long as the target module is within the pythonpath. This method recursively uses the find_module and load_module functions of the python imp module to locate the target module by its heirarchical module name.

module_list - a python list of strings, where each element is the name
of a contained module. For example, os.path would be represented here as [‘os’, ‘path’].
path=None - the base path to search. If None, the pythonpath will be
used.

returns an executeable python module object if it can be found. Returns None if not.

natcap.invest.iui.fileio module

InVEST fileio module

class natcap.invest.iui.fileio.AbstractTableHandler(uri)

Bases: object

This class provides an abstract class for specific reimplementation for each tabular filetype

__iter__()

Reimplemented, allows the user to iterate through an instance of AbstractTableHandler without actually returning self.table. Having this function allows this class to actually be iterable.

get_fieldnames(case='lower')

Returns a python list of the original fieldnames, true to their original case.

case=’lower’ - a python string representing the desired status of the
fieldnames. ‘lower’ for lower case, ‘orig’ for original case.

returns a python list of strings.

get_file_object()

Getter function for the underlying file object. If the file object has not been retrieved, retrieve it before returning the file object.

returns a file object.

get_map(key_field, value_field)

Returns a python dictionary mapping values contained in key_field to values contained in value_field. If duplicate keys are found, they are overwritten in the output dictionary.

This is implemented as a dictionary comprehension on top of self.get_table_list(), so there shouldn’t be a need to reimplement this for each subclass of AbstractTableHandler.

If the table list has not been retrieved, it is retrieved before generating the map.

key_field - a python string. value_field - a python string.

returns a python dictionary mapping key_fields to value_fields.

get_table_dictionary(key_field)

Returns a python dictionary mapping a key value to all values in that particular row dictionary (including the key field). If duplicate keys are found, the are overwritten in the output dictionary.

key_field - a python string of the desired field value to be used as
the key for the returned dictionary.

returns a python dictionary of dictionaries.

get_table_row(key_field, key_value)

Return the first full row where the value of key_field is equivalent to key_value. Raises a KeyError if key_field does not exist.

key_field - a python string. key_value - a value of appropriate type for this field.

returns a python dictionary of the row, or None if the row does not exist.

set_field_mask(regexp=None, trim=0)

Set a mask for the table’s self.fieldnames. Any fieldnames that match regexp will have trim number of characters stripped off the front.

regexp=None - a python string or None. If a python string, this
will be a regular expression. If None, this represents no regular expression.

trim - a python int.

Returns nothing.

update(uri)

Update the URI associated with this AbstractTableHandler object. Updating the URI also rebuilds the fieldnames and internal representation of the table.

uri - a python string target URI to be set as the new URI of this
AbstractTableHandler.

Returns nothing.

class natcap.invest.iui.fileio.CSVHandler(uri)

Bases: natcap.invest.iui.fileio.AbstractTableHandler

class natcap.invest.iui.fileio.DBFHandler(uri)

Bases: natcap.invest.iui.fileio.AbstractTableHandler

class natcap.invest.iui.fileio.JSONHandler(uri)

Bases: object

delete()
get_attributes()
write_to_disk(dict)
class natcap.invest.iui.fileio.LastRunHandler(modelname, version=None)

Bases: natcap.invest.iui.fileio.JSONHandler

class natcap.invest.iui.fileio.OGRHandler(uri)

Bases: natcap.invest.iui.fileio.AbstractTableHandler

class natcap.invest.iui.fileio.ResourceHandler(resource_dir)

Bases: natcap.invest.iui.fileio.JSONHandler

This class allows actually handles reading a resource handler file from disk.

check(dictionary=None)

Iterate through all nested key-value pairs in this resource file and print an error message if the file cannot be found. Returns nothing.

icon(icon_key)

Fetch the URI based on the icon_key. If the key is not found, raises a keyError.

icon_key - a python string key to be accessed from the resources
file.

Returns an absolute path to the resource.

class natcap.invest.iui.fileio.ResourceManager(user_resource_dir='')

Bases: object

ResourceManager reconciles overrides supplied by the user against the default values saved to the internal iui_resources resource file. It adheres to the ResourceInterface interface and will print messages to stdout when defaulting to iui’s internal resources.

icon(icon_key)

Return the appropriate icon path based on the path returned by the user’s resource file and the path returned by the default resource file. Defaults are used if the specified python string key cannot be found in the user_resources file

icon_key - a python string key for the desired icon.

Returns a python string.

natcap.invest.iui.fileio.find_handler(uri)

Attempt to open the file provided by uri.

uri - a string URI to a table on disk.

returns the appropriate file’s Handler. Returns None if an appropriate handler cannot be found.

natcap.invest.iui.fileio.save_model_run(arguments, module, out_file)

Save an arguments list and module to a new python file that can be executed on its own.

arguments - a python dictionary of arguments. module - the python module path in python package notation (e.g.

natcap.invest.pollination.pollination)
out_file - the file to which the output file should be written. If the
file exists, it will be overwritten.

This function returns nothing.

natcap.invest.iui.fileio.save_model_run_json(arguments, module, out_file)
natcap.invest.iui.fileio.settings_folder()

Return the file location of the user’s settings folder. This folder location is OS-dependent.

natcap.invest.iui.iui_validator module

This module provides validation functionality for the IUI package. In a nutshell, this module will validate a value if given a dictionary that specifies how the value should be validated.

class natcap.invest.iui.iui_validator.CSVChecker

Bases: natcap.invest.iui.iui_validator.TableChecker

open(valid_dict)

Attempt to open the CSV file

class natcap.invest.iui.iui_validator.Checker

Bases: natcap.invest.iui.registrar.Registrar

The Checker class defines a superclass for all classes that actually perform validation. Specific subclasses exist for validating specific features. These can be broken up into two separate groups based on the value of the field in the UI:

  • URI-based values (such as files and folders)
    • Represented by the URIChecker class and its subclasses
  • Scalar values (such as strings and numbers)
    • Represented by the PrimitiveChecker class and its subclasses
There are two steps to validating a user’s input:

  • First, the user’s input is preprocessed by looping through a list of operations. Functions can be added to this list by calling self.add_check_function(). All functions that are added to this list must take a single argument, which is the entire validation dictionary. This is useful for guaranteeing that a given function is performed (such as opening a file and saving its reference to self.file) before any other validation happens.

  • Second, the user’s input is validated according to the validation dictionary in no particular order. All functions in this step must take a single argument which represents the user-defined value for this particular key.

    For example, if we have the following validation dictionary:
    valid_dict = {‘type’: ‘OGR’,

    ‘value’: ‘/tmp/example.shp’, ‘layers: [{layer_def ...}]}

    The OGRChecker class would expect the function associated with the ‘layers’ key to take a list of python dictionaries.

add_check_function(func, index=None)

Add a function to the list of check functions.

func - A function. Must accept a single argument: the entire
validation dictionary for this element.
index=None - an int. If provided, the function will be inserted
into the check function list at this index. If no index is provided, the check function will be appended to the list of check functions.

returns nothing

run_checks(valid_dict)

Run all checks in their appropriate order. This operation is done in two steps:

  • preprocessing

    In the preprocessing step, all functions in the list of check functions are executed. All functions in this list must take a single argument: the dictionary passed in as valid_dict.

  • attribute validation

    In this step, key-value pairs in the valid_dict dictionary are evaluated in arbitrary order unless the key of a key-value pair is present in the list self.ignore.

class natcap.invest.iui.iui_validator.DBFChecker

Bases: natcap.invest.iui.iui_validator.TableChecker

open(valid_dict, read_only=True)

Attempt to open the DBF.

class natcap.invest.iui.iui_validator.FileChecker

Bases: natcap.invest.iui.iui_validator.URIChecker

This subclass of URIChecker is tweaked to validate a file on disk.

In contrast to the FolderChecker class, this class validates that a specific file exists on disk.

open(valid_dict)

Checks to see if the file at self.uri can be opened by python.

This function can be overridden by subclasses as appropriate for the filetype.

Returns an error string if the file cannot be opened. None if otherwise.

class natcap.invest.iui.iui_validator.FlexibleTableChecker

Bases: natcap.invest.iui.iui_validator.TableChecker

This class validates a file in a generic ‘table’ format.

Currently, this supports DBF and CSV formats.

This class is essentially a wrapper that first determines which file format we’re dealing with, and then delegates the rest of the work to the appropriate Checker class for that specific file format.

open(valid_dict)

Attempt to open the file

class natcap.invest.iui.iui_validator.FolderChecker

Bases: natcap.invest.iui.iui_validator.URIChecker

This subclass of URIChecker is tweaked to validate a folder.

check_contents(files)

Verify that the files listed in files exist. Paths in files must be relative to the Folder path that we are validating. This function strictly validates the presence of these files.

files - a list of string file URIs, where each file is relative to
the Folder stored in self.uri.

Conforming with all Checker classes, this function returns a string error if one of the files does not exist or None if all required files are found.

check_exists(valid_dict)

Verify that the file at valid_dict[‘value’] exists. Reimplemented from URIChecker class to provide more helpful, folder-oriented error message.

class natcap.invest.iui.iui_validator.GDALChecker

Bases: natcap.invest.iui.iui_validator.FileChecker

This class subclasses FileChecker to provide GDAL-specific validation.

open(valid_dict)

Attempt to open the GDAL object. URI must exist. This is an overridden FileChecker.open()

Returns an error string if in error. Returns none otherwise.

class natcap.invest.iui.iui_validator.NumberChecker

Bases: natcap.invest.iui.iui_validator.PrimitiveChecker

greater_than(b)
greater_than_equal_to(b)
less_than(b)
less_than_equal_to(b)
class natcap.invest.iui.iui_validator.OGRChecker

Bases: natcap.invest.iui.iui_validator.TableChecker

check_layers(layer_list)

Attempt to open the layer specified in self.valid.

open(valid_dict)

Attempt to open the shapefile.

class natcap.invest.iui.iui_validator.PrimitiveChecker

Bases: natcap.invest.iui.iui_validator.Checker

check_regexp(valid_dict)

Check an input regular expression contained in valid_dict.

valid_dict - a python dictionary with the following structure: valid_dict[‘value’] - (required) a python string to be matched valid_dict[‘allowed_values’] - (required) a python dictionary with the

following entries:
valid_dict[‘allowed_values’][‘pattern’] - (‘required’) must match
one of the following formats:

  • A python string regular expression formatted according to the re module (http://docs.python.org/library/re.html)

  • A python list of values to be matched. These are treated as logical or (‘|’ in the built regular expression). Note that the entire input pattern will be matched if you use this option. For more fine-tuned matching, use the dict described below.

  • A python dict with the following entries:
    ‘values’ - (optional) a python list of strings that are

    joined by the ‘join’ key to create a single regular expression. If this a ‘values’ list is not provided, it’s assumed to be [‘.*’], which matches all patterns.

    ‘join’ - (optional) the character with which to join all

    provided values to form a single regular expression. If the ‘join’ value is not provided, it defaults to ‘|’, the operator for logical or.

    ‘sub’ - (optional) a string on which string substitution

    will be performed for all elements in the ‘values’ list. If this value is not provided, it defaults to ‘^%s$’, which causes the entire string to be matched. This string uses python’s standard string formatting operations: http://docs.python.org/library/stdtypes.html#string-formatting-operations but should only use a single ‘%s’

valid_dict[‘allowed_values’][‘flag’] - (optional) a python string
representing one of the python re module’s available regexp flags. Available values are: ‘ignoreCase’, ‘verbose’, ‘debug’, ‘locale’, ‘multiline’, ‘dotAll’. If a different string is provided, no flags are applied to the regular expression matching.
example valid_dicts:

# This would try to match ‘[a-z_]* in ‘sample_string_pattern’ valid_dict = {‘value’ : ‘sample_string pattern’,

‘allowed_values’ : {‘pattern’: ‘[a-z_]*’}}

# This would try to match ‘^test$|^word$’ in ‘sample_list_pattern’ valid_dict = {‘value’ : ‘sample_list_pattern’,

‘allowed_values’: {‘pattern’: [‘test’, ‘word’]}}

# This would try to match ‘test.words’ in sample_dict_pattern valid_dict = {‘value’ : ‘sample_dict_pattern’,

‘allowed_values’: {‘pattern’: {
‘values’: [‘test’, ‘words’], ‘join’: ‘.’, ‘sub’: ‘%s’}

This function builds a single regular expression string (if necessary) and checks to see if valid_dict[‘value’] matches that string. If not, a python string with an error message is returned. Otherwise, None is returned.

class natcap.invest.iui.iui_validator.TableChecker

Bases: natcap.invest.iui.iui_validator.FileChecker, natcap.invest.iui.iui_validator.ValidationAssembler

This class provides a template for validation of table-based files.

get_matching_fields(field_defn)
verify_fields_exist(field_list)

This is a function stub for reimplementation. field_list is a python list of strings where each string in the list is a required fieldname. List order is not validated. Returns the error string if an error is found. Returns None if no error found.

verify_restrictions(restriction_list)
class natcap.invest.iui.iui_validator.URIChecker

Bases: natcap.invest.iui.iui_validator.Checker

This subclass of Checker provides functionality for URI-based inputs.

check_exists(valid_dict)

Verify that the file at valid_dict[‘value’] exists.

check_permissions(permissions)

Verify that the URI has the given permissions.

permissions - a string containing the characters ‘r’ for readable,
‘w’ for writeable, and/or ‘x’ for executable. Multiple characters may be specified, and all specified permissions will be checked. ‘rwx’ will check all 3 permissions. ‘rx’ will check only read and execute. ‘’ will not check any permissions.

Returns a string with and error message, if one is found, or else None.

class natcap.invest.iui.iui_validator.ValidationAssembler

Bases: object

This class allows other checker classes (such as the abstract TableChecker class) to assemble sub-elements for evaluation as primitive values. In other words, if an input validation dictionary contains two fields in a table, the ValidationAssembler class provides a framework to fetch the value from the table.

assemble(value, valid_dict)

Assembles a dictionary containing the input value and the assembled values.

class natcap.invest.iui.iui_validator.ValidationThread(validate_funcs, type_checker, valid_dict)

Bases: threading.Thread

This class subclasses threading.Thread to provide validation in a separate thread of control. Functionally, this allows the work of validation to be offloaded from the user interface thread, thus providing a snappier UI. Generally, this thread is created and managed by the Validator class.

get_error()

Returns a tuple containing the error message and the error state, both being python strings. If no error message is present, None is returned.

run()

Reimplemented from threading.Thread.run(). Performs the actual work of the thread.

set_error(error, state='error')

Set the local variable error_msg to the input error message. This local variable is necessary to allow for another thread to be able to retrieve it from this thread object.

error - a string. state - a python string indicating the kind of message being

reported (e.g. ‘error’ or ‘warning’)

returns nothing.

class natcap.invest.iui.iui_validator.Validator(validator_type)

Bases: natcap.invest.iui.registrar.Registrar

Validator class contains a reference to an object’s type-specific checker. It is assumed that one single iui input element will have its own validator.

Validation can be performed at will and is performed in a new thread to allow other processes (such as the UI) to proceed without interruption.

Validation is available for a number of different values: files of various types (see the FileChecker and its subclasses), strings (see the PrimitiveChecker class) and numbers (see the NumberChecker class).

element - a reference to the element in question.

get_error()

Gets the error message returned by the validator.

Returns a tuple with (error_state, error_message). Tuple is (None, None) if no error has been found or if the validator thread has not been created.

init_type_checker(validator_type)

Initialize the type checker based on the input validator_type.

validator_type - a string representation of the validator type.

Returns an instance of a checker class if validator_type matches an
existing checker class. Returns None otherwise.
thread_finished()

Check to see whether the validator has finished. This is done by calling the active thread’s is_alive() function.

Returns a boolean. True if the thread is alive.

validate(valid_dict)

Validate the element. This is a two step process: first, all functions in the Validator’s validateFuncs list are executed. Then, The validator’s type checker class is invoked to actually check the input against the defined restrictions.

Note that this is done in a separate thread.

returns a string if an error is found. Returns None otherwise.

natcap.invest.iui.iui_validator.get_fields(feature)

Return a dict with all fields in the given feature.

feature - an OGR feature.

Returns an assembled python dict with a mapping of fieldname -> fieldvalue

natcap.invest.iui.modelui module

natcap.invest.iui.modelui_test module

natcap.invest.iui.registrar module

class natcap.invest.iui.registrar.DatatypeRegistrar

Bases: natcap.invest.iui.registrar.Registrar

eval(mapKey, opValues)
class natcap.invest.iui.registrar.Registrar

Bases: object

eval(mapKey, opValues)
get_func(mapKey)
update_map(updates)

natcap.invest.iui.usage_logger module

Functions to assist with remote logging of InVEST usage.

class natcap.invest.iui.usage_logger.LoggingServer(database_filepath)

Bases: object

RPC server for logging invest runs and getting database summaries.

get_run_summary_db()

Retrieve the raw sqlite database of runs as a binary stream.

log_invest_run(data, mode)

Log some parameters of an InVEST run.

Metadata is saved to a new record in the sqlite database found at self.database_filepath. The mode specifies if it is a log or an exit status notification. The appropriate table name and fields will be used in that case.

Parameters:
  • data (dict) – a flat dictionary with data about the InVEST run where the keys of the dictionary are at least self._LOG_FIELD_NAMES
  • mode (string) – one of ‘log’ or ‘exit’. If ‘log’ uses self._LOG_TABLE_NAME and parameters, while ‘exit’ logs to self._LOG_EXIT_TABLE_NAME
Returns:

None
natcap.invest.iui.usage_logger.execute(args)

Function to start a remote procedure call server.

Parameters:
  • args['database_filepath'] (string) – local filepath to the sqlite database
  • args['hostname'] (string) – network interface to bind to
  • args['port'] (int) – TCP port to bind to
Returns:

never

Module contents

natcap.invest.iui.get_ui_logger(name)