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

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

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: python-substack
-Version: 0.8.0
+Version: 0.9.1
 Summary: Write and safely manage Substack drafts from Markdown with Python, CLI, and MCP.
-License: MIT
+License-Expression: MIT
 License-File: LICENSE
 Keywords: substack,substack-api,cli,newsletter,publishing,automation,mcp
 Author: Paolo Mazza
@@ -10,13 +10,11 @@ Author-email: mazzapaolo2019@gmail.com
 Requires-Python: >=3.10,<4.0
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
-Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Communications :: Email
 Classifier: Topic :: Internet :: WWW/HTTP
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
@@ -94,6 +92,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 +144,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 +217,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 +280,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.1}/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.1}/pyproject.toml

@@ -1,19 +1,13 @@
-[tool.poetry]
+[project]
 name = "python-substack"
-version = "0.8.0"
+version = "0.9.1"
 description = "Write and safely manage Substack drafts from Markdown with Python, CLI, and MCP."
-authors = ["Paolo Mazza <mazzapaolo2019@gmail.com>"]
-license = "MIT"
-packages = [
-    { include = "substack" },
-    { include = "substack_mcp" }
+authors = [
+    { name = "Paolo Mazza", email = "mazzapaolo2019@gmail.com" }
 ]
-
+license = "MIT"
 readme = "README.md"
-
-repository = "https://github.com/ma2za/python-substack"
-homepage = "https://github.com/ma2za/python-substack"
-
+requires-python = ">=3.10,<4.0"
 keywords = ["substack", "substack-api", "cli", "newsletter", "publishing", "automation", "mcp"]
 classifiers = [
     "Development Status :: 4 - Beta",
@@ -27,24 +21,38 @@ classifiers = [
     "Topic :: Internet :: WWW/HTTP",
     "Topic :: Software Development :: Libraries :: Python Modules"
 ]
+dependencies = [
+    "requests>=2.32.0,<3.0.0",
+    "python-dotenv>=1.2.1,<2.0.0",
+    "PyYAML>=6.0,<7.0",
+    "markdown-it-py>=3,<5",
+    "mdit-py-plugins>=0.5,<0.7"
+]
+
+[project.optional-dependencies]
+mcp = [
+    "fastmcp>=3.1.1,<5.0.0"
+]
 
-[tool.poetry.urls]
+[project.urls]
 "Documentation" = "https://ma2za.github.io/python-substack/"
 "Changelog" = "https://github.com/ma2za/python-substack/blob/main/CHANGELOG.md"
 "Issues" = "https://github.com/ma2za/python-substack/issues"
+"Homepage" = "https://github.com/ma2za/python-substack"
+"Repository" = "https://github.com/ma2za/python-substack"
 
-[tool.poetry.dependencies]
-python = "<4.0,>=3.10"
-
-requests = "^2.32.0"
-python-dotenv = "^1.2.1"
-PyYAML = "^6.0"
-markdown-it-py = ">=3,<5"
-mdit-py-plugins = ">=0.5,<0.7"
-fastmcp = { version = ">=3.1.1,<5.0.0", optional = true }
+[project.scripts]
+substack = "substack.cli:main"
+substack-auth-check = "substack.cli:auth_check"
+substack-publish-markdown = "substack.cli:publish_markdown"
+substack-publish-yaml = "substack.cli:publish_yaml"
+substack-mcp = "substack_mcp.mcp_server:main"
 
-[tool.poetry.extras]
-mcp = ["fastmcp"]
+[tool.poetry]
+packages = [
+    { include = "substack" },
+    { include = "substack_mcp" }
+]
 
 [tool.poetry.group.dev.dependencies]
 pytest = "^9.1.1"
@@ -56,13 +64,6 @@ markers = [
     "live: opt-in tests that call the live Substack service",
 ]
 
-[tool.poetry.scripts]
-substack = "substack.cli:main"
-substack-auth-check = "substack.cli:auth_check"
-substack-publish-markdown = "substack.cli:publish_markdown"
-substack-publish-yaml = "substack.cli:publish_yaml"
-substack-mcp = "substack_mcp.mcp_server:main"
-
 [build-system]
-requires = ["poetry-core>=1.0.0"]
+requires = ["poetry-core>=2.0.0"]
 build-backend = "poetry.core.masonry.api"

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

@@ -3,7 +3,7 @@
 __author__ = "Paolo Mazza"
 __email__ = "mazzapaolo2019@gmail.com"
 __license__ = "MIT License"
-__version__ = "0.8.0"
+__version__ = "0.9.1"
 __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.1}/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,10 +495,12 @@ 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.
         """
+        from substack import mdrender
         from substack.mdexport import document_to_markdown
         from substack.post import Post
 
@@ -500,6 +518,7 @@ class Api:
 
         _, remote_unsupported = document_to_markdown(draft_body)
 
+        image_markers = []
         post = Post(
             title=draft.get("title", ""),
             subtitle=(
@@ -509,7 +528,88 @@ class Api:
             audience=audience,
             write_comment_permissions=write_comment_permissions,
         )
-        post.from_markdown(markdown, api=self)
+        rendered = mdrender.markdown_to_doc(
+            markdown, api=self, track_markers=image_markers
+        )
+        post.draft_body["content"] = rendered
+
+        remote_images = _image_attrs(draft_body)
+        submitted_images = _image_attrs(post.draft_body)
+
+        consumed_remote_indices = set()
+
+        for submitted, marker in zip(submitted_images, image_markers):
+            if marker is not None and marker.get("version") == 2:
+                bound_src = marker["src"]
+                matched_idx = None
+                for idx, r_img in enumerate(remote_images):
+                    if (
+                        idx not in consumed_remote_indices
+                        and r_img.get("src") == bound_src
+                    ):
+                        matched_idx = idx
+                        break
+
+                if matched_idx is None:
+                    all_with_src = [
+                        idx
+                        for idx, r_img in enumerate(remote_images)
+                        if r_img.get("src") == bound_src
+                    ]
+                    if not all_with_src:
+                        raise ValueError(
+                            f"Refusing to update: stale image marker bound to '{bound_src}'."
+                        )
+                    else:
+                        raise ValueError(
+                            f"Refusing to update: reused or duplicate image marker for '{bound_src}'."
+                        )
+
+                consumed_remote_indices.add(matched_idx)
+                remote_img = remote_images[matched_idx]
+                source, alt, href = (
+                    submitted.get("src"),
+                    submitted.get("alt"),
+                    submitted.get("href"),
+                )
+                submitted.update(remote_img)
+                submitted.update(marker["attrs"])
+                submitted.update(
+                    {"src": source, "alt": alt, "href": href, "isProcessing": False}
+                )
+
+            elif marker is not None and marker.get("version") == 1:
+                sub_src = submitted.get("src")
+                matches = [
+                    idx
+                    for idx, r_img in enumerate(remote_images)
+                    if r_img.get("src") == sub_src
+                    and idx not in consumed_remote_indices
+                ]
+                if len(matches) == 1:
+                    matched_idx = matches[0]
+                    consumed_remote_indices.add(matched_idx)
+                    remote_img = remote_images[matched_idx]
+                    source, alt, href = (
+                        submitted.get("src"),
+                        submitted.get("alt"),
+                        submitted.get("href"),
+                    )
+                    submitted.update(remote_img)
+                    submitted.update(marker["attrs"])
+                    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."
+                    )
+
+            else:
+                if 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)
 

{python_substack-0.8.0 → python_substack-0.9.1}/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.1}/substack/mdexport.py

@@ -57,6 +57,22 @@ def _marker(node, unsupported):
     return f"<!-- python-substack-node:v1 {encoded} -->"
 
 
+def _image_marker(attrs):
+    payload_data = {
+        "src": attrs["src"],
+        **{
+            key: value
+            for key, value in attrs.items()
+            if key not in {"src", "alt", "href", "isProcessing"}
+        },
+    }
+    payload = json.dumps(
+        payload_data, ensure_ascii=False, separators=(",", ":"), sort_keys=True
+    ).encode("utf-8")
+    encoded = base64.urlsafe_b64encode(payload).decode("ascii").rstrip("=")
+    return f"\n<!-- python-substack-image:v2 {encoded} -->"
+
+
 def _require_dict(node, context):
     if not isinstance(node, dict):
         raise ValueError(f"Malformed draft body: {context} must be an object")
@@ -214,7 +230,6 @@ def _render_image(node, unsupported):
         image["type"] != "image2"
         or _has_unknown_keys(node, {"type", "content"})
         or _has_unknown_keys(image, {"type", "attrs"})
-        or _has_unknown_keys(attrs, _IMAGE_ATTRS)
         or not isinstance(attrs.get("src"), str)
     ):
         return _marker(node, unsupported)
@@ -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.1}/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
@@ -46,19 +48,21 @@ _MARK_FOR = {
 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:
@@ -87,6 +91,44 @@ def parse_node_marker(comment_content: str) -> dict | None:
     return data
 
 
+def parse_image_marker(comment_content: str) -> dict | None:
+    clean = comment_content.strip()
+    match = re.match(
+        r"^<!--\s*python-substack-image:(v1|v2)\s+([A-Za-z0-9_-]+=*)\s*-->$", clean
+    )
+    if not match:
+        if "python-substack-image:" in clean:
+            raise ValueError("Corrupt image marker format")
+        return None
+    version_str, encoded = match.group(1), match.group(2)
+    encoded += "=" * (-len(encoded) % 4)
+    try:
+        decoded_bytes = base64.urlsafe_b64decode(encoded.encode("ascii"))
+    except Exception as exc:
+        raise ValueError("Invalid image marker") from exc
+    try:
+        attrs = json.loads(decoded_bytes.decode("utf-8"))
+    except Exception as exc:
+        raise ValueError("Invalid image marker") from exc
+    if not isinstance(attrs, dict):
+        raise ValueError("Invalid image marker attributes")
+
+    if version_str == "v1":
+        if any(key in {"src", "alt", "href", "isProcessing"} for key in attrs):
+            raise ValueError("Invalid image marker attributes")
+        return {"version": 1, "src": None, "attrs": attrs}
+
+    if version_str == "v2":
+        if "src" not in attrs or not isinstance(attrs["src"], str):
+            raise ValueError("Invalid image marker attributes")
+        if any(key in {"alt", "href", "isProcessing"} for key in attrs):
+            raise ValueError("Invalid image marker attributes")
+        preserved = {k: v for k, v in attrs.items() if k != "src"}
+        return {"version": 2, "src": attrs["src"], "attrs": preserved}
+
+    return None
+
+
 def _make_parser() -> MarkdownIt:
     return (
         MarkdownIt("commonmark")
@@ -151,6 +193,8 @@ def _render_inline(node: SyntaxTreeNode, marks: List[Dict], ctx: Dict) -> List[D
             if alt:
                 out.append(nodes.text(alt, marks))
         elif t == "html_inline":
+            if "python-substack-image:" in child.content:
+                raise ValueError("Image marker must immediately follow an image")
             marker_data = parse_node_marker(child.content)
             if marker_data is not None:
                 out.append(marker_data)
@@ -173,13 +217,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.
@@ -284,7 +343,9 @@ def _footnote_definitions(tree: SyntaxTreeNode, api) -> Dict[int, List[Dict]]:
     return definitions
 
 
-def markdown_to_doc(markdown_content: str, api=None) -> List[Dict]:
+def markdown_to_doc(
+    markdown_content: str, api=None, track_markers: Optional[List] = None
+) -> List[Dict]:
     """Convert Markdown into a list of Substack ProseMirror block nodes."""
     tree = SyntaxTreeNode(_make_parser().parse(markdown_content))
 
@@ -292,10 +353,39 @@ def markdown_to_doc(markdown_content: str, api=None) -> List[Dict]:
 
     ctx: Dict = {"order": []}
     out: List[Dict] = []
+    last_was_image = False
+    last_image_idx: Optional[int] = None
+
     for node in tree.children:
         if node.type == "footnote_block":
+            last_was_image = False
             continue
-        out.extend(_render_block(node, api, ctx))
+        if node.type == "html_block":
+            marker = parse_image_marker(node.content)
+            if marker is not None:
+                if not last_was_image or last_image_idx is None:
+                    raise ValueError("Image marker must immediately follow an image")
+                last_was_image = False
+                out[last_image_idx]["content"][0]["attrs"].update(marker["attrs"])
+                out[last_image_idx]["content"][0]["attrs"]["isProcessing"] = False
+                if track_markers is not None:
+                    track_markers[-1] = marker
+                continue
+            last_was_image = False
+
+        rendered = _render_block(node, api, ctx)
+        if rendered:
+            for blk in rendered:
+                out.append(blk)
+                if blk.get("type") == NodeType.CAPTIONED_IMAGE:
+                    last_was_image = True
+                    last_image_idx = len(out) - 1
+                    if track_markers is not None:
+                        track_markers.append(None)
+                else:
+                    last_was_image = False
+        else:
+            last_was_image = False
 
     # Emit one footnote block per reference, in anchor order, numbered to match.
     for number, footnote_id in enumerate(ctx["order"], start=1):