substack-api 1.0.2__tar.gz → 1.1.2__tar.gz

substack_api-1.1.2/PKG-INFO

@@ -0,0 +1,221 @@
+Metadata-Version: 2.4
+Name: substack-api
+Version: 1.1.2
+Summary: Unofficial wrapper for the Substack API
+Project-URL: Homepage, https://github.com/nhagar/substack_api
+Project-URL: Bug Tracker, https://github.com/nhagar/substack_api/issues
+Project-URL: Documentation, https://nhagar.github.io/substack_api/
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.32.3
+Dynamic: license-file
+
+# Substack API
+
+An unofficial Python client library for interacting with Substack newsletters and content.
+
+## Overview
+
+This library provides Python interfaces for interacting with Substack's unofficial API, allowing you to:
+
+- Retrieve newsletter posts, podcasts, and recommendations
+- Get user profile information and subscriptions
+- Fetch post content and metadata
+- Search for posts within newsletters
+- Access paywalled content **that you have written or paid for** with user-provided authentication
+
+## Installation
+
+```bash
+# Using pip
+pip install substack-api
+
+# Using poetry
+poetry add substack-api
+```
+
+## Usage Examples
+
+### Working with Newsletters
+
+```python
+from substack_api import Newsletter
+
+# Initialize a newsletter by its URL
+newsletter = Newsletter("https://example.substack.com")
+
+# Get recent posts (returns Post objects)
+recent_posts = newsletter.get_posts(limit=5)
+
+# Get posts sorted by popularity
+top_posts = newsletter.get_posts(sorting="top", limit=10)
+
+# Search for posts
+search_results = newsletter.search_posts("machine learning", limit=3)
+
+# Get podcast episodes
+podcasts = newsletter.get_podcasts(limit=5)
+
+# Get recommended newsletters
+recommendations = newsletter.get_recommendations()
+
+# Get newsletter authors
+authors = newsletter.get_authors()
+```
+
+### Working with Posts
+
+```python
+from substack_api import Post
+
+# Initialize a post by its URL
+post = Post("https://example.substack.com/p/post-slug")
+
+# Get post metadata
+metadata = post.get_metadata()
+
+# Get the post's HTML content
+content = post.get_content()
+```
+
+### Accessing Paywalled Content with Authentication
+
+To access paywalled content, you need to provide your own session cookies from a logged-in Substack session:
+
+```python
+from substack_api import Newsletter, Post, SubstackAuth
+
+# Set up authentication with your cookies
+auth = SubstackAuth(cookies_path="path/to/your/cookies.json")
+
+# Use authentication with newsletters
+newsletter = Newsletter("https://example.substack.com", auth=auth)
+posts = newsletter.get_posts(limit=5)  # Can now access paywalled posts
+
+# Use authentication with individual posts
+post = Post("https://example.substack.com/p/paywalled-post", auth=auth)
+content = post.get_content()  # Can now access paywalled content
+
+# Check if a post is paywalled
+if post.is_paywalled():
+    print("This post requires a subscription")
+```
+
+#### Getting Your Cookies
+
+To access paywalled content, you need to export your browser cookies from a logged-in Substack session. The cookies should be in JSON format with the following structure:
+
+```json
+[
+  {
+    "name": "substack.sid",
+    "value": "your_session_id",
+    "domain": ".substack.com",
+    "path": "/",
+    "secure": true
+  },
+  {
+    "name": "substack.lli", 
+    "value": "your_lli_value",
+    "domain": ".substack.com",
+    "path": "/",
+    "secure": true
+  },
+  ...
+]
+```
+
+**Important**: Only use your own cookies from your own authenticated session. **This feature is intended for users to access their own subscribed or authored content programmatically.**
+
+### Working with Users
+
+```python
+from substack_api import User
+
+# Initialize a user by their username
+user = User("username")
+
+# Get user profile information
+profile_data = user.get_raw_data()
+
+# Get user ID and name
+user_id = user.id
+name = user.name
+
+# Get user's subscriptions
+subscriptions = user.get_subscriptions()
+```
+
+#### Handling Renamed Accounts
+Substack allows users to change their handle (username) at any time. When this happens, the old API endpoints return 404 errors. This library automatically handles these redirects by default.
+##### Automatic Redirect Handling
+
+```python
+from substack_api import User
+
+# This will automatically follow redirects if the handle has changed
+user = User("oldhandle")  # Will find the user even if they renamed to "newhandle"
+
+# Check if a redirect occurred
+if user.was_redirected:
+    print(f"User was renamed from {user.original_username} to {user.username}")
+```
+
+##### Disable Redirect Following
+
+If you prefer to handle 404s yourself:
+
+```python
+# Disable automatic redirect following
+user = User("oldhandle", follow_redirects=False)
+```
+
+##### Manual Handle Resolution
+
+You can also manually resolve handle redirects:
+
+```python
+from substack_api import resolve_handle_redirect
+
+new_handle = resolve_handle_redirect("oldhandle")
+if new_handle:
+    print(f"Handle was renamed to: {new_handle}")
+```
+## Limitations
+
+- This is an unofficial library and not endorsed by Substack
+- APIs may change without notice, potentially breaking functionality
+- Rate limiting may be enforced by Substack
+- **Authentication requires users to provide their own session cookies**
+- **Users are responsible for complying with Substack's terms of service when using authentication features**
+
+## Development
+
+### Running Tests
+
+```bash
+# Install dev dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+```
+
+### Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.
+
+## Disclaimer
+
+This package is not affiliated with, endorsed by, or connected to Substack in any way. It is an independent project created to make Substack content more accessible through Python.

