Patch#

Patch configuration documents.

Follows the description in RFC 6902: JSON Patch.

Operation assign has been added as a simplified replace, dropping the requirement that the target location must exist for the operation to be successful. It also allows appending to an array with key -.

Operation merge has been added to merge an object into an object or extend an array with an array. When merging objects, existing keys will be replaced.

A shorthand notation is also supported, using an array (list) instead of an object (dict) per operation.

A shorthand list consists of

a shorthand op (+-@<$?=&),
a path and
a from or value field if relevant, depending on the operation.

Operation	Shorthand	Third element
add	`+`	value
remove	`-`	-
replace	`@`	value
move	`<`	from
copy	`$`	from
test	`?`	value
assign	`=`	value
merge	`&`	value

Operations are applied in order of appearance.

Toplevel patching is not supported for in-place patching.

Listing 8 Example from RFC 6902 section 3.#

[
    { "op": "test", "path": "/a/b/c", "value": "foo" },
    { "op": "remove", "path": "/a/b/c" },
    { "op": "add", "path": "/a/b/c", "value": [ "foo", "bar" ] },
    { "op": "replace", "path": "/a/b/c", "value": 42 },
    { "op": "move", "from": "/a/b/c", "path": "/a/b/d" },
    { "op": "copy", "from": "/a/b/d", "path": "/a/b/e" }
]

Listing 9 Shorthand equivalent.#

[
    [ "?", "/a/b/c", "foo" ],
    [ "-", "/a/b/c" ],
    [ "+", "/a/b/c", [ "foo", "bar" ] ],
    [ "@", "/a/b/c", 42 ],
    [ "<", "/a/b/d", "/a/b/c" ],
    [ "$", "/a/b/e", "/a/b/d" ]
]

Patch#

class rconf.patch.PatchOperation#

Patch operations.

Follows the definitions in RFC 6902 section 4. Operation assign is added for convenience.

Operation merge has been added to merge an object into an object or extend an array with an array. When merging objects, existing keys will be replaced.

rconf.patch.PatchOperation can be indexed with a full or shorthand name.

shorthand()#

Get shorthand name for an operation.

Return type:: str

class rconf.patch.PatchOperationObject#

A single patch operation object.

The operation object is defined in RFC 6902 section 4.

value and from are merged into value.

__init__(op, path, value=None, *, pointer_type=<class 'rconf.pointer.JSONPointer'>, **kwargs)#

Build a rconf.patch.PatchOperationObject.

Parameters:

op (str | PatchOperation) – The operation to perform.
path (str | Pointer) – The pointer to the target location.
value (Value | str | Pointer | None) – The operation-specific value or from field.
pointer_type (type[Pointer]) – The pointer type if path is a str.

Return type:

None

value will be interpreted as an operation’s from for move and copy (PatchOperation.MOVE and PatchOperation.COPY). If missing, it will look for an explicit from field in kwargs.

apply(doc)#

Apply the PatchOperationObject.

Parameters:: doc (rconf.Value) – The document to patch.
Raises:: rconf.patch.PatchError for errors while patching, rconf.patch.PatchTestError for failing tests.
Return type:: rconf.Value

class rconf.patch.Patch#

JSON Patch document.

__init__(diff=None, pointer_type=<class 'rconf.pointer.JSONPointer'>)#

Build a rconf.patch.Patch.

The diff consists of a list of Patch Operation Objects, represented as

a rconf.patch.PatchOperationObject,
an operation dict or,
a shorthand list.

Parameters:

diff (list[PatchOperationObject | dict[str, rconf.Value] | list[rconf.Value]] | None) –
pointer_type (type[rconf.pointer.Pointer]) –

Return type:

None

add(op, path, value=None, **kwargs)#

Add a single operation object.

value will be interpreted as an operation’s from for move and copy (PatchOperation.MOVE and PatchOperation.COPY).

Parameters:

op (str | PatchOperation) –
path (str | Pointer) –
value (Value | str | Pointer | None) –

Return type:

None

apply(doc, *, in_place=False)#

Apply the Patch to doc and return the patched Value.

Parameters:

doc (rconf.Value) – The document to patch.
in_place (bool) – Apply the changes to doc instead of a copy.

Raises:

rconf.patch.PatchError for invalid patches, rconf.patch.PatchTestError for failing tests.

Return type:

rconf.Value

Exceptions#

class rconf.patch.PatchError#

A generic Patch exception.

__new__(**kwargs)#

__init__(*args, **kwargs)#

class rconf.patch.PatchTestError#

Raised if a patch document test fails.

__new__(**kwargs)#

__init__(*args, **kwargs)#

class rconf.patch.PatchValueError#

Raised if a patch document is not valid.

__new__(**kwargs)#

__init__(*args, **kwargs)#

class rconf.patch.PatchLookupError#

Raised if a path in a patch can’t be resolved.

__new__(**kwargs)#

__init__(*args, **kwargs)#

class rconf.patch.PatchIndexError#

Raised when a sequence subscript is out of range.

__new__(**kwargs)#

__init__(*args, **kwargs)#

class rconf.patch.PatchKeyError#

Raised when a mapping (dictionary) key is not found.

__new__(**kwargs)#

__init__(*args, **kwargs)#