Metadata-Version: 2.1
Name: mastodon.bookmarkmedia
Version: 0.8.0
Summary: Download and archive media attachments from your Mastodon bookmarks.
Home-page: https://gitlab.com/pbielefeldt/mastodon.bookmarkmedia
Author: P. Bielefeldt
License: MPL-2.0
Description: # 📚 Mastodon Bookmark Media Downloader
        
        A lightweight Python script that downloads image and video media from your **bookmarked Mastodon posts**, optionally filtering by post age.
        Useful for archiving media before it's deleted or expires on remote instances.
        
        
        ## ✨ Features
        
        * Downloads all images and videos from bookmarked posts
        * Supports **image-only**, **video-only**, or **all media**
        * Saves media with clean, traceable filenames
        * Skips media that’s already downloaded
        
        
        ## 🛠️ Installation Instructions
        
        ### 1. Install Python 3.6+
        
        Check your version:
        
        ```bash
        python3 --version
        ```
        
        If it's missing or outdated:
        
        * **Debian/Ubuntu:**
          ```bash
          sudo apt update
          sudo apt install python3 python3-pip
          ```
        * **openSUSE:**
          ```bash
          sudo zypper install python3 python3-pip
          ```
        
        ### 2. Install Pyhton dependencies
        
        You can install all required dependencies using requirements.txt:
        
        ```bash
        pip3 install -r requirements.txt
        ```
        Alternatively, install them manually:
        
        ```bash
        pip3 install Mastodon.py python-dotenv magic requests
        ```
        
        ---
        
        ## ⚙️ Configuration
        
        ### Create a `.env` file with your access credentials
        
        ```bash
        cp .env.example .env
        ```
        
        Edit `.env` and fill in:
        
        ```env
        MASTODON_TOKEN=your_access_token_here
        MASTODON_INSTANCE=https://your.instance
        MAX_BOOKMARKS=40
        ```
        
        ---
        
        ## 🚀 Usage
        
        You can run the script with default config from `.env`:
        
        ```bash
        python3 bookmark_media_downloader.py
        ```
        
        Or override options directly from the command line:
        
        ```bash
        python3 bookmark_media_downloader.py \
          --token YOUR_ACCESS_TOKEN \
          --instance https://your.instance \
          --max-bookmarks 200 \
          --media image \
          --outdir saved_media
        ```
        
        ### 🔧 Options
        
        | Option            | Description                                     | Required               | Default     |
        | ----------------- | ----------------------------------------------- | ---------------------- | ----------- |
        | `--token`         | Mastodon access token                           | Yes (unless in `.env`) | —           |
        | `--instance`      | Mastodon instance base URL (e.g. `https://...`) | Yes (unless in `.env`) | —           |
        | `--max-bookmarks` | Only include this number of newest bookmarks    | No                     | `80`        |
        | `--media`         | Filter media type: `image`, `video`, `all`      | No                     | `all`       |
        | `--outdir`        | Directory to save downloaded media              | No                     | `downloads` |
        
        
        ### 📦 Output
        
        Downloaded media will be saved in the `downloads/` directory (or the folder you set via `--outdir`). Filenames follow this pattern:
        
        ```
        username_instance_postid[-N].ext
        ```
        
        For example:
        
        ```
        johndoe_mastodon-social_1094823048123.jpg
        johndoe_mastodon-social_1094823048123-2.png
        ```
        
        If a post includes multiple media files, suffixes like `-2`, `-3`, etc. will be appended.
        
        
        ## 🛡 Permissions
        
        Your **Mastodon access token** must include the following scopes:
        
        * `read`
        * `read:bookmarks`
        
        To generate or manage tokens, go to:
        
        ```
        https://your.instance/settings/applications
        ```
        
        Make sure your app has `read:bookmarks` checked.
        
        
        ## 📝 License
        
        This project is licensed under the **Mozilla Public License 2.0+ (MPL-2.0)**.
        You are free to use, modify, and redistribute the code under the terms of this license.
        
        ---
        
        ## 🙋 FAQ
        
        **Q:** What happens if I bookmark an old post today?
        **A:** The script filters by the **post creation date**, not the bookmark date.
        
        **Q:** What if I run the script multiple times?
        **A:** Already-downloaded media is skipped automatically.
        
        **Q:** Will this download media from *private* posts?
        **A:** If you have permission to view and bookmark the post, it should work.
        
        ---
        
        Feel free to fork or contribute to improve the script!
        
        
Platform: UNKNOWN
Requires-Python: >=3.8
Description-Content-Type: text/markdown
