python-substack 0.1.12__tar.gz → 0.1.14__tar.gz

{python_substack-0.1.12 → python_substack-0.1.14}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: python-substack
-Version: 0.1.12
+Version: 0.1.14
 Summary: A Python wrapper around the Substack API.
 Home-page: https://github.com/ma2za/python-substack
 License: MIT
@@ -44,15 +44,19 @@ You can install python-substack using:
 
 Set the following environment variables by creating a **.env** file:
 
-    PUBLICATION_URL=https://ma2za.substack.com
     EMAIL=
     PASSWORD=
-    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
-followed by your USER_ID and your username:
-https://substack.com/profile/[USER_ID]-[username]
+## If you don't have a password
+
+Recently Substack has been setting up new accounts without a password. If you sign-out and sign back in it just uses
+your email address with a "magic" link.
+
+Set a password:
+
+- Sign-out of Substack
+- At the sign-in page click, "Sign in with password" under the `Email` text box
+- Then choose, "Set a new password"
 
 The .env file will be ignored by git but always be careful.
 
@@ -71,31 +75,69 @@ from substack.post import Post
 api = Api(
     email=os.getenv("EMAIL"),
     password=os.getenv("PASSWORD"),
-    publication_url=os.getenv("PUBLICATION_URL"),
 )
 
+user_id = api.get_user_id()
+
+# Switch Publications - The library defaults to your users primary publication. You can retrieve all your publications and change which one you want to use.
+
+# primary publication
+user_publication = api.get_user_primary_publication()
+# all publications
+user_publications = api.get_user_publications()
+
+# This step is only necessary if you are not using your primary publication
+# api.change_publication(user_publication)
+
 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")
+    user_id=user_id
 )
 
 post.add({'type': 'paragraph', 'content': 'This is how you add a new paragraph to your post!'})
 
-#bolden text
-post.add({'type': "paragraph",'content':[{'content': "This is how you "},{'content': "bolden ",'marks':[{'type': "strong"}]},{'content': "a word."}]})
+# bolden text
+post.add({'type': "paragraph",
+          'content': [{'content': "This is how you "}, {'content': "bolden ", 'marks': [{'type': "strong"}]},
+                      {'content': "a word."}]})
+
+# add hyperlink to text
+post.add({'type': 'paragraph', 'content': [
+    {'content': "View Link", 'marks': [{'type': "link", 'href': 'https://whoraised.substack.com/'}]}]})
 
-#add hyperlink to text
-post.add({'type':'paragraph','content':[{'content': "View Link",'marks':[{'type': "link",'href':'https://whoraised.substack.com/'}]}]})
+# set paywall boundary
+post.add({'type': 'paywall'})
 
-#add image
-post.add({'type':'captionedImage','src': "https://media.tenor.com/7B4jMa-a7bsAAAAC/i-am-batman.gif"})
+# add image
+post.add({'type': 'captionedImage', 'src': "https://media.tenor.com/7B4jMa-a7bsAAAAC/i-am-batman.gif"})
+
+# add local image
+image = api.get_image('image.png')
+post.add({"type": "captionedImage", "src": image.get("url")})
 
 draft = api.post_draft(post.get_draft())
 
