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 descriptions of the options

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 ARGS_SPEC dict to a JSON string.

Parameters

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

Raises

  • TypeError if any object type within the spec is not handled by –

  • json.dumps or by the fallback serializer. –

Returns

JSON String