jsonpatch 1.44__tar.gz → 1.45__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (28) hide show
  1. {jsonpatch-1.44/jsonpatch.egg-info → jsonpatch-1.45}/PKG-INFO +11 -1
  2. {jsonpatch-1.44 → jsonpatch-1.45}/README.md +10 -0
  3. {jsonpatch-1.44 → jsonpatch-1.45}/doc/tutorial.rst +179 -6
  4. {jsonpatch-1.44 → jsonpatch-1.45}/jsonpatch-stubs/__init__.pyi +5 -0
  5. {jsonpatch-1.44 → jsonpatch-1.45/jsonpatch.egg-info}/PKG-INFO +11 -1
  6. {jsonpatch-1.44 → jsonpatch-1.45}/jsonpatch.py +202 -7
  7. {jsonpatch-1.44 → jsonpatch-1.45}/property_tests.py +20 -0
  8. {jsonpatch-1.44 → jsonpatch-1.45}/tests.py +555 -6
  9. {jsonpatch-1.44 → jsonpatch-1.45}/typetests/usage.py +23 -0
  10. {jsonpatch-1.44 → jsonpatch-1.45}/AUTHORS +0 -0
  11. {jsonpatch-1.44 → jsonpatch-1.45}/LICENSE +0 -0
  12. {jsonpatch-1.44 → jsonpatch-1.45}/MANIFEST.in +0 -0
  13. {jsonpatch-1.44 → jsonpatch-1.45}/doc/commandline.rst +0 -0
  14. {jsonpatch-1.44 → jsonpatch-1.45}/doc/index.rst +0 -0
  15. {jsonpatch-1.44 → jsonpatch-1.45}/doc/mod-jsonpatch.rst +0 -0
  16. {jsonpatch-1.44 → jsonpatch-1.45}/ext_tests.py +0 -0
  17. {jsonpatch-1.44 → jsonpatch-1.45}/jsonpatch.egg-info/SOURCES.txt +0 -0
  18. {jsonpatch-1.44 → jsonpatch-1.45}/jsonpatch.egg-info/dependency_links.txt +0 -0
  19. {jsonpatch-1.44 → jsonpatch-1.45}/jsonpatch.egg-info/entry_points.txt +0 -0
  20. {jsonpatch-1.44 → jsonpatch-1.45}/jsonpatch.egg-info/requires.txt +0 -0
  21. {jsonpatch-1.44 → jsonpatch-1.45}/jsonpatch.egg-info/top_level.txt +0 -0
  22. {jsonpatch-1.44 → jsonpatch-1.45}/jsonpatch_cli.py +0 -0
  23. {jsonpatch-1.44 → jsonpatch-1.45}/pyproject.toml +0 -0
  24. {jsonpatch-1.44 → jsonpatch-1.45}/pytest.ini +0 -0
  25. {jsonpatch-1.44 → jsonpatch-1.45}/requirements.txt +0 -0
  26. {jsonpatch-1.44 → jsonpatch-1.45}/setup.cfg +0 -0
  27. {jsonpatch-1.44 → jsonpatch-1.45}/setup.py +0 -0
  28. {jsonpatch-1.44 → jsonpatch-1.45}/tests.js +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: jsonpatch
3
- Version: 1.44
3
+ Version: 1.45
4
4
  Summary: Apply JSON-Patches (RFC 6902)
5
5
  Home-page: https://github.com/stefankoegl/python-json-patch
6
6
  Author: Stefan Kögl
@@ -70,6 +70,16 @@ See source code for examples
70
70
  * CI: https://github.com/stefankoegl/python-json-patch/actions
71
71
  * Coveralls: https://coveralls.io/github/stefankoegl/python-json-patch
72
72
 
