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

{python_substack-0.2.0 → python_substack-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-substack
-Version: 0.2.0
+Version: 0.4.0
 Summary: Write and safely manage Substack drafts from Markdown with Python, CLI, and MCP.
 License: MIT
 License-File: LICENSE
@@ -28,6 +28,7 @@ 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: Documentation, https://ma2za.github.io/python-substack/
 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
@@ -45,6 +46,10 @@ publish them through Python, a command-line interface, or MCP.
 [![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)
 
+[Documentation](https://ma2za.github.io/python-substack/) ·
+[Getting started](https://ma2za.github.io/python-substack/getting-started.html) ·
+[PyPI](https://pypi.org/project/python-substack/)
+
 > [!IMPORTANT]
 > Creating and publishing are separate operations. `substack drafts create`
 > always creates an unpublished draft. It never schedules, sends, publishes,
@@ -248,12 +253,19 @@ See [MCP server](docs/mcp.md) for the tool list and safety notes.
 
 ## Project documentation
 
+- [Documentation site](https://ma2za.github.io/python-substack/)
+- [Installation and first draft](docs/getting-started.md)
+- [Unified CLI](docs/cli.md)
+- [Python SDK](docs/python-sdk.md)
 - [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)
+- [Gemini CLI with Vertex AI](docs/gemini-vertex-ai.md)
+- [Safety and publishing behavior](docs/safety.md)
+- [Troubleshooting](docs/troubleshooting.md)
 - [Compatibility policy](docs/compatibility.md)
 - [Contributing](CONTRIBUTING.md)
 - [Security policy](SECURITY.md)

{python_substack-0.2.0 → python_substack-0.4.0}/README.md

@@ -10,6 +10,10 @@ publish them through Python, a command-line interface, or MCP.
 [![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)
 
+[Documentation](https://ma2za.github.io/python-substack/) ·
+[Getting started](https://ma2za.github.io/python-substack/getting-started.html) ·
+[PyPI](https://pypi.org/project/python-substack/)
+
 > [!IMPORTANT]
 > Creating and publishing are separate operations. `substack drafts create`
 > always creates an unpublished draft. It never schedules, sends, publishes,
@@ -213,12 +217,19 @@ See [MCP server](docs/mcp.md) for the tool list and safety notes.
 
 ## Project documentation
 
+- [Documentation site](https://ma2za.github.io/python-substack/)
+- [Installation and first draft](docs/getting-started.md)
+- [Unified CLI](docs/cli.md)
+- [Python SDK](docs/python-sdk.md)
 - [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)
+- [Gemini CLI with Vertex AI](docs/gemini-vertex-ai.md)
+- [Safety and publishing behavior](docs/safety.md)
+- [Troubleshooting](docs/troubleshooting.md)
 - [Compatibility policy](docs/compatibility.md)
 - [Contributing](CONTRIBUTING.md)
 - [Security policy](SECURITY.md)

{python_substack-0.2.0 → python_substack-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "python-substack"
-version = "0.2.0"
+version = "0.4.0"
 description = "Write and safely manage Substack drafts from Markdown with Python, CLI, and MCP."
 authors = ["Paolo Mazza <mazzapaolo2019@gmail.com>"]
 license = "MIT"
@@ -29,6 +29,7 @@ classifiers = [
 ]
 
 [tool.poetry.urls]
+"Documentation" = "https://ma2za.github.io/python-substack/"
 "Changelog" = "https://github.com/ma2za/python-substack/blob/main/CHANGELOG.md"
 "Issues" = "https://github.com/ma2za/python-substack/issues"
 

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

@@ -3,7 +3,7 @@
 __author__ = "Paolo Mazza"
 __email__ = "mazzapaolo2019@gmail.com"
 __license__ = "MIT License"
-__version__ = "0.2.0"
+__version__ = "0.4.0"
 __url__ = "https://github.com/ma2za/python-substack"
 __download_url__ = "https://pypi.python.org/pypi/python-substack"
 __description__ = (

{python_substack-0.2.0 → python_substack-0.4.0}/substack_mcp/mcp_server.py

@@ -163,55 +163,24 @@ async def post_draft_from_markdown(
         This docstring example is meant to mirror the YAML-driven workflow and show how to decompose the same operations into explicit tool calls.
     """
     client = get_api()
-    user_id = client.get_user_id()
 
-    post = Post(
+    return client.create_draft_from_markdown(
         title=title,
-        subtitle=subtitle or "",
-        user_id=user_id,
+        markdown=markdown,
+        subtitle=subtitle,
         audience=audience,
         write_comment_permissions=write_comment_permissions,
+        search_engine_title=search_engine_title,
+        search_engine_description=search_engine_description,
+        slug=slug,
+        draft_section_id=draft_section_id,
+        tags=tags,
+        prepublish=prepublish,
+        publish=publish,
+        send=send,
+        share_automatically=share_automatically,
     )
 
-    post.from_markdown(markdown, api=client)
-
-    draft = client.post_draft(post.get_draft())
-
-    update_payload: Dict[str, Any] = {}
-    if search_engine_title:
-        update_payload["search_engine_title"] = search_engine_title
-    if search_engine_description:
-        update_payload["search_engine_description"] = search_engine_description
-    if slug:
-        update_payload["slug"] = slug
-    if draft_section_id is not None:
-        update_payload["draft_section_id"] = draft_section_id
-
-    if update_payload:
-        draft = client.put_draft(draft.get("id"), **update_payload)
-
-    tags_list = _normalize_tags(tags)
-    tags_result = None
-    if tags_list:
-        tags_result = client.add_tags_to_post(draft.get("id"), tags_list)
-
-    prepublish_result = None
-    if prepublish:
-        prepublish_result = client.prepublish_draft(draft.get("id"))
-
-    publish_result = None
-    if publish:
-        publish_result = client.publish_draft(
-            draft.get("id"), send=send, share_automatically=share_automatically
-        )
-
-    return {
-        "draft": draft,
-        "tags": tags_result,
-        "prepublish": prepublish_result,
-        "publish": publish_result,
-    }
-
 
 @mcp.tool()
 async def put_draft(
@@ -269,7 +238,11 @@ async def publish_draft(
     send: bool = True,
     share_automatically: bool = False,
 ) -> Dict[str, Any]:
-    """Publish a draft to live post state.
+    """Publish a draft to live post state. (Legacy compatibility interface).
+
+    This tool remains for backward compatibility. It is recommended to use
+    `publish_draft_checked` instead, which provides a safer publishing path
+    with explicit confirmation and prepublish validation.
 
     Args:
         draft_id: target draft identifier.
@@ -285,6 +258,126 @@ async def publish_draft(
     )
 
 
+@mcp.tool()
+async def publish_draft_checked(
+    draft_id: int,
+    confirm: bool = False,
+    send: bool = False,
+    share_automatically: bool = False,
+) -> Dict[str, Any]:
+    """A safer publishing path that requires confirmation and runs prepublish checks.
+
+    Args:
+        draft_id: target draft identifier.
+        confirm: Must be True to proceed with publication.
+        send: if False then do not send email to subscribers. Defaults to False.
+        share_automatically: whether to auto-share.
+
+    Returns:
+        Response from Substack `publish_draft`.
+    """
+    if not confirm:
+        raise ValueError("Publishing rejected: confirm parameter must be True.")
+
+    client = get_api()
+    client.prepublish_draft(draft_id)
+    return client.publish_draft(
+        draft_id, send=send, share_automatically=share_automatically
+    )
+
+
+@mcp.tool()
+async def get_status() -> Dict[str, Any]:
+    """Get the authentication status and basic user information.
+
+    Returns:
+        A dictionary containing user profile and primary publication details.
+    """
+    client = get_api()
+    profile = client.get_user_profile()
+    primary_pub = client.get_user_primary_publication()
+    return {"profile": profile, "primary_publication": primary_pub}
+
+
+@mcp.tool()
+async def list_publications() -> List[Dict[str, Any]]:
+    """List all publications available to the authenticated user.
+
+    Returns:
+        A list of publications.
+    """
+    client = get_api()
+    return client.get_user_publications()
+
+
+@mcp.tool()
+async def list_drafts(
+    filter: str = "draft", offset: int = 0, limit: int = 25
+) -> List[Dict[str, Any]]:
+    """List drafts for the current publication.
+
+    Args:
+        filter: Filter string, defaults to "draft".
+        offset: Pagination offset.
+        limit: Max number of drafts to return.
+
+    Returns:
+        A list of drafts.
+    """
+    client = get_api()
+    return client.get_drafts(filter=filter, offset=offset, limit=limit)
+
+
+@mcp.tool()
+async def get_draft(draft_id: int) -> Dict[str, Any]:
+    """Get a specific draft by its ID.
+
+    Args:
+        draft_id: The identifier of the draft.
+
+    Returns:
+        The draft details.
+    """
+    client = get_api()
+    return client.get_draft(draft_id)
+
+
+@mcp.tool()
+async def schedule_draft(draft_id: int, at: str) -> Dict[str, Any]:
+    """Schedule a draft for release.
+
+    Args:
+        draft_id: target draft identifier.
+        at: ISO 8601 formatted datetime string (e.g., "2024-01-01T12:00:00Z").
+
+    Returns:
+        API response dict for the scheduled draft.
+    """
+    from datetime import datetime
+
+    try:
+        draft_datetime = datetime.fromisoformat(at.replace("Z", "+00:00"))
+    except ValueError as e:
+        raise ValueError(f"Invalid ISO datetime string for 'at': {e}")
+
+    client = get_api()
+    return client.schedule_draft(draft_id, draft_datetime)
+
+
+@mcp.tool()
+async def unschedule_draft(draft_id: int) -> Dict[str, Any]:
+    """Unschedule a previously scheduled draft.
+
+    Args:
+        draft_id: target draft identifier.
+
+    Returns:
+        API response dict for unscheduling.
+    """
+    client = get_api()
+    return client.unschedule_draft(draft_id)
+
+
 def main() -> None:
     mcp.run(transport="stdio")