python-substack 0.1.25__py3-none-any.whl → 0.1.27__py3-none-any.whl

{python_substack-0.1.25.dist-info → python_substack-0.1.27.dist-info}/METADATA

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: python-substack
-Version: 0.1.25
-Summary: A Python wrapper around the Substack API.
+Version: 0.1.27
+Summary: A Python SDK and CLI for managing Substack publications and drafts.
 License: MIT
 License-File: LICENSE
-Keywords: substack
+Keywords: substack,substack-api,cli,newsletter,publishing,automation,mcp
 Author: Paolo Mazza
 Author-email: mazzapaolo2019@gmail.com
 Requires-Python: >=3.10,<4.0
@@ -24,7 +24,7 @@ Provides-Extra: mcp
 Requires-Dist: PyYAML (>=6.0,<7.0)
 Requires-Dist: fastmcp (>=3.1.1,<4.0.0) ; extra == "mcp"
 Requires-Dist: markdown-it-py (>=3.0,<4.0)
-Requires-Dist: mdit-py-plugins (>=0.4,<0.5)
+Requires-Dist: mdit-py-plugins (>=0.5,<0.7)
 Requires-Dist: python-dotenv (>=1.2.1,<2.0.0)
 Requires-Dist: requests (>=2.32.0,<3.0.0)
 Project-URL: Changelog, https://github.com/ma2za/python-substack/blob/main/CHANGELOG.md
@@ -35,13 +35,20 @@ Description-Content-Type: text/markdown
 
 # Python Substack
 
