Release 0.1.27 Markdown CLI and reliability

Author: ma2za

.github/workflows/ci.yml

@@ -27,35 +27,50 @@ jobs:
           python -m pip install poetry==2.3.2
           poetry install --all-extras
       - name: Run tests
-        run: poetry run pytest -q
+        run: poetry run pytest -q -m "not live" --strict-markers
 
-  build:
+  package:
     needs: test
     runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.14"]
     steps:
       - uses: actions/checkout@v6
       - uses: actions/setup-python@v6
         with:
-          python-version: "3.12"
+          python-version: ${{ matrix.python-version }}
           cache: pip
       - name: Install build tools
         run: python -m pip install poetry==2.3.2 twine==6.2.0
+      - name: Verify test collection
+        run: |
+          poetry install --all-extras
+          poetry run pytest --collect-only -q --strict-markers
       - name: Validate and build package
         run: |
           poetry check
           poetry build
           python -m twine check dist/*
-      - name: Smoke test wheel installations
+      - name: Smoke test base wheel installation
         run: |
           WHEEL=$(find dist -name '*.whl' -print -quit)
           python -m venv /tmp/python-substack-base
           /tmp/python-substack-base/bin/pip install "$WHEEL"
+          /tmp/python-substack-base/bin/pip check
           /tmp/python-substack-base/bin/substack --version
-          /tmp/python-substack-base/bin/python -c "import substack"
+          /tmp/python-substack-base/bin/python -c "import importlib.util; assert importlib.util.find_spec('fastmcp') is None"
+          /tmp/python-substack-base/bin/python -c "from importlib import metadata; import substack; expected={'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','substack-mcp':'substack_mcp.mcp_server:main'}; actual={entry.name:entry.value for entry in metadata.entry_points(group='console_scripts') if entry.name in expected}; package=metadata.metadata('python-substack'); requirements=metadata.requires('python-substack'); assert actual == expected; assert metadata.version('python-substack') == substack.__version__; assert package['Requires-Python'] == '>=3.10,<4.0'; assert package.get_all('Provides-Extra') == ['mcp']; assert all(any(requirement.startswith(name) for requirement in requirements) for name in ['PyYAML','fastmcp','markdown-it-py','mdit-py-plugins','python-dotenv','requests'])"
+      - name: Smoke test MCP wheel installation
+        run: |
+          WHEEL=$(find dist -name '*.whl' -print -quit)
           python -m venv /tmp/python-substack-mcp
           /tmp/python-substack-mcp/bin/pip install "${WHEEL}[mcp]"
+          /tmp/python-substack-mcp/bin/pip check
           /tmp/python-substack-mcp/bin/python -c "import substack_mcp.mcp_server"
       - uses: actions/upload-artifact@v7
+        if: matrix.python-version == '3.14'
         with:
           name: python-substack-distributions
           path: dist/

.github/workflows/ci_publish.yml

@@ -20,15 +20,39 @@ jobs:
           cache: pip
       - name: Install release tools
         run: python -m pip install poetry==2.3.2 twine==6.2.0
+      - name: Validate tag and package versions
+        run: |
+          VERSION=$(poetry version -s)
+          PACKAGE_VERSION=$(python -c "import pathlib, re; print(re.search(r'__version__ = \"([^\"]+)\"', pathlib.Path('substack/__init__.py').read_text()).group(1))")
+          test "$VERSION" = "$PACKAGE_VERSION"
+          test "$GITHUB_REF_TYPE" = "tag"
+          test "$GITHUB_REF_NAME" = "v$VERSION"
       - name: Test release source
         run: |
           poetry install --all-extras
-          poetry run pytest -q
+          poetry run pytest -q -m "not live" --strict-markers
+          poetry run pytest --collect-only -q --strict-markers
           poetry check
       - name: Build and validate distributions
         run: |
           poetry build
           python -m twine check dist/*
+      - name: Smoke test base wheel installation
+        run: |
+          WHEEL=$(find dist -name '*.whl' -print -quit)
+          python -m venv /tmp/python-substack-base
+          /tmp/python-substack-base/bin/pip install "$WHEEL"
+          /tmp/python-substack-base/bin/pip check
+          /tmp/python-substack-base/bin/substack --version
+          /tmp/python-substack-base/bin/python -c "import importlib.util; assert importlib.util.find_spec('fastmcp') is None"
+          /tmp/python-substack-base/bin/python -c "from importlib import metadata; import substack; expected={'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','substack-mcp':'substack_mcp.mcp_server:main'}; actual={entry.name:entry.value for entry in metadata.entry_points(group='console_scripts') if entry.name in expected}; package=metadata.metadata('python-substack'); requirements=metadata.requires('python-substack'); assert actual == expected; assert metadata.version('python-substack') == substack.__version__; assert package['Requires-Python'] == '>=3.10,<4.0'; assert package.get_all('Provides-Extra') == ['mcp']; assert all(any(requirement.startswith(name) for requirement in requirements) for name in ['PyYAML','fastmcp','markdown-it-py','mdit-py-plugins','python-dotenv','requests'])"
+      - name: Smoke test MCP wheel installation
+        run: |
+          WHEEL=$(find dist -name '*.whl' -print -quit)
+          python -m venv /tmp/python-substack-mcp
+          /tmp/python-substack-mcp/bin/pip install "${WHEEL}[mcp]"
+          /tmp/python-substack-mcp/bin/pip check
+          /tmp/python-substack-mcp/bin/python -c "import substack_mcp.mcp_server"
       - name: Publish validated distributions
         uses: pypa/gh-action-pypi-publish@release/v1
         with:

CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 0.1.27
+
+### Added
+
+- Unified `substack drafts create MARKDOWN_FILE` command for safe draft-only Markdown creation.
+- Markdown rendering for LaTeX, superscript, subscript, pull quotes, and callouts.
+- Registered `live` test marker with documented opt-in API and CLI smoke commands.
+
+### Fixed
+
+- Support Substack subscriber responses that provide a `subscribers` list instead of `subscriberCount`.
+- Use Substack's current scheduled-release endpoint for scheduling and unscheduling drafts.
+- Retry rate-limited GET and DELETE requests with bounded backoff without retrying write-producing POST requests.
+
+### Improved
+
+- Validate offline tests separately from live integrations.
+- Validate wheel metadata, console entry points, base installations, and MCP-extra installations on Python 3.10 and 3.14.
+- Require release tags, package metadata, and `substack.__version__` to agree before publishing.
+
 ## 0.1.26
 
 ### Added

README.md

@@ -52,6 +52,33 @@ Newer Substack accounts may only have magic-link sign-in enabled. To set a passw
 
 ## 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
@@ -128,7 +155,9 @@ print(result["draft"]["id"])
 
 `create_draft_from_markdown` creates a draft by default. It only publishes when `publish=True` is passed.
 
-## Content Publishing CLI
+## Legacy Content Publishing CLI
+
+The existing standalone commands remain supported for compatibility.
 
 Check authentication without creating a draft:
 
@@ -386,11 +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"
+```
 
-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.
+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
 

docs/markdown.md

@@ -139,7 +139,8 @@ Delimiters follow Pandoc's rules: the opening `$` must not be followed by
 whitespace, and the closing `$` must not be preceded by whitespace or followed
 by a digit. Ordinary dollar amounts (`$5 million to $10 million`) therefore
 stay plain text. A label after a block (`$$ ... $$ (label)`) is accepted but
-discarded, since Substack has no equation labels.
+discarded, since Substack has no equation labels. Unclosed math delimiters remain
+plain text.
 
 ## Pull quotes and callouts
 
@@ -156,6 +157,9 @@ A callout block, e.g. an aside or note.
 :::
 ```
 
+Empty pull quotes and callouts produce an empty paragraph so the resulting
+document remains valid. Unknown `:::` container names remain ordinary text.
+
 ## Not supported
 
 - **Tables** — Substack has no table renderer or editor UI for them, so GFM

docs/releases/0.1.27.md

@@ -0,0 +1,47 @@
+# python-substack 0.1.27
+
+Version 0.1.27 turns a Markdown file into a rich Substack draft through the
+main CLI and strengthens package validation around that workflow.
+
+## Highlights
+
+- Create an unpublished draft with `substack drafts create post.md`.
+- Set title, subtitle, audience, comment permissions, SEO metadata, slug,
+  section, and repeatable tags from the unified CLI.
+- Render inline and block LaTeX, superscript, subscript, pull quotes, and
+  callouts from Markdown.
+- Handle both known subscriber-count response formats.
+- Restore draft scheduling and unscheduling against Substack's current endpoint.
+- Retry rate-limited reads and deletes with bounded backoff while avoiding unsafe POST retries.
+- Keep live Substack tests opt-in while validating offline tests on Python 3.10
+  through 3.14 and clean wheel installations on Python 3.10 and 3.14.
+
+Existing Python APIs, MCP tools, environment variables, standalone console
+commands, defaults, and CLI output contracts remain available.
+
+## Quick examples
+
+```bash
+substack drafts create post.md
+substack --json drafts create post.md --tag python --tag substack
+substack drafts publish 12345 --no-send
+```
+
+Creation never publishes, schedules, sends, or deletes a draft. Publishing
+remains a separate command with the existing confirmation safeguards. If tag
+assignment fails after Substack creates the draft, the draft may remain in the
+publication and is not deleted automatically.
+
+## Observable Markdown changes
+
+Text matching the new `$...$`, `$$...$$`, `^...^`, `~...~`, `:::pullquote`,
+or `:::callout` syntax now produces corresponding Substack document nodes.
+Ordinary currency amounts remain text, and `~~...~~` remains strikethrough.
+
+## Announcement copy
+
+python-substack 0.1.27 can now turn a Markdown file directly into a rich,
+unpublished Substack draft with `substack drafts create post.md`. The release
+adds LaTeX, superscript, subscript, pull quotes, and callouts, while strengthening
+clean-install and release validation. Install it with
+`pip install -U python-substack`.

docs/releasing.md

@@ -0,0 +1,30 @@
+# Release checklist
+
+1. Keep `pyproject.toml` and `substack/__init__.py` on the previous version
+   while implementing code, tests, workflows, and documentation.
+2. Run `poetry install --all-extras`.
+3. Run `poetry run pytest -q -m "not live" --strict-markers`.
+4. Run `poetry run pytest -q` with live opt-ins unset and confirm all live tests
+   are skipped.
+5. With configured maintainer credentials, run:
+
+   ```bash
+   RUN_SUBSTACK_E2E=1 poetry run pytest -q -m live
+   RUN_SUBSTACK_CLI_E2E=1 poetry run pytest -q -m live tests/substack/test_cli_end_to_end.py
+   ```
+
+6. Update `pyproject.toml`, `substack.__version__`, `CHANGELOG.md`, and the
+   release page to the target version.
+7. From a clean checkout, run `poetry check`, `poetry build`, and
+   `poetry run python -m twine check dist/*`.
+8. Install the wheel in fresh base and `[mcp]` virtual environments, run
+   `pip check`, verify all five console entry points, and import the base and MCP
+   modules.
+9. Push only after CI passes. Create `vX.Y.Z` from that exact commit; the publish
+   workflow rejects a tag that differs from either package version.
+10. After publishing, install `python-substack==X.Y.Z` from PyPI in a clean
+    environment and repeat the smoke checks before announcing.
+
+Live tests create disposable drafts and must never publish. Confirm cleanup in
+the publication after each run. If an artifact is defective, yank it rather
+than attempting to replace the same version.

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "python-substack"
-version = "0.1.26"
+version = "0.1.27"
 description = "A Python SDK and CLI for managing Substack publications and drafts."
 authors = ["Paolo Mazza <mazzapaolo2019@gmail.com>"]
 license = "MIT"
@@ -48,6 +48,11 @@ 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/__init__.py

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

substack/api.py

@@ -12,6 +12,7 @@
 from urllib.parse import unquote, urljoin
 
 import requests
+from requests.adapters import HTTPAdapter, Retry
 
 from substack.exceptions import SubstackAPIException, SubstackRequestException
 
@@ -65,6 +66,18 @@ def __init__(
             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
@@ -556,8 +569,8 @@ def schedule_draft(self, draft, draft_datetime: datetime) -> dict:
 
         """
         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)
 
@@ -570,8 +583,8 @@ def unschedule_draft(self, draft) -> dict:
         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)