substack_api-1.1.2/README.md

@@ -0,0 +1,208 @@
+# Substack API
+
+An unofficial Python client library for interacting with Substack newsletters and content.
+
+## Overview
+
+This library provides Python interfaces for interacting with Substack's unofficial API, allowing you to:
+
+- Retrieve newsletter posts, podcasts, and recommendations
+- Get user profile information and subscriptions
+- Fetch post content and metadata
+- Search for posts within newsletters
+- Access paywalled content **that you have written or paid for** with user-provided authentication
+
+## Installation
+
+```bash
+# Using pip
+pip install substack-api
+
+# Using poetry
+poetry add substack-api
+```
+
+## Usage Examples
+
+### Working with Newsletters
+
+```python
+from substack_api import Newsletter
+
+# Initialize a newsletter by its URL
+newsletter = Newsletter("https://example.substack.com")
+
+# Get recent posts (returns Post objects)
+recent_posts = newsletter.get_posts(limit=5)
+
+# Get posts sorted by popularity
+top_posts = newsletter.get_posts(sorting="top", limit=10)
+
+# Search for posts
+search_results = newsletter.search_posts("machine learning", limit=3)
+
+# Get podcast episodes
+podcasts = newsletter.get_podcasts(limit=5)
+
+# Get recommended newsletters
+recommendations = newsletter.get_recommendations()
+
+# Get newsletter authors
+authors = newsletter.get_authors()
+```
+
+### Working with Posts
+
+```python
+from substack_api import Post
+
+# Initialize a post by its URL
+post = Post("https://example.substack.com/p/post-slug")
+
+# Get post metadata
+metadata = post.get_metadata()
+
+# Get the post's HTML content
+content = post.get_content()
+```
+
+### Accessing Paywalled Content with Authentication
+
+To access paywalled content, you need to provide your own session cookies from a logged-in Substack session:
+
+```python
+from substack_api import Newsletter, Post, SubstackAuth
+
+# Set up authentication with your cookies
+auth = SubstackAuth(cookies_path="path/to/your/cookies.json")
+
+# Use authentication with newsletters
+newsletter = Newsletter("https://example.substack.com", auth=auth)
+posts = newsletter.get_posts(limit=5)  # Can now access paywalled posts
+
+# Use authentication with individual posts
+post = Post("https://example.substack.com/p/paywalled-post", auth=auth)
+content = post.get_content()  # Can now access paywalled content
+
+# Check if a post is paywalled
+if post.is_paywalled():
+    print("This post requires a subscription")
+```
+
+#### Getting Your Cookies
+
+To access paywalled content, you need to export your browser cookies from a logged-in Substack session. The cookies should be in JSON format with the following structure:
+
+```json
+[
+  {
+    "name": "substack.sid",
+    "value": "your_session_id",
+    "domain": ".substack.com",
+    "path": "/",
+    "secure": true
+  },
+  {
+    "name": "substack.lli", 
+    "value": "your_lli_value",
+    "domain": ".substack.com",
+    "path": "/",
+    "secure": true
+  },
+  ...
+]
+```
+
+**Important**: Only use your own cookies from your own authenticated session. **This feature is intended for users to access their own subscribed or authored content programmatically.**
+
+### Working with Users
+
+```python
+from substack_api import User
+
+# Initialize a user by their username
+user = User("username")
+
+# Get user profile information
+profile_data = user.get_raw_data()
+
+# Get user ID and name
+user_id = user.id
+name = user.name
+
+# Get user's subscriptions
+subscriptions = user.get_subscriptions()
+```
+
+#### Handling Renamed Accounts
+Substack allows users to change their handle (username) at any time. When this happens, the old API endpoints return 404 errors. This library automatically handles these redirects by default.
+##### Automatic Redirect Handling
+
+```python
+from substack_api import User
+
+# This will automatically follow redirects if the handle has changed
+user = User("oldhandle")  # Will find the user even if they renamed to "newhandle"
+
+# Check if a redirect occurred
+if user.was_redirected:
+    print(f"User was renamed from {user.original_username} to {user.username}")
+```
+
+##### Disable Redirect Following
+
+If you prefer to handle 404s yourself:
+
+```python
+# Disable automatic redirect following
+user = User("oldhandle", follow_redirects=False)
+```
+
+##### Manual Handle Resolution
+
+You can also manually resolve handle redirects:
+
+```python
+from substack_api import resolve_handle_redirect
+
+new_handle = resolve_handle_redirect("oldhandle")
+if new_handle:
+    print(f"Handle was renamed to: {new_handle}")
+```
+## Limitations
+
+- This is an unofficial library and not endorsed by Substack
+- APIs may change without notice, potentially breaking functionality
+- Rate limiting may be enforced by Substack
+- **Authentication requires users to provide their own session cookies**
+- **Users are responsible for complying with Substack's terms of service when using authentication features**
+
+## Development
+
+### Running Tests
+
+```bash
+# Install dev dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+```
+
+### Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.
+
+## Disclaimer
+
+This package is not affiliated with, endorsed by, or connected to Substack in any way. It is an independent project created to make Substack content more accessible through Python.

