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.

@@ -0,0 +1,11 @@
1
+ __pycache__/
2
+ .pytest_cache/
3
+ .ruff_cache/
4
+ *.egg-info/
5
+ build/
6
+ dist/
7
+ venv/
8
+ .venv/
9
+
10
+ .DS_Store
11
+ *.bak
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
+ ![Sunset](images/sunset.jpg "Caption"){.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
+ ![Sunset](images/sunset.jpg "Caption"){.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.