wpsync 1.2.1__tar.gz
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-1.2.1/.gitignore +11 -0
- wpsync-1.2.1/LICENSE +61 -0
- wpsync-1.2.1/PKG-INFO +312 -0
- wpsync-1.2.1/README.md +293 -0
- wpsync-1.2.1/build_backend/versioning.py +57 -0
- wpsync-1.2.1/pyproject.toml +66 -0
- wpsync-1.2.1/src/wpsync/__init__.py +3 -0
- wpsync-1.2.1/src/wpsync/__main__.py +3 -0
- wpsync-1.2.1/src/wpsync/cli.py +740 -0
- wpsync-1.2.1/src/wpsync/config.py +173 -0
- wpsync-1.2.1/src/wpsync/documents.py +258 -0
- wpsync-1.2.1/src/wpsync/markup/__init__.py +0 -0
- wpsync-1.2.1/src/wpsync/markup/dom.py +313 -0
- wpsync-1.2.1/src/wpsync/markup/markdown.py +526 -0
- wpsync-1.2.1/src/wpsync/media.py +92 -0
- wpsync-1.2.1/src/wpsync/posts.py +76 -0
- wpsync-1.2.1/src/wpsync/pull.py +324 -0
- wpsync-1.2.1/src/wpsync/state.py +177 -0
- wpsync-1.2.1/src/wpsync/storage.py +28 -0
- wpsync-1.2.1/src/wpsync/sync.py +260 -0
- wpsync-1.2.1/src/wpsync/wordpress/__init__.py +0 -0
- wpsync-1.2.1/src/wpsync/wordpress/autop.py +114 -0
- wpsync-1.2.1/src/wpsync/wordpress/client.py +208 -0
- wpsync-1.2.1/src/wpsync/wordpress/content.py +565 -0
- wpsync-1.2.1/src/wpsync/wordpress/remote.py +100 -0
- wpsync-1.2.1/version.json +3 -0
wpsync-1.2.1/.gitignore
ADDED
wpsync-1.2.1/LICENSE
ADDED
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
Copyright (c) 2026 WPSync contributors
|
|
2
|
+
|
|
3
|
+
# PolyForm Strict License 1.0.0
|
|
4
|
+
|
|
5
|
+
<https://polyformproject.org/licenses/strict/1.0.0>
|
|
6
|
+
|
|
7
|
+
## Acceptance
|
|
8
|
+
|
|
9
|
+
In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
|
|
10
|
+
|
|
11
|
+
## Copyright License
|
|
12
|
+
|
|
13
|
+
The licensor grants you a copyright license for the software to do everything you might do with the software that would otherwise infringe the licensor's copyright in it for any permitted purpose, other than distributing the software or making changes or new works based on the software.
|
|
14
|
+
|
|
15
|
+
## Patent License
|
|
16
|
+
|
|
17
|
+
The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software.
|
|
18
|
+
|
|
19
|
+
## Noncommercial Purposes
|
|
20
|
+
|
|
21
|
+
Any noncommercial purpose is a permitted purpose.
|
|
22
|
+
|
|
23
|
+
## Personal Uses
|
|
24
|
+
|
|
25
|
+
Personal use for research, experiment, and testing for the benefit of public knowledge, personal study, private entertainment, hobby projects, amateur pursuits, or religious observance, without any anticipated commercial application, is use for a permitted purpose.
|
|
26
|
+
|
|
27
|
+
## Noncommercial Organizations
|
|
28
|
+
|
|
29
|
+
Use by any charitable organization, educational institution, public research organization, public safety or health organization, environmental protection organization, or government institution is use for a permitted purpose regardless of the source of funding or obligations resulting from the funding.
|
|
30
|
+
|
|
31
|
+
## Fair Use
|
|
32
|
+
|
|
33
|
+
You may have "fair use" rights for the software under the law. These terms do not limit them.
|
|
34
|
+
|
|
35
|
+
## No Other Rights
|
|
36
|
+
|
|
37
|
+
These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else. These terms do not imply any other licenses.
|
|
38
|
+
|
|
39
|
+
## Patent Defense
|
|
40
|
+
|
|
41
|
+
If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
|
|
42
|
+
|
|
43
|
+
## Violations
|
|
44
|
+
|
|
45
|
+
The first time you are notified in writing that you have violated any of these terms, or done anything with the software not covered by your licenses, your licenses can nonetheless continue if you come into full compliance with these terms, and take practical steps to correct past violations, within 32 days of receiving notice. Otherwise, all your licenses end immediately.
|
|
46
|
+
|
|
47
|
+
## No Liability
|
|
48
|
+
|
|
49
|
+
***As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.***
|
|
50
|
+
|
|
51
|
+
## Definitions
|
|
52
|
+
|
|
53
|
+
The **licensor** is the individual or entity offering these terms, and the **software** is the software the licensor makes available under these terms.
|
|
54
|
+
|
|
55
|
+
**You** refers to the individual or entity agreeing to these terms.
|
|
56
|
+
|
|
57
|
+
**Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all organizations that have control over, are under the control of, or are under common control with that organization. **Control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise. Control can be direct or indirect.
|
|
58
|
+
|
|
59
|
+
**Your licenses** are all the licenses granted to you for the software under these terms.
|
|
60
|
+
|
|
61
|
+
**Use** means anything you do with the software requiring one of your licenses.
|
wpsync-1.2.1/PKG-INFO
ADDED
|
@@ -0,0 +1,312 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: wpsync
|
|
3
|
+
Version: 1.2.1
|
|
4
|
+
Summary: Manage blog posts as local Markdown files
|
|
5
|
+
License-Expression: LicenseRef-PolyForm-Strict-1.0.0
|
|
6
|
+
License-File: LICENSE
|
|
7
|
+
Classifier: Development Status :: 2 - Pre-Alpha
|
|
8
|
+
Classifier: Environment :: Console
|
|
9
|
+
Classifier: Operating System :: OS Independent
|
|
10
|
+
Classifier: Programming Language :: Python :: 3
|
|
11
|
+
Requires-Python: >=3.11
|
|
12
|
+
Requires-Dist: html5lib<2,>=1.1
|
|
13
|
+
Requires-Dist: httpx<1,>=0.28
|
|
14
|
+
Requires-Dist: markdown-it-py<5,>=3
|
|
15
|
+
Requires-Dist: mdit-py-plugins<1,>=0.5
|
|
16
|
+
Requires-Dist: pyyaml<7,>=6
|
|
17
|
+
Requires-Dist: tzdata; sys_platform == 'win32'
|
|
18
|
+
Description-Content-Type: text/markdown
|
|
19
|
+
|
|
20
|
+
# WPSync
|
|
21
|
+
|
|
22
|
+
WPSync (`wpsync`) is a command-line tool for managing blog posts as local
|
|
23
|
+
Markdown files: map a folder to a blog, pull its posts, edit them in any
|
|
24
|
+
editor, preview the differences, and push the changes back. WordPress is the
|
|
25
|
+
first supported platform.
|
|
26
|
+
|
|
27
|
+
WPSync is pre-alpha software. Profiles and the connection check work today;
|
|
28
|
+
pull, diff, and push are in progress (see `TODO.md`).
|
|
29
|
+
|
|
30
|
+
## Installation
|
|
31
|
+
|
|
32
|
+
WPSync requires Python 3.11 or newer. Install it from a checkout with uv:
|
|
33
|
+
|
|
34
|
+
```console
|
|
35
|
+
uv tool install --editable /path/to/wpsync/app
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
## Credentials
|
|
39
|
+
|
|
40
|
+
WPSync signs in with a WordPress Application Password, which you create in the
|
|
41
|
+
WordPress dashboard under **Users > Profile > Application Passwords**.
|
|
42
|
+
Application Passwords require the site to use HTTPS.
|
|
43
|
+
|
|
44
|
+
WPSync reads the password from an environment variable and never stores it. The
|
|
45
|
+
variable name comes from the profile name: profile `myblog` reads
|
|
46
|
+
`MYBLOG_WP_PASSWORD`. Choose a different variable with `--password-env` when
|
|
47
|
+
creating the profile.
|
|
48
|
+
|
|
49
|
+
## Profiles
|
|
50
|
+
|
|
51
|
+
A profile maps one local folder to one blog. Profiles are stored in
|
|
52
|
+
`~/.wpsync/config.json`. Folders may not overlap between profiles.
|
|
53
|
+
|
|
54
|
+
From the folder you want to use for the blog:
|
|
55
|
+
|
|
56
|
+
```console
|
|
57
|
+
export MYBLOG_WP_PASSWORD='abcd efgh ijkl mnop qrst uvwx'
|
|
58
|
+
wpsync create myblog --site https://example.com --username emrah
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
`create` offers the current directory as the profile's folder; press Enter to
|
|
62
|
+
accept it, or decline to name another. Use `--local-root PATH` to name it
|
|
63
|
+
directly, and omit `--username` to be prompted. Before saving the profile,
|
|
64
|
+
`create` finds the blog's REST API, signs in, and lists the blog's posts. If
|
|
65
|
+
the password variable is missing or sign-in fails, nothing is saved.
|
|
66
|
+
|
|
67
|
+
Commands run inside a profile's folder, or any folder below it, use that
|
|
68
|
+
profile automatically. Elsewhere, put the profile name before the command:
|
|
69
|
+
|
|
70
|
+
```console
|
|
71
|
+
wpsync connect # sign in and list the blog's posts
|
|
72
|
+
wpsync myblog connect # the same, from any directory
|
|
73
|
+
wpsync profiles # list profiles; * marks the current one
|
|
74
|
+
wpsync profile --details # show the current profile's settings
|
|
75
|
+
wpsync root myblog # print the profile's folder
|
|
76
|
+
wpsync map --local-root /new/folder # move the profile to another folder
|
|
77
|
+
wpsync remove myblog # remove the profile only
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
`map` asks for confirmation and only changes the local folder. A different
|
|
81
|
+
blog needs its own profile, because synchronization state belongs to one blog.
|
|
82
|
+
`remove` deletes only the profile; local files and the blog stay unchanged.
|
|
83
|
+
|
|
84
|
+
Commands may be shortened to any unique prefix, such as `wpsync conn`.
|
|
85
|
+
|
|
86
|
+
## Post files
|
|
87
|
+
|
|
88
|
+
Each post is a Markdown file under the profile folder's `posts/` directory, in
|
|
89
|
+
any subfolder. The file starts with a YAML header:
|
|
90
|
+
|
|
91
|
+
```markdown
|
|
92
|
+
---
|
|
93
|
+
id: 123
|
|
94
|
+
title: Hello world
|
|
95
|
+
slug: hello-world
|
|
96
|
+
date: 2026-10-01T09:30:00+02:00
|
|
97
|
+
status: published
|
|
98
|
+
categories:
|
|
99
|
+
- News
|
|
100
|
+
tags:
|
|
101
|
+
- python
|
|
102
|
+
---
|
|
103
|
+
|
|
104
|
+
The post body in Markdown.
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
- `id` links the file to a WordPress post. Leave it out for a new post.
|
|
108
|
+
- `title`, `slug`, and `date` are optional. A `date` needs a time zone offset
|
|
109
|
+
or `Z`.
|
|
110
|
+
- `status` is one of `draft`, `published`, `scheduled`, `pending`, or
|
|
111
|
+
`private`, and defaults to `draft`.
|
|
112
|
+
- `categories` and `tags` are lists of names.
|
|
113
|
+
|
|
114
|
+
The body is Markdown. Styling that plain Markdown cannot express uses
|
|
115
|
+
Pandoc-style attributes, and only where a post has such styling:
|
|
116
|
+
|
|
117
|
+
```markdown
|
|
118
|
+
Some [red text]{style="color: #c00"} and [a link](https://example.com/){target=_blank}.
|
|
119
|
+
|
|
120
|
+
{.has-text-align-right}
|
|
121
|
+
A right-aligned paragraph.
|
|
122
|
+
|
|
123
|
+
{.aligncenter}
|
|
124
|
+
|
|
125
|
+
:::: {.wp-block-columns}
|
|
126
|
+
::: {.wp-block-column}
|
|
127
|
+
Left column.
|
|
128
|
+
:::
|
|
129
|
+
::::
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
A video or other embeddable URL alone in a paragraph is embedded by WordPress.
|
|
133
|
+
Content with no Markdown form, such as galleries, stays in the file as its
|
|
134
|
+
exact original HTML; WPSync never drops it. When plain HTML would not survive
|
|
135
|
+
Markdown unchanged, it is wrapped in a raw HTML fence, which is published
|
|
136
|
+
exactly as written:
|
|
137
|
+
|
|
138
|
+
````markdown
|
|
139
|
+
```{=html}
|
|
140
|
+
<!-- wp:gallery -->
|
|
141
|
+
<figure class="wp-block-gallery">…</figure>
|
|
142
|
+
<!-- /wp:gallery -->
|
|
143
|
+
```
|
|
144
|
+
````
|
|
145
|
+
|
|
146
|
+
Other header entries, such as `layout:` from another tool, stay in the file
|
|
147
|
+
exactly as written and are never sent to WordPress. When WPSync rewrites a file,
|
|
148
|
+
it writes its own fields in the order above, sorts category and tag names, and
|
|
149
|
+
leaves other entries and their comments unchanged. Two files with the same `id`
|
|
150
|
+
are an error.
|
|
151
|
+
|
|
152
|
+
## Pulling posts
|
|
153
|
+
|
|
154
|
+
`pull` brings the blog's posts into the profile folder: each post becomes
|
|
155
|
+
`posts/<slug>.md`, and images from the site's media library are downloaded into
|
|
156
|
+
`images/` and referenced from the Markdown. The copy of an image that the post
|
|
157
|
+
displays is downloaded, usually WordPress's resized `large` copy.
|
|
158
|
+
|
|
159
|
+
```console
|
|
160
|
+
wpsync pull # every post
|
|
161
|
+
wpsync pull 123 # one post, by ID
|
|
162
|
+
wpsync pull hello # one post, by slug, including one not pulled yet
|
|
163
|
+
wpsync pull -y # answer yes to every question
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
```text
|
|
167
|
+
+ r 123 posts/hello-world.md 2 images
|
|
168
|
+
~ r 145 posts/release-notes.md
|
|
169
|
+
? 150 posts/about.md changed on both sides; your file is unchanged
|
|
170
|
+
+ r 160 posts/gallery-tour.md kept as HTML: core/gallery
|
|
171
|
+
Pulled 3 posts (2 new, 1 updated), 2 images; 1 skipped. Rerun with --yes to accept the skipped changes.
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
Pull never loses local work:
|
|
175
|
+
|
|
176
|
+
- A file you edited is replaced only after you confirm, and only when the post
|
|
177
|
+
also changed on WordPress. Without a terminal, or when you answer no, the
|
|
178
|
+
file is skipped.
|
|
179
|
+
- A WordPress post whose title or slug matches a local file that has no `id`
|
|
180
|
+
yet is linked to that file only after you confirm, so pull does not create
|
|
181
|
+
a duplicate.
|
|
182
|
+
- A file you deleted is not restored, and a post deleted on WordPress keeps its
|
|
183
|
+
local file.
|
|
184
|
+
- Header entries WPSync does not sync, such as `layout:`, are kept when a file
|
|
185
|
+
is updated.
|
|
186
|
+
|
|
187
|
+
Dates are written in the blog's time zone. Images placed inside a line of text,
|
|
188
|
+
rather than on their own, keep their WordPress address and are not downloaded.
|
|
189
|
+
|
|
190
|
+
## Seeing what changed
|
|
191
|
+
|
|
192
|
+
Local files are the source of truth. `ls` lists the posts in the profile folder
|
|
193
|
+
with their IDs and slugs, without contacting the blog:
|
|
194
|
+
|
|
195
|
+
```console
|
|
196
|
+
wpsync ls
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
`diff` shows what a push would change and anything that would stop it:
|
|
200
|
+
|
|
201
|
+
```console
|
|
202
|
+
wpsync diff # every post
|
|
203
|
+
wpsync diff 123 # one post, by ID
|
|
204
|
+
wpsync diff hello # one post, by slug
|
|
205
|
+
wpsync diff posts/new-idea.md # one post, by file
|
|
206
|
+
wpsync diff -a # also list unchanged posts
|
|
207
|
+
wpsync --legend # explain the status symbols
|
|
208
|
+
```
|
|
209
|
+
|
|
210
|
+
```text
|
|
211
|
+
~ l 123 posts/hello-world.md content; block post becomes plain HTML on push
|
|
212
|
+
~ l 145 posts/release-notes.md details
|
|
213
|
+
? 150 posts/about.md content; also changed on WordPress since the last sync
|
|
214
|
+
- l 160 posts/old.md deleted locally; WordPress keeps the post
|
|
215
|
+
+ l - posts/new-idea.md new post
|
|
216
|
+
Not shown: 12 unchanged (-a to show)
|
|
217
|
+
```
|
|
218
|
+
|
|
219
|
+
`content` means the body changed and `details` means a header field changed.
|
|
220
|
+
`diff` never changes anything. It contacts the blog only for posts that changed
|
|
221
|
+
locally, to check whether they also changed on WordPress since the last sync,
|
|
222
|
+
and for new files, to match them against existing posts by title and slug.
|
|
223
|
+
With no local changes it works offline. Posts created or edited on WordPress
|
|
224
|
+
appear only through `pull`.
|
|
225
|
+
|
|
226
|
+
## License
|
|
227
|
+
|
|
228
|
+
WPSync is source-available under the [PolyForm Strict License 1.0.0](LICENSE).
|
|
229
|
+
Use is free of charge for the purposes permitted by that license, including:
|
|
230
|
+
|
|
231
|
+
- Any noncommercial purpose.
|
|
232
|
+
- The personal uses listed in the license, such as personal study and hobby
|
|
233
|
+
projects, without any anticipated commercial application.
|
|
234
|
+
- Use by charitable organizations, educational institutions, public research
|
|
235
|
+
organizations, public safety or health organizations, environmental protection
|
|
236
|
+
organizations, and government institutions, regardless of funding source or
|
|
237
|
+
obligations resulting from funding.
|
|
238
|
+
|
|
239
|
+
This license grants no rights to modify or redistribute WPSync or create works
|
|
240
|
+
based on it. The full license governs; this summary does not grant additional
|
|
241
|
+
permissions.
|
|
242
|
+
|
|
243
|
+
Commercial use outside those permissions requires a separate paid license.
|
|
244
|
+
Contact [Emrah Diril](mailto:emrah@diril.org) for pricing and a commercial
|
|
245
|
+
agreement before beginning such use.
|
|
246
|
+
|
|
247
|
+
WPSync is source-available, not open source.
|
|
248
|
+
|
|
249
|
+
## Development
|
|
250
|
+
|
|
251
|
+
See [`TODO.md`](TODO.md) for the ordered work queue and
|
|
252
|
+
[`CHANGELOG.md`](CHANGELOG.md) for completed changes.
|
|
253
|
+
|
|
254
|
+
```console
|
|
255
|
+
uv sync
|
|
256
|
+
uv run pytest
|
|
257
|
+
uv run ruff check src tests
|
|
258
|
+
```
|
|
259
|
+
|
|
260
|
+
### Versions
|
|
261
|
+
|
|
262
|
+
Versions use `<major>.<work-day>.<increment>` without leading zeroes and
|
|
263
|
+
advance from Git history, not from the build date:
|
|
264
|
+
|
|
265
|
+
- [`version.json`](version.json) gives the starting version of the history's
|
|
266
|
+
first commit.
|
|
267
|
+
- Each later date with commits advances the work-day number by one, regardless
|
|
268
|
+
of how many idle days pass.
|
|
269
|
+
- The increment counts the commits on the latest commit date, continuing from
|
|
270
|
+
the starting increment on the first day.
|
|
271
|
+
|
|
272
|
+
Versions follow first-parent history, so commit dates must not go backwards.
|
|
273
|
+
Wheels and source archives keep the computed version; installed commands do
|
|
274
|
+
not use Git. `uv sync` rebuilds the development install when `version.json` or
|
|
275
|
+
the current commit changes; a copy installed with `uv tool install` keeps its
|
|
276
|
+
version until it is reinstalled. `wpsync --version` prints the installed version.
|
|
277
|
+
|
|
278
|
+
### Releasing to PyPI
|
|
279
|
+
|
|
280
|
+
Use a PyPI account with two-factor authentication and an API token. Twine reads
|
|
281
|
+
credentials from `~/.pypirc` or `TWINE_USERNAME`/`TWINE_PASSWORD` and prompts
|
|
282
|
+
if needed. Do not store the token in the repository.
|
|
283
|
+
|
|
284
|
+
1. Commit everything to release. Preparation refuses a working tree with
|
|
285
|
+
uncommitted changes, because the version describes the last commit.
|
|
286
|
+
2. With development dependencies installed (`uv sync`), run:
|
|
287
|
+
|
|
288
|
+
```console
|
|
289
|
+
./scripts/publish.sh
|
|
290
|
+
```
|
|
291
|
+
|
|
292
|
+
The script uses the repository's `.venv/bin/python` when available,
|
|
293
|
+
otherwise `python3`; set `PYTHON` to select another interpreter. Through the
|
|
294
|
+
helpers in `scripts/helpers/`, it checks the release identity, runs lint and
|
|
295
|
+
tests, builds the wheel and source archive with `uv build`, checks their
|
|
296
|
+
metadata with Twine, installs the wheel into a clean environment to confirm
|
|
297
|
+
`wpsync --version`, and uploads both artifacts. Prepared artifacts are kept
|
|
298
|
+
in `dist/wpsync/<version>/` and reused if the script runs again for the same
|
|
299
|
+
version.
|
|
300
|
+
|
|
301
|
+
To prepare and validate artifacts without publishing, run
|
|
302
|
+
`./scripts/publish.sh --prepare`.
|
|
303
|
+
|
|
304
|
+
3. Tag the release commit as `v<version>`, push the tag, and create a matching
|
|
305
|
+
GitHub Release. PyPI does not require a tag, but it records which source was
|
|
306
|
+
published.
|
|
307
|
+
4. Install the published version in a clean environment and run
|
|
308
|
+
`wpsync --version` before announcing it.
|
|
309
|
+
|
|
310
|
+
PyPI never lets a published version be replaced. If publication fails after
|
|
311
|
+
PyPI accepted either artifact, make another commit (an empty commit is enough)
|
|
312
|
+
and publish the new version.
|
wpsync-1.2.1/README.md
ADDED
|
@@ -0,0 +1,293 @@
|
|
|
1
|
+
# WPSync
|
|
2
|
+
|
|
3
|
+
WPSync (`wpsync`) is a command-line tool for managing blog posts as local
|
|
4
|
+
Markdown files: map a folder to a blog, pull its posts, edit them in any
|
|
5
|
+
editor, preview the differences, and push the changes back. WordPress is the
|
|
6
|
+
first supported platform.
|
|
7
|
+
|
|
8
|
+
WPSync is pre-alpha software. Profiles and the connection check work today;
|
|
9
|
+
pull, diff, and push are in progress (see `TODO.md`).
|
|
10
|
+
|
|
11
|
+
## Installation
|
|
12
|
+
|
|
13
|
+
WPSync requires Python 3.11 or newer. Install it from a checkout with uv:
|
|
14
|
+
|
|
15
|
+
```console
|
|
16
|
+
uv tool install --editable /path/to/wpsync/app
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
## Credentials
|
|
20
|
+
|
|
21
|
+
WPSync signs in with a WordPress Application Password, which you create in the
|
|
22
|
+
WordPress dashboard under **Users > Profile > Application Passwords**.
|
|
23
|
+
Application Passwords require the site to use HTTPS.
|
|
24
|
+
|
|
25
|
+
WPSync reads the password from an environment variable and never stores it. The
|
|
26
|
+
variable name comes from the profile name: profile `myblog` reads
|
|
27
|
+
`MYBLOG_WP_PASSWORD`. Choose a different variable with `--password-env` when
|
|
28
|
+
creating the profile.
|
|
29
|
+
|
|
30
|
+
## Profiles
|
|
31
|
+
|
|
32
|
+
A profile maps one local folder to one blog. Profiles are stored in
|
|
33
|
+
`~/.wpsync/config.json`. Folders may not overlap between profiles.
|
|
34
|
+
|
|
35
|
+
From the folder you want to use for the blog:
|
|
36
|
+
|
|
37
|
+
```console
|
|
38
|
+
export MYBLOG_WP_PASSWORD='abcd efgh ijkl mnop qrst uvwx'
|
|
39
|
+
wpsync create myblog --site https://example.com --username emrah
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
`create` offers the current directory as the profile's folder; press Enter to
|
|
43
|
+
accept it, or decline to name another. Use `--local-root PATH` to name it
|
|
44
|
+
directly, and omit `--username` to be prompted. Before saving the profile,
|
|
45
|
+
`create` finds the blog's REST API, signs in, and lists the blog's posts. If
|
|
46
|
+
the password variable is missing or sign-in fails, nothing is saved.
|
|
47
|
+
|
|
48
|
+
Commands run inside a profile's folder, or any folder below it, use that
|
|
49
|
+
profile automatically. Elsewhere, put the profile name before the command:
|
|
50
|
+
|
|
51
|
+
```console
|
|
52
|
+
wpsync connect # sign in and list the blog's posts
|
|
53
|
+
wpsync myblog connect # the same, from any directory
|
|
54
|
+
wpsync profiles # list profiles; * marks the current one
|
|
55
|
+
wpsync profile --details # show the current profile's settings
|
|
56
|
+
wpsync root myblog # print the profile's folder
|
|
57
|
+
wpsync map --local-root /new/folder # move the profile to another folder
|
|
58
|
+
wpsync remove myblog # remove the profile only
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
`map` asks for confirmation and only changes the local folder. A different
|
|
62
|
+
blog needs its own profile, because synchronization state belongs to one blog.
|
|
63
|
+
`remove` deletes only the profile; local files and the blog stay unchanged.
|
|
64
|
+
|
|
65
|
+
Commands may be shortened to any unique prefix, such as `wpsync conn`.
|
|
66
|
+
|
|
67
|
+
## Post files
|
|
68
|
+
|
|
69
|
+
Each post is a Markdown file under the profile folder's `posts/` directory, in
|
|
70
|
+
any subfolder. The file starts with a YAML header:
|
|
71
|
+
|
|
72
|
+
```markdown
|
|
73
|
+
---
|
|
74
|
+
id: 123
|
|
75
|
+
title: Hello world
|
|
76
|
+
slug: hello-world
|
|
77
|
+
date: 2026-10-01T09:30:00+02:00
|
|
78
|
+
status: published
|
|
79
|
+
categories:
|
|
80
|
+
- News
|
|
81
|
+
tags:
|
|
82
|
+
- python
|
|
83
|
+
---
|
|
84
|
+
|
|
85
|
+
The post body in Markdown.
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
- `id` links the file to a WordPress post. Leave it out for a new post.
|
|
89
|
+
- `title`, `slug`, and `date` are optional. A `date` needs a time zone offset
|
|
90
|
+
or `Z`.
|
|
91
|
+
- `status` is one of `draft`, `published`, `scheduled`, `pending`, or
|
|
92
|
+
`private`, and defaults to `draft`.
|
|
93
|
+
- `categories` and `tags` are lists of names.
|
|
94
|
+
|
|
95
|
+
The body is Markdown. Styling that plain Markdown cannot express uses
|
|
96
|
+
Pandoc-style attributes, and only where a post has such styling:
|
|
97
|
+
|
|
98
|
+
```markdown
|
|
99
|
+
Some [red text]{style="color: #c00"} and [a link](https://example.com/){target=_blank}.
|
|
100
|
+
|
|
101
|
+
{.has-text-align-right}
|
|
102
|
+
A right-aligned paragraph.
|
|
103
|
+
|
|
104
|
+
{.aligncenter}
|
|
105
|
+
|
|
106
|
+
:::: {.wp-block-columns}
|
|
107
|
+
::: {.wp-block-column}
|
|
108
|
+
Left column.
|
|
109
|
+
:::
|
|
110
|
+
::::
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
A video or other embeddable URL alone in a paragraph is embedded by WordPress.
|
|
114
|
+
Content with no Markdown form, such as galleries, stays in the file as its
|
|
115
|
+
exact original HTML; WPSync never drops it. When plain HTML would not survive
|
|
116
|
+
Markdown unchanged, it is wrapped in a raw HTML fence, which is published
|
|
117
|
+
exactly as written:
|
|
118
|
+
|
|
119
|
+
````markdown
|
|
120
|
+
```{=html}
|
|
121
|
+
<!-- wp:gallery -->
|
|
122
|
+
<figure class="wp-block-gallery">…</figure>
|
|
123
|
+
<!-- /wp:gallery -->
|
|
124
|
+
```
|
|
125
|
+
````
|
|
126
|
+
|
|
127
|
+
Other header entries, such as `layout:` from another tool, stay in the file
|
|
128
|
+
exactly as written and are never sent to WordPress. When WPSync rewrites a file,
|
|
129
|
+
it writes its own fields in the order above, sorts category and tag names, and
|
|
130
|
+
leaves other entries and their comments unchanged. Two files with the same `id`
|
|
131
|
+
are an error.
|
|
132
|
+
|
|
133
|
+
## Pulling posts
|
|
134
|
+
|
|
135
|
+
`pull` brings the blog's posts into the profile folder: each post becomes
|
|
136
|
+
`posts/<slug>.md`, and images from the site's media library are downloaded into
|
|
137
|
+
`images/` and referenced from the Markdown. The copy of an image that the post
|
|
138
|
+
displays is downloaded, usually WordPress's resized `large` copy.
|
|
139
|
+
|
|
140
|
+
```console
|
|
141
|
+
wpsync pull # every post
|
|
142
|
+
wpsync pull 123 # one post, by ID
|
|
143
|
+
wpsync pull hello # one post, by slug, including one not pulled yet
|
|
144
|
+
wpsync pull -y # answer yes to every question
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
```text
|
|
148
|
+
+ r 123 posts/hello-world.md 2 images
|
|
149
|
+
~ r 145 posts/release-notes.md
|
|
150
|
+
? 150 posts/about.md changed on both sides; your file is unchanged
|
|
151
|
+
+ r 160 posts/gallery-tour.md kept as HTML: core/gallery
|
|
152
|
+
Pulled 3 posts (2 new, 1 updated), 2 images; 1 skipped. Rerun with --yes to accept the skipped changes.
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
Pull never loses local work:
|
|
156
|
+
|
|
157
|
+
- A file you edited is replaced only after you confirm, and only when the post
|
|
158
|
+
also changed on WordPress. Without a terminal, or when you answer no, the
|
|
159
|
+
file is skipped.
|
|
160
|
+
- A WordPress post whose title or slug matches a local file that has no `id`
|
|
161
|
+
yet is linked to that file only after you confirm, so pull does not create
|
|
162
|
+
a duplicate.
|
|
163
|
+
- A file you deleted is not restored, and a post deleted on WordPress keeps its
|
|
164
|
+
local file.
|
|
165
|
+
- Header entries WPSync does not sync, such as `layout:`, are kept when a file
|
|
166
|
+
is updated.
|
|
167
|
+
|
|
168
|
+
Dates are written in the blog's time zone. Images placed inside a line of text,
|
|
169
|
+
rather than on their own, keep their WordPress address and are not downloaded.
|
|
170
|
+
|
|
171
|
+
## Seeing what changed
|
|
172
|
+
|
|
173
|
+
Local files are the source of truth. `ls` lists the posts in the profile folder
|
|
174
|
+
with their IDs and slugs, without contacting the blog:
|
|
175
|
+
|
|
176
|
+
```console
|
|
177
|
+
wpsync ls
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
`diff` shows what a push would change and anything that would stop it:
|
|
181
|
+
|
|
182
|
+
```console
|
|
183
|
+
wpsync diff # every post
|
|
184
|
+
wpsync diff 123 # one post, by ID
|
|
185
|
+
wpsync diff hello # one post, by slug
|
|
186
|
+
wpsync diff posts/new-idea.md # one post, by file
|
|
187
|
+
wpsync diff -a # also list unchanged posts
|
|
188
|
+
wpsync --legend # explain the status symbols
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
```text
|
|
192
|
+
~ l 123 posts/hello-world.md content; block post becomes plain HTML on push
|
|
193
|
+
~ l 145 posts/release-notes.md details
|
|
194
|
+
? 150 posts/about.md content; also changed on WordPress since the last sync
|
|
195
|
+
- l 160 posts/old.md deleted locally; WordPress keeps the post
|
|
196
|
+
+ l - posts/new-idea.md new post
|
|
197
|
+
Not shown: 12 unchanged (-a to show)
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
`content` means the body changed and `details` means a header field changed.
|
|
201
|
+
`diff` never changes anything. It contacts the blog only for posts that changed
|
|
202
|
+
locally, to check whether they also changed on WordPress since the last sync,
|
|
203
|
+
and for new files, to match them against existing posts by title and slug.
|
|
204
|
+
With no local changes it works offline. Posts created or edited on WordPress
|
|
205
|
+
appear only through `pull`.
|
|
206
|
+
|
|
207
|
+
## License
|
|
208
|
+
|
|
209
|
+
WPSync is source-available under the [PolyForm Strict License 1.0.0](LICENSE).
|
|
210
|
+
Use is free of charge for the purposes permitted by that license, including:
|
|
211
|
+
|
|
212
|
+
- Any noncommercial purpose.
|
|
213
|
+
- The personal uses listed in the license, such as personal study and hobby
|
|
214
|
+
projects, without any anticipated commercial application.
|
|
215
|
+
- Use by charitable organizations, educational institutions, public research
|
|
216
|
+
organizations, public safety or health organizations, environmental protection
|
|
217
|
+
organizations, and government institutions, regardless of funding source or
|
|
218
|
+
obligations resulting from funding.
|
|
219
|
+
|
|
220
|
+
This license grants no rights to modify or redistribute WPSync or create works
|
|
221
|
+
based on it. The full license governs; this summary does not grant additional
|
|
222
|
+
permissions.
|
|
223
|
+
|
|
224
|
+
Commercial use outside those permissions requires a separate paid license.
|
|
225
|
+
Contact [Emrah Diril](mailto:emrah@diril.org) for pricing and a commercial
|
|
226
|
+
agreement before beginning such use.
|
|
227
|
+
|
|
228
|
+
WPSync is source-available, not open source.
|
|
229
|
+
|
|
230
|
+
## Development
|
|
231
|
+
|
|
232
|
+
See [`TODO.md`](TODO.md) for the ordered work queue and
|
|
233
|
+
[`CHANGELOG.md`](CHANGELOG.md) for completed changes.
|
|
234
|
+
|
|
235
|
+
```console
|
|
236
|
+
uv sync
|
|
237
|
+
uv run pytest
|
|
238
|
+
uv run ruff check src tests
|
|
239
|
+
```
|
|
240
|
+
|
|
241
|
+
### Versions
|
|
242
|
+
|
|
243
|
+
Versions use `<major>.<work-day>.<increment>` without leading zeroes and
|
|
244
|
+
advance from Git history, not from the build date:
|
|
245
|
+
|
|
246
|
+
- [`version.json`](version.json) gives the starting version of the history's
|
|
247
|
+
first commit.
|
|
248
|
+
- Each later date with commits advances the work-day number by one, regardless
|
|
249
|
+
of how many idle days pass.
|
|
250
|
+
- The increment counts the commits on the latest commit date, continuing from
|
|
251
|
+
the starting increment on the first day.
|
|
252
|
+
|
|
253
|
+
Versions follow first-parent history, so commit dates must not go backwards.
|
|
254
|
+
Wheels and source archives keep the computed version; installed commands do
|
|
255
|
+
not use Git. `uv sync` rebuilds the development install when `version.json` or
|
|
256
|
+
the current commit changes; a copy installed with `uv tool install` keeps its
|
|
257
|
+
version until it is reinstalled. `wpsync --version` prints the installed version.
|
|
258
|
+
|
|
259
|
+
### Releasing to PyPI
|
|
260
|
+
|
|
261
|
+
Use a PyPI account with two-factor authentication and an API token. Twine reads
|
|
262
|
+
credentials from `~/.pypirc` or `TWINE_USERNAME`/`TWINE_PASSWORD` and prompts
|
|
263
|
+
if needed. Do not store the token in the repository.
|
|
264
|
+
|
|
265
|
+
1. Commit everything to release. Preparation refuses a working tree with
|
|
266
|
+
uncommitted changes, because the version describes the last commit.
|
|
267
|
+
2. With development dependencies installed (`uv sync`), run:
|
|
268
|
+
|
|
269
|
+
```console
|
|
270
|
+
./scripts/publish.sh
|
|
271
|
+
```
|
|
272
|
+
|
|
273
|
+
The script uses the repository's `.venv/bin/python` when available,
|
|
274
|
+
otherwise `python3`; set `PYTHON` to select another interpreter. Through the
|
|
275
|
+
helpers in `scripts/helpers/`, it checks the release identity, runs lint and
|
|
276
|
+
tests, builds the wheel and source archive with `uv build`, checks their
|
|
277
|
+
metadata with Twine, installs the wheel into a clean environment to confirm
|
|
278
|
+
`wpsync --version`, and uploads both artifacts. Prepared artifacts are kept
|
|
279
|
+
in `dist/wpsync/<version>/` and reused if the script runs again for the same
|
|
280
|
+
version.
|
|
281
|
+
|
|
282
|
+
To prepare and validate artifacts without publishing, run
|
|
283
|
+
`./scripts/publish.sh --prepare`.
|
|
284
|
+
|
|
285
|
+
3. Tag the release commit as `v<version>`, push the tag, and create a matching
|
|
286
|
+
GitHub Release. PyPI does not require a tag, but it records which source was
|
|
287
|
+
published.
|
|
288
|
+
4. Install the published version in a clean environment and run
|
|
289
|
+
`wpsync --version` before announcing it.
|
|
290
|
+
|
|
291
|
+
PyPI never lets a published version be replaced. If publication fails after
|
|
292
|
+
PyPI accepted either artifact, make another commit (an empty commit is enough)
|
|
293
|
+
and publish the new version.
|