{substack_api-1.0.2 → substack_api-1.1.2}/pyproject.toml

@@ -1,12 +1,10 @@
 [project]
 name = "substack-api"
-version = "1.0.2"
+version = "1.1.2"
 description = "Unofficial wrapper for the Substack API"
 readme = "README.md"
 requires-python = ">=3.12"
-dependencies = [
-    "requests>=2.32.3",
-]
+dependencies = ["requests>=2.32.3"]
 
 [dependency-groups]
 dev = [
@@ -18,3 +16,8 @@ dev = [
     "pytest>=8.3.4",
     "ruff>=0.9.9",
 ]
+
+[project.urls]
+"Homepage" = "https://github.com/nhagar/substack_api"
+"Bug Tracker" = "https://github.com/nhagar/substack_api/issues"
+"Documentation" = "https://nhagar.github.io/substack_api/"

substack_api-1.1.2/substack_api/__init__.py

@@ -0,0 +1,15 @@
+from .auth import SubstackAuth
+from .category import Category, list_all_categories
+from .newsletter import Newsletter
+from .post import Post
+from .user import User, resolve_handle_redirect
+
+__all__ = [
+    "User",
+    "Post",
+    "Category",
+    "Newsletter",
+    "SubstackAuth",
+    "resolve_handle_redirect",
+    "list_all_categories",
+]

substack_api-1.1.2/substack_api/auth.py

@@ -0,0 +1,106 @@
+import json
+import os
+
+import requests
+
+
+class SubstackAuth:
+    """Handles authentication for Substack API requests."""
+
+    def __init__(
+        self,
+        cookies_path: str,
+    ):
+        """
+        Initialize authentication handler.
+
+        Parameters
+        ----------
+        cookies_path : str, optional
+            Path to retrieve session cookies from
+        """
+        self.cookies_path = cookies_path
+        self.session = requests.Session()
+        self.authenticated = False
+
+        # Set default headers
+        self.session.headers.update(
+            {
+                "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.77 Safari/537.36",
+                "Accept": "application/json",
+                "Content-Type": "application/json",
+            }
+        )
+
+        # Try to load existing cookies
+        if os.path.exists(self.cookies_path):
+            self.load_cookies()
+            self.authenticated = True
+        else:
+            print(f"Cookies file not found at {self.cookies_path}. Please log in.")
+            self.authenticated = False
+            self.session.cookies.clear()
+
+    def load_cookies(self) -> bool:
+        """
+        Load cookies from file.
+
+        Returns
+        -------
+        bool
+            True if cookies loaded successfully
+        """
+        try:
+            with open(self.cookies_path, "r") as f:
+                cookies = json.load(f)
+
+            for cookie in cookies:
+                self.session.cookies.set(
+                    cookie["name"],
+                    cookie["value"],
+                    domain=cookie.get("domain"),
+                    path=cookie.get("path", "/"),
+                    secure=cookie.get("secure", False),
+                )
+
+            return True
+
+        except Exception as e:
+            print(f"Failed to load cookies: {str(e)}")
+            return False
+
+    def get(self, url: str, **kwargs) -> requests.Response:
+        """
+        Make authenticated GET request.
+
+        Parameters
+        ----------
+        url : str
+            URL to request
+        **kwargs
+            Additional arguments to pass to requests.get
+
+        Returns
+        -------
+        requests.Response
+            Response object
+        """
+        return self.session.get(url, **kwargs)
+
+    def post(self, url: str, **kwargs) -> requests.Response:
+        """
+        Make authenticated POST request.
+
+        Parameters
+        ----------
+        url : str
+            URL to request
+        **kwargs
+            Additional arguments to pass to requests.post
+
+        Returns
+        -------
+        requests.Response
+            Response object
+        """
+        return self.session.post(url, **kwargs)

{substack_api-1.0.2 → substack_api-1.1.2}/substack_api/category.py

@@ -1,3 +1,4 @@
+from time import sleep
 from typing import Any, Dict, List, Optional, Tuple
 
 import requests
@@ -127,6 +128,7 @@ class Category:
             full_url = endpoint + str(page_num)
             r = requests.get(full_url, headers=HEADERS, timeout=30)
             r.raise_for_status()
+            sleep(2)  # Be polite to the server
 
             resp = r.json()
             newsletters = resp["publications"]