Utility Classes & Functions¶

The indigo.utils module collects several things that aren't directly tied to a specific Indigo object but are helpful when writing scripts and building plugins. Everything below is reached through the indigo.utils. prefix from any Indigo Python script or plugin (e.g. indigo.utils.ValidationError).

Classes¶

Name	Base	Description
`IndigoJSONEncoder`	`json.JSONEncoder`	A JSON encoder that converts Python `date`/`datetime` objects (and `NaN`) so they can be serialized. Very useful when encoding a device dictionary into JSON: `json.dumps(dict(my_device), cls=indigo.utils.IndigoJSONEncoder)`. The original name `JSONDateEncoder` is still available as an alias.
`ValidationError`	`Exception`	An exception for reporting validation problems. It can carry a single summary message or a whole dictionary of field-specific errors. See ValidationError below.

IndigoJSONEncoder¶

By default the Python json module can't serialize datetime objects. Pass this encoder as the cls argument to a JSON dump call and any date/datetime encountered during encoding is converted to its ISO string. Indigo constants (e.g. indigo.kFanMode.Auto) are encoded as their full string representation so they can be reconstituted later.

import json
my_device = indigo.devices[123456]
print(json.dumps(dict(my_device), indent=4, cls=indigo.utils.IndigoJSONEncoder))

ValidationError¶

ValidationError is primarily used when validating fields for commands, messages, or Config UIs, but it can carry any kind of validation result. The simplest use is to raise it with a string and let the caller str() it. For more involved cases it holds a dictionary of field names (or keys), each mapped to a single error string or a list of error strings, so the caller can process individual errors — for example to mark the offending fields when validating a Config UI.

Constructor

indigo.utils.ValidationError(message, error_state_str=None, error_dict=None)

Parameter	Required	Type	Description
`message`	Yes	string	A general message summarizing the entire validation. Useful for logging.
`error_state_str`	No	string	If the validation represents a device state issue, this string is used as the device's error state in the various UIs. Pass an empty string to clear any existing error.
`error_dict`	No	dict	A dictionary of field names mapped to error message(s) — each value may be a single string or a list of strings.

Attributes

Attribute	Type	Description
`error_message`	string	The general summary message passed to the constructor.
`error_state_str`	string or None	The optional device error-state string.
`error_dict`	dict	The dictionary of field/key → error message(s).

Methods

Method	Description
`add_error(key, description)`	Add an error for `key` (e.g. a field name). `description` can be a single string or a list of strings. If the key already has an error, the new message is appended (the value becomes a list).
`remove_error(key)`	Remove and return all error message(s) for `key`. Note that this removes the entire key, including any multiple messages.
`raise_if_errors()`	Raise this exception if there is anything to report — i.e. if `error_dict` is non-empty or `error_state_str` is not `None`. Otherwise does nothing.

A ValidationError is also iterable: calling dict(my_validation_error) yields the contents of error_dict. And str(my_validation_error) produces a human-readable summary that includes the general message followed by the formatted error details.

Example

# Accumulate field errors, then raise only if something failed.
errors = indigo.utils.ValidationError("Sensor configuration is invalid")
if not values.get("address"):
    errors.add_error("address", "You must enter an address.")
if not indigo.utils.is_int(values.get("pollInterval", "")):
    errors.add_error("pollInterval", "Poll interval must be a whole number.")

errors.raise_if_errors()   # raises only if at least one error was added

For a worked example of turning a ValidationError into the error dictionary a Config UI validation method returns, see Validation Methods.

Functions¶

Return Static File¶

Accepts a file path and an optional content type and returns the correctly structured indigo.Dict that the Indigo Web Server (IWS) interprets as a directive to stream the specified file back to the caller. This avoids returning a large amount of data through the plugin IPC mechanism.

Command Syntax Examples

indigo.utils.return_static_file("some/relative/path/to/file.txt")
indigo.utils.return_static_file("/some/path/to/file.json", status=400, path_is_relative=False, content_type="application/json")

Parameters

Parameter	Required	Type	Description
`file_path`	Yes	string or list	A string path to the file, or a list of path parts ending in the file name.
`status`	No	int	The HTTP status code to return. Defaults to `200`.
`path_is_relative`	No	boolean	`True` if the path is relative to the Indigo install folder, `False` for a complete file path. Defaults to `True`.
`content_type`	No	string	The MIME type for the `Content-Type` header. If omitted, an appropriate type is chosen from the file extension.

The returned indigo.Dict can be passed directly back to IWS from an HTTP processing call in your plugin. It looks something like this:

{
    "status": 404,
    "headers": {
        "Content-Type": "text/html"
    },
    "file_path": "/Library/Application Support/Perceptive Automation/Indigo 2025.2/Plugins/Example HTTP Responder.indigoPlugin/Contents/Resources/static/html/static_404.html"
}

IWS uses this to create the HTTP reply that streams the file back to the caller. The function raises a FileNotFoundError if the file doesn't exist, or a TypeError if file_path isn't a list of path parts or a string.

Validate Email Address¶

Accepts an email address string and returns True if it is constructed correctly, False otherwise. Note: it only checks that the address is formatted correctly — it does not verify that the address exists on the destination system.

Command Syntax Examples

indigo.utils.validate_email_address("[email protected]")   # True
indigo.utils.validate_email_address("invalid address")             # False

Parameters

Parameter	Required	Type	Description
`address`	Yes	string	A string that represents an email address.

Boolean Functions¶

Two functions help convert and use strings that represent boolean values but aren't literally True/False. Both use the following map (and its reverse):

BOOL_MAP_TRUE = {
    "y": "n",
    "yes": "no",
    "t": "f",
    "true": "false",
    "on": "off",
    "1": "0",
    "open": "closed",
    "locked": "unlocked",
}

str_to_bool(val) converts the supplied string to a boolean. It returns True for true values (y, yes, t, true, on, 1, open, locked), False for the corresponding false values, and raises a ValueError if the input can't be converted. A bool passed in is returned unchanged.

indigo.utils.str_to_bool("closed")   # False
indigo.utils.str_to_bool("on")       # True

reverse_bool_str_value(val) returns the string representing the opposite boolean value using the map above. It raises a ValueError if the input can't be found.

indigo.utils.reverse_bool_str_value("closed")   # "open"

Parameter	Required	Type	Description
`val`	Yes	string	A string that represents a boolean value as mapped above.

Is Integer¶

Accepts any value and returns True if it is an integer or can be cast to one, False otherwise. Handy for validating user-entered Config UI fields, which arrive as strings.

indigo.utils.is_int("42")     # True
indigo.utils.is_int("3.5")    # False
indigo.utils.is_int("abc")    # False

Parameter	Required	Type	Description
`value`	Yes	any	Any Python object to test.

Converting indigo.Dict and indigo.List¶

The indigo.utils module also attaches convenience methods to the indigo.Dict and indigo.List classes that recursively convert them to their native Python counterparts:

python_dict = my_indigo_dict.to_dict()   # recursively convert an indigo.Dict to a python dict
python_list = my_indigo_list.to_list()   # recursively convert an indigo.List to a python list

These are the same conversions used when you call dict() on an Indigo object. For the full picture of how a device is represented as a dictionary, see Dictionary Representation.