JSON Pointer

JSON Pointer defines a string syntax for identifying a specific value within a JSON document. The most common usage is this:

from jsonspec.pointer import extract, Pointer
document = {
    'foo': ['bar', 'baz', {
        '$ref': 'obj2#/sub'
    }]
}
assert 'baz' == extract(document, '/foo/1')

But you can also iter throught the object:

obj = document
for token in Pointer('/foo/1'):
    obj = token.extract(obj)
assert 'baz' == obj

This module is event driven. It means that an event will be raised when it can’t be explored. Here is the most meaningful:

Event	meaning
RefError	encountered a JSON Reference, see.
LastElement	asking for the last element of a sequence
OutOfBounds	member does not exists into the current mapping
OutOfRange	element does not exists into the current sequence

About JSON Reference

A pointer.RefError is raised when when a JSON Reference is encountered. This behavior can be desactivated by setting bypass_ref=True.

assert 'obj2#/sub' == extract(document, '/foo/2/$ref', bypass_ref=True)

If you need to resolve JSON Reference, you can that a look at JSON Reference.

About relative JSON Reference

Relative JSON Pointer are still experimental, but this library offers an implementation of it.

It implies to convert the whole document into a staged document, and then follow these rules:

from jsonspec.pointer import extract, stage

staged_doc = stage({
    'foo': ['bar', 'baz'],
    'highly': {
        'nested': {
            'objects': True
        }
    }
})

baz_relative = extract(self.document, '/foo/1')

# staged objects
assert extract(baz_relative, '0') == 'baz'
assert extract(baz_relative, '1/0') == 'bar'
assert extract(baz_relative, '2/highly/nested/objects') == True  # `foo is True` won't work

# keys, not staged
assert extract(baz_relative, '0#') == 1
assert extract(baz_relative, '1#') == 'foo'

# unstage object
assert extract(baz_relative, '0').obj == 'baz'
assert extract(baz_relative, '1/0').obj == 'bar'
assert extract(baz_relative, '2/highly/nested/objects').obj is True

API

pointer.extract(obj, pointer, bypass_ref=False)

Extract member or element of obj according to pointer.

Parameters:

• obj – the object source
• pointer (Pointer, str) – the pointer
• bypass_ref (boolean) – bypass JSON Reference event

class pointer.DocumentPointer(pointer)

Defines a document pointer

Variables:

• document – document name
• pointer – pointer

endswith(txt)

used by os.path.join

extract(obj, bypass_ref=False)

Extract subelement from obj, according to pointer. It assums that document is the object.

Parameters:

• obj – the object source
• bypass_ref – disable JSON Reference errors

is_inner()

Tells if pointer refers to an inner document

class pointer.Pointer(pointer)

Defines a pointer

Variables:tokens – list of PointerToken

extract(obj, bypass_ref=False)

Extract subelement from obj, according to tokens.

Parameters:

• obj – the object source
• bypass_ref – disable JSON Reference errors

parse(pointer)

parse pointer into tokens

class pointer.PointerToken

A single token

extract(obj, bypass_ref=False)

Extract parents or subelement from obj, according to current token.

Parameters:

• obj – the object source
• bypass_ref – disable JSON Reference errors

pointer.stage(obj, parent=None, member=None)

Prepare obj to be staged.

This is almost used for relative JSON Pointers.

Exceptions

class pointer.ExtractError(obj, *args)

Raised for any errors.

Variables:obj – the object that raised this event

class pointer.RefError(obj, *args)

Raised when encoutered a JSON Ref.

Variables:obj – the object that raised this event

class pointer.LastElement(obj, *args)

Raised when refers to the last element of a sequence.

Variables:obj – the object that raised this event

class pointer.OutOfBounds(obj, *args)

Raised when a member of a mapping does not exists.

Variables:obj – the object that raised this event

class pointer.OutOfRange(obj, *args)

Raised when an element of a sequence does not exists.

Variables:obj – the object that raised this event