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 atdirpath
must already exist on the filesystem.permissions='rx' (string) – A string that includes the lowercase characters
r
,w
and/orx
indicating required permissions for this folder . Seecheck_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/orx
indicating required permissions for this file. Seecheck_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. IfTrue
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 inoptions
.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/orx
(lowercase), indicating read, write, and execute permissions (respectively) that the filesystem object atpath
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:
Present within
args
Does not have a value of
''
orNone
.
- 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 tovalidate
must be adict
limit_to
parameter tovalidate
must be eitherNone
or a string (str
orunicode
) that exists in theargs
dict.All keys in
args
must be stringsDecorated
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
. Ifspatial_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 byspatial_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.