python-substack 0.5.0__tar.gz → 0.7.0__tar.gz

{python_substack-0.5.0 → python_substack-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-substack
-Version: 0.5.0
+Version: 0.7.0
 Summary: Write and safely manage Substack drafts from Markdown with Python, CLI, and MCP.
 License: MIT
 License-File: LICENSE
@@ -22,7 +22,7 @@ Classifier: Topic :: Internet :: WWW/HTTP
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Provides-Extra: mcp
 Requires-Dist: PyYAML (>=6.0,<7.0)
-Requires-Dist: fastmcp (>=3.1.1,<4.0.0) ; extra == "mcp"
+Requires-Dist: fastmcp (>=3.1.1,<5.0.0) ; extra == "mcp"
 Requires-Dist: markdown-it-py (>=3,<5)
 Requires-Dist: mdit-py-plugins (>=0.5,<0.7)
 Requires-Dist: python-dotenv (>=1.2.1,<2.0.0)
@@ -93,6 +93,7 @@ Substack result:
 - Upload local images referenced by Markdown.
 - 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.
 - 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.
@@ -143,6 +144,7 @@ Inspect publications and drafts:
 substack publications list
 substack drafts list --limit 10
 substack drafts get 12345
+substack drafts export 12345 --output backup.md
 substack --publication-url https://example.substack.com drafts list
 ```
 
@@ -207,6 +209,14 @@ print(result["draft"]["id"])
 `create_draft_from_markdown` creates a draft by default. It publishes only when
 `publish=True` is passed.
 
+Back up an existing draft without modifying it:
+
+```python
+backup = api.export_draft_to_markdown(12345)
+print(backup["markdown"])
+print(backup["unsupported_nodes"])
+```
+
 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).

{python_substack-0.5.0 → python_substack-0.7.0}/README.md

@@ -57,6 +57,7 @@ Substack result:
 - Upload local images referenced by Markdown.
 - 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.
 - 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.
@@ -107,6 +108,7 @@ Inspect publications and drafts:
 substack publications list
 substack drafts list --limit 10
 substack drafts get 12345
+substack drafts export 12345 --output backup.md
 substack --publication-url https://example.substack.com drafts list
 ```
 
@@ -171,6 +173,14 @@ print(result["draft"]["id"])
 `create_draft_from_markdown` creates a draft by default. It publishes only when
 `publish=True` is passed.
 
+Back up an existing draft without modifying it:
+
+```python
+backup = api.export_draft_to_markdown(12345)
+print(backup["markdown"])
+print(backup["unsupported_nodes"])
+```
+
 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).

