python-substack 0.1.16__py3-none-any.whl → 0.1.17__py3-none-any.whl

{python_substack-0.1.16.dist-info → python_substack-0.1.17.dist-info}/METADATA

@@ -1,17 +1,15 @@
 Metadata-Version: 2.4
 Name: python-substack
-Version: 0.1.16
+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.7,<4.0
+Requires-Python: >=3.9,<4.0
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.7
-Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
@@ -30,7 +28,6 @@ Description-Content-Type: text/markdown
 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)
 ---
@@ -72,18 +69,49 @@ The .env file will be ignored by git but always be careful.
 
 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.
@@ -96,12 +124,22 @@ 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
@@ -127,6 +165,16 @@ post.add({"type": "captionedImage", "src": image.get("url")})
 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)
@@ -138,6 +186,85 @@ 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:

python_substack-0.1.17.dist-info/RECORD

@@ -0,0 +1,8 @@
+substack/__init__.py,sha256=mkNj8jFW6wA4dIYyyM1UfKt5Q9MgR8xg3CaADl4IjlQ,387
+substack/api.py,sha256=KFSeStlfmri1qyO_5rOT41dd7QWV-iHqyMbQyVSd5-k,18336
+substack/exceptions.py,sha256=BbP5W5UpzFcM5SYIxx6snWD_Rmj7F_YjYIYC_r03gZY,911
+substack/post.py,sha256=KVwEBeQp32CtzUJPZFf3yACJaPzUiJ0zoZZfyWcqnlM,20820
+python_substack-0.1.17.dist-info/METADATA,sha256=HZKwKT1VRGn7z37sYFn3u4XyIO7up2c7tv0ejuu0Ago,8007
+python_substack-0.1.17.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
+python_substack-0.1.17.dist-info/licenses/LICENSE,sha256=L6jk148I5HhhVbfUvkO3EO7eAoU5zToLio4-ApkCkxg,1062
+python_substack-0.1.17.dist-info/RECORD,,

substack/post.py

@@ -5,13 +5,103 @@ Post Utilities
 """
 
 import json
-from typing import Dict
+import re
+from typing import Dict, List
 
-__all__ = ["Post"]
+__all__ = ["Post", "parse_inline"]
 
 from substack.exceptions import SectionNotExistsException
 
 
+def parse_inline(text: str) -> List[Dict]:
+    """
+    Convert inline Markdown in a text string into a list of tokens
+    for use in the post content.
+
+    Supported formatting:
+      - **Bold**: Text wrapped in double asterisks.
+      - *Italic*: Text wrapped in single asterisks.
+      - [Links]: Text wrapped in square brackets followed by URL in parentheses.
+
+    Args:
+        text: Text string containing inline Markdown formatting.
+
+    Returns:
+        List of token dictionaries with content and marks.
+
+    Example:
+        >>> parse_inline("This is **bold** and this is [a link](https://example.com)")
+        [{'content': 'This is '}, {'content': 'bold', 'marks': [{'type': 'strong'}]}, {'content': ' and this is '}, {'content': 'a link', 'marks': [{'type': 'link', 'attrs': {'href': 'https://example.com'}}]}]
+    """
+    if not text:
+        return []
+
+    tokens = []
+    # Process text character by character to handle nested formatting
+    # We'll use regex to find all markdown patterns, then process them in order
+    
+    # Find all markdown patterns: links, bold, italic
+    # Pattern order: links first (to avoid conflicts), then bold, then italic
+    link_pattern = r'\[([^\]]+)\]\(([^)]+)\)'
+    bold_pattern = r'\*\*([^*]+)\*\*'
+    italic_pattern = r'(?<!\*)\*([^*]+)\*(?!\*)'  # Not preceded or followed by *
+    
+    # Find all matches with their positions
+    matches = []
+    for match in re.finditer(link_pattern, text):
+        # Skip if it's an image link (starts with ![)
+        if match.start() > 0 and text[match.start()-1:match.start()+1] != "![":
+            matches.append((match.start(), match.end(), "link", match.group(1), match.group(2)))
+    
+    for match in re.finditer(bold_pattern, text):
+        # Check if this range is already covered by a link
+        if not any(start <= match.start() < end for start, end, _, _, _ in matches):
+            matches.append((match.start(), match.end(), "bold", match.group(1), None))
+    
+    for match in re.finditer(italic_pattern, text):
+        # Check if this range is already covered by a link or bold
+        if not any(start <= match.start() < end for start, end, _, _, _ in matches):
+            matches.append((match.start(), match.end(), "italic", match.group(1), None))
+    
+    # Sort matches by position
+    matches.sort(key=lambda x: x[0])
+    
+    # Build tokens
+    last_pos = 0
+    for start, end, match_type, content, url in matches:
+        # Add text before this match
+        if start > last_pos:
+            tokens.append({"content": text[last_pos:start]})
+        
+        # Add the formatted content
+        if match_type == "link":
+            tokens.append({
+                "content": content,
+                "marks": [{"type": "link", "attrs": {"href": url}}]
+            })
+        elif match_type == "bold":
+            tokens.append({
+                "content": content,
+                "marks": [{"type": "strong"}]
+            })
+        elif match_type == "italic":
+            tokens.append({
+                "content": content,
+                "marks": [{"type": "em"}]
+            })
+        
+        last_pos = end
+    
+    # Add remaining text
+    if last_pos < len(text):
+        tokens.append({"content": text[last_pos:]})
+    
+    # Filter out empty tokens
+    tokens = [t for t in tokens if t.get("content")]
+    
+    return tokens
+
+
 class Post:
     """
 
