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

{python_substack-0.1.25 → python_substack-0.1.27}/PKG-INFO

@@ -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.25 → python_substack-0.1.27}/README.md

@@ -1,12 +1,19 @@
 # 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.
@@ -43,6 +50,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
@@ -78,7 +155,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:
 
@@ -255,7 +334,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:
 
@@ -336,9 +415,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.25 → python_substack-0.1.27}/pyproject.toml

@@ -1,7 +1,7 @@
 [tool.poetry]
 name = "python-substack"
-version = "0.1.25"
-description = "A Python wrapper around the Substack API."
+version = "0.1.27"
+description = "A Python SDK and CLI for managing Substack publications and drafts."
 authors = ["Paolo Mazza <mazzapaolo2019@gmail.com>"]
 license = "MIT"
 packages = [
@@ -14,7 +14,7 @@ readme = "README.md"
 repository = "https://github.com/ma2za/python-substack"
 homepage = "https://github.com/ma2za/python-substack"
 
-keywords = ["substack"]
+keywords = ["substack", "substack-api", "cli", "newsletter", "publishing", "automation", "mcp"]
 classifiers = [
     "Development Status :: 3 - Alpha",
     "Intended Audience :: Developers",
@@ -39,15 +39,22 @@ requests = "^2.32.0"
 python-dotenv = "^1.2.1"
 PyYAML = "^6.0"
 markdown-it-py = "^3.0"
-mdit-py-plugins = "^0.4"
+mdit-py-plugins = ">=0.5,<0.7"
 fastmcp = { version = "^3.1.1", optional = true }
 
 [tool.poetry.extras]
 mcp = ["fastmcp"]
 
 [tool.poetry.group.dev.dependencies]
+pytest = "^9.1.1"
+
+[tool.pytest.ini_options]
+markers = [
+    "live: opt-in tests that call the live Substack service",
+]
 
 [tool.poetry.scripts]
+substack = "substack.cli:main"
 substack-auth-check = "substack.cli:auth_check"
 substack-publish-markdown = "substack.cli:publish_markdown"
 substack-publish-yaml = "substack.cli:publish_yaml"

{python_substack-0.1.25 → python_substack-0.1.27}/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

{python_substack-0.1.25 → python_substack-0.1.27}/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)