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

substack_api-1.1.1/PKG-INFO

@@ -0,0 +1,221 @@
+Metadata-Version: 2.4
+Name: substack-api
+Version: 1.1.1
+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.1/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.1}/pyproject.toml

@@ -1,12 +1,10 @@
 [project]
 name = "substack-api"
-version = "1.0.2"
+version = "1.1.1"
 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.1/substack_api/__init__.py

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

substack_api-1.1.1/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.1}/substack_api/newsletter.py

@@ -3,6 +3,8 @@ from typing import Any, Dict, List, Optional
 
 import requests
 
+from substack_api.auth import SubstackAuth
+
 HEADERS = {
     "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"
 }
@@ -13,7 +15,7 @@ class Newsletter:
     Newsletter class for interacting with Substack newsletters
     """
 
-    def __init__(self, url: str) -> None:
+    def __init__(self, url: str, auth: Optional[SubstackAuth] = None) -> None:
         """
         Initialize a Newsletter object.
 
@@ -21,8 +23,11 @@ class Newsletter:
         ----------
         url : str
             The URL of the Substack newsletter
+        auth : Optional[SubstackAuth]
+            Authentication handler for accessing paywalled content
         """
         self.url = url
+        self.auth = auth
 
     def __str__(self) -> str:
         return f"Newsletter: {self.url}"
@@ -30,6 +35,27 @@ class Newsletter:
     def __repr__(self) -> str:
         return f"Newsletter(url={self.url})"
 
+    def _make_request(self, endpoint: str, **kwargs) -> requests.Response:
+        """
+        Make a GET request to the specified endpoint with authentication if needed.
+
+        Parameters
+        ----------
+        endpoint : str
+            The API endpoint to request
+        **kwargs : Any
+            Additional parameters for the request
+
+        Returns
+        -------
+        requests.Response
+            The response object from the request
+        """
+        if self.auth and self.auth.authenticated:
+            return self.auth.get(endpoint, **kwargs)
+        else:
+            return requests.get(endpoint, headers=HEADERS, **kwargs)
+
     def _fetch_paginated_posts(
         self, params: Dict[str, str], limit: Optional[int] = None, page_size: int = 15
     ) -> List[Dict[str, Any]]:
@@ -65,7 +91,7 @@ class Newsletter:
             endpoint = f"{self.url}/api/v1/archive?{query_string}"
 
             # Make the request
-            response = requests.get(endpoint, headers=HEADERS, timeout=30)
+            response = self._make_request(endpoint, timeout=30)
 
             if response.status_code != 200:
                 break
@@ -115,7 +141,7 @@ class Newsletter:
 
         params = {"sort": sorting}
         post_data = self._fetch_paginated_posts(params, limit)
-        return [Post(item["canonical_url"]) for item in post_data]
+        return [Post(item["canonical_url"], auth=self.auth) for item in post_data]
 
     def search_posts(self, query: str, limit: Optional[int] = None) -> List:
         """
@@ -137,7 +163,7 @@ class Newsletter:
 
         params = {"sort": "new", "search": query}
         post_data = self._fetch_paginated_posts(params, limit)
-        return [Post(item["canonical_url"]) for item in post_data]
+        return [Post(item["canonical_url"], auth=self.auth) for item in post_data]
 
     def get_podcasts(self, limit: Optional[int] = None) -> List:
         """
@@ -157,7 +183,7 @@ class Newsletter:
 
         params = {"sort": "new", "type": "podcast"}
         post_data = self._fetch_paginated_posts(params, limit)
-        return [Post(item["canonical_url"]) for item in post_data]
+        return [Post(item["canonical_url"], auth=self.auth) for item in post_data]
 
     def get_recommendations(self) -> List["Newsletter"]:
         """
@@ -177,7 +203,7 @@ class Newsletter:
 
         # Now get the recommendations
         endpoint = f"{self.url}/api/v1/recommendations/from/{publication_id}"
-        response = requests.get(endpoint, headers=HEADERS, timeout=30)
+        response = self._make_request(endpoint, timeout=30)
 
         if response.status_code != 200:
             return []
@@ -199,7 +225,9 @@ class Newsletter:
         # Avoid circular import
         from .newsletter import Newsletter
 
-        result = [Newsletter(url) for url in recommended_newsletter_urls]
+        result = [
+            Newsletter(url, auth=self.auth) for url in recommended_newsletter_urls
+        ]
 
         return result
 
@@ -214,11 +242,8 @@ class Newsletter:
         """
         from .user import User  # Import here to avoid circular import
 
-        r = requests.get(
-            f"{self.url}/api/v1/publication/users/ranked?public=true",
-            headers=HEADERS,
-            timeout=30,
-        )
+        endpoint = f"{self.url}/api/v1/publication/users/ranked?public=true"
+        r = self._make_request(endpoint, timeout=30)
         r.raise_for_status()
         authors = r.json()
         return [User(author["handle"]) for author in authors]