wpsync 1.17.2__py3-none-any.whl

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.
@@ -0,0 +1,526 @@
1
+ """The post Markdown dialect, rendered to HTML trees and converted back.
2
+
3
+ The dialect is CommonMark with pipe tables, Pandoc-style attributes
4
+ (`[text]{.class}`, `{key=value}` after links and images, `{.class}` before a
5
+ block), fenced divs (`::: {.class}`), and Pandoc raw HTML fences
6
+ (```` ```{=html} ````), whose content is published exactly as written. The
7
+ converter is the inverse of the renderer: it writes only constructs the
8
+ renderer reads back to the same tree, and raises `Unconvertible` for anything
9
+ else.
10
+ """
11
+
12
+ from __future__ import annotations
13
+
14
+ import re
15
+ from collections.abc import Callable, Sequence
16
+ from dataclasses import dataclass
17
+
18
+ from markdown_it import MarkdownIt
19
+ from markdown_it.common.html_blocks import block_names
20
+ from markdown_it.token import Token
21
+ from mdit_py_plugins.attrs import attrs_block_plugin, attrs_plugin
22
+ from mdit_py_plugins.attrs.parse import parse as parse_attrs
23
+ from mdit_py_plugins.container import container_plugin
24
+
25
+ from wpsync.markup.dom import (
26
+ BLOCK_TAGS,
27
+ VOID_TAGS,
28
+ Comment,
29
+ Element,
30
+ Node,
31
+ parse_html,
32
+ serialize,
33
+ start_tag,
34
+ )
35
+
36
+
37
+ class Unconvertible(Exception):
38
+ """An element with no Markdown form that renders back identically."""
39
+
40
+
41
+ def _render_div(self, tokens, index, options, env) -> str: # noqa: ANN001
42
+ token = tokens[index]
43
+ if token.nesting < 0:
44
+ return "</div>\n"
45
+ info = token.info.strip()
46
+ attrs = parse_attrs(info)[1] if info.startswith("{") else {}
47
+ return start_tag(Element("div", dict(attrs))) + "\n"
48
+
49
+
50
+ RAW_FENCE_INFO = "{=html}"
51
+
52
+
53
+ def _parser() -> MarkdownIt:
54
+ parser = (
55
+ MarkdownIt("commonmark", {"html": True})
56
+ .enable("table")
57
+ .use(attrs_plugin, spans=True)
58
+ .use(attrs_block_plugin)
59
+ .use(container_plugin, name="div", validate=lambda *_: True, render=_render_div)
60
+ )
61
+ parser.normalizeLink = lambda url: url # type: ignore[method-assign]
62
+ parser.normalizeLinkText = lambda text: text # type: ignore[method-assign]
63
+ parser.add_render_rule("softbreak", lambda *_: " ")
64
+ fence = parser.renderer.rules["fence"]
65
+
66
+ def render_fence(self, tokens, index, options, env) -> str: # noqa: ANN001
67
+ token = tokens[index]
68
+ if token.info.strip() == RAW_FENCE_INFO:
69
+ return token.content
70
+ return fence(tokens, index, options, env)
71
+
72
+ parser.add_render_rule("fence", render_fence)
73
+ return parser
74
+
75
+
76
+ PARSER = _parser()
77
+
78
+
79
+ TokenTransform = Callable[[list[Token]], list[Token]]
80
+
81
+
82
+ @dataclass(frozen=True)
83
+ class Piece:
84
+ """One top-level block of a document."""
85
+
86
+ tokens: list[Token]
87
+ raw: str | None = None
88
+ """The exact HTML of a raw block, published without rendering."""
89
+
90
+
91
+ def pieces(markdown: str) -> list[Piece]:
92
+ """Split a document into top-level blocks, keeping raw HTML separate."""
93
+ result: list[Piece] = []
94
+ current: list[Token] = []
95
+ depth = 0
96
+ for token in PARSER.parse(markdown):
97
+ raw_fence = token.type == "fence" and token.info.strip() == RAW_FENCE_INFO
98
+ if depth == 0 and (token.type == "html_block" or raw_fence):
99
+ result.append(Piece([token], token.content.removesuffix("\n")))
100
+ continue
101
+ current.append(token)
102
+ depth += token.nesting
103
+ if depth == 0:
104
+ result.append(Piece(current))
105
+ current = []
106
+ return result
107
+
108
+
109
+ def render_tokens(tokens: list[Token]) -> list[Node]:
110
+ return parse_html(PARSER.renderer.render(tokens, PARSER.options, {}))
111
+
112
+
113
+ def kept_markdown(source: str) -> str:
114
+ """Markdown that publishes HTML source exactly as written.
115
+
116
+ Plain HTML is used when Markdown reads it back unchanged; otherwise the
117
+ source goes into a raw HTML fence.
118
+ """
119
+ tokens = PARSER.parse(source)
120
+ if (
121
+ len(tokens) == 1
122
+ and tokens[0].type == "html_block"
123
+ and tokens[0].content.removesuffix("\n") == source
124
+ ):
125
+ return source
126
+ longest = max((len(run) for run in re.findall(r"`+", source)), default=0)
127
+ fence = "`" * max(3, longest + 1)
128
+ return f"{fence}{RAW_FENCE_INFO}\n{source}\n{fence}"
129
+
130
+
131
+ def image_sources(markdown: str) -> set[str]:
132
+ """The sources of the images a document shows through Markdown syntax."""
133
+ sources = set()
134
+ for token in PARSER.parse(markdown):
135
+ for child in token.children or []:
136
+ if child.type == "image":
137
+ sources.add(str(child.attrs["src"]))
138
+ return sources
139
+
140
+
141
+ def render_inline(token: Token) -> list[Node]:
142
+ return parse_html(PARSER.renderer.render([token], PARSER.options, {}))
143
+
144
+
145
+ # Converting HTML trees to Markdown -------------------------------------------
146
+
147
+ ESCAPED = re.compile(r"([\\`*{}<]|\](?=[(\[{:]))")
148
+ LOOSE_UNDERSCORE = re.compile(r"(?<![A-Za-z0-9])_|_(?![A-Za-z0-9])")
149
+ ENTITY_LIKE = re.compile(r"&(?=#?[A-Za-z0-9]+;)")
150
+ LINE_START = re.compile(r"^(?:([#>+=|-])|(\d+)([.)]))", re.M)
151
+ TYPE_ONE_TAGS = frozenset({"pre", "script", "style", "textarea"})
152
+ TYPE_SIX_TAGS = frozenset(block_names)
153
+
154
+
155
+ def _escape(text: str) -> str:
156
+ text = ESCAPED.sub(r"\\\1", text)
157
+ text = LOOSE_UNDERSCORE.sub(r"\\_", text)
158
+ return ENTITY_LIKE.sub(r"\\&", text)
159
+
160
+
161
+ def _escape_line_starts(markdown: str) -> str:
162
+ def escape(match: re.Match[str]) -> str:
163
+ return "\\" + match[1] if match[1] else f"{match[2]}\\{match[3]}"
164
+
165
+ return LINE_START.sub(escape, markdown)
166
+
167
+
168
+ def _attribute_list(attrs: dict[str, str]) -> str:
169
+ parts = []
170
+ # Pandoc's convention puts the id and classes before other attributes.
171
+ ordered = sorted(attrs.items(), key=lambda item: item[0] not in ("id", "class"))
172
+ for name, value in ordered:
173
+ if name == "class":
174
+ parts.extend(f".{cls}" for cls in value.split())
175
+ elif name == "id" and re.fullmatch(r"[A-Za-z][\w-]*", value):
176
+ parts.append(f"#{value}")
177
+ elif re.fullmatch(r"[\w-]+", value):
178
+ parts.append(f"{name}={value}")
179
+ else:
180
+ escaped = value.replace("\\", "\\\\").replace('"', '\\"')
181
+ parts.append(f'{name}="{escaped}"')
182
+ return "{" + " ".join(parts) + "}"
183
+
184
+
185
+ def _attributes(attrs: dict[str, str]) -> str:
186
+ return _attribute_list(attrs) if attrs else ""
187
+
188
+
189
+ class Converter:
190
+ """Converts HTML trees to the dialect, dropping the given bookkeeping classes."""
191
+
192
+ def __init__(self, ignored_classes: frozenset[str] = frozenset()) -> None:
193
+ self.ignored_classes = ignored_classes
194
+ self.in_link = False
195
+
196
+ def attrs(self, element: Element) -> dict[str, str]:
197
+ attrs = dict(element.attrs)
198
+ if "class" in attrs:
199
+ classes = [
200
+ cls for cls in attrs["class"].split() if cls not in self.ignored_classes
201
+ ]
202
+ if classes:
203
+ attrs["class"] = " ".join(classes)
204
+ else:
205
+ del attrs["class"]
206
+ return attrs
207
+
208
+ # Inline content ------------------------------------------------------
209
+
210
+ def inline(self, nodes: Sequence[Node]) -> str:
211
+ return "".join(self._inline_node(node) for node in nodes)
212
+
213
+ def _inline_node(self, node: Node) -> str:
214
+ if isinstance(node, str):
215
+ return _escape(re.sub(r"[ \t\n\r\f]+", " ", node))
216
+ if isinstance(node, Comment):
217
+ return f"<!--{node.text}-->"
218
+ attrs = self.attrs(node)
219
+ match node.tag:
220
+ case "strong" | "b" | "em" | "i" if not attrs:
221
+ marker = "**" if node.tag in ("strong", "b") else "*"
222
+ inner = self.inline(node.children)
223
+ stripped = inner.strip(" ")
224
+ if not stripped:
225
+ return inner
226
+ lead = inner[: len(inner) - len(inner.lstrip(" "))]
227
+ trail = inner[len(inner.rstrip(" ")) :]
228
+ return f"{lead}{marker}{stripped}{marker}{trail}"
229
+ case "code" if not attrs and all(isinstance(c, str) for c in node.children):
230
+ return _code_span("".join(node.children)) # type: ignore[arg-type]
231
+ case "a" if "href" in attrs:
232
+ href = attrs.pop("href")
233
+ title = attrs.pop("title", None)
234
+ # Bracketed spans cannot nest inside link text.
235
+ self.in_link = True
236
+ try:
237
+ text = self.inline(node.children)
238
+ finally:
239
+ self.in_link = False
240
+ return f"[{text}]({_destination(href, title)})" + _attributes(attrs)
241
+ case "img" if "src" in attrs:
242
+ src = attrs.pop("src")
243
+ alt = attrs.pop("alt", "")
244
+ title = attrs.pop("title", None)
245
+ return f"![{_escape(alt)}]({_destination(src, title)})" + _attributes(
246
+ attrs
247
+ )
248
+ case "br" if not attrs:
249
+ return "\\\n"
250
+ case "span" if not attrs:
251
+ return self.inline(node.children)
252
+ case "span" if not self.in_link:
253
+ return f"[{self.inline(node.children)}]{_attribute_list(attrs)}"
254
+ return self.raw_inline(node)
255
+
256
+ def raw_inline(self, element: Element) -> str:
257
+ tag = start_tag(element)
258
+ if element.tag in VOID_TAGS:
259
+ return tag
260
+ return f"{tag}{self.inline(element.children)}</{element.tag}>"
261
+
262
+ # Blocks --------------------------------------------------------------
263
+
264
+ def block(self, node: Node) -> str:
265
+ if isinstance(node, Comment):
266
+ return raw_block(node)
267
+ if isinstance(node, str):
268
+ raise Unconvertible("text outside a block")
269
+ attrs = self.attrs(node)
270
+ tag = node.tag
271
+ if tag == "p":
272
+ body = _escape_line_starts(self.inline(node.children)).strip(" ")
273
+ if not body:
274
+ raise Unconvertible("empty paragraph")
275
+ return _with_block_attrs(attrs, body)
276
+ if re.fullmatch(r"h[1-6]", tag):
277
+ body = _escape_line_starts(self.inline(node.children)).strip(" ")
278
+ if "\n" in body:
279
+ raise Unconvertible("line break in heading")
280
+ if body.endswith("#"):
281
+ body = body[:-1] + "\\#"
282
+ return _with_block_attrs(attrs, f"{'#' * int(tag[1])} {body}".rstrip())
283
+ if tag in ("ul", "ol"):
284
+ return self.list(node, attrs)
285
+ if tag == "blockquote":
286
+ inner = self.blocks(node.children)
287
+ quoted = "\n".join(
288
+ f"> {line}" if line else ">" for line in inner.split("\n")
289
+ )
290
+ return _with_block_attrs(attrs, quoted)
291
+ if tag == "pre":
292
+ return self.code_block(node, attrs)
293
+ if tag == "hr":
294
+ return _with_block_attrs(attrs, "---")
295
+ if tag == "table":
296
+ return _with_block_attrs(attrs, self.table(node))
297
+ if tag == "div":
298
+ inner = self.blocks(node.children)
299
+ fence = ":" * (3 + _div_depth(node.children))
300
+ opening = f"{fence} {_attribute_list(attrs)}" if attrs else fence
301
+ return f"{opening}\n{inner}\n{fence}"
302
+ raise Unconvertible(f"<{tag}>")
303
+
304
+ def blocks(self, nodes: Sequence[Node]) -> str:
305
+ children = [
306
+ node for node in nodes if not (isinstance(node, str) and not node.strip())
307
+ ]
308
+ if not children:
309
+ raise Unconvertible("empty container")
310
+ return join_blocks([self.block_or_raw(child) for child in children])
311
+
312
+ def block_or_raw(self, node: Node) -> str:
313
+ try:
314
+ return self.block(node)
315
+ except Unconvertible:
316
+ return raw_block(node)
317
+
318
+ def list(self, element: Element, attrs: dict[str, str]) -> str:
319
+ start = 1
320
+ if element.tag == "ol" and "start" in attrs:
321
+ if not attrs["start"].isdigit():
322
+ raise Unconvertible("list start")
323
+ start = int(attrs.pop("start"))
324
+ items = [
325
+ child
326
+ for child in element.children
327
+ if not (isinstance(child, str) and not child.strip())
328
+ ]
329
+ if not items or any(
330
+ not isinstance(item, Element) or item.tag != "li" for item in items
331
+ ):
332
+ raise Unconvertible("list content")
333
+ loose = any(
334
+ isinstance(child, Element) and child.tag == "p"
335
+ for item in items
336
+ for child in item.children # type: ignore[union-attr]
337
+ )
338
+ lines = []
339
+ for offset, item in enumerate(items):
340
+ assert isinstance(item, Element)
341
+ if self.attrs(item):
342
+ raise Unconvertible("list item attributes")
343
+ marker = f"{start + offset}. " if element.tag == "ol" else "- "
344
+ body = self.loose_item(item) if loose else self.tight_item(item)
345
+ first, *rest = body.split("\n")
346
+ indent = " " * len(marker)
347
+ lines.append((marker + first).rstrip())
348
+ lines.extend(indent + line if line else "" for line in rest)
349
+ if loose and offset < len(items) - 1:
350
+ lines.append("")
351
+ return _with_block_attrs(attrs, "\n".join(lines))
352
+
353
+ def tight_item(self, item: Element) -> str:
354
+ children = list(item.children)
355
+ nested = []
356
+ while children and (
357
+ (isinstance(children[-1], Element) and children[-1].tag in ("ul", "ol"))
358
+ or (isinstance(children[-1], str) and not children[-1].strip())
359
+ ):
360
+ node = children.pop()
361
+ if isinstance(node, Element):
362
+ nested.insert(0, node)
363
+ if any(
364
+ isinstance(child, Element) and child.tag in BLOCK_TAGS for child in children
365
+ ):
366
+ raise Unconvertible("block inside a tight list item")
367
+ text = _escape_line_starts(self.inline(children)).strip(" ")
368
+ parts = [text] + [self.block(child) for child in nested]
369
+ return "\n".join(parts)
370
+
371
+ def loose_item(self, item: Element) -> str:
372
+ return self.blocks(item.children)
373
+
374
+ def code_block(self, pre: Element, attrs: dict[str, str]) -> str:
375
+ children = [child for child in pre.children]
376
+ if attrs or len(children) != 1 or not isinstance(children[0], Element):
377
+ raise Unconvertible("preformatted text")
378
+ code = children[0]
379
+ code_attrs = self.attrs(code)
380
+ language = ""
381
+ if code_attrs:
382
+ match = re.fullmatch(r"language-(\S+)", code_attrs.get("class", ""))
383
+ if len(code_attrs) != 1 or not match:
384
+ raise Unconvertible("code attributes")
385
+ language = match[1]
386
+ if code.tag != "code" or not all(isinstance(c, str) for c in code.children):
387
+ raise Unconvertible("preformatted markup")
388
+ text = "".join(code.children).removesuffix("\n") # type: ignore[arg-type]
389
+ longest = max((len(run) for run in re.findall(r"`+", text)), default=0)
390
+ fence = "`" * max(3, longest + 1)
391
+ return f"{fence}{language}\n{text}\n{fence}"
392
+
393
+ def table(self, table: Element) -> str:
394
+ sections = [c for c in table.children if isinstance(c, Element)]
395
+ if [s.tag for s in sections] not in (["thead", "tbody"], ["thead"]):
396
+ raise Unconvertible("table layout")
397
+ rows = [
398
+ [cell for cell in row.children if isinstance(cell, Element)]
399
+ for section in sections
400
+ for row in section.children
401
+ if isinstance(row, Element)
402
+ ]
403
+ header, body = rows[0], rows[1:]
404
+ width = len(header)
405
+ if any(len(row) != width for row in body):
406
+ raise Unconvertible("ragged table")
407
+ if any(cell.tag != "th" for cell in header) or any(
408
+ cell.tag != "td" for row in body for cell in row
409
+ ):
410
+ raise Unconvertible("table cells")
411
+ alignments = [self.cell_alignment(cell) for cell in header]
412
+ if any(
413
+ self.cell_alignment(cell) != alignments[i]
414
+ for row in body
415
+ for i, cell in enumerate(row)
416
+ ):
417
+ raise Unconvertible("mixed column alignment")
418
+ delimiter = {"": "---", "left": ":---", "center": ":---:", "right": "---:"}
419
+ lines = [
420
+ self.table_row(header),
421
+ "| " + " | ".join(delimiter[a] for a in alignments) + " |",
422
+ ]
423
+ lines.extend(self.table_row(row) for row in body)
424
+ return "\n".join(lines)
425
+
426
+ def cell_alignment(self, cell: Element) -> str:
427
+ attrs = self.attrs(cell)
428
+ style = attrs.pop("style", "")
429
+ if attrs:
430
+ raise Unconvertible("table cell attributes")
431
+ if not style:
432
+ return ""
433
+ match = re.fullmatch(r"text-align:\s*(left|center|right)", style)
434
+ if not match:
435
+ raise Unconvertible("table cell style")
436
+ return match[1]
437
+
438
+ def table_row(self, cells: list[Element]) -> str:
439
+ texts = []
440
+ for cell in cells:
441
+ if any(
442
+ isinstance(c, Element) and c.tag in BLOCK_TAGS for c in cell.children
443
+ ):
444
+ raise Unconvertible("block inside a table cell")
445
+ text = self.inline(cell.children).strip(" ")
446
+ if "\n" in text:
447
+ raise Unconvertible("line break in a table cell")
448
+ texts.append(text.replace("|", "\\|"))
449
+ return "| " + " | ".join(texts) + " |"
450
+
451
+
452
+ def join_blocks(blocks: list[str]) -> str:
453
+ """Join Markdown blocks so adjacent lists stay separate lists.
454
+
455
+ Markdown merges consecutive lists unless their markers differ, so a list
456
+ that follows another list switches marker style.
457
+ """
458
+ blocks = list(blocks)
459
+ for index in range(1, len(blocks)):
460
+ previous, current = blocks[index - 1], blocks[index]
461
+ if previous.startswith("- ") and current.startswith("- "):
462
+ blocks[index] = re.sub(r"^- ", "* ", current, flags=re.M)
463
+ elif re.match(r"\d+\. ", previous) and re.match(r"\d+\. ", current):
464
+ blocks[index] = re.sub(r"^(\d+)\. ", r"\1) ", current, flags=re.M)
465
+ return "\n\n".join(blocks)
466
+
467
+
468
+ def raw_block(node: Node) -> str:
469
+ """Markdown that carries a nested node as an HTML block.
470
+
471
+ Bare text cannot start an HTML block, so it is prefixed with an empty
472
+ comment, which starts a block that ends on that line. Content with a blank
473
+ line would end the block early, so it is unconvertible.
474
+ """
475
+ if isinstance(node, Comment):
476
+ html = f"<!--{node.text}-->"
477
+ else:
478
+ html = serialize([node])
479
+ if isinstance(node, str):
480
+ html = f"<!---->{html}"
481
+ elif node.tag not in TYPE_ONE_TAGS | TYPE_SIX_TAGS | VOID_TAGS:
482
+ # A line holding only an opening tag starts an HTML block that runs
483
+ # to the next blank line.
484
+ opening = start_tag(node)
485
+ html = f"{opening}\n{html[len(opening) :]}"
486
+ ends_at_close = isinstance(node, Element) and node.tag in TYPE_ONE_TAGS
487
+ if not ends_at_close and re.search(r"\n[ \t]*\n", html):
488
+ raise Unconvertible("blank line in nested HTML")
489
+ return html
490
+
491
+
492
+ def _with_block_attrs(attrs: dict[str, str], body: str) -> str:
493
+ return f"{_attribute_list(attrs)}\n{body}" if attrs else body
494
+
495
+
496
+ def _div_depth(nodes: Sequence[Node]) -> int:
497
+ depths = [
498
+ 1 + _div_depth(node.children)
499
+ for node in nodes
500
+ if isinstance(node, Element) and node.tag == "div"
501
+ ]
502
+ nested = [
503
+ _div_depth(node.children)
504
+ for node in nodes
505
+ if isinstance(node, Element) and node.tag != "div"
506
+ ]
507
+ return max(depths + nested + [0])
508
+
509
+
510
+ def _code_span(text: str) -> str:
511
+ if "\n" in text:
512
+ raise Unconvertible("line break in inline code")
513
+ longest = max((len(run) for run in re.findall(r"`+", text)), default=0)
514
+ fence = "`" * (longest + 1)
515
+ if text.startswith(("`", " ")) or text.endswith(("`", " ")):
516
+ text = f" {text} "
517
+ return f"{fence}{text}{fence}"
518
+
519
+
520
+ def _destination(url: str, title: str | None) -> str:
521
+ if re.search(r"[\s()<>\\]", url) or not url:
522
+ url = "<" + re.sub(r"([<>\\])", r"\\\1", url) + ">"
523
+ if title is None:
524
+ return url
525
+ escaped = title.replace("\\", "\\\\").replace('"', '\\"')
526
+ return f'{url} "{escaped}"'
wpsync/media.py ADDED
@@ -0,0 +1,161 @@
1
+ """The media table: local image files and the library images they stand for."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import hashlib
6
+ import posixpath
7
+ from dataclasses import dataclass
8
+ from pathlib import Path, PurePosixPath
9
+ from typing import Protocol
10
+ from urllib.parse import unquote, urlsplit
11
+
12
+ from wpsync.documents import CONTENT_DIR
13
+ from wpsync.markup.markdown import image_sources
14
+ from wpsync.state import MediaRecord
15
+
16
+ IMAGES_DIR = f"{CONTENT_DIR}/images"
17
+
18
+
19
+ class MissingImage(Exception):
20
+ """The platform lists an image, but its file is gone."""
21
+
22
+
23
+ @dataclass(frozen=True)
24
+ class MediaImage:
25
+ id: str
26
+ url: str
27
+ """The copy of the image a post displays."""
28
+ size: str
29
+ """The platform's name for that copy, such as WordPress's `large`."""
30
+
31
+
32
+ class Media(Protocol):
33
+ def remember(self, url: str, media_id: str, size: str) -> str:
34
+ """Record a library image found on pull; return its Markdown source."""
35
+ ...
36
+
37
+ def lookup(self, src: str) -> MediaImage | None:
38
+ """The library image a Markdown source refers to, if any."""
39
+ ...
40
+
41
+
42
+ @dataclass(frozen=True)
43
+ class Download:
44
+ path: PurePosixPath
45
+ url: str
46
+ media_id: str
47
+ size: str
48
+
49
+
50
+ class MediaLibrary:
51
+ """The media table during a pull: known images and images to download."""
52
+
53
+ def __init__(self, root: Path, records: list[MediaRecord]) -> None:
54
+ self.root = root
55
+ self.by_path = {record.path: record for record in records}
56
+ self.by_url = {record.url: record.path for record in records}
57
+ self.pending: dict[PurePosixPath, Download] = {}
58
+
59
+ def remember(self, url: str, media_id: str, size: str) -> PurePosixPath:
60
+ path = self.by_url.get(url)
61
+ if path is None:
62
+ path = self._local_path(url, media_id)
63
+ self.by_url[url] = path
64
+ self.pending[path] = Download(path, url, media_id, size)
65
+ return path
66
+
67
+ def lookup(self, path: PurePosixPath) -> MediaImage | None:
68
+ if path in self.by_path:
69
+ record = self.by_path[path]
70
+ return MediaImage(record.media_id, record.url, record.size)
71
+ if path in self.pending:
72
+ download = self.pending[path]
73
+ return MediaImage(download.media_id, download.url, download.size)
74
+ return None
75
+
76
+ def take_pending(self) -> list[Download]:
77
+ downloads = list(self.pending.values())
78
+ self.pending.clear()
79
+ return downloads
80
+
81
+ def release(self, download: Download) -> None:
82
+ """Forget a planned download that the converted post does not use."""
83
+ self.by_url.pop(download.url, None)
84
+
85
+ def add(self, record: MediaRecord) -> None:
86
+ self.by_path[record.path] = record
87
+ self.by_url[record.url] = record.path
88
+
89
+ def at_url(self, url: str) -> MediaRecord:
90
+ return self.by_path[self.by_url[url]]
91
+
92
+ def _local_path(self, url: str, media_id: str) -> PurePosixPath:
93
+ """Where a library image is saved: its upload path, mirrored.
94
+
95
+ WordPress keeps file names unique within each upload folder, so the
96
+ path after uploads/ belongs to this image alone and is the same on
97
+ every pull. An image from elsewhere gets a free name instead.
98
+ """
99
+ address = unquote(urlsplit(url).path)
100
+ if "/uploads/" in address:
101
+ parts = [part for part in address.split("/uploads/", 1)[1].split("/")]
102
+ if all(part not in ("", ".", "..") for part in parts):
103
+ return PurePosixPath(IMAGES_DIR, *parts)
104
+ return self._free_path(url, media_id)
105
+
106
+ def _free_path(self, url: str, media_id: str) -> PurePosixPath:
107
+ name = unquote(PurePosixPath(urlsplit(url).path).name) or f"image-{media_id}"
108
+ name = name.replace("/", "-")
109
+ stem, suffix = PurePosixPath(name).stem, PurePosixPath(name).suffix
110
+ candidates = [name, f"{stem}-{media_id}{suffix}"]
111
+ candidates += [f"{stem}-{media_id}-{n}{suffix}" for n in range(2, 1000)]
112
+ for candidate in candidates:
113
+ path = PurePosixPath(IMAGES_DIR) / candidate
114
+ taken = path in self.by_path or path in self.pending
115
+ if not taken and not (self.root / path).exists():
116
+ return path
117
+ raise ValueError(f"no free file name for {url}")
118
+
119
+
120
+ class PostMedia:
121
+ """The media table as one post sees it, with sources relative to its file."""
122
+
123
+ def __init__(self, library: MediaLibrary, post: PurePosixPath) -> None:
124
+ self.library = library
125
+ self.post = post
126
+
127
+ def remember(self, url: str, media_id: str, size: str) -> str:
128
+ path = self.library.remember(url, media_id, size)
129
+ return posixpath.relpath(path, self.post.parent)
130
+
131
+ def lookup(self, src: str) -> MediaImage | None:
132
+ path = image_path(self.post, src)
133
+ return None if path is None else self.library.lookup(path)
134
+
135
+
136
+ def image_path(post: PurePosixPath, source: str) -> PurePosixPath | None:
137
+ """The file a post's image source names, relative to the profile folder.
138
+
139
+ Sources are relative to the post's file, as Markdown editors read them. A
140
+ source that is a URL names no local file.
141
+ """
142
+ if urlsplit(source).scheme or source.startswith("//"):
143
+ return None
144
+ joined = posixpath.join(post.parent.as_posix(), unquote(source))
145
+ return PurePosixPath(posixpath.normpath(joined))
146
+
147
+
148
+ def file_checksum(path: Path) -> str:
149
+ """The checksum the media table keeps for an image file."""
150
+ return hashlib.sha256(path.read_bytes()).hexdigest()
151
+
152
+
153
+ def post_images(path: PurePosixPath, body: str) -> set[PurePosixPath]:
154
+ """The images in the profile folder that a post file shows."""
155
+ return {
156
+ image
157
+ for source in image_sources(body)
158
+ if (image := image_path(path, source)) is not None
159
+ and not image.is_absolute()
160
+ and ".." not in image.parts
161
+ }