Pointer

RConf pointer module.

rconf.pointer.Pointer can be implemented for different pointer types, with type-specific

• class method rconf.pointer.Pointer.parse() and

• method rconf.pointer.Pointer.__str__().

A rconf.pointer.Pointer can be fully resolved for a rconf.Value (rconf.pointer.Pointer.resolve()), or as far as possible (rconf.pointer.Pointer.reduce()). Optionally, resolution can be stopped at mappings containing certain keys, for example stop_keys=("$ref",).

rconf.pointer.traverse() implements post-order depth-first traversal of a rconf.Value.

rconf.pointer.Key

alias of Union[int, str]

class rconf.pointer.Pointer

A Pointer to a rconf.Value fragment.

It’s a hashable, iterable sequence of rconf.Key. The slash operator can be used to create child paths.

__init__(*keys)

Build a pointer from its keys, or copy a Pointer.

Parameters:

keys (Pointer | Key) –

Return type:

None

__str__()

Return str(self).

Return type:

str

property keys: tuple[rconf.Key, ...]

Get the internal representation of the pointer.

classmethod parse(ptr)

Pointer-specific parsing.

Raises:

PointerValueError for invalid pointer strings.

Parameters:

ptr (str) –

Return type:

rconf.pointer.Pointer

reduce(value, *, parent=None, key=None, stop_keys=None)

Reduce the pointer by following the path as far as possible.

Parameters:

• value (Value) – The configuration.

• parent (Value | None) – The parent of the target.

• key (Key | None) – The key for the target in parent.

• stop_keys (Iterable[Key] | None) – Don’t cross a mapping if it contains any of the listed keys.

Returns:

The reduced (parent, key, value, pointer) tuple.

Return type:

tuple[Value | None, Key | None, Value, Pointer]

resolve(value, *, stop_keys=None)

Resolve the pointer in a configuration.

Parameters:

• value (Value) – The configuration.

• stop_keys (Iterable[Key] | None) – Don’t cross a mapping if it contains any of the listed keys.

Returns:

The value.

Raises:

PointerLookupError if the pointer path is not present in the configuration.

Return type:

Value

rconf.pointer.traverse(value, *, leafs=True, dicts=True, lists=True, parent=None, key=None, pointer_type=<class 'rconf.pointer.Pointer'>)

Post-order depth-first traversal of a configuration.

Iterates over (pointer, parent, key, value) tuple s.

Parameters:

• value (Value) – The configuration to traverse.

• leafs (bool) – Include rconf.Leaf s.

• dicts (bool) – Include dict s.

• lists (bool) – Include list s.

• parent (Value | None) – The parent of value.

• key (Key | None) – The key for value in parent.

• pointer_type (type[Pointer]) – Pointer subclass to use.

Return type:

Iterator[tuple[Pointer, Value | None, Key | None, Value]]

Language-specific pointers

class rconf.pointer.JSONPointer

rconf.pointer.Pointer to parse and serialize JSON Pointers.

Follows JSON Pointer.

__new__(**kwargs)

__init__(*keys)

Build a pointer from its keys, or copy a Pointer.

Parameters:

keys (Pointer | Key) –

Return type:

None

class rconf.pointer.TOMLPointer

rconf.pointer.Pointer to parse and serialize TOML Pointers.

A TOML Pointer is defined as a TOML Key.

__new__(**kwargs)

__init__(*keys)

Build a pointer from its keys, or copy a Pointer.

Parameters:

keys (Pointer | Key) –

Return type:

None

Exceptions

class rconf.pointer.PointerError

A generic Pointer exception.

__new__(**kwargs)

__init__(*args, **kwargs)

class rconf.pointer.PointerValueError

Raised if a pointer representation can’t be parsed.

__new__(**kwargs)

__init__(*args, **kwargs)

class rconf.pointer.PointerLookupError

Raised if a pointer can’t be resolved.

__new__(**kwargs)

__init__(*args, **kwargs)