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

substack_api-1.0.2/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.2
+Name: substack-api
+Version: 1.0.2
+Summary: Unofficial wrapper for the Substack API
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.32.3
+
+# 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
+
+## 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()
+```
+
+### 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()
+```
+
+## Limitations
+
+- This is an unofficial library and not endorsed by Substack
+- APIs may change without notice, potentially breaking functionality
+- Some features may only work for public content
+- Rate limiting may be enforced by Substack
+
+## 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/README.md

@@ -0,0 +1,122 @@
+# 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
+
+## 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()
+```
+
+### 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()
+```
+
+## Limitations
+
+- This is an unofficial library and not endorsed by Substack
+- APIs may change without notice, potentially breaking functionality
+- Some features may only work for public content
+- Rate limiting may be enforced by Substack
+
+## 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/pyproject.toml

@@ -0,0 +1,20 @@
+[project]
+name = "substack-api"
+version = "1.0.2"
+description = "Unofficial wrapper for the Substack API"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "requests>=2.32.3",
+]
+
+[dependency-groups]
+dev = [
+    "ipykernel>=6.29.5",
+    "mike>=2.1.3",
+    "mkdocs>=1.6.1",
+    "mkdocs-material>=9.6.6",
+    "mkdocstrings-python>=1.16.2",
+    "pytest>=8.3.4",
+    "ruff>=0.9.9",
+]

substack_api-1.0.2/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

substack_api-1.0.2/substack_api/__init__.py

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

substack_api-1.0.2/substack_api/category.py

@@ -0,0 +1,180 @@
+from typing import Any, Dict, List, Optional, Tuple
+
+import requests
+
+# Add Newsletter import
+from .newsletter import Newsletter
+
+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"
+}
+
+
+def list_all_categories() -> List[Tuple[str, int]]:
+    """
+    Get name / id representations of all newsletter categories
+
+    Returns
+    -------
+    List[Tuple[str, int]]
+        List of tuples containing (category_name, category_id)
+    """
+    endpoint_cat = "https://substack.com/api/v1/categories"
+    r = requests.get(endpoint_cat, headers=HEADERS, timeout=30)
+    r.raise_for_status()
+    categories = [(i["name"], i["id"]) for i in r.json()]
+    return categories
+
+
+class Category:
+    """
+    Top-level newsletter category
+    """
+
+    def __init__(self, name: Optional[str] = None, id: Optional[int] = None) -> None:
+        """
+        Initialize a Category object.
+
+        Parameters
+        ----------
+        name : Optional[str]
+            The name of the category
+        id : Optional[int]
+            The ID of the category
+
+        Raises
+        ------
+        ValueError
+            If neither name nor id is provided, or if the provided name/id is not found
+        """
+        if name is None and id is None:
+            raise ValueError("Either name or id must be provided")
+
+        self.name = name
+        self.id = id
+        self._newsletters_data = None  # Cache for newsletter data
+
+        # Retrieve missing attributes if only one of name or id is provided
+        if self.name and self.id is None:
+            self._get_id_from_name()
+        elif self.id and self.name is None:
+            self._get_name_from_id()
+
+    def __str__(self) -> str:
+        return f"{self.name} ({self.id})"
+
+    def __repr__(self) -> str:
+        return f"Category(name={self.name}, id={self.id})"
+
+    def _get_id_from_name(self) -> None:
+        """
+        Lookup category ID based on name
+
+        Raises
+        ------
+        ValueError
+            If the category name is not found
+        """
+        categories = list_all_categories()
+        for name, id in categories:
+            if name == self.name:
+                self.id = id
+                return
+        raise ValueError(f"Category name '{self.name}' not found")
+
+    def _get_name_from_id(self) -> None:
+        """
+        Lookup category name based on ID
+
+        Raises
+        ------
+        ValueError
+            If the category ID is not found
+        """
+        categories = list_all_categories()
+        for name, id in categories:
+            if id == self.id:
+                self.name = name
+                return
+        raise ValueError(f"Category ID {self.id} not found")
+
+    def _fetch_newsletters_data(
+        self, force_refresh: bool = False
+    ) -> List[Dict[str, Any]]:
+        """
+        Fetch the raw newsletter data from the API and cache it
+
+        Parameters
+        ----------
+        force_refresh : bool
+            Whether to force a refresh of the data, ignoring the cache
+
+        Returns
+        -------
+        List[Dict[str, Any]]
+            Full newsletter metadata
+        """
+        if self._newsletters_data is not None and not force_refresh:
+            return self._newsletters_data
+
+        endpoint = f"https://substack.com/api/v1/category/public/{self.id}/all?page="
+
+        all_newsletters = []
+        page_num = 0
+        more = True
+        # endpoint doesn't return more than 21 pages
+        while more and page_num <= 20:
+            full_url = endpoint + str(page_num)
+            r = requests.get(full_url, headers=HEADERS, timeout=30)
+            r.raise_for_status()
+
+            resp = r.json()
+            newsletters = resp["publications"]
+            all_newsletters.extend(newsletters)
+            page_num += 1
+            more = resp["more"]
+
+        self._newsletters_data = all_newsletters
+        return all_newsletters
+
+    def get_newsletter_urls(self) -> List[str]:
+        """
+        Get only the URLs of newsletters in this category
+
+        Returns
+        -------
+        List[str]
+            List of newsletter URLs
+        """
+        data = self._fetch_newsletters_data()
+
+        return [item["base_url"] for item in data]
+
+    def get_newsletters(self) -> List[Newsletter]:
+        """
+        Get Newsletter objects for all newsletters in this category
+
+        Returns
+        -------
+        List[Newsletter]
+            List of Newsletter objects
+        """
+        urls = self.get_newsletter_urls()
+        return [Newsletter(url) for url in urls]
+
+    def get_newsletter_metadata(self) -> List[Dict[str, Any]]:
+        """
+        Get full metadata for all newsletters in this category
+
+        Returns
+        -------
+        List[Dict[str, Any]]
+            List of newsletter metadata dictionaries
+        """
+        return self._fetch_newsletters_data()
+
+    def refresh_data(self) -> None:
+        """
+        Force refresh of the newsletter data cache
+        """
+        self._fetch_newsletters_data(force_refresh=True)