-Unofficial Python tools for publishing to [Substack](https://substack.com/).
+An unofficial Python SDK and CLI for managing [Substack](https://substack.com/) publications and drafts.
 
+[![PyPI](https://img.shields.io/pypi/v/python-substack)](https://pypi.org/project/python-substack/)
+[![Python](https://img.shields.io/pypi/pyversions/python-substack)](https://pypi.org/project/python-substack/)
+[![Tests](https://github.com/ma2za/python-substack/actions/workflows/ci.yml/badge.svg)](https://github.com/ma2za/python-substack/actions/workflows/ci.yml)
+[![Release](https://github.com/ma2za/python-substack/actions/workflows/ci_publish.yml/badge.svg)](https://github.com/ma2za/python-substack/actions/workflows/ci_publish.yml)
+[![License](https://img.shields.io/pypi/l/python-substack)](LICENSE)
 [![Downloads](https://static.pepy.tech/badge/python-substack/month)](https://pepy.tech/project/python-substack)
-![Release Build](https://github.com/ma2za/python-substack/actions/workflows/ci_publish.yml/badge.svg)
 
 ## Features
 
+- Inspect authentication and publication status from the terminal.
+- List publications and inspect, schedule, publish, or delete drafts.
+- Use stable JSON output in scripts and automation.
 - Create drafts and publish posts from Python.
 - Convert Markdown into Substack's editor document format.
 - Upload local images while rendering Markdown.
@@ -78,6 +85,76 @@ Use either `EMAIL` and `PASSWORD`, or cookie-based authentication with `COOKIES_
 
 Newer Substack accounts may only have magic-link sign-in enabled. To set a password, sign out of Substack, choose "Sign in with password", then choose "Set a new password".
 
+## CLI Operations
+
+Create a draft from Markdown without publishing it:
+
+```bash
+substack drafts create post.md
+```
+
+Set metadata and repeat `--tag` to attach multiple tags:
+
+```bash
+substack --json drafts create post.md \
+  --title "My Post" \
+  --subtitle "Optional subtitle" \
+  --tag python \
+  --tag substack \
+  --slug my-post \
+  --search-engine-title "SEO title" \
+  --search-engine-description "SEO description"
+```
+
+Creation and publishing are intentionally separate. Use the returned draft ID
+when the draft is ready:
+
+```bash
+substack drafts create post.md
+substack drafts publish 12345 --no-send
+```
+
+Check authentication, the selected publication, and subscriber count:
+
+```bash
+substack status
+```
+
+List available publications or target one without changing `.env`:
+
+```bash
+substack publications list
+substack --publication-url https://example.substack.com drafts list
+```
+
+List and inspect drafts:
+
+```bash
+substack drafts list --limit 10
+substack drafts get 12345
+```
+
+Schedule with a timezone-aware ISO 8601 timestamp, or remove a schedule:
+
+```bash
+substack drafts schedule 12345 --at 2026-08-01T09:00:00+03:00
+substack drafts unschedule 12345
+```
+
+Publishing and deletion prompt for confirmation. Use `--yes` for intentional non-interactive execution:
+
+```bash
+substack drafts publish 12345 --no-send
+substack drafts delete 12345 --yes
+```
+
+Global options must appear before the command. `--json` returns stable envelopes containing the raw Substack responses:
+
+```bash
+substack --json drafts list
+substack --cookies cookies.json --json status
+```
+
 ## Quickstart
 
 ```python
@@ -113,7 +190,9 @@ print(result["draft"]["id"])
 
 `create_draft_from_markdown` creates a draft by default. It only publishes when `publish=True` is passed.
 
-## CLI
+## Legacy Content Publishing CLI
+
+The existing standalone commands remain supported for compatibility.
 
 Check authentication without creating a draft:
 
@@ -290,7 +369,7 @@ Paragraph with **bold**, *italic*, `code`, [links](https://example.com), and foo
 )
 ```
 
-Supported Markdown includes headings, paragraphs, bold, italic, inline code, strikethrough, links, images, linked images, image captions, code blocks, blockquotes, ordered lists, unordered lists, horizontal rules, and footnotes.
+Supported Markdown includes headings, paragraphs, bold, italic, inline code, strikethrough, superscript, subscript, links, images, linked images, image captions, code blocks, blockquotes, ordered lists, unordered lists, horizontal rules, footnotes, LaTeX math, pull quotes, and callouts. See [docs/markdown.md](docs/markdown.md) for the full reference with examples.
 
 When an `Api` instance is passed to `from_markdown`, local image paths are uploaded before the draft is created:
 
@@ -371,9 +450,28 @@ pre-commit install
 pytest
 ```
 
-Live Substack tests are opt-in. Set `RUN_SUBSTACK_E2E=1` and configure credentials before running them.
+Run the offline suite with:
+
+```bash
+pytest -m "not live"
+```
+
+Live Substack tests are not part of normal CI. They are opt-in and require
+configured credentials:
+
+```bash
+RUN_SUBSTACK_E2E=1 pytest -m live
+```
+
+The CLI operations smoke tests are separately opt-in. They create, inspect, and
+delete disposable drafts but never publish them:
+
+```bash
+RUN_SUBSTACK_CLI_E2E=1 pytest -m live tests/substack/test_cli_end_to_end.py
+```
 
 Release changes are tracked in [CHANGELOG.md](CHANGELOG.md).
+The maintainer release process is documented in [docs/releasing.md](docs/releasing.md).
 
 ## Disclaimer
 

python_substack-0.1.27.dist-info/RECORD

@@ -0,0 +1,13 @@
+substack/__init__.py,sha256=Wd16zqqfA6bYLntSyq_dnRIFxosqgzjbyIVcJigGQ_A,416
+substack/api.py,sha256=tuxefoBuOvBn4Ww2VCbqkWCuX6qPOg7YM6EsLheBpV4,23213
+substack/cli.py,sha256=JBCsCdmthjzTeDpOYBLeVKOdNYjBrPuY1o_CIsAIekk,21712
+substack/exceptions.py,sha256=BbP5W5UpzFcM5SYIxx6snWD_Rmj7F_YjYIYC_r03gZY,911
+substack/mdrender.py,sha256=QGJkdp1isFmhVyTRMogIabAK8OO2xQh9CrjnXZvFTY4,9308
+substack/nodes.py,sha256=fTsGO0-lTztcXiloIjXrHVnJes9EcltGcrX-mEV2ceQ,5004
+substack/post.py,sha256=nXeZMAZ6-lx1Qf4yuAlrEQ0lcWFYF2afai1_TxVEl0Q,19704
+substack_mcp/mcp_server.py,sha256=gmevdc59XTBXXMTvVMpYoq66Umlqku1O_uzmw5tMy7o,8405
+python_substack-0.1.27.dist-info/METADATA,sha256=-yH6Uq4uhgO8tUYONxf3EkMMpvXd7--dxEAMkYsHTMc,11738
+python_substack-0.1.27.dist-info/WHEEL,sha256=kJCRJT_g0adfAJzTx2GUMmS80rTJIVHRCfG0DQgLq3o,88
+python_substack-0.1.27.dist-info/entry_points.txt,sha256=MKPjaBUd-0PtvxsBviStsVq1c0h8JZ_qUoYEsBK1xJc,236
+python_substack-0.1.27.dist-info/licenses/LICENSE,sha256=L6jk148I5HhhVbfUvkO3EO7eAoU5zToLio4-ApkCkxg,1062
+python_substack-0.1.27.dist-info/RECORD,,

{python_substack-0.1.25.dist-info → python_substack-0.1.27.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: poetry-core 2.4.0
+Generator: poetry-core 2.3.1
 Root-Is-Purelib: true
 Tag: py3-none-any

{python_substack-0.1.25.dist-info → python_substack-0.1.27.dist-info}/entry_points.txt

@@ -1,4 +1,5 @@
 [console_scripts]
+substack=substack.cli:main
 substack-auth-check=substack.cli:auth_check
 substack-mcp=substack_mcp.mcp_server:main
 substack-publish-markdown=substack.cli:publish_markdown

substack/__init__.py

@@ -3,9 +3,9 @@
 __author__ = "Paolo Mazza"
 __email__ = "mazzapaolo2019@gmail.com"
 __license__ = "MIT License"
-__version__ = "0.1.25"
+__version__ = "0.1.27"
 __url__ = "https://github.com/ma2za/python-substack"
 __download_url__ = "https://pypi.python.org/pypi/python-substack"
-__description__ = "A Python wrapper around the Substack API"
+__description__ = "A Python SDK and CLI for managing Substack publications and drafts"
 
 from .api import Api

substack/api.py

@@ -12,6 +12,7 @@ from datetime import datetime
 from urllib.parse import unquote, urljoin
 
 import requests
+from requests.adapters import HTTPAdapter, Retry
 
 from substack.exceptions import SubstackAPIException, SubstackRequestException
 
@@ -65,6 +66,18 @@ class Api:
             logging.getLogger().setLevel(logging.DEBUG)
 
         self._session = requests.Session()
+        retry = Retry(
+            total=4,
+            status=4,
+            backoff_factor=1,
+            status_forcelist=(429,),
+            allowed_methods=frozenset({"GET", "DELETE"}),
+            respect_retry_after_header=True,
+            raise_on_status=False,
+        )
+        adapter = HTTPAdapter(max_retries=retry)
+        self._session.mount("http://", adapter)
+        self._session.mount("https://", adapter)
 
         # Load cookies from file if provided
         # Helps with Captcha errors by reusing cookies from "local" auth, then switching to running code in the cloud
@@ -346,7 +359,10 @@ class Api:
             f"{self.publication_url}/publication_launch_checklist"
         )
 
-        return Api._handle_response(response=response)["subscriberCount"]
+        data = Api._handle_response(response=response)
+        if "subscriberCount" in data:
+            return data["subscriberCount"]
+        return len(data["subscribers"])
 
     def get_published_posts(
         self, offset=0, limit=25, order_by="post_date", order_direction="desc"
@@ -553,8 +569,8 @@ class Api:
 
         """
         response = self._session.post(
-            f"{self.publication_url}/drafts/{draft}/schedule",
-            json={"post_date": draft_datetime.isoformat()},
+            f"{self.publication_url}/drafts/{draft}/scheduled_release",
+            json={"trigger_at": draft_datetime.isoformat()},
         )
         return Api._handle_response(response=response)
 
@@ -567,8 +583,8 @@ class Api:
         Returns:
 
         """
-        response = self._session.post(
-            f"{self.publication_url}/drafts/{draft}/schedule", json={"post_date": None}
+        response = self._session.delete(
+            f"{self.publication_url}/drafts/{draft}/scheduled_release"
         )
         return Api._handle_response(response=response)
 

substack/cli.py

@@ -1,32 +1,41 @@
 import argparse
 import json
 import os
+import sys
+from datetime import datetime
 from pathlib import Path
+from urllib.parse import urljoin
 
 import yaml
 from dotenv import load_dotenv
 
-from substack import Api
+from substack import Api, __version__
+from substack.exceptions import SubstackAPIException, SubstackRequestException
 from substack.post import Post
 
 
-def _api_from_env(cookies_path=None):
+class CLIUsageError(Exception):
+    pass
+
+
+def _api_from_env(cookies_path=None, publication_url=None):
     load_dotenv()
 
     cookies_path = cookies_path or os.getenv("COOKIES_PATH")
     cookies_string = os.getenv("COOKIES_STRING")
+    publication_url = publication_url or os.getenv("PUBLICATION_URL")
 
     if cookies_path or cookies_string:
         return Api(
             cookies_path=cookies_path,
             cookies_string=cookies_string,
-            publication_url=os.getenv("PUBLICATION_URL"),
+            publication_url=publication_url,
         )
 
     return Api(
         email=os.getenv("EMAIL"),
         password=os.getenv("PASSWORD"),
-        publication_url=os.getenv("PUBLICATION_URL"),
+        publication_url=publication_url,
     )
 
 
@@ -56,6 +65,402 @@ def _print_result(result):
     print(json.dumps({"draft_id": draft.get("id"), "draft": draft}, indent=2))
 
 
+def _print_json(value, stream=None):
+    print(json.dumps(value, indent=2, default=str), file=stream)
+
+
+def _display(value):
+    if value is None or value == "":
+        return "-"
+    return str(value)
+
+
+def _print_rows(headers, rows):
+    rows = [[_display(value) for value in row] for row in rows]
+    widths = [len(header) for header in headers]
+    for row in rows:
+        for index, value in enumerate(row):
+            widths[index] = max(widths[index], len(value))
+
+    print(
+        "  ".join(header.ljust(widths[index]) for index, header in enumerate(headers))
+    )
+    print("  ".join("-" * width for width in widths))
+    for row in rows:
+        print("  ".join(value.ljust(widths[index]) for index, value in enumerate(row)))
+
+
+def _identity(profile):
+    return (
+        profile.get("email")
+        or profile.get("name")
+        or profile.get("handle")
+        or str(profile.get("id", "unknown"))
+    )
+
+
+def _selected_publication(api, publications):
+    for publication in publications:
+        publication_url = publication.get("publication_url")
+        if (
+            publication_url
+            and urljoin(publication_url, "api/v1") == api.publication_url
+        ):
+            return publication
+    return {"publication_url": api.publication_url.removesuffix("/api/v1")}
+
+
+def _parse_schedule(value):
+    normalized = value[:-1] + "+00:00" if value.endswith(("Z", "z")) else value
+    try:
+        scheduled_at = datetime.fromisoformat(normalized)
+    except ValueError as exc:
+        raise CLIUsageError("--at must be a valid ISO 8601 timestamp") from exc
+    if scheduled_at.utcoffset() is None:
+        raise CLIUsageError("--at must include a timezone offset or Z")
+    return scheduled_at
+
+
+def _confirm(action, target, yes, json_output):
+    if yes:
+        return
+    if json_output or not sys.stdin.isatty():
+        raise CLIUsageError(f"{action} requires --yes in non-interactive or JSON mode")
+    try:
+        confirmed = input(f"{action} draft {target}? [y/N] ").strip().lower()
+    except EOFError as exc:
+        raise CLIUsageError(f"{action} requires confirmation or --yes") from exc
+    if confirmed not in {"y", "yes"}:
+        raise CLIUsageError("Cancelled")
+
+
+def _redact(message):
+    redacted = str(message)
+    for name in ("EMAIL", "PASSWORD", "COOKIES_STRING"):
+        secret = os.getenv(name)
+        if secret:
+            redacted = redacted.replace(secret, "[redacted]")
+    return redacted
+
+
+def _error_payload(exc):
+    if isinstance(exc, SubstackAPIException):
+        return {
+            "error": {
+                "type": "api_error",
+                "message": _redact(exc.message),
+                "status_code": exc.status_code,
+            }
+        }
+    if isinstance(exc, SubstackRequestException):
+        return {
+            "error": {
+                "type": "request_error",
+                "message": _redact(exc.message),
+            }
+        }
+    if isinstance(exc, OSError):
+        return {"error": {"type": "io_error", "message": _redact(exc)}}
+    return {"error": {"type": "configuration_error", "message": _redact(exc)}}
+
+
+def _print_error(exc, json_output):
+    payload = _error_payload(exc)
+    if json_output:
+        _print_json(payload, stream=sys.stderr)
+    else:
+        print(f"Error: {payload['error']['message']}", file=sys.stderr)
+
+
+def _print_usage_error(exc, json_output):
+    if json_output:
+        _print_json(
+            {"error": {"type": "usage_error", "message": str(exc)}},
+            stream=sys.stderr,
+        )
+    else:
+        print(f"Error: {exc}", file=sys.stderr)
+
+
+def _status(api, args):
+    profile = api.get_user_profile()
+    publications = api.get_user_publications()
+    selected = _selected_publication(api, publications)
+    subscriber_count = api.get_publication_subscriber_count()
+    result = {
+        "status": {
+            "identity": _identity(profile),
+            "auth_method": _auth_method(args.cookies),
+            "subscriber_count": subscriber_count,
+        },
+        "profile": profile,
+        "publication": selected,
+        "publications": publications,
+    }
+    if args.json_output:
+        _print_json(result)
+    else:
+        print(f"Authenticated as: {result['status']['identity']}")
+        print(f"Auth method: {result['status']['auth_method']}")
+        print(f"Publication: {_display(selected.get('name'))}")
+        print(f"Publication URL: {_display(selected.get('publication_url'))}")
+        print(f"Subscribers: {subscriber_count}")
+        print(f"Available publications: {len(publications)}")
+
+
+def _publications_list(api, args):
+    publications = api.get_user_publications()
+    if args.json_output:
+        _print_json({"publications": publications, "count": len(publications)})
+    else:
+        _print_rows(
+            ["ID", "NAME", "SUBDOMAIN", "URL"],
+            [
+                [
+                    publication.get("id"),
+                    publication.get("name"),
+                    publication.get("subdomain"),
+                    publication.get("publication_url"),
+                ]
+                for publication in publications
+            ],
+        )
+
+
+def _drafts_list(api, args):
+    if args.offset < 0:
+        raise CLIUsageError("--offset must be zero or greater")
+    if args.limit < 1:
+        raise CLIUsageError("--limit must be greater than zero")
+    drafts = api.get_drafts(filter=args.filter, offset=args.offset, limit=args.limit)
+    if args.json_output:
+        _print_json(
+            {
+                "drafts": drafts,
+                "count": len(drafts),
+                "filter": args.filter,
+                "offset": args.offset,
+                "limit": args.limit,
+            }
+        )
+    else:
+        _print_rows(
+            ["ID", "TITLE", "STATUS", "SCHEDULED"],
+            [
+                [
+                    draft.get("id"),
+                    draft.get("draft_title") or draft.get("title"),
+                    draft.get("type") or draft.get("status") or "draft",
+                    draft.get("post_date"),
+                ]
+                for draft in drafts
+            ],
+        )
+
+
+def _drafts_get(api, args):
+    draft = api.get_draft(args.draft_id)
+    if args.json_output:
+        _print_json({"draft": draft})
+    else:
+        fields = [
+            ("ID", draft.get("id")),
+            ("Title", draft.get("draft_title") or draft.get("title")),
+            ("Subtitle", draft.get("draft_subtitle") or draft.get("subtitle")),
+            ("Status", draft.get("type") or draft.get("status") or "draft"),
+            ("Slug", draft.get("slug")),
+            ("Scheduled", draft.get("post_date")),
+            ("Audience", draft.get("audience")),
+        ]
+        for label, value in fields:
+            print(f"{label}: {_display(value)}")
+
+
+def _drafts_create(api, args):
+    markdown_path = Path(args.markdown_file)
+    markdown = markdown_path.read_text(encoding="utf-8")
+    title = args.title or _title_from_markdown(markdown, markdown_path.stem)
+    result = api.create_draft_from_markdown(
+        title=title,
+        markdown=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,
+        prepublish=False,
+        publish=False,
+    )
+    draft = result["draft"]
+    payload = {
+        "action": "create",
+        "draft_id": draft.get("id"),
+        "draft": draft,
+        "tags": result.get("tags"),
+    }
+    if args.json_output:
+        _print_json(payload)
+    else:
+        print(f"Created draft {draft.get('id')}: {title}")
+
+
+def _drafts_schedule(api, args):
+    scheduled_at = _parse_schedule(args.at)
+    result = api.schedule_draft(args.draft_id, scheduled_at)
+    payload = {
+        "action": "schedule",
+        "draft_id": args.draft_id,
+        "scheduled_at": scheduled_at.isoformat(),
+        "result": result,
+    }
+    if args.json_output:
+        _print_json(payload)
+    else:
+        print(f"Scheduled draft {args.draft_id} for {scheduled_at.isoformat()}")
+
+
+def _drafts_unschedule(api, args):
+    result = api.unschedule_draft(args.draft_id)
+    payload = {"action": "unschedule", "draft_id": args.draft_id, "result": result}
+    if args.json_output:
+        _print_json(payload)
+    else:
+        print(f"Unscheduled draft {args.draft_id}")
+
+
+def _drafts_publish(api, args):
+    _confirm("Publish", args.draft_id, args.yes, args.json_output)
+    prepublish = api.prepublish_draft(args.draft_id)
+    result = api.publish_draft(
+        args.draft_id,
+        send=args.send,
+        share_automatically=args.share_automatically,
+    )
+    payload = {
+        "action": "publish",
+        "draft_id": args.draft_id,
+        "prepublish": prepublish,
+        "result": result,
+    }
+    if args.json_output:
+        _print_json(payload)
+    else:
+        delivery = "without email" if not args.send else "with email"
+        print(f"Published draft {args.draft_id} {delivery}")
+
+
+def _drafts_delete(api, args):
+    _confirm("Delete", args.draft_id, args.yes, args.json_output)
+    result = api.delete_draft(args.draft_id)
+    payload = {"action": "delete", "draft_id": args.draft_id, "result": result}
+    if args.json_output:
+        _print_json(payload)
+    else:
+        print(f"Deleted draft {args.draft_id}")
+
+
+def _build_parser():
+    parser = argparse.ArgumentParser(
+        prog="substack", description="Manage Substack publications and drafts."
+    )
+    parser.add_argument("--cookies", help="Path to a cookies JSON file.")
+    parser.add_argument(
+        "--publication-url", help="Override PUBLICATION_URL for this command."
+    )
+    parser.add_argument("--json", action="store_true", dest="json_output")
+    parser.add_argument("--version", action="version", version=__version__)
+
+    commands = parser.add_subparsers(dest="command", required=True)
+    status = commands.add_parser(
+        "status", help="Show authentication and publication status."
+    )
+    status.set_defaults(handler=_status)
+
+    publications = commands.add_parser("publications", help="Manage publications.")
+    publication_commands = publications.add_subparsers(
+        dest="publication_command", required=True
+    )
+    publications_list = publication_commands.add_parser(
+        "list", help="List available publications."
+    )
+    publications_list.set_defaults(handler=_publications_list)
+
+    drafts = commands.add_parser("drafts", help="Manage drafts.")
+    draft_commands = drafts.add_subparsers(dest="draft_command", required=True)
+
+    drafts_list = draft_commands.add_parser("list", help="List drafts.")
+    drafts_list.add_argument("--filter", default="draft")
+    drafts_list.add_argument("--offset", type=int, default=0)
+    drafts_list.add_argument("--limit", type=int, default=25)
+    drafts_list.set_defaults(handler=_drafts_list)
+
+    drafts_get = draft_commands.add_parser("get", help="Inspect a draft.")
+    drafts_get.add_argument("draft_id", type=int)
+    drafts_get.set_defaults(handler=_drafts_get)
+
+    drafts_create = draft_commands.add_parser(
+        "create", help="Create a draft from a Markdown file."
+    )
+    drafts_create.add_argument("markdown_file", metavar="MARKDOWN_FILE")
+    drafts_create.add_argument("--title")
+    drafts_create.add_argument("--subtitle", default="")
+    drafts_create.add_argument("--audience", default="everyone")
+    drafts_create.add_argument("--write-comment-permissions", default="everyone")
+    drafts_create.add_argument("--search-engine-title")
+    drafts_create.add_argument("--search-engine-description")
+    drafts_create.add_argument("--slug")
+    drafts_create.add_argument("--draft-section-id", type=int)
+    drafts_create.add_argument("--tag", action="append", dest="tags", metavar="TAG")
+    drafts_create.set_defaults(handler=_drafts_create)
+
+    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)
+    drafts_schedule.set_defaults(handler=_drafts_schedule)
+
+    drafts_unschedule = draft_commands.add_parser(
+        "unschedule", help="Remove a draft schedule."
+    )
+    drafts_unschedule.add_argument("draft_id", type=int)
+    drafts_unschedule.set_defaults(handler=_drafts_unschedule)
+
+    drafts_publish = draft_commands.add_parser("publish", help="Publish a draft.")
+    drafts_publish.add_argument("draft_id", type=int)
+    drafts_publish.add_argument(
+        "--no-send", action="store_false", dest="send", default=True
+    )
+    drafts_publish.add_argument("--share-automatically", action="store_true")
+    drafts_publish.add_argument("--yes", action="store_true")
+    drafts_publish.set_defaults(handler=_drafts_publish)
+
+    drafts_delete = draft_commands.add_parser("delete", help="Delete a draft.")
+    drafts_delete.add_argument("draft_id", type=int)
+    drafts_delete.add_argument("--yes", action="store_true")
+    drafts_delete.set_defaults(handler=_drafts_delete)
+    return parser
+
+
+def main(argv=None):
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    try:
+        api = _api_from_env(
+            cookies_path=args.cookies,
+            publication_url=args.publication_url,
+        )
+        args.handler(api, args)
+    except CLIUsageError as exc:
+        _print_usage_error(exc, args.json_output)
+        return 2
+    except (SubstackAPIException, SubstackRequestException, OSError, ValueError) as exc:
+        _print_error(exc, args.json_output)
+        return 1
+    return 0
+
+
 def publish_markdown(argv=None):
     parser = argparse.ArgumentParser()
     parser.add_argument("markdown", nargs="?", default="README.md")

substack/mdrender.py

@@ -22,7 +22,11 @@ from typing import Dict, List, Optional
 
 from markdown_it import MarkdownIt
 from markdown_it.tree import SyntaxTreeNode
+from mdit_py_plugins.container import container_plugin
+from mdit_py_plugins.dollarmath import dollarmath_plugin
 from mdit_py_plugins.footnote import footnote_plugin
+from mdit_py_plugins.subscript import sub_plugin
+from mdit_py_plugins.superscript import superscript_plugin
 
 from substack import nodes
 from substack.nodes import MarkType, NodeType
@@ -31,11 +35,25 @@ _MARK_FOR = {
     "strong": {"type": MarkType.STRONG},
     "em": {"type": MarkType.EM},
     "s": {"type": MarkType.STRIKETHROUGH},
+    "sup": {"type": MarkType.SUPERSCRIPT},
+    "sub": {"type": MarkType.SUBSCRIPT},
 }
 
 
 def _make_parser() -> MarkdownIt:
-    return MarkdownIt("commonmark").use(footnote_plugin).enable("strikethrough")
+    return (
+        MarkdownIt("commonmark")
+        .use(footnote_plugin)
+        # Pandoc-style delimiters: no whitespace just inside the dollars and no
+        # digit just outside them, so paired currency amounts ("$5 ... $10")
+        # stay plain text instead of becoming math.
+        .use(dollarmath_plugin, allow_space=False, allow_digits=False)
+        .use(sub_plugin)
+        .use(superscript_plugin)
+        .use(container_plugin, name="pullquote")
+        .use(container_plugin, name="callout")
+        .enable("strikethrough")
+    )
 
 
 def _coalesce(out_nodes: List[Dict]) -> List[Dict]:
@@ -64,6 +82,8 @@ def _render_inline(node: SyntaxTreeNode, marks: List[Dict], ctx: Dict) -> List[D
                 out.append(nodes.text(child.content, marks))
         elif t == "code_inline":
             out.append(nodes.text(child.content, marks + [nodes.code_mark()]))
+        elif t == "math_inline":
+            out.append(nodes.latex_inline(child.content.strip()))
         elif t in _MARK_FOR:
             out.extend(_render_inline(child, marks + [_MARK_FOR[t]], ctx))
         elif t == "link":
@@ -159,10 +179,28 @@ def _render_block(node: SyntaxTreeNode, api, ctx: Dict) -> List[Dict]:
     if t == "ordered_list":
         return [nodes.ordered_list(_render_list_items(node, api, ctx))]
 
+    # "$$...$$ (label)" tokenizes as math_block_label; Substack has no equation
+    # labels, so it renders like an unlabeled block.
+    if t in ("math_block", "math_block_label"):
+        return [nodes.latex_block(node.content.strip())]
+
+    if t == "container_pullquote":
+        return [nodes.pullquote(_render_container_body(node, api, ctx))]
+
+    if t == "container_callout":
+        return [nodes.callout_block(_render_container_body(node, api, ctx))]
+
     # footnote_block is handled separately in markdown_to_doc; ignore it here.
     return []
 
 
+def _render_container_body(node: SyntaxTreeNode, api, ctx: Dict) -> List[Dict]:
+    body: List[Dict] = []
+    for child in node.children:
+        body.extend(_render_block(child, api, ctx))
+    return body
+
+
 def _render_list_items(list_node: SyntaxTreeNode, api, ctx: Dict) -> List[Dict]:
     items = []
     for li in list_node.children:

substack/nodes.py

@@ -33,6 +33,10 @@ class NodeType:
     FOOTNOTE_ANCHOR = "footnoteAnchor"
     CAPTIONED_IMAGE = "captionedImage"
     CAPTION = "caption"
+    LATEX_BLOCK = "latex_block"
+    LATEX_INLINE = "latex"
+    PULLQUOTE = "pullquote"
+    CALLOUT_BLOCK = "calloutBlock"
 
 
 class MarkType:
@@ -40,6 +44,8 @@ class MarkType:
     EM = "em"
     CODE = "code"
     STRIKETHROUGH = "strikethrough"
+    SUPERSCRIPT = "superscript"
+    SUBSCRIPT = "subscript"
     LINK = "link"
 
 
@@ -146,3 +152,32 @@ def footnote(number: int, paragraphs: List[Dict]) -> Dict:
         "attrs": {"number": number},
         "content": paragraphs or [paragraph()],
     }
+
+
+def latex_block(expression: str) -> Dict:
+    return {
+        "type": NodeType.LATEX_BLOCK,
+        "attrs": {"persistentExpression": expression, "dirty": True},
+    }
+
+
+def latex_inline(expression: str) -> Dict:
+    return {
+        "type": NodeType.LATEX_INLINE,
+        "attrs": {"expression": expression, "persistentExpression": expression},
+    }
+
+
+def pullquote(paragraphs: List[Dict]) -> Dict:
+    return {
+        "type": NodeType.PULLQUOTE,
+        "attrs": {"align": None, "color": None},
+        "content": paragraphs or [paragraph()],
+    }
+
+
+def callout_block(paragraphs: List[Dict]) -> Dict:
+    return {
+        "type": NodeType.CALLOUT_BLOCK,
+        "content": paragraphs or [paragraph()],
+    }

python_substack-0.1.25.dist-info/RECORD

@@ -1,13 +0,0 @@
-substack/__init__.py,sha256=sm5s0r53o_oBjA_3yUob0L4VwXeT8bNuA20PnAjTflI,390
-substack/api.py,sha256=QX9A_7PanQd_Q_QJwnxXM9auIHCtKd7rHbFTDATcm-U,22640
-substack/cli.py,sha256=Hu9tBjyIW9zl7IE92VuZ-MOThS2cLpwXXAOR8Ixsu6o,7708
-substack/exceptions.py,sha256=BbP5W5UpzFcM5SYIxx6snWD_Rmj7F_YjYIYC_r03gZY,911
-substack/mdrender.py,sha256=cB0fLFzOF7CmWHk-9eRvQormP8StqIgy9hYE6CSKPH0,7770
-substack/nodes.py,sha256=eFVxoVwi684g_DLbz8BRHfU7nyHsJb-m8w17UHocXgY,4106
-substack/post.py,sha256=nXeZMAZ6-lx1Qf4yuAlrEQ0lcWFYF2afai1_TxVEl0Q,19704
-substack_mcp/mcp_server.py,sha256=gmevdc59XTBXXMTvVMpYoq66Umlqku1O_uzmw5tMy7o,8405
-python_substack-0.1.25.dist-info/METADATA,sha256=Ero48_tB_HIHbkccKxfKK24rvOJiqlO80SlXItRgpC4,8720
-python_substack-0.1.25.dist-info/WHEEL,sha256=EGEvSphFYqXKs23-kQBeyNoJP1nrT8ZJKQoi5p5DYL8,88
-python_substack-0.1.25.dist-info/entry_points.txt,sha256=la9TUtzyaVksmdSkdKZsg55XIRXx4KjkKW7J3pvBegc,209
-python_substack-0.1.25.dist-info/licenses/LICENSE,sha256=L6jk148I5HhhVbfUvkO3EO7eAoU5zToLio4-ApkCkxg,1062
-python_substack-0.1.25.dist-info/RECORD,,