@@ -90,6 +180,8 @@ class Post:
             self.youtube(item.get("src"))
         elif item.get("type") == "subscribeWidget":
             self.subscribe_with_caption(item.get("message"))
+        elif item.get("type") == "codeBlock":
+            self.code_block(item.get("content"), item.get("attrs", {}))
         else:
             if content is not None:
                 self.add_complex_text(content)
@@ -329,3 +421,217 @@ class Post:
         content_attrs.update({"videoId": value})
         self.draft_body["content"][-1]["attrs"] = content_attrs
         return self
+
+    def code_block(self, content, attrs=None):
+        """
+        Add code block to post.
+
+        Args:
+            content: String containing code or list of text nodes
+            attrs: Optional attributes like language
+
+        Returns:
+
+        """
+        if attrs is None:
+            attrs = {}
+
+        # Handle content - can be list of text nodes or a string
+        if isinstance(content, str):
+            # Convert string to list of text nodes
+            code_content = [{"type": "text", "text": content}]
+        elif isinstance(content, list):
+            code_content = content
+        else:
+            code_content = []
+
+        # Set up the code block structure
+        code_block = self.draft_body["content"][-1]
+        code_block["content"] = code_content
+        if attrs:
+            code_block["attrs"] = attrs
+
+        return self
+
+    def from_markdown(self, markdown_content: str, api=None):
+        """
+        Parse Markdown content and add it to the post.
+
+        Supported Markdown features:
+          - Headings: Lines starting with '#' characters (1-6 levels)
+          - Images: Markdown image syntax ![Alt](URL)
+          - Linked images: [![Alt](image_url)](link_url) - images that are also links
+          - Links: [text](url) - inline links in paragraphs
+          - Code blocks: Fenced code blocks with ```language or ```
+          - Paragraphs: Regular text blocks
+          - Bullet lists: Lines starting with '*' or '-'
+          - Inline formatting: **bold** and *italic* within paragraphs
+
+        Args:
+            markdown_content: Markdown string to parse and add to the post.
+            api: Optional Api instance for uploading local images. If provided,
+                 local image paths will be uploaded via api.get_image().
+
+        Returns:
+            Self for method chaining.
+
+        Example:
+            >>> post = Post("Title", "Subtitle", user_id)
+            >>> post.from_markdown("# Heading\\n\\nThis is **bold** text with [a link](https://example.com).")
+        """
+        lines = markdown_content.split("\n")
+        blocks = []
+        current_block: List[str] = []
+        in_code_block = False
+        code_block_language = None
+
+        for line in lines:
+            # Check for fenced code block start/end
+            if line.strip().startswith("```"):
+                if in_code_block:
+                    # End of code block
+                    if current_block:
+                        blocks.append({
+                            "type": "code",
+                            "language": code_block_language,
+                            "content": "\n".join(current_block)
+                        })
+                    current_block = []
+                    in_code_block = False
+                    code_block_language = None
+                else:
+                    # Start of code block
+                    if current_block:
+                        blocks.append({"type": "text", "content": "\n".join(current_block)})
+                        current_block = []
+                    # Extract language if specified
+                    language = line.strip()[3:].strip()
+                    code_block_language = language if language else None
+                    in_code_block = True
+                continue
+
+            if in_code_block:
+                # Inside code block - collect lines as-is
+                current_block.append(line)
+            else:
+                # Regular content
+                if line.strip() == "":
+                    # Empty line - end current block if it has content
+                    if current_block:
+                        blocks.append({"type": "text", "content": "\n".join(current_block)})
+                        current_block = []
+                else:
+                    current_block.append(line)
+
+        # Add any remaining content
+        if current_block:
+            if in_code_block:
+                blocks.append({
+                    "type": "code",
+                    "language": code_block_language,
+                    "content": "\n".join(current_block)
+                })
+            else:
+                blocks.append({"type": "text", "content": "\n".join(current_block)})
+
+        # Process blocks
+        for block in blocks:
+            if block["type"] == "code":
+                # Add code block
+                code_content = block.get("content", "").strip()
+                if code_content:
+                    # Substack uses "codeBlock" type
+                    code_attrs = {}
+                    if block.get("language"):
+                        code_attrs["language"] = block["language"]
+                    self.add({
+                        "type": "codeBlock",
+                        "content": code_content,  # Pass as string, code_block method will handle it
+                        "attrs": code_attrs
+                    })
+            else:
+                # Process text block
+                text_content = block.get("content", "").strip()
+                if not text_content:
+                    continue
+
+                # Process headings (lines starting with '#' characters)
+                if text_content.startswith("#"):
+                    level = len(text_content) - len(text_content.lstrip("#"))
+                    heading_text = text_content.lstrip("#").strip()
+                    if heading_text:  # Only add if there's actual text
+                        self.heading(content=heading_text, level=min(level, 6))
+
+                # Process images using Markdown image syntax: ![Alt](URL)
+                # Also handle linked images: [![Alt](image_url)](link_url)
+                elif text_content.startswith("!") or (text_content.startswith("[") and "![" in text_content):
+                    # Check for linked image first: [![alt](img)](link)
+                    linked_image_match = re.match(r'\[!\[([^\]]*)\]\(([^)]+)\)\]\(([^)]+)\)', text_content)
+                    if linked_image_match:
+                        # Linked image - create image with href
+                        alt_text = linked_image_match.group(1)
+                        image_url = linked_image_match.group(2)
+                        link_url = linked_image_match.group(3)
+                        
+                        # Adjust image URL if it starts with a slash
+                        image_url = image_url[1:] if image_url.startswith("/") else image_url
+
+                        # If api is provided and image_url is a local file, upload it
+                        if api is not None:
+                            try:
+                                image = api.get_image(image_url)
+                                image_url = image.get("url")
+                            except Exception:
+                                # If upload fails, use original URL
+                                pass
+
+                        self.add({
+                            "type": "captionedImage",
+                            "src": image_url,
+                            "alt": alt_text,
+                            "href": link_url
+                        })
+                    else:
+                        # Regular image: ![Alt](URL)
+                        match = re.match(r"!\[.*?\]\((.*?)\)", text_content)
+                        if match:
+                            image_url = match.group(1)
+                            # Adjust image URL if it starts with a slash
+                            image_url = image_url[1:] if image_url.startswith("/") else image_url
+
+                            # If api is provided and image_url is a local file, upload it
+                            if api is not None:
+                                try:
+                                    image = api.get_image(image_url)
+                                    image_url = image.get("url")
+                                except Exception:
+                                    # If upload fails, use original URL
+                                    pass
+
+                            self.add({"type": "captionedImage", "src": image_url})
+
+                # Process paragraphs or bullet lists
+                else:
+                    if "\n" in text_content:
+                        # Process each line separately (for bullet lists)
+                        for line in text_content.split("\n"):
+                            line = line.strip()
+                            if not line:
+                                continue
+                            # Remove bullet marker if present
+                            if line.startswith("* "):
+                                line = line[2:].strip()
+                            elif line.startswith("- "):
+                                line = line[2:].strip()
+                            elif line.startswith("*") and not line.startswith("**"):
+                                line = line[1:].strip()
+
+                            if line:
+                                tokens = parse_inline(line)
+                                self.add({"type": "paragraph", "content": tokens})
+                    else:
+                        # Single paragraph
+                        tokens = parse_inline(text_content)
+                        self.add({"type": "paragraph", "content": tokens})
+
+        return self

python_substack-0.1.16.dist-info/RECORD

@@ -1,8 +0,0 @@
-substack/__init__.py,sha256=mkNj8jFW6wA4dIYyyM1UfKt5Q9MgR8xg3CaADl4IjlQ,387
-substack/api.py,sha256=KFSeStlfmri1qyO_5rOT41dd7QWV-iHqyMbQyVSd5-k,18336
-substack/exceptions.py,sha256=BbP5W5UpzFcM5SYIxx6snWD_Rmj7F_YjYIYC_r03gZY,911
-substack/post.py,sha256=rcnTfWUqfuocvHN61UxidbAiX4Y7LtcvSAkLjjsxqxM,7997
-python_substack-0.1.16.dist-info/METADATA,sha256=GVC0syynaz3zkNQLr3GzjV-mgA6mOCXALwcqfQs5X5w,4925
-python_substack-0.1.16.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
-python_substack-0.1.16.dist-info/licenses/LICENSE,sha256=L6jk148I5HhhVbfUvkO3EO7eAoU5zToLio4-ApkCkxg,1062
-python_substack-0.1.16.dist-info/RECORD,,