tumblockr

Ever had one of those moments where you saw a post so abhorrent you went through the list of likes to manually block every single blog? This project provides an automated Tumblr post liker-blocking tool that periodically fetches blogs that have liked specified posts and queues them up for blocking through the Tumblr API. No more messy, manual one-by-one bullshit!

Quick Start

Choose your operating system for step-by-step instructions:

🪟 Windows

Step 1: Download

1. Go to the releases page
2. Download tumblockr-windows.exe
3. Save it somewhere easy to find (e.g., C:\Users\YourName\tumblockr\)

Step 2: Register a Tumblr App

1. Open https://www.tumblr.com/oauth/apps in your browser
2. Click "Register application"
3. Fill in:
   • Application name: Tumblockr
   • Application description: Personal blocking tool
   • Default callback URL: http://localhost:5000/callback
   • OAuth2 redirect URLs: http://localhost:5000/callback
4. Click Save and copy your OAuth Consumer Key and Secret

Step 3: Open Command Prompt

1. Press Win + R, type cmd, press Enter
2. Navigate to where you saved the file:

   cd C:\Users\YourName\tumblockr
   

Step 4: Run Setup

tumblockr-windows.exe setup

Follow the prompts to enter your OAuth credentials and blog name.

Step 5: Start Blocking

tumblockr-windows.exe init
tumblockr-windows.exe start

The tool will now run continuously. Press Ctrl+C to stop.

🍎 macOS

Tumblockr does not currently ship a pre-built macOS executable.

Step 1: Get the Source Code

1. Install Python 3.10+ (or use the system Python if appropriate)
2. Clone the repository:

   git clone https://maker.doll.gl/lavinia7/tumblockr.git
   cd tumblockr
   

Step 2: Register a Tumblr App

1. Open https://www.tumblr.com/oauth/apps in your browser
2. Click "Register application"
3. Fill in:
   • Application name: Tumblockr
   • Application description: Personal blocking tool
   • Default callback URL: http://localhost:5000/callback
   • OAuth2 redirect URLs: http://localhost:5000/callback
4. Click Save and copy your OAuth Consumer Key and Secret

Step 3: Install Dependencies

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Step 4: Run Setup

python3 tumblockr.py setup

Follow the prompts to enter your OAuth credentials and blog name.

Step 5: Start Blocking

python3 tumblockr.py init
python3 tumblockr.py start

The tool will now run continuously. Press Ctrl+C to stop.

🐧 Linux

Step 1: Download

1. Go to the releases page
2. Download tumblockr-linux
3. Open a terminal and make it executable:

   chmod +x ~/Downloads/tumblockr-linux
   

Step 2: Register a Tumblr App

1. Open https://www.tumblr.com/oauth/apps in your browser
2. Click "Register application"
3. Fill in:
   • Application name: Tumblockr
   • Application description: Personal blocking tool
   • Default callback URL: http://localhost:5000/callback
   • OAuth2 redirect URLs: http://localhost:5000/callback
4. Click Save and copy your OAuth Consumer Key and Secret

Step 3: Run Setup

cd ~/Downloads
./tumblockr-linux setup

Follow the prompts to enter your OAuth credentials and blog name.

Step 4: Start Blocking

./tumblockr-linux init
./tumblockr-linux start

The tool will now run continuously. Press Ctrl+C to stop.

---

Features

• 🚫 Auto-blocking: Automatically block users who like specific posts
• 📋 Import blocks: Import existing block lists from other Tumblr blogs
• 📁 File import: Import usernames from text files
• 📤 Export blocks: Export your block lists for backup or sharing
• 🔄 Sync blocks: Sync your complete block list from Tumblr
• ⏰ Scheduled operation: Runs on configurable intervals
• 🔐 OAuth2 authentication: Secure authentication with Tumblr
• 💾 Persistent queue: SQLite database for reliable operation
• 🔧 Automatic migrations: Seamlessly upgrade from older versions
• 🖥️ Cross-platform: Works on Windows, macOS, and Linux
• 📚 Multi-blog support: Manage multiple Tumblr blogs with separate block lists

System Requirements

• Windows: Windows 10 or later (Windows 7/8 may work but are not tested)
• macOS: macOS 10.12 (Sierra) or later
• Linux: Any modern distribution with glibc 2.17+
• Python: 3.8+ (for building from source)

Installation

Option 1: Download Pre-built Executable

Download the latest release for your platform from the releases page.

macOS users should run from source (see Quick Start above), as a macOS executable is not currently published.

Option 2: Build from Source

# Clone the repository
git clone https://maker.doll.gl/lavinia7/tumblockr.git
cd tumblockr

# Install dependencies
pip install -r requirements.txt

# For building executables, install dev dependencies
pip install -r requirements_dev.txt

# Run directly with Python
python tumblockr.py --help

# Or build standalone executable
./build.sh  # On Unix/macOS
build.bat   # On Windows

Detailed Setup

1. Register a Tumblr Application

1. Go to https://www.tumblr.com/oauth/apps
2. Click "Register application"
3. Fill in the form:
   • Application name: Tumblockr (or anything you want)
   • Application description: Personal blocking tool
   • Default callback URL: http://localhost:5000/callback
   • OAuth2 redirect URLs: Add this URL:
     • http://localhost:5000/callback
4. Save your OAuth Consumer Key and Secret

2. Setup

Run the interactive setup wizard:

tumblockr setup

By default, the OAuth Consumer Secret input is hidden. For troubleshooting paste/input issues, use:

tumblockr setup --show-secret-input

This will guide you through:

• Entering your OAuth credentials
• Selecting your blog
• Adding posts to monitor (optional)
• Setting fetch and block intervals

3. Initialize and Start

# Initialize database (first time only)
tumblockr init

# Start blocking service
tumblockr start

The service will run continuously, checking for new likes and processing the blocking queue at your configured intervals.

Usage

Import from Another Blog

Copy the entire block list from another blog you're an admin of:

tumblockr import blog source-blog.tumblr.com

Important: You must authenticate as the owner of the source blog to access its block list. The import process will:

1. Open a browser for you to log in as the source blog owner
2. Request permission to read the block list
3. Import all blocked users to your main blog's queue
4. The imported users will be blocked on your next scheduled run

Import from File

Bulk import usernames from a text file:

tumblockr import file usernames.txt

Supported formats:

• Plain usernames: exampleuser
• With domain: exampleuser.tumblr.com
• Full URLs: https://exampleuser.tumblr.com
• With @ prefix: @exampleuser
• CSV files (uses first column)

Export Block Lists

Export your blocked users to a file for backup or sharing:

# Export to default filename (auto-generated with timestamp)
tumblockr export file

# Export to specific file
tumblockr export file my_blocks.txt

# Export as CSV with metadata
tumblockr export file --format csv --include-metadata

# Export all users (blocked + queued)
tumblockr export file --include-queued

# Show statistics without exporting
tumblockr export file --stats-only

# Show detailed statistics
tumblockr export stats

Export Formats

1. Plain (default): Simple text file with one username per line

   username1
   username2
   username3
   

2. CSV: Structured format with optional metadata

   username,blocked_date,source
   spammer1,2024-01-15 10:30:00,blog|12345
   troll2,2024-01-16 14:22:00,imported from file.txt
   

3. Detailed: Plain text with inline comments

   username1 # blocked 2024-01-15 from blog|12345
   username2 # blocked 2024-01-16 from imported file
   

Export Options

• --format, -f: Choose export format (plain, csv, detailed)
• --include-metadata, -m: Include blocking date and source information
• --include-queued, -q: Export both blocked and queued users
• --stats-only, -s: Show statistics without creating a file

Large Exports

The export feature handles large datasets efficiently:

• Processes users in batches to manage memory
• Shows progress for exports over 5,000 users
• Warns before exporting over 10,000 users
• Provides file size estimates

Managing Posts

# Add a post to monitor
tumblockr add-post blogname|postid

# List monitored posts
tumblockr list-posts

# Remove a post
tumblockr remove-post blogname|postid

Sync Block List

Sync your complete block list from Tumblr to ensure your local database is up to date:

# Sync block list from Tumblr
tumblockr sync

# Force sync even if recently synced
tumblockr sync --force

Other Commands

# Initialize database
tumblockr init

# Start blocking for active blog
tumblockr start

# Start blocking for ALL blogs at once
tumblockr start-all

# Check status and statistics
tumblockr status

# Re-authenticate if needed
tumblockr auth

# Check and run database/config migrations
tumblockr migrate

# Check migration status without migrating
tumblockr migrate --check

# View application logs
tumblockr logs

# View help
tumblockr --help

# Check version
tumblockr --version

Multi-Blog Support

Manage multiple Tumblr blogs with separate block lists and credentials:

Adding and Managing Blogs

# Add a new blog
tumblockr blog add myblog

# Add blog with OAuth credentials (if different from main app)
tumblockr blog add myblog --client-id YOUR_ID --client-secret YOUR_SECRET

# List all registered blogs
tumblockr blog list

# Set a blog as active (used by default for all operations)
tumblockr blog set myblog

# Remove a blog (requires --force if it has blocks)
tumblockr blog remove myblog
tumblockr blog remove myblog --force

# View statistics for a specific blog
tumblockr blog stats myblog

Per-Blog Authentication

Authenticate specific blogs using the --blog flag:

# Authenticate a specific blog
tumblockr auth --blog myblog

# Re-authenticate the active blog
tumblockr auth

Each blog stores its own OAuth tokens, allowing you to manage blogs with different owners.

Per-Blog Operations

Use the --blog flag to target specific blogs:

# Sync blocks for a specific blog
tumblockr sync --blog myblog

# Check status for a specific blog
tumblockr status --blog myblog

# Export blocks from a specific blog
tumblockr export file --blog myblog

# Start blocking with a specific blog
tumblockr start --blog myblog

# Start blocking for ALL blogs at once
tumblockr start-all

If no --blog flag is provided, operations use the currently active blog.

Running All Blogs at Once

The start-all command processes all registered blogs that have valid authentication tokens:

tumblockr start-all

This will:

• Display all blogs that will be processed
• Run fetch and block tasks for each blog sequentially
• Continue on a schedule (same intervals as start)
• Handle rate limits per-blog independently

Example output:

🚀 Starting Tumblockr for ALL blogs (2 blogs)
Fetch interval: 60 minutes
Block interval: 15 minutes

Blogs to process:
  🟢 main-blog.tumblr.com (3 monitored posts)
  ⚪ side-blog.tumblr.com (1 monitored posts)

Press Ctrl+C to stop

How Multi-Blog Works

• Each blog has its own OAuth credentials and block list
• Block lists are tracked separately per blog (a user can be blocked by multiple blogs)
• Queue items are associated with specific blogs
• The active blog is used by default when no blog is specified
• Backups include all blogs and their block associations

Backup and Restore

Create portable backups of your configuration and data:

# Create a full backup (includes OAuth tokens)
tumblockr backup create my_backup.json

# Create a shareable backup (without tokens)
tumblockr backup create --no-tokens shareable_backup.json

# View backup contents without importing
tumblockr backup info my_backup.json

# Restore from backup (merges with existing data)
tumblockr backup restore my_backup.json

# Restore without importing tokens (will need to re-authenticate)
tumblockr backup restore my_backup.json --no-tokens

Backups are stored as plaintext JSON, making them portable across machines and useful for:

• Migrating to a new computer
• Restoring after reinstallation
• Sharing block lists (use --no-tokens to exclude credentials)

How It Works

1. Fetches - Periodically checks specified posts for new likes
2. Queues - Adds likers to a queue (skipping already blocked users)
3. Blocks - Processes the queue in batches using Tumblr's bulk block API
4. Respects rate limits - Automatically pauses when hitting API limits

Configuration

Configuration is stored in:

• Windows: %USERPROFILE%\.tumblockr\config.json
• macOS/Linux: ~/.tumblockr/config.json

Schedule Settings

• Fetch interval: How often to check for new likes (default: 60 minutes)
• Block interval: How often to process the queue (default: 15 minutes)

Troubleshooting

Upgrading from Older Versions

If you're upgrading from an older version, run the migration command:

# Check if migration is needed
tumblockr migrate --check

# Run migrations (creates automatic backups)
tumblockr migrate

# Skip backup creation (not recommended)
tumblockr migrate --no-backup

The migration system automatically:

• Detects your database and config versions
• Creates backups before making changes
• Updates schemas while preserving your data
• Adds new required fields with sensible defaults

Database Errors

If you see "no such table" errors:

1. The database may not have been initialized
2. Run tumblockr init to create the database
3. Check that the data directory is writable:
   • Windows: %USERPROFILE%\.tumblockr\
   • macOS/Linux: ~/.tumblockr/

Build Issues

If building fails with PyInstaller errors:

1. Ensure you're using Python 3.8 or later
2. Install build dependencies: pip install -r requirements_dev.txt
3. Try updating PyInstaller: pip install --upgrade "pyinstaller>=4.0,<6.0"
4. On older systems, you may need to use an older PyInstaller version

Authentication Issues

If authentication fails:

1. Ensure the callback URL is registered in your Tumblr app
2. Check that your OAuth credentials are correct
3. Try running tumblockr auth again

Import Issues

If importing from another blog fails:

1. Make sure you're logging in as the owner of the source blog
2. The source blog must have existing blocked users
3. Check the logs (~/.tumblockr/tumblockr.log) for specific errors

Building from Source

Requirements

• Python 3.8+
• pip

Build Commands

# Install build dependencies
pip install -r requirements_dev.txt

# Build executable
pyinstaller tumblockr.spec

# Or use the build scripts
./build.sh   # Unix/macOS
build.bat    # Windows

Example Workflow

# 1. Check current statistics
tumblockr export stats

# 2. Export everything for backup
tumblockr export file backup_2024.csv --format csv --include-metadata --include-queued

# 3. Export just usernames for sharing
tumblockr export file share_list.txt

# 4. Share with someone else who can import it
# On their system:
tumblockr import file share_list.txt