jschon.jsonpointer

class jschon.jsonpointer.JSONPointer(*values)

RFC 6901-conformant JSON Pointer implementation.

A JSON pointer is a string representing a reference to some value within a JSON document. It consists of a series of reference tokens each prefixed by "/", each token in turn being the (escaped) JSON object key or the JSON array index at the next node down the path to the referenced value. The empty string "" represents a reference to an entire JSON document.

A JSONPointer instance is an immutable sequence of the unescaped JSON object keys [1] and/or array indices [2] that comprise the path to a referenced value within a JSON document.

A JSONPointer instance is constructed by the concatenation of any number of arguments, each of which can be one of:

• a string conforming to the RFC 6901 syntax

• an iterable of unescaped keys (which may itself be a JSONPointer instance)

Two JSONPointer instances compare equal if their key sequences are identical.

The / operator provides a convenient syntax for extending a JSON pointer. It produces a new JSONPointer instance by copying the left-hand argument (a JSONPointer instance) and appending the right-hand argument (an unescaped key, or an iterable of unescaped keys).

Taking an index into a JSONPointer returns the unescaped key at that position. Taking a slice into a JSONPointer returns a new JSONPointer composed of the specified slice of the original’s keys.

[1]

An unescaped object key is the unmodified form of the key within its mapping. Keys appearing in an RFC 6901 JSON pointer string, on the other hand, are required by the syntax to have reserved characters escaped.

[2]

Object keys and array indices are uniformly represented as strings and referred to as keys in the JSONPointer class.

Parameters:

values (Union[str, Iterable[str]]) –

Return type:

JSONPointer

malformed_exc

Exception raised when the input is not a valid JSON Pointer.

alias of JSONPointerMalformedError

reference_exc

Exception raised when the JSON Pointer cannot be resolved against a document.

alias of JSONPointerReferenceError

__eq__(other)

Return self == other.

Parameters:

other (JSONPointer) –

Return type:

bool

__getitem__(index: int) → str

__getitem__(index: slice) → JSONPointer

Return self[index].

__hash__()

Return hash(self).

Return type:

int

__le__(other)

Return self <= other.

Test whether self is a prefix of other, that is, self == other[:len(self)].

Parameters:

other (JSONPointer) –

Return type:

bool

__len__()

Return len(self).

Return type:

int

__lt__(other)

Return self < other.

Test whether self is a proper prefix of other, that is, self <= other and self != other.

Parameters:

other (JSONPointer) –

Return type:

bool

static __new__(cls, *values)

Create and return a new JSONPointer instance, constructed by the concatenation of the given values.

Parameters:

values (str | Iterable[str]) – each value may either be an RFC 6901 string, or an iterable of unescaped keys

Raises:

JSONPointerMalformedError – if a string argument does not conform to the RFC 6901 syntax

Return type:

JSONPointer

__repr__()

Return repr(self).

Return type:

str

__str__()

Return str(self).

Return type:

str

__truediv__(suffix: str) → JSONPointer

__truediv__(suffix: Iterable[str]) → JSONPointer

Return self / suffix.

static escape(key)

Return the escaped form of a JSON object key / array index, suitable for use in an RFC 6901 JSON pointer string.

Parameters:

key (str) – an unescaped key

Return type:

str

evaluate(document)

Return the value within document at the location referenced by self.

document may be of any type, though if neither a Mapping nor a Sequence, evaluation by any non-empty JSONPointer will always fail.

Parameters:

document (Any) – any Python object

Raises:

JSONPointerReferenceError – if self references a non-existent location in document

Return type:

Any

classmethod parse_uri_fragment(value)

Return a new JSONPointer constructed from the RFC 6901 string obtained by decoding value.

value must exclude the initial '#' of the fragment; this allows for sensible interoperation with URI objects.

Parameters:

value (str) – a percent-encoded URI fragment

Return type:

JSONPointer

static unescape(token)

Return the unescaped form of a reference token appearing in an RFC 6901 JSON pointer string

Parameters:

token (str) – an RFC 6901 reference token

Return type:

str

uri_fragment()

Return a percent-encoded URI fragment representation of self.

The returned string excludes the initial '#' of the fragment; this allows for sensible interoperation with URI objects.

Return type:

str

class jschon.jsonpointer.RelativeJSONPointer(value=None, /, *, up=0, over=0, ref=JSONPointer(''))

Parameters:

• value (str) –

• up (int) –

• over (int) –

• ref (Union[JSONPointer, Literal['#']]) –

Return type:

RelativeJSONPointer

malformed_exc

Exception raised when the input is not a valid Relative JSON Pointer.

alias of RelativeJSONPointerMalformedError

reference_exc

Exception raised when the Relative JSON Pointer cannot be resolved against a document.

alias of RelativeJSONPointerReferenceError

__eq__(other)

Return self == other.

Parameters:

other (RelativeJSONPointer) –

Return type:

bool

__hash__()

Return hash(self).

Return type:

int

static __new__(cls, value=None, /, *, up=0, over=0, ref=JSONPointer(''))

Create and return a new RelativeJSONPointer instance.

Parameters:

• value (str | None) – a relative JSON pointer-conformant string; if value is given, keyword args are ignored

• up (int) – the number of levels up from the current referenced JSON node from which to evaluate ref

• over (int) – the integer value used to adjust the array index after applying up, which is only valid if that location is an array item; a value of 0, which is not allowed by the grammar, is treated as if there is no adjustment.

• ref (JSONPointer | Literal['#']) – a JSONPointer instance, or the literal '#'

Raises:

RelativeJSONPointerMalformedError – for any invalid arguments

Return type:

RelativeJSONPointer

__repr__()

Return repr(self).

Return type:

str

__str__()

Return str(self).

Return type:

str

evaluate(document)

Return the value within document at the location referenced by self.

document must be an instance of JSON, as evaluation relies on parent and sibling links provided by that class.

Parameters:

document (JSON) – a JSON instance representing the document

Raises:

RelativeJSONPointerReferenceError – if self references a non-existent location in document

Return type:

Union[int, str, JSON]