Skip to content

docs: explain two-phase flow-sequence handling in sync() #53

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
nathanjmcdougall wants to merge 2 commits into
base: main
Choose a base branch
from
Open

docs: explain two-phase flow-sequence handling in sync() #53

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ca00e25
docs: explain two-phase flow-sequence handling in sync()
nathanjmcdougall May 27, 2026
9281d19
docs: refine two-phase flow-sequence comment in sync()
nathanjmcdougall May 27, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 12 additions & 3 deletions src/yamltrip/document.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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-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
# 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(
self._core_doc, old_value, value, normalized
Expand All @@ -488,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)])
Expand Down
Loading