🔄 WHSync

WHSync is a Python utility which synchronizes wallpapers from Wallhaven collections. It's aimed at backing up your favorites locally.

Features

• Wallpaper downloading: syncs all wallpapers from specified collections. Tries to make sure the local file sizes match the ones on the server.
• Rate limiting: implements throttling mechanisms to handle API usage gracefully.
• Progress display: shows progress of the synchronization.
• Filtering: filter wallpapers by orientation/ratio (landscape, portrait/vertical, square, or exact ratios like 16:9) and by minimum resolution (e.g. 1920x1080).
• Pruning: optionally delete local files that are no longer in the synced collection (--delete-removed).

Getting Started

Prerequisites

You will need Python 3.8+ with requests library installed on your system. You'll also need a Wallhaven API key. You can obtain one from your account settings.

Installation

1. Clone the repository or just download whsync.py.
2. Install dependencies (e.g. pip install requests).

Usage

To sync a collection, execute:

python whsync.py --username jdoe --api-key B6u36iIK8ljcfEKPNKNiGehKycdODbbP --collection-label "Landscapes" --output-dir /home/jdoe/wallpapers/landscapes --delete-removed

To sync only landscape wallpapers at least 1920×1080:

python whsync.py --username jdoe --api-key B6u36iIK8ljcfEKPNKNiGehKycdODbbP --collection-id 123 -o /home/jdoe/wallpapers/landscapes --ratio landscape --min-resolution 1920x1080

To see all available options, run:

python whsync.py --help

You can change throttling settings by modifying DEFAULT_API_DELAY and DEFAULT_DOWNLOAD_DELAY right in the code.

If your script is running for a long time, you can prevent your computer from going to sleep by running the script in systemd-inhibit wrapper:

systemd-inhibit python whsync.py

License

This script is licensed under the MIT License.