python-substack 0.1.26__py3-none-any.whl → 0.2.0__py3-none-any.whl

python_substack-0.2.0.dist-info/METADATA

@@ -0,0 +1,273 @@
+Metadata-Version: 2.4
+Name: python-substack
+Version: 0.2.0
+Summary: Write and safely manage Substack drafts from Markdown with Python, CLI, and MCP.
+License: MIT
+License-File: LICENSE
+Keywords: substack,substack-api,cli,newsletter,publishing,automation,mcp
+Author: Paolo Mazza
+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
+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.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
+Project-URL: Homepage, https://github.com/ma2za/python-substack
+Project-URL: Issues, https://github.com/ma2za/python-substack/issues
+Project-URL: Repository, https://github.com/ma2za/python-substack
+Description-Content-Type: text/markdown
+
+# Python Substack
+
+Write Substack posts in Markdown and safely create, inspect, schedule, and
+publish them through Python, a command-line interface, or MCP.
+
+[![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)
+
+> [!IMPORTANT]
+> Creating and publishing are separate operations. `substack drafts create`
+> always creates an unpublished draft. It never schedules, sends, publishes,
+> or deletes content.
+
+## From Markdown to a Substack draft
+
+Install the package:
+
+```bash
+pip install python-substack
+```
+
+Check the selected account and publication:
+
+```bash
+substack status
+```
+
+Create a safe unpublished draft, then publish only when it is ready:
+
+```bash
+substack drafts create post.md
+substack drafts publish 12345 --no-send
+```
+
+Publishing and deletion require confirmation. Noninteractive and JSON
+workflows must pass `--yes` explicitly.
+
+Markdown source:
+
+![Markdown before conversion](docs/before.png)
+
+Substack result:
+
+![Substack after conversion](docs/after.png)
+
+## What it supports
+
+- Create rich Substack drafts from Markdown.
+- Upload local images referenced by Markdown.
+- Set audience, comment permissions, SEO metadata, slug, sections, and tags.
+- List and inspect publications and drafts.
+- 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.
+- Use the same publishing workflow from Python or an optional MCP server.
+
+## Setup
+
+Copy `.env.example` to `.env` and configure one authentication method:
+
+```env
+EMAIL=
+PASSWORD=
+PUBLICATION_URL=
+COOKIES_PATH=
+COOKIES_STRING=
+```
+
+Cookie authentication is usually more reliable when Substack requires captcha
+or magic-link sign-in. See
+[Authentication](docs/authentication.md) for cookie export instructions and
+account-selection details.
+
+Verify the installation without authenticating:
+
+```bash
+substack --version
+substack --help
+```
+
+## CLI
+
+Create a draft with metadata:
+
+```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"
+```
+
+Inspect publications and drafts:
+
+```bash
+substack publications list
+substack drafts list --limit 10
+substack drafts get 12345
+substack --publication-url https://example.substack.com drafts list
+```
+
+Manage scheduling:
+
+```bash
+substack drafts schedule 12345 --at 2026-08-01T09:00:00+03:00
+substack drafts unschedule 12345
+```
+
+Publish or delete intentionally:
+
+```bash
+substack drafts publish 12345 --no-send
+substack drafts delete 12345 --yes
+```
+
+Global options such as `--json`, `--cookies`, and `--publication-url` must
+appear before the command:
+
+```bash
+substack --json drafts list
+substack --cookies cookies.json --json status
+```
+
+The original standalone commands remain supported. See
+[Legacy CLI commands](docs/legacy-cli.md).
+
+## Python
+
+```python
+import os
+
+from dotenv import load_dotenv
+from substack import Api
+
+load_dotenv()
+
+api = Api(
+    email=os.getenv("EMAIL"),
+    password=os.getenv("PASSWORD"),
+    publication_url=os.getenv("PUBLICATION_URL"),
+)
+
+result = api.create_draft_from_markdown(
+    title="Shipping with Python",
+    subtitle="A short note from a script",
+    markdown="""
+# Hello
+
+This draft was created from **Markdown**.
+
+![Alt text](https://example.com/image.png "Image caption")
+""",
+    tags=["python", "automation"],
+    slug="shipping-with-python",
+)
+
+print(result["draft"]["id"])
+```
+
+`create_draft_from_markdown` creates a draft by default. It publishes only when
+`publish=True` is 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).
+
+## Markdown
+
+Supported Markdown includes headings, paragraphs, bold, italic, inline code,
+strikethrough, superscript, subscript, links, images, linked images, image
+captions, code blocks, blockquotes, ordered and unordered lists, horizontal
+rules, footnotes, LaTeX math, pull quotes, and callouts.
+
+```python
+from substack.post import Post
+
+post = Post("Title", "Subtitle", user_id=1)
+post.from_markdown(
+    """
+# Heading
+
+Paragraph with **bold**, *italic*, `code`, and [links](https://example.com).
+"""
+)
+```
+
+Pass `api=` to upload local images while rendering:
+
+```python
+post.from_markdown(markdown_content, api=api)
+```
+
+See the complete [Markdown reference](docs/markdown.md).
+
+## MCP
+
+Install and run the optional MCP server:
+
+```bash
+pip install "python-substack[mcp]"
+substack-mcp
+```
+
+The MCP tools use the same environment variables and SDK behavior as the CLI.
+See [MCP server](docs/mcp.md) for the tool list and safety notes.
+
+## Project documentation
+
+- [Authentication](docs/authentication.md)
+- [Markdown reference](docs/markdown.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)
+- [Compatibility policy](docs/compatibility.md)
+- [Contributing](CONTRIBUTING.md)
+- [Security policy](SECURITY.md)
+- [Changelog](CHANGELOG.md)
+
+## Compatibility
+
+The project preserves existing Python APIs, console commands, CLI behavior,
+environment variables, JSON keys, and MCP tool signatures through the 1.x
+series. Additive capabilities may be introduced. See the
+[compatibility policy](docs/compatibility.md).
+
+## Disclaimer
+
+This project is not affiliated with Substack. It uses undocumented Substack
+interfaces that may change without notice.
+

python_substack-0.2.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+substack/__init__.py,sha256=sg29UCiHYlpsz2E_kYynKEuTpgLYEMUxvy4tUg4opBg,437
+substack/api.py,sha256=5dIijlGDZI5bPgX9skTzytDkY1IO6etvCv6PbNFUjyQ,23212
+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=qDXu-xzO3nRXtahc-yG2EhxKAXB2hG_Z1nLa55UMBGg,19697
+substack_mcp/mcp_server.py,sha256=gmevdc59XTBXXMTvVMpYoq66Umlqku1O_uzmw5tMy7o,8405
+python_substack-0.2.0.dist-info/METADATA,sha256=YfWB49RQARORPNqrOaDaqTBkNYkNs5ANpxyZWlXLE-8,7802
+python_substack-0.2.0.dist-info/WHEEL,sha256=kJCRJT_g0adfAJzTx2GUMmS80rTJIVHRCfG0DQgLq3o,88
+python_substack-0.2.0.dist-info/entry_points.txt,sha256=MKPjaBUd-0PtvxsBviStsVq1c0h8JZ_qUoYEsBK1xJc,236
+python_substack-0.2.0.dist-info/licenses/LICENSE,sha256=L6jk148I5HhhVbfUvkO3EO7eAoU5zToLio4-ApkCkxg,1062
+python_substack-0.2.0.dist-info/RECORD,,

substack/__init__.py

@@ -3,9 +3,11 @@
 __author__ = "Paolo Mazza"
 __email__ = "mazzapaolo2019@gmail.com"
 __license__ = "MIT License"
-__version__ = "0.1.26"
+__version__ = "0.2.0"
 __url__ = "https://github.com/ma2za/python-substack"
 __download_url__ = "https://pypi.python.org/pypi/python-substack"
-__description__ = "A Python SDK and CLI for managing Substack publications and drafts"
+__description__ = (
+    "Write and safely manage Substack drafts from Markdown with Python, CLI, and MCP."
+)
 
 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
@@ -335,7 +348,6 @@ class Api:
         return Api._handle_response(response=response)
 
     def get_publication_subscriber_count(self):
-
         """
         Get subscriber count.
 
@@ -346,7 +358,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 +568,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 +582,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

@@ -276,6 +276,37 @@ def _drafts_get(api, args):
             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)
@@ -370,6 +401,21 @@ def _build_parser():
     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)

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()],
+    }

substack/post.py

@@ -10,8 +10,8 @@ from typing import Dict, List
 
 __all__ = ["Post", "parse_inline", "tokens_to_text_nodes"]
 
-from substack.exceptions import SectionNotExistsException
 from substack import nodes
+from substack.exceptions import SectionNotExistsException
 
 
 def tokens_to_text_nodes(tokens: List[Dict]) -> List[Dict]:
@@ -61,12 +61,12 @@ def parse_inline(text: str) -> List[Dict]:
     tokens = []
 
     # Pattern order matters: code > links > bold+italic > bold > italic > strikethrough
-    code_pattern = r'`([^`]+)`'
-    link_pattern = r'\[([^\]]+)\]\(([^)]+)\)'
-    bold_italic_pattern = r'\*\*\*([^*]+)\*\*\*'
-    bold_pattern = r'\*\*([^*]+)\*\*'
-    italic_pattern = r'(?<!\*)\*([^*]+)\*(?!\*)'  # Not preceded or followed by *
-    strikethrough_pattern = r'~~([^~]+)~~'
+    code_pattern = r"`([^`]+)`"
+    link_pattern = r"\[([^\]]+)\]\(([^)]+)\)"
+    bold_italic_pattern = r"\*\*\*([^*]+)\*\*\*"
+    bold_pattern = r"\*\*([^*]+)\*\*"
+    italic_pattern = r"(?<!\*)\*([^*]+)\*(?!\*)"  # Not preceded or followed by *
+    strikethrough_pattern = r"~~([^~]+)~~"
 
     # Find all matches with their positions
     matches = []
@@ -79,14 +79,18 @@ def parse_inline(text: str) -> List[Dict]:
     for match in re.finditer(link_pattern, text):
         # Skip if it's an image link (starts with ![)
         # But do NOT skip normal links at position 0.
-        if match.start() == 0 or text[match.start()-1:match.start()+1] != "![":
+        if match.start() == 0 or text[match.start() - 1 : match.start() + 1] != "![":
             if not any(start <= match.start() < end for start, end, _, _, _ in matches):
-                matches.append((match.start(), match.end(), "link", match.group(1), match.group(2)))
+                matches.append(
+                    (match.start(), match.end(), "link", match.group(1), match.group(2))
+                )
 
     # Bold+italic combo
     for match in re.finditer(bold_italic_pattern, text):
         if not any(start <= match.start() < end for start, end, _, _, _ in matches):
-            matches.append((match.start(), match.end(), "bold_italic", match.group(1), None))
+            matches.append(
+                (match.start(), match.end(), "bold_italic", match.group(1), None)
+            )
 
     # Bold
     for match in re.finditer(bold_pattern, text):
@@ -101,7 +105,9 @@ def parse_inline(text: str) -> List[Dict]:
     # Strikethrough
     for match in re.finditer(strikethrough_pattern, text):
         if not any(start <= match.start() < end for start, end, _, _, _ in matches):
-            matches.append((match.start(), match.end(), "strikethrough", match.group(1), None))
+            matches.append(
+                (match.start(), match.end(), "strikethrough", match.group(1), None)
+            )
 
     # Sort matches by position
     matches.sort(key=lambda x: x[0])
@@ -115,35 +121,24 @@ def parse_inline(text: str) -> List[Dict]:
 
         # Add the formatted content
         if match_type == "code":
-            tokens.append({
-                "content": content,
-                "marks": [{"type": "code"}]
-            })
+            tokens.append({"content": content, "marks": [{"type": "code"}]})
         elif match_type == "link":
-            tokens.append({
-                "content": content,
-                "marks": [{"type": "link", "attrs": {"href": url}}]
-            })
+            tokens.append(
+                {
+                    "content": content,
+                    "marks": [{"type": "link", "attrs": {"href": url}}],
+                }
+            )
         elif match_type == "bold_italic":
-            tokens.append({
-                "content": content,
-                "marks": [{"type": "strong"}, {"type": "em"}]
-            })
+            tokens.append(
+                {"content": content, "marks": [{"type": "strong"}, {"type": "em"}]}
+            )
         elif match_type == "bold":
-            tokens.append({
-                "content": content,
-                "marks": [{"type": "strong"}]
-            })
+            tokens.append({"content": content, "marks": [{"type": "strong"}]})
         elif match_type == "italic":
-            tokens.append({
-                "content": content,
-                "marks": [{"type": "em"}]
-            })
+            tokens.append({"content": content, "marks": [{"type": "em"}]})
         elif match_type == "strikethrough":
-            tokens.append({
-                "content": content,
-                "marks": [{"type": "strikethrough"}]
-            })
+            tokens.append({"content": content, "marks": [{"type": "strikethrough"}]})
 
         last_pos = end
 
@@ -583,7 +578,9 @@ class Post:
             for chunk in re.split(r"\n\s*\n", content):
                 chunk = chunk.strip()
                 if chunk:
-                    paragraphs.append(nodes.paragraph(tokens_to_text_nodes(parse_inline(chunk))))
+                    paragraphs.append(
+                        nodes.paragraph(tokens_to_text_nodes(parse_inline(chunk)))
+                    )
         elif isinstance(content, list):
             # Accept either parse_inline tokens ({"content": ...}) or text nodes.
             if content and content[0].get("type") == "text":

python_substack-0.1.26.dist-info/METADATA

@@ -1,433 +0,0 @@
-Metadata-Version: 2.4
-Name: python-substack
-Version: 0.1.26
-Summary: A Python SDK and CLI for managing Substack publications and drafts.
-License: MIT
-License-File: LICENSE
-Keywords: substack,substack-api,cli,newsletter,publishing,automation,mcp
-Author: Paolo Mazza
-Author-email: mazzapaolo2019@gmail.com
-Requires-Python: >=3.10,<4.0
-Classifier: Development Status :: 3 - Alpha
-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
-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: 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
-Project-URL: Homepage, https://github.com/ma2za/python-substack
-Project-URL: Issues, https://github.com/ma2za/python-substack/issues
-Project-URL: Repository, https://github.com/ma2za/python-substack
-Description-Content-Type: text/markdown
-
-# Python Substack
-
-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)
-
-## 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.
-- Set audience, comment permissions, SEO title, SEO description, slug, sections, and tags.
-- Publish now, schedule drafts, or keep drafts unpublished by default.
-- Authenticate with email/password, cookies JSON, or a browser cookie string.
-- Run a FastMCP server for AI-assisted publishing workflows.
-
-## Installation
-
-```bash
-pip install python-substack
-```
-
-Install the MCP server extra:
-
-```bash
-pip install "python-substack[mcp]"
-```
-
-## Setup
-
-Copy `.env.example` to `.env` and fill in one authentication method:
-
-```env
-EMAIL=
-PASSWORD=
-PUBLICATION_URL=
-COOKIES_PATH=
-COOKIES_STRING=
-```
-
-Use either `EMAIL` and `PASSWORD`, or cookie-based authentication with `COOKIES_PATH` or `COOKIES_STRING`. Cookie authentication is usually the better option if Substack prompts for captcha or magic-link sign-in.
-
-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
-
-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
-import os
-
-from dotenv import load_dotenv
-from substack import Api
-
-load_dotenv()
-
-api = Api(
-    email=os.getenv("EMAIL"),
-    password=os.getenv("PASSWORD"),
-    publication_url=os.getenv("PUBLICATION_URL"),
-)
-
-result = api.create_draft_from_markdown(
-    title="Shipping with Python",
-    subtitle="A short note from a script",
-    markdown="""
-# Hello
-
-This draft was created from **Markdown**.
-
-![Alt text](https://example.com/image.png "Image caption")
-""",
-    tags=["python", "automation"],
-    slug="shipping-with-python",
-)
-
-print(result["draft"]["id"])
-```
-
-`create_draft_from_markdown` creates a draft by default. It only publishes when `publish=True` is passed.
-
-## Content Publishing CLI
-
-Check authentication without creating a draft:
-
-```bash
-substack-auth-check
-```
-
-With a cookies JSON file:
-
-```bash
-substack-auth-check --cookies cookies.json
-```
-
-Publish a Markdown file as a draft:
-
-```bash
-substack-publish-markdown post.md --title "My Post"
-```
-
-Create and publish:
-
-```bash
-substack-publish-markdown post.md --title "My Post" --publish
-```
-
-Publish from YAML:
-
-```bash
-substack-publish-yaml draft.yaml
-```
-
-Useful options:
-
-```bash
-substack-publish-markdown 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"
-```
-
-## Cookie Authentication
-
-Cookie authentication avoids logging in with email/password on every run and helps when Substack requires captcha or magic-link sign-in.
-
-Use a cookies JSON file:
-
-```python
-import os
-
-from dotenv import load_dotenv
-from substack import Api
-
-load_dotenv()
-
-api = Api(
-    cookies_path=os.getenv("COOKIES_PATH"),
-    publication_url=os.getenv("PUBLICATION_URL"),
-)
-```
-
-Or paste a browser cookie header into `COOKIES_STRING`:
-
-```python
-import os
-
-from dotenv import load_dotenv
-from substack import Api
-
-load_dotenv()
-
-api = Api(
-    cookies_string=os.getenv("COOKIES_STRING"),
-    publication_url=os.getenv("PUBLICATION_URL"),
-)
-```
-
-To get a cookie string:
-
-1. Sign in to Substack in your browser.
-2. Open developer tools.
-3. Go to the network tab and refresh Substack.
-4. Select a request such as `subscription/unred/subscriptions`.
-5. Copy the full `cookie` request header value into `COOKIES_STRING`.
-
-To export a working session to a cookies JSON file:
-
-```python
-api.export_cookies("cookies.json")
-```
-
-Then set:
-
-```env
-COOKIES_PATH=cookies.json
-```
-
-The CLI also accepts a cookie JSON path:
-
-```bash
-substack-publish-markdown post.md --cookies cookies.json
-```
-
-## Low-Level Post Builder
-
-```python
-import os
-
-from dotenv import load_dotenv
-from substack import Api
-from substack.post import Post
-
-load_dotenv()
-
-api = Api(
-    email=os.getenv("EMAIL"),
-    password=os.getenv("PASSWORD"),
-    publication_url=os.getenv("PUBLICATION_URL"),
-)
-
-user_id = api.get_user_id()
-
-post = Post(
-    title="How to publish a Substack post using Python",
-    subtitle="Created with python-substack",
-    user_id=user_id,
-    audience="everyone",
-    write_comment_permissions="everyone",
-)
-
-post.paragraph("This is a paragraph.")
-post.add(
-    {
-        "type": "paragraph",
-        "content": [
-            {"content": "A link to "},
-            {
-                "content": "Substack",
-                "marks": [{"type": "link", "href": "https://substack.com"}],
-            },
-        ],
-    }
-)
-post.add({"type": "paywall"})
-post.add({"type": "captionedImage", "src": "https://example.com/image.png"})
-
-draft = api.post_draft(post.get_draft())
-api.prepublish_draft(draft.get("id"))
-api.publish_draft(draft.get("id"))
-```
-
-## Markdown Support
-
-```python
-from substack.post import Post
-
-post = Post("Title", "Subtitle", user_id=1)
-post.from_markdown(
-    """
-# Heading
-
-Paragraph with **bold**, *italic*, `code`, [links](https://example.com), and footnotes.[^1]
-
-- Lists
-- Images
-
-![Alt](local-image.png "Caption")
-
-[^1]: Footnote text.
-"""
-)
-```
-
-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.
-
-When an `Api` instance is passed to `from_markdown`, local image paths are uploaded before the draft is created:
-
-```python
-post.from_markdown(markdown_content, api=api)
-```
-
-## YAML Drafts
-
-```yaml
-title: "My Post Title"
-subtitle: "My Post Subtitle"
-audience: "everyone"
-write_comment_permissions: "everyone"
-search_engine_title: "SEO title"
-search_engine_description: "SEO description"
-slug: "my-post-title"
-tags:
-  - python
-  - substack
-markdown: |
-  # Introduction
-
-  This post body is Markdown.
-```
-
-The lower-level node format is also supported:
-
-```yaml
-title: "My Post Title"
-subtitle: "My Post Subtitle"
-body:
-  0:
-    type: "heading"
-    level: 1
-    content: "Introduction"
-  1:
-    type: "paragraph"
-    content: "This is a paragraph."
-  2:
-    type: "captionedImage"
-    src: "local_image.jpg"
-```
-
-## MCP Server
-
-Install the MCP extra:
-
-```bash
-pip install "python-substack[mcp]"
-```
-
-Run the server over stdio:
-
-```bash
-substack-mcp
-```
-
-Equivalent Python entry point:
-
-```bash
-python -c "from substack_mcp.mcp_server import main; main()"
-```
-
-Available tools:
-
-- `post_draft_from_markdown(...)`
-- `put_draft(draft_id, update_payload)`
-- `add_tags(draft_id, tags)`
-- `prepublish_draft(draft_id)`
-- `publish_draft(draft_id, send=True, share_automatically=False)`
-
-## Development
-
-```bash
-pip install pre-commit
-pre-commit install
-pytest
-```
-
-Live Substack tests are opt-in. Set `RUN_SUBSTACK_E2E=1` and configure credentials before running them.
-
-The CLI operations smoke test is separately opt-in. Set `RUN_SUBSTACK_CLI_E2E=1` to create, schedule, unschedule, inspect, and delete a disposable draft. It never publishes the draft.
-
-Release changes are tracked in [CHANGELOG.md](CHANGELOG.md).
-
-## Disclaimer
-
-This project is not affiliated with Substack.
-

python_substack-0.1.26.dist-info/RECORD

@@ -1,13 +0,0 @@
-substack/__init__.py,sha256=6wfj_pMsGW4d-y6wyswxGMMQtu0q41tmalHchGkzOyY,416
-substack/api.py,sha256=QX9A_7PanQd_Q_QJwnxXM9auIHCtKd7rHbFTDATcm-U,22640
-substack/cli.py,sha256=F6ba6mgrBzoHXpwNTgUv8JMRmSKgdP7AHpm89keC8EM,19911
-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.26.dist-info/METADATA,sha256=mw0CiIItyXlZt5jODivLqwcHtMFILPpHZCEJKcsysR4,10702
-python_substack-0.1.26.dist-info/WHEEL,sha256=kJCRJT_g0adfAJzTx2GUMmS80rTJIVHRCfG0DQgLq3o,88
-python_substack-0.1.26.dist-info/entry_points.txt,sha256=MKPjaBUd-0PtvxsBviStsVq1c0h8JZ_qUoYEsBK1xJc,236
-python_substack-0.1.26.dist-info/licenses/LICENSE,sha256=L6jk148I5HhhVbfUvkO3EO7eAoU5zToLio4-ApkCkxg,1062
-python_substack-0.1.26.dist-info/RECORD,,