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.
wpsync/sync.py ADDED
@@ -0,0 +1,501 @@
1
+ """Comparing local post files with their last synchronized state."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import difflib
6
+ from collections.abc import Sequence
7
+ from dataclasses import dataclass, replace
8
+ from enum import StrEnum
9
+ from pathlib import Path, PurePosixPath
10
+ from typing import Generic, Protocol, TypeVar
11
+
12
+ from wpsync.documents import (
13
+ CONTENT_DIR,
14
+ FIELDS,
15
+ LocalDocument,
16
+ body_checksum,
17
+ fields_checksum,
18
+ )
19
+ from wpsync.markup.markdown import image_sources
20
+ from wpsync.media import file_checksum, image_path, post_images
21
+ from wpsync.posts import Post, PostStatus, PostSummary, RemoteState
22
+ from wpsync.state import MediaRecord, PostRecord
23
+
24
+ C = TypeVar("C", bound="Candidate")
25
+
26
+
27
+ class SelectionError(ValueError):
28
+ """Raised when a post selector matches no post or several."""
29
+
30
+
31
+ class Remote(Protocol):
32
+ def post_states(self, ids: list[str]) -> dict[str, RemoteState]: ...
33
+
34
+ def post_summaries(self) -> list[PostSummary]: ...
35
+
36
+
37
+ @dataclass(frozen=True)
38
+ class Selection:
39
+ documents: list[LocalDocument]
40
+ records: dict[str, PostRecord]
41
+
42
+
43
+ def select(
44
+ selector: str | None,
45
+ documents: list[LocalDocument],
46
+ records: dict[str, PostRecord],
47
+ *,
48
+ root: Path,
49
+ base: Path,
50
+ ) -> Selection:
51
+ """Narrow to one post chosen by post ID, file, slug, or title.
52
+
53
+ A file name without a folder is looked for under the current directory
54
+ first, then in every folder under content/.
55
+ """
56
+ if selector is None:
57
+ return Selection(documents, records)
58
+ if selector.isdigit():
59
+ chosen = [item for item in documents if item.document.post_id == selector]
60
+ if chosen or selector in records:
61
+ record = {selector: records[selector]} if selector in records else {}
62
+ return Selection(chosen, record)
63
+ raise SelectionError(f"no local post has id {selector}")
64
+ if "/" in selector:
65
+ chosen = _at_path(selector, documents, root, base)
66
+ if not chosen:
67
+ raise SelectionError(f"{selector} is not a post file under {CONTENT_DIR}/")
68
+ elif selector.endswith(".md"):
69
+ chosen = _at_path(selector, documents, root, base) or [
70
+ item for item in documents if PurePosixPath(item.path).name == selector
71
+ ]
72
+ if not chosen:
73
+ raise SelectionError(f"no post file is named {selector}")
74
+ else:
75
+ title = selector.casefold()
76
+ chosen = (
77
+ [item for item in documents if item.document.post.slug == selector]
78
+ or [item for item in documents if PurePosixPath(item.path).stem == selector]
79
+ or [
80
+ item
81
+ for item in documents
82
+ if item.document.post.title.casefold() == title
83
+ ]
84
+ )
85
+ if not chosen:
86
+ raise SelectionError(
87
+ f"no local post has slug, file name, or title '{selector}'"
88
+ )
89
+ if len(chosen) > 1:
90
+ paths = ", ".join(str(item.path) for item in chosen)
91
+ raise SelectionError(f"'{selector}' matches {paths}")
92
+ post_id = chosen[0].document.post_id
93
+ record = {post_id: records[post_id]} if post_id in records else {}
94
+ return Selection(chosen, record)
95
+
96
+
97
+ def _at_path(
98
+ selector: str, documents: list[LocalDocument], root: Path, base: Path
99
+ ) -> list[LocalDocument]:
100
+ path = (base / selector).resolve()
101
+ try:
102
+ relative = PurePosixPath(path.relative_to(root).as_posix())
103
+ except ValueError as error:
104
+ raise SelectionError(f"{selector} is outside the profile folder") from error
105
+ return [item for item in documents if PurePosixPath(item.path) == relative]
106
+
107
+
108
+ class Candidate(Protocol):
109
+ @property
110
+ def id(self) -> str: ...
111
+
112
+ @property
113
+ def title(self) -> str: ...
114
+
115
+ @property
116
+ def slug(self) -> str: ...
117
+
118
+
119
+ @dataclass(frozen=True)
120
+ class Match(Generic[C]):
121
+ """How a post relates to the posts on the other side.
122
+
123
+ Only a shared slug identifies the same post. A shared title is reported so
124
+ the user can avoid a duplicate, but titles need not be unique.
125
+ """
126
+
127
+ post: C | None
128
+ """The one post with the same slug."""
129
+ candidates: tuple[C, ...] = ()
130
+ """Several posts with the same slug; none is chosen."""
131
+ same_title: tuple[C, ...] = ()
132
+ """Other posts with the same title."""
133
+
134
+
135
+ def match_post(post: Post, candidates: Sequence[C]) -> Match[C]:
136
+ by_slug = tuple(c for c in candidates if post.slug and c.slug == post.slug)
137
+ title = post.title.strip()
138
+ same_title = tuple(
139
+ c for c in candidates if title and c.title.strip() == title and c not in by_slug
140
+ )
141
+ if len(by_slug) > 1:
142
+ return Match(None, by_slug, same_title)
143
+ return Match(by_slug[0] if by_slug else None, (), same_title)
144
+
145
+
146
+ class Action(StrEnum):
147
+ NEW = "+"
148
+ CHANGED = "~"
149
+ DELETED = "-"
150
+ CONFLICT = "?"
151
+ UNCHANGED = "="
152
+ PRIVATE = "x"
153
+ """Excluded: push skips a private post."""
154
+ KEPT = " "
155
+ """Deleted locally, but push keeps the post without -p."""
156
+
157
+
158
+ @dataclass(frozen=True)
159
+ class PushStep:
160
+ """What a push does for one post."""
161
+
162
+ document: LocalDocument
163
+ target: str | None = None
164
+ """The post to update; a new post is created when None."""
165
+ content: bool = True
166
+ fields: bool = True
167
+ unpublish: bool = False
168
+ question: str | None = None
169
+ """What to ask first, for anything that could overwrite or duplicate a post."""
170
+
171
+
172
+ @dataclass(frozen=True)
173
+ class DeleteStep:
174
+ """What a pruning push does for a post whose file was deleted."""
175
+
176
+ target: str
177
+ gone: bool = False
178
+ """The post is already off WordPress, so only its record is dropped."""
179
+ question: str | None = None
180
+
181
+
182
+ @dataclass(frozen=True)
183
+ class ImageUpload:
184
+ """An image a post shows that push uploads: new, or replaced since upload."""
185
+
186
+ action: Action
187
+ path: PurePosixPath
188
+ """Relative to the profile folder."""
189
+
190
+
191
+ @dataclass(frozen=True)
192
+ class DiffEntry:
193
+ action: Action
194
+ presence: str
195
+ """'l' when only the file exists, 'r' when only the post, blank for both."""
196
+ post_id: str | None
197
+ path: PurePosixPath
198
+ step: PushStep | DeleteStep | None = None
199
+ """None when a push leaves the post alone."""
200
+ reason: str = ""
201
+ """Why push cannot send a conflicting post it has no question for."""
202
+ images: tuple[ImageUpload, ...] = ()
203
+ """The images the post shows that push uploads with it."""
204
+
205
+
206
+ @dataclass(frozen=True)
207
+ class Outcome:
208
+ """One file push or pull wrote or deleted, or a post it skipped."""
209
+
210
+ action: Action
211
+ path: str
212
+ failure: str = ""
213
+ """Why the post could not be sent or written; empty for a declined one."""
214
+
215
+
216
+ @dataclass(frozen=True)
217
+ class Diff:
218
+ entries: list[DiffEntry]
219
+ notes: list[str]
220
+
221
+
222
+ def _local_changes(document: LocalDocument, record: PostRecord) -> list[str]:
223
+ post = document.document.post
224
+ changes = []
225
+ if body_checksum(post) != record.body_checksum:
226
+ changes.append("content")
227
+ if fields_checksum(post) != record.fields_checksum:
228
+ changes.append("details")
229
+ return changes
230
+
231
+
232
+ def _typo_notes(document: LocalDocument) -> list[str]:
233
+ notes = []
234
+ for key in document.document.extra_keys:
235
+ close = difflib.get_close_matches(key, FIELDS, n=1, cutoff=0.75)
236
+ if close:
237
+ notes.append(
238
+ f"{document.path}: '{key}' is not synced; did you mean '{close[0]}'?"
239
+ )
240
+ return notes
241
+
242
+
243
+ def compare(
244
+ selection: Selection,
245
+ remote: Remote,
246
+ *,
247
+ root: Path,
248
+ media: list[MediaRecord],
249
+ prune: bool = False,
250
+ ) -> Diff:
251
+ """Classify the selected posts, contacting the remote only when needed.
252
+
253
+ The images the sent posts show are listed too: a new or replaced image is
254
+ uploaded, so a post that shows one changes even if its file did not. With
255
+ prune, a post whose file was deleted is deleted from the blog.
256
+ """
257
+ entries: list[DiffEntry] = []
258
+ changed: dict[str, tuple[LocalDocument, list[str]]] = {}
259
+ unlinked: list[LocalDocument] = []
260
+ new: list[LocalDocument] = []
261
+ notes: list[str] = []
262
+ present = set()
263
+ for document in selection.documents:
264
+ notes.extend(_typo_notes(document))
265
+ post_id = document.document.post_id
266
+ path = PurePosixPath(document.path)
267
+ private = document.document.post.status is PostStatus.PRIVATE
268
+ if post_id is not None:
269
+ present.add(post_id)
270
+ record = selection.records.get(post_id) if post_id else None
271
+ if private and record is None:
272
+ entries.append(DiffEntry(Action.PRIVATE, "l", post_id, path))
273
+ continue
274
+ if post_id is None:
275
+ new.append(document)
276
+ continue
277
+ if record is None:
278
+ unlinked.append(document)
279
+ continue
280
+ changes = _local_changes(document, record)
281
+ if changes:
282
+ changed[post_id] = (document, changes)
283
+ else:
284
+ entries.append(DiffEntry(Action.UNCHANGED, "", post_id, path))
285
+ deleted = [
286
+ record
287
+ for post_id, record in selection.records.items()
288
+ if post_id not in present
289
+ ]
290
+ if not prune:
291
+ entries.extend(
292
+ DiffEntry(Action.KEPT, "r", record.post_id, record.path)
293
+ for record in deleted
294
+ )
295
+ deleted = []
296
+
297
+ ids = sorted(
298
+ {
299
+ *changed,
300
+ *(d.document.post_id for d in unlinked),
301
+ *(record.post_id for record in deleted),
302
+ },
303
+ key=int,
304
+ )
305
+ states = remote.post_states(ids) if ids else {} # type: ignore[arg-type]
306
+ entries.extend(
307
+ _trash_entry(record, states.get(record.post_id)) for record in deleted
308
+ )
309
+ for post_id, (document, changes) in changed.items():
310
+ record = selection.records[post_id]
311
+ state = states.get(post_id)
312
+ path = PurePosixPath(document.path)
313
+ unpublish = document.document.post.status is PostStatus.PRIVATE
314
+ if unpublish and (state is None or not state.published):
315
+ # Push sends nothing for a private post except unpublishing it.
316
+ presence = "" if state is not None else "l"
317
+ entries.append(DiffEntry(Action.PRIVATE, presence, post_id, path))
318
+ continue
319
+ if state is None:
320
+ entries.append(
321
+ DiffEntry(
322
+ Action.CONFLICT,
323
+ "l",
324
+ post_id,
325
+ path,
326
+ reason="deleted on WordPress",
327
+ )
328
+ )
329
+ elif state.fingerprint != record.remote_fingerprint:
330
+ step = _update_step(document, post_id, changes, unpublish)
331
+ question = (
332
+ f"#{post_id} {path} changed locally and on WordPress. "
333
+ "Replace WordPress's version with your file?"
334
+ )
335
+ entries.append(
336
+ DiffEntry(
337
+ Action.CONFLICT, "", post_id, path, replace(step, question=question)
338
+ )
339
+ )
340
+ else:
341
+ step = _update_step(document, post_id, changes, unpublish)
342
+ entries.append(DiffEntry(Action.CHANGED, "", post_id, path, step))
343
+ for document in unlinked:
344
+ post_id = document.document.post_id
345
+ path = PurePosixPath(document.path)
346
+ if post_id in states:
347
+ question = (
348
+ f"{path} has id {post_id} but was never synced here. "
349
+ "Replace that post with your file?"
350
+ )
351
+ step = PushStep(document, target=post_id, question=question)
352
+ entries.append(DiffEntry(Action.CONFLICT, "", post_id, path, step))
353
+ else:
354
+ entries.append(
355
+ DiffEntry(
356
+ Action.CONFLICT,
357
+ "l",
358
+ post_id,
359
+ path,
360
+ reason=f"id {post_id} is not a post on WordPress",
361
+ )
362
+ )
363
+ if new:
364
+ summaries = remote.post_summaries()
365
+ for document in new:
366
+ entries.append(_new_entry(document, summaries))
367
+ entries = _with_images(entries, selection.documents, root, media)
368
+ entries.sort(key=lambda entry: str(entry.path))
369
+ return Diff(entries, notes)
370
+
371
+
372
+ def _with_images(
373
+ entries: list[DiffEntry],
374
+ documents: list[LocalDocument],
375
+ root: Path,
376
+ media: list[MediaRecord],
377
+ ) -> list[DiffEntry]:
378
+ """Attach the images push would upload to the posts that show them."""
379
+ library = {record.path: record for record in media}
380
+ by_path = {PurePosixPath(item.path): item for item in documents}
381
+ result = []
382
+ for entry in entries:
383
+ document = by_path.get(entry.path)
384
+ sent = entry.action is Action.UNCHANGED or (
385
+ isinstance(entry.step, PushStep) and not entry.step.unpublish
386
+ )
387
+ if document is None or not sent:
388
+ result.append(entry)
389
+ continue
390
+ body = document.document.post.body
391
+ problems = (
392
+ []
393
+ if entry.action is Action.UNCHANGED
394
+ else _image_problems(entry.path, body, root, library)
395
+ )
396
+ images = tuple(
397
+ ImageUpload(action, image)
398
+ for image in sorted(
399
+ post_images(entry.path, body) | {image for image, _ in problems}
400
+ )
401
+ if (action := _image_upload(root / image, library.get(image)))
402
+ )
403
+ if problems:
404
+ # Push cannot send a post whose image it cannot upload.
405
+ entry = DiffEntry(
406
+ Action.CONFLICT,
407
+ entry.presence,
408
+ entry.post_id,
409
+ entry.path,
410
+ reason=problems[0][1],
411
+ )
412
+ elif images and entry.action is Action.UNCHANGED:
413
+ step = PushStep(document, target=entry.post_id, fields=False)
414
+ entry = DiffEntry(Action.CHANGED, "", entry.post_id, entry.path, step)
415
+ elif images and isinstance(entry.step, PushStep):
416
+ entry = replace(entry, step=replace(entry.step, content=True))
417
+ result.append(replace(entry, images=images))
418
+ return result
419
+
420
+
421
+ def _image_problems(
422
+ post: PurePosixPath,
423
+ body: str,
424
+ root: Path,
425
+ library: dict[PurePosixPath, MediaRecord],
426
+ ) -> list[tuple[PurePosixPath, str]]:
427
+ """The images push cannot upload, as push would report them."""
428
+ problems = []
429
+ for source in sorted(image_sources(body)):
430
+ image = image_path(post, source)
431
+ if image is None or image in library:
432
+ continue
433
+ if image.is_absolute() or ".." in image.parts:
434
+ problems.append((image, f"image {source} is outside the profile folder"))
435
+ elif not (root / image).is_file():
436
+ problems.append((image, f"image not found: {source}"))
437
+ return problems
438
+
439
+
440
+ def _image_upload(file: Path, record: MediaRecord | None) -> Action | None:
441
+ """Whether push uploads an image file: new, replaced, missing, or not at all."""
442
+ if not file.is_file():
443
+ return None if record is not None else Action.CONFLICT
444
+ if record is None:
445
+ return Action.NEW
446
+ if record.checksum and file_checksum(file) != record.checksum:
447
+ return Action.CHANGED
448
+ return None
449
+
450
+
451
+ def _trash_entry(record: PostRecord, state: RemoteState | None) -> DiffEntry:
452
+ post_id, path = record.post_id, record.path
453
+ if state is None:
454
+ return DiffEntry(
455
+ Action.DELETED, "", post_id, path, DeleteStep(post_id, gone=True)
456
+ )
457
+ if state.fingerprint != record.remote_fingerprint:
458
+ question = (
459
+ f"#{post_id} {path} was deleted locally but changed on WordPress. "
460
+ "Delete it from WordPress anyway?"
461
+ )
462
+ return DiffEntry(
463
+ Action.CONFLICT, "r", post_id, path, DeleteStep(post_id, question=question)
464
+ )
465
+ return DiffEntry(Action.DELETED, "r", post_id, path, DeleteStep(post_id))
466
+
467
+
468
+ def _update_step(
469
+ document: LocalDocument, post_id: str, changes: list[str], unpublish: bool
470
+ ) -> PushStep:
471
+ if unpublish:
472
+ return PushStep(
473
+ document, target=post_id, content=False, fields=False, unpublish=True
474
+ )
475
+ return PushStep(
476
+ document,
477
+ target=post_id,
478
+ content="content" in changes,
479
+ fields="details" in changes,
480
+ )
481
+
482
+
483
+ def _new_entry(document: LocalDocument, summaries: Sequence[PostSummary]) -> DiffEntry:
484
+ path = PurePosixPath(document.path)
485
+ match = match_post(document.document.post, summaries)
486
+ owners = match.candidates or ((match.post,) if match.post else ())
487
+ if owners:
488
+ # A new post never takes over another post's slug; the file is wrong.
489
+ listed = ", ".join(f"#{post.id} {post.title!r}" for post in owners)
490
+ return DiffEntry(
491
+ Action.CONFLICT,
492
+ "l",
493
+ None,
494
+ path,
495
+ reason=f"slug '{document.document.post.slug}' belongs to {listed}",
496
+ )
497
+ question = None
498
+ if match.same_title:
499
+ listed = ", ".join(f"#{p.id}" for p in match.same_title)
500
+ question = f"{path} has the same title as {listed}. Create another post?"
501
+ return DiffEntry(Action.NEW, "l", None, path, PushStep(document, question=question))
wpsync/trash.py ADDED
@@ -0,0 +1,132 @@
1
+ """WPSync's trash: deleted posts and their images, kept in the profile folder.
2
+
3
+ Deleting a post on the blog is permanent, since not every platform has a trash
4
+ of its own. The copy in `.trash/` keeps its path, so it still shows its images,
5
+ and restoring it brings it back as a new post that the next push creates.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ from dataclasses import dataclass
11
+ from pathlib import Path, PurePosixPath
12
+ from typing import Protocol
13
+
14
+ from wpsync.documents import (
15
+ TRASH_DIR,
16
+ Document,
17
+ LocalDocument,
18
+ scan_documents,
19
+ write_document,
20
+ )
21
+ from wpsync.media import post_images
22
+ from wpsync.state import MediaRecord, read_media, write_state
23
+
24
+
25
+ class TrashError(Exception):
26
+ """A post cannot be moved into or out of the trash."""
27
+
28
+
29
+ class DeleteRemote(Protocol):
30
+ def delete_post(self, post_id: str) -> None:
31
+ """Delete a post for good."""
32
+ ...
33
+
34
+ def delete_media(self, media_id: str) -> None:
35
+ """Delete a library image for good."""
36
+ ...
37
+
38
+ def media_in_use(self, media: MediaRecord, post_id: str) -> bool:
39
+ """Whether a post or page other than post_id shows the library image."""
40
+ ...
41
+
42
+
43
+ @dataclass(frozen=True)
44
+ class Deleted:
45
+ trashed: PurePosixPath
46
+ """Where the post's file is now."""
47
+ media: list[PurePosixPath]
48
+ """Library images deleted from the blog."""
49
+
50
+
51
+ def delete_post(
52
+ root: Path,
53
+ api_root: str,
54
+ remote: DeleteRemote | None,
55
+ post_id: str | None,
56
+ path: PurePosixPath,
57
+ document: Document,
58
+ on_disk: bool,
59
+ ) -> Deleted:
60
+ """Delete a post and the images only it shows, keeping both in the trash.
61
+
62
+ The post and its library images are deleted from the blog when a remote is
63
+ given; an image another post or page uses stays. A file already deleted
64
+ locally is written to the trash from the document first.
65
+ """
66
+ shown_elsewhere = {
67
+ image
68
+ for item in scan_documents(root)
69
+ if PurePosixPath(item.path) != path
70
+ for image in post_images(PurePosixPath(item.path), item.document.post.body)
71
+ }
72
+ own = sorted(post_images(path, document.post.body) - shown_elsewhere)
73
+ trashed = _free_path(root, PurePosixPath(TRASH_DIR) / path)
74
+ if not on_disk:
75
+ # Written before the blog loses the post, so a failure keeps a copy.
76
+ (root / trashed).parent.mkdir(parents=True, exist_ok=True)
77
+ write_document(root / trashed, document)
78
+ deleted: list[MediaRecord] = []
79
+ if remote is not None and post_id is not None:
80
+ remote.delete_post(post_id)
81
+ library = {record.path: record for record in read_media(root, api_root)}
82
+ for image in own:
83
+ record = library.get(image)
84
+ if record is not None and not remote.media_in_use(record, post_id):
85
+ remote.delete_media(record.media_id)
86
+ deleted.append(record)
87
+ if on_disk:
88
+ _move(root, path, trashed)
89
+ for image in own:
90
+ target = PurePosixPath(TRASH_DIR) / image
91
+ if (root / image).is_file() and not (root / target).exists():
92
+ _move(root, image, target)
93
+ if post_id is not None:
94
+ with write_state(root, api_root) as state:
95
+ state.forget(post_id)
96
+ for record in deleted:
97
+ state.forget_media(record.path)
98
+ return Deleted(trashed, [record.path for record in deleted])
99
+
100
+
101
+ def restore_post(root: Path, item: LocalDocument) -> PurePosixPath:
102
+ """Move a trashed post and its images back, as a post not on the blog yet."""
103
+ trashed = PurePosixPath(item.path)
104
+ original = trashed.relative_to(TRASH_DIR)
105
+ if (root / original).exists():
106
+ raise TrashError(f"{original} already exists; move it before restoring")
107
+ document = item.document
108
+ for image in post_images(trashed, document.post.body):
109
+ if image.parts[0] != TRASH_DIR:
110
+ continue
111
+ target = image.relative_to(TRASH_DIR)
112
+ if (root / image).is_file() and not (root / target).exists():
113
+ _move(root, image, target)
114
+ # The deleted post is gone for good, so push creates it again.
115
+ (root / original).parent.mkdir(parents=True, exist_ok=True)
116
+ write_document(root / original, Document(None, document.post, document.extra))
117
+ (root / trashed).unlink()
118
+ return original
119
+
120
+
121
+ def _free_path(root: Path, path: PurePosixPath) -> PurePosixPath:
122
+ candidate = path
123
+ number = 2
124
+ while (root / candidate).exists():
125
+ candidate = path.with_name(f"{path.stem}-{number}{path.suffix}")
126
+ number += 1
127
+ return candidate
128
+
129
+
130
+ def _move(root: Path, source: PurePosixPath, target: PurePosixPath) -> None:
131
+ (root / target).parent.mkdir(parents=True, exist_ok=True)
132
+ (root / source).rename(root / target)
File without changes