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 newJSONPointer
instance by copying the left-hand argument (aJSONPointer
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 aJSONPointer
returns a newJSONPointer
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
- __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
- __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 aSequence
, evaluation by any non-emptyJSONPointer
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 withURI
objects.- Parameters
value (str) – a percent-encoded URI fragment
- Return type
- 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
- __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
- __repr__()
Return repr(self).
- Return type
str
- __str__()
Return str(self).
- Return type
str