Collections

Wallhaven lets users organize wallpapers into named collections. xanax exposes two collection endpoints.

List a user’s collections

from xanax import Wallhaven

client = Wallhaven()

# Public collections for any user (no API key needed)
collections = client.collections(username="someuser")
for col in collections:
    print(col.id, col.label, col.count, "wallpapers")

Your own collections

Without a username, the API returns the authenticated user’s own collections:

client = Wallhaven(api_key="your-api-key")
collections = client.collections()

This requires an API key. Without one, AuthenticationError is raised.

Get wallpapers in a collection

listing = client.collection(username="someuser", collection_id=15)

print(f"Page {listing.meta.current_page} of {listing.meta.last_page}")

for wallpaper in listing.data:
    print(wallpaper.id, wallpaper.resolution)

listing is a CollectionListing, which has the same data and meta fields as a SearchResult.

Collection metadata

Each Collection object has:

collection.id       # int — collection ID
collection.label    # str — collection name
collection.views    # int — view count
collection.public   # bool — whether the collection is public
collection.count    # int — number of wallpapers

Async

import asyncio
from xanax import AsyncWallhaven

async def main():
    async with AsyncWallhaven(api_key="your-api-key") as client:
        collections = await client.collections(username="someuser")
        listing = await client.collection("someuser", collections[0].id)

        for wallpaper in listing.data:
            print(wallpaper.id)

asyncio.run(main())

Paginating a collection

Collection listings use the same pagination metadata as search results. Use PaginationHelper or request pages manually:

from xanax import PaginationHelper

listing = client.collection("someuser", 15)
helper = PaginationHelper(listing.meta)

while helper.has_next:
    listing = client.collection("someuser", 15)
    # ... process listing.data

Or use manual page control:

page = 1
while True:
    listing = client.collection("someuser", 15)
    # process page...
    if listing.meta.current_page >= listing.meta.last_page:
        break
    page += 1