python-substack 0.1.15__tar.gz → 0.1.17__tar.gz

python_substack-0.1.17/PKG-INFO

@@ -0,0 +1,285 @@
+Metadata-Version: 2.4
+Name: python-substack
+Version: 0.1.17
+Summary: A Python wrapper around the Substack API.
+License: MIT
+License-File: LICENSE
+Keywords: substack
+Author: Paolo Mazza
+Author-email: mazzapaolo2019@gmail.com
+Requires-Python: >=3.9,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: PyYAML (>=6.0,<7.0)
+Requires-Dist: python-dotenv (>=0.21.0,<0.22.0)
+Requires-Dist: requests (>=2.31.0,<3.0.0)
+Project-URL: Homepage, https://github.com/ma2za/python-substack
+Project-URL: Repository, https://github.com/ma2za/python-substack
+Description-Content-Type: text/markdown
+
+# Python Substack
+
+This is an unofficial library providing a Python interface for [Substack](https://substack.com/).
+I am in no way affiliated with Substack.
+
+[![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=
+    PUBLICATION_URL=  # Optional: your publication URL
+    COOKIES_PATH=     # Optional: path to cookies JSON file
+    COOKIES_STRING=   # Optional: cookie string for authentication
+
+## 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 😃 🚀
+
+## Basic Authentication
+
+```python
+import os
+from dotenv import load_dotenv
+
+from substack import Api
+from substack.post import Post
+
+load_dotenv()
+
+# Authenticate with email and password
+api = Api(
+    email=os.getenv("EMAIL"),
+    password=os.getenv("PASSWORD"),
+    publication_url=os.getenv("PUBLICATION_URL"),
+)
+```
+
+## Cookie-based Authentication
+
+You can also authenticate using cookies instead of email/password:
+
+```python
+import os
+from dotenv import load_dotenv
+
+from substack import Api
+
+load_dotenv()
+
+# Authenticate with cookies (alternative to email/password)
+api = Api(
+    cookies_path=os.getenv("COOKIES_PATH"),  # Path to cookies JSON file
+    # OR
+    cookies_string=os.getenv("COOKIES_STRING"),  # Cookie string
+    publication_url=os.getenv("PUBLICATION_URL"),
+)
+```
+
+## Creating and Publishing Posts
+
+```python
+user_id = api.get_user_id()
+
+# Switch Publications - The library defaults to your user's 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)
+
+# Create a post with basic settings
+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
+)
+
+# Create a post with audience and comment permissions
+post = Post(
+    title="My Post Title",
+    subtitle="My Post Subtitle",
+    user_id=user_id,
+    audience="everyone",  # Options: "everyone", "only_paid", "founding", "only_free"
+    write_comment_permissions="everyone"  # Options: "none", "only_paid", "everyone"
+)
+
+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")})
+
+# embed publication
+embedded = api.publication_embed("https://jackio.substack.com/")
+post.add({"type": "embeddedPublication", "url": embedded})
+
+# create post from Markdown
+markdown_content = """
+# My Heading
+
+This is a paragraph with **bold** and *italic* text.
+
+![Image Alt](https://example.com/image.jpg)
+"""
+post.from_markdown(markdown_content, api=api)
+
+draft = api.post_draft(post.get_draft())
+
+# set section (can only be done after first posting 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"))
+```
+
+## Loading Posts from YAML Files
+
+You can define your posts in YAML files for easier management:
+
+```python
+import yaml
+import os
+from dotenv import load_dotenv
+
+from substack import Api
+from substack.post import Post
+
+load_dotenv()
+
+# Load post data from YAML file
+with open("draft.yaml", "r") as fp:
+    post_data = yaml.safe_load(fp)
+
+# Authenticate (using cookies or email/password)
+cookies_path = os.getenv("COOKIES_PATH")
+cookies_string = os.getenv("COOKIES_STRING")
+
+api = Api(
+    email=os.getenv("EMAIL") if not cookies_path and not cookies_string else None,
+    password=os.getenv("PASSWORD") if not cookies_path and not cookies_string else None,
+    cookies_path=cookies_path,
+    cookies_string=cookies_string,
+    publication_url=os.getenv("PUBLICATION_URL"),
+)
+
+user_id = api.get_user_id()
+
+# Create post from YAML data
+post = Post(
+    post_data.get("title"),
+    post_data.get("subtitle", ""),
+    user_id,
+    audience=post_data.get("audience", "everyone"),
+    write_comment_permissions=post_data.get("write_comment_permissions", "everyone"),
+)
+
+# Add body content from YAML
+body = post_data.get("body", {})
+for _, item in body.items():
+    # Handle local images - upload them first
+    if item.get("type") == "captionedImage" and not item.get("src").startswith("http"):
+        image = api.get_image(item.get("src"))
+        item.update({"src": image.get("url")})
+    post.add(item)
+
+draft = api.post_draft(post.get_draft())
+api.put_draft(draft.get("id"), draft_section_id=post.draft_section_id)
+
+# Publish the draft
+api.prepublish_draft(draft.get("id"))
+api.publish_draft(draft.get("id"))
+```
+
+Example YAML structure:
+
+```yaml
+title: "My Post Title"
+subtitle: "My Post Subtitle"
+audience: "everyone"  # everyone, only_paid, founding, only_free
+write_comment_permissions: "everyone"  # none, only_paid, everyone
+section: "my-section"
+body:
+  0:
+    type: "heading"
+    level: 1
+    content: "Introduction"
+  1:
+    type: "paragraph"
+    content: "This is a paragraph."
+  2:
+    type: "captionedImage"
+    src: "local_image.jpg"  # Local images will be uploaded automatically
+```
+
+# Contributing
+
+Install pre-commit:
+
+```shell
+pip install pre-commit
+```
+
+Set up pre-commit
+
+```shell
+pre-commit install
+```
+
+## Cookie Help
+
+To get a cookie string, after login, go to dev tools (F12), network tab, refresh and find one of the requests like subscription/unred/subscriptions, right click and copy as fetch (Node.js), paste somewhere and get the entire cookie string assigned to the cookie header and put it in the env variables as COOKIES_STRING, et voila!
+

python_substack-0.1.17/README.md

@@ -0,0 +1,259 @@
+# Python Substack
+
+This is an unofficial library providing a Python interface for [Substack](https://substack.com/).
+I am in no way affiliated with Substack.
+
+[![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=
+    PUBLICATION_URL=  # Optional: your publication URL
+    COOKIES_PATH=     # Optional: path to cookies JSON file
+    COOKIES_STRING=   # Optional: cookie string for authentication
+
+## 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 😃 🚀
+
+## Basic Authentication
+
+```python
+import os
+from dotenv import load_dotenv
+
+from substack import Api
+from substack.post import Post
+
+load_dotenv()
+
+# Authenticate with email and password
+api = Api(
+    email=os.getenv("EMAIL"),
+    password=os.getenv("PASSWORD"),
+    publication_url=os.getenv("PUBLICATION_URL"),
+)
+```
+
+## Cookie-based Authentication
+
+You can also authenticate using cookies instead of email/password:
+
+```python
+import os
+from dotenv import load_dotenv
+
+from substack import Api
+
+load_dotenv()
+
+# Authenticate with cookies (alternative to email/password)
+api = Api(
+    cookies_path=os.getenv("COOKIES_PATH"),  # Path to cookies JSON file
+    # OR
+    cookies_string=os.getenv("COOKIES_STRING"),  # Cookie string
+    publication_url=os.getenv("PUBLICATION_URL"),
+)
+```
+
+## Creating and Publishing Posts
+
+```python
+user_id = api.get_user_id()
+
+# Switch Publications - The library defaults to your user's 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)
+
+# Create a post with basic settings
+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
+)
+
+# Create a post with audience and comment permissions
+post = Post(
+    title="My Post Title",
+    subtitle="My Post Subtitle",
+    user_id=user_id,
+    audience="everyone",  # Options: "everyone", "only_paid", "founding", "only_free"
+    write_comment_permissions="everyone"  # Options: "none", "only_paid", "everyone"
+)
+
+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")})
+
+# embed publication
+embedded = api.publication_embed("https://jackio.substack.com/")
+post.add({"type": "embeddedPublication", "url": embedded})
+
+# create post from Markdown
+markdown_content = """
+# My Heading
+
+This is a paragraph with **bold** and *italic* text.
+
+![Image Alt](https://example.com/image.jpg)
+"""
+post.from_markdown(markdown_content, api=api)
+
+draft = api.post_draft(post.get_draft())
+
+# set section (can only be done after first posting 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"))
+```
+
+## Loading Posts from YAML Files
+
+You can define your posts in YAML files for easier management:
+
+```python
+import yaml
+import os
+from dotenv import load_dotenv
+
+from substack import Api
+from substack.post import Post
+
+load_dotenv()
+
+# Load post data from YAML file
+with open("draft.yaml", "r") as fp:
+    post_data = yaml.safe_load(fp)
+
+# Authenticate (using cookies or email/password)
+cookies_path = os.getenv("COOKIES_PATH")
+cookies_string = os.getenv("COOKIES_STRING")
+
+api = Api(
+    email=os.getenv("EMAIL") if not cookies_path and not cookies_string else None,
+    password=os.getenv("PASSWORD") if not cookies_path and not cookies_string else None,
+    cookies_path=cookies_path,
+    cookies_string=cookies_string,
+    publication_url=os.getenv("PUBLICATION_URL"),
+)
+
+user_id = api.get_user_id()
+
+# Create post from YAML data
+post = Post(
+    post_data.get("title"),
+    post_data.get("subtitle", ""),
+    user_id,
+    audience=post_data.get("audience", "everyone"),
+    write_comment_permissions=post_data.get("write_comment_permissions", "everyone"),
+)
+
+# Add body content from YAML
+body = post_data.get("body", {})
+for _, item in body.items():
+    # Handle local images - upload them first
+    if item.get("type") == "captionedImage" and not item.get("src").startswith("http"):
+        image = api.get_image(item.get("src"))
+        item.update({"src": image.get("url")})
+    post.add(item)
+
+draft = api.post_draft(post.get_draft())
+api.put_draft(draft.get("id"), draft_section_id=post.draft_section_id)
+
+# Publish the draft
+api.prepublish_draft(draft.get("id"))
+api.publish_draft(draft.get("id"))
+```
+
+Example YAML structure:
+
+```yaml
+title: "My Post Title"
+subtitle: "My Post Subtitle"
+audience: "everyone"  # everyone, only_paid, founding, only_free
+write_comment_permissions: "everyone"  # none, only_paid, everyone
+section: "my-section"
+body:
+  0:
+    type: "heading"
+    level: 1
+    content: "Introduction"
+  1:
+    type: "paragraph"
+    content: "This is a paragraph."
+  2:
+    type: "captionedImage"
+    src: "local_image.jpg"  # Local images will be uploaded automatically
+```
+
+# Contributing
+
+Install pre-commit:
+
+```shell
+pip install pre-commit
+```
+
+Set up pre-commit
+
+```shell
+pre-commit install
+```
+
+## Cookie Help
+
+To get a cookie string, after login, go to dev tools (F12), network tab, refresh and find one of the requests like subscription/unred/subscriptions, right click and copy as fetch (Node.js), paste somewhere and get the entire cookie string assigned to the cookie header and put it in the env variables as COOKIES_STRING, et voila!

{python_substack-0.1.15 → python_substack-0.1.17}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "python-substack"
-version = "0.1.15"
+version = "0.1.17"
 description = "A Python wrapper around the Substack API."
 authors = ["Paolo Mazza <mazzapaolo2019@gmail.com>"]
 license = "MIT"
@@ -16,14 +16,14 @@ homepage = "https://github.com/ma2za/python-substack"
 keywords = ["substack"]
 
 [tool.poetry.dependencies]
-python = "^3.7"
+python = "^3.9"
 
 requests = "^2.31.0"
 python-dotenv = "^0.21.0"
 PyYAML = "^6.0"
 
 
-[tool.poetry.dev-dependencies]
+[tool.poetry.group.dev.dependencies]
 
 
 [build-system]

{python_substack-0.1.15 → python_substack-0.1.17}/substack/api.py

@@ -9,7 +9,7 @@ import json
 import logging
 import os
 from datetime import datetime
-from urllib.parse import urljoin
+from urllib.parse import urljoin, unquote
 
 import requests
 
@@ -35,6 +35,7 @@ class Api:
         base_url=None,
         publication_url=None,
         debug=False,
+        cookies_string=None,
     ):
         """
 
@@ -49,6 +50,10 @@ class Api:
             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.
+          cookies_string
+            To re-use your session without logging in each time, you can provide cookies as a semicolon-separated
+            string (e.g., "cookie1=value1; cookie2=value2"). This is useful when copying cookies from browser
+            developer tools.
           base_url:
             The base URL to use to contact the Substack API.
             Defaults to https://substack.com/api/v1.
@@ -68,11 +73,15 @@ class Api:
                 cookies = json.load(f)
             self._session.cookies.update(cookies)
 
+        elif cookies_string is not None:
+            cookies = self._parse_cookies_string(cookies_string)
+            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."
+                "Must provide email and password, cookies_path, or cookies_string to authenticate."
             )
 
         user_publication = None
@@ -98,6 +107,31 @@ class Api:
         # set the current publication to the users primary publication
         self.change_publication(user_publication)
 
+    @staticmethod
+    def _parse_cookies_string(cookies_string: str) -> dict:
+        """
+        Parse a semicolon-separated cookie string into a dictionary.
+        
+        Args:
+            cookies_string: A semicolon-separated string of cookies (e.g., "cookie1=value1; cookie2=value2")
+            
+        Returns:
+            A dictionary of cookie name-value pairs
+        """
+        cookies = {}
+        for cookie_pair in cookies_string.split(';'):
+            cookie_pair = cookie_pair.strip()
+            if not cookie_pair:
+                continue
+            if '=' in cookie_pair:
+                key, value = cookie_pair.split('=', 1)
+                key = key.strip()
+                value = value.strip()
+                # URL decode the value (e.g., s%3A becomes s:)
+                value = unquote(value)
+                cookies[key] = value
+        return cookies
+
     def login(self, email, password) -> dict:
         """
 
@@ -189,8 +223,8 @@ class Api:
         Args:
             publication:
         """
-        custom_domain = publication["custom_domain"]
-        if not custom_domain:
+        custom_domain = publication.get("custom_domain", None)
+        if not custom_domain and not publication.get('custom_domain_optional', None):
             publication_url = f"https://{publication['subdomain']}.substack.com"
         else:
             publication_url = f"https://{custom_domain}"
@@ -203,7 +237,31 @@ class Api:
         """
 
         profile = self.get_user_profile()
-        primary_publication = profile["primaryPublication"]
+        primary_publication = None
+        
+        # Try old API format first (backward compatibility)
+        if "primaryPublication" in profile and profile["primaryPublication"] is not None:
+            primary_publication = profile["primaryPublication"]
+        else:
+            # New API format: look for primary publication in publicationUsers
+            publication_users = profile.get("publicationUsers")
+            if publication_users is not None and len(publication_users) > 0:
+                # Find the publication where is_primary is True
+                for pub_user in publication_users:
+                    if pub_user.get("is_primary", False):
+                        primary_publication = pub_user.get("publication")
+                        if primary_publication:
+                            break
+                
+                # If no primary found, use the first publication
+                if primary_publication is None:
+                    primary_publication = publication_users[0].get("publication")
+        
+        if primary_publication is None:
+            raise SubstackRequestException(
+                "Could not find primary publication in profile"
+            )
+            
         primary_publication["publication_url"] = self.get_publication_url(
             primary_publication
         )
@@ -220,10 +278,18 @@ class Api:
         # 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)
+        publication_users = profile.get("publicationUsers")
+        
+        if publication_users is None:
+            # If publicationUsers is None, return empty list or try to construct from other fields
+            # This maintains backward compatibility while handling new API format
+            return user_publications
+        
+        for publication in publication_users:
+            pub = publication.get("publication")
+            if pub is not None:
+                pub["publication_url"] = self.get_publication_url(pub)
+                user_publications.append(pub)
 
         return user_publications