From ca00e2508ec4d42bbc6e71a54adfb7f667172813 Mon Sep 17 00:00:00 2001 From: Nathan McDougall Date: Wed, 27 May 2026 15:44:23 +1200 Subject: [PATCH 1/2] docs: explain two-phase flow-sequence handling in sync() --- src/yamltrip/document.py | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/src/yamltrip/document.py b/src/yamltrip/document.py index 555d598..e7d118a 100644 --- a/src/yamltrip/document.py +++ b/src/yamltrip/document.py @@ -468,8 +468,16 @@ def sync(self, *keys: KeyPart, value: Any) -> Document: except (ValueError, KeyError): return self.upsert(*normalized, value=value) - # Pre-convert any flow sequences that will be modified. - # This targets only the affected leaf paths, preserving sibling formatting. + # Two-phase flow-sequence handling: + # + # Phase 1 (_flow_seq_replacements) pre-converts only the flow sequences + # that will be modified. A full replace at a higher path would + # re-serialise the whole mapping with 2-space indentation, losing the + # document's existing indent for nested lists. + # + # Phase 2 (except PatchError below) catches cases phase 1 misses. The + # main gap is list reordering: new indices in the diff weren't in the + # original tree, so phase 1 couldn't anticipate them. doc: Document = self flow_patches = _flow_seq_replacements( self._core_doc, old_value, value, normalized From 9281d1978f651e2aa02b5a5ac6e4ef4ffc9270e5 Mon Sep 17 00:00:00 2001 From: Nathan McDougall Date: Thu, 28 May 2026 07:38:58 +1200 Subject: [PATCH 2/2] docs: refine two-phase flow-sequence comment in sync() --- src/yamltrip/document.py | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/src/yamltrip/document.py b/src/yamltrip/document.py index e7d118a..66bd78a 100644 --- a/src/yamltrip/document.py +++ b/src/yamltrip/document.py @@ -472,11 +472,11 @@ def sync(self, *keys: KeyPart, value: Any) -> Document: # # Phase 1 (_flow_seq_replacements) pre-converts only the flow sequences # that will be modified. A full replace at a higher path would - # re-serialise the whole mapping with 2-space indentation, losing the - # document's existing indent for nested lists. + # re-serialize the whole mapping with the default indentation, losing + # the document's existing indent for nested lists. # # Phase 2 (except PatchError below) catches cases phase 1 misses. The - # main gap is list reordering: new indices in the diff weren't in the + # known gap is list reordering: new indices in the diff weren't in the # original tree, so phase 1 couldn't anticipate them. doc: Document = self flow_patches = _flow_seq_replacements( @@ -496,7 +496,8 @@ def sync(self, *keys: KeyPart, value: Any) -> Document: if _classify_patch_error(e) != _PatchErrorKind.BLOCK_SEQUENCE_EXPECTED: raise # Fallback: a flow sequence was missed by pre-detection (e.g. due to - # list reordering). Replace the entire synced value. + # list reordering). Full replace from original doc; phase 1 work + # is superseded. route = _make_route(normalized) op = Op.replace(value) return self._apply_patches([Patch(route=route, operation=op)])