python-substack 0.8.0__tar.gz → 0.9.0__tar.gz

{python_substack-0.8.0 → python_substack-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-substack
-Version: 0.8.0
+Version: 0.9.0
 Summary: Write and safely manage Substack drafts from Markdown with Python, CLI, and MCP.
 License: MIT
 License-File: LICENSE
@@ -94,6 +94,7 @@ Substack result:
 - Set audience, comment permissions, SEO metadata, slug, sections, and tags.
 - List and inspect publications and drafts.
 - Export drafts to loss-aware Markdown backups without server writes.
+- Safely update drafts from Markdown, preserving unsupported editor widgets by default.
 - Schedule, unschedule, publish, and delete drafts with explicit safeguards.
 - Use stable JSON envelopes in scripts and automation.
 - Authenticate with browser cookies or email and password.
@@ -145,6 +146,7 @@ substack publications list
 substack drafts list --limit 10
 substack drafts get 12345
 substack drafts export 12345 --output backup.md
+substack drafts update 12345 revised-post.md --dry-run --yes
 substack --publication-url https://example.substack.com drafts list
 ```
 
@@ -217,6 +219,17 @@ print(backup["markdown"])
 print(backup["unsupported_nodes"])
 ```
 
+Review a Markdown update before writing it, then update deliberately:
+
+```python
+result = api.update_draft_from_markdown(12345, "# Revised draft", dry_run=True)
+result = api.update_draft_from_markdown(12345, "# Revised draft")
+```
+
+Unsupported editor widgets exported as `python-substack-node:v1` markers are
+preserved by default. An update refuses to remove or alter them unless
+`allow_unsupported_change=True` is explicitly passed.
+
 For direct ProseMirror node construction, see the
 [low-level Python API](docs/low-level-api.md). YAML workflows are documented in
 [YAML drafts](docs/yaml.md).
@@ -269,11 +282,12 @@ See [MCP server](docs/mcp.md) for the tool list and safety notes.
 - [Python SDK](docs/python-sdk.md)
 - [Authentication](docs/authentication.md)
 - [Markdown reference](docs/markdown.md)
+- [Draft backup and safe updates](docs/cli.md)
 - [Legacy CLI commands](docs/legacy-cli.md)
 - [Low-level Python API](docs/low-level-api.md)
 - [YAML drafts](docs/yaml.md)
 - [MCP server](docs/mcp.md)
-- [Gemini CLI with Vertex AI](docs/gemini-vertex-ai.md)
+- [Agent workflow](docs/agents.md)
 - [Safety and publishing behavior](docs/safety.md)
 - [Troubleshooting](docs/troubleshooting.md)
 - [Compatibility policy](docs/compatibility.md)

{python_substack-0.8.0 → python_substack-0.9.0}/README.md

@@ -58,6 +58,7 @@ Substack result:
 - Set audience, comment permissions, SEO metadata, slug, sections, and tags.
 - List and inspect publications and drafts.
 - Export drafts to loss-aware Markdown backups without server writes.
+- Safely update drafts from Markdown, preserving unsupported editor widgets by default.
 - Schedule, unschedule, publish, and delete drafts with explicit safeguards.
 - Use stable JSON envelopes in scripts and automation.
 - Authenticate with browser cookies or email and password.
@@ -109,6 +110,7 @@ substack publications list
 substack drafts list --limit 10
 substack drafts get 12345
 substack drafts export 12345 --output backup.md
+substack drafts update 12345 revised-post.md --dry-run --yes
 substack --publication-url https://example.substack.com drafts list
 ```
 
@@ -181,6 +183,17 @@ print(backup["markdown"])
 print(backup["unsupported_nodes"])
 ```
 
+Review a Markdown update before writing it, then update deliberately:
+
+```python
+result = api.update_draft_from_markdown(12345, "# Revised draft", dry_run=True)
+result = api.update_draft_from_markdown(12345, "# Revised draft")
+```
+
+Unsupported editor widgets exported as `python-substack-node:v1` markers are
+preserved by default. An update refuses to remove or alter them unless
+`allow_unsupported_change=True` is explicitly passed.
+
 For direct ProseMirror node construction, see the
 [low-level Python API](docs/low-level-api.md). YAML workflows are documented in
 [YAML drafts](docs/yaml.md).
@@ -233,11 +246,12 @@ See [MCP server](docs/mcp.md) for the tool list and safety notes.
 - [Python SDK](docs/python-sdk.md)
 - [Authentication](docs/authentication.md)
 - [Markdown reference](docs/markdown.md)
+- [Draft backup and safe updates](docs/cli.md)
 - [Legacy CLI commands](docs/legacy-cli.md)
 - [Low-level Python API](docs/low-level-api.md)
 - [YAML drafts](docs/yaml.md)
 - [MCP server](docs/mcp.md)
-- [Gemini CLI with Vertex AI](docs/gemini-vertex-ai.md)
+- [Agent workflow](docs/agents.md)
 - [Safety and publishing behavior](docs/safety.md)
 - [Troubleshooting](docs/troubleshooting.md)
 - [Compatibility policy](docs/compatibility.md)

{python_substack-0.8.0 → python_substack-0.9.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "python-substack"
-version = "0.8.0"
+version = "0.9.0"
 description = "Write and safely manage Substack drafts from Markdown with Python, CLI, and MCP."
 authors = ["Paolo Mazza <mazzapaolo2019@gmail.com>"]
 license = "MIT"

{python_substack-0.8.0 → python_substack-0.9.0}/substack/__init__.py

@@ -3,7 +3,7 @@
 __author__ = "Paolo Mazza"
 __email__ = "mazzapaolo2019@gmail.com"
 __license__ = "MIT License"
-__version__ = "0.8.0"
+__version__ = "0.9.0"
 __url__ = "https://github.com/ma2za/python-substack"
 __download_url__ = "https://pypi.python.org/pypi/python-substack"
 __description__ = (

{python_substack-0.8.0 → python_substack-0.9.0}/substack/api.py

@@ -21,6 +21,19 @@ logger = logging.getLogger(__name__)
 __all__ = ["Api"]
 
 
+def _image_attrs(document):
+    images = []
+    if isinstance(document, dict):
+        if document.get("type") == "image2" and isinstance(document.get("attrs"), dict):
+            images.append(document["attrs"])
+        for value in document.values():
+            images.extend(_image_attrs(value))
+    elif isinstance(document, list):
+        for value in document:
+            images.extend(_image_attrs(value))
+    return images
+
+
 class Api:
     """
 
@@ -432,7 +445,10 @@ class Api:
             f"{self.publication_url}/drafts",
             params={"filter": filter, "offset": offset, "limit": limit},
         )
-        return Api._handle_response(response=response)
+        drafts = Api._handle_response(response=response)
+        if isinstance(drafts, dict) and isinstance(drafts.get("posts"), list):
+            return drafts["posts"]
+        return drafts
 
     def get_draft(self, draft_id):
         """
@@ -479,6 +495,7 @@ class Api:
         tags=None,
         dry_run: bool = False,
         allow_unsupported_change: bool = False,
+        allow_image_replacement: bool = False,
     ) -> dict:
         """
         Update an existing draft body from Markdown, with optional metadata changes.
@@ -511,6 +528,29 @@ class Api:
         )
         post.from_markdown(markdown, api=self)
 
+        remote_images = _image_attrs(draft_body)
+        submitted_images = _image_attrs(post.draft_body)
+        for submitted in submitted_images:
+            matches = [
+                image
+                for image in remote_images
+                if image.get("src") == submitted.get("src")
+            ]
+            if len(matches) == 1:
+                source, alt, href = (
+                    submitted.get("src"),
+                    submitted.get("alt"),
+                    submitted.get("href"),
+                )
+                submitted.update(matches[0])
+                submitted.update(
+                    {"src": source, "alt": alt, "href": href, "isProcessing": False}
+                )
+            elif not allow_image_replacement:
+                raise ValueError(
+                    "Refusing to update: image cannot be matched uniquely; set allow_image_replacement=True to proceed."
+                )
+
         _, submitted_unsupported = document_to_markdown(post.draft_body)
 
         if not allow_unsupported_change:

{python_substack-0.8.0 → python_substack-0.9.0}/substack/cli.py

@@ -312,6 +312,8 @@ def _drafts_create(api, args):
 def _drafts_update(api, args):
     if args.allow_unsupported_change and not args.yes:
         raise CLIUsageError("--yes is required when using --allow-unsupported-change")
+    if args.allow_image_replacement and not args.yes:
+        raise CLIUsageError("--yes is required when using --allow-image-replacement")
 
     if not args.yes and (args.json_output or not sys.stdin.isatty()):
         raise CLIUsageError("--yes is required in non-interactive or JSON mode")
@@ -351,6 +353,7 @@ def _drafts_update(api, args):
         tags=args.tags,
         dry_run=args.dry_run,
         allow_unsupported_change=args.allow_unsupported_change,
+        allow_image_replacement=args.allow_image_replacement,
     )
 
     if args.json_output:
@@ -513,6 +516,7 @@ def _build_parser():
     drafts_update.add_argument("--tag", action="append", dest="tags", metavar="TAG")
     drafts_update.add_argument("--dry-run", action="store_true")
     drafts_update.add_argument("--allow-unsupported-change", action="store_true")
+    drafts_update.add_argument("--allow-image-replacement", action="store_true")
     drafts_update.add_argument("--yes", action="store_true")
     drafts_update.set_defaults(handler=_drafts_update)
 

{python_substack-0.8.0 → python_substack-0.9.0}/substack/mdexport.py

@@ -57,6 +57,21 @@ def _marker(node, unsupported):
     return f"<!-- python-substack-node:v1 {encoded} -->"
 
 
+def _image_marker(attrs):
+    preserved = {
+        key: value
+        for key, value in attrs.items()
+        if key not in {"src", "alt", "href", "isProcessing"}
+    }
+    if not preserved:
+        return ""
+    payload = json.dumps(
+        preserved, ensure_ascii=False, separators=(",", ":"), sort_keys=True
+    ).encode("utf-8")
+    encoded = base64.urlsafe_b64encode(payload).decode("ascii").rstrip("=")
+    return f"\n<!-- python-substack-image:v1 {encoded} -->"
+
+
 def _require_dict(node, context):
     if not isinstance(node, dict):
         raise ValueError(f"Malformed draft body: {context} must be an object")
@@ -247,7 +262,7 @@ def _render_image(node, unsupported):
         if not isinstance(href, str):
             return _marker(node, unsupported)
         image_markdown = f"[{image_markdown}]({_escape_destination(href)})"
-    return image_markdown
+    return image_markdown + _image_marker(attrs)
 
 
 def _render_footnote(node, unsupported):

{python_substack-0.8.0 → python_substack-0.9.0}/substack/mdrender.py

@@ -21,7 +21,9 @@ import base64
 import copy
 import json
 import re
+from pathlib import Path
 from typing import Dict, List, Optional
+from urllib.parse import unquote, urlsplit
 
 from markdown_it import MarkdownIt
 from markdown_it.tree import SyntaxTreeNode
@@ -43,22 +45,24 @@ _MARK_FOR = {
 }
 
 
-def parse_node_marker(comment_content: str) -> dict | None:
+def parse_node_marker(comment_content: str) -> dict | None:
     """
     Parse a python-substack-node:v1 comment marker and return the parsed JSON dictionary.
-    
+
     If it is not a python-substack-node:v1 marker, returns None.
     If it is an attempted marker but is corrupt/malformed, raises ValueError.
     """
     clean = comment_content.strip()
-    match = re.match(r"^<!--\s*python-substack-node:v1\s+([A-Za-z0-9_-]+=*)\s*-->$", clean)
+    match = re.match(
+        r"^<!--\s*python-substack-node:v1\s+([A-Za-z0-9_-]+=*)\s*-->$", clean
+    )
     if not match:
         if "python-substack-node:v1" in clean:
             raise ValueError("Corrupt marker format")
         return None
-    
+
     encoded = match.group(1)
-    
+
     try:
         padding = len(encoded) % 4
         if padding:
@@ -84,7 +88,29 @@ def parse_node_marker(comment_content: str) -> dict | None:
     if not isinstance(node_type, str) or not node_type:
         raise ValueError("Marker payload has missing or empty 'type'")
 
-    return data
+    return data
+
+
+def parse_image_marker(comment_content: str) -> dict | None:
+    clean = comment_content.strip()
+    match = re.match(
+        r"^<!--\s*python-substack-image:v1\s+([A-Za-z0-9_-]+=*)\s*-->$", clean
+    )
+    if not match:
+        if "python-substack-image:v1" in clean:
+            raise ValueError("Corrupt image marker format")
+        return None
+    encoded = match.group(1)
+    encoded += "=" * (-len(encoded) % 4)
+    try:
+        attrs = json.loads(base64.urlsafe_b64decode(encoded.encode("ascii")))
+    except Exception as exc:
+        raise ValueError("Invalid image marker") from exc
+    if not isinstance(attrs, dict) or any(
+        key in {"src", "alt", "href", "isProcessing"} for key in attrs
+    ):
+        raise ValueError("Invalid image marker attributes")
+    return attrs
 
 
 def _make_parser() -> MarkdownIt:
@@ -173,13 +199,28 @@ def _only_image(inline: SyntaxTreeNode) -> Optional[SyntaxTreeNode]:
 
 def _captioned_image(img: SyntaxTreeNode, api) -> Dict:
     src = img.attrs.get("src", "")
-    if src.startswith("/"):
-        src = src[1:]
-    if api is not None and not src.startswith("http"):
+    if api is not None and (
+        urlsplit(src).scheme.lower() not in ("http", "https")
+        and not src.startswith("//")
+    ):
+        # Markdown destinations encode spaces and non-ASCII characters as URLs.
+        path = Path(unquote(src)).expanduser()
+        if not path.is_file() and src.startswith("/"):
+            # Preserve legacy root-relative asset paths only when they resolve
+            # to a real file; an existing absolute path always takes precedence.
+            relative = Path(unquote(src[1:]))
+            if relative.is_file():
+                path = relative
+        if not path.is_file():
+            raise FileNotFoundError(f"Local image file not found: {path}")
         try:
-            src = api.get_image(src).get("url")
-        except Exception:
-            pass
+            uploaded = api.get_image(str(path))
+            url = uploaded.get("url")
+            if not isinstance(url, str) or not url.startswith(("https://", "http://")):
+                raise ValueError("Upload did not return an HTTP image URL")
+        except Exception as exc:
+            raise ValueError(f"Failed to upload local image: {path}") from exc
+        src = url
     # markdown-it stores the image alt text as the node's content, not in attrs.
     alt = img.content or img.attrs.get("alt") or None
     # Standard markdown image title `![alt](src "caption")` maps to Substack's caption node.
@@ -292,10 +333,18 @@ def markdown_to_doc(markdown_content: str, api=None) -> List[Dict]:
 
     ctx: Dict = {"order": []}
     out: List[Dict] = []
-    for node in tree.children:
-        if node.type == "footnote_block":
-            continue
-        out.extend(_render_block(node, api, ctx))
+    for node in tree.children:
+        if node.type == "footnote_block":
+            continue
+        if node.type == "html_block":
+            attrs = parse_image_marker(node.content)
+            if attrs is not None:
+                if not out or out[-1].get("type") != "captionedImage":
+                    raise ValueError("Image marker must immediately follow an image")
+                out[-1]["content"][0]["attrs"].update(attrs)
+                out[-1]["content"][0]["attrs"]["isProcessing"] = False
+                continue
+        out.extend(_render_block(node, api, ctx))
 
     # Emit one footnote block per reference, in anchor order, numbered to match.
     for number, footnote_id in enumerate(ctx["order"], start=1):