🪿 upkeep

Author: ma2za

.github/workflows/ci_publish.yml

@@ -1,4 +1,4 @@
-name: Upload Python Package
+name: Publish
 on:
   push:
     branches:

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2022 hogier
+Copyright (c) 2022 ma2za
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -1,18 +1,22 @@
 # Python Substack
 
-# Introduction
-
 This is an unofficial library providing a Python interface for [Substack](https://substack.com/).
-I am in no way affiliated with Substack. It works with
-Python versions from 3.7+.
+I am in no way affiliated with Substack.
+
+[![Python](https://img.shields.io/pypi/pyversions/fastapi.svg?color=%2334D058)](https://www.python.org/downloads/)
+[![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)
+---
 
 # Installation
 
 You can install python-substack using:
 
     $ pip install python-substack
 
-# Usage
+---
+
+# Setup
 
 Set the following environment variables by creating a **.env** file:
 
@@ -22,9 +26,40 @@ Set the following environment variables by creating a **.env** file:
     USER_ID=
 
 To discover the USER_ID go to your public profile page,
-in the URL bar of the browser you find the substack address 
+in the URL bar of the browser you find the substack address
 followed by your USER_ID and your username:
 https://substack.com/profile/[USER_ID]-[username]
 
-
 The .env file will be ignored by git but always be careful.
+
+---
+
+# Usage
+
+```python
+import os
+
+from substack import Api
+from substack.post import Post
+
+api = Api(
+    email=os.getenv("EMAIL"),
+    password=os.getenv("PASSWORD"),
+    publication_url=os.getenv("PUBLICATION_URL"),
+)
+
+post = Post(
+    title="How to publish a Substack post using the Python API",
+    subtitle="This post was published using the Python API",
+    user_id=os.getenv("USER_ID")
+)
+
+post.add({'type': 'paragraph', 'content': 'This is how you add a new paragraph to your post!'})
+
+draft = api.post_draft(post.get_draft())
+
+api.prepublish_draft(draft.get("id"))
+
+api.publish_draft(draft.get("id"))
+```
+

examples/publish_post.py

@@ -10,11 +10,18 @@
 load_dotenv()
 
 if __name__ == "__main__":
-
     parser = argparse.ArgumentParser()
-    parser.add_argument("-p", "--post", default="draft.yaml", required=False,
-                        help="YAML file containing the post to publish.", type=str)
-    parser.add_argument("--publish", help="Publish the draft.", action="store_true", default=False)
+    parser.add_argument(
+        "-p",
+        "--post",
+        default="draft.yaml",
+        required=False,
+        help="YAML file containing the post to publish.",
+        type=str,
+    )
+    parser.add_argument(
+        "--publish", help="Publish the draft.", action="store_true", default=False
+    )
     args = parser.parse_args()
 
     with open(args.post, "r") as fp:
@@ -26,11 +33,15 @@
         publication_url=os.getenv("PUBLICATION_URL"),
     )
 
-    post = Post(post_data.get("title"),
-                post_data.get("subtitle", ""),
-                os.getenv("USER_ID"),
-                audience=post_data.get("audience", "everyone"),
-                write_comment_permissions=post_data.get("write_comment_permissions", "everyone"))
+    post = Post(
+        post_data.get("title"),
+        post_data.get("subtitle", ""),
+        os.getenv("USER_ID"),
+        audience=post_data.get("audience", "everyone"),
+        write_comment_permissions=post_data.get(
+            "write_comment_permissions", "everyone"
+        ),
+    )
 
     body = post_data.get("body", {})
 

substack/__init__.py

@@ -4,7 +4,7 @@
 __email__ = "mazzapaolo2019@gmail.com"
 __license__ = "MIT License"
 __version__ = "1.0"
-__url__ = "https://github.com/hogier/python-substack"
+__url__ = "https://github.com/ma2za/python-substack"
 __download_url__ = "https://pypi.python.org/pypi/python-substack"
 __description__ = "A Python wrapper around the Substack API"
 

substack/api.py

@@ -10,6 +10,8 @@
 
 logger = logging.getLogger(__name__)
 
+__all__ = ["Api"]
+
 
 class Api:
     """
@@ -19,12 +21,12 @@ class Api:
     """
 
     def __init__(
-            self,
-            email=None,
-            password=None,
-            base_url=None,
-            publication_url=None,
-            debug=False,
+        self,
+        email=None,
+        password=None,
+        base_url=None,
+        publication_url=None,
+        debug=False,
     ):
         """
 
@@ -116,9 +118,7 @@ def get_drafts(self, filter=None, offset=None, limit=None):
         return Api._handle_response(response=response)
 
     def delete_draft(self, draft_id):
-        response = self._session.delete(
-            f"{self.publication_url}/drafts/{draft_id}"
-        )
+        response = self._session.delete(f"{self.publication_url}/drafts/{draft_id}")
         return Api._handle_response(response=response)
 
     def post_draft(self, body) -> dict:
@@ -134,12 +134,12 @@ def post_draft(self, body) -> dict:
         return Api._handle_response(response=response)
 
     def put_draft(
-            self,
-            draft,
-            title=None,
-            subtitle=None,
-            body=None,
-            cover_image=None,
+        self,
+        draft,
+        title=None,
+        subtitle=None,
+        body=None,
+        cover_image=None,
     ) -> dict:
         """
 
@@ -181,7 +181,7 @@ def prepublish_draft(self, draft) -> dict:
         return Api._handle_response(response=response)
 
     def publish_draft(
-            self, draft, send: bool = True, share_automatically: bool = False
+        self, draft, send: bool = True, share_automatically: bool = False
     ) -> dict:
         """
 
@@ -211,7 +211,7 @@ 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()}
+            json={"post_date": draft_datetime.isoformat()},
         )
         return Api._handle_response(response=response)
 
@@ -225,8 +225,7 @@ def unschedule_draft(self, draft) -> dict:
 
         """
         response = self._session.post(
-            f"{self.publication_url}/drafts/{draft}/schedule",
-            json={"post_date": None}
+            f"{self.publication_url}/drafts/{draft}/schedule", json={"post_date": None}
         )
         return Api._handle_response(response=response)
 
@@ -247,9 +246,7 @@ def get_image(self, image: str):
 
         response = self._session.post(
             f"{self.publication_url}/image",
-            data={
-                "image": image
-            },
+            data={"image": image},
         )
         return Api._handle_response(response=response)
 
@@ -265,12 +262,13 @@ def get_categories(self):
         return Api._handle_response(response=response)
 
     def get_category(self, category_id, category_type, page):
-        response = self._session.get(f"{self.base_url}/category/public/{category_id}/{category_type}",
-                                     params={"page": page})
+        response = self._session.get(
+            f"{self.base_url}/category/public/{category_id}/{category_type}",
+            params={"page": page},
+        )
         return Api._handle_response(response=response)
 
-    def get_single_category(self, category_id, category_type, page=None,
-                            limit=None):
+    def get_single_category(self, category_id, category_type, page=None, limit=None):
         """
 
         Args:
@@ -290,13 +288,15 @@ def get_single_category(self, category_id, category_type, page=None,
             while True:
                 page_output = self.get_category(category_id, category_type, page)
                 publications.extend(page_output.get("publications", []))
-                if (limit is not None and limit <= len(publications)) or not page_output.get("more", False):
+                if (
+                    limit is not None and limit <= len(publications)
+                ) or not page_output.get("more", False):
                     publications = publications[:limit]
                     break
                 page += 1
             output = {
                 "publications": publications,
-                "more": page_output.get("more", False)
+                "more": page_output.get("more", False),
             }
         return output