Wrapper around the JSON/XML rule34.xxx API.
Represents a connection to the R34 API.
Central component of the library. Handles all communication to and from the API.
user_id: int
The ID of the user associated with the API key
api_key: str
The API key used to authenticate the R34 API
url: str, optional (keyword-only)
Base URL for the API, should be an index.php.
If omitted, https://api.rule34.xxx/index.php is used.
base_url: str, optional (keyword-only)
Base URL for the website
If omitted, https://rule34.xxx/ is used.
search_posts(tags: Tag | str = Tag(), *, limit: int = 1000, exclusions: list[Tag] | list[str] | None = None, page: int = 0, suppress_log: bool = False) -> Generator[Post]
Search for posts via standard search tags.
tags: Tag or str, optional
Tags to search for.
If omitted, pull from the front page.
limit: int, optional (keyword-only)
Maximum number of posts to pull.
If omitted, pull the maximum allowed (1000).
exclusions: list[Tag] or list[str], optional (keyword-only)
Tags to exclude from search.
page: int, optional (keyword-only)
Page of results to return.
If omitted, return first page.
suppress_log: bool, optional (keyword-only)
Don't log search. Intended for internal use.
Generator that yields fetched Posts.
Logs search at INFO level.
Excluding tags using tags is allowed, but discouraged due to R34 quirks.
get_post(id: int) -> Post
Fetch a post by ID.
id: int
ID of the post to fetch.
Post
The fetched post.
Logs fetch at INFO level.
get_comments(post: Post) -> list[Comments]
Fetch the comments of a post.
post: Post
Post to fetch comments from.
list[Comment]
List of fetched comments.
Logs fetch at INFO level.
request(params: Mapping[str, Any]) -> ET.Element | Any | None
Make a generic request to the API.
Usage is discouraged, as input validation and error handling is minimal.
xml.etree.ElementTree.Element or Any
XML parsed as an Element, or JSON parsed into Python objects.
Logs API request at INFO level.
Returns None for empty responses / malformed requests.
Represents a post.
id: int
ID of the post.
tags: list[Tag]
List of post's tags.
author: str
User who created the post.
source: str
Where the post came from.
score: int
Post's score.
rating: Rating
Safe, Questionable, or Explicit.
last_change: datetime.datetime
Timestamp of the post's last edit in UTC.
content_url: str
URL of the post's image.
comments: list[Comment]
Lazy-loaded list of comments.
get_comments() -> list[Comment]
Fetch post's comments in real-time.
get_url() -> str
URL of post given the base URL provided to ClientAPI.
Represents a comment.
id: int
ID of the comment.
post: Post
Post the comment is under.
content: str
Content of the comment.
author: str
Creator of the comment.
created_at: datetime.datetime
Timestamp of the comment's creation in UTC.
Safe, Questionable, or Explicit.
str_to_rating(rating: str) -> Rating
Maps "safe", "questionable", and "explicit" to enum values.
rating_to_str(rating: Rating) -> str
Maps enum values to "safe", "questionable", and "explicit".
Represents a tag.
Utilizes a DSL-like system of combining Tag objects.
tag1 & tag2: tag1 tag2
tag1 | tag2: ( tag1 ~ tag2 )
tag1 - tag2: tag1 -tag2
-tag OR ~tag: -tag
All binary operators support str inputs for other
R34 is strange, and several combinations of tags aren't allowed. Don't be surprised if no posts come up.