python-substack 0.9.1__py3-none-any.whl → 0.10.0__py3-none-any.whl

{python_substack-0.9.1.dist-info → python_substack-0.10.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-substack
-Version: 0.9.1
+Version: 0.10.0
 Summary: Write and safely manage Substack drafts from Markdown with Python, CLI, and MCP.
 License-Expression: MIT
 License-File: LICENSE

python_substack-0.10.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+substack/__init__.py,sha256=1z7cdQwJPM4msiHdIoSzm4etUIu5Jcc5CKmFDHcnODA,451
+substack/api.py,sha256=KWEJXjlxZY1sQ9j5qZSGxHfaATyE3O9Nup_elsXBHNU,37927
+substack/cli.py,sha256=dgUTgZeX4sgJDXsFmPIJRBpNGgGQyLR2OpXoEcoHQa0,27586
+substack/exceptions.py,sha256=xuckEoS-PYGYt-9zvuG8CDbr4WncpuKqGXN34yBvGnE,2140
+substack/mdexport.py,sha256=Tzkav3mnF9eIUVHUqUzEQkOTiJsLYde1Xi2AcE_cUdk,14017
+substack/mdrender.py,sha256=xRJIO4_6gcQ9jwLFm32KByi7bRmOJyowqF41GmYCA7A,15450
+substack/nodes.py,sha256=fTsGO0-lTztcXiloIjXrHVnJes9EcltGcrX-mEV2ceQ,5004
+substack/post.py,sha256=qDXu-xzO3nRXtahc-yG2EhxKAXB2hG_Z1nLa55UMBGg,19697
+substack/revision.py,sha256=guEJ8vd38eqHHDqwHL0baf3v02U7RO34Li3D2pvCka8,8796
+substack_mcp/mcp_server.py,sha256=M5XH3C4iWjzvCw3uOPbY2NFljTQAl8FLt14RKaTzka0,11324
+python_substack-0.10.0.dist-info/METADATA,sha256=fgjfdA7h0iQv_kCqxFLFw3Gemhd-LHeJOKhhEZFxthc,9209
+python_substack-0.10.0.dist-info/WHEEL,sha256=kJCRJT_g0adfAJzTx2GUMmS80rTJIVHRCfG0DQgLq3o,88
+python_substack-0.10.0.dist-info/entry_points.txt,sha256=MKPjaBUd-0PtvxsBviStsVq1c0h8JZ_qUoYEsBK1xJc,236
+python_substack-0.10.0.dist-info/licenses/LICENSE,sha256=L6jk148I5HhhVbfUvkO3EO7eAoU5zToLio4-ApkCkxg,1062
+python_substack-0.10.0.dist-info/RECORD,,

substack/__init__.py

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

substack/api.py

@@ -460,6 +460,7 @@ class Api:
 
     def export_draft_to_markdown(self, draft_id):
         from substack.mdexport import document_to_markdown
+        from substack.revision import compute_draft_revision, format_revision_marker
 
         draft = self.get_draft(draft_id)
         draft_body = draft.get("draft_body")
@@ -474,9 +475,15 @@ class Api:
             raise ValueError("Malformed draft body: draft_body must be a JSON object")
 
         markdown, unsupported_nodes = document_to_markdown(draft_body)
+        revision = compute_draft_revision(draft)
+        revision_marker = format_revision_marker(revision)
+        full_markdown = (
+            f"{revision_marker}\n\n{markdown}" if markdown else f"{revision_marker}\n"
+        )
         return {
             "draft": draft,
-            "markdown": markdown,
+            "markdown": full_markdown,
+            "revision": revision,
             "unsupported_nodes": unsupported_nodes,
         }
 
@@ -496,13 +503,22 @@ class Api:
         dry_run: bool = False,
         allow_unsupported_change: bool = False,
         allow_image_replacement: bool = False,
+        expected_revision=None,
+        allow_conflict: bool = False,
+        force: bool = False,
     ) -> dict:
         """
         Update an existing draft body from Markdown, with optional metadata changes.
         """
         from substack import mdrender
+        from substack.exceptions import DraftConflictError
         from substack.mdexport import document_to_markdown
         from substack.post import Post
+        from substack.revision import (
+            compare_draft_revisions,
+            compute_draft_revision,
+            parse_revision_marker,
+        )
 
         draft = self.get_draft(draft_id)
         draft_body = draft.get("draft_body")