73
+ String append extension
74
+ -----------------------
75
+ `JsonPatchWithAppend` is a drop-in replacement for `JsonPatch` with a
76
+ non-RFC string `append` operation. Its `from_diff()` method sends only the
77
+ new suffix when an object member's string grows. `JsonPatch`, `make_patch()`
78
+ and `apply_patch()` retain their standard RFC 6902 behavior.
79
+
80
+ See the [tutorial](doc/tutorial.rst#string-append-extension) for examples.
81
+ Both sender and receiver must support the extension.
82
+
73
83
  Type hints
74
84
  ----------
75
85
  jsonpatch ships type stubs (in the `jsonpatch-stubs` directory, as
@@ -21,6 +21,16 @@ See source code for examples
21
21
  * CI: https://github.com/stefankoegl/python-json-patch/actions
22
22
  * Coveralls: https://coveralls.io/github/stefankoegl/python-json-patch
23
23
 
24
+ String append extension
25
+ -----------------------
26
+ `JsonPatchWithAppend` is a drop-in replacement for `JsonPatch` with a
27
+ non-RFC string `append` operation. Its `from_diff()` method sends only the
28
+ new suffix when an object member's string grows. `JsonPatch`, `make_patch()`
29
+ and `apply_patch()` retain their standard RFC 6902 behavior.
30
+
31
+ See the [tutorial](doc/tutorial.rst#string-append-extension) for examples.
32
+ Both sender and receiver must support the extension.
33
+
24
34
  Type hints
25
35
  ----------
26
36
  jsonpatch ships type stubs (in the `jsonpatch-stubs` directory, as
@@ -323,15 +323,146 @@ The unescaped path ``/fields/test`` would mean something different: the key
323
323
  ``test`` inside the key ``fields``. Applying it to ``{}`` fails, because there
324
324
  is no key ``fields``.
325
325
 
326
- When writing a patch by hand, escape keys in the same way. The ``jsonpointer``
327
- package, which ``jsonpatch`` depends on, can build a pointer from a list of
328
- unescaped keys.
326
+ When writing a patch by hand, escape keys in the same way. ``path_join``
327
+ builds a path from a list of unescaped keys and array indices, and
328
+ ``path_split`` turns a path back into its unescaped parts, for example to
329
+ inspect the keys a patch refers to. The parts that ``path_split`` returns are
330
+ always strings, also those of array indices.
329
331
 
330
332
  .. code-block:: python
331
333
 
332
- >>> from jsonpointer import JsonPointer
333
- >>> JsonPointer.from_parts(['/fields/test', 'a~b']).path
334
- '/~1fields~1test/a~0b'
334
+ >>> jsonpatch.path_join(['/fields/test', 'a~b', 0])
335
+ '/~1fields~1test/a~0b/0'
336
+ >>> jsonpatch.path_split('/~1fields~1test/a~0b/0')
337
+ ('/fields/test', 'a~b', '0')
338
+ >>> [jsonpatch.path_split(op['path']) for op in patch]
339
+ [('/fields/test',)]
340
+
341
+
342
+ Custom Path Syntax
343
+ ------------------
344
+
345
+ How paths are read and written is defined by a pointer class, which is
346
+ ``jsonpointer.JsonPointer`` by default. Another class can be passed as
347
+ ``pointer_cls`` to ``JsonPatch``, ``JsonPatch.from_string``,
348
+ ``JsonPatch.from_diff``, ``apply_patch``, ``make_patch``, ``path_split`` and
349
+ ``path_join``, for example to use a different path syntax.
350
+
351
+ A pointer stores a path as the list of its unescaped parts, in its ``parts``
352
+ attribute. Resolving it against a document only uses these parts, so a class
353
+ for a different syntax only has to override three members of ``JsonPointer``:
354
+
355
+ ``__init__(self, pointer)``
356
+ Parses the path string ``pointer`` and sets ``self.parts`` to a list of
357
+ strings, one per object key or array index. The empty list refers to the
358
+ whole document. Raise ``jsonpointer.JsonPointerException`` for an invalid
359
+ path.
360
+
361
+ ``from_parts(cls, parts)``
362
+ A class method that returns a pointer to the given parts, which can also
363
+ contain ints for array indices.
364
+
365
+ ``path``
366
+ A property that turns ``self.parts`` back into a path string. Parts that
367
+ are array indices are strings like ``'0'``. Raise
368
+ ``jsonpointer.JsonPointerException`` if the parts can't be written in the
369
+ syntax.
370
+
371
+ ``path_join`` returns the ``path`` of the pointer that ``from_parts``
372
+ returns. ``make_patch`` and ``JsonPatch.from_diff`` write the paths of the
373
+ operations they create with it, and the ``path`` and ``from_path`` properties
374
+ of operations use it as well.
375
+
376
+ The following class uses paths like ``a.0.b``, in which the parts are
377
+ separated by ``.``. For simplicity, it doesn't support escaping, so it
378
+ rejects keys that are empty or contain ``.``, as they could not be told apart
379
+ from other paths.
380
+
381
+ .. code-block:: python
382
+
383
+ >>> from jsonpointer import JsonPointer, JsonPointerException
384
+
385
+ >>> class DotPointer(JsonPointer):
386
+ ... """ Paths like 'a.0.b'; '' refers to the whole document """
387
+ ...
388
+ ... def __init__(self, pointer):
389
+ ... self.parts = pointer.split('.') if pointer else []
390
+ ... if '' in self.parts:
391
+ ... raise JsonPointerException('Empty part in %r' % pointer)
392
+ ...
393
+ ... @classmethod
394
+ ... def from_parts(cls, parts):
395
+ ... pointer = cls('')
396
+ ... pointer.parts = [str(part) for part in parts]
397
+ ... return pointer
398
+ ...
399
+ ... @property
400
+ ... def path(self):
401
+ ... for part in self.parts:
402
+ ... if not part or '.' in part:
403
+ ... raise JsonPointerException(
404
+ ... 'Key %r can not be written as a part' % part)
405
+ ... return '.'.join(self.parts)
406
+
407
+ Patches then use this syntax, whether they are written by hand or created by
408
+ diffing two documents:
409
+
410
+ .. code-block:: python
411
+
412
+ >>> doc = {'users': [{'name': 'Alice'}]}
413
+ >>> jsonpatch.apply_patch(doc, [
414
+ ... {'op': 'replace', 'path': 'users.0.name', 'value': 'Bob'},
415
+ ... ], pointer_cls=DotPointer)
416
+ {'users': [{'name': 'Bob'}]}
417
+
418
+ >>> patch = jsonpatch.make_patch(
419
+ ... doc, {'users': [{'name': 'Alice', 'admin': True}]},
420
+ ... pointer_cls=DotPointer)
421
+ >>> patch.patch
422
+ [{'op': 'add', 'path': 'users.0.admin', 'value': True}]
423
+ >>> patch.apply(doc)
424
+ {'users': [{'name': 'Alice', 'admin': True}]}
425
+
426
+ >>> jsonpatch.path_split('users.0.name', pointer_cls=DotPointer)
427
+ ('users', '0', 'name')
428
+ >>> jsonpatch.path_join(['users', 0, 'name'], pointer_cls=DotPointer)
429
+ 'users.0.name'
430
+
431
+ If the class rejects a path or a key, creating or applying the patch fails:
432
+
433
+ .. code-block:: python
434
+
435
+ >>> jsonpatch.make_patch({}, {'a.b': 1}, pointer_cls=DotPointer)
436
+ Traceback (most recent call last):
437
+ ...
438
+ jsonpointer.JsonPointerException: Key 'a.b' can not be written as a part
439
+
440
+ Such patches are not JSON Patches as defined by RFC 6902, which requires
441
+ JSON Pointers. ``path_split`` and ``path_join`` convert them to standard
442
+ patches, for example to pass them on to other software:
443
+
444
+ .. code-block:: python
445
+
446
+ >>> def convert_paths(operations, from_cls, to_cls):
447
+ ... converted = []
448
+ ... for operation in operations:
449
+ ... operation = dict(operation)
450
+ ... for member in ('path', 'from'):
451
+ ... if member in operation:
452
+ ... parts = jsonpatch.path_split(operation[member], from_cls)
453
+ ... operation[member] = jsonpatch.path_join(parts, to_cls)
454
+ ... converted.append(operation)
455
+ ... return converted
456
+
457
+ >>> convert_paths(patch, DotPointer, JsonPointer)
458
+ [{'op': 'add', 'path': '/users/0/admin', 'value': True}]
459
+
460
+ Override the three members together. If a pointer class doesn't override
461
+ ``from_parts``, ``path_join`` and thereby ``make_patch`` write JSON Pointers,
462
+ as ``from_parts`` of ``JsonPointer`` builds those, whatever syntax the class
463
+ reads. This keeps pointer classes working that only change how paths are
464
+ resolved, but a class that only overrides ``__init__`` and ``path`` reads the
465
+ paths of the patches it creates differently than they were written.
335
466
 
336
467
 
337
468
  Dealing with Custom Types
@@ -365,6 +496,7 @@ support for Python's ``Decimal`` type, can be used to create a custom
365
496
  >>> patch.apply(doc)
366
497
  {'foo': 1, 'bar': Decimal('1.10')}
367
498
 
499
+
368
500
  Instead of subclassing it is also possible to pass a dump function to
369
501
  ``from_diff``:
370
502
 
@@ -391,3 +523,44 @@ and load function to ``from_string``:
391
523
  >>> doc = {'foo': 1}
392
524
  >>> patch.apply(doc)
393
525
  {'foo': 1, 'bar': Decimal('1.10')}
526
+
527
+
528
+ String append extension
529
+ -----------------------
530
+
531
+ ``JsonPatchWithAppend`` accepts the standard operations and an additional
532
+ ``append`` operation for existing strings. This extension is not part of
533
+ RFC 6902, so both the producer and consumer of the patch must support it.
534
+ The standard ``JsonPatch`` class and module-level helpers remain unchanged.
535
+
536
+ .. code-block:: python
537
+
538
+ >>> src = {'message': 'Hello'}
539
+ >>> dst = {'message': 'Hello World'}
540
+ >>> patch = jsonpatch.JsonPatchWithAppend.from_diff(src, dst)
541
+ >>> patch.patch
542
+ [{'op': 'append', 'path': '/message', 'value': ' World'}]
543
+ >>> patch.apply(src)
544
+ {'message': 'Hello World'}
545
+ >>> jsonpatch.JsonPatchWithAppend.from_string(patch.to_string()).apply(src) == dst
546
+ True
547
+
548
+ Every append operation requires ``op``, ``path`` and a string ``value``.
549
+ Its target must be an existing string in an object member or array element;
550
+ appending to the root document is not supported. Operations can also be
551
+ constructed directly:
552
+
553
+ .. code-block:: python
554
+
555
+ >>> patch = jsonpatch.JsonPatchWithAppend([
556
+ ... {'op': 'append', 'path': '/message', 'value': '!'},
557
+ ... ])
558
+ >>> patch.apply({'message': 'Hello'})
559
+ {'message': 'Hello!'}
560
+
561
+ Automatic suffix detection applies to object members, including objects
562
+ nested in arrays. Root strings and scalar array elements retain the standard
563
+ diff behavior. ``optimization=False`` disables moves but retains suffix
564
+ detection. ``generate_test_ops=True`` also tests the original string before
565
+ appending. As with custom operations, ``in_place=True, atomic=True`` uses
566
+ the existing copy-based rollback fallback.
@@ -53,6 +53,8 @@ def make_patch(
53
53
  pointer_cls: type[JsonPointer] = ...,
54
54
  generate_test_ops: bool = False,
55
55
  ) -> JsonPatch: ...
56
+ def path_split(path: str, pointer_cls: type[JsonPointer] = ...) -> tuple[str, ...]: ...
57
+ def path_join(parts: Iterable[str | int], pointer_cls: type[JsonPointer] = ...) -> str: ...
56
58
 
57
59
  class PatchOperation:
58
60
  pointer_cls: type[JsonPointer]
@@ -89,6 +91,7 @@ class MoveOperation(PatchOperation):
89
91
 
90
92
  class TestOperation(PatchOperation): ...
91
93
  class CopyOperation(PatchOperation): ...
94
+ class AppendOperation(PatchOperation): ...
92
95
 
93
96
  class JsonPatch:
94
97
  json_dumper: ClassVar[Callable[..., str]]
@@ -123,6 +126,8 @@ class JsonPatch:
123
126
  def to_string(self, dumps: Callable[[Any], str] | None = None) -> str: ...
124
127
  def apply(self, obj: Any, in_place: bool = False, atomic: bool = False) -> Any: ...
125
128
 
129
+ class JsonPatchWithAppend(JsonPatch): ...
130
+
126
131
  # Computes the operations for JsonPatch.from_diff; mostly an implementation
127
132
  # detail, so its internal methods are typed loosely.
128
133
  class DiffBuilder:
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: jsonpatch
3
- Version: 1.44
3
+ Version: 1.45
4
4
  Summary: Apply JSON-Patches (RFC 6902)
5
5
  Home-page: https://github.com/stefankoegl/python-json-patch
6
6
  Author: Stefan Kögl
@@ -70,6 +70,16 @@ See source code for examples
70
70
  * CI: https://github.com/stefankoegl/python-json-patch/actions
71
71
  * Coveralls: https://coveralls.io/github/stefankoegl/python-json-patch
72
72
 
73
+ String append extension
74
+ -----------------------
75
+ `JsonPatchWithAppend` is a drop-in replacement for `JsonPatch` with a
76
+ non-RFC string `append` operation. Its `from_diff()` method sends only the
77
+ new suffix when an object member's string grows. `JsonPatch`, `make_patch()`
78
+ and `apply_patch()` retain their standard RFC 6902 behavior.
79
+
80
+ See the [tutorial](doc/tutorial.rst#string-append-extension) for examples.
81
+ Both sender and receiver must support the extension.
82
+
73
83
  Type hints
74
84
  ----------
75
85
  jsonpatch ships type stubs (in the `jsonpatch-stubs` directory, as
@@ -53,9 +53,13 @@ _ST_REMOVE = 1
53
53
  _EXACT_MATCH_LIMIT = 500 ** 2
54
54
 
55
55
 
56
+ # The from_parts of pointer classes that don't override it, see path_join
57
+ _JSONPOINTER_FROM_PARTS = JsonPointer.from_parts.__func__
58
+
59
+
56
60
  # Will be parsed by setup.py to determine package metadata
57
61
  __author__ = 'Stefan Kögl <stefan@skoegl.net>'
58
- __version__ = '1.44'
62
+ __version__ = '1.45'
59
63
  __website__ = 'https://github.com/stefankoegl/python-json-patch'
60
64
  __license__ = 'BSD-3-Clause'
61
65
 
@@ -190,7 +194,9 @@ def make_patch(src, dst, pointer_cls=JsonPointer, generate_test_ops=False):
190
194
  :param dst: Target JSON document, including arrays and scalar values.
191
195
  :type dst: object
192
196
 
193
- :param pointer_cls: JSON pointer class to use.
197
+ :param pointer_cls: JSON pointer class to use. The paths of the
198
+ created operations are written with
199
+ :func:`path_join`, so they use its syntax.
194
200
  :type pointer_cls: Type[JsonPointer]
195
201
 
196
202
  :param generate_test_ops: Precede each ``remove`` and ``replace``
@@ -211,6 +217,83 @@ def make_patch(src, dst, pointer_cls=JsonPointer, generate_test_ops=False):
211
217
  generate_test_ops=generate_test_ops)
212
218
 
213
219
 
220
+ def path_split(path, pointer_cls=JsonPointer):
221
+ """Splits the ``path`` (or ``from``) of an operation into its parts.
222
+
223
+ The parts are the unescaped reference tokens of the JSON Pointer: ``~1``
224
+ becomes ``/`` and ``~0`` becomes ``~``. They are always strings, also
225
+ those that refer to array elements, as only the document a path is
226
+ applied to tells whether a part is an object key or an array index.
227
+
228
+ This is the reverse of :func:`path_join`.
229
+
230
+ :param path: The path, a JSON Pointer such as ``'/foo/0'``.
231
+ :type path: str
232
+
233
+ :param pointer_cls: JSON pointer class to parse the path with.
234
+ :type pointer_cls: Type[JsonPointer]
235
+
236
+ :return: The unescaped parts of the path; empty for the whole document
237
+ (the path ``''``).
238
+ :rtype: tuple[str, ...]
239
+
240
+ :raises JsonPointerException: if ``path`` is not a valid JSON Pointer.
241
+
242
+ >>> path_split('/foo/0')
243
+ ('foo', '0')
244
+ >>> path_split('/~1fields~1test/a~0b')
245
+ ('/fields/test', 'a~b')
246
+ >>> path_split('')
247
+ ()
248
+ """
249
+ return tuple(pointer_cls(path).parts)
250
+
251
+
252
+ def path_join(parts, pointer_cls=JsonPointer):
253
+ """Joins unescaped parts into a path, as used in the ``path`` (or
254
+ ``from``) of an operation.
255
+
256
+ Each part is converted to a string and escaped: ``~`` becomes ``~0`` and
257
+ ``/`` becomes ``~1``. Integers can be used for array indices.
258
+
259
+ This is the reverse of :func:`path_split`. :meth:`JsonPatch.from_diff`
260
+ and :func:`make_patch` use it to write the paths of the operations they
261
+ create, so these use the syntax of their ``pointer_cls``.
262
+
263
+ If ``pointer_cls`` overrides ``JsonPointer.from_parts``,
264
+ the path is ``pointer_cls.from_parts(parts).path``, so a pointer class
265
+ with a different path syntax overrides ``from_parts`` to build pointers
266
+ from parts. Otherwise the path is a JSON Pointer as defined by RFC 6901,
267
+ and ``pointer_cls`` is not used, as ``from_parts`` of ``JsonPointer``
268
+ always builds such a pointer.
269
+
270
+ :param parts: The object keys and array indices that lead to the
271
+ location; empty for the whole document.
272
+ :type parts: Iterable[str | int]
273
+
274
+ :param pointer_cls: JSON pointer class to build the path with.
275
+ :type pointer_cls: Type[JsonPointer]
276
+
277
+ :return: The path, a JSON Pointer.
278
+ :rtype: str
279
+
280
+ >>> path_join(['foo', 0])
281
+ '/foo/0'
282
+ >>> path_join(['/fields/test', 'a~b'])
283
+ '/~1fields~1test/a~0b'
284
+ >>> path_join([])
285
+ ''
286
+ """
287
+ from_parts = getattr(pointer_cls, 'from_parts', None)
288
+ if from_parts is None or \
289
+ getattr(from_parts, '__func__', None) is _JSONPOINTER_FROM_PARTS:
290
+ # Also for subclasses that only change how paths are parsed, which
291
+ # JsonPointer.from_parts would parse an RFC 6901 pointer with
292
+ return _to_pointer(parts)
293
+
294
+ return from_parts(parts).path
295
+
296
+
214
297
  class _NullJournal(object):
215
298
  """Performs the changes of patch operations without recording them."""
216
299
 
@@ -421,10 +504,20 @@ class PatchOperation(object):
421
504
 
422
505
  @property
423
506
  def path(self):
424
- return '/'.join(self.pointer.parts[:-1])
507
+ """The location of the object or array that contains the target of
508
+ the operation, i.e. its ``path`` without the last part, written in
509
+ the syntax of ``pointer_cls`` (see :func:`path_join`).
510
+
511
+ For example ``'/a/0'`` for the ``path`` ``'/a/0/b'``, and ``''`` for
512
+ a target at the top level of the document. The last part is
513
+ :attr:`key`.
514
+ """
515
+ return path_join(self.pointer.parts[:-1], self.pointer_cls)
425
516
 
426
517
  @property
427
518
  def key(self):
519
+ """The last part of ``path``, as returned by :meth:`get_part`.
520
+ Setting it changes the ``path`` member of the operation."""
428
521
  return self.get_part(-1)
429
522
 
430
523
  @key.setter
@@ -432,6 +525,20 @@ class PatchOperation(object):
432
525
  self.set_part(-1, value)
433
526
 
434
527
  def get_part(self, index):
528
+ """Returns the part of ``path`` at ``index``, unescaped.
529
+
530
+ The part is converted to an int if ``int()`` accepts it, and is a
531
+ str otherwise. Whether it is an array index or an object key is not
532
+ checked, as only the document tells, so numeric object keys are
533
+ converted as well: ``'01'`` and ``'1_0'`` become ``1`` and ``10``.
534
+ To get the exact keys, use :func:`path_split` or ``pointer.parts``.
535
+
536
+ >>> op = RemoveOperation({'op': 'remove', 'path': '/a/0/01/b'})
537
+ >>> [op.get_part(i) for i in range(4)]
538
+ ['a', 0, 1, 'b']
539
+ >>> path_split(op.location)
540
+ ('a', '0', '01', 'b')
541
+ """
435
542
  try:
436
543
  return int(self.pointer.parts[index])
437
544
  except ValueError:
@@ -595,11 +702,16 @@ class MoveOperation(PatchOperation):
595
702
 
596
703
  @property
597
704
  def from_path(self):
705
+ """Like :attr:`PatchOperation.path`, but of the ``from`` member: the location of
706
+ the object or array that contains the moved value."""
598
707
  from_ptr = self._from_pointer()
599
- return '/'.join(from_ptr.parts[:-1])
708
+ return path_join(from_ptr.parts[:-1], self.pointer_cls)
600
709
 
601
710
  @property
602
711
  def from_key(self):
712
+ """The last part of ``from``, as returned by
713
+ :meth:`get_from_part`. Setting it changes the ``from`` member of the
714
+ operation."""
603
715
  return self.get_from_part(-1)
604
716
 
605
717
  @from_key.setter
@@ -607,6 +719,8 @@ class MoveOperation(PatchOperation):
607
719
  self.set_from_part(-1, value)
608
720
 
609
721
  def get_from_part(self, index):
722
+ """Like :meth:`PatchOperation.get_part`, but returns the part of
723
+ ``from`` at ``index``: also numeric object keys become ints."""
610
724
  from_ptr = self._from_pointer()
611
725
  try:
612
726
  return int(from_ptr.parts[index])
@@ -673,6 +787,39 @@ class CopyOperation(PatchOperation):
673
787
  return obj
674
788
 
675
789
 
790
+ class AppendOperation(PatchOperation):
791
+ """Appends a string suffix to an existing string (not part of RFC 6902)."""
792
+
793
+ def _apply(self, obj, journal):
794
+ try:
795
+ value = self.operation['value']
796
+ except KeyError:
797
+ raise InvalidJsonPatch("The operation does not contain a 'value' member", op=self)
798
+ if not isinstance(value, str):
799
+ raise JsonPatchConflict("Cannot append a non-string value", op=self)
800
+
801
+ try:
802
+ subobj, part = self.pointer.to_last(obj)
803
+ except JsonPointerException as ex:
804
+ raise JsonPatchPathNotFound(str(ex), op=self)
805
+
806
+ if part is None:
807
+ raise JsonPatchConflict("Cannot append to root document", op=self)
808
+ if isinstance(subobj, MutableSequence):
809
+ if not isinstance(part, int) or part < 0 or part >= len(subobj):
810
+ raise JsonPatchPathNotFound("Cannot append outside of list", op=self)
811
+ elif isinstance(subobj, MutableMapping):
812
+ if part not in subobj:
813
+ raise JsonPatchPathNotFound("Cannot append to a non-existent member", op=self)
814
+ else:
815
+ raise JsonPatchConflict("Cannot append to a non-string value", op=self)
816
+
817
+ if not isinstance(subobj[part], str):
818
+ raise JsonPatchConflict("Cannot append to a non-string value", op=self)
819
+ journal.setitem(subobj, part, subobj[part] + value)
820
+ return obj
821
+
822
+
676
823
  def _restore(obj, saved):
677
824
  """Restores the contents of a document from a copy of it.
678
825
 
@@ -891,7 +1038,9 @@ class JsonPatch(object):
891
1038
  JSON string.
892
1039
  :type dumps: Callable
893
1040
 
894
- :param pointer_cls: JSON pointer class to use.
1041
+ :param pointer_cls: JSON pointer class to use. The paths of the
1042
+ created operations are written with
1043
+ :func:`path_join`, so they use its syntax.
895
1044
  :type pointer_cls: Type[JsonPointer]
896
1045
 
897
1046
  :param generate_test_ops: Precede each ``remove`` and ``replace``
@@ -1009,6 +1158,35 @@ class JsonPatch(object):
1009
1158
  return cls(operation, pointer_cls=self.pointer_cls)
1010
1159
 
1011
1160
 
1161
+ class JsonPatchWithAppend(JsonPatch):
1162
+ """A JsonPatch with an optional, non-RFC string append operation.
1163
+
1164
+ Each append operation requires full ``op``, ``path`` and ``value`` members.
1165
+ It appends a string suffix to an existing object member or array element.
1166
+ The standard JsonPatch class and module-level helpers remain RFC 6902 only.
1167
+ """
1168
+
1169
+ operations = MappingProxyType(dict(JsonPatch.operations, append=AppendOperation))
1170
+
1171
+ @classmethod
1172
+ def from_diff(cls, src, dst, optimization=True, dumps=None,
1173
+ pointer_cls=JsonPointer, generate_test_ops=False):
1174
+ """Creates a patch, using append for string growth in object members.
1175
+
1176
+ Root strings and scalar array elements retain standard diff behavior.
1177
+ Options follow JsonPatch.from_diff; optimization=False disables moves,
1178
+ while append remains enabled. With generate_test_ops=True, an append
1179
+ is preceded by a test of the original string.
1180
+ """
1181
+ json_dumper = dumps or cls.json_dumper
1182
+ builder = _AppendDiffBuilder(src, dst, json_dumper, pointer_cls=pointer_cls,
1183
+ optimization=optimization,
1184
+ generate_test_ops=generate_test_ops)
1185
+ builder._compare_values((), None, src, dst)
1186
+ ops = copy.deepcopy(list(builder.execute()))
1187
+ return cls(ops, pointer_cls=pointer_cls)
1188
+
1189
+
1012
1190
  class DiffBuilder(object):
1013
1191
 
1014
1192
  def __init__(self, src_doc, dst_doc, dumps=json.dumps, pointer_cls=JsonPointer,
@@ -1082,7 +1260,8 @@ class DiffBuilder(object):
1082
1260
  op_second['op'] == 'add':
1083
1261
  yield {
1084
1262
  'op': 'replace',
1085
- 'path': _to_pointer(op_second['path']),
1263
+ 'path': path_join(op_second['path'],
1264
+ self.pointer_cls),
1086
1265
  'value': op_second['value'],
1087
1266
  }
1088
1267
  i += 2
@@ -1091,7 +1270,8 @@ class DiffBuilder(object):
1091
1270
  operation = operations[i]
1092
1271
  for member in ('from', 'path'):
1093
1272
  if member in operation:
1094
- operation[member] = _to_pointer(operation[member])
1273
+ operation[member] = path_join(operation[member],
1274
+ self.pointer_cls)
1095
1275
  yield operation
1096
1276
  i += 1
1097
1277
 
@@ -1362,6 +1542,20 @@ class DiffBuilder(object):
1362
1542
  self._item_replaced(path, key, dst, src)
1363
1543
 
1364
1544
 
1545
+ class _AppendDiffBuilder(DiffBuilder):
1546
+
1547
+ def _item_replaced(self, path, key, item, old_item):
1548
+ if (path or key is not None) and isinstance(old_item, str) and \
1549
+ isinstance(item, str) and len(item) > len(old_item) and \
1550
+ item.startswith(old_item):
1551
+ location = self._location(_path_join(path, key))
1552
+ self._insert_test(location, old_item)
1553
+ self.insert({'op': 'append', 'path': location,
1554
+ 'value': item[len(old_item):]})
1555
+ else:
1556
+ super()._item_replaced(path, key, item, old_item)
1557
+
1558
+
1365
1559
  def _positional_cost(old, new):
1366
1560
  """ Estimates how many operations change old into new, if the items of
1367
1561
  arrays are compared by position """
@@ -1526,6 +1720,7 @@ def _path_join(path, key):
1526
1720
 
1527
1721
 
1528
1722
  def _to_pointer(path):
1723
+ """ Fast path of path_join for JsonPointer """
1529
1724
  return ''.join('/' + str(part).replace('~', '~0').replace('/', '~1')
1530
1725
  for part in path)
1531
1726
 
@@ -694,6 +694,26 @@ class PatchOperationMachine(RuleBasedStateMachine):
694
694
  self.doc)
695
695
 
696
696
 
697
+ class AppendDiffProperties(unittest.TestCase):
698
+
699
+ @given(key=json_keys, prefix=st.text(max_size=10),
700
+ suffix=st.text(min_size=1, max_size=10), generate_tests=st.booleans())
701
+ def test_string_growth_uses_suffix(self, key, prefix, suffix, generate_tests):
702
+ src, dst = {key: prefix}, {key: prefix + suffix}
703
+ patch = jsonpatch.JsonPatchWithAppend.from_diff(
704
+ src, dst, generate_test_ops=generate_tests)
705
+ self.assertEqual(patch.patch[-1]['op'], 'append')
706
+ self.assertEqual(patch.patch[-1]['value'], suffix)
707
+ self.assertEqual(patch.apply(src), dst)
708
+
709
+ @given(pair=doc_pairs)
710
+ def test_generated_patch_round_trip(self, pair):
711
+ src, dst = pair
712
+ patch = jsonpatch.JsonPatchWithAppend.from_diff(src, dst)
713
+ restored = jsonpatch.JsonPatchWithAppend.from_string(patch.to_string())
714
+ assert_json_equal(restored.apply(src), dst)
715
+
716
+
697
717
  PatchOperationTests = PatchOperationMachine.TestCase
698
718
 
699
719