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

{substack_api-0.0.2 → substack_api-1.0.2}/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2023 Nick Hagar
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+MIT License
+
+Copyright (c) 2023 Nick Hagar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.

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)