python-substack 0.1.27__tar.gz → 0.2.0__tar.gz

python_substack-0.2.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,237 @@
+# 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.1.27 → python_substack-0.2.0}/pyproject.toml

@@ -1,7 +1,7 @@
 [tool.poetry]
 name = "python-substack"
-version = "0.1.27"
-description = "A Python SDK and CLI for managing Substack publications and drafts."
+version = "0.2.0"
+description = "Write and safely manage Substack drafts from Markdown with Python, CLI, and MCP."
 authors = ["Paolo Mazza <mazzapaolo2019@gmail.com>"]
 license = "MIT"
 packages = [
@@ -16,7 +16,7 @@ homepage = "https://github.com/ma2za/python-substack"
 
 keywords = ["substack", "substack-api", "cli", "newsletter", "publishing", "automation", "mcp"]
 classifiers = [
-    "Development Status :: 3 - Alpha",
+    "Development Status :: 4 - Beta",
     "Intended Audience :: Developers",
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3.10",
@@ -47,6 +47,7 @@ mcp = ["fastmcp"]
 
 [tool.poetry.group.dev.dependencies]
 pytest = "^9.1.1"
+pre-commit = "^4.6.1"
 
 [tool.pytest.ini_options]
 markers = [

{python_substack-0.1.27 → python_substack-0.2.0}/substack/__init__.py

@@ -3,9 +3,11 @@
 __author__ = "Paolo Mazza"
 __email__ = "mazzapaolo2019@gmail.com"
 __license__ = "MIT License"
-__version__ = "0.1.27"
+__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

{python_substack-0.1.27 → python_substack-0.2.0}/substack/api.py

@@ -348,7 +348,6 @@ class Api:
         return Api._handle_response(response=response)
 
     def get_publication_subscriber_count(self):
-
         """
         Get subscriber count.
 

{python_substack-0.1.27 → python_substack-0.2.0}/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":