wpsync 1.2.1__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.

Potentially problematic release.


This version of wpsync might be problematic. Click here for more details.

wpsync/config.py ADDED
@@ -0,0 +1,173 @@
1
+ from __future__ import annotations
2
+
3
+ import json
4
+ import os
5
+ import re
6
+ from dataclasses import dataclass, field, replace
7
+ from pathlib import Path
8
+ from typing import Any
9
+
10
+ from wpsync.storage import write_text_atomic
11
+
12
+ CONFIG_VERSION = 1
13
+ PROFILE_NAME_PATTERN = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]*$")
14
+ ENVIRONMENT_NAME_PATTERN = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
15
+
16
+
17
+ class ConfigurationError(ValueError):
18
+ """Raised when configuration is invalid or cannot be decoded."""
19
+
20
+
21
+ def validate_profile_name(name: str) -> str:
22
+ if not PROFILE_NAME_PATTERN.fullmatch(name):
23
+ raise ConfigurationError(
24
+ "profile name must start with a letter or digit and contain "
25
+ "only letters, digits, '.', '_', or '-'"
26
+ )
27
+ return name
28
+
29
+
30
+ def validate_environment_name(name: str) -> str:
31
+ if not ENVIRONMENT_NAME_PATTERN.fullmatch(name):
32
+ raise ConfigurationError(f"'{name}' is not a valid environment-variable name")
33
+ return name
34
+
35
+
36
+ def default_password_env(profile_name: str) -> str:
37
+ stem = re.sub(r"[^A-Za-z0-9]", "_", profile_name).upper()
38
+ name = f"{stem}_WP_PASSWORD"
39
+ if not ENVIRONMENT_NAME_PATTERN.fullmatch(name):
40
+ raise ConfigurationError(
41
+ f"profile '{profile_name}' has no valid default password variable; "
42
+ "choose one with --password-env"
43
+ )
44
+ return name
45
+
46
+
47
+ def canonical_local_root(directory: str | Path) -> Path:
48
+ candidate = Path(directory).expanduser()
49
+ try:
50
+ resolved = candidate.resolve(strict=True)
51
+ except OSError as error:
52
+ raise ConfigurationError(f"local root does not exist: {candidate}") from error
53
+ if not resolved.is_dir():
54
+ raise ConfigurationError(f"local root is not a directory: {candidate}")
55
+ if resolved.parent == resolved:
56
+ raise ConfigurationError("local root cannot be the filesystem root")
57
+ return resolved
58
+
59
+
60
+ def _paths_overlap(first: Path, second: Path) -> bool:
61
+ return first == second or first in second.parents or second in first.parents
62
+
63
+
64
+ def _required_string(document: dict[str, Any], key: str, profile: str) -> str:
65
+ value = document.get(key)
66
+ if not isinstance(value, str) or not value.strip():
67
+ raise ConfigurationError(
68
+ f"profile '{profile}' {key} must be a non-empty string"
69
+ )
70
+ return value
71
+
72
+
73
+ @dataclass(frozen=True)
74
+ class Profile:
75
+ site: str
76
+ api_root: str
77
+ username: str
78
+ password_env: str
79
+ local_root: Path
80
+
81
+ def to_document(self) -> dict[str, str]:
82
+ return {
83
+ "site": self.site,
84
+ "api_root": self.api_root,
85
+ "username": self.username,
86
+ "password_env": self.password_env,
87
+ "local_root": os.fspath(self.local_root),
88
+ }
89
+
90
+ @classmethod
91
+ def from_document(cls, name: str, document: Any) -> Profile:
92
+ if not isinstance(document, dict):
93
+ raise ConfigurationError(f"profile '{name}' must be an object")
94
+ local_root = Path(_required_string(document, "local_root", name))
95
+ if not local_root.is_absolute():
96
+ raise ConfigurationError(f"profile '{name}' local_root must be absolute")
97
+ return cls(
98
+ site=_required_string(document, "site", name),
99
+ api_root=_required_string(document, "api_root", name),
100
+ username=_required_string(document, "username", name),
101
+ password_env=validate_environment_name(
102
+ _required_string(document, "password_env", name)
103
+ ),
104
+ local_root=local_root,
105
+ )
106
+
107
+
108
+ @dataclass
109
+ class Configuration:
110
+ profiles: dict[str, Profile] = field(default_factory=dict)
111
+
112
+ def add(self, name: str, profile: Profile) -> None:
113
+ if name in self.profiles:
114
+ raise ConfigurationError(f"profile '{name}' already exists")
115
+ self.check_root(name, profile.local_root)
116
+ self.profiles[name] = profile
117
+
118
+ def remap(self, name: str, local_root: Path) -> Profile:
119
+ self.check_root(name, local_root)
120
+ self.profiles[name] = replace(self.profiles[name], local_root=local_root)
121
+ return self.profiles[name]
122
+
123
+ def check_root(self, name: str, root: Path) -> None:
124
+ for other_name, other in self.profiles.items():
125
+ if other_name != name and _paths_overlap(root, other.local_root):
126
+ raise ConfigurationError(
127
+ f"local root '{root}' overlaps profile '{other_name}' "
128
+ f"at '{other.local_root}'"
129
+ )
130
+
131
+ def profile_for_path(self, path: Path) -> tuple[str, Profile] | None:
132
+ for name, profile in self.profiles.items():
133
+ if path == profile.local_root or profile.local_root in path.parents:
134
+ return name, profile
135
+ return None
136
+
137
+
138
+ class ConfigurationStore:
139
+ def __init__(self, path: Path | None = None) -> None:
140
+ self.path = path or Path.home() / ".wpsync" / "config.json"
141
+
142
+ def load(self) -> Configuration:
143
+ if not self.path.exists():
144
+ return Configuration()
145
+ try:
146
+ document = json.loads(self.path.read_text(encoding="utf-8"))
147
+ except (OSError, json.JSONDecodeError) as error:
148
+ raise ConfigurationError(f"cannot read {self.path}: {error}") from error
149
+ if not isinstance(document, dict) or document.get("version") != CONFIG_VERSION:
150
+ raise ConfigurationError(
151
+ f"{self.path} is not a version {CONFIG_VERSION} wpsync configuration"
152
+ )
153
+ profiles = document.get("profiles", {})
154
+ if not isinstance(profiles, dict):
155
+ raise ConfigurationError(f"{self.path}: profiles must be an object")
156
+ configuration = Configuration()
157
+ for name, profile in profiles.items():
158
+ configuration.add(
159
+ validate_profile_name(name), Profile.from_document(name, profile)
160
+ )
161
+ return configuration
162
+
163
+ def save(self, configuration: Configuration) -> None:
164
+ document = {
165
+ "version": CONFIG_VERSION,
166
+ "profiles": {
167
+ name: profile.to_document()
168
+ for name, profile in sorted(configuration.profiles.items())
169
+ },
170
+ }
171
+ self.path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
172
+ payload = json.dumps(document, indent=2) + "\n"
173
+ write_text_atomic(self.path, payload, mode=0o600)
wpsync/documents.py ADDED
@@ -0,0 +1,258 @@
1
+ """Local post files: Markdown with YAML frontmatter.
2
+
3
+ WPSync owns the synchronized fields and rewrites them canonically. Any other
4
+ frontmatter entry is kept byte for byte, including its comments, and is never
5
+ sent to the blog.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import hashlib
11
+ import json
12
+ import os
13
+ from dataclasses import dataclass
14
+ from datetime import UTC, datetime
15
+ from pathlib import Path
16
+
17
+ import yaml
18
+ from yaml.nodes import MappingNode, Node, ScalarNode, SequenceNode
19
+
20
+ from wpsync.posts import Post, PostStatus
21
+ from wpsync.storage import write_text_atomic
22
+
23
+ POSTS_DIR = "posts"
24
+ FENCE = "---"
25
+ FIELDS = ("id", "title", "slug", "date", "status", "categories", "tags")
26
+ EXAMPLE_HEADER = "---\ntitle: My post\nstatus: draft\n---"
27
+
28
+
29
+ class DocumentError(ValueError):
30
+ """Raised when a post file cannot be read as a WPSync document."""
31
+
32
+
33
+ @dataclass(frozen=True)
34
+ class Document:
35
+ post_id: str | None
36
+ post: Post
37
+ extra: tuple[tuple[str, str], ...] = ()
38
+ """Unsynchronized frontmatter entries as (key, original text)."""
39
+
40
+ @property
41
+ def extra_keys(self) -> tuple[str, ...]:
42
+ return tuple(key for key, _ in self.extra)
43
+
44
+
45
+ @dataclass(frozen=True)
46
+ class LocalDocument:
47
+ path: Path
48
+ """Relative to the profile's local root."""
49
+ document: Document
50
+
51
+
52
+ def _scalar(node: Node, key: str) -> str:
53
+ if not isinstance(node, ScalarNode):
54
+ raise DocumentError(f"'{key}' must be a single value")
55
+ return node.value
56
+
57
+
58
+ def _terms(node: Node, key: str) -> tuple[str, ...]:
59
+ if isinstance(node, ScalarNode) and node.value == "":
60
+ return ()
61
+ if not isinstance(node, SequenceNode):
62
+ raise DocumentError(f"'{key}' must be a list, such as {key}: [One, Two]")
63
+ names = [_scalar(item, key).strip() for item in node.value]
64
+ if not all(names):
65
+ raise DocumentError(f"'{key}' cannot contain empty names")
66
+ return tuple(sorted(set(names)))
67
+
68
+
69
+ def _date(value: str) -> datetime | None:
70
+ if value == "":
71
+ return None
72
+ try:
73
+ parsed = datetime.fromisoformat(value)
74
+ except ValueError as error:
75
+ raise DocumentError(
76
+ f"date '{value}' is not an ISO date, such as 2026-10-01T09:30:00+02:00"
77
+ ) from error
78
+ if parsed.tzinfo is None:
79
+ raise DocumentError(
80
+ f"date '{value}' needs a time zone, such as 2026-10-01T09:30:00+02:00"
81
+ )
82
+ return parsed
83
+
84
+
85
+ def _status(value: str) -> PostStatus:
86
+ if value == "":
87
+ return PostStatus.DRAFT
88
+ try:
89
+ return PostStatus(value)
90
+ except ValueError as error:
91
+ choices = ", ".join(status.value for status in PostStatus)
92
+ raise DocumentError(f"status '{value}' must be one of: {choices}") from error
93
+
94
+
95
+ def _line_end(text: str, index: int) -> int:
96
+ if index > 0 and text[index - 1] == "\n":
97
+ return index
98
+ newline = text.find("\n", index)
99
+ return len(text) if newline == -1 else newline + 1
100
+
101
+
102
+ def _split(text: str) -> tuple[str, str]:
103
+ lines = text.split("\n")
104
+ if lines[0] != FENCE:
105
+ raise DocumentError(
106
+ f"missing frontmatter; start the file with a header such as:\n"
107
+ f"{EXAMPLE_HEADER}"
108
+ )
109
+ for index, line in enumerate(lines[1:], start=1):
110
+ if line in (FENCE, "..."):
111
+ return "\n".join(lines[1:index]) + "\n", "\n".join(lines[index + 1 :])
112
+ raise DocumentError("frontmatter is not closed with a '---' line")
113
+
114
+
115
+ def parse_document(text: str) -> Document:
116
+ text = text.removeprefix("").replace("\r\n", "\n")
117
+ header, body = _split(text)
118
+ try:
119
+ root = yaml.compose(header, Loader=yaml.BaseLoader)
120
+ except yaml.YAMLError as error:
121
+ raise DocumentError(f"frontmatter is not valid YAML: {error}") from error
122
+ if root is None:
123
+ entries = []
124
+ elif isinstance(root, MappingNode):
125
+ entries = root.value
126
+ else:
127
+ raise DocumentError("frontmatter must be a set of 'key: value' lines")
128
+ values: dict[str, Node] = {}
129
+ extra: list[tuple[str, str]] = []
130
+ seen: set[str] = set()
131
+ start = 0
132
+ for index, (key_node, value_node) in enumerate(entries):
133
+ key = _scalar(key_node, "frontmatter key")
134
+ last = index == len(entries) - 1
135
+ end = len(header) if last else _line_end(header, value_node.end_mark.index)
136
+ if key in seen:
137
+ raise DocumentError(f"'{key}' appears more than once")
138
+ seen.add(key)
139
+ if key in FIELDS:
140
+ values[key] = value_node
141
+ else:
142
+ extra.append((key, header[start:end]))
143
+ start = end
144
+ post_id = _scalar(values["id"], "id").strip() if "id" in values else ""
145
+ post = Post(
146
+ title=_scalar(values["title"], "title") if "title" in values else "",
147
+ slug=_scalar(values["slug"], "slug").strip() if "slug" in values else "",
148
+ date=_date(_scalar(values["date"], "date").strip())
149
+ if "date" in values
150
+ else None,
151
+ status=_status(_scalar(values["status"], "status").strip())
152
+ if "status" in values
153
+ else PostStatus.DRAFT,
154
+ categories=_terms(values["categories"], "categories")
155
+ if "categories" in values
156
+ else (),
157
+ tags=_terms(values["tags"], "tags") if "tags" in values else (),
158
+ body=body.strip("\n"),
159
+ )
160
+ return Document(post_id or None, post, tuple(extra))
161
+
162
+
163
+ def _yaml_value(key: str, value: object) -> str:
164
+ return yaml.safe_dump(
165
+ {key: value}, allow_unicode=True, sort_keys=False, width=1_000_000
166
+ )
167
+
168
+
169
+ def serialize_document(document: Document) -> str:
170
+ post = document.post
171
+ lines = []
172
+ if document.post_id is not None:
173
+ if document.post_id.isdigit():
174
+ lines.append(f"id: {document.post_id}\n")
175
+ else:
176
+ lines.append(_yaml_value("id", document.post_id))
177
+ lines.append(_yaml_value("title", post.title))
178
+ if post.slug:
179
+ lines.append(_yaml_value("slug", post.slug))
180
+ if post.date is not None:
181
+ lines.append(f"date: {post.date.isoformat()}\n")
182
+ lines.append(f"status: {post.status}\n")
183
+ lines.append(_yaml_value("categories", list(post.categories)))
184
+ lines.append(_yaml_value("tags", list(post.tags)))
185
+ for _, text in document.extra:
186
+ lines.append(text if text.endswith("\n") else text + "\n")
187
+ header = "".join(lines)
188
+ body = f"\n{post.body}\n" if post.body else ""
189
+ return f"{FENCE}\n{header}{FENCE}\n{body}"
190
+
191
+
192
+ def _load(path: Path) -> Document:
193
+ try:
194
+ text = path.read_text(encoding="utf-8")
195
+ except (OSError, UnicodeDecodeError) as error:
196
+ raise DocumentError(f"cannot read: {error}") from error
197
+ return parse_document(text)
198
+
199
+
200
+ def write_document(path: Path, document: Document) -> None:
201
+ write_text_atomic(path, serialize_document(document), mode=0o644)
202
+
203
+
204
+ def _post_files(posts_dir: Path) -> list[Path]:
205
+ files = []
206
+ for directory, subdirectories, names in os.walk(posts_dir):
207
+ subdirectories[:] = [
208
+ name for name in subdirectories if not name.startswith(".")
209
+ ]
210
+ files.extend(
211
+ Path(directory, name)
212
+ for name in names
213
+ if name.endswith(".md") and not name.startswith(".")
214
+ )
215
+ return sorted(files)
216
+
217
+
218
+ def scan_documents(root: Path) -> list[LocalDocument]:
219
+ """Read every post file under the root, reporting all problems together."""
220
+ documents: list[LocalDocument] = []
221
+ problems: list[str] = []
222
+ for path in _post_files(root / POSTS_DIR):
223
+ relative = path.relative_to(root)
224
+ try:
225
+ documents.append(LocalDocument(relative, _load(path)))
226
+ except DocumentError as error:
227
+ problems.append(f"{relative}: {error}")
228
+ users: dict[str, list[Path]] = {}
229
+ for item in documents:
230
+ if item.document.post_id is not None:
231
+ users.setdefault(item.document.post_id, []).append(item.path)
232
+ for post_id, paths in sorted(users.items()):
233
+ if len(paths) > 1:
234
+ listed = ", ".join(str(path) for path in paths)
235
+ problems.append(
236
+ f"post id {post_id} is used by more than one file: {listed}"
237
+ )
238
+ if problems:
239
+ raise DocumentError("\n".join(problems))
240
+ return documents
241
+
242
+
243
+ def body_checksum(post: Post) -> str:
244
+ return hashlib.sha256(post.body.encode()).hexdigest()
245
+
246
+
247
+ def fields_checksum(post: Post) -> str:
248
+ """One checksum over every synchronized header field."""
249
+ fields = {
250
+ "title": post.title,
251
+ "slug": post.slug,
252
+ "date": post.date.astimezone(UTC).isoformat() if post.date else None,
253
+ "status": post.status.value,
254
+ "categories": list(post.categories),
255
+ "tags": list(post.tags),
256
+ }
257
+ encoded = json.dumps(fields, sort_keys=True, ensure_ascii=False)
258
+ return hashlib.sha256(encoded.encode()).hexdigest()
File without changes