Search Parameters¶

Wallhaven¶

class xanax.sources.wallhaven.params.SearchParams(**data)[source]¶

Bases: BaseModel

Parameters for a Wallhaven wallpaper search.

All fields are validated before any network request is made. Invalid combinations raise ValidationError immediately.

The default categories includes all three (general, anime, people), matching Wallhaven’s own default search behaviour.

Example

params = SearchParams(
    query="+anime -sketch",
    categories=[Category.ANIME],
    purity=[Purity.SFW],
    sorting=Sort.TOPLIST,
    top_range=TopRange.ONE_MONTH,
)

query: str | None¶

categories: list[Category]¶

purity: list[Purity]¶

sorting: Sort¶

order: Order¶

top_range: TopRange | None¶

resolutions: list[str]¶

ratios: list[str]¶

colors: list[Color]¶

page: int¶

seed: str | None¶

file_type: FileType | None¶

like: str | None¶

classmethod validate_resolutions(v)[source]¶

Return type:: list[str]

classmethod validate_ratios(v)[source]¶

Return type:: list[str]

classmethod validate_seed(v)[source]¶

Return type:: str | None

model_post_init(_SearchParams__context)[source]¶

Override this method to perform additional initialization after __init__ and model_construct. This is useful if you want to do some validation that requires the entire model to be initialized.

Return type:: None

to_query_params()[source]¶

Serialize to a dict of API query parameters.

Return type:: dict[str, Any]
Returns:: Dict suitable for passing as params= to an httpx request.

with_page(page)[source]¶

Return a new SearchParams with only the page number changed.

Parameters:: page (int) – New page number.
Return type:: SearchParams
Returns:: New instance with page updated and all other fields preserved.

with_seed(seed)[source]¶

Return a new SearchParams with only the seed changed.

Parameters:: seed (str) – New seed value (6 alphanumeric characters).
Return type:: SearchParams
Returns:: New instance with seed updated and all other fields preserved.

model_config: ClassVar[ConfigDict] = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

Unsplash¶

class xanax.sources.unsplash.params.UnsplashSearchParams(**data)[source]¶

Bases: BaseModel

Parameters for GET /search/photos.

The query field is required. All other fields have sensible defaults matching the Unsplash API’s own defaults.

Example

params = UnsplashSearchParams(
    query="mountains",
    orientation=UnsplashOrientation.LANDSCAPE,
    color=UnsplashColor.BLUE,
    order_by=UnsplashOrderBy.LATEST,
    per_page=30,
)
result = unsplash.search(params)

Parameters:

query (str) – Search terms. Required.
page (int) – Page number (1-indexed). Default is 1.
per_page (int) – Results per page. Min 1, max 30. Default is 10.
order_by (UnsplashOrderBy) – How to sort results. Default is RELEVANT.
collections (list[str]) – Collection IDs to narrow the search (comma-joined internally).
content_filter (UnsplashContentFilter) – Content safety level. Default is LOW.
color (UnsplashColor | None) – Filter by dominant color.
orientation (UnsplashOrientation | None) – Filter by photo orientation.

query: str¶

page: int¶

per_page: int¶

order_by: UnsplashOrderBy¶

collections: list[str]¶

content_filter: UnsplashContentFilter¶

color: UnsplashColor | None¶

orientation: UnsplashOrientation | None¶

to_query_params()[source]¶

Serialize parameters to a dict suitable for use as HTTP query params.

Return type:: dict[str, Any]
Returns:: Dictionary of query parameters for the API request.

with_page(page)[source]¶

Return a new UnsplashSearchParams with the page number updated.

Parameters:: page (int) – New page number.
Return type:: UnsplashSearchParams
Returns:: New instance with page updated and all other fields preserved.

model_config: ClassVar[ConfigDict] = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class xanax.sources.unsplash.params.UnsplashRandomParams(**data)[source]¶

Bases: BaseModel

Parameters for GET /photos/random.

All fields are optional. With no parameters, a completely random photo is returned. Parameters narrow the pool of eligible photos.

Note

collections and topics cannot be combined with query in the same request. The API will return an error if both are provided.

Example

params = UnsplashRandomParams(
    query="forest",
    orientation=UnsplashOrientation.LANDSCAPE,
)
photo = unsplash.random(params)

Parameters:

collections (list[str]) – Collection IDs to restrict the random pool to.
topics (list[str]) – Topic IDs to restrict the random pool to.
username (str | None) – Restrict to photos from a specific user.
query (str | None) – Restrict to photos matching a search term.
orientation (UnsplashOrientation | None) – Filter by photo orientation.
content_filter (UnsplashContentFilter) – Content safety level. Default is LOW.

collections: list[str]¶

topics: list[str]¶

username: str | None¶

query: str | None¶

orientation: UnsplashOrientation | None¶

content_filter: UnsplashContentFilter¶

to_query_params()[source]¶

Serialize parameters to a dict suitable for use as HTTP query params.

Return type:: dict[str, Any]
Returns:: Dictionary of query parameters for the API request.

model_config: ClassVar[ConfigDict] = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

Reddit¶

class xanax.sources.reddit.params.RedditParams(**data)[source]¶

Bases: BaseModel

Parameters for a subreddit media listing request.

The subreddit field is required. All other fields have sensible defaults. Use the + separator to fetch from multiple subreddits at once (e.g. "EarthPorn+spaceporn").

Cursor-based pagination is handled via the after field. Use with_after() to build the next-page params from a listing’s after cursor rather than mutating the instance.

Note

time_filter only affects results when sort is TOP or CONTROVERSIAL. It is silently ignored for all other sort orders.

Example

params = RedditParams(
    subreddit="EarthPorn",
    sort=RedditSort.TOP,
    time_filter=RedditTimeFilter.WEEK,
    limit=50,
)
for post in reddit.iter_media(params):
    reddit.download(post, path=f"{post.id}.jpg")

Parameters:

subreddit (str) – Target subreddit(s). Use + to combine multiple, e.g. "wallpapers+EarthPorn". Required.
sort (RedditSort) – Listing sort order. Default is HOT.
time_filter (RedditTimeFilter) – Time window for TOP/CONTROVERSIAL listings. Default is ALL.
limit (int) – Posts per page (1–100). Default is 25.
after (str | None) – Cursor for the next page (fullname like 't3_abc123'). None fetches the first page.
media_type (MediaType) – Media type filter applied client-side. Default is ANY (no filtering).
include_nsfw (bool) – Whether to include NSFW posts. Default is False.

subreddit: str¶

sort: RedditSort¶

time_filter: RedditTimeFilter¶

limit: int¶

after: str | None¶

media_type: MediaType¶

include_nsfw: bool¶

with_after(after)[source]¶

Return a new RedditParams with the pagination cursor updated.

All other fields are preserved unchanged.

Parameters:: after (str) – New cursor value (fullname from RedditListing.after).
Return type:: RedditParams
Returns:: New RedditParams instance with after set.

model_config: ClassVar[ConfigDict] = {'frozen': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].