substack_api-1.0.2/substack_api/newsletter.py

@@ -0,0 +1,224 @@
+from time import sleep
+from typing import Any, Dict, List, Optional
+
+import requests
+
+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"
+}
+
+
+class Newsletter:
+    """
+    Newsletter class for interacting with Substack newsletters
+    """
+
+    def __init__(self, url: str) -> None:
+        """
+        Initialize a Newsletter object.
+
+        Parameters
+        ----------
+        url : str
+            The URL of the Substack newsletter
+        """
+        self.url = url
+
+    def __str__(self) -> str:
+        return f"Newsletter: {self.url}"
+
+    def __repr__(self) -> str:
+        return f"Newsletter(url={self.url})"
+
+    def _fetch_paginated_posts(
+        self, params: Dict[str, str], limit: Optional[int] = None, page_size: int = 15
+    ) -> List[Dict[str, Any]]:
+        """
+        Helper method to fetch paginated posts with different query parameters
+
+        Parameters
+        ----------
+        params : Dict[str, str]
+            Dictionary of query parameters to include in the API request
+        limit : Optional[int]
+            Maximum number of posts to return
+        page_size : int
+            Number of posts to retrieve per page request
+
+        Returns
+        -------
+        List[Dict[str, Any]]
+            List of post data dictionaries
+        """
+        results = []
+        offset = 0
+        batch_size = page_size  # The API default limit per request
+        more_items = True
+
+        while more_items:
+            # Update params with current offset and batch size
+            current_params = params.copy()
+            current_params.update({"offset": str(offset), "limit": str(batch_size)})
+
+            # Format query parameters
+            query_string = "&".join([f"{k}={v}" for k, v in current_params.items()])
+            endpoint = f"{self.url}/api/v1/archive?{query_string}"
+
+            # Make the request
+            response = requests.get(endpoint, headers=HEADERS, timeout=30)
+
+            if response.status_code != 200:
+                break
+
+            items = response.json()
+            if not items:
+                break
+
+            results.extend(items)
+
+            # Update offset for next batch
+            offset += batch_size
+
+            # Check if we've reached the requested limit
+            if limit and len(results) >= limit:
+                results = results[:limit]
+                more_items = False
+
+            # Check if we got fewer items than requested (last page)
+            if len(items) < batch_size:
+                more_items = False
+
+            # Be nice to the API
+            sleep(0.5)
+
+        # Instead of creating Post objects directly, return the URLs
+        # The caller will create Post objects as needed
+        return results
+
+    def get_posts(self, sorting: str = "new", limit: Optional[int] = None) -> List:
+        """
+        Get posts from the newsletter with specified sorting
+
+        Parameters
+        ----------
+        sorting : str
+            Sorting order for the posts ("new", "top", "pinned", or "community")
+        limit : Optional[int]
+            Maximum number of posts to return
+
+        Returns
+        -------
+        List[Post]
+            List of Post objects
+        """
+        from .post import Post  # Import here to avoid circular import
+
+        params = {"sort": sorting}
+        post_data = self._fetch_paginated_posts(params, limit)
+        return [Post(item["canonical_url"]) for item in post_data]
+
+    def search_posts(self, query: str, limit: Optional[int] = None) -> List:
+        """
+        Search posts in the newsletter with the given query
+
+        Parameters
+        ----------
+        query : str
+            Search query string
+        limit : Optional[int]
+            Maximum number of posts to return
+
+        Returns
+        -------
+        List[Post]
+            List of Post objects matching the search query
+        """
+        from .post import Post  # Import here to avoid circular import
+
+        params = {"sort": "new", "search": query}
+        post_data = self._fetch_paginated_posts(params, limit)
+        return [Post(item["canonical_url"]) for item in post_data]
+
+    def get_podcasts(self, limit: Optional[int] = None) -> List:
+        """
+        Get podcast posts from the newsletter
+
+        Parameters
+        ----------
+        limit : Optional[int]
+            Maximum number of podcast posts to return
+
+        Returns
+        -------
+        List[Post]
+            List of Post objects representing podcast posts
+        """
+        from .post import Post  # Import here to avoid circular import
+
+        params = {"sort": "new", "type": "podcast"}
+        post_data = self._fetch_paginated_posts(params, limit)
+        return [Post(item["canonical_url"]) for item in post_data]
+
+    def get_recommendations(self) -> List["Newsletter"]:
+        """
+        Get recommended publications for this newsletter
+
+        Returns
+        -------
+        List[Newsletter]
+            List of recommended Newsletter objects
+        """
+        # First get any post to extract the publication ID
+        posts = self.get_posts(limit=1)
+        if not posts:
+            return []
+
+        publication_id = posts[0].get_metadata()["publication_id"]
+
+        # Now get the recommendations
+        endpoint = f"{self.url}/api/v1/recommendations/from/{publication_id}"
+        response = requests.get(endpoint, headers=HEADERS, timeout=30)
+
+        if response.status_code != 200:
+            return []
+
+        recommendations = response.json()
+        if not recommendations:
+            return []
+
+        recommended_newsletter_urls = []
+        for rec in recommendations:
+            recpub = rec["recommendedPublication"]
+            if "custom_domain" in recpub and recpub["custom_domain"]:
+                recommended_newsletter_urls.append(recpub["custom_domain"])
+            else:
+                recommended_newsletter_urls.append(
+                    f"{recpub['subdomain']}.substack.com"
+                )
+
+        # Avoid circular import
+        from .newsletter import Newsletter
+
+        result = [Newsletter(url) for url in recommended_newsletter_urls]
+
+        return result
+
+    def get_authors(self) -> List:
+        """
+        Get authors of the newsletter
+
+        Returns
+        -------
+        List[User]
+            List of User objects representing the authors
+        """
+        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,
+        )
+        r.raise_for_status()
+        authors = r.json()
+        return [User(author["handle"]) for author in authors]