{python_substack-0.5.0 → python_substack-0.7.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "python-substack"
-version = "0.5.0"
+version = "0.7.0"
 description = "Write and safely manage Substack drafts from Markdown with Python, CLI, and MCP."
 authors = ["Paolo Mazza <mazzapaolo2019@gmail.com>"]
 license = "MIT"
@@ -41,7 +41,7 @@ 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", optional = true }
+fastmcp = { version = ">=3.1.1,<5.0.0", optional = true }
 
 [tool.poetry.extras]
 mcp = ["fastmcp"]
@@ -49,6 +49,7 @@ mcp = ["fastmcp"]
 [tool.poetry.group.dev.dependencies]
 pytest = "^9.1.1"
 pre-commit = "^4.6.1"
+twine = "^7.0.0"
 
 [tool.pytest.ini_options]
 markers = [

{python_substack-0.5.0 → python_substack-0.7.0}/substack/__init__.py

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

{python_substack-0.5.0 → python_substack-0.7.0}/substack/api.py

@@ -442,6 +442,117 @@ class Api:
         response = self._session.get(f"{self.publication_url}/drafts/{draft_id}")
         return Api._handle_response(response=response)
 
+    def export_draft_to_markdown(self, draft_id):
+        from substack.mdexport import document_to_markdown
+
+        draft = self.get_draft(draft_id)
+        draft_body = draft.get("draft_body")
+        if isinstance(draft_body, str):
+            try:
+                draft_body = json.loads(draft_body)
+            except json.JSONDecodeError as exc:
+                raise ValueError(
+                    "Malformed draft body: draft_body is not valid JSON"
+                ) from exc
+        if not isinstance(draft_body, dict):
+            raise ValueError("Malformed draft body: draft_body must be a JSON object")
+
+        markdown, unsupported_nodes = document_to_markdown(draft_body)
+        return {
+            "draft": draft,
+            "markdown": markdown,
+            "unsupported_nodes": unsupported_nodes,
+        }
+
+    def update_draft_from_markdown(
+        self,
+        draft_id: int,
+        markdown: str,
+        *,
+        subtitle: str = None,
+        audience: str = None,
+        write_comment_permissions: str = None,
+        search_engine_title: str = None,
+        search_engine_description: str = None,
+        slug: str = None,
+        draft_section_id: int = None,
+        tags=None,
+        dry_run: bool = False,
+    ) -> dict:
+        """
+        Update an existing draft body from Markdown, with optional metadata changes.
+        """
+        from substack.mdexport import document_to_markdown
+        from substack.post import Post
+
+        draft = self.get_draft(draft_id)
+        draft_body = draft.get("draft_body")
+        if isinstance(draft_body, str):
+            try:
+                draft_body = json.loads(draft_body)
+            except json.JSONDecodeError as exc:
+                raise ValueError(
+                    "Malformed draft body: draft_body is not valid JSON"
+                ) from exc
+        if not isinstance(draft_body, dict):
+            raise ValueError("Malformed draft body: draft_body must be a JSON object")
+
+        _, unsupported_nodes = document_to_markdown(draft_body)
+        if unsupported_nodes:
+            raise ValueError(
+                "Refusing to update: remote draft contains unsupported Substack nodes. "
+                "Export it first or remove the nodes manually to avoid data loss."
+            )
+
+        post = Post(
+            title=draft.get("title", ""),
+            subtitle=(
+                subtitle if subtitle is not None else (draft.get("subtitle") or "")
+            ),
+            user_id=self.get_user_id(),
+            audience=audience,
+            write_comment_permissions=write_comment_permissions,
+        )
+        post.from_markdown(markdown, api=self)
+
+        update_payload = {"draft_body": json.dumps(post.draft_body)}
+
+        if subtitle is not None:
+            update_payload["subtitle"] = subtitle
+        if audience is not None:
+            update_payload["audience"] = audience
+        if write_comment_permissions is not None:
+            update_payload["write_comment_permissions"] = write_comment_permissions
+        if search_engine_title is not None:
+            update_payload["search_engine_title"] = search_engine_title
+        if search_engine_description is not None:
+            update_payload["search_engine_description"] = search_engine_description
+        if slug is not None:
+            update_payload["slug"] = slug
+        if draft_section_id is not None:
+            update_payload["draft_section_id"] = draft_section_id
+
+        tags_result = None
+        updated_draft = draft
+
+        if not dry_run:
+            updated_draft = self.put_draft(draft_id, **update_payload)
+
+            tags_list = Api._normalize_tags(tags)
+            if tags_list:
+                tags_result = self.add_tags_to_post(draft_id, tags_list)
+
+        return {
+            "action": "update",
+            "draft_id": draft_id,
+            "dry_run": dry_run,
+            "changed": not dry_run,
+            "payload": update_payload,
+            "draft": updated_draft,
+            "tags": tags_result,
+            "unsupported_nodes": unsupported_nodes,
+        }
+
     def delete_draft(self, draft_id):
         """
 

{python_substack-0.5.0 → python_substack-0.7.0}/substack/cli.py

@@ -309,6 +309,79 @@ def _drafts_create(api, args):
         print(f"Created draft {draft.get('id')}: {title}")
 
 
+def _drafts_update(api, args):
+    if not args.yes and (args.json_output or not sys.stdin.isatty()):
+        raise CLIUsageError("--yes is required in non-interactive or JSON mode")
+
+    markdown_file = Path(args.markdown_file)
+    if not markdown_file.exists():
+        raise CLIUsageError(f"File not found: {markdown_file}")
+
+    if not args.yes:
+        action = "update" if not args.dry_run else "dry-run update"
+        print(f"Ready to {action} draft {args.draft_id} from {markdown_file}")
+        print("Substack nodes that are not supported by Markdown export/import")
+        print("will cause the update to be refused to prevent data loss.")
+        print()
+        try:
+            response = input(f"Confirm {action}? [y/N]: ")
+            if response.lower() not in ["y", "yes"]:
+                print("Aborted.")
+                return
+        except EOFError as exc:
+            raise CLIUsageError(
+                f"Confirm {action} requires confirmation or --yes"
+            ) from exc
+
+    markdown = markdown_file.read_text(encoding="utf-8")
+
+    result = api.update_draft_from_markdown(
+        args.draft_id,
+        markdown,
+        subtitle=args.subtitle,
+        audience=args.audience,
+        write_comment_permissions=args.write_comment_permissions,
+        search_engine_title=args.search_engine_title,
+        search_engine_description=args.search_engine_description,
+        slug=args.slug,
+        draft_section_id=args.draft_section_id,
+        tags=args.tags,
+        dry_run=args.dry_run,
+    )
+
+    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}")
+
+
+def _drafts_export(api, args):
+    output_path = Path(args.output) if args.output else None
+    if output_path is not None and output_path.exists() and not args.force:
+        raise CLIUsageError(
+            f"Output file already exists: {output_path}; use --force to overwrite"
+        )
+
+    result = api.export_draft_to_markdown(args.draft_id)
+    markdown = result["markdown"]
+    if output_path is not None:
+        output_path.write_text(markdown, encoding="utf-8")
+
+    payload = {
+        "action": "export",
+        "draft_id": args.draft_id,
+        "markdown": markdown,
+        "unsupported_nodes": result["unsupported_nodes"],
+    }
+    if args.json_output:
+        _print_json(payload)
+    elif output_path is not None:
+        print(f"Exported draft {args.draft_id} to {output_path}")
+    else:
+        print(markdown, end="")
+
+
 def _drafts_schedule(api, args):
     scheduled_at = _parse_schedule(args.at)
     result = api.schedule_draft(args.draft_id, scheduled_at)
@@ -421,6 +494,31 @@ def _build_parser():
     drafts_create.add_argument("--tag", action="append", dest="tags", metavar="TAG")
     drafts_create.set_defaults(handler=_drafts_create)
 
+    drafts_update = draft_commands.add_parser(
+        "update", help="Update a draft from a Markdown file."
+    )
+    drafts_update.add_argument("draft_id", type=int)
+    drafts_update.add_argument("markdown_file", metavar="MARKDOWN_FILE")
+    drafts_update.add_argument("--subtitle")
+    drafts_update.add_argument("--audience")
+    drafts_update.add_argument("--write-comment-permissions")
+    drafts_update.add_argument("--search-engine-title")
+    drafts_update.add_argument("--search-engine-description")
+    drafts_update.add_argument("--slug")
+    drafts_update.add_argument("--draft-section-id", type=int)
+    drafts_update.add_argument("--tag", action="append", dest="tags", metavar="TAG")
+    drafts_update.add_argument("--dry-run", action="store_true")
+    drafts_update.add_argument("--yes", action="store_true")
+    drafts_update.set_defaults(handler=_drafts_update)
+
+    drafts_export = draft_commands.add_parser(
+        "export", help="Export a draft to Markdown without modifying it."
+    )
+    drafts_export.add_argument("draft_id", type=int)
+    drafts_export.add_argument("--output", metavar="PATH")
+    drafts_export.add_argument("--force", action="store_true")
+    drafts_export.set_defaults(handler=_drafts_export)
+
     drafts_schedule = draft_commands.add_parser("schedule", help="Schedule a draft.")
     drafts_schedule.add_argument("draft_id", type=int)
     drafts_schedule.add_argument("--at", required=True)