natcap.invest.spec_utils¶

natcap.invest.spec_utils.capitalize(title)¶

Capitalize a string into title case.

Parameters:: title (str) – string to capitalize
Returns:: capitalized string (each word capitalized except linking words)

natcap.invest.spec_utils.describe_arg_from_name(module_name, *arg_keys)¶

Generate RST documentation for an arg, given its model and name.

Parameters:

module_name (str) – invest model module containing the arg.
*arg_keys – one or more strings that are nested arg keys.

Returns:

String describing the arg in RST format. Contains an anchor named <arg_keys[0]>-<arg_keys[1]>…-<arg_keys[n]> where underscores in arg keys are replaced with hyphens.

natcap.invest.spec_utils.describe_arg_from_spec(name, spec)¶

Generate RST documentation for an arg, given an arg spec.

This is used for documenting:

a single top-level arg
a row or column in a CSV
a field in a vector
an item in a directory

Parameters:

name (str) – Name to give the section. For top-level args this is arg[‘name’]. For nested args it’s typically their key in the dictionary one level up.
spec (dict) – A arg spec dictionary that conforms to the InVEST args spec specification. It must at least have the key ‘type’, and whatever other keys are expected for that type.

Returns:

list of strings, where each string is a line of RST-formatted text. The first line has the arg name, type, required state, description, and units if applicable. Depending on the type, there may be additional lines that are indented, that describe details of the arg such as vector fields and geometries, option_string options, etc.

natcap.invest.spec_utils.format_geometries_string(geometries)¶

Represent a set of allowed vector geometries as user-friendly text.

Parameters:: geometries (set(str)) – set of geometry names
Returns:: string

natcap.invest.spec_utils.format_options_string_from_dict(options)¶

Represent a dictionary of option: description pairs as a bulleted list.

Parameters:: options (dict) – the dictionary of options to document, where keys are options and values are dictionaries describing the options. They may have either or both ‘display_name’ and ‘description’ keys, for example: {‘option1’: {‘display_name’: ‘Option 1’, ‘description’: ‘the first option’}}
Returns:: list of RST-formatted strings, where each is a line in a bullet list

natcap.invest.spec_utils.format_options_string_from_list(options)¶

Represent options as a comma-separated list.

Parameters:: options (list[str]) – the set of options to document
Returns:: string of comma-separated options

natcap.invest.spec_utils.format_permissions_string(permissions)¶

Represent a rwx-style permissions string as user-friendly text.

Parameters:: permissions (str) – rwx-style permissions string
Returns:: string

natcap.invest.spec_utils.format_required_string(required)¶

Represent an arg’s required status as a user-friendly string.

Parameters:: required (bool | str | None) – required property of an arg. May be True, False, None, or a conditional string.
Returns:: string

natcap.invest.spec_utils.format_type_string(arg_type)¶

Represent an arg type as a user-friendly string.

Parameters:: arg_type (str|set(str)) – the type to format. May be a single type or a set of types.
Returns:: formatted string that links to a description of the input type(s)

natcap.invest.spec_utils.format_unit(unit)¶

Represent a pint Unit as user-friendly unicode text.

This attempts to follow the style guidelines from the NIST Guide to the SI (https://www.nist.gov/pml/special-publication-811): - Use standard symbols rather than spelling out - Use ‘/’ to represent division - Use the center dot ‘ · ‘ to represent multiplication - Combine denominators into one, surrounded by parentheses

Parameters:: unit (pint.Unit) – the unit to format
Raises:: TypeError if unit is not an instance of pint.Unit. –
Returns:: String describing the unit.

natcap.invest.spec_utils.serialize_args_spec(spec)¶

Serialize an MODEL_SPEC dict to a JSON string.

Parameters:

spec (dict) – An invest model’s MODEL_SPEC.

Raises:

TypeError if any object type within the spec is not handled by –
json.dumps or by the fallback serializer. –

Returns:

JSON String