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

__eq__(other)

Return self == other.

Parameters

other (jschon.jsonpointer.JSONPointer) –

Return type

bool

__getitem__(index: int) → str
__getitem__(index: slice) → jschon.jsonpointer.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 (jschon.jsonpointer.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 (jschon.jsonpointer.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 (Union[str, Iterable[str]]) – each value may either be an RFC 6901 string, or an iterable of unescaped keys

Raises

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

Return type

jschon.jsonpointer.JSONPointer

__repr__()

Return repr(self).

Return type

str

__str__()

Return str(self).

Return type

str

__truediv__(suffix: str) → jschon.jsonpointer.JSONPointer
__truediv__(suffix: Iterable[str]) → jschon.jsonpointer.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

JSONPointerError – if self references a non-existent location within 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

jschon.jsonpointer.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

__eq__(other)

Return self == other.

Parameters

other (jschon.jsonpointer.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 (Optional[str]) – 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 (Union[jschon.jsonpointer.JSONPointer, Literal['#']]) – a JSONPointer instance, or the literal '#'

Raises

RelativeJSONPointerError – for any invalid arguments

Return type

jschon.jsonpointer.RelativeJSONPointer

__repr__()

Return repr(self).

Return type

str

__str__()

Return str(self).

Return type

str

evaluate(document)
Parameters

document (JSON) –

Return type

Union[int, str, JSON]