djblets.util.json_utils¶

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

Bases: Exception

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

__init__(msg, doc, patch, patch_entry_index=None)¶

Initialize the error.

Parameters:

• msg (unicode) – The error message.

• doc (dict or list) – The original JSON document the patch was being applied to. This won’t contain the patched modifications. patch.

• patch (object) – The patch being applied. The value depends on the patch.

• patch_entry_index (int, optional) – The index of the patch being applied. This can be None if the error doesn’t apply to a specific entry.

exception JSONPatchPathError(msg, path, **kwargs)¶

Bases: JSONPatchError

Error with a path in a JSON Patch.

__init__(msg, path, **kwargs)¶

Initialize the error.

Parameters:

• msg (unicode) – The error message describing the path failure.

• path (unicode) – The path that had an error.

• **kwargs (dict) – Additional keyword arguments to pass to the parent class.

exception JSONPatchAccessError(msg, path, **kwargs)¶

Bases: JSONPatchPathError

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

exception JSONPatchReadAccessError(msg, path, **kwargs)¶

Bases: JSONPatchAccessError

Access error reading from part of an object.

exception JSONPatchWriteAccessError(msg, path, **kwargs)¶

Bases: JSONPatchAccessError

Access error writing to part of an object.

exception JSONPatchTestError(msg, path, **kwargs)¶

Bases: JSONPatchPathError

Test condition failed when applying a JSON Patch.

exception JSONPointerError¶

Bases: Exception

Base class for JSON Pointer errors.

exception JSONPointerSyntaxError¶

Bases: JSONPointerError

Syntax error in a JSON Pointer path.

exception JSONPointerLookupError(msg, parent, token, token_index, tokens)¶

Bases: JSONPointerError

Error looking up data from a JSON Pointer path.

__init__(msg, parent, token, token_index, tokens)¶

Initialize the error.

Parameters:

• msg (unicode) – The error message.

• parent (object) – The parent object. This may be a dictionary or a list.

• token (unicode) – The last resolvable token in the path. This will be None if the first token failed.

• token_index (int) – The 0-based index of the last resolvable token in the path. This will be None if the first token failed.

• tokens (list of unicode) – The list of tokens comprising the full path.

class JSONPointerEndOfList(json_list)¶

Bases: object

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.

__init__(json_list)¶

Initialize the object.

Parameters:

json_list (list) – The list this object represents.

__eq__(other_list)¶

Return whether two instances are equal.

Instances are equal if both of their lists are equal.

Parameters:

other_list (JSONPointerEndOfList) – The other instance to compare to for equality.

Returns:

True if the two lists are equal.

Return type:

bool

__repr__()¶

Return a string representation of the instance.

Returns:

A string representation of the instance.

Return type:

unicode

__hash__ = None¶

json_merge_patch(doc, patch, can_write_key_func=None)¶

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)¶

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)¶

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)¶

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.