substack-api 1.1.2__tar.gz → 1.1.4.dev0__tar.gz

substack_api-1.1.4.dev0/.github/workflows/docs.yml

@@ -0,0 +1,54 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+    branches:
+      - master
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.12'
+
+      - name: Install uv
+        run: |
+          curl -LsSf https://astral.sh/uv/install.sh | sh
+          echo "$HOME/.cargo/bin" >> $GITHUB_PATH
+
+      - name: Setup uv cache
+        uses: actions/cache@v3
+        with:
+          path: ~/.cache/uv
+          key: ${{ runner.os }}-uv-${{ hashFiles('pyproject.toml') }}
+          restore-keys: |
+            ${{ runner.os }}-uv-
+
+      - name: Install dependencies
+        run: |
+          uv sync
+
+      - name: Configure Git user
+        run: |
+          git config --global user.name "github-actions[bot]"
+          git config --global user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+      - name: Deploy documentation
+        if: github.event_name == 'push' && github.ref == 'refs/heads/master'
+        run: |
+          uv run mkdocs gh-deploy --force
+
+      - name: Build documentation (PR)
+        if: github.event_name == 'pull_request'
+        run: uv run mkdocs build

substack_api-1.1.4.dev0/.github/workflows/pull_request.yml

@@ -0,0 +1,42 @@
+name: Pull Request
+
+on:
+  pull_request:
+    branches: [ master ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    
+    steps:
+    - uses: actions/checkout@v3
+    
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: '3.12'
+    
+    - name: Install uv
+      run: |
+        curl -LsSf https://astral.sh/uv/install.sh | sh
+        echo "$HOME/.cargo/bin" >> $GITHUB_PATH
+    
+    - name: Setup uv cache
+      uses: actions/cache@v3
+      with:
+        path: ~/.cache/uv
+        key: ${{ runner.os }}-uv-${{ hashFiles('pyproject.toml') }}
+        restore-keys: |
+          ${{ runner.os }}-uv-
+    
+    - name: Install dependencies
+      run: |
+        uv sync
+    
+    - name: Lint with ruff
+      run: |
+        uv run ruff check .
+    
+    - name: Test with pytest
+      run: |
+        uv run pytest

substack_api-1.1.4.dev0/.github/workflows/release.yml

@@ -0,0 +1,42 @@
+name: Python package
+on:
+  push:
+    tags:
+      - "v*.*.*"
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v3
+      
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.12'
+      
+      - name: Install uv
+        run: |
+          curl -LsSf https://astral.sh/uv/install.sh | sh
+          echo "$HOME/.cargo/bin" >> $GITHUB_PATH
+      
+      - name: Setup uv cache
+        uses: actions/cache@v3
+        with:
+          path: ~/.cache/uv
+          key: ${{ runner.os }}-uv-${{ hashFiles('pyproject.toml') }}
+          restore-keys: |
+            ${{ runner.os }}-uv-
+      
+      - name: Install dependencies
+        run: |
+          uv sync
+          uv pip install build twine
+      
+      - name: Build and publish
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_API_KEY }}
+        run: |
+          uv run python -m build
+          uv run twine upload dist/*

substack_api-1.1.4.dev0/.gitignore

@@ -0,0 +1,9 @@
+.conda/
+__pycache__/
+dist/
+.env
+.vscode/
+.DS_Store
+*.json
+substack_api.egg-info/
+.coverage

substack_api-1.1.4.dev0/.python-version

@@ -0,0 +1 @@
+3.12

{substack_api-1.1.2/substack_api.egg-info → substack_api-1.1.4.dev0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: substack-api
-Version: 1.1.2
+Version: 1.1.4.dev0
 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

substack_api-1.1.4.dev0/docs/api-reference/auth.md

@@ -0,0 +1,163 @@
+# SubstackAuth
+
+The `SubstackAuth` class handles authentication for accessing paywalled Substack content.
+
+## Class Definition
+
+```python
+SubstackAuth(cookies_path: str)
+```
+
+### Parameters
+
+- `cookies_path` (str): Path to the JSON file containing session cookies
+
+## Properties
+
+### `authenticated` (bool)
+Whether the authentication was successful and cookies were loaded.
+
+### `cookies_path` (str)
+Path to the cookies file.
+
+### `session` (requests.Session)
+The authenticated requests session object.
+
+## Methods
+
+### `load_cookies() -> bool`
+
+Load cookies from the specified file.
+
+#### Returns
+
+- `bool`: True if cookies were loaded successfully, False otherwise
+
+### `get(url: str, **kwargs) -> requests.Response`
+
+Make an authenticated GET request.
+
+#### Parameters
+
+- `url` (str): The URL to request
+- `**kwargs`: Additional arguments passed to requests.get
+
+#### Returns
+
+- `requests.Response`: The response object
+
+### `post(url: str, **kwargs) -> requests.Response`
+
+Make an authenticated POST request.
+
+#### Parameters
+
+- `url` (str): The URL to request
+- `**kwargs`: Additional arguments passed to requests.post
+
+#### Returns
+
+- `requests.Response`: The response object
+
+## Example Usage
+
+### Basic Authentication Setup
+
+```python
+from substack_api import SubstackAuth
+
+# Initialize with cookies file
+auth = SubstackAuth(cookies_path="my_cookies.json")
+
+# Check if authentication succeeded
+if auth.authenticated:
+    print("Successfully authenticated!")
+else:
+    print("Authentication failed")
+```
+
+### Using with Newsletter and Post Classes
+
+```python
+from substack_api import Newsletter, Post, SubstackAuth
+
+# Set up authentication
+auth = SubstackAuth(cookies_path="cookies.json")
+
+# Use with Newsletter
+newsletter = Newsletter("https://example.substack.com", auth=auth)
+posts = newsletter.get_posts(limit=5)
+
+# Use with Post
+post = Post("https://example.substack.com/p/paywalled-post", auth=auth)
+content = post.get_content()
+```
+
+### Manual Authenticated Requests
+
+```python
+from substack_api import SubstackAuth
+
+auth = SubstackAuth(cookies_path="cookies.json")
+
+# Make authenticated GET request
+response = auth.get("https://example.substack.com/api/v1/posts/123")
+data = response.json()
+
+# Make authenticated POST request
+response = auth.post(
+    "https://example.substack.com/api/v1/some-endpoint",
+    json={"key": "value"}
+)
+```
+
+## Cookie File Format
+
+The cookies file 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
+  },
+  ...
+]
+```
+
+## Error Handling
+
+The `SubstackAuth` class handles several error conditions:
+
+- **File not found**: If the cookies file doesn't exist, `authenticated` will be `False`
+- **Invalid JSON**: If the cookies file contains invalid JSON, `load_cookies()` returns `False`
+- **Missing cookies**: If required cookies are missing, authentication may fail silently
+
+```python
+from substack_api import SubstackAuth
+
+try:
+    auth = SubstackAuth(cookies_path="cookies.json")
+    if not auth.authenticated:
+        print("Authentication failed - check your cookies file")
+except Exception as e:
+    print(f"Error setting up authentication: {e}")
+```
+
+## Security Notes
+
+- Keep your cookies file secure and private
+- Don't commit cookies files to version control
+- Only use your own session cookies
+- Cookies may expire and need to be refreshed periodically
+- Respect Substack's Terms of Service when using authentication

substack_api-1.1.4.dev0/docs/api-reference/category.md

@@ -0,0 +1,118 @@
+# Category
+
+The `Category` class provides access to Substack newsletter categories.
+
+## Module Functions
+
+### `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)
+
+## Class Definition
+
+```python
+Category(name: Optional[str] = None, id: Optional[int] = None)
+```
+
+### 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
+
+## Methods
+
+### `_get_id_from_name() -> None`
+
+Lookup category ID based on name.
+
+#### Raises
+
+- `ValueError`: If the category name is not found
+
+### `_get_name_from_id() -> None`
+
+Lookup category name based on ID.
+
+#### Raises
+
+- `ValueError`: If the category ID is not found
+
+### `_fetch_newsletters_data(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
+
+### `get_newsletter_urls() -> List[str]`
+
+Get only the URLs of newsletters in this category.
+
+#### Returns
+
+- `List[str]`: List of newsletter URLs
+
+### `get_newsletters() -> List[Newsletter]`
+
+Get Newsletter objects for all newsletters in this category.
+
+#### Returns
+
+- `List[Newsletter]`: List of Newsletter objects
+
+### `get_newsletter_metadata() -> List[Dict[str, Any]]`
+
+Get full metadata for all newsletters in this category.
+
+#### Returns
+
+- `List[Dict[str, Any]]`: List of newsletter metadata dictionaries
+
+### `refresh_data() -> None`
+
+Force refresh of the newsletter data cache.
+
+## Example Usage
+
+```python
+from substack_api import Category
+from substack_api.category import list_all_categories
+
+# List all available categories
+categories = list_all_categories()
+print("Available categories:")
+for name, id in categories:
+    print(f"- {name} (ID: {id})")
+
+# Create a category object by name
+tech_category = Category(name="Technology")
+print(f"Selected category: {tech_category}")
+
+# Get newsletters in this category
+newsletters = tech_category.get_newsletters()
+print(f"Found {len(newsletters)} newsletters in {tech_category.name} category")
+
+# Print the first 5 newsletters
+for i, newsletter in enumerate(newsletters[:5]):
+    print(f"{i+1}. {newsletter.url}")
+
+# Get detailed metadata
+metadata = tech_category.get_newsletter_metadata()
+for entry in metadata[:3]:
+    print(f"Newsletter ID: {entry['id']}")
+    print(f"Description: {entry.get('description', 'No description')[:100]}...")
+    print("-" * 40)
+```

substack_api-1.1.4.dev0/docs/api-reference/index.md

@@ -0,0 +1,37 @@
+# API Reference
+
+This section provides detailed documentation for all modules and classes in the Substack API library.
+
+## Modules
+
+- [User](user.md): Access to Substack user profiles and subscriptions
+- [Newsletter](newsletter.md): Access to Substack publications, posts, and podcasts
+- [Post](post.md): Access to individual Substack post content and metadata
+- [Category](category.md): Discovery of newsletters by category
+- [SubstackAuth](auth.md): Authentication for accessing paywalled content
+
+Each module documentation includes:
+
+- Class properties and methods
+- Method parameters
+- Return types
+- Example usage
+
+## Common Patterns
+
+Most classes in the library follow these patterns:
+
+1. **Initialization**: Create an object by providing an identifier (URL, username, etc.)
+2. **Data Retrieval**: Methods that fetch data from the Substack API
+3. **Caching**: Data is cached to avoid unnecessary API requests
+4. **Force Refresh**: Most methods accept a `force_refresh` parameter to bypass the cache
+
+## Error Handling
+
+The library uses standard Python exceptions:
+
+- `requests.exceptions.HTTPError`: Raised when an HTTP request fails
+- `ValueError`: Raised when invalid parameters are provided
+- `KeyError`: Raised when expected data is not found in the API response
+
+You should wrap API calls in try/except blocks to handle these exceptions gracefully.

substack_api-1.1.4.dev0/docs/api-reference/newsletter.md

@@ -0,0 +1,130 @@
+# Newsletter
+
+The `Newsletter` class provides access to Substack publications.
+
+## Class Definition
+
+```python
+Newsletter(url: str, auth: Optional[SubstackAuth] = None)
+```
+
+### Parameters
+
+- `url` (str): The URL of the Substack newsletter
+- `auth` (Optional[SubstackAuth]): Authentication handler for accessing paywalled content
+
+## Methods
+
+### `_fetch_paginated_posts(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
+
+### `get_posts(sorting: str = "new", limit: Optional[int] = None) -> List[Post]`
+
+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
+
+### `search_posts(query: str, limit: Optional[int] = None) -> List[Post]`
+
+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
+
+### `get_podcasts(limit: Optional[int] = None) -> List[Post]`
+
+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
+
+### `get_recommendations() -> List[Newsletter]`
+
+Get recommended publications for this newsletter.
+
+#### Returns
+
+- `List[Newsletter]`: List of recommended Newsletter objects
+
+### `get_authors() -> List[User]`
+
+Get authors of the newsletter.
+
+#### Returns
+
+- `List[User]`: List of User objects representing the authors
+
+## Example Usage
+
+```python
+from substack_api import Newsletter, SubstackAuth
+
+# Create a newsletter object
+newsletter = Newsletter("https://example.substack.com")
+
+# Get recent posts
+recent_posts = newsletter.get_posts(limit=5)
+for post in recent_posts:
+    metadata = post.get_metadata()
+    print(f"Post: {metadata['title']}")
+
+# Search for posts on a specific topic
+search_results = newsletter.search_posts("machine learning", limit=3)
+for post in search_results:
+    metadata = post.get_metadata()
+    print(f"Found: {metadata['title']}")
+
+# Get podcast episodes
+podcasts = newsletter.get_podcasts(limit=2)
+for podcast in podcasts:
+    metadata = podcast.get_metadata()
+    print(f"Podcast: {metadata['title']}")
+
+# Get newsletter authors
+authors = newsletter.get_authors()
+for author in authors:
+    print(f"Author: {author.name}")
+
+# Get recommended newsletters
+recommendations = newsletter.get_recommendations()
+for rec in recommendations:
+    print(f"Recommended: {rec.url}")
+
+# Use with authentication for paywalled content
+auth = SubstackAuth(cookies_path="cookies.json")
+authenticated_newsletter = Newsletter("https://example.substack.com", auth=auth)
+paywalled_posts = authenticated_newsletter.get_posts(limit=5)
+for post in paywalled_posts:
+    if post.is_paywalled():
+        content = post.get_content()  # Now accessible with auth
+        print(f"Paywalled content: {content[:100]}...")
+```

substack_api-1.1.4.dev0/docs/api-reference/post.md

@@ -0,0 +1,93 @@
+# Post
+
+The `Post` class provides access to individual Substack posts.
+
+## Class Definition
+
+```python
+Post(url: str, auth: Optional[SubstackAuth] = None)
+```
+
+### Parameters
+
+- `url` (str): The URL of the Substack post
+- `auth` (Optional[SubstackAuth]): Authentication handler for accessing paywalled content
+
+## Methods
+
+### `_fetch_post_data(force_refresh: bool = False) -> Dict[str, Any]`
+
+Fetch the raw post data from the API and cache it.
+
+#### Parameters
+
+- `force_refresh` (bool): Whether to force a refresh of the data, ignoring the cache
+
+#### Returns
+
+- `Dict[str, Any]`: Full post metadata
+
+### `get_metadata(force_refresh: bool = False) -> Dict[str, Any]`
+
+Get metadata for the post.
+
+#### Parameters
+
+- `force_refresh` (bool): Whether to force a refresh of the data, ignoring the cache
+
+#### Returns
+
+- `Dict[str, Any]`: Full post metadata
+
+### `get_content(force_refresh: bool = False) -> Optional[str]`
+
+Get the HTML content of the post.
+
+#### Parameters
+
+- `force_refresh` (bool): Whether to force a refresh of the data, ignoring the cache
+
+#### Returns
+
+- `Optional[str]`: HTML content of the post, or None if not available (e.g., for paywalled content without authentication)
+
+### `is_paywalled() -> bool`
+
+Check if the post is paywalled.
+
+#### Returns
+
+- `bool`: True if the post requires a subscription to access full content
+
+## Example Usage
+
+```python
+from substack_api import Post, SubstackAuth
+
+# Create a post object
+post = Post("https://example.substack.com/p/post-slug")
+
+# Get post metadata
+metadata = post.get_metadata()
+print(f"Title: {metadata['title']}")
+print(f"Published: {metadata['post_date']}")
+
+# Check if the post is paywalled
+if post.is_paywalled():
+    print("This post is paywalled")
+    
+    # Set up authentication to access paywalled content
+    auth = SubstackAuth(cookies_path="cookies.json")
+    authenticated_post = Post("https://example.substack.com/p/post-slug", auth=auth)
+    content = authenticated_post.get_content()
+else:
+    # Public content - no authentication needed
+    content = post.get_content()
+
+print(f"Content length: {len(content) if content else 0}")
+
+# Alternative: Create post with authentication from the start
+auth = SubstackAuth(cookies_path="cookies.json")
+authenticated_post = Post("https://example.substack.com/p/paywalled-post", auth=auth)
+content = authenticated_post.get_content()  # Works for both public and paywalled content
+```