Operations

Operations are inspired by the JSON Patch specification.

For example:

from jsonspec import operations

obj = {
    'foo': {
        'bar': 'baz',
        'waldo': 'fred'
    },
    'qux': {
        'corge': 'grault'
    }
}
assert operations.move(obj, '/qux/thud', '/foo/waldo') == {
    'foo': {
        'bar': 'baz'
    },
    'qux': {
        'corge': 'grault',
        'thud': 'fred'
    }
}

Sources, destinations and locations are expressed with pointer.Pointer.

Operations

add:

The add operation performs one of the following functions, depending upon what the target location references:

  • If the target location specifies an array index, a new value is inserted into the array at the specified index.
  • If the target location specifies an object member that does not already exist, a new member is added to the object.
  • If the target location specifies an object member that does exist, that member’s value is replaced.

For example:

# add or replace a mapping
operations.add({'foo': 'bar'}, '/baz', 'qux') == {
    'baz': 'qux',
    'foo': 'bar'
}

# add into a sequence
operations.add(['foo', 'bar'], '/1', 'qux') == ['foo', 'qux', 'bar']
remove:

The remove operation removes the value at the target location:

# remove a mapping member
operations.remove({
    'baz': 'qux',
    'foo': 'bar'
}, '/baz') == {'foo': 'bar'}

# remove a sequence element
operations.remove(['bar', 'qux', 'baz'], '/1') == ['bar', 'baz']
replace:

The replace operation replaces the value at the target location with a new value:

operations.replace({
    'baz': 'qux',
    'foo': 'bar'
}, '/baz', 'boo') == {
    'baz': 'boo',
    'foo': 'bar'
}
move:

The move operation removes the value at a specified location and adds it to the target location:

# move a value into a mapping
operations.move({
    'foo': {
        'bar': 'baz',
        'waldo': 'fred'
    },
    'qux': {
        'corge': 'grault'
    }
}, '/qux/thud', '/foo/waldo') == {
    'foo': {
        'bar': 'baz'
    },
    'qux': {
        'corge': 'grault',
        'thud': 'fred'
    }
}

# move an array element
operations.move([
    'all', 'grass', 'cows', 'eat'
], '/3', '/1') == [
    'all', 'cows', 'eat', 'grass'
]
copy:

The copy operation copies the value at a specified location to the target location:

operations.copy({
    'foo': {'bar': 42},
}, 'baz', '/foo/bar') == {
    'foo': {'bar': 42}, 'baz': 42
}
check:

The test operation tests that a value at the target location is equal to a specified value:

# testing a value with success
obj = {
    'baz': 'qux',
    'foo': ['a', 2, 'c']
}
assert operations.check(obj, '/baz', 'qux')
assert operations.check(obj, '/foo/1', 2)

# testing a value with error
assert not operations.check({'baz': 'qux'}, '/baz', 'bar')

API

operations.check(doc, pointer, expected, raise_onerror=False)

Check if value exists into object.

Parameters:
  • doc – the document base
  • pointer – the path to search in
  • expected – the expected value
  • raise_onerror – should raise on error?
Returns:

boolean
operations.remove(doc, pointer)

Remove element from sequence, member from mapping.

Parameters:
  • doc – the document base
  • pointer – the path to search in
Returns:

the new object
operations.add(doc, pointer, value)

Add element to sequence, member to mapping.

Parameters:
  • doc – the document base
  • pointer – the path to add in it
  • value – the new value
Returns:

the new object
operations.replace(doc, pointer, value)

Replace element from sequence, member from mapping.

Parameters:
  • doc – the document base
  • pointer – the path to search in
  • value – the new value
Returns:

the new object

Note

This operation is functionally identical to a “remove” operation for a value, followed immediately by an “add” operation at the same location with the replacement value.

operations.move(doc, dest, src)

Move element from sequence, member from mapping.

Parameters:
  • doc – the document base
  • dest (Pointer) – the destination
  • src (Pointer) – the source
Returns:

the new object

Note

it delete then it add to the new location soo the dest must refer to the middle object.

operations.copy(doc, dest, src)

Copy element from sequence, member from mapping.

Parameters:
  • doc – the document base
  • dest (Pointer) – the destination
  • src (Pointer) – the source
Returns:

the new object
class operations.Target(document)
Variables:document – the document base
add(pointer, value)

Add element to sequence, member to mapping.

Parameters:
  • pointer – the path to add in it
  • value – the new value
Returns:

resolved document
Return type:

Target

The pointer must reference one of:

  • The root of the target document - whereupon the specified value becomes the entire content of the target document.
  • A member to add to an existing mapping - whereupon the supplied value is added to that mapping at the indicated location. If the member already exists, it is replaced by the specified value.
  • An element to add to an existing sequence - whereupon the supplied value is added to the sequence at the indicated location. Any elements at or above the specified index are shifted one position to the right. The specified index must no be greater than the number of elements in the sequence. If the “-” character is used to index the end of the sequence, this has the effect of appending the value to the sequence.
check(pointer, expected, raise_onerror=False)

Check if value exists into object.

Parameters:
  • pointer – the path to search in
  • expected – the expected value
  • raise_onerror – should raise on error?
Returns:

boolean
copy(dest, src)

Copy element from sequence, member from mapping.

Parameters:
Returns:

resolved document
Return type:

Target
move(dest, src)

Move element from sequence, member from mapping.

Parameters:
Returns:

resolved document
Return type:

Target

Note

This operation is functionally identical to a “remove” operation on the “from” location, followed immediately by an “add” operation at the target location with the value that was just removed.

The “from” location MUST NOT be a proper prefix of the “path” location; i.e., a location cannot be moved into one of its children

remove(pointer)

Remove element from sequence, member from mapping.

Parameters:pointer – the path to search in
Returns:resolved document
Return type:Target
replace(pointer, value)

Replace element from sequence, member from mapping.

Parameters:
  • pointer – the path to search in
  • value – the new value
Returns:

resolved document
Return type:

Target