API

class forestwalker.Walker(root: Any)

Bases: object

A Walker is a pointer to a particular node of the tree, or possible a missing child node. It also remembers the path to the node.

parent: Walker | None = None

Walker of the parent node. Used to reconstruct the path.

obj: Any

The tree node. MissingValue if it is a missing node.

raise_error(msg) → NoReturn

Raise a WalkerError on the current node with the given error message.

is_null() → bool

Tests if the current node is None (JSON null).

is_str() → bool

Tests if the current node is a string.

is_int() → bool

Tests if the current node is an integer.

is_number() → bool

Tests if the current node is an integer or float.

is_bool() → bool

Tests if the current node is a Boolean value.

is_missing() → bool

Tests if the current node is a missing child.

is_present() → bool

Tests if the current node is not a missing child.

is_array() → bool

Tests if the current node is an array.

is_object() → bool

Tests if the current node is an object (dictionary).

expect_present() → Self

Raises an error if the current node is a missing child. Returns itself.

as_str(default: str | None = None) → str

If the current node is a string, returns its value. If it is missing and default is given, returns default. Otherwise raises WalkerError.

as_int(default: int | None = None) → int

If the current node is an integer, returns its value. If it is missing and default is given, returns default. Otherwise raises WalkerError.

as_float(default: float | None = None) → float

If the current node is a float, returns its value. If it is an integer, it is cast to a float. If it is missing and default is given, returns default. Otherwise raises WalkerError.

as_bool(default: bool | None = None) → bool

If the current node is a Boolean, returns its value. If it is missing and default is given, returns default. Otherwise raises WalkerError.

as_enum(enum: Type[E], default: E | None = None) → E

If the current node is a string, returns its value cast to the given enumeration type (descendant of Enum). If the node is missing and default is given, returns default. Otherwise raises WalkerError.

as_optional_str() → str | None

If the current node is a string, returns its value. If it is missing, returns None. Otherwise raises WalkerError.

as_optional_int() → int | None

If the current node is an integer, returns its value. If it is missing, returns None. Otherwise raises WalkerError.

as_optional_float() → float | None

If the current node is a float, returns its value. If it is an integer, it is cast to a float. If it is missing, returns None. Otherwise raises WalkerError.

as_optional_bool() → bool | None

If the current node is a Boolean, returns its value. If it is missing, returns None. Otherwise raises WalkerError.

array_values() → Iterator[WalkerInArray]

Produces an iterator over an array node, which yields WalkerInArray objects for the elements of the array. If the node is not an array, raises WalkerError.

object_values() → Iterator[WalkerInObject]

Produces an iterator over attributes of an object (dictionary), which yields WalkerInObject objects for the values of the attributes. If the node is not an object, raises WalkerError.

object_items() → Iterator[Tuple[str, WalkerInObject]]

Produces an iterator over attributes of an object (dictionary), which yields pairs of the attribute’s name and a WalkerInObject object for the attribute’s value. If the node is not an object, raises WalkerError.

enter_object() → ObjectWalker

Produces an ObjectWalker for an object (dictionary), which allows indexing of the object’s attributes and checking which attributes are missing. If the node is not an object, raises WalkerError.

default_to(default) → Walker

If the current node is missing, make the walker point to default instead. Returns itself, so it is possible to write e.g. walker.default_to([]).array_values().

context() → str

Construct a path fragment for the current node.

set_custom_context(ctx: str) → None

Set a string that is appended to the path fragment returned by context().

class forestwalker.WalkerInArray(obj: Any, parent: Walker, index: int)

Bases: Walker

A Walker referring to an array item. Never constructed directly, use Walker.array_items() to obtain it.

index: int

Position of the item in the array (zero-based).

class forestwalker.WalkerInObject(obj: Any, parent: Walker, key: str)

Bases: Walker

A Walker referring to an object attribute (dictionary item). Never constructed directly, use Walker.object_values(), Walker.object_items(), or indexing in ObjectWalker() to obtain it.

key: str

Key of the attribute.

unexpected() → NoReturn

Raises a WalkerError complaining that this key was not expected.

class forestwalker.ObjectWalker(obj: Any, parent: Walker)

Bases: Walker

A Walker for inspecting an object (dictionary). In addition to the default walker, it allows indexing of attribute by the square brackets operator. It also remembers which attributes were referenced this way and when used as a context manager, it complains upon exit from the context if the object contains unreferenced attributes.

Never constructed directly, use Walker.enter_object() to obtain it.

referenced_keys: Set[str]

A set of keys of referenced attributes.

assert_no_other_keys() → None

Checks if the object has attributes not accessed by the [] operator. Raises an WalkerError if there are any.

exception forestwalker.WalkerError(walker: Walker, msg: str)

Bases: Exception

An exception for any error occurring during walking the tree.

walker: Walker

The walker that raised the exception. Used to reconstruct the path to the erroneous node.

msg: str

Error message.