From 4ad8ccd1f4618887f14f7be077994467d4889ea8 Mon Sep 17 00:00:00 2001
From: Anton Pepperok <perchneko.anton@gmail.com>
Date: Tue, 27 Oct 2026 07:54:39 +0200
Subject: [PATCH] docs: explain patch failure with copy and in-place modes

---
 doc/tutorial.rst | 38 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)

diff --git a/doc/tutorial.rst b/doc/tutorial.rst
index d4609db..6c9a641 100644
--- a/doc/tutorial.rst
+++ b/doc/tutorial.rst
@@ -86,6 +86,44 @@ explicitly.
     >>> res = jsonpatch.apply_patch(obj, patch)
 
 
+When an Operation Fails
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Operations are applied in order. If an operation raises an exception,
+application stops. With the default ``in_place=False``, operations affect a
+copy, so the original document is unchanged:
+
+.. code-block:: python
+
+    >>> import jsonpatch
+    >>> original = {'value': 1}
+    >>> patch = [
+    ...     {'op': 'replace', 'path': '/value', 'value': 2},
+    ...     {'op': 'test', 'path': '/value', 'value': 3},
+    ... ]
+    >>> try:
+    ...     jsonpatch.apply_patch(original, patch)
+    ... except jsonpatch.JsonPatchTestFailed:
+    ...     print('Test failed')
+    Test failed
+    >>> original
+    {'value': 1}
+
+With ``in_place=True``, the same patch raises ``JsonPatchTestFailed``, but
+the earlier replacement remains in the original document. Failed patches
+do not roll back changes already made in place:
+
+.. code-block:: python
+
+    >>> try:
+    ...     jsonpatch.apply_patch(original, patch, in_place=True)
+    ... except jsonpatch.JsonPatchTestFailed:
+    ...     print('Test failed')
+    Test failed
+    >>> original
+    {'value': 2}
+
+
 Replacing the Whole Document
 ----------------------------