pyr34 0.2.1

Wrapper around the JSON/XML rule34.xxx API.

pyr34

Wrapper around the JSON/XML rule34.xxx API.

Classes

ClientAPI

Represents a connection to the R34 API.
Central component of the library. Handles all communication to and from the API.

Parameters

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.

---

Methods

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.

Parameters

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.

Returns

Generator that yields fetched Posts.

Notes

    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.

Parameters

id: int
    ID of the post to fetch.

Returns

    Post
    The fetched post.

Notes

    Logs fetch at INFO level.

---

get_comments(post: Post) -> list[Comments]
    Fetch the comments of a post.

Parameters

post: Post
    Post to fetch comments from.

Returns

list[Comment]
    List of fetched comments.

Notes

    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.

Returns

    xml.etree.ElementTree.Element or Any
    XML parsed as an Element, or JSON parsed into Python objects.

Notes

    Logs API request at INFO level.
    Returns None for empty responses / malformed requests.

---

Post

Represents a post.

Attributes

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.

---

Methods

get_comments() -> list[Comment]
    Fetch post's comments in real-time.

get_url() -> str
    URL of post given the base URL provided to ClientAPI.

---

Comment

Represents a comment.

Attributes

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.

---

Rating (Enum)

Safe, Questionable, or Explicit.

Class Methods

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".

---

Tag

Represents a tag.
Utilizes a DSL-like system of combining Tag objects.

Operators

     tag1 & tag2: tag1 tag2
     tag1 | tag2: ( tag1 ~ tag2 )
     tag1 - tag2: tag1 -tag2
     -tag OR ~tag: -tag

Notes

    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.