article 0.1.4__tar.gz → 0.1.6__tar.gz

{article-0.1.4 → article-0.1.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: article
-Version: 0.1.4
+Version: 0.1.6
 Summary: Tools to semi-automate the publication of articles
 Project-URL: Homepage, https://github.com/thorwhalen/article
 Project-URL: Repository, https://github.com/thorwhalen/article
@@ -26,6 +26,7 @@ Requires-Dist: pyyaml
 Provides-Extra: completion
 Requires-Dist: argcomplete; extra == 'completion'
 Provides-Extra: dev
+Requires-Dist: pillow; extra == 'dev'
 Requires-Dist: pytest-cov>=4.0; extra == 'dev'
 Requires-Dist: pytest>=7.0; extra == 'dev'
 Requires-Dist: python-substack<0.11,>=0.10; extra == 'dev'
@@ -33,6 +34,8 @@ Requires-Dist: ruff>=0.1.0; extra == 'dev'
 Provides-Extra: docs
 Requires-Dist: sphinx-rtd-theme>=1.0; extra == 'docs'
 Requires-Dist: sphinx>=6.0; extra == 'docs'
+Provides-Extra: images
+Requires-Dist: pillow; extra == 'images'
 Provides-Extra: substack
 Requires-Dist: markdown-it-py>=3; extra == 'substack'
 Requires-Dist: mdit-py-plugins>=0.4; extra == 'substack'
@@ -77,7 +80,7 @@ Image paths resolve against the Markdown file's directory. Before anything is up
 
 | Construct | Why | What to do |
 |---|---|---|
-| A table | Substack has no table node | `--tables code` keeps it as a monospace code block; or render it to an image (in Python, pass `tables=` a function returning the image Markdown) |
+| A table | Substack has no table node | `--tables code` keeps it as a monospace code block; `--tables image` renders it to a PNG (needs `pip install 'article[images]'`); in Python, `tables=` also takes a function returning the image Markdown |
 | An image in a paragraph with text | the converter keeps only the alt text | give the image its own paragraph; caption goes in the title slot |
 | A missing local image | nothing to upload | fix the path |
 | A raw HTML block | the converter drops it | rewrite it in Markdown |
@@ -88,6 +91,8 @@ Image paths resolve against the Markdown file's directory. Before anything is up
 article draft-substack essay.md --dry-run          # what survives, no credentials needed
 article draft-substack essay.md                    # create the draft; prints its edit link
 article draft-substack essay.md --tables code      # keep tables as code blocks
+article draft-substack essay.md --update           # rewrite the draft the last run created (refuses if you edited it in Substack; --overwrite-edits to replace those edits)
+article syndicate-secondary essay.md               # refused until the Substack post is live (--allow-unpublished to override)
 ```
 
 The draft's future public URL (`<publication>/p/<slug>`) is recorded as the canonical URL, so `syndicate-secondary` can point the other platforms at it.

{article-0.1.4 → article-0.1.6}/README.md

@@ -36,7 +36,7 @@ Image paths resolve against the Markdown file's directory. Before anything is up
 
 | Construct | Why | What to do |
 |---|---|---|
-| A table | Substack has no table node | `--tables code` keeps it as a monospace code block; or render it to an image (in Python, pass `tables=` a function returning the image Markdown) |
+| A table | Substack has no table node | `--tables code` keeps it as a monospace code block; `--tables image` renders it to a PNG (needs `pip install 'article[images]'`); in Python, `tables=` also takes a function returning the image Markdown |
 | An image in a paragraph with text | the converter keeps only the alt text | give the image its own paragraph; caption goes in the title slot |
 | A missing local image | nothing to upload | fix the path |
 | A raw HTML block | the converter drops it | rewrite it in Markdown |
@@ -47,6 +47,8 @@ Image paths resolve against the Markdown file's directory. Before anything is up
 article draft-substack essay.md --dry-run          # what survives, no credentials needed
 article draft-substack essay.md                    # create the draft; prints its edit link
 article draft-substack essay.md --tables code      # keep tables as code blocks
+article draft-substack essay.md --update           # rewrite the draft the last run created (refuses if you edited it in Substack; --overwrite-edits to replace those edits)
+article syndicate-secondary essay.md               # refused until the Substack post is live (--allow-unpublished to override)
 ```
 
 The draft's future public URL (`<publication>/p/<slug>`) is recorded as the canonical URL, so `syndicate-secondary` can point the other platforms at it.

{article-0.1.4 → article-0.1.6}/article/__init__.py

@@ -45,6 +45,7 @@ from .base import (
     ArticleError,
     ArticleValidationError,
     CanonicalUrlMissing,
+    CanonicalUrlNotLive,
     ConfigError,
     Phase,
     PlatformName,
@@ -122,6 +123,7 @@ __all__ = [
     "AdapterError",
     "UnknownPlatformError",
     "CanonicalUrlMissing",
+    "CanonicalUrlNotLive",
     # state
     "JsonStateStore",
     "default_state_store",

{article-0.1.4 → article-0.1.6}/article/__main__.py

@@ -70,9 +70,14 @@ def syndicate_secondary(
     env_file: Optional[str] = None,
     state_path: Optional[str] = None,
     platforms: Optional[str] = None,
+    allow_unpublished: bool = False,
     json_out: bool = False,
 ):
-    """Phase 2 — syndicate to secondary platforms, injecting canonical_url for SEO."""
+    """Phase 2 — syndicate to secondary platforms, injecting canonical_url for SEO.
+
+    Refused while the Substack post is still a draft (its URL would be a 404), unless
+    ``allow_unpublished``.
+    """
     settings, article, store = _prepare(
         article_path, env_file=env_file, state_path=state_path
     )
@@ -80,7 +85,11 @@ def syndicate_secondary(
     try:
         summary = run_sync(
             _syndicate_secondary(
-                article, settings=settings, store=store, platforms=selected
+                article,
+                settings=settings,
+                store=store,
+                platforms=selected,
+                allow_unpublished=allow_unpublished,
             )
         )
     except ArticleError as e:
@@ -105,22 +114,41 @@ def draft_substack(
     state_path: Optional[str] = None,
     tables: Optional[str] = None,
     dry_run: bool = False,
+    update: bool = False,
+    overwrite_edits: bool = False,
     json_out: bool = False,
 ):
-    """Create an UNPUBLISHED Substack draft from a Markdown file; never publishes."""
+    """Create an UNPUBLISHED Substack draft from a Markdown file; never publishes.
+
+    With ``update``, rewrite the draft this article's earlier run created (from the
+    state file) instead of creating another one.
+    """
     settings, article, store = _prepare(
         article_path, env_file=env_file, state_path=state_path
     )
     config = article.platforms.substack or SubstackConfig()
     if tables is not None:
         config = config.model_copy(update={"tables": tables})
+    earlier = store.get(article.slug, {}).get("primary", {}).get("detail", {})
+    if update:
+        if not earlier.get("draft_id"):
+            raise cw.CommandError(
+                f"--update: no earlier draft is recorded for {article.slug!r} in the "
+                f"state file; run once without --update first"
+            )
+        config = config.model_copy(
+            update={
+                "draft_id": earlier["draft_id"],
+                "expected_revision": earlier.get("revision"),
+                "overwrite_edits": overwrite_edits,
+            }
+        )
     try:
         if dry_run:
             report = _substack.dry_run(article, config=config)
             return json.dumps(report, indent=2) if json_out else _render_dry_run(report)
         platforms = article.platforms.model_copy(update={SUBSTACK: config})
         article = article.model_copy(update={"platforms": platforms})
-        earlier = store.get(article.slug, {}).get("primary", {}).get("detail", {})
         summary = run_sync(_publish_primary(article, settings=settings, store=store))
     except ArticleError as e:
         raise cw.CommandError(str(e)) from e
@@ -131,7 +159,7 @@ def draft_substack(
     detail = summary.by_platform[SUBSTACK].detail
     lines = [summary.render(), f"Edit the draft: {detail.get('edit_url')}"]
     lines += [f"  warning: {w}" for w in detail.get("warnings", ())]
-    if earlier.get("edit_url"):
+    if earlier.get("edit_url") and not update:
         lines.append(
             f"Note: an earlier draft of this article is still on Substack "
             f"({earlier['edit_url']}); delete it if this one replaces it."
@@ -149,11 +177,21 @@ _dispatch_config = {
     command: {"article_path": {"help": "Path to the article JSON file"}}
     for command in ("publish-primary", "syndicate-secondary")
 }
+_dispatch_config["syndicate-secondary"]["allow_unpublished"] = {
+    "help": "Syndicate even though the Substack post is still a draft (its URL is a 404)"
+}
 _dispatch_config["draft-substack"] = {
     "article_path": {"help": "Path to the essay Markdown file (or article JSON)"},
     "tables": {
-        "choices": ["error", "code"],
-        "help": "Markdown tables: refuse (error, the default) or keep as code blocks",
+        "choices": ["error", "code", "image"],
+        "help": "Markdown tables: refuse (error, the default), keep as code blocks, "
+        "or render to an image (needs article[images])",
+    },
+    "update": {
+        "help": "Rewrite the draft an earlier run created instead of making a new one"
+    },
+    "overwrite_edits": {
+        "help": "With --update: replace edits made in the Substack editor since the last run"
     },
     "dry_run": {"help": "Check and convert only; no credentials, nothing sent"},
 }

{article-0.1.4 → article-0.1.6}/article/adapters/substack.py

@@ -14,19 +14,30 @@ that publishes. Review the draft in the Substack editor and publish it there.
 Before anything is uploaded, :func:`preflight` checks the Markdown for what
 the converter would lose silently, and refuses it with every problem listed:
 
-- **tables** (Substack has no table node): refused by default, or kept as a
-  monospace code block with ``tables="code"``, or replaced by whatever a
-  callable returns (e.g. a rendered image), never dropped;
+- **tables** (Substack has no table node): refused by default, kept as a
+  monospace code block with ``tables="code"``, rendered to a PNG with
+  ``tables="image"`` (needs Pillow: ``pip install 'article[images]'``), or replaced
+  by whatever a callable returns, never dropped;
 - an **image sharing a paragraph with text** (the converter keeps only its
   alt text): put the image in its own paragraph, caption in the title slot;
 - a **local image that does not exist** (paths resolve against the article's
-  ``assets_dir``, the source file's directory);
+  ``assets_dir``, the source file's directory) or that sits **inside a list, quote
+  or footnote** (Substack's editor is not known to accept those; move it to the top
+  level). Local image paths are rewritten to absolute ones, so conversion never
+  depends on, or changes, the process's working directory;
 - a **raw HTML block** (the converter drops it).
 
 The result's ``url`` is the post's public address once published
 (``<publication>/p/<slug>``), which the engine records as the canonical URL;
 ``detail["edit_url"]`` opens the draft in the editor.
 
+**Updating in place.** With ``config.draft_id`` set (the CLI's ``--update`` fills it
+from the state store), the existing draft is rewritten with python-substack's
+``update_draft_from_markdown`` instead of creating a new one. The draft's revision
+(recorded when it was created or last updated) guards against clobbering edits made
+in Substack's editor: a changed draft is refused unless ``config.overwrite_edits``.
+The title is not updated in place.
+
 The client is a seam: pass ``api=`` (anything with python-substack's ``Api``
 methods) to :func:`create_substack_draft`; tests pass a fake.
 """
@@ -34,14 +45,15 @@ methods) to :func:`create_substack_draft`; tests pass a fake.
 from __future__ import annotations
 
 import asyncio
-import os
+import hashlib
+import json
 import re
-import threading
+import struct
+import tempfile
 from collections import Counter
-from contextlib import contextmanager
 from pathlib import Path
 from typing import Any, Callable, Iterator, Literal, Mapping, Optional, Union
-from urllib.parse import unquote, urlsplit
+from urllib.parse import quote, unquote, urlsplit
 
 from ..base import SUBSTACK, AdapterError, PublishResult
 from ..config import Article, SubstackConfig
@@ -52,7 +64,7 @@ _log = get_logger()
 
 #: How a Markdown table is handled: refuse it, keep it as a code block, or
 #: replace it with the Markdown a callable returns (e.g. an image reference).
-TablePolicy = Union[Literal["error", "code"], Callable[[str], str]]
+TablePolicy = Union[Literal["error", "code", "image"], Callable[[str], str]]
 
 _INSTALL_HINT = "install the Substack extra: pip install 'article[substack]'"
 _AUTH_HINT = (
@@ -94,6 +106,61 @@ def _code_table(table_markdown: str) -> str:
     return f"```\n{table_markdown.rstrip()}\n```\n"
 
 
+def _split_row(line: str) -> list[str]:
+    cells = re.split(r"(?<!\\)\|", line.strip().strip("|"))
+    return [c.strip().replace("\\|", "|") for c in cells]
+
+
+def render_table_image(
+    table_markdown: str, *, out_dir: Optional[str] = None, scale: int = 2
+) -> str:
+    """Render a Markdown table to a PNG and return the Markdown image that shows it.
+
+    The file name is the content hash, so re-running reuses the file. Needs Pillow.
+    ``out_dir`` defaults to a folder under the system temp directory.
+    """
+    try:
+        from PIL import Image, ImageDraw, ImageFont
+    except ImportError as e:
+        raise AdapterError(
+            "substack: tables='image' needs Pillow: pip install 'article[images]'"
+        ) from e
+    rows = [
+        _split_row(line)
+        for line in table_markdown.strip().splitlines()
+        if not re.fullmatch(r"\s*\|?[\s:|-]+\|?\s*", line) or "-" not in line
+    ]
+    width = max(len(r) for r in rows)
+    rows = [r + [""] * (width - len(r)) for r in rows]
+    font = ImageFont.load_default(size=14 * scale)
+    pad = 6 * scale
+    probe = ImageDraw.Draw(Image.new("RGB", (1, 1)))
+    col_w = [
+        max(probe.textlength(row[c], font=font) for row in rows) + 2 * pad
+        for c in range(width)
+    ]
+    row_h = int(14 * scale * 1.4) + 2 * pad
+    image = Image.new("RGB", (int(sum(col_w)) + 1, row_h * len(rows) + 1), "white")
+    draw = ImageDraw.Draw(image)
+    for r, row in enumerate(rows):
+        x = 0.0
+        for c, cell in enumerate(row):
+            box = (x, r * row_h, x + col_w[c], (r + 1) * row_h)
+            if r == 0:
+                draw.rectangle(box, fill="#eeeeee")
+            draw.rectangle(box, outline="#999999")
+            draw.text((x + pad, r * row_h + pad), cell, fill="black", font=font)
+            x += col_w[c]
+    folder = (
+        Path(out_dir) if out_dir else Path(tempfile.gettempdir()) / "article-tables"
+    )
+    folder.mkdir(parents=True, exist_ok=True)
+    digest = hashlib.sha256(table_markdown.encode("utf-8")).hexdigest()[:16]
+    path = folder / f"table-{digest}.png"
+    image.save(path)
+    return f"![table]({quote(str(path))})\n"
+
+
 def _replace_tables(
     markdown: str, tokens: list, policy: TablePolicy, problems: list[str]
 ) -> str:
@@ -103,10 +170,11 @@ def _replace_tables(
         for t in tables:
             problems.append(
                 f"{_where(t, lines)}: a table (Substack has no table; pass "
-                f"tables='code' to keep it as a code block, or render it to an image)"
+                f"tables='code' to keep it as a code block, or tables='image' to "
+                f"render it to a picture)"
             )
         return markdown
-    render = _code_table if policy == "code" else policy
+    render = {"code": _code_table, "image": render_table_image}.get(policy, policy)
     if not callable(render):
         raise AdapterError(f"substack: unknown tables policy {policy!r}")
     for t in reversed(tables):  # bottom-up, so earlier line numbers stay valid
@@ -139,9 +207,20 @@ def _image_problems(
                 f"text, and Substack would keep only its alt text; give the image "
                 f'its own paragraph and put the caption in the title: ![alt](src "caption")'
             )
+        nested = (
+            in_paragraph
+            and _is_image_only(tok.children)
+            and (tokens[i - 1].level > 0 or not tok.map)
+        )
         for img in images:
             src = img.attrs.get("src", "")
-            if src.lower().startswith("data:"):
+            if nested and _is_local(src) and not src.lower().startswith("data:"):
+                yield (
+                    f"{line}: a local image inside a list, quote or footnote "
+                    f"({src}); Substack's editor is not known to accept those, so "
+                    f"move it to the top level"
+                )
+            elif src.lower().startswith("data:"):
                 yield f"{line}: an inline data: image cannot be uploaded; save it as a file"
             elif (
                 _is_local(src)
@@ -150,6 +229,38 @@ def _image_problems(
                 yield f"{line}: image file not found: {src} (looked in {base})"
 
 
+def _absolute_images(markdown: str, tokens: list, assets_dir: Optional[str]) -> str:
+    """Rewrite each top-level image-only paragraph's local source to an absolute path.
+
+    python-substack resolves local image paths against the process's working
+    directory; absolute paths make conversion independent of it. Only images that
+    passed :func:`_image_problems` (so image-only top-level paragraphs) get here.
+    """
+    base = Path(assets_dir) if assets_dir else Path.cwd()
+    lines = markdown.splitlines(keepends=True)
+    edits = []
+    for i, tok in enumerate(tokens):
+        if tok.type != "inline" or not tok.children or not tok.map:
+            continue
+        kids = [c for c in tok.children if c.type != "softbreak"]
+        image = next((c for c in kids if c.type == "image"), None)
+        if image is None or not _is_local(image.attrs.get("src", "")):
+            continue
+        if image.attrs["src"].lower().startswith("data:"):
+            continue
+        path = (base / Path(unquote(image.attrs["src"])).expanduser()).resolve()
+        alt = image.content.replace("]", "\\]")
+        title = image.attrs.get("title")
+        title_part = f' "{title.replace(chr(34), chr(92) + chr(34))}"' if title else ""
+        text = f"![{alt}](<{quote(str(path))}>{title_part})"
+        if kids[0].type == "link_open":
+            text = f"[{text}]({kids[0].attrs.get('href', '')})"
+        edits.append((tok.map, text + "\n"))
+    for (start, end), text in reversed(edits):  # bottom-up keeps line numbers valid
+        lines[start:end] = [text]
+    return "".join(lines)
+
+
 def _is_image_only(children: list) -> bool:
     kids = [c for c in children if c.type != "softbreak"]
     if len(kids) == 1 and kids[0].type == "image":
@@ -251,6 +362,7 @@ def preflight(
             f"substack: {len(problems)} problem(s) would lose content in the draft:\n"
             + "\n".join(f"  - {p}" for p in problems)
         )
+    markdown = _absolute_images(markdown, tokens, assets_dir)
     return markdown, list(_html_inline_warnings(tokens, lines))
 
 
@@ -259,26 +371,67 @@ def preflight(
 # --------------------------------------------------------------------------- #
 
 
-_CWD_LOCK = threading.Lock()
+def image_size(path: Union[str, Path]) -> Optional[tuple[int, int]]:
+    """``(width, height)`` of a PNG, GIF or JPEG file read from its header, else ``None``.
 
+    Stdlib only; other formats are measured with Pillow when it is installed.
+    """
+    with open(path, "rb") as f:
+        head = f.read(26)
+        if head[:8] == b"\x89PNG\r\n\x1a\n":
+            return struct.unpack(">II", head[16:24])
+        if head[:6] in (b"GIF87a", b"GIF89a"):
+            return struct.unpack("<HH", head[6:10])
+        if head[:2] == b"\xff\xd8":
+            f.seek(2)
+            while True:
+                marker = f.read(4)
+                if len(marker) < 4 or marker[0] != 0xFF:
+                    break
+                code, length = marker[1], struct.unpack(">H", marker[2:4])[0]
+                if 0xC0 <= code <= 0xCF and code not in (0xC4, 0xC8, 0xCC):
+                    h, w = struct.unpack(">HH", f.read(5)[1:5])
+                    return w, h
+                f.seek(length - 2, 1)
+    try:
+        from PIL import Image
+
+        with Image.open(path) as im:
+            return im.size
+    except Exception:
+        return None
 
-@contextmanager
-def _working_directory(path: Optional[str]) -> Iterator[None]:
-    """python-substack resolves local image paths against the cwd.
 
-    The cwd is process-wide, so conversions are serialized by a lock; a server
-    that converts concurrently should first make image paths absolute instead.
+class _MeasuringApi:
+    """Wraps a python-substack ``Api``, remembering the pixel size of each upload.
+
+    python-substack gives every image node a default 1456x819; the sizes
+    recorded here are written back by :func:`_apply_image_sizes`.
     """
-    if not path:
-        yield
-        return
-    with _CWD_LOCK:
-        previous = os.getcwd()
-        os.chdir(path)
-        try:
-            yield
-        finally:
-            os.chdir(previous)
+
+    def __init__(self, api: Any):
+        self._api = api
+        self.sizes: dict[str, tuple[int, int]] = {}
+
+    def get_image(self, path):
+        uploaded = self._api.get_image(path)
+        size = image_size(path)
+        if size and isinstance(uploaded, Mapping) and uploaded.get("url"):
+            self.sizes[uploaded["url"]] = size
+        return uploaded
+
+    def __getattr__(self, name):
+        return getattr(self._api, name)
+
+
+def _apply_image_sizes(node: Any, sizes: Mapping[str, tuple[int, int]]) -> None:
+    if isinstance(node, dict):
+        attrs = node.get("attrs")
+        if node.get("type") == "image2" and isinstance(attrs, dict):
+            if attrs.get("src") in sizes:
+                attrs["width"], attrs["height"] = sizes[attrs["src"]]
+        for child in node.get("content") or []:
+            _apply_image_sizes(child, sizes)
 
 
 def draft_document(
@@ -291,7 +444,8 @@ def draft_document(
 ) -> dict:
     """The draft payload python-substack posts (``draft_body`` is a JSON string).
 
-    With ``api=None`` nothing is uploaded and local image paths stay as they are.
+    ``markdown`` is what :func:`preflight` returned (its local image paths are
+    absolute). With ``api=None`` nothing is uploaded.
     """
     try:
         from substack.post import Post
@@ -303,9 +457,14 @@ def draft_document(
         user_id=user_id,
         audience=config.audience,
     )
-    with _working_directory(article.assets_dir):
-        post.from_markdown(markdown, api=api)
-    return post.get_draft()
+    measuring = _MeasuringApi(api) if api is not None else None
+    post.from_markdown(markdown, api=measuring)
+    draft = post.get_draft()
+    if measuring and measuring.sizes:
+        body = json.loads(draft["draft_body"])
+        _apply_image_sizes(body, measuring.sizes)
+        draft["draft_body"] = json.dumps(body)
+    return draft
 
 
 def make_substack_api(
@@ -423,6 +582,10 @@ def create_substack_draft(
         api = make_substack_api(secrets, publication_url=configured_url)
     publication = _publication_base(api, configured_url)
 
+    if config.draft_id is not None:
+        return _update_draft(
+            article, markdown, warnings, config=config, api=api, publication=publication
+        )
     draft = draft_document(
         article, markdown, config=config, api=api, user_id=api.get_user_id()
     )
@@ -465,12 +628,84 @@ def create_substack_draft(
         detail={
             "draft_id": draft_id,
             "edit_url": edit_url,
+            "revision": _revision_of(api, draft_id),
             "counts": summarize_document(draft),
             "warnings": warnings,
         },
     )
 
 
+def _revision_of(api: Any, draft_id: Any) -> Optional[dict]:
+    """The draft's current revision (python-substack's conflict-check fingerprint), or None."""
+    try:
+        from substack.revision import compute_draft_revision
+
+        return compute_draft_revision(api.get_draft(draft_id))
+    except (
+        Exception
+    ):  # an unreadable revision only makes the next update ask to overwrite
+        return None
+
+
+def _update_draft(
+    article: Article,
+    markdown: str,
+    warnings: list[str],
+    *,
+    config: SubstackConfig,
+    api: Any,
+    publication: str,
+) -> PublishResult:
+    """Rewrite the existing draft ``config.draft_id`` from ``markdown``, never publishing."""
+    draft_id = config.draft_id
+    edit_url = f"{publication}/publish/post/{draft_id}"
+    tags = coalesce(config.tags, article.tags)
+    try:
+        result = api.update_draft_from_markdown(
+            draft_id,
+            markdown,
+            subtitle=article.subtitle or "",
+            audience=config.audience,
+            search_engine_description=article.description,
+            slug=article.slug,
+            draft_section_id=config.section_id,
+            tags=list(tags) if tags else None,
+            expected_revision=config.expected_revision,
+            allow_image_replacement=True,  # the Markdown is the source of truth
+            allow_conflict=config.overwrite_edits,
+        )
+    except Exception as e:
+        hint = (
+            " (edited in Substack since the last run; pass overwrite_edits / "
+            "--overwrite-edits to replace those edits)"
+            if type(e).__name__ == "DraftConflictError"
+            else ""
+        )
+        raise AdapterError(
+            f"substack: updating draft {draft_id} ({edit_url}) failed: {e}{hint}"
+        ) from e
+    slug = ((result or {}).get("draft") or {}).get("slug") or article.slug
+    if slug != article.slug:
+        warnings.append(f"Substack changed the slug from {article.slug!r} to {slug!r}")
+    warnings.append(
+        "the title is not updated in place; change it in the Substack editor"
+    )
+    public_url = f"{publication}/p/{slug}"
+    return PublishResult.success(
+        SUBSTACK,
+        url=public_url,
+        status="draft",
+        canonical_url=public_url,
+        detail={
+            "draft_id": draft_id,
+            "edit_url": edit_url,
+            "updated_in_place": True,
+            "revision": _revision_of(api, draft_id),
+            "warnings": warnings,
+        },
+    )
+
+
 @register_adapter(SUBSTACK)
 async def publish(
     article: Article,

{article-0.1.4 → article-0.1.6}/article/base.py

@@ -286,3 +286,11 @@ class UnknownPlatformError(ArticleError, KeyError):
 
 class CanonicalUrlMissing(ArticleError):
     """Phase 2 was requested before phase 1 recorded a canonical_url."""
+
+
+class CanonicalUrlNotLive(ArticleError):
+    """Phase 2 was requested while the primary post is still an unpublished draft.
+
+    The recorded canonical URL is the post's *future* address, so syndicating now
+    would point other platforms at a 404.
+    """

{article-0.1.4 → article-0.1.6}/article/config.py

@@ -73,7 +73,14 @@ class SubstackConfig(_PlatformConfig):
     #: What to do with a Markdown table, which Substack cannot represent:
     #: ``"error"`` (refuse, naming every table) or ``"code"`` (keep it as a
     #: monospace code block). Never dropped silently.
-    tables: Literal["error", "code"] = "error"
+    tables: Literal["error", "code", "image"] = "error"
+    #: Update this existing draft in place instead of creating a new one (the CLI's
+    #: ``--update`` fills it, and ``expected_revision``, from the state store).
+    draft_id: Optional[int] = None
+    #: The draft's revision as last recorded; a draft edited since is refused.
+    expected_revision: Optional[dict] = None
+    #: Overwrite edits made in the Substack editor since ``expected_revision``.
+    overwrite_edits: bool = False
 
 
 class MediumConfig(_PlatformConfig):

{article-0.1.4 → article-0.1.6}/article/engine.py

@@ -35,6 +35,7 @@ from .base import (
     SECONDARY_PLATFORMS,
     AdapterError,
     CanonicalUrlMissing,
+    CanonicalUrlNotLive,
     Phase,
     PlatformName,
     PublishResult,
@@ -47,6 +48,21 @@ from .util import get_logger
 
 AdapterResolver = Callable[[str], PublishAdapter]
 
+#: Seconds the draft-liveness GET may take before the URL counts as not live.
+DFLT_LIVE_TIMEOUT = 10.0
+
+
+def url_is_live(url: str, *, timeout: float = DFLT_LIVE_TIMEOUT) -> bool:
+    """Whether one GET of ``url`` answers 2xx (redirects followed); any failure is False."""
+    import urllib.request
+
+    request = urllib.request.Request(url, headers={"User-Agent": "article-pipeline"})
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as response:
+            return 200 <= response.status < 300
+    except Exception:
+        return False
+
 
 @dataclass
 class PipelineEngine:
@@ -60,6 +76,9 @@ class PipelineEngine:
     settings: Settings
     store: MutableMapping
     resolve_adapter: AdapterResolver = field(default=get_adapter)
+    #: ``url -> bool``: is the canonical URL live? Asked in phase 2 only while the
+    #: primary post is still a draft. Defaults to one HTTP GET (:func:`url_is_live`).
+    is_live: Callable[[str], bool] = field(default=url_is_live)
 
     def __post_init__(self) -> None:
         self._log = get_logger()
@@ -118,11 +137,14 @@ class PipelineEngine:
         article: Article,
         *,
         platforms: Optional[Iterable[PlatformName]] = None,
+        allow_unpublished: bool = False,
     ) -> RunSummary:
         """Syndicate to each configured secondary, injecting the canonical URL.
 
         Raises :class:`~article.base.CanonicalUrlMissing` if phase 1 hasn't
-        recorded a canonical URL for this slug yet.
+        recorded a canonical URL for this slug yet, and
+        :class:`~article.base.CanonicalUrlNotLive` if the primary post is still a
+        draft whose URL does not resolve (``allow_unpublished=True`` skips the check).
         """
         canonical_url = self.store.get_canonical_url(article.slug)
         if not canonical_url:
@@ -131,6 +153,16 @@ class PipelineEngine:
                 f"Run `publish-primary` first so the SSOT URL exists."
             )
 
+        primary = self.store.get(article.slug, {}).get("primary", {})
+        if primary.get("status") == "draft" and not allow_unpublished:
+            if not self.is_live(canonical_url):
+                raise CanonicalUrlNotLive(
+                    f"The primary post for {article.slug!r} is still a draft: "
+                    f"{canonical_url} does not resolve yet, so syndicating now would "
+                    f"point other platforms at a 404. Publish it from the Substack "
+                    f"editor first (or pass allow_unpublished to override)."
+                )
+
         targets = self._secondary_targets(article, platforms)
         if not targets:
             self._log.warning("No secondary platforms configured for %r.", article.slug)
@@ -258,7 +290,10 @@ async def syndicate_secondary(
     settings: Optional[Settings] = None,
     store: Optional[MutableMapping] = None,
     platforms: Optional[Iterable[PlatformName]] = None,
+    allow_unpublished: bool = False,
 ) -> RunSummary:
     """Phase 2 facade: syndicate to secondaries with the canonical_url injected."""
     engine = build_engine(settings=settings, store=store)
-    return await engine.syndicate_secondary(article, platforms=platforms)
+    return await engine.syndicate_secondary(
+        article, platforms=platforms, allow_unpublished=allow_unpublished
+    )

{article-0.1.4 → article-0.1.6}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "article"
-version = "0.1.4"
+version = "0.1.6"
 description = "Tools to semi-automate the publication of articles"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -57,6 +57,8 @@ substack = [
     "markdown-it-py>=3",
     "mdit-py-plugins>=0.4",
 ]
+# tables="image": render Markdown tables to PNGs.
+images = ["pillow"]
 # Shell tab-completion for the CLI.
 completion = [
     "argcomplete",
@@ -66,6 +68,7 @@ dev = [
     "pytest-cov>=4.0",
     "ruff>=0.1.0",
     "python-substack>=0.10,<0.11",
+    "pillow",
 ]
 docs = [
     "sphinx>=6.0",

{article-0.1.4 → article-0.1.6}/tests/test_cli.py

@@ -82,7 +82,7 @@ def test_draft_substack_usage_line(subparsers):
     usage = " ".join(subparsers["draft-substack"].format_usage().split())
     assert usage == (
         "usage: article draft-substack [-h] [-e ENV_FILE] [-s STATE_PATH]"
-        " [-t {error,code}] [-d] [-j] article-path"
+        " [-t {error,code,image}] [-d] [-u] [-o] [-j] article-path"
     )
 
 
@@ -97,7 +97,7 @@ def test_draft_substack_usage_line(subparsers):
         (
             "syndicate-secondary",
             "usage: article syndicate-secondary [-h] [-e ENV_FILE] [-s STATE_PATH]"
-            " [-p PLATFORMS] [-j] article-path",
+            " [-p PLATFORMS] [-a] [-j] article-path",
         ),
     ],
 )

{article-0.1.4 → article-0.1.6}/tests/test_pipeline.py

@@ -93,6 +93,7 @@ def _engine(tmp_path, *, resolve_adapter=get_adapter) -> PipelineEngine:
         settings=settings,
         store=store,
         resolve_adapter=_with_fake_substack(resolve_adapter),
+        is_live=lambda url: True,  # no network: the draft counts as published
     )
 
 
@@ -256,3 +257,24 @@ def test_unconfigured_secondary_is_not_attempted(tmp_path):
     asyncio.run(engine.publish_primary(art))
     summary = asyncio.run(engine.syndicate_secondary(art))
     assert {r.platform for r in summary.results} == {MEDIUM}
+
+
+def test_phase2_refuses_while_the_substack_post_is_still_a_draft(tmp_path):
+    from article.base import CanonicalUrlNotLive
+
+    engine = _engine(tmp_path)
+    engine.is_live = lambda url: False
+    art = _article()
+    asyncio.run(engine.publish_primary(art))
+    with pytest.raises(CanonicalUrlNotLive, match="still a draft"):
+        asyncio.run(engine.syndicate_secondary(art))
+    summary = asyncio.run(engine.syndicate_secondary(art, allow_unpublished=True))
+    assert summary.canonical_url
+    engine.is_live = lambda url: True
+    assert asyncio.run(engine.syndicate_secondary(art)).canonical_url
+
+
+def test_url_is_live_is_false_for_an_unreachable_address():
+    from article.engine import url_is_live
+
+    assert url_is_live("http://127.0.0.1:9/never", timeout=0.2) is False

{article-0.1.4 → article-0.1.6}/tests/test_substack.py

@@ -15,6 +15,8 @@ import os
 import re
 import subprocess
 import sys
+from pathlib import Path
+from urllib.parse import unquote
 
 import pytest
 
@@ -362,3 +364,97 @@ def test_a_title_without_ascii_asks_for_a_slug(tmp_path):
     (tmp_path / "x.md").write_text("# 日本語\n\nx\n", encoding="utf-8")
     with pytest.raises(Exception, match="add a 'slug:'"):
         load_article(str(tmp_path / "x.md"))
+
+
+def test_uploaded_images_keep_their_real_pixel_size(tmp_path, fake_api):
+    import struct, zlib
+
+    def png(w, h):
+        def chunk(t, d):
+            return struct.pack(">I", len(d)) + t + d + struct.pack(">I", zlib.crc32(t + d))
+
+        raw = b"".join(b"\x00" + b"\x00\x00\x00" * w for _ in range(h))
+        return (
+            b"\x89PNG\r\n\x1a\n"
+            + chunk(b"IHDR", struct.pack(">IIBBBBB", w, h, 8, 2, 0, 0, 0))
+            + chunk(b"IDAT", zlib.compress(raw))
+            + chunk(b"IEND", b"")
+        )
+
+    (tmp_path / "wide.png").write_bytes(png(30, 10))
+    (tmp_path / "tall.png").write_bytes(png(7, 21))
+    (tmp_path / "a.md").write_text("# T\n\n![w](wide.png)\n\n![t](tall.png)\n")
+    create_substack_draft(load_article(str(tmp_path / "a.md")), api=fake_api)
+    sizes = [
+        (n["attrs"]["width"], n["attrs"]["height"])
+        for n in _of_type(_body(fake_api), "image2")
+    ]
+    assert sizes == [(30, 10), (7, 21)]
+
+
+# --------------------------------------------------------------------------- #1-#5 follow-ups
+
+
+def test_conversion_does_not_touch_the_working_directory(essay_dir, fake_api, monkeypatch):
+    """Local image paths become absolute during preflight, so no process-wide chdir."""
+    seen = []
+    real_chdir = os.chdir
+    monkeypatch.setattr(os, "chdir", lambda p: (seen.append(p), real_chdir(p)))
+    monkeypatch.chdir(essay_dir.parent)
+    seen.clear()
+    art = load_article(str(essay_dir / "essay.md"))
+    create_substack_draft(art, api=fake_api)
+    assert seen == []
+    assert fake_api.uploaded == [str((essay_dir / "images" / "fig 1.png").resolve())]
+
+
+def test_preflight_makes_local_image_paths_absolute(tmp_path, png_bytes):
+    (tmp_path / "a b.png").write_bytes(png_bytes)
+    md, _ = preflight('![alt](<a b.png> "cap")\n', assets_dir=str(tmp_path))
+    assert str(tmp_path.resolve()) in unquote(md) and 'a%20b.png' in md and '"cap"' in md
+
+
+def test_a_local_image_inside_a_list_is_refused(tmp_path, png_bytes):
+    (tmp_path / "a.png").write_bytes(png_bytes)
+    with pytest.raises(AdapterError, match="inside a list, quote or footnote"):
+        preflight("- ![alt](a.png)\n", assets_dir=str(tmp_path))
+    # a remote one is fine
+    preflight("- ![alt](https://example.com/a.png)\n", assets_dir=str(tmp_path))
+
+
+def test_tables_image_policy_renders_a_png(tmp_path):
+    pytest.importorskip("PIL")
+    md, _ = preflight(
+        "| a | b |\n|---|---|\n| 1 | 2 |\n", tables="image", assets_dir=str(tmp_path)
+    )
+    assert md.startswith("![table](")
+    path = Path(unquote(md[len("![table](") : md.index(")")]).strip("<>"))
+    assert path.is_file() and path.read_bytes()[:4] == b"\x89PNG"
+
+
+def test_a_draft_is_updated_in_place_with_its_revision_guard(essay_dir, fake_api):
+    calls = []
+    fake_api.update_draft_from_markdown = lambda draft_id, md, **kw: (
+        calls.append((draft_id, md, kw)) or {"draft": {"slug": "the-agile-religion"}}
+    )
+    art = load_article(str(essay_dir / "essay.md"))
+    config = SubstackConfig(draft_id=1234, expected_revision={"revision": "abc"})
+    result = create_substack_draft(art, config=config, api=fake_api)
+    ((draft_id, md, kwargs),) = calls
+    assert draft_id == 1234 and kwargs["expected_revision"] == {"revision": "abc"}
+    assert kwargs["allow_conflict"] is False and kwargs["slug"] == "the-agile-religion"
+    assert fake_api.posted == []  # no new draft
+    assert result.detail["updated_in_place"] and result.status == "draft"
+
+
+def test_an_edited_draft_is_refused_with_a_hint(essay_dir, fake_api):
+    class DraftConflictError(ValueError):
+        pass
+
+    def conflict(*args, **kwargs):
+        raise DraftConflictError("remote draft has changed")
+
+    fake_api.update_draft_from_markdown = conflict
+    art = load_article(str(essay_dir / "essay.md"))
+    with pytest.raises(AdapterError, match="overwrite_edits"):
+        create_substack_draft(art, config=SubstackConfig(draft_id=1), api=fake_api)

{article-0.1.4 → article-0.1.6}/tests/test_substack_live.py

@@ -8,6 +8,7 @@ one draft and deletes it again; it never publishes.
 
 from __future__ import annotations
 
+import json
 import os
 
 import pytest
@@ -29,6 +30,13 @@ pytestmark = pytest.mark.skipif(
 )
 
 
+def _image_nodes(node):
+    found = [node] if node.get("type") == "image2" else []
+    for child in node.get("content") or []:
+        found += _image_nodes(child)
+    return found
+
+
 def test_a_real_draft_keeps_footnotes_and_captions(tmp_path, png_bytes):
     (tmp_path / "fig.png").write_bytes(png_bytes)
     (tmp_path / "smoke.md").write_text(
@@ -47,6 +55,9 @@ def test_a_real_draft_keeps_footnotes_and_captions(tmp_path, png_bytes):
         draft = api.get_draft(result.detail["draft_id"])
         assert not draft.get("is_published")
         body = str(draft.get("draft_body"))
-        assert "footnote" in body and "A caption" in body and "substackcdn" in body
+        assert "footnote" in body and "A caption" in body
+        (image,) = _image_nodes(json.loads(draft["draft_body"]))
+        assert image["attrs"]["src"].startswith("https://")
+        assert (image["attrs"]["width"], image["attrs"]["height"]) == (1, 1)
     finally:
         api.delete_draft(result.detail["draft_id"])