@@ -516,6 +532,50 @@ class Api:
         if not isinstance(draft_body, dict):
             raise ValueError("Malformed draft body: draft_body must be a JSON object")
 
+        current_rev = compute_draft_revision(draft)
+
+        target_expected_rev = None
+        if expected_revision is not None:
+            if isinstance(expected_revision, dict):
+                target_expected_rev = expected_revision
+            elif isinstance(expected_revision, str):
+                target_expected_rev = {"revision": expected_revision}
+            else:
+                raise ValueError("expected_revision must be a revision dict or string")
+        else:
+            target_expected_rev = parse_revision_marker(markdown)
+
+        override_enabled = bool(allow_conflict or force)
+        conflict_detected = False
+        mismatches = []
+
+        if target_expected_rev is None:
+            conflict_detected = True
+            mismatches = [
+                "Markdown file is missing revision metadata (unprotected update); safe conflict comparison is impossible."
+            ]
+            if not override_enabled and not dry_run:
+                raise DraftConflictError(
+                    "Refusing to update: Markdown file is missing revision metadata (unprotected update). "
+                    "Export the draft first or pass allow_conflict=True to proceed.",
+                    mismatches=mismatches,
+                    expected_revision=None,
+                    current_revision=current_rev,
+                )
+        else:
+            mismatches = compare_draft_revisions(target_expected_rev, current_rev)
+            if mismatches:
+                conflict_detected = True
+                if not override_enabled and not dry_run:
+                    details = "; ".join(mismatches)
+                    raise DraftConflictError(
+                        f"Refusing to update: remote draft has changed since export ({details}). "
+                        "Re-export the draft or pass allow_conflict=True to proceed.",
+                        mismatches=mismatches,
+                        expected_revision=target_expected_rev,
+                        current_revision=current_rev,
+                    )
+
         _, remote_unsupported = document_to_markdown(draft_body)
 
         image_markers = []
@@ -657,7 +717,7 @@ class Api:
             if tags_list:
                 tags_result = self.add_tags_to_post(draft_id, tags_list)
 
