djblets.util.json_utils¶

exception JSONPatchError(msg, doc, patch, patch_entry_index=None)[source]¶

An error occurred while patching an object.

doc¶

The original JSON document the patch was being applied to. This won’t contain the patched modifications.

Type

dict or list

patch¶

The patch being applied. The value depends on the type of patch.

Type

object

patch_entry_index¶

The index of the patch being applied. This can be None if the error doesn’t apply to a specific entry.

Type

int, optional

exception JSONPatchPathError(msg, path, **kwargs)[source]¶

Error with a path in a JSON Patch.

exception JSONPatchAccessError(msg, path, **kwargs)[source]¶

Access error reading from or writing to part of an object.

exception JSONPatchReadAccessError(msg, path, **kwargs)[source]¶

Access error reading from part of an object.

exception JSONPatchWriteAccessError(msg, path, **kwargs)[source]¶

Access error writing to part of an object.

exception JSONPatchTestError(msg, path, **kwargs)[source]¶

Test condition failed when applying a JSON Patch.

exception JSONPointerError[source]¶

Base class for JSON Pointer errors.

exception JSONPointerSyntaxError[source]¶

Syntax error in a JSON Pointer path.

exception JSONPointerLookupError(msg, parent, token, token_index, tokens)[source]¶

Error looking up data from a JSON Pointer path.

class JSONPointerEndOfList(json_list)[source]¶

A representation of the end of a list.

This is used by the JSON Pointer functions to represent the very end of a list (not the last item). This is used primarily when specifying an insertion point, with this value repersenting appending to a list.

json_merge_patch(doc, patch, can_write_key_func=None)[source]¶

Apply a JSON Merge Patch to a value.

This is an implementation of the proposed JSON Merge Patch standard (RFC 7396), which is a simple algorithm for applying changes to a JSON-compatible data structure.

This will attempt to merge the contents of the patch object into the doc object as best as possible, using the following rules:

• If a key in patch matches a key in doc, and the value is None, the key in doc is removed.

• If a key in patch matches a key in doc, and the value is a dictionary, this method will be called on the values in each and the result will be stored as the new value.

• If a key in patch matches a key in doc, and the value is not a dictionary, the value from patch will replace the value in doc.

• If patch is a dictionary but doc is not, then patch will be returned directly.

• If patch is a dictionary but doc is not, then doc will be discarded and the JSON Merge Patch will be applied to a new empty dictionary.

• If patch is not a dictionary, then patch will be returned directly.

Parameters

• doc (object) – The JSON-compatible document object the patch is being applied to. This will usually be a dict().

• patch (object) – The JSON-compatible patch to apply.

• can_write_key_func (callable, optional) –

  An optional function to call for each key to determine if the key can be written in the new dictionary. This must take the following form:

  def can_write_key(doc, patch, path, **kwargs):
      ...
  

  This must return a boolean indicating if the key can be written, or may raise a JSONPatchError to abort the patching process. If the function returns False, the key will simply be skipped.

Returns

The resulting object. This will be the same type as patch.

Return type

object

Raises

• JSONPatchError – There was an error patching the document. This is only raised by can_write_key_func implementations.

• ValueError – A provided parameter was incorrect.

json_patch(doc, patch, can_read_key_func=None, can_write_key_func=None)[source]¶

Apply a JSON Patch to a value.

A JSON Patch (RFC 6902), similar to a JSON Merge Patch, is used to make changes to an existing JSON-compatible data structure. JSON Patches are composed of a list of operations which can add a new value, remove a value, replace an existing value, move a value, copy a value, or test that a path has a given value. All operations must pass for a patch to apply.

A full description of the operations are available in the RFC or from http://jsonpatch.com/.

Parameters

• doc (dict or list) – The root JSON document to apply the patch to. This will not be modified itself.

• patch (list of dict) – The list of operations to apply to the JSON document.

• can_read_key_func (callable, optional) –

  An optional function to call for each path to determine if the path can be read from the document. This is in the following form:

  def can_read_key(doc, patch, patch_entry, path, **kwargs):
      ...
  

  It must return a boolean indicating if the key can be written.

• can_write_key_func (callable, optional) –

  An optional function to call for each path to determine if the path can be written to the document. This takes the same form as can_read_key_func.

  If not provided, it will default to can_read_key_func.

Returns

The resulting JSON document after the patch is applied.

Return type

dict or list

Raises

JSONPatchError – An error occurred patching the JSON document.

json_get_pointer_info(obj, path)[source]¶

Return information from a JSON object based on a JSON Pointer path.

JSON Pointers are a standard way of specifying a path to data within a JSON object. This method takes a JSON Pointer path and returns information from the given object based on that path.

Pointer paths consist of dictionary keys, array indexes, or a special - token (representing the end of a list, after the last item) separated by / tokens. There are also two special escaped values: ~0, representing a ~ character, and ~1, representing a / character.

Paths must start with /, or must be an empty string (which will match the provided object). If the path has a trailing /, then the final token is actually an empty string (matching an empty key in a dictionary).

If the Pointer does not resolve to a complete path (for instance, a key specified in the path is missing), the resulting information will return the keys that could be resolved, keys that could not be resolved, the object where it left off, and an error message. This allows implementations to determine which part of a path does not yet exist, potentially for the purpose of inserting data at that key in the path.

Parameters

• obj (object or list) – The object or list representing the starting object for the path.

• path (unicode) – The Pointer path for the lookup.

Returns

Information about the object and what the path was able to match. This has the following keys:

value (object):

The resulting value from the path, if the path was fully resolved.

This will be a JSONPointerEndOfList if the last part of the path was a - token (representing the very end of a list).

tokens (list):

The normalized (unescaped) list of path tokens that comprise the full path.

parent (object):

The parent object for either the most-recently resolved value.

resolved (list):

The list of resolved objects from the original JSON object. This will contain each key, array item, or other value that was found, in path order.

lookup_error (unicode):

The error message, if any, if failing to resolve the full path.

Return type

dict

Raises

JSONPointerSyntaxError – There was a syntax error with a token in the path.

json_resolve_pointer(obj, path)[source]¶

Return the value from a JSON object based on a JSON Pointer path.

See json_get_pointer_info() for information on how a Pointer path is constructed. Unlike that function, this requires a fully-resolved path.

Parameters

• obj (object or list) – The object or list representing the starting object for the path.

• path (unicode) – The Pointer path for the lookup.

Returns

The resulting value from the object, based on the path.

This will be a JSONPointerEndOfList if the last part of the path was a - token (representing the very end of a list).

Return type

object

Raises

• JSONPointerLookupError – The path could not be fully resolved.

• JSONPointerSyntaxError – There was a syntax error with a token in the path.