natcap.invest.validation

Common validation utilities for InVEST models.

natcap.invest.validation.CHECK_ALL_KEYS = None

A flag to pass to the validation context manager indicating that all keys should be checked.

natcap.invest.validation.check_boolean(value)

Validate a boolean value.

If the value provided is not a python boolean, an error message is returned.

Parameters

value – The value to evaluate.

Returns

A string error message if an error was found. None otherwise.

natcap.invest.validation.check_csv(filepath, required_fields=None, excel_ok=False)

Validate a table.

Parameters
  • filepath (string) – The string filepath to the table.

  • required_fields=None (list) – A case-insensitive list of fieldnames that must exist in the table. If None, fieldnames will not be checked.

  • excel_ok=False (boolean) – Whether it’s OK for the file to be an Excel table. This is not a common case.

Returns

A string error message if an error was found. None otherwise.

natcap.invest.validation.check_directory(dirpath, exists=False, permissions='rx')

Validate a directory.

Parameters
  • dirpath (string) – The directory path to validate.

  • exists=False (bool) – If True, the directory at dirpath must already exist on the filesystem.

  • permissions='rx' (string) – A string that includes the lowercase characters r, w and/or x indicating required permissions for this folder . See check_permissions for details.

Returns

A string error message if an error was found. None otherwise.

natcap.invest.validation.check_file(filepath, permissions='r')

Validate a single file.

Parameters
  • filepath (string) – The filepath to validate.

  • permissions='r' (string) – A string that includes the lowercase characters r, w and/or x indicating required permissions for this file. See check_permissions for details.

Returns

A string error message if an error was found. None otherwise.

natcap.invest.validation.check_freestyle_string(value, regexp=None)

Validate an arbitrary string.

Parameters
  • value – The value to check. Must be able to be cast to a string.

  • regexp=None (dict) – A dict representing validation parameters for a regular expression. regexp['pattern'] is required, and its value must be a string regular expression. regexp['case_sensitive'] may also be provided and is expected to be a boolean value. If True or truthy, the regular expression will ignore case.

Returns

A string error message if an error was found. None otherwise.

natcap.invest.validation.check_number(value, expression=None)

Validate numbers.

Parameters
  • value – A python value. This should be able to be cast to a float.

  • expression=None (string) – A string expression to be evaluated with the intent of determining that the value is within a specific range. The expression must contain the string value, which will represent the user-provided value (after it has been cast to a float). Example expression: "(value >= 0) & (value <= 1)".

Returns

A string error message if an error was found. None otherwise.

natcap.invest.validation.check_option_string(value, options)

Validate that a string is in a list of options.

Parameters
  • value (string) – The string value to test.

  • options (list) – A list of strings to test against.

Returns

A string error message if value is not in options. None otherwise.

natcap.invest.validation.check_permissions(path, permissions)

Validate permissions on a filesystem object.

This function uses os.access to determine permissions access.

Parameters
  • path (string) – The path to examine for permissions.

  • permissions (string) – a string including the characters r, w and/or x (lowercase), indicating read, write, and execute permissions (respectively) that the filesystem object at path must have.

Returns

A string error message if an error was found. None otherwise.

natcap.invest.validation.check_raster(filepath, projected=False, projection_units=None)

Validate a GDAL Raster on disk.

Parameters
  • filepath (string) – The path to the raster on disk. The file must exist and be readable.

  • projected=False (bool) – Whether the spatial reference must be projected in linear units.

  • projection_units=None (string) – The string label (case-insensitive) indicating the required linear units of the projection. If None, the projection units will not be checked.

Returns

A string error message if an error was found. None otherwise.

natcap.invest.validation.check_spatial_overlap(spatial_filepaths_list, different_projections_ok=False)

Check that the given spatial files spatially overlap.

Parameters
  • spatial_filepaths_list (list) – A list of files that can be opened with GDAL. Must be on the local filesystem.

  • different_projections_ok=False (bool) – Whether it’s OK for the input spatial files to have different projections. If True, all projections will be converted to WGS84 before overlap is checked.

Returns

A string error message if an error is found. None otherwise.

natcap.invest.validation.check_vector(filepath, required_fields=None, projected=False, projection_units=None)

Validate a GDAL vector on disk.

Note

If the provided vector has multiple layers, only the first layer will be checked.

Parameters
  • filepath (string) – The path to the vector on disk. The file must exist and be readable.

  • required_fields=None (list) – The string fieldnames (case-insensitive) that must be present in the vector layer’s table. If None, fieldnames will not be checked.

  • projected=False (bool) – Whether the spatial reference must be projected in linear units. If None, the projection will not be checked.

  • projection_units=None (string) – The string label (case-insensitive) indicating the required linear units of the projection. If None, the projection units will not be checked.

Returns

A string error message if an error was found. None otherwise.

natcap.invest.validation.get_invalid_keys(validation_warnings)

Get the invalid keys from a validation warnings list.

Parameters

validation_warnings (list) – A list of two-tuples where the first item is an iterable of string args keys affected and the second item is a string error message.

Returns

A set of the string args keys found across all of the first elements in the validation tuples.

natcap.invest.validation.get_sufficient_keys(args)

Determine which keys in args are sufficient.

A sufficient key is one that is:

  1. Present within args

  2. Does not have a value of '' or None.

Parameters

args (dict) – An args dict of string keys to serializeable values.

Returns

A set of keys from args that are sufficient.

natcap.invest.validation.invest_validator(validate_func)

Decorator to enforce characteristics of validation inputs and outputs.

Attributes of inputs and outputs that are enforced are:

  • args parameter to validate must be a dict

  • limit_to parameter to validate must be either None or a string (str or unicode) that exists in the args dict.

  • All keys in args must be strings

  • Decorated validate func must return a list of 2-tuples, where each 2-tuple conforms to these rules:

    • The first element of the 2-tuple is an iterable of strings. It is an error for the first element to be a string.

    • The second element of the 2-tuple is a string error message.

In addition, this validates the n_workers argument if it’s included.

Raises

AssertionError when an invalid format is found.

Example:

from natcap.invest import validation
@validation.invest_validator
def validate(args, limit_to=None):
    # do your validation here
natcap.invest.validation.load_fields_from_vector(filepath, layer_id=0)

Load fieldnames from a given vector.

Parameters
  • filepath (string) – The path to a GDAL-compatible vector on disk.

  • layer_id=0 (string or int) – The identifier for the layer to use.

Returns

A list of string fieldnames within the target layer.

natcap.invest.validation.timeout(func, *args, timeout=5, **kwargs)

Stop a function after a given amount of time.

Parameters
  • func (function) – function to apply the timeout to

  • args – arguments to pass to the function

  • timeout (number) – how many seconds to allow the function to run. Defaults to 5.

Returns

A string warning message if the thread completed in time and returned warnings, None otherwise.

Raises

RuntimeWarning` if the thread does not complete in time

natcap.invest.validation.validate(args, spec, spatial_overlap_opts=None)

Validate an args dict against a model spec.

Validates an arguments dictionary according to the rules laid out in spec. If spatial_overlap_opts is also provided, valid spatial inputs will be checked for spatial overlap.

Parameters
  • args (dict) – The InVEST model args dict to validate.

  • spec (dict) – The InVEST model spec dict to validate against.

  • spatial_overlap_opts=None (dict) – A dict. If provided, the key

  • is required to be a list of keys that may be present ("spatial_keys") – in the args dict and (if provided in args) will be checked for overlap with all other keys in this list. If the key "reference_key" is also present in this dict, the bounding boxes of each of the files represented by spatial_overlap_opts["spatial_keys"] will be transformed to the SRS of the dataset at this key.

Returns

A list of tuples where the first element of the tuple is an iterable of keys affected by the error in question and the second element of the tuple is the string message of the error. If no validation errors were found, an empty list is returned.