json_pointer

detdevlib.utils.json_pointer

JSONPointer

Represents an RFC 6901 compliant JSON Pointer.

A JSON Pointer is a string syntax for identifying a specific value within a JSON document. It is a Unicode string containing a sequence of zero or more reference tokens, each prefixed by a '/' character.

Attributes:

Name	Type	Description
_tokens	tuple[str, ...]	A tuple of unescaped string tokens that constitute the pointer.

last_token property

last_token

Returns the last token in this pointer.

tokens property

tokens: tuple[str, ...]

Returns the tokens of this pointer.

is_root property

is_root: bool

True if the pointer is a root pointer, False otherwise.

__init__

__init__(
    p: Union[
        str,
        list[str | int],
        tuple[str | int, ...],
        Self,
        None,
    ] = None,
)

Initializes a JSONPointer instance.

Parameters:

Name	Type	Description	Default
p	Union[str, list[str | int], tuple[str | int, ...], Self, None]	The source to create the pointer from. Can be a pointer string, a list/tuple of tokens, another JSONPointer instance, or None for a root pointer. Defaults to None.	None

Raises:

Type	Description
TypeError	If p is of an unsupported type.

set_last_token

set_last_token(last_token: str) -> Self

Creates a new pointer by replacing the last token of the current one.

Parameters:

Name	Type	Description	Default
last_token	str	The new final token.	required

Returns:

Name	Type	Description
Self	Self	A new JSONPointer instance with the replaced final token.

Raises:

Type	Description
ValueError	If called on a root pointer (which has no tokens).

exists

exists(obj) -> bool

Checks if the pointer can resolve to a value within a given object.

Parameters:

Name	Type	Description	Default
obj	Any	The JSON-like object to check.	required

Returns:

Name	Type	Description
bool	bool	True if the pointer resolves to a value, False otherwise.

parent

parent() -> Self

Returns the parent pointer.

The parent is a new pointer with the last token removed. If the pointer is already the root, it returns itself.

Returns:

Name	Type	Description
Self	Self	A new JSONPointer instance representing the parent, or self if it is the root pointer.

get

get(obj, default=_NO_DEFAULT) -> Any

Resolves the pointer against a JSON-like object to get a value.

Parameters:

Name	Type	Description	Default
obj	Any	The object to resolve the pointer against.	required
default	Any	A value to return if the pointer cannot be resolved. If not provided, a ValueError is raised.	_NO_DEFAULT

Returns:

Name	Type	Description
Any	Any	The value at the pointer's location, or the default value if provided and the path does not exist.

Raises:

Type	Description
ValueError	If the pointer cannot be resolved and no default is given.

put

put(obj, value)

Sets a value in a JSON-like object at the location specified by the pointer.

This method will create nested dictionaries as needed to fulfill the path. It can also set or append values in lists.

Parameters:

Name	Type	Description	Default
obj	Any	The object to modify.	required
value	Any	The value to set at the pointer's location.	required

Returns:

Name	Type	Description
Self		The current pointer instance.

Raises:

Type	Description
ValueError	If attempting to set the root, use an invalid list index, or if a path segment cannot be created (e.g., trying to set a key on a non-dict object).

pop

pop(obj)

Removes and returns a value from an object at the pointer's location.

Parameters:

Name	Type	Description	Default
obj	Any	The object to modify.	required

Returns:

Name	Type	Description
Any		The value that was removed.

Raises:

Type	Description
ValueError	If the pointer is the root, the path does not exist, the index is out of bounds, or the target object does not support popping (i.e., is not a list or dict).
KeyError	If a key in the path does not exist in a dictionary.

resolve

resolve(obj) -> Optional[Self]

Resolves a JSON reference string found at the pointer's location.

First, it gets the value at the current pointer's location within obj. If that value is a JSON reference string (e.g., "#/definitions/User"), it parses this string into a new JSONPointer object.

Parameters:

Name	Type	Description	Default
obj	Any	The object to resolve the reference from.	required

Returns:

Type	Description
Optional[Self]	Optional[Self]: A new JSONPointer instance parsed from the reference string, or None if the pointer does not exist in the object or the value is not a valid reference string.

get_reference

get_reference(pointer: JSONPointer, url: str = '') -> str

Formats a JSONPointer into a JSON reference string.

A JSON reference is a string that identifies a value in a JSON document, combining an optional URI with a JSON Pointer fragment.

Parameters:

Name	Type	Description	Default
pointer	JSONPointer	The pointer to format.	required
url	str	An optional URL or URI to prepend to the reference. Defaults to "".	''

Returns:

Name	Type	Description
str	str	The fully formed JSON reference string (e.g., "http://example.com#/a/b").

parse_reference

parse_reference(ref_str: str) -> Optional[JSONPointer]

Parses a JSONPointer from a JSON reference string.

Extracts the fragment identifier from a reference string (the part after '#') and parses it into a JSONPointer object.

Parameters:

Name	Type	Description	Default
ref_str	str	The JSON reference string (e.g., "#/a/b").	required

Returns:

Type	Description
Optional[JSONPointer]	Optional[JSONPointer]: A JSONPointer object if the fragment can be parsed successfully. Returns None if the string is not a valid reference (e.g., missing '#', contains a URL part, or has a malformed fragment).

bfs

bfs(
    obj: Any,
) -> Generator[tuple[JSONPointer, Any], None, None]

Performs a breadth-first search (BFS) on a JSON-like object.

Iterates through all keys and values in nested dictionaries and lists, yielding the pointer and value for each item encountered.

Parameters:

Name	Type	Description	Default
obj	Any	The JSON-like object (dict, list, etc.) to traverse.	required

Yields:

Type	Description
tuple[JSONPointer, Any]	Generator[tuple[JSONPointer, Any], None, None]: A generator that yields tuples of (JSONPointer, value) for each item in the object.

collect_references

collect_references(
    obj: Any,
) -> dict[JSONPointer, list[JSONPointer]]

Finds and groups all JSON references ($ref) within a JSON-like object.

This function traverses the object and identifies all keys named "$ref". It parses the string value of each reference and collects them into a dictionary.

Parameters:

Name	Type	Description	Default
obj	Any	The JSON-like object to scan for references.	required

Returns:

Type	Description
dict[JSONPointer, list[JSONPointer]]	dict[JSONPointer, list[JSONPointer]]: A dictionary where keys are the parsed JSONPointer objects from the $ref values (the targets), and values are lists of JSONPointer objects pointing to the locations of those $ref keys (the sources).