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

{python_substack-0.1.25.dist-info → python_substack-0.1.26.dist-info}/METADATA

@@ -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.26
+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
@@ -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,49 @@ 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
+
+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 +163,7 @@ print(result["draft"]["id"])
 
 `create_draft_from_markdown` creates a draft by default. It only publishes when `publish=True` is passed.
 
-## CLI
+## Content Publishing CLI
 
 Check authentication without creating a draft:
 
@@ -373,6 +423,8 @@ 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

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.25.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.25.dist-info → python_substack-0.1.26.dist-info}/entry_points.txt

@@ -1,4 +1,5 @@
 [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/__init__.py

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

@@ -1,32 +1,41 @@
 import argparse
 import json
 import os
+import sys
+from datetime import datetime
 from pathlib import Path
+from urllib.parse import urljoin
 
 import yaml
 from dotenv import load_dotenv
 
-from substack import Api
+from substack import Api, __version__
+from substack.exceptions import SubstackAPIException, SubstackRequestException
 from substack.post import Post
 
 
-def _api_from_env(cookies_path=None):
+class CLIUsageError(Exception):
+    pass
+
+
+def _api_from_env(cookies_path=None, publication_url=None):
     load_dotenv()
 
     cookies_path = cookies_path or os.getenv("COOKIES_PATH")
     cookies_string = os.getenv("COOKIES_STRING")
+    publication_url = publication_url or os.getenv("PUBLICATION_URL")
 
     if cookies_path or cookies_string:
         return Api(
             cookies_path=cookies_path,
             cookies_string=cookies_string,
-            publication_url=os.getenv("PUBLICATION_URL"),
+            publication_url=publication_url,
         )
 
     return Api(
         email=os.getenv("EMAIL"),
         password=os.getenv("PASSWORD"),
-        publication_url=os.getenv("PUBLICATION_URL"),
+        publication_url=publication_url,
     )
 
 
@@ -56,6 +65,356 @@ def _print_result(result):
     print(json.dumps({"draft_id": draft.get("id"), "draft": draft}, indent=2))
 
 
+def _print_json(value, stream=None):
+    print(json.dumps(value, indent=2, default=str), file=stream)
+
+
+def _display(value):
+    if value is None or value == "":
+        return "-"
+    return str(value)
+
+
+def _print_rows(headers, rows):
+    rows = [[_display(value) for value in row] for row in rows]
+    widths = [len(header) for header in headers]
+    for row in rows:
+        for index, value in enumerate(row):
+            widths[index] = max(widths[index], len(value))
+
+    print(
+        "  ".join(header.ljust(widths[index]) for index, header in enumerate(headers))
+    )
+    print("  ".join("-" * width for width in widths))
+    for row in rows:
+        print("  ".join(value.ljust(widths[index]) for index, value in enumerate(row)))
+
+
+def _identity(profile):
+    return (
+        profile.get("email")
+        or profile.get("name")
+        or profile.get("handle")
+        or str(profile.get("id", "unknown"))
+    )
+
+
+def _selected_publication(api, publications):
+    for publication in publications:
+        publication_url = publication.get("publication_url")
+        if (
+            publication_url
+            and urljoin(publication_url, "api/v1") == api.publication_url
+        ):
+            return publication
+    return {"publication_url": api.publication_url.removesuffix("/api/v1")}
+
+
+def _parse_schedule(value):
+    normalized = value[:-1] + "+00:00" if value.endswith(("Z", "z")) else value
+    try:
+        scheduled_at = datetime.fromisoformat(normalized)
+    except ValueError as exc:
+        raise CLIUsageError("--at must be a valid ISO 8601 timestamp") from exc
+    if scheduled_at.utcoffset() is None:
+        raise CLIUsageError("--at must include a timezone offset or Z")
+    return scheduled_at
+
+
+def _confirm(action, target, yes, json_output):
+    if yes:
+        return
+    if json_output or not sys.stdin.isatty():
+        raise CLIUsageError(f"{action} requires --yes in non-interactive or JSON mode")
+    try:
+        confirmed = input(f"{action} draft {target}? [y/N] ").strip().lower()
+    except EOFError as exc:
+        raise CLIUsageError(f"{action} requires confirmation or --yes") from exc
+    if confirmed not in {"y", "yes"}:
+        raise CLIUsageError("Cancelled")
+
+
+def _redact(message):
+    redacted = str(message)
+    for name in ("EMAIL", "PASSWORD", "COOKIES_STRING"):
+        secret = os.getenv(name)
+        if secret:
+            redacted = redacted.replace(secret, "[redacted]")
+    return redacted
+
+
+def _error_payload(exc):
+    if isinstance(exc, SubstackAPIException):
+        return {
+            "error": {
+                "type": "api_error",
+                "message": _redact(exc.message),
+                "status_code": exc.status_code,
+            }
+        }
+    if isinstance(exc, SubstackRequestException):
+        return {
+            "error": {
+                "type": "request_error",
+                "message": _redact(exc.message),
+            }
+        }
+    if isinstance(exc, OSError):
+        return {"error": {"type": "io_error", "message": _redact(exc)}}
+    return {"error": {"type": "configuration_error", "message": _redact(exc)}}
+
+
+def _print_error(exc, json_output):
+    payload = _error_payload(exc)
+    if json_output:
+        _print_json(payload, stream=sys.stderr)
+    else:
+        print(f"Error: {payload['error']['message']}", file=sys.stderr)
+
+
+def _print_usage_error(exc, json_output):
+    if json_output:
+        _print_json(
+            {"error": {"type": "usage_error", "message": str(exc)}},
+            stream=sys.stderr,
+        )
+    else:
+        print(f"Error: {exc}", file=sys.stderr)
+
+
+def _status(api, args):
+    profile = api.get_user_profile()
+    publications = api.get_user_publications()
+    selected = _selected_publication(api, publications)
+    subscriber_count = api.get_publication_subscriber_count()
+    result = {
+        "status": {
+            "identity": _identity(profile),
+            "auth_method": _auth_method(args.cookies),
+            "subscriber_count": subscriber_count,
+        },
+        "profile": profile,
+        "publication": selected,
+        "publications": publications,
+    }
+    if args.json_output:
+        _print_json(result)
+    else:
+        print(f"Authenticated as: {result['status']['identity']}")
+        print(f"Auth method: {result['status']['auth_method']}")
+        print(f"Publication: {_display(selected.get('name'))}")
+        print(f"Publication URL: {_display(selected.get('publication_url'))}")
+        print(f"Subscribers: {subscriber_count}")
+        print(f"Available publications: {len(publications)}")
+
+
+def _publications_list(api, args):
+    publications = api.get_user_publications()
+    if args.json_output:
+        _print_json({"publications": publications, "count": len(publications)})
+    else:
+        _print_rows(
+            ["ID", "NAME", "SUBDOMAIN", "URL"],
+            [
+                [
+                    publication.get("id"),
+                    publication.get("name"),
+                    publication.get("subdomain"),
+                    publication.get("publication_url"),
+                ]
+                for publication in publications
+            ],
+        )
+
+
+def _drafts_list(api, args):
+    if args.offset < 0:
+        raise CLIUsageError("--offset must be zero or greater")
+    if args.limit < 1:
+        raise CLIUsageError("--limit must be greater than zero")
+    drafts = api.get_drafts(filter=args.filter, offset=args.offset, limit=args.limit)
+    if args.json_output:
+        _print_json(
+            {
+                "drafts": drafts,
+                "count": len(drafts),
+                "filter": args.filter,
+                "offset": args.offset,
+                "limit": args.limit,
+            }
+        )
+    else:
+        _print_rows(
+            ["ID", "TITLE", "STATUS", "SCHEDULED"],
+            [
+                [
+                    draft.get("id"),
+                    draft.get("draft_title") or draft.get("title"),
+                    draft.get("type") or draft.get("status") or "draft",
+                    draft.get("post_date"),
+                ]
+                for draft in drafts
+            ],
+        )
+
+
+def _drafts_get(api, args):
+    draft = api.get_draft(args.draft_id)
+    if args.json_output:
+        _print_json({"draft": draft})
+    else:
+        fields = [
+            ("ID", draft.get("id")),
+            ("Title", draft.get("draft_title") or draft.get("title")),
+            ("Subtitle", draft.get("draft_subtitle") or draft.get("subtitle")),
+            ("Status", draft.get("type") or draft.get("status") or "draft"),
+            ("Slug", draft.get("slug")),
+            ("Scheduled", draft.get("post_date")),
+            ("Audience", draft.get("audience")),
+        ]
+        for label, value in fields:
+            print(f"{label}: {_display(value)}")
+
+
+def _drafts_schedule(api, args):
+    scheduled_at = _parse_schedule(args.at)
+    result = api.schedule_draft(args.draft_id, scheduled_at)
+    payload = {
+        "action": "schedule",
+        "draft_id": args.draft_id,
+        "scheduled_at": scheduled_at.isoformat(),
+        "result": result,
+    }
+    if args.json_output:
+        _print_json(payload)
+    else:
+        print(f"Scheduled draft {args.draft_id} for {scheduled_at.isoformat()}")
+
+
+def _drafts_unschedule(api, args):
+    result = api.unschedule_draft(args.draft_id)
+    payload = {"action": "unschedule", "draft_id": args.draft_id, "result": result}
+    if args.json_output:
+        _print_json(payload)
+    else:
+        print(f"Unscheduled draft {args.draft_id}")
+
+
+def _drafts_publish(api, args):
+    _confirm("Publish", args.draft_id, args.yes, args.json_output)
+    prepublish = api.prepublish_draft(args.draft_id)
+    result = api.publish_draft(
+        args.draft_id,
+        send=args.send,
+        share_automatically=args.share_automatically,
+    )
+    payload = {
+        "action": "publish",
+        "draft_id": args.draft_id,
+        "prepublish": prepublish,
+        "result": result,
+    }
+    if args.json_output:
+        _print_json(payload)
+    else:
+        delivery = "without email" if not args.send else "with email"
+        print(f"Published draft {args.draft_id} {delivery}")
+
+
+def _drafts_delete(api, args):
+    _confirm("Delete", args.draft_id, args.yes, args.json_output)
+    result = api.delete_draft(args.draft_id)
+    payload = {"action": "delete", "draft_id": args.draft_id, "result": result}
+    if args.json_output:
+        _print_json(payload)
+    else:
+        print(f"Deleted draft {args.draft_id}")
+
+
+def _build_parser():
+    parser = argparse.ArgumentParser(
+        prog="substack", description="Manage Substack publications and drafts."
+    )
+    parser.add_argument("--cookies", help="Path to a cookies JSON file.")
+    parser.add_argument(
+        "--publication-url", help="Override PUBLICATION_URL for this command."
+    )
+    parser.add_argument("--json", action="store_true", dest="json_output")
+    parser.add_argument("--version", action="version", version=__version__)
+
+    commands = parser.add_subparsers(dest="command", required=True)
+    status = commands.add_parser(
+        "status", help="Show authentication and publication status."
+    )
+    status.set_defaults(handler=_status)
+
+    publications = commands.add_parser("publications", help="Manage publications.")
+    publication_commands = publications.add_subparsers(
+        dest="publication_command", required=True
+    )
+    publications_list = publication_commands.add_parser(
+        "list", help="List available publications."
+    )
+    publications_list.set_defaults(handler=_publications_list)
+
+    drafts = commands.add_parser("drafts", help="Manage drafts.")
+    draft_commands = drafts.add_subparsers(dest="draft_command", required=True)
+
+    drafts_list = draft_commands.add_parser("list", help="List drafts.")
+    drafts_list.add_argument("--filter", default="draft")
+    drafts_list.add_argument("--offset", type=int, default=0)
+    drafts_list.add_argument("--limit", type=int, default=25)
+    drafts_list.set_defaults(handler=_drafts_list)
+
+    drafts_get = draft_commands.add_parser("get", help="Inspect a draft.")
+    drafts_get.add_argument("draft_id", type=int)
+    drafts_get.set_defaults(handler=_drafts_get)
+
+    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)
+    drafts_schedule.set_defaults(handler=_drafts_schedule)
+
+    drafts_unschedule = draft_commands.add_parser(
+        "unschedule", help="Remove a draft schedule."
+    )
+    drafts_unschedule.add_argument("draft_id", type=int)
+    drafts_unschedule.set_defaults(handler=_drafts_unschedule)
+
+    drafts_publish = draft_commands.add_parser("publish", help="Publish a draft.")
+    drafts_publish.add_argument("draft_id", type=int)
+    drafts_publish.add_argument(
+        "--no-send", action="store_false", dest="send", default=True
+    )
+    drafts_publish.add_argument("--share-automatically", action="store_true")
+    drafts_publish.add_argument("--yes", action="store_true")
+    drafts_publish.set_defaults(handler=_drafts_publish)
+
+    drafts_delete = draft_commands.add_parser("delete", help="Delete a draft.")
+    drafts_delete.add_argument("draft_id", type=int)
+    drafts_delete.add_argument("--yes", action="store_true")
+    drafts_delete.set_defaults(handler=_drafts_delete)
+    return parser
+
+
+def main(argv=None):
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    try:
+        api = _api_from_env(
+            cookies_path=args.cookies,
+            publication_url=args.publication_url,
+        )
+        args.handler(api, args)
+    except CLIUsageError as exc:
+        _print_usage_error(exc, args.json_output)
+        return 2
+    except (SubstackAPIException, SubstackRequestException, OSError, ValueError) as exc:
+        _print_error(exc, args.json_output)
+        return 1
+    return 0
+
+
 def publish_markdown(argv=None):
     parser = argparse.ArgumentParser()
     parser.add_argument("markdown", nargs="?", default="README.md")

python_substack-0.1.25.dist-info/RECORD

@@ -1,13 +0,0 @@
-substack/__init__.py,sha256=sm5s0r53o_oBjA_3yUob0L4VwXeT8bNuA20PnAjTflI,390
-substack/api.py,sha256=QX9A_7PanQd_Q_QJwnxXM9auIHCtKd7rHbFTDATcm-U,22640
-substack/cli.py,sha256=Hu9tBjyIW9zl7IE92VuZ-MOThS2cLpwXXAOR8Ixsu6o,7708
-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.25.dist-info/METADATA,sha256=Ero48_tB_HIHbkccKxfKK24rvOJiqlO80SlXItRgpC4,8720
-python_substack-0.1.25.dist-info/WHEEL,sha256=EGEvSphFYqXKs23-kQBeyNoJP1nrT8ZJKQoi5p5DYL8,88
-python_substack-0.1.25.dist-info/entry_points.txt,sha256=la9TUtzyaVksmdSkdKZsg55XIRXx4KjkKW7J3pvBegc,209
-python_substack-0.1.25.dist-info/licenses/LICENSE,sha256=L6jk148I5HhhVbfUvkO3EO7eAoU5zToLio4-ApkCkxg,1062
-python_substack-0.1.25.dist-info/RECORD,,