Struct ClientBuilder

Source

pub struct ClientBuilder<T: Client> { /* private fields */ }

Expand description

Builder for constructing booru API clients.

This builder allows you to configure various options before creating a client to query a booru site.

§Example

use booru_rs::danbooru::{DanbooruClient, DanbooruRating};
use booru_rs::client::Client;

let client = DanbooruClient::builder()
    .tag("cat_ears")?
    .rating(DanbooruRating::General)
    .limit(10)
    .build();

let posts = client.get().await?;

Implementations§

Source §

impl<T: Client> ClientBuilder<T>

Source

pub fn new() -> Self

Creates a new builder with default settings.

Uses the shared HTTP client for connection pooling.

Source

pub fn with_client(client: Client) -> Self

Creates a new builder with a custom HTTP client.

Use this when you need custom HTTP configuration (e.g., proxy, custom TLS).

Source

pub fn with_custom_url(self, url: &str) -> Self

Sets a custom base URL for the API.

This is primarily useful for testing with mock servers.

Source

pub fn set_credentials( self, key: impl Into<String>, user: impl Into<String>, ) -> Self

Sets the API key and username for authenticated requests.

Some booru sites require or benefit from authentication.

Source

pub fn tag(self, tag: impl Into<String>) -> Result<Self>

Adds a tag to the search query.

§Errors

Returns BooruError::TagLimitExceeded if adding this tag would exceed the client’s maximum tag limit.

§Example

use booru_rs::danbooru::DanbooruClient;
use booru_rs::client::Client;

let client = DanbooruClient::builder()
    .tag("cat_ears")?
    .tag("blue_eyes")?
    .build();

Source

pub fn rating(self, rating: T::Rating) -> Self

Adds a rating filter to the search query.

The rating type is specific to each booru site, ensuring compile-time type safety.

§Example

use booru_rs::danbooru::{DanbooruClient, DanbooruRating};
use booru_rs::client::Client;

let client = DanbooruClient::builder()
    .rating(DanbooruRating::General)
    .build();

Source

pub fn limit(self, limit: u32) -> Self

Sets the maximum number of posts to retrieve.

Default is 100, which is also typically the maximum allowed by most APIs.

Source

pub fn random(self) -> Self

Enables random ordering of results.

Source

pub fn sort(self, order: Sort) -> Self

Adds a sort order to the query.

Source

pub fn blacklist_tag(self, tag: impl Into<String>) -> Self

Excludes posts with the specified tag.

Multiple blacklist tags can be added by calling this method multiple times.

Source

pub fn default_url(self, url: impl Into<String>) -> Self

Overrides the default API URL.

Useful for testing or accessing mirror sites.

Source

pub fn page(self, page: u32) -> Self

Sets the page number for pagination.

Page numbering starts at 0.

Source

pub fn tags<I, S>(self, tags: I) -> Result<Self>
where I: IntoIterator<Item = S>, S: Into<String>,

Adds multiple tags to the search query at once.

§Errors

Returns BooruError::TagLimitExceeded if adding these tags would exceed the client’s maximum tag limit.

§Example

use booru_rs::prelude::*;

let client = GelbooruClient::builder()
    .tags(["cat_ears", "blue_eyes", "1girl"])?
    .build();

Source

pub fn blacklist_tags<I, S>(self, tags: I) -> Self
where I: IntoIterator<Item = S>, S: Into<String>,

Excludes multiple tags from the search query at once.

§Example

use booru_rs::prelude::*;

let client = GelbooruClient::builder()
    .tag("cat_ears")?
    .blacklist_tags(["ugly", "low_quality"])
    .build();

Source

pub fn tag_count(&self) -> usize

Returns the current number of tags in the query.

Source

pub fn has_tags(&self) -> bool

Returns true if the builder has any tags configured.

Source

pub fn build(self) -> T

Builds the client with the configured options.

Source §

impl<T: Client> ClientBuilder<T>

Source

pub fn into_page_stream(self) -> PageStream<T>

Creates an async stream that yields pages of posts.

Each call to next() fetches and returns a full page of posts.

§Example

use booru_rs::prelude::*;

let mut stream = SafebooruClient::builder()
    .tag("landscape")?
    .limit(100)
    .into_page_stream();

while let Some(page_result) = stream.next().await {
    let posts = page_result?;
    if posts.is_empty() { break; }
    println!("Page with {} posts", posts.len());
}

Source

pub fn into_post_stream(self) -> PostStream<T>

Creates an async stream that yields individual posts.

Automatically handles pagination, fetching new pages as needed.

§Example

use booru_rs::prelude::*;

let mut stream = SafebooruClient::builder()
    .tag("landscape")?
    .limit(100)
    .into_post_stream()
    .max_posts(250);

while let Some(post_result) = stream.next().await {
    let post = post_result?;
    println!("Post #{}", post.id);
}