yts/
lib.rs

1//! # YTS Movie API Client
2//!
3//! This crate provides an interface for searching and retrieving movie information from the YTS API,
4//! including filtering options, pagination, and torrent details.
5//!
6//! ## Features
7//! - Async and blocking HTTP clients (enabled via feature flags `async` and `blocking`).
8//! - Rich filtering options such as quality, genre, rating, year, and sorting order.
9//! - Parsing of HTML responses to extract movie and torrent metadata.
10//!
11//!
12//! ### Async Example (default)
13//!
14//! ```
15//! # #[cfg(feature = "async")]
16//! use yts::{Filters, OrderBy, Year, Yts};
17//!
18//! #[tokio::main]
19//! async fn main() -> yts::Result {
20//!     let yts = Yts::default();
21//!     let response = yts
22//!         .search_with_filter(
23//!             "the godfather",
24//!             Filters::default()
25//!                 .year(Year::Range1970to1979)
26//!                 .order_by(OrderBy::Rating)
27//!                 .build(),
28//!         )
29//!         .await?;
30//!
31//!     println!("{response:#?}");
32//!
33//!     // Getting the torrents of the first movie
34//!     let torrents = yts
35//!         .torrents(&response.movies[0])
36//!         .await?;
37//!
38//!     println!("{torrents:#?}");
39//!
40//!     Ok(())
41//! }
42//! ```
43//!
44//! ## Modules & Re-exports
45//!
46//! The crate re-exports key types for convenience:
47//! - Filtering options: [`Filters`], [`OrderBy`], [`Quality`], [`Rating`], [`Year`]
48//! - Core types: [`Page`], [`Response`], [`Torrent`], [`Genre`], [`Movie`]
49//! - Client structs: [`Yts`] (async) and blocking client (behind feature flags)
50//!
51//! ## Error Handling
52//!
53//! All fallible operations return [`Result<T>`](Result) with a custom [`Error`] enum that wraps
54//! errors from underlying dependencies (e.g., `reqwest`, `scraper`).
55//!
56//! ## Feature Flags
57//!
58//! - `async` — Enables the asynchronous API (`search`).
59//! - `blocking` — Enables the blocking (synchronous) API (`blocking::search`).
60//!
61//! ## License
62//!
63//! This is free software, published under the [MIT License](https://mit-license.org/).
64//!
65//! ## See Also
66//!
67//! - [`reqwest`] — HTTP client for requests.
68//! - [`scraper`] — HTML parsing for subtitle extraction.
69
70mod client;
71mod core;
72
73pub use client::{Filters, OrderBy, Quality, Rating, Year};
74pub use core::{
75    Page, Response, Torrent,
76    model::{Genre, Movie},
77};
78
79#[cfg(feature = "async")]
80pub use client::default::Yts;
81
82#[cfg(feature = "blocking")]
83pub use client::blocking;
84
85/// Errors that can occur when using this crate.
86///
87/// This enum wraps errors from underlying dependencies such as [`reqwest`] and [`scraper`],
88/// as well as custom errors related to parsing movie data.
89#[derive(thiserror::Error, Debug)]
90pub enum Error {
91    /// Error originating from an HTTP request failure.
92    #[error(transparent)]
93    ReqwestError(#[from] reqwest::Error),
94
95    /// Error converting HTTP header values to strings.
96    #[error(transparent)]
97    ToStrError(#[from] reqwest::header::ToStrError),
98
99    /// Error parsing CSS selectors during HTML scraping.
100    #[error(transparent)]
101    SelectorError(#[from] scraper::error::SelectorErrorKind<'static>),
102
103    /// Error parsing a floating point number.
104    #[error(transparent)]
105    ParseFloatError(#[from] std::num::ParseFloatError),
106
107    /// Error parsing an integer.
108    #[error(transparent)]
109    ParseIntError(#[from] std::num::ParseIntError),
110
111    /// Error indicating failure to extract the movie rating from HTML.
112    #[error("Error getting movie rating")]
113    MovieRatingError,
114
115    /// Error indicating failure to extract the movie year from HTML.
116    #[error("Error getting movie year")]
117    MovieYearError,
118
119    /// Error indicating failure to extract the movie name from HTML.
120    #[error("Error getting movie name")]
121    MovieNameError,
122
123    /// Error parsing an url.
124    #[error("Error parsing url {0}")]
125    ParseError(String),
126}
127
128/// A convenient alias for `Result` with the crate's [`Error`] type.
129///
130/// Defaults to `()` for the success type if not specified.
131pub type Result<T = ()> = std::result::Result<T, Error>;
yts/lib.rs

yts/
lib.rs
