API Reference

dotpath.get_path(obj: object, dotpath: str, default=None, **kwargs)

Return a value from an object using a dot-delimited path.

This function traverses mappings, sequences, and attributes using the keys or indexes found in dotpath. For sequences (list, tuple, set), numeric indexes are converted to strings internally. getpath is an alias of this function.

Example:

data = {"pets": {"dog": {"name": "Billy"}}}
name = getpath(data, "pets.dog.name")
Parameters:

  • obj – The object, mapping, or sequence to traverse.

  • dotpath – Dot-delimited path (e.g. "a.b.0.c").

  • default – Value returned when traversal fails.

  • kwargs – Optional settings.

  • raise_exception (bool) – If True, re-raise the underlying exception instead of returning default.

Returns:

The resolved value or default if not found.

Return type:

object

Raises:

  • AttributeError – When raise_exception is True and an attribute is missing.

  • KeyError – When raise_exception is True and a key is missing.

  • IndexError – When raise_exception is True and an index is out of range.

dotpath.getpath(obj: object, dotpath: str, default=None, **kwargs)

Wrapper for get_path().

This exists for backward compatibility with earlier releases.

dotpath.set_path(obj: object, dotpath: str, value, default=None, **kwargs)

Set a value on an object using a dot-delimited path.

This function traverses mappings, sequences, and attributes using the keys or indexes found in dotpath. When a child is missing, a new dict is created by default. setpath is an alias of this function.

Example:

data = {}
setpath(data, "pets.dog.name", "Billy")
# data == {"pets": {"dog": {"name": "Billy"}}}
Parameters:

  • obj – The object, mapping, or sequence to mutate.

  • dotpath – Dot-delimited path (e.g. "a.b.0.c").

  • value – Value to assign at the resolved path.

  • default – Value returned when traversal fails.

  • kwargs – Optional settings.

  • create_child (bool) – If True (default), create missing children as dict.

  • raise_exception (bool) – If True, re-raise the underlying exception instead of returning default.

Returns:

The mutated root object or default if it fails.

Return type:

object

Raises:

  • AttributeError – When raise_exception is True and an attribute is missing.

  • KeyError – When raise_exception is True and a key is missing.

  • IndexError – When raise_exception is True and an index is out of range.

  • TypeError – When raise_exception is True and a value cannot be set on the current object.

  • ValueError – When raise_exception is True and a list index is not an integer.

dotpath.setpath(obj: object, dotpath: str, value, default=None, **kwargs)

Wrapper for set_path().

This exists for backward compatibility with earlier releases.