|
| 1 | +# Wallhaven API v1 Python Wrapper |
| 2 | + |
| 3 | +## Overview |
| 4 | + |
| 5 | +This module provides a Python wrapper for the [Wallhaven.cc API](https://wallhaven.cc/help/api) (v1), enabling users to programmatically search for wallpapers, fetch wallpaper metadata, download images, and interact with user collections. |
| 6 | + |
| 7 | +It is suitable for building custom tools or integrations around the Wallhaven API. |
| 8 | + |
| 9 | +> [!Note] |
| 10 | +> This project is unofficial and not affiliated with [Wallhaven.cc](https://wallhaven.cc). |
| 11 | +> Use at your own discretion and in accordance with the site's [terms of service](https://wallhaven.cc/about). |
| 12 | +
|
| 13 | +--- |
| 14 | + |
| 15 | +## 📦 Installation |
| 16 | + |
| 17 | +This module can be installed from PyPI (recommended), or manually by cloning the repo and moving it to your project's root directory. |
| 18 | + |
| 19 | +If installing manually, be sure to clone the latest release and not the `main` branch. The latest release is identical to that on PyPI. |
| 20 | +Additionally, the `requests` library will also need to be installed from PyPI or your preferred method. |
| 21 | + |
| 22 | +* PyPI Install |
| 23 | +```bash |
| 24 | +pip install wallhavenapi |
| 25 | +``` |
| 26 | + |
| 27 | +* Manual Install |
| 28 | +```bash |
| 29 | +git clone --depth=1 https://github.com/raycadle/WallhavenAPI.git && cd WallhavenAPI |
| 30 | +pip install -r requirements.txt |
| 31 | +``` |
| 32 | + |
| 33 | +--- |
| 34 | + |
| 35 | +## 🚀 Quick Start |
| 36 | + |
| 37 | +```python |
| 38 | +from wallhavenapi import WallhavenAPI, Category, Purity |
| 39 | + |
| 40 | +api = WallhavenAPI(api_key="your_api_key") |
| 41 | +results = api.search(q="nature", categories=[Category.general], purities=[Purity.sfw]) |
| 42 | + |
| 43 | +# Download a specific wallpaper |
| 44 | +wallpaper_id = results["data"][0]["id"] |
| 45 | +api.download_wallpaper(wallpaper_id, "wallpaper.jpg") |
| 46 | +``` |
| 47 | + |
| 48 | +--- |
| 49 | + |
| 50 | +## 🐛 Issue Reporting |
| 51 | + |
| 52 | +Report bugs [here](https://github.com/raycadle/WallhavenAPI/issues). |
| 53 | + |
| 54 | +--- |
| 55 | + |
| 56 | +## Notes |
| 57 | + |
| 58 | +* All API interaction is wrapped in safe error handling with custom exceptions. |
| 59 | +* The wrapper is designed to respect Wallhaven API rate limits if configured via `requestslimit_timeout`. |
0 commit comments