+# set section (THIS CAN BE DONE ONLY AFTER HAVING FIRST POSTED THE DRAFT)
+post.set_section("rick rolling", api.get_sections())
+api.put_draft(draft.get("id"), draft_section_id=post.draft_section_id)
+
 api.prepublish_draft(draft.get("id"))
 
 api.publish_draft(draft.get("id"))
 ```
 
+# Contributing
+
+Install pre-commit:
+
+```shell
+pip install pre-commit
+```
+
+Set up pre-commit
+
+```shell
+pre-commit install
+```
 

python_substack-0.1.14/README.md

@@ -0,0 +1,118 @@
+# Python Substack
+
+This is an unofficial library providing a Python interface for [Substack](https://substack.com/).
+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
+
+---
+
+# Setup
+
+Set the following environment variables by creating a **.env** file:
+
+    EMAIL=
+    PASSWORD=
+
+## If you don't have a password
+
+Recently Substack has been setting up new accounts without a password. If you sign-out and sign back in it just uses
+your email address with a "magic" link.
+
+Set a password:
+
+- Sign-out of Substack
+- At the sign-in page click, "Sign in with password" under the `Email` text box
+- Then choose, "Set a new password"
+
+The .env file will be ignored by git but always be careful.
+
+---
+
+# Usage
+
+Check out the examples folder for some examples 😃 🚀
+
+```python
+import os
+
+from substack import Api
+from substack.post import Post
+
+api = Api(
+    email=os.getenv("EMAIL"),
+    password=os.getenv("PASSWORD"),
+)
+
+user_id = api.get_user_id()
+
+# Switch Publications - The library defaults to your users primary publication. You can retrieve all your publications and change which one you want to use.
+
+# primary publication
+user_publication = api.get_user_primary_publication()
+# all publications
+user_publications = api.get_user_publications()
+
+# This step is only necessary if you are not using your primary publication
+# api.change_publication(user_publication)
+
+post = Post(
+    title="How to publish a Substack post using the Python API",
+    subtitle="This post was published using the Python API",
+    user_id=user_id
+)
+
+post.add({'type': 'paragraph', 'content': 'This is how you add a new paragraph to your post!'})
+
+# bolden text
+post.add({'type': "paragraph",
+          'content': [{'content': "This is how you "}, {'content': "bolden ", 'marks': [{'type': "strong"}]},
+                      {'content': "a word."}]})
+
+# add hyperlink to text
+post.add({'type': 'paragraph', 'content': [
+    {'content': "View Link", 'marks': [{'type': "link", 'href': 'https://whoraised.substack.com/'}]}]})
+
+# set paywall boundary
+post.add({'type': 'paywall'})
+
+# add image
+post.add({'type': 'captionedImage', 'src': "https://media.tenor.com/7B4jMa-a7bsAAAAC/i-am-batman.gif"})
+
+# add local image
+image = api.get_image('image.png')
+post.add({"type": "captionedImage", "src": image.get("url")})
+
+draft = api.post_draft(post.get_draft())
+
+# set section (THIS CAN BE DONE ONLY AFTER HAVING FIRST POSTED THE DRAFT)
+post.set_section("rick rolling", api.get_sections())
+api.put_draft(draft.get("id"), draft_section_id=post.draft_section_id)
+
+api.prepublish_draft(draft.get("id"))
+
+api.publish_draft(draft.get("id"))
+```
+
+# Contributing
+
+Install pre-commit:
+
+```shell
+pip install pre-commit
+```
+
+Set up pre-commit
+
+```shell
+pre-commit install
+```

{python_substack-0.1.12 → python_substack-0.1.14}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "python-substack"
-version = "0.1.12"
+version = "0.1.14"
 description = "A Python wrapper around the Substack API."
 authors = ["Paolo Mazza <mazzapaolo2019@gmail.com>"]
 license = "MIT"
@@ -28,4 +28,4 @@ PyYAML = "^6.0"
 
 [build-system]
 requires = ["poetry-core>=1.0.0"]
-build-backend = "poetry.core.masonry.api"
+build-backend = "poetry.core.masonry.api"

{python_substack-0.1.12 → python_substack-0.1.14}/substack/api.py

@@ -1,4 +1,11 @@
+"""
+
+API Wrapper
+
+"""
+
 import base64
+import json
 import logging
 import os
 from datetime import datetime
@@ -21,12 +28,13 @@ class Api:
     """
 
     def __init__(
-            self,
-            email=None,
-            password=None,
-            base_url=None,
-            publication_url=None,
-            debug=False,
+        self,
+        email=None,
+        password=None,
+        cookies_path=None,
+        base_url=None,
+        publication_url=None,
+        debug=False,
     ):
         """
 
@@ -37,12 +45,15 @@ class Api:
         Args:
           email:
           password:
+          cookies_path
+            To re-use your session without logging in each time, you can save your cookies to a json file and
+            then load them in the next session.
+            Make sure to re-save your cookies, as they do update over time.
           base_url:
             The base URL to use to contact the Substack API.
             Defaults to https://substack.com/api/v1.
         """
         self.base_url = base_url or "https://substack.com/api/v1"
-        self.publication_url = urljoin(publication_url, "api/v1")
 
         if debug:
             logging.basicConfig()
@@ -50,8 +61,42 @@ class Api:
 
         self._session = requests.Session()
 
-        if email is not None and password is not None:
+        # Load cookies from file if provided
+        # Helps with Captcha errors by reusing cookies from "local" auth, then switching to running code in the cloud
+        if cookies_path is not None:
+            with open(cookies_path) as f:
+                cookies = json.load(f)
+            self._session.cookies.update(cookies)
+
+        elif email is not None and password is not None:
             self.login(email, password)
+        else:
+            raise ValueError(
+                "Must provide email and password or cookies_path to authenticate."
+            )
+
+        user_publication = None
+        # if the user provided a publication url, then use that
+        if publication_url:
+            import re
+
+            # Regular expression to extract subdomain name
+            match = re.search(r"https://(.*).substack.com", publication_url.lower())
+            subdomain = match.group(1) if match else None
+
+            user_publications = self.get_user_publications()
+            # search through publications to find the publication with the matching subdomain
+            for publication in user_publications:
+                if publication["subdomain"] == subdomain:
+                    # set the current publication to the users publication
+                    user_publication = publication
+                    break
+        else:
+            # get the users primary publication
+            user_publication = self.get_user_primary_publication()
+
+        # set the current publication to the users primary publication
+        self.change_publication(user_publication)
 
     def login(self, email, password) -> dict:
         """
@@ -73,8 +118,37 @@ class Api:
                 "redirect": "/",
             },
         )
+
+        return Api._handle_response(response=response)
+
+    def signin_for_pub(self, publication):
+        """
+        Complete the signin process
+        """
+        response = self._session.get(
+            f"https://substack.com/sign-in?redirect=%2F&for_pub={publication['subdomain']}",
+        )
         return Api._handle_response(response=response)
 
+    def change_publication(self, publication):
+        """
+        Change the publication URL
+        """
+        self.publication_url = urljoin(publication["publication_url"], "api/v1")
+
+        # sign-in to the publication
+        self.signin_for_pub(publication)
+
+    def export_cookies(self, path: str = "cookies.json"):
+        """
+        Export cookies to a json file.
+        Args:
+            path: path to the json file
+        """
+        cookies = self._session.cookies.get_dict()
+        with open(path, "w") as f:
+            json.dump(cookies, f)
+
     @staticmethod
     def _handle_response(response: requests.Response):
         """
@@ -92,6 +166,82 @@ class Api:
         except ValueError:
             raise SubstackRequestException("Invalid Response: %s" % response.text)
 
+    def get_user_id(self):
+        """
+
+        Returns:
+
+        """
+        profile = self.get_user_profile()
+        user_id = profile["id"]
+
+        return user_id
+
+    @staticmethod
+    def get_publication_url(publication: dict) -> str:
+        """
+        Gets the publication url
+
+        Args:
+            publication:
+        """
+        custom_domain = publication["custom_domain"]
+        if not custom_domain:
+            publication_url = f"https://{publication['subdomain']}.substack.com"
+        else:
+            publication_url = f"https://{custom_domain}"
+
+        return publication_url
+
+    def get_user_primary_publication(self):
+        """
+        Gets the users primary publication
+        """
+
+        profile = self.get_user_profile()
+        primary_publication = profile["primaryPublication"]
+        primary_publication["publication_url"] = self.get_publication_url(
+            primary_publication
+        )
+
+        return primary_publication
+
+    def get_user_publications(self):
+        """
+        Gets the users publications
+        """
+
+        profile = self.get_user_profile()
+
+        # Loop through users "publicationUsers" list, and return a list
+        # of dictionaries of "name", and "subdomain", and "id"
+        user_publications = []
+        for publication in profile["publicationUsers"]:
+            pub = publication["publication"]
+            pub["publication_url"] = self.get_publication_url(pub)
+            user_publications.append(pub)
+
+        return user_publications
+
+    def get_user_profile(self):
+        """
+        Gets the users profile
+        """
+        response = self._session.get(f"{self.base_url}/user/profile/self")
+
+        return Api._handle_response(response=response)
+
+    def get_user_settings(self):
+        """
+        Get list of users.
+
+        Returns:
+
+        """
+        response = self._session.get(f"{self.base_url}/settings")
+
+        return Api._handle_response(response=response)
+
     def get_publication_users(self):
         """
         Get list of users.
@@ -111,9 +261,29 @@ class Api:
         Returns:
 
         """
-        response = self._session.get(f"{self.publication_url}/publication_launch_checklist")
+        response = self._session.get(
+            f"{self.publication_url}/publication_launch_checklist"
+        )
+
+        return Api._handle_response(response=response)["subscriberCount"]
+
+    def get_published_posts(
+        self, offset=0, limit=25, order_by="post_date", order_direction="desc"
+    ):
+        """
+        Get list of published posts for the publication.
+        """
+        response = self._session.get(
+            f"{self.publication_url}/post_management/published",
+            params={
+                "offset": offset,
+                "limit": limit,
+                "order_by": order_by,
+                "order_direction": order_direction,
+            },
+        )
 
-        return Api._handle_response(response=response)['subscriberCount']
+        return Api._handle_response(response=response)
 
     def get_posts(self) -> dict:
         """
@@ -142,6 +312,14 @@ class Api:
         )
         return Api._handle_response(response=response)
 
+    def get_draft(self, draft_id):
+        """
+        Gets a draft given it's id.
+
+        """
+        response = self._session.get(f"{self.publication_url}/drafts/{draft_id}")
+        return Api._handle_response(response=response)
+
     def delete_draft(self, draft_id):
         """
 
@@ -166,35 +344,19 @@ class Api:
         response = self._session.post(f"{self.publication_url}/drafts", json=body)
         return Api._handle_response(response=response)
 
-    def put_draft(
-            self,
-            draft,
-            title=None,
-            subtitle=None,
-            body=None,
-            cover_image=None,
-    ) -> dict:
+    def put_draft(self, draft, **kwargs) -> dict:
         """
 
         Args:
-            draft: draft id
-            title:
-            subtitle:
-            body:
-            cover_image:
+            draft:
+            **kwargs:
 
         Returns:
 
         """
-
         response = self._session.put(
             f"{self.publication_url}/drafts/{draft}",
-            json={
-                "draft_title": title,
-                "draft_subtitle": subtitle,
-                "draft_body": body,
-                "cover_image": cover_image,
-            },
+            json=kwargs,
         )
         return Api._handle_response(response=response)
 
@@ -214,7 +376,7 @@ class Api:
         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:
         """
 
@@ -332,7 +494,7 @@ class Api:
                 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)
+                    limit is not None and limit <= len(publications)
                 ) or not page_output.get("more", False):
                     publications = publications[:limit]
                     break
@@ -357,3 +519,22 @@ class Api:
             for draft in drafts:
                 response = self.delete_draft(draft.get("id"))
         return response
+
+    def get_sections(self):
+        """
+        Get a list of the sections of your publication.
+
+        TODO: this is hacky but I cannot find another place where to get the sections.
+        Returns:
+
+        """
+        response = self._session.get(
+            f"{self.publication_url}/subscriptions",
+        )
+        content = Api._handle_response(response=response)
+        sections = [
+            p.get("sections")
+            for p in content.get("publications")
+            if p.get("hostname") in self.publication_url
+        ]
+        return sections[0]

{python_substack-0.1.12 → python_substack-0.1.14}/substack/exceptions.py

@@ -26,3 +26,7 @@ class SubstackRequestException(Exception):
 
     def __str__(self):
         return f"SubstackRequestException: {self.message}"
+
+
+class SectionNotExistsException(SubstackRequestException):
+    pass

{python_substack-0.1.12 → python_substack-0.1.14}/substack/post.py

@@ -1,17 +1,31 @@
+"""
+
+Post Utilities
+
+"""
+
 import json
 from typing import Dict
 
 __all__ = ["Post"]
 
+from substack.exceptions import SectionNotExistsException
+
 
 class Post:
+    """
+
+    Post utility class
+
+    """
+
     def __init__(
-            self,
-            title: str,
-            subtitle: str,
-            user_id,
-            audience: str = None,
-            write_comment_permissions: str = None,
+        self,
+        title: str,
+        subtitle: str,
+        user_id,
+        audience: str = None,
+        write_comment_permissions: str = None,
     ):
         """
 
@@ -27,6 +41,8 @@ class Post:
         self.draft_body = {"type": "doc", "content": []}
         self.draft_bylines = [{"id": int(user_id), "is_guest": False}]
         self.audience = audience if audience is not None else "everyone"
+        self.draft_section_id = None
+        self.section_chosen = True
 
         # TODO better understand the possible values and combinations with audience
         if write_comment_permissions is not None:
@@ -34,6 +50,22 @@ class Post:
         else:
             self.write_comment_permissions = self.audience
 
+    def set_section(self, name: str, sections: list):
+        """
+
+        Args:
+            name:
+            sections:
+
+        Returns:
+
+        """
+        section = [s for s in sections if s.get("name") == name]
+        if len(section) != 1:
+            raise SectionNotExistsException(name)
+        section = section[0]
+        self.draft_section_id = section.get("id")
+
     def add(self, item: Dict):
         """
 
@@ -123,20 +155,20 @@ class Post:
         return self
 
     def captioned_image(
-            self,
-            src: str,
-            fullscreen: bool = False,
-            imageSize: str = "normal",
-            height: int = 819,
-            width: int = 1456,
-            resizeWidth: int = 728,
-            bytes: str = None,
-            alt: str = None,
-            title: str = None,
-            type: str = None,
-            href: str = None,
-            belowTheFold: bool = False,
-            internalRedirect: str = None,
+        self,
+        src: str,
+        fullscreen: bool = False,
+        imageSize: str = "normal",
+        height: int = 819,
+        width: int = 1456,
+        resizeWidth: int = 728,
+        bytes: str = None,
+        alt: str = None,
+        title: str = None,
+        type: str = None,
+        href: str = None,
+        belowTheFold: bool = False,
+        internalRedirect: str = None,
     ):
         """
 
@@ -232,7 +264,7 @@ class Post:
         return self
 
     def remove_last_paragraph(self):
-        """ """
+        """Remove last paragraph"""
         del self.draft_body.get("content")[-1]
 
     def get_draft(self):
@@ -262,7 +294,11 @@ class Post:
             Subscribe for free to receive new posts and support my work."""
 
         subscribe = self.draft_body["content"][-1]
-        subscribe["attrs"] = {"url": "%%checkout_url%%", "text": "Subscribe", "language": "en"}
+        subscribe["attrs"] = {
+            "url": "%%checkout_url%%",
+            "text": "Subscribe",
+            "language": "en",
+        }
         subscribe["content"] = [
             {
                 "type": "ctaCaption",

python_substack-0.1.12/README.md

@@ -1,76 +0,0 @@
-# Python Substack
-
-This is an unofficial library providing a Python interface for [Substack](https://substack.com/).
-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
-
----
-
-# Setup
-
-Set the following environment variables by creating a **.env** file:
-
-    PUBLICATION_URL=https://ma2za.substack.com
-    EMAIL=
-    PASSWORD=
-    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
-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
-
-Check out the examples folder for some examples 😃 🚀
-
-```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!'})
-
-#bolden text
-post.add({'type': "paragraph",'content':[{'content': "This is how you "},{'content': "bolden ",'marks':[{'type': "strong"}]},{'content': "a word."}]})
-
-#add hyperlink to text
-post.add({'type':'paragraph','content':[{'content': "View Link",'marks':[{'type': "link",'href':'https://whoraised.substack.com/'}]}]})
-
-#add image
-post.add({'type':'captionedImage','src': "https://media.tenor.com/7B4jMa-a7bsAAAAC/i-am-batman.gif"})
-
-draft = api.post_draft(post.get_draft())
-
-api.prepublish_draft(draft.get("id"))
-
-api.publish_draft(draft.get("id"))
-```
-