|
| 1 | +"""Preserve user-owned regions across ``copier update``. |
| 2 | +
|
| 3 | +Templates often ship files with dummy content or ``TODO`` markers that the |
| 4 | +developer is expected to replace right after generating a project. On a later |
| 5 | +``copier update``, Copier's 3-way merge treats those regions like any other |
| 6 | +template-owned content, so a change to the placeholder in the template can |
| 7 | +clobber the developer's implementation (or raise a needless merge conflict). |
| 8 | +
|
| 9 | +This module lets a template author wrap such a region in a pair of *preserve |
| 10 | +markers*. Everything **between** the markers becomes developer-owned: its |
| 11 | +content is captured from the existing project before an update and written |
| 12 | +back into every intermediate render, so the merge sees identical content on |
| 13 | +all sides and leaves the developer's version untouched. The marker lines |
| 14 | +themselves, and everything around them, keep updating from the template as |
| 15 | +usual. |
| 16 | +
|
| 17 | +A marker is any line that *contains* the sentinel token, so it works |
| 18 | +regardless of the host language's comment syntax:: |
| 19 | +
|
| 20 | + # copier:preserve:start greeting |
| 21 | + def greeting() -> str: |
| 22 | + return "Hello from the developer!" |
| 23 | + # copier:preserve:end greeting |
| 24 | +
|
| 25 | +The optional identifier after the token (``greeting`` above) lets Copier match |
| 26 | +a region to its counterpart even if the region moves within the file between |
| 27 | +template versions. Unidentified regions are matched by their order of |
| 28 | +appearance instead. |
| 29 | +
|
| 30 | +See the ``updating.md`` documentation for the user-facing description. |
| 31 | +""" |
| 32 | + |
| 33 | +from __future__ import annotations |
| 34 | + |
| 35 | +import re |
| 36 | +from collections.abc import Iterable |
| 37 | +from dataclasses import dataclass |
| 38 | +from pathlib import Path |
| 39 | + |
| 40 | +__all__ = [ |
| 41 | + "PRESERVE_END_TOKEN", |
| 42 | + "PRESERVE_START_TOKEN", |
| 43 | + "capture_preserved_regions", |
| 44 | + "find_marker_files", |
| 45 | + "restore_preserved_regions", |
| 46 | +] |
| 47 | + |
| 48 | +#: Sentinel token opening a preserved region. |
| 49 | +PRESERVE_START_TOKEN = "copier:preserve:start" |
| 50 | +#: Sentinel token closing a preserved region. |
| 51 | +PRESERVE_END_TOKEN = "copier:preserve:end" |
| 52 | + |
| 53 | +# The identifier (if any) follows the token after a ``:`` or whitespace and |
| 54 | +# runs until the next whitespace, so it can be embedded in a comment. |
| 55 | +_START_RE = re.compile(re.escape(PRESERVE_START_TOKEN) + r"(?:[:\s]+(?P<id>\S+))?") |
| 56 | +_END_RE = re.compile(re.escape(PRESERVE_END_TOKEN) + r"(?:[:\s]+(?P<id>\S+))?") |
| 57 | + |
| 58 | + |
| 59 | +class PreserveMarkerError(ValueError): |
| 60 | + """Raised when preserve markers in a file are unbalanced or nested.""" |
| 61 | + |
| 62 | + |
| 63 | +@dataclass(frozen=True) |
| 64 | +class _Region: |
| 65 | + """A single preserved region parsed from a file.""" |
| 66 | + |
| 67 | + identifier: str | None |
| 68 | + body: str |
| 69 | + start_line: int # index of the start-marker line |
| 70 | + end_line: int # index of the end-marker line |
| 71 | + |
| 72 | + |
| 73 | +# A hashable key that maps a region to its counterpart in another render. |
| 74 | +_RegionKey = str | tuple[str, int] |
| 75 | + |
| 76 | + |
| 77 | +def _parse_regions(text: str) -> list[_Region]: |
| 78 | + """Parse all preserved regions from ``text``. |
| 79 | +
|
| 80 | + Raises: |
| 81 | + PreserveMarkerError: If a start marker is nested inside another, or a |
| 82 | + start/end marker has no matching counterpart. |
| 83 | + """ |
| 84 | + lines = text.splitlines(keepends=True) |
| 85 | + regions: list[_Region] = [] |
| 86 | + open_identifier: str | None = None |
| 87 | + open_start: int | None = None |
| 88 | + open_body: list[str] = [] |
| 89 | + for idx, line in enumerate(lines): |
| 90 | + if (match := _START_RE.search(line)) is not None: |
| 91 | + if open_start is not None: |
| 92 | + raise PreserveMarkerError( |
| 93 | + f"nested preserve start marker at line {idx + 1}" |
| 94 | + ) |
| 95 | + open_identifier = match.group("id") |
| 96 | + open_start = idx |
| 97 | + open_body = [] |
| 98 | + elif _END_RE.search(line) is not None: |
| 99 | + if open_start is None: |
| 100 | + raise PreserveMarkerError( |
| 101 | + f"preserve end marker without matching start at line {idx + 1}" |
| 102 | + ) |
| 103 | + regions.append( |
| 104 | + _Region( |
| 105 | + identifier=open_identifier, |
| 106 | + body="".join(open_body), |
| 107 | + start_line=open_start, |
| 108 | + end_line=idx, |
| 109 | + ) |
| 110 | + ) |
| 111 | + open_start = None |
| 112 | + open_identifier = None |
| 113 | + open_body = [] |
| 114 | + elif open_start is not None: |
| 115 | + open_body.append(line) |
| 116 | + if open_start is not None: |
| 117 | + raise PreserveMarkerError( |
| 118 | + f"preserve start marker at line {open_start + 1} is never closed" |
| 119 | + ) |
| 120 | + return regions |
| 121 | + |
| 122 | + |
| 123 | +def _keyed_regions(regions: list[_Region]) -> list[tuple[_RegionKey, _Region]]: |
| 124 | + """Pair each region with a key used to match it across renders. |
| 125 | +
|
| 126 | + Named regions are keyed by their identifier; unnamed regions are keyed by |
| 127 | + their positional index among the unnamed regions. |
| 128 | + """ |
| 129 | + keyed: list[tuple[_RegionKey, _Region]] = [] |
| 130 | + anonymous_index = 0 |
| 131 | + for region in regions: |
| 132 | + if region.identifier is not None: |
| 133 | + keyed.append((region.identifier, region)) |
| 134 | + else: |
| 135 | + keyed.append((("", anonymous_index), region)) |
| 136 | + anonymous_index += 1 |
| 137 | + return keyed |
| 138 | + |
| 139 | + |
| 140 | +def _read_text(path: Path) -> str | None: |
| 141 | + """Read ``path`` as UTF-8 text, or return ``None`` if that's not possible.""" |
| 142 | + if not path.is_file() or path.is_symlink(): |
| 143 | + return None |
| 144 | + try: |
| 145 | + return path.read_text(encoding="utf-8") |
| 146 | + except (OSError, UnicodeDecodeError): |
| 147 | + return None |
| 148 | + |
| 149 | + |
| 150 | +def find_marker_files(root: Path) -> set[Path]: |
| 151 | + """Return the paths (relative to ``root``) of files with preserve markers. |
| 152 | +
|
| 153 | + Only regular, UTF-8-decodable files that contain the start token are |
| 154 | + returned; the ``.git`` directory is skipped. This is meant to be run |
| 155 | + against a *template render*, which bounds the scan to template-managed |
| 156 | + files instead of the whole (potentially huge) project tree. |
| 157 | + """ |
| 158 | + found: set[Path] = set() |
| 159 | + for path in root.rglob("*"): |
| 160 | + if ".git" in path.parts: |
| 161 | + continue |
| 162 | + text = _read_text(path) |
| 163 | + if text is not None and PRESERVE_START_TOKEN in text: |
| 164 | + found.add(path.relative_to(root)) |
| 165 | + return found |
| 166 | + |
| 167 | + |
| 168 | +def capture_preserved_regions( |
| 169 | + root: Path, relpaths: Iterable[Path] | None = None |
| 170 | +) -> dict[Path, dict[_RegionKey, str]]: |
| 171 | + """Capture the content of preserved regions under ``root``. |
| 172 | +
|
| 173 | + Args: |
| 174 | + root: Directory holding the files to read (typically the existing |
| 175 | + project). |
| 176 | + relpaths: The candidate files to inspect, relative to ``root``. When |
| 177 | + ``None``, ``root`` is scanned recursively; callers that already |
| 178 | + know the template-managed files (see :func:`find_marker_files`) |
| 179 | + should pass them to avoid walking unrelated project content. |
| 180 | +
|
| 181 | + Returns: |
| 182 | + A mapping from each file's path (relative to ``root``) to a mapping of |
| 183 | + region key to the region's current body. Only files that contain at |
| 184 | + least one well-formed preserved region are included. Files with |
| 185 | + malformed markers are skipped so they never break an update. |
| 186 | + """ |
| 187 | + if relpaths is None: |
| 188 | + relpaths = find_marker_files(root) |
| 189 | + captured: dict[Path, dict[_RegionKey, str]] = {} |
| 190 | + for relpath in relpaths: |
| 191 | + text = _read_text(root / relpath) |
| 192 | + if text is None or PRESERVE_START_TOKEN not in text: |
| 193 | + continue |
| 194 | + try: |
| 195 | + regions = _parse_regions(text) |
| 196 | + except PreserveMarkerError: |
| 197 | + continue |
| 198 | + if regions: |
| 199 | + captured[relpath] = { |
| 200 | + key: region.body for key, region in _keyed_regions(regions) |
| 201 | + } |
| 202 | + return captured |
| 203 | + |
| 204 | + |
| 205 | +def _apply_regions(text: str, bodies: dict[_RegionKey, str]) -> str: |
| 206 | + """Return ``text`` with each matching region body replaced from ``bodies``.""" |
| 207 | + lines = text.splitlines(keepends=True) |
| 208 | + result: list[str] = [] |
| 209 | + cursor = 0 |
| 210 | + for key, region in _keyed_regions(_parse_regions(text)): |
| 211 | + if key not in bodies: |
| 212 | + continue |
| 213 | + # Emit everything up to and including the start-marker line, then the |
| 214 | + # captured body, and resume from the end-marker line so the (possibly |
| 215 | + # updated) marker lines themselves are preserved from the template. |
| 216 | + result.extend(lines[cursor : region.start_line + 1]) |
| 217 | + result.append(bodies[key]) |
| 218 | + cursor = region.end_line |
| 219 | + result.extend(lines[cursor:]) |
| 220 | + return "".join(result) |
| 221 | + |
| 222 | + |
| 223 | +def restore_preserved_regions( |
| 224 | + root: Path, captured: dict[Path, dict[_RegionKey, str]] |
| 225 | +) -> None: |
| 226 | + """Write captured region bodies back into the matching files under ``root``. |
| 227 | +
|
| 228 | + Files, or individual regions, that are missing from a given render are left |
| 229 | + as-is, so brand-new regions introduced by the template still appear. Files |
| 230 | + with malformed markers are skipped. |
| 231 | +
|
| 232 | + Args: |
| 233 | + root: Directory whose files should receive the captured content. |
| 234 | + captured: The mapping returned by :func:`capture_preserved_regions`. |
| 235 | + """ |
| 236 | + for relpath, bodies in captured.items(): |
| 237 | + target = root / relpath |
| 238 | + text = _read_text(target) |
| 239 | + if text is None or PRESERVE_START_TOKEN not in text: |
| 240 | + continue |
| 241 | + try: |
| 242 | + new_text = _apply_regions(text, bodies) |
| 243 | + except PreserveMarkerError: |
| 244 | + continue |
| 245 | + if new_text != text: |
| 246 | + target.write_text(new_text, encoding="utf-8") |
0 commit comments