ShowSweep

ShowSweep is a Python utility to identify and manage unwatched TV shows in Plex, with integration for Overseerr, Tautulli, and Sonarr. It helps you keep your TV library clean by safely removing or archiving shows that are no longer needed.

---

🚀 Getting Started

1. Clone the Repo

git clone https://github.com/faultoverload/showsweep.git
cd showsweep

2. Set Up Your Environment

• Create a virtual environment (recommended):

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

• Or use Docker (see Docker section below)

3. Configure

• Copy config/example_config.ini to config/config.ini and edit it with your server URLs, API keys, and preferences.

4. Run ShowSweep

python main.py [options]

---

🛠️ Usage

• By default, ShowSweep runs in simulation mode (no files are deleted).
• Use --skip-confirmation and --action to automate actions.
• All options can be set in config.ini or overridden on the command line.

Example Commands

• Interactive mode:

  python main.py

• Non-interactive, delete all eligible shows:

  python main.py --skip-confirmation --action delete

• Force refresh all data:

  python main.py --force-refresh

• Enable debug logging:

  python main.py --debug

---

🐳 Docker Usage

Using Docker Compose (Recommended)

1. Create the configuration file:

   cp config/example_config.ini config/config.ini

2. Edit the configuration file:

   nano config/config.ini

3. Run with Docker Compose:

   docker-compose up -d

4. View logs:

   docker-compose logs -f

5. Run with custom arguments:

   docker-compose run --rm showsweep python main.py --debug --force-refresh

Using the Published Docker Image

You can run ShowSweep directly from Docker Hub without building locally:

docker run --rm -v $(pwd)/config:/config -v $(pwd)/logs:/logs \
  -e TZ=America/New_York \
  faultoverload/showsweep:latest

You can also pass command line arguments:

docker run --rm -v $(pwd)/config:/config -v $(pwd)/logs:/logs \
  -e TZ=America/New_York \
  faultoverload/showsweep:latest --skip-confirmation --action delete

Customizing the Docker Environment

You can modify the docker-compose.yml file to:

• Set environment variables instead of using config.ini
• Change the timezone
• Connect to an existing Docker network where your media services run
• Configure scheduling with cron (by using the Docker host's cron)

Using Docker Without Compose

docker build -t showsweep .
docker run -v $(pwd)/config:/config showsweep

---

✅ Feature Checklist

Core Purpose

• Identify and manage unwatched TV shows in Plex
• Clean up Plex library by identifying TV content that has been downloaded but never watched

Integration with Media Services

• Plex: Retrieve and manage TV show libraries
• Overseerr: Check if shows were requested before deletion
• Tautulli: Retrieve watch statistics
• Sonarr: Unmonitor or delete series as needed

Show Management Features

• Show discovery from Plex
• Identify unwatched shows (no watch or request history)
• Correlate show data across Plex, TVDB, TMDB
• Actions:
  • Delete: Remove unwatched shows from Plex
  • Keep first season: Delete all but the first season
  • Keep first episode: Delete all but the first episode
  • Keep: No action

User Interface

• Rich text console interface
• Interactive mode: Prompt for each show
• Non-interactive mode: Apply default action

Data Management

• Local SQLite database for caching and tracking
• Store TV show list, watch stats, request data, and ID mappings
• Record processing history and actions

Cache Management

• Configurable cache TTL (default 24h)
• Automatic cache refresh
• Force refresh option

Configuration

• All options in config.ini
• Command line overrides
• Environment variable support
• Docker-friendly config

Operational Features

• Simulation mode (no files deleted by default)
• Explicit deletion with --action delete
• Processing summaries and logs
• Tracks actions and timestamps

Rate Limiting

• Configurable per-service rate limits

Technical Features

• Error handling for API/database failures
• Safe DB transaction management
• Database repair, backup, and restore
• Configurable logging (console and file)
• Docker containerization

Command Line Options

• --skip-confirmation: Non-interactive mode
• --debug: Debug logging
• --force-refresh: Bypass cache
• --action: Default action for eligible shows
• --skip-overseerr, --skip-tautulli: Skip checks
• --ignore-first-season, --ignore-first-episode: Ignore certain shows

Safe Deletion Rules

• Do not delete shows with recent Overseerr requests
• Do not delete shows with any watch history
• Confirmation required in interactive mode

---

Configuration

• See config/example_config.ini for all available options and documentation.
• Place your config as config/config.ini or set the SHOWSWEEP_CONFIG environment variable.

---

Contributing

Pull requests and issues are welcome!

---

License

MIT