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

python_substack-0.1.26.dist-info/METADATA

@@ -0,0 +1,433 @@
+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

@@ -0,0 +1,13 @@
+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,,

{python_substack-0.1.24.dist-info → python_substack-0.1.26.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.26.dist-info/entry_points.txt

@@ -0,0 +1,7 @@
+[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-publish-yaml=substack.cli:publish_yaml
+

substack/__init__.py

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

@@ -9,7 +9,7 @@ import json
 import logging
 import os
 from datetime import datetime
-from urllib.parse import urljoin, unquote
+from urllib.parse import unquote, urljoin
 
 import requests
 
@@ -111,20 +111,20 @@ class Api:
     def _parse_cookies_string(cookies_string: str) -> dict:
         """
         Parse a semicolon-separated cookie string into a dictionary.
-        
+
         Args:
             cookies_string: A semicolon-separated string of cookies (e.g., "cookie1=value1; cookie2=value2")
-            
+
         Returns:
             A dictionary of cookie name-value pairs
         """
         cookies = {}
-        for cookie_pair in cookies_string.split(';'):
+        for cookie_pair in cookies_string.split(";"):
             cookie_pair = cookie_pair.strip()
             if not cookie_pair:
                 continue
-            if '=' in cookie_pair:
-                key, value = cookie_pair.split('=', 1)
+            if "=" in cookie_pair:
+                key, value = cookie_pair.split("=", 1)
                 key = key.strip()
                 value = value.strip()
                 # URL decode the value (e.g., s%3A becomes s:)
@@ -132,6 +132,14 @@ class Api:
                 cookies[key] = value
         return cookies
 
+    @staticmethod
+    def _normalize_tags(tags):
+        if tags is None:
+            return []
+        if isinstance(tags, str):
+            return [tags]
+        return [str(tag) for tag in tags]
+
     def login(self, email, password) -> dict:
         """
 
@@ -224,7 +232,7 @@ class Api:
             publication:
         """
         custom_domain = publication.get("custom_domain", None)
-        if not custom_domain and not publication.get('custom_domain_optional', None):
+        if not custom_domain and not publication.get("custom_domain_optional", None):
             publication_url = f"https://{publication['subdomain']}.substack.com"
         else:
             publication_url = f"https://{custom_domain}"
@@ -238,9 +246,12 @@ class Api:
 
         profile = self.get_user_profile()
         primary_publication = None
-        
+
         # Try old API format first (backward compatibility)
-        if "primaryPublication" in profile and profile["primaryPublication"] is not None:
+        if (
+            "primaryPublication" in profile
+            and profile["primaryPublication"] is not None
+        ):
             primary_publication = profile["primaryPublication"]
         else:
             # New API format: look for primary publication in publicationUsers
@@ -252,16 +263,16 @@ class Api:
                         primary_publication = pub_user.get("publication")
                         if primary_publication:
                             break
-                
+
                 # If no primary found, use the first publication
                 if primary_publication is None:
                     primary_publication = publication_users[0].get("publication")
-        
+
         if primary_publication is None:
             raise SubstackRequestException(
                 "Could not find primary publication in profile"
             )
-            
+
         primary_publication["publication_url"] = self.get_publication_url(
             primary_publication
         )
@@ -279,12 +290,12 @@ class Api:
         # of dictionaries of "name", and "subdomain", and "id"
         user_publications = []
         publication_users = profile.get("publicationUsers")
-        
+
         if publication_users is None:
             # If publicationUsers is None, return empty list or try to construct from other fields
             # This maintains backward compatibility while handling new API format
             return user_publications
-        
+
         for publication in publication_users:
             pub = publication.get("publication")
             if pub is not None:
@@ -414,6 +425,73 @@ class Api:
         response = self._session.post(f"{self.publication_url}/drafts", json=body)
         return Api._handle_response(response=response)
 
+    def create_draft_from_markdown(
+        self,
+        title: str,
+        markdown: str,
+        subtitle: str = "",
+        audience: str = "everyone",
+        write_comment_permissions: str = "everyone",
+        search_engine_title: str = None,
+        search_engine_description: str = None,
+        slug: str = None,
+        draft_section_id: int = None,
+        tags=None,
+        prepublish: bool = False,
+        publish: bool = False,
+        send: bool = True,
+        share_automatically: bool = False,
+    ) -> dict:
+        from substack.post import Post
+
+        post = Post(
+            title=title,
+            subtitle=subtitle or "",
+            user_id=self.get_user_id(),
+            audience=audience,
+            write_comment_permissions=write_comment_permissions,
+        )
+        post.from_markdown(markdown, api=self)
+
+        draft = self.post_draft(post.get_draft())
+        draft_id = draft.get("id")
+
+        update_payload = {
+            "search_engine_title": search_engine_title,
+            "search_engine_description": search_engine_description,
+            "slug": slug,
+            "draft_section_id": draft_section_id,
+        }
+        update_payload = {
+            key: value for key, value in update_payload.items() if value is not None
+        }
+        if update_payload:
+            draft = self.put_draft(draft_id, **update_payload)
+
+        tags_result = None
+        tags_list = self._normalize_tags(tags)
+        if tags_list:
+            tags_result = self.add_tags_to_post(draft_id, tags_list)
+
+        prepublish_result = None
+        if prepublish:
+            prepublish_result = self.prepublish_draft(draft_id)
+
+        publish_result = None
+        if publish:
+            publish_result = self.publish_draft(
+                draft_id,
+                send=send,
+                share_automatically=share_automatically,
+            )
+
+        return {
+            "draft": draft,
+            "tags": tags_result,
+            "prepublish": prepublish_result,
+            "publish": publish_result,
+        }
+
     def put_draft(self, draft, **kwargs) -> dict:
         """
 
@@ -514,7 +592,7 @@ class Api:
             data={"image": image},
         )
         return Api._handle_response(response=response)
-    
+
     def add_tags_to_post(self, post_id: int, tag_names: list) -> dict:
         """
         Add multiple tags to a post.
@@ -575,7 +653,6 @@ class Api:
         )
         return Api._handle_response(apply_tag_response)
 
-
     def get_categories(self):
         """