-        return {
+        result_payload = {
             "action": "update",
             "draft_id": draft_id,
             "dry_run": dry_run,
@@ -666,7 +726,14 @@ class Api:
             "draft": updated_draft,
             "tags": tags_result,
             "unsupported_nodes": unsupported_nodes,
+            "conflict": conflict_detected,
+            "mismatches": mismatches,
+            "expected_revision": target_expected_rev,
+            "current_revision": current_rev,
         }
+        if override_enabled and conflict_detected:
+            result_payload["override"] = True
+        return result_payload
 
     def delete_draft(self, draft_id):
         """

substack/cli.py

@@ -10,7 +10,11 @@ import yaml
 from dotenv import load_dotenv
 
 from substack import Api, __version__
-from substack.exceptions import SubstackAPIException, SubstackRequestException
+from substack.exceptions import (
+    DraftConflictError,
+    SubstackAPIException,
+    SubstackRequestException,
+)
 from substack.post import Post
 
 
@@ -146,6 +150,14 @@ def _redact(message):
 
 
 def _error_payload(exc):
+    if isinstance(exc, DraftConflictError):
+        return {
+            "error": {
+                "type": "conflict_error",
+                "message": _redact(exc.message),
+                "mismatches": exc.mismatches,
+            }
+        }
     if isinstance(exc, SubstackAPIException):
         return {
             "error": {
@@ -314,6 +326,8 @@ def _drafts_update(api, args):
         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 args.allow_conflict and not args.yes:
+        raise CLIUsageError("--yes is required when using --allow-conflict")
 
     if not args.yes and (args.json_output or not sys.stdin.isatty()):
         raise CLIUsageError("--yes is required in non-interactive or JSON mode")
@@ -354,13 +368,25 @@ def _drafts_update(api, args):
         dry_run=args.dry_run,
         allow_unsupported_change=args.allow_unsupported_change,
         allow_image_replacement=args.allow_image_replacement,
+        allow_conflict=args.allow_conflict,
     )
 
     if args.json_output:
         _print_json(result)
     else:
         status = "Dry-run updated" if args.dry_run else "Updated"
-        print(f"{status} draft {args.draft_id}")
+        if result.get("conflict"):
+            print(f"Conflict detected in draft {args.draft_id}:")
+            for mismatch in result.get("mismatches", []):
+                print(f"  - {mismatch}")
+            if result.get("dry_run"):
+                print(
+                    f"Dry-run preview completed for draft {args.draft_id} with conflicts."
+                )
+            else:
+                print(f"{status} draft {args.draft_id} (override applied)")
+        else:
+            print(f"{status} draft {args.draft_id}")
 
 
 def _drafts_export(api, args):
@@ -381,6 +407,8 @@ def _drafts_export(api, args):
         "markdown": markdown,
         "unsupported_nodes": result["unsupported_nodes"],
     }
+    if "revision" in result and result["revision"] is not None:
+        payload["revision"] = result["revision"]
     if args.json_output:
         _print_json(payload)
     elif output_path is not None:
@@ -517,6 +545,13 @@ def _build_parser():
     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(
+        "--allow-conflict",
+        "--force",
+        action="store_true",
+        dest="allow_conflict",
+        help="Allow updating draft even if remote revision has changed or revision metadata is missing.",
+    )
     drafts_update.add_argument("--yes", action="store_true")
     drafts_update.set_defaults(handler=_drafts_update)
 

substack/exceptions.py

@@ -12,7 +12,13 @@ def _redact_message(text: str) -> str:
     return text
 
 
-class SubstackAPIException(Exception):
+class SubstackException(Exception):
+    """Base exception for all python-substack exceptions."""
+
+    pass
+
+
+class SubstackAPIException(SubstackException):
     def __init__(self, status_code, text):
         text = _redact_message(text)
         try:
@@ -32,7 +38,7 @@ class SubstackAPIException(Exception):
         return f"APIError(code={self.status_code}): {self.message}"
 
 
-class SubstackRequestException(Exception):
+class SubstackRequestException(SubstackException):
     def __init__(self, message):
         self.message = _redact_message(message)
 
@@ -42,3 +48,23 @@ class SubstackRequestException(Exception):
 
 class SectionNotExistsException(SubstackRequestException):
     pass
+
+
+class DraftConflictError(ValueError, SubstackException):
+    """Raised when an update conflicts with the current remote draft state or lacks revision metadata."""
+
+    def __init__(
+        self,
+        message: str,
+        mismatches: list = None,
+        expected_revision: dict = None,
+        current_revision: dict = None,
+    ):
+        super().__init__(message)
+        self.message = message
+        self.mismatches = mismatches or []
+        self.expected_revision = expected_revision
+        self.current_revision = current_revision
+
+    def __str__(self):
+        return self.message

substack/revision.py

@@ -0,0 +1,254 @@
+import base64
+import hashlib
+import json
+import re
+from typing import Any, Dict, List, Optional
+
+from markdown_it import MarkdownIt
+
+
+def compute_draft_revision(draft: Dict[str, Any]) -> Dict[str, Any]:
+    """Compute deterministic revision and fingerprint metadata from a Substack draft dict."""
+    draft_id = draft.get("id")
+    title = (
+        draft.get("draft_title") if "draft_title" in draft else draft.get("title", "")
+    )
+    subtitle = (
+        draft.get("draft_subtitle")
+        if "draft_subtitle" in draft
+        else draft.get("subtitle", "")
+    )
+    audience = draft.get("audience") or "everyone"
+    write_comment_permissions = draft.get("write_comment_permissions") or "everyone"
+    draft_section_id = (
+        draft.get("draft_section_id")
+        if "draft_section_id" in draft
+        else draft.get("section_id")
+    )
+    slug = draft.get("slug") or ""
+    updated_at = draft.get("draft_updated_at") or draft.get("updated_at")
+
+    raw_body = draft.get("draft_body")
+    if isinstance(raw_body, str):
+        try:
+            body_obj = json.loads(raw_body)
+        except Exception:
+            body_obj = raw_body
+    else:
+        body_obj = raw_body
+
+    if isinstance(body_obj, (dict, list)):
+        body_canonical = json.dumps(
+            body_obj, ensure_ascii=False, separators=(",", ":"), sort_keys=True
+        )
+    else:
+        body_canonical = str(body_obj or "")
+
+    body_hash = hashlib.sha256(body_canonical.encode("utf-8")).hexdigest()
+
+    fingerprint_components = {
+        "draft_id": draft_id,
+        "body_hash": body_hash,
+        "title": title or "",
+        "subtitle": subtitle or "",
+        "audience": audience,
+        "write_comment_permissions": write_comment_permissions,
+        "draft_section_id": draft_section_id,
+        "slug": slug,
+    }
+    fingerprint_bytes = json.dumps(
+        fingerprint_components,
+        ensure_ascii=False,
+        separators=(",", ":"),
+        sort_keys=True,
+    ).encode("utf-8")
+    revision_hash = hashlib.sha256(fingerprint_bytes).hexdigest()
+
+    return {
+        "version": 1,
+        "draft_id": draft_id,
+        "revision": revision_hash,
+        "body_hash": body_hash,
+        "title": title or "",
+        "subtitle": subtitle or "",
+        "audience": audience,
+        "write_comment_permissions": write_comment_permissions,
+        "draft_section_id": draft_section_id,
+        "slug": slug,
+        "updated_at": str(updated_at) if updated_at else None,
+    }
+
+
+def format_revision_marker(revision_info: Dict[str, Any]) -> str:
+    """Format revision metadata as a versioned HTML comment marker."""
+    payload = json.dumps(
+        revision_info, ensure_ascii=False, separators=(",", ":"), sort_keys=True
+    ).encode("utf-8")
+    encoded = base64.urlsafe_b64encode(payload).decode("ascii").rstrip("=")
+    return f"<!-- python-substack-revision:v1 {encoded} -->"
+
+
+def parse_revision_marker(markdown: str) -> Optional[Dict[str, Any]]:
+    """
+    Parse a python-substack-revision:v1 comment marker from markdown content.
+
+    Only top-level HTML comment blocks are considered; comments inside code blocks
+    are ignored.
+
+    Returns the parsed revision dictionary, or None if no marker is found.
+    Raises ValueError if an attempted marker is corrupt, malformed, unsupported, or duplicated.
+    """
+    md = MarkdownIt()
+    tokens = md.parse(markdown)
+
+    found_markers = []
+    marker_pattern = re.compile(
+        r"^<!--\s*python-substack-revision:v([0-9]+)\s+([A-Za-z0-9_-]+=*)\s*-->$"
+    )
+
+    for token in tokens:
+        if token.type == "html_block":
+            clean = token.content.strip()
+            match = marker_pattern.match(clean)
+            if match:
+                found_markers.append(match.groups())
+            elif "python-substack-revision:" in clean:
+                raise ValueError(
+                    "Malformed revision marker: corrupt comment format or invalid characters"
+                )
+
+    if not found_markers:
+        return None
+
+    if len(found_markers) > 1:
+        raise ValueError("Malformed revision marker: multiple revision markers found")
+
+    version_str, encoded = found_markers[0]
+    if version_str != "1":
+        raise ValueError(
+            f"Malformed revision marker: unsupported version '{version_str}'"
+        )
+
+    pad = len(encoded) % 4
+    if pad:
+        encoded += "=" * (4 - pad)
+
+    try:
+        raw = base64.urlsafe_b64decode(encoded.encode("ascii"))
+    except Exception as exc:
+        raise ValueError("Malformed revision marker: invalid base64 encoding") from exc
+
+    try:
+        data = json.loads(raw.decode("utf-8"))
+    except Exception as exc:
+        raise ValueError("Malformed revision marker: invalid JSON payload") from exc
+
+    if not isinstance(data, dict):
+        raise ValueError("Malformed revision marker: payload must be a JSON object")
+
+    if not data.get("revision") or not isinstance(data.get("revision"), str):
+        raise ValueError(
+            "Malformed revision marker: missing or empty required 'revision' field"
+        )
+
+    return data
+
+
+def compare_draft_revisions(
+    expected: Dict[str, Any], current: Dict[str, Any]
+) -> List[str]:
+    """
+    Compare expected revision metadata with current remote draft revision metadata.
+
+    Returns a list of human-readable, actionable mismatch descriptions.
+    If the list is empty, there is no conflict.
+    """
+    mismatches: List[str] = []
+
+    if (
+        expected.get("draft_id") is not None
+        and current.get("draft_id") is not None
+        and str(expected.get("draft_id")) != str(current.get("draft_id"))
+    ):
+        mismatches.append(
+            f"Draft ID mismatch: expected {expected.get('draft_id')}, got {current.get('draft_id')}"
+        )
+
+    if (
+        expected.get("body_hash")
+        and current.get("body_hash")
+        and expected.get("body_hash") != current.get("body_hash")
+    ):
+        mismatches.append("Remote draft body has changed since export")
+
+    if (
+        expected.get("title") is not None
+        and current.get("title") is not None
+        and expected.get("title") != current.get("title")
+    ):
+        mismatches.append(
+            f"Remote title changed: expected '{expected.get('title')}', got '{current.get('title')}'"
+        )
+
+    if (
+        expected.get("subtitle") is not None
+        and current.get("subtitle") is not None
+        and expected.get("subtitle") != current.get("subtitle")
+    ):
+        mismatches.append(
+            f"Remote subtitle changed: expected '{expected.get('subtitle')}', got '{current.get('subtitle')}'"
+        )
+
+    if (
+        expected.get("audience")
+        and current.get("audience")
+        and expected.get("audience") != current.get("audience")
+    ):
+        mismatches.append(
+            f"Remote audience changed: expected '{expected.get('audience')}', got '{current.get('audience')}'"
+        )
+
+    if (
+        expected.get("write_comment_permissions")
+        and current.get("write_comment_permissions")
+        and expected.get("write_comment_permissions")
+        != current.get("write_comment_permissions")
+    ):
+        mismatches.append(
+            f"Remote write_comment_permissions changed: expected '{expected.get('write_comment_permissions')}', got '{current.get('write_comment_permissions')}'"
+        )
+
+    if expected.get("draft_section_id") != current.get("draft_section_id"):
+        mismatches.append(
+            f"Remote section changed: expected {expected.get('draft_section_id')}, got {current.get('draft_section_id')}"
+        )
+
+    if (
+        expected.get("slug") is not None
+        and current.get("slug") is not None
+        and expected.get("slug") != current.get("slug")
+    ):
+        mismatches.append(
+            f"Remote slug changed: expected '{expected.get('slug')}', got '{current.get('slug')}'"
+        )
+
+    if (
+        expected.get("updated_at")
+        and current.get("updated_at")
+        and expected.get("updated_at") != current.get("updated_at")
+    ):
+        mismatches.append(
+            f"Remote update timestamp changed: expected '{expected.get('updated_at')}', got '{current.get('updated_at')}'"
+        )
+
+    if (
+        expected.get("revision")
+        and current.get("revision")
+        and expected.get("revision") != current.get("revision")
+        and not mismatches
+    ):
+        mismatches.append(
+            f"Remote revision fingerprint mismatch: expected '{expected.get('revision')}', got '{current.get('revision')}'"
+        )
+
+    return mismatches

python_substack-0.9.1.dist-info/RECORD

@@ -1,14 +0,0 @@
-substack/__init__.py,sha256=FNVZvkchlc56ph-fm0NUca2FHQpLFmwV_o2Umz_nNjQ,450
-substack/api.py,sha256=hnzIHC_t6VOjEzOCSngg9uaTQacyLtBYUlS3uQfbrJk,34830
-substack/cli.py,sha256=56BTWxfr3gpAaJOLJsKRG7k6PPT7xSgLdp632H4mezA,26292
-substack/exceptions.py,sha256=Y61XSPyxDxXPbVlioFvKhb94MRY0tpD389F5YdL1rGM,1390
-substack/mdexport.py,sha256=Tzkav3mnF9eIUVHUqUzEQkOTiJsLYde1Xi2AcE_cUdk,14017
-substack/mdrender.py,sha256=xRJIO4_6gcQ9jwLFm32KByi7bRmOJyowqF41GmYCA7A,15450
-substack/nodes.py,sha256=fTsGO0-lTztcXiloIjXrHVnJes9EcltGcrX-mEV2ceQ,5004
-substack/post.py,sha256=qDXu-xzO3nRXtahc-yG2EhxKAXB2hG_Z1nLa55UMBGg,19697
-substack_mcp/mcp_server.py,sha256=M5XH3C4iWjzvCw3uOPbY2NFljTQAl8FLt14RKaTzka0,11324
-python_substack-0.9.1.dist-info/METADATA,sha256=pDBPPtbe1r5CKfn2dC-qAsH0l0SuCGwGtFd9sPl3jmM,9208
-python_substack-0.9.1.dist-info/WHEEL,sha256=kJCRJT_g0adfAJzTx2GUMmS80rTJIVHRCfG0DQgLq3o,88
-python_substack-0.9.1.dist-info/entry_points.txt,sha256=MKPjaBUd-0PtvxsBviStsVq1c0h8JZ_qUoYEsBK1xJc,236
-python_substack-0.9.1.dist-info/licenses/LICENSE,sha256=L6jk148I5HhhVbfUvkO3EO7eAoU5zToLio4-ApkCkxg,1062
-python_substack-0.9.1.dist-info/RECORD,,