### Install Dependencies and Build Project

Source: https://b3yc0d3.github.io/rule34Py/dev/developer-guide.html

Installs project dependencies using poetry and builds the project's wheels using make. Ensure you have git, GNU Make, and poetry installed.

```bash
poetry install
make all
```

--------------------------------

### Install Dependencies

Source: https://b3yc0d3.github.io/rule34Py/tutorials/downloader.html

Install the necessary Python packages using pip. Ensure you have pip installed.

```bash
python -m pip install rule34Py
python -m pip install requests
```

--------------------------------

### Install Dependencies and Run Project Tests

Source: https://b3yc0d3.github.io/rule34Py/dev/contributing.html

Install project dependencies using Poetry if not already done, then execute the project's test suite using 'make check'. Ensure all tests pass before submitting changes.

```bash
poetry install  # Optional, if you have not done it previously.
make check
```

--------------------------------

### Install rule34Py

Source: https://b3yc0d3.github.io/rule34Py/index.html

Install the rule34Py package using pip. Alternatively, you can build it from source.

```bash
pip install rule34Py
```

--------------------------------

### Install Dependencies and Lint Project Sources

Source: https://b3yc0d3.github.io/rule34Py/dev/contributing.html

Install project dependencies using Poetry if not already done, then run the project linter using 'make lint'. This command utilizes 'ruff' to check all project sources for style and quality issues.

```bash
poetry install  # Optional, if you have not done it previously.
make lint
```

--------------------------------

### Complete Example Script

Source: https://b3yc0d3.github.io/rule34Py/tutorials/downloader.html

A complete script combining initialization, tag definition, search, and download functionality. Ensure you replace placeholder API keys and user IDs with your actual credentials.

```python
from rule34Py import rule34Py

client = rule34Py()
client.api_key = "YOUR_API_KEY"
client.user_id = "YOUR_USER_ID"

TAGS = ["neko", "sort:score", "-video"]

results = client.search(tags=TAGS)

from pathlib import Path
import requests

DOWNLOAD_LIMIT = 3

for result in results[0:DOWNLOAD_LIMIT]:
    print(f"Downloading post {result.id} ({result.image}).")
    with open(Path(result.image).name, "wb") as fp_output:
        resp = requests.get(result.image)
        resp.raise_for_status()
        fp_output.write(resp.content)
```

--------------------------------

### Common Development Commands

Source: https://b3yc0d3.github.io/rule34Py/dev/developer-guide.html

A quick reference for common development tasks including installation, building, testing, and linting. These commands streamline the development workflow.

```bash
poetry install
make all    # build wheel
make check  # run unit tests
make dist   # build sdist
make html   # build documentation
make lint   # run project linter
```

--------------------------------

### Get package license information

Source: https://b3yc0d3.github.io/rule34Py/guides/package-metadata.html

Extract the project's SPDX license identifier by interrogating the `License` field from the package metadata.

```python
from importlib.metadata import metadata
license = metadata("rule34Py")["License"]
```

--------------------------------

### get_post

Source: https://b3yc0d3.github.io/rule34Py/api/rule34Py/rule34.html

Get a Post by its ID.

```APIDOC
## get_post

### Description
Get a specific Post by its ID. Returns None if the post ID is not found.

### Method
```
get_post(_post_id : int_)
```

### Parameters
#### Path Parameters
- **post_id** (int) - Required - The Post's Rule34 ID.

### Returns
- The Post object matching the post_id, or None if the post_id is not found.

### Raises
- requests.HTTPError: The backing HTTP GET operation failed.
```

--------------------------------

### Get package version

Source: https://b3yc0d3.github.io/rule34Py/guides/package-metadata.html

Extract the project's version information using the `importlib.metadata.version` method. The version is guaranteed to be PEP440 compliant.

```python
from importlib.metadata import version
rule34Py_version = version("rule34Py")
```

--------------------------------

### Get a Pool of Posts

Source: https://b3yc0d3.github.io/rule34Py/api/rule34Py/rule34.html

Retrieve a collection of posts organized into a pool, identified by its ID. This method is rate-limited.

```python
pool = client.get_pool(pool_id=5678)
```

--------------------------------

### random_post

Source: https://b3yc0d3.github.io/rule34Py/api/rule34Py/rule34.html

Get a random post.

```APIDOC
## random_post

### Description
Get a random post. This method behaves similarly to the website's Post > Random function. It uses the interactive website and is subject to rate limiting.

### Method
```
random_post()
```

### Returns
- A random Post object.

### Raises
- requests.HTTPError: The backing HTTP GET operation failed.
```

--------------------------------

### Get Tag Suggestions

Source: https://b3yc0d3.github.io/rule34Py/api/rule34Py/rule34.html

Retrieve tag suggestions based on partial input. Results are ordered by popularity. This method may raise an HTTPError or ValueError.

```python
suggestions = client.autocomplete('tag_prefix')
```

--------------------------------

### Get a Random Post

Source: https://b3yc0d3.github.io/rule34Py/api/rule34Py/rule34.html

Retrieve a random post. Note that this method uses the interactive website and is rate-limited.

```python
random_post = client.random_post()
```

--------------------------------

### random_post_id

Source: https://b3yc0d3.github.io/rule34Py/api/rule34Py/rule34.html

Get a random Post ID.

```APIDOC
## random_post_id

### Description
Get a random Post ID. This method returns the Post ID contained in the 302 redirect the website responds with when using the "random post" function. It uses the interactive website and is subject to rate limiting.

### Method
```
random_post_id()
```

### Returns
- An integer representing a random Post ID.

### Raises
- requests.HTTPError: The backing HTTP GET operation failed.
```

--------------------------------

### Get Top 100 iCame Objects

Source: https://b3yc0d3.github.io/rule34Py/api/rule34Py/rule34.html

Retrieve a list of the top 100 iCame objects. This method uses the interactive website and is subject to rate limiting.

```python
icame_list = client.icame()
```

--------------------------------

### Get a Specific Post by ID

Source: https://b3yc0d3.github.io/rule34Py/api/rule34Py/rule34.html

Retrieve a single post using its unique ID. Returns None if the post is not found. This method may raise an HTTPError.

```python
post = client.get_post(1234)
```

--------------------------------

### Get package maintainer information

Source: https://b3yc0d3.github.io/rule34Py/guides/package-metadata.html

Extract the package's maintainer name and email using the `Maintainer` and `Maintainer-email` fields from the package metadata.

```python
from importlib.metadata import metadata
maintainer = metadata("rule34Py")["Maintainer"]
maintainer_email = metadata("rule34Py")["Maintainer-email"]
```

--------------------------------

### Get Comments for a Post

Source: https://b3yc0d3.github.io/rule34Py/api/rule34Py/rule34.html

Retrieve all comments associated with a specific post ID. Returns an empty list if no comments are found. Be aware of a known API bug where creation timestamps are inaccurate.

```python
comments = client.get_comments(post_id=1234)
```

--------------------------------

### Build Project Documentation

Source: https://b3yc0d3.github.io/rule34Py/dev/developer-guide.html

Builds the project's documentation using make html. The output will be placed in the :build/html/ directory.

```bash
make html
```

--------------------------------

### Host Documentation Locally

Source: https://b3yc0d3.github.io/rule34Py/dev/developer-guide.html

Serves the built documentation locally using Python's http.server. Navigate to the build/html directory and run the command to test changes.

```bash
cd build/html
python -m http.server 8080
```

--------------------------------

### Run Unit Tests

Source: https://b3yc0d3.github.io/rule34Py/dev/developer-guide.html

Executes the project's unit tests using make test. This command requires the build environment to be set up.

```bash
make test
```

--------------------------------

### Initialize rule34Py Client

Source: https://b3yc0d3.github.io/rule34Py/api/rule34Py/rule34.html

Instantiate the main API client. API keys and user IDs can be set after initialization.

```python
client = rule34Py()
client.api_key="API_KEY"
client.user_id="USER_ID"
```

--------------------------------

### rule34Py Client Initialization

Source: https://b3yc0d3.github.io/rule34Py/api/rule34Py/rule34.html

Instantiate the Rule34Py client and optionally set API key and user ID.

```APIDOC
## rule34Py Client Initialization

### Description
Instantiate the Rule34Py client. You can optionally set your API key and user ID.

### Usage
```python
client = rule34Py()
client.api_key = "YOUR_API_KEY"
client.user_id = "YOUR_USER_ID"
```
```

--------------------------------

### Initialize Rule34Py Client

Source: https://b3yc0d3.github.io/rule34Py/tutorials/downloader.html

Import the rule34Py module and create a client instance to interact with the API. This client handles API requests and data marshalling.

```python
from rule34Py import rule34Py

client = rule34Py()
```

--------------------------------

### Get a Random Post ID

Source: https://b3yc0d3.github.io/rule34Py/api/rule34Py/rule34.html

Retrieve the ID of a random post. This method is rate-limited as it interacts with the website's random post function.

```python
random_post_id = client.random_post_id()
```

--------------------------------

### Initialize and Use rule34Py Client

Source: https://b3yc0d3.github.io/rule34Py/index.html

Initialize the rule34Py client, set API credentials, and perform various API operations like fetching comments, posts, pools, or searching by tags. Ensure your API key and user ID are set before making requests.

```python
from rule34Py import rule34Py
client = rule34Py()
client.api_key = "YOUR_API_KEY"
client.user_id = "YOUR_USER_ID"

# Get comments of an post.
client.get_comments(4153825)

# Get post by its id.
client.get_post(4153825)

# Get top 100 icame.
client.icame()

# Search for posts by tag(s).
client.search(["neko"], page_id=2, limit=50)

# Get pool by id.
client.get_pool(28)

# Get a random post.
random = client.random_post()

# Get just a random post ID.
random_id = client.random_post_id()
```

--------------------------------

### Clone Repository

Source: https://b3yc0d3.github.io/rule34Py/dev/developer-guide.html

Clones the rule34Py repository from GitHub and navigates into the project directory. This is the first step for building from source.

```bash
git clone https://github.com/b3yc0d3/rule34Py.git
cd rule34Py
```

--------------------------------

### Post.from_json Static Method

Source: https://b3yc0d3.github.io/rule34Py/api/rule34Py/post.html

Initialize a Post object directly from a JSON string obtained from the api.rule34.xxx API.

```APIDOC
## static rule34Py.post.Post.from_json

### Description
Initialize a Post object from an `api.rule34.xxx` JSON Post element.

### Parameters
* **json** (_str_) – The JSON string to parse.

### Returns
* **Post** - The rule34Py.Post representation of the object.
```

--------------------------------

### Post Class Initialization

Source: https://b3yc0d3.github.io/rule34Py/api/rule34Py/post.html

The Post class constructor initializes a Rule34 Post object with its essential attributes. These attributes are directly mapped from the Rule34.xxx JSON API response.

```APIDOC
## class rule34Py.post.Post

### Description
A Rule34 Post object, representing a single post from Rule34.xxx.

### Parameters
* **id** (_int_) – The Post’s Rule34 ID number.
* **hash** (_str_) – The Post’s Rule34 object hash.
* **score** (_int_) – The Post’s voted user score.
* **size** (_list_) – A two-element list of image dimensions. [width, height]
* **image** (_str_) – URL to the Post’s rule34 image server location.
* **preview** (_str_) – A URL to the Post’s preview image.
* **sample** (_str_) – A URL to the Post’s sample image.
* **owner** (_str_) – The user who owns the Post.
* **tags** (_list_) – A list of tags to assign to the Post.
* **file_type** (_str_) – The Post’s image file type. One of ["image", "gif", "video"].
* **directory** (_int_) – The Post’s image directory on the Rule34 image server.
* **change** (_int_) – The Post’s change ID.
```

--------------------------------

### autocomplete

Source: https://b3yc0d3.github.io/rule34Py/api/rule34Py/rule34.html

Retrieve tag suggestions based on partial input.

```APIDOC
## autocomplete

### Description
Retrieve tag suggestions based on partial input. The results are ordered by popularity in descending order.

### Method
```
autocomplete(_tag_string : str_)
```

### Parameters
#### Path Parameters
- **tag_string** (str) - Required - Partial tag input to search suggestions for.

### Returns
- A list of AutocompleteTag objects matching the search query.

### Raises
- requests.HTTPError: The backing HTTP request failed.
- ValueError: If the response contains invalid data structure.
```

--------------------------------

### rule34Py.rule34 Module

Source: https://b3yc0d3.github.io/rule34Py/api/rule34Py/rule34.html

This section details the constants and the main function available within the rule34Py.rule34 module.

```APIDOC
## Constants

### `DEFAULT_USER_AGENT`

- **Description**: Default User-Agent string used for requests.

### `SEARCH_RESULT_MAX`

- **Description**: Maximum number of search results that can be requested.

## `rule34Py` Function

### Description

- **Description**: The main function to search for posts on Rule34.xxx.

### Parameters

#### Query Parameters

- **tags** (str) - Required - A string of tags to search for, separated by spaces.
- **limit** (int) - Optional - The maximum number of results to return. Defaults to `SEARCH_RESULT_MAX`.
- **pid** (int) - Optional - The page number of the search results. Defaults to 0.

### Response

#### Success Response (200)

- **posts** (list) - A list of post objects, where each object contains details about a post.
  - **id** (int) - The unique identifier of the post.
  - **tags** (str) - The tags associated with the post.
  - **file_url** (str) - The URL of the post's image or video file.
  - **preview_url** (str) - The URL of the post's preview image.
  - **preview_width** (int) - The width of the preview image.
  - **preview_height** (int) - The height of the preview image.
  - **width** (int) - The width of the post's image or video file.
  - **height** (int) - The height of the post's image or video file.
  - **rating** (str) - The rating of the post (e.g., 'safe', 'questionable', 'explicit').
  - **source** (str) - The source URL of the post.
  - **created_at** (str) - The timestamp when the post was created.
  - **creator_id** (int) - The ID of the user who created the post.
  - **score** (int) - The score or number of favorites for the post.

### Request Example

```python
from rule34Py import rule34

posts = rule34("cat_girl", limit=10, pid=1)
for post in posts:
    print(f"Post ID: {post['id']}, URL: {post['file_url']}")
```

### Response Example

```json
{
  "posts": [
    {
      "id": 1234567,
      "tags": "cat_girl anime",
      "file_url": "http://example.com/image.jpg",
      "preview_url": "http://example.com/preview.jpg",
      "preview_width": 150,
      "preview_height": 100,
      "width": 800,
      "height": 600,
      "rating": "safe",
      "source": "http://example.com/source",
      "created_at": "2023-10-27T10:00:00Z",
      "creator_id": 98765,
      "score": 150
    }
  ]
}
```
```

--------------------------------

### Set Rule34 API Credentials

Source: https://b3yc0d3.github.io/rule34Py/guides/api-credentials.html

Configure your API key and user ID to authenticate requests with the Rule34 API. Ensure you have obtained these credentials from your rule34.xxx account settings.

```python
import rule34Py as r34
client = r34.rule34Py()

client.api_key="00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000"
client.user_id="0000000"

```

--------------------------------

### Search and Download Posts

Source: https://b3yc0d3.github.io/rule34Py/tutorials/downloader.html

Search for posts using the defined tags and download a limited number of images. This code iterates through the search results, fetches image content using requests, and saves it locally.

```python
results = client.search(tags=TAGS)

from pathlib import Path
import requests

DOWNLOAD_LIMIT = 3

for result in results[0:DOWNLOAD_LIMIT]:
    print(f"Downloading post {result.id} ({result.image}).")
    with open(Path(result.image).name, "wb") as fp_output:
        resp = requests.get(result.image)
        resp.raise_for_status()
        fp_output.write(resp.content)
```

--------------------------------

### get_pool

Source: https://b3yc0d3.github.io/rule34Py/api/rule34Py/rule34.html

Retrieve a pool of Posts.

```APIDOC
## get_pool

### Description
Retrieve a pool of Posts. This method uses the interactive website and is subject to rate limiting.

### Method
```
get_pool(_pool_id : int_)
```

### Parameters
#### Path Parameters
- **pool_id** (int) - Required - The pool's object ID on Rule34.

### Returns
- A Pool object representing the requested pool.

### Raises
- requests.HTTPError: The backing HTTP GET operation failed.
```

--------------------------------

### rule34Py.icame

Source: https://b3yc0d3.github.io/rule34Py/api/rule34Py/rule34.html

Functionality related to the 'i came' feature.

```APIDOC
## `icame` Module

### Description

- **Description**: This module likely handles interactions with a feature referred to as 'i came', possibly related to user history or tracking.

### Function

- **`icame(post_id)`**
  - **Description**: Records or retrieves information related to a specific post ID for the 'i came' feature.
  - **Parameters**:
    - `post_id` (int) - The ID of the post to interact with.
  - **Returns**: The result of the 'i came' operation (details depend on the API implementation).

### Usage Example

```python
# from rule34Py import icame
#
# result = icame(1234567)
# print(result)
```
```

--------------------------------

### rule34Py.html

Source: https://b3yc0d3.github.io/rule34Py/api/rule34Py/rule34.html

Utilities for parsing HTML content.

```APIDOC
## `html` Module

### Description

- **Description**: This module provides functions for parsing HTML content, likely used internally for scraping data from web pages.

### Functions

- **`parse_html(html_content)`**
  - **Description**: Parses the given HTML content.
  - **Parameters**:
    - `html_content` (str) - The HTML content to parse.
  - **Returns**: A parsed HTML object (e.g., BeautifulSoup object).

- **`extract_post_data(soup)`**
  - **Description**: Extracts post data from a parsed HTML soup object.
  - **Parameters**:
    - `soup` (BeautifulSoup) - The parsed HTML object.
  - **Returns**: A list of dictionaries, where each dictionary represents a post.

### Usage Example

```python
# This is an internal utility and direct usage might not be intended for end-users.
# Example assumes you have html_content and a soup object.
# from rule34Py import html
#
# html_content = "<html><body>...</body></html>"
# soup = html.parse_html(html_content)
# posts = html.extract_post_data(soup)
```
```

--------------------------------

### Set Captcha Clearance and User-Agent via Environment Variables

Source: https://b3yc0d3.github.io/rule34Py/guides/captcha-clearance.html

Set the `R34_CAPTCHA_CLEARANCE` and `R34_USER_AGENT` environment variables to provide captcha clearance and user-agent information to rule34Py. This method is suitable for scripts or applications where environment variables are preferred.

```bash
export R34_CAPTCHA_CLEARANCE=${token_value}
export R34_USER_AGENT=${user_agent}
# some script or commands that use rule34Py

```

--------------------------------

### Set Captcha Clearance and User-Agent in rule34Py

Source: https://b3yc0d3.github.io/rule34Py/guides/captcha-clearance.html

Configure the rule34Py client with your `cf_clearance` token and `User-Agent` directly within your Python script. This method is useful for programmatic control over the clearance process.

```python
import rule34Py as r34

client = r34.rule34Py()
client.cf_clearance =  # ${token_value}
client.user_agent =  # ${user_agent}

# Some code that uses the rule34Py client.

```

--------------------------------

### rule34Py.rule34.top_tags

Source: https://b3yc0d3.github.io/rule34Py/api/rule34Py/rule34.html

Retrieves a list of the top 100 global tags.

```APIDOC
## rule34Py.rule34.top_tags

### Description
Retrieve list of top 100 global tags.

### Method
top_tags

### Parameters
None

### Response
#### Success Response (list[TopTag])
A list of the current top 100 tags, globally.

#### Response Example
```json
[
  "anime",
  "girl",
  "solo"
]
```

### Raises
* **requests.HTTPError** – The backing HTTP GET operation failed.
```

--------------------------------

### Search Posts with Tags

Source: https://b3yc0d3.github.io/rule34Py/api/rule34Py/rule34.html

Iterate through search results for posts matching the given tags. The iteration continues until max_results is met or all results are exhausted. Deduplication is recommended if necessary.

```python
for post in client.iter_search(tags=['tag1', 'tag2'], max_results=100):
    # Process post
```

--------------------------------

### rule34Py.rule34.set_base_site_rate_limit

Source: https://b3yc0d3.github.io/rule34Py/api/rule34Py/rule34.html

Enables or disables the base site (rule34.xxx) API rate limiter.

```APIDOC
## rule34Py.rule34.set_base_site_rate_limit

### Description
Enables or disables the base site (rule34.xxx) API rate limiter.

### Method
set_base_site_rate_limit

### Parameters
* **enabled** (bool) - Whether to enable or disable the rate limiter.
```

--------------------------------

### icame

Source: https://b3yc0d3.github.io/rule34Py/api/rule34Py/rule34.html

Retrieve a list of the top 100 iCame objects.

```APIDOC
## icame

### Description
Retrieve a list of the top 100 iCame objects. This method uses the interactive website and is subject to rate limiting.

### Method
```
icame()
```

### Returns
- The current top 100 iCame objects.

### Raises
- requests.HTTPError: The backing HTTP GET operation failed.
```

--------------------------------

### rule34Py.pool

Source: https://b3yc0d3.github.io/rule34Py/api/rule34Py/rule34.html

Functions for interacting with post pools.

```APIDOC
## `pool` Module

### Description

- **Description**: This module provides functions to retrieve and manage posts within pools on Rule34.xxx.

### Functions

- **`get_pool_posts(pool_id, limit=SEARCH_RESULT_MAX, pid=0)`**
  - **Description**: Retrieves posts belonging to a specific pool.
  - **Parameters**:
    - `pool_id` (int) - The ID of the pool.
    - `limit` (int) - Optional - The maximum number of posts to retrieve. Defaults to `SEARCH_RESULT_MAX`.
    - `pid` (int) - Optional - The page number for pagination. Defaults to 0.
  - **Returns**: A list of post objects within the specified pool.

### Usage Example

```python
# from rule34Py import pool
#
# pool_posts = pool.get_pool_posts(112233, limit=20)
# for post in pool_posts:
#     print(f"Pool Post ID: {post['id']}")
```
```

--------------------------------

### Pool Class

Source: https://b3yc0d3.github.io/rule34Py/api/rule34Py/pool.html

Represents a collection of Rule34 Posts.

```APIDOC
## class rule34Py.pool.Pool

### Description
A collection of Rule34 Posts.

### Parameters
* **pool_id** (int) - The pool’s unique numeric ID.
* **name** (str) - The pool’s title.
* **description** (str) - A summary description of the pool’s contents.
* **posts** (list[int]) - A list of Post ID numbers that are members of the pool.

### Attributes
* **pool_id** (int) - The pool’s unique numeric ID.
* **name** (str) - The pool’s title.
* **description** (str) - A summary description of the pool’s contents.
* **posts** (list[int]) - A list of Post ID numbers that are members of the pool.
```

--------------------------------

### Define Search Tags

Source: https://b3yc0d3.github.io/rule34Py/tutorials/downloader.html

Specify the tags for searching posts. You can include positive tags, sorting options, and negative tags to exclude specific content like videos.

```python
client.user_id = "YOUR_USER_ID"

TAGS = ["neko", "sort:score", "-video"]
```

--------------------------------

### rule34Py.post

Source: https://b3yc0d3.github.io/rule34Py/api/rule34Py/rule34.html

Functions for retrieving details about a specific post.

```APIDOC
## `post` Module

### Description

- **Description**: This module allows fetching detailed information about a specific post using its ID.

### Function

- **`get_post(post_id)`**
  - **Description**: Retrieves detailed information for a single post.
  - **Parameters**:
    - `post_id` (int) - The ID of the post to retrieve.
  - **Returns**: A dictionary containing the detailed information of the post.

### Usage Example

```python
# from rule34Py import post
#
# post_details = post.get_post(1234567)
# print(f"Post Rating: {post_details['rating']}")
```
```

--------------------------------

### rule34Py.autocomplete_tag

Source: https://b3yc0d3.github.io/rule34Py/api/rule34Py/rule34.html

Functions for tag autocompletion.

```APIDOC
## `autocomplete_tag` Module

### Description

- **Description**: This module offers functionality to get tag suggestions based on a prefix.

### Function

- **`get_autocomplete_tags(tag_prefix)`**
  - **Description**: Provides tag suggestions that start with the given prefix.
  - **Parameters**:
    - `tag_prefix` (str) - The prefix to search for tag suggestions.
  - **Returns**: A list of tag strings that match the prefix.

### Usage Example

```python
# from rule34Py import autocomplete_tag
#
# suggestions = autocomplete_tag.get_autocomplete_tags("cat")
# print("Tag suggestions:", suggestions)
```
```

--------------------------------

### iter_search

Source: https://b3yc0d3.github.io/rule34Py/api/rule34Py/rule34.html

Iterate through Post search results, one element at a time.

```APIDOC
## iter_search

### Description
Iterate through Post search results, one element at a time. This method transparently requests additional results pages until either `max_results` is reached, or there are no more results. It is recommended to deduplicate results if that is important, as additional Posts may be added between page calls.

### Method
```
iter_search(_tags : list[str] = []_, _max_results : int | None = None_)
```

### Parameters
#### Path Parameters
- **tags** (list[str]) - Optional - A list of tags to search. If the tags list is empty, all posts will be returned.
- **max_results** (int | None) - Optional - The maximum number of results to return before ending the iteration. If None, iteration continues until the end of the results.

### Yields
- An iterator representing each Post element of the search results.

### Raises
- requests.HTTPError: The backing HTTP GET operation failed.
```

--------------------------------

### PoolHistoryPage Parsing

Source: https://b3yc0d3.github.io/rule34Py/api/rule34Py/html.html

Enables parsing of Rule34 Pool history pages to extract event entries.

```APIDOC
## PoolHistoryPage

### Description
A Rule34 Pool history page.

### Class
`rule34Py.html.PoolHistoryPage`

### Static Methods
* **events_from_html(html: str) -> list[PoolHistoryEvent]**

Parse the history event entries from the page html.

Parameters:
    
**html** (str) – The pool history page HTML to parse.

Returns:
    
A list of `PoolHistoryEvents` representing the changes in this Pool.
Return type:
    
list[_PoolHistoryEvent_]
```

--------------------------------

### rule34Py.toptag

Source: https://b3yc0d3.github.io/rule34Py/api/rule34Py/rule34.html

Functions for retrieving the most popular tags.

```APIDOC
## `toptag` Module

### Description

- **Description**: This module provides a function to get a list of the most popular tags on the site.

### Function

- **`get_top_tags(limit=SEARCH_RESULT_MAX)`**
  - **Description**: Retrieves a list of the most popular tags.
  - **Parameters**:
    - `limit` (int) - Optional - The maximum number of tags to retrieve. Defaults to `SEARCH_RESULT_MAX`.
  - **Returns**: A list of tag strings.

### Usage Example

```python
# from rule34Py import toptag
#
# top_tags = toptag.get_top_tags(limit=15)
# print("Top Tags:", top_tags)
```
```

--------------------------------

### ICamePage Parsing

Source: https://b3yc0d3.github.io/rule34Py/api/rule34Py/html.html

Provides functionality to parse the Rule34 'icame' page, extracting top results. It can be used as an object or a static class.

```APIDOC
## ICamePage

### Description
The Rule34 ‘icame’ page. Parses the useful information from the page’s html.

### Class
`rule34Py.html.ICamePage(html: str)`

### Parameters
* **html** (str) - The page HTML to parse.

### Attributes
* **top_chart** (list[ICame]) - The top icame results, in descending order.

## top_chart_from_html

### Description
Parse the ICame Top 100 chart from the page html.

### Method
`static rule34Py.html.top_chart_from_html(html: str) -> list[ICame]`

### Parameters
* **html** (str) - The ICame page HTML, as a string.

### Returns
A list of the top 100 ICame characters and their counts.
Return type: list[_ICame_]
```

--------------------------------

### rule34Py.api_urls

Source: https://b3yc0d3.github.io/rule34Py/api/rule34Py/rule34.html

Provides access to the API URLs used by the library.

```APIDOC
## `api_urls` Module

### Description

- **Description**: This module contains constants for the API endpoints used by rule34Py.

### Constants

- **`API_URL`** (str) - The base URL for the Rule34.xxx API.
- **`POST_COMMENTS_URL`** (str) - The URL for retrieving post comments.
- **`POST_URL`** (str) - The URL for retrieving post details.
- **`RULE34_URL`** (str) - The URL for searching posts on Rule34.xxx.
- **`TOPTAGE_URL`** (str) - The URL for retrieving top tags.
- **`AUTOCOMPLETE_TAG_URL`** (str) - The URL for tag autocompletion.
- **`ICAME_URL`** (str) - The URL for the 'i came' endpoint.
- **`POOL_URL`** (str) - The URL for pool-related operations.

### Usage Example

```python
from rule34Py import api_urls

print(f"Rule34 URL: {api_urls.RULE34_URL}")
```
```

--------------------------------

### Run Specific Unit Tests

Source: https://b3yc0d3.github.io/rule34Py/dev/developer-guide.html

Invokes a single test or a subset of tests by passing arguments to the PYTEST_ARGS variable. This is useful for targeted debugging.

```bash
PYTEST_ARGS="-k package" make check
```

--------------------------------

### rule34Py.rule34.tagmap

Source: https://b3yc0d3.github.io/rule34Py/api/rule34Py/rule34.html

Retrieves a list of the top 100 global tags. This method is deprecated and users should use `top_tags()` instead.

```APIDOC
## rule34Py.rule34.tagmap

### Description
Retrieve list of top 100 global tags. This method is deprecated in favor of the `top_tags()` method.

### Method
tagmap

### Parameters
None

### Response
#### Success Response (list[TopTag])
A list of the current top 100 tags, globally.

#### Response Example
```json
[
  "anime",
  "girl",
  "solo"
]
```

### Raises
* **requests.HTTPError** – The backing HTTP GET operation failed.

### Warns
* **This method is deprecated in favor of the top_tags() method.**
```

--------------------------------

### rule34Py.rule34.search

Source: https://b3yc0d3.github.io/rule34Py/api/rule34Py/rule34.html

Searches for posts on Rule34.xxx based on provided tags and filters. It allows exclusion of AI-generated content and pagination.

```APIDOC
## rule34Py.rule34.search

### Description
Search for posts with specified tags, optionally excluding AI-generated content. Supports pagination and limiting results per page.

### Method
search

### Parameters
#### Path Parameters
None

#### Query Parameters
* **tags** (list[str]) - A list of tags to search for.
* **exclude_ai** (bool) - Exclude AI generated content from the results. Default is False.
* **page_id** (int | None) - The search page number to request, or None. If None, search will eventually return all pages.
* **limit** (int) - The maximum number of post results to return per page. Defaults to `SEARCH_RESULT_MAX` (1000, by Rule34 policy).

### Request Example
```python
from rule34Py import rule34

posts = rule34.search(tags=['cat', 'girl'], exclude_ai=True, limit=50)
for post in posts:
    print(post.url)
```

### Response
#### Success Response (list[Post])
A list of Post objects, representing the search results.

#### Response Example
```json
[
  {
    "id": 12345,
    "tags": "cat girl",
    "url": "http://example.com/image.jpg",
    "preview_url": "http://example.com/preview.jpg",
    "width": 800,
    "height": 600
  }
]
```

### Raises
* **requests.HTTPError** – The backing HTTP GET operation failed.
* **ValueError** – An invalid `limit` value was requested.
```

--------------------------------

### PoolPage Parsing

Source: https://b3yc0d3.github.io/rule34Py/api/rule34Py/html.html

Provides functionality to parse Rule34 Pool pages and extract Pool information.

```APIDOC
## PoolPage

### Description
A Rule34 post Pool page.

### Class
`rule34Py.html.PoolPage`

### Static Methods
* **pool_from_html(html: str) -> Pool**

Generate a Pool object from the page HTML.

Parameters:
    
**html** (str) – The pool page HTML, as a string.

Returns:
    
A Pool object representing the parsed page information.
Return type:
    
_Pool_
```

--------------------------------

### TagMapPage Parsing

Source: https://b3yc0d3.github.io/rule34Py/api/rule34Py/html.html

Allows parsing of the rule34.xxx/static/tagmap.html page to extract map data.

```APIDOC
## TagMapPage

### Description
The rule34.xxx/static/tagmap.html page. Parses the useful information from the page’s html.

### Class
`rule34Py.html.TagMapPage(html: str)`

### Parameters
* **html** (str) - The Tag Map page HTML, as a string.

### Attributes
* **map_points** (dict[str, str]) - The most popular tag in each country or region code. Formatted as `[location_code, top_tag]`.

### Static Methods
* **map_points_from_html(html: str) -> dict[str, str]**

Parse the map data from a Tag Map Page.

Parameters:
    
**html** (str) – The Tag Map page HTML as a string.

Returns:
    
The map data as a dictionary of `[location_code, top_tag]`.
Return type:
    
dict[str, str]
```

--------------------------------

### AutocompleteTag Class

Source: https://b3yc0d3.github.io/rule34Py/api/rule34Py/autocomplete_tag.html

Represents a tag suggestion from autocomplete. The 'type' attribute is currently always None due to a change in the underlying API endpoint.

```APIDOC
## class rule34Py.autocomplete_tag.AutocompleteTag

### Description
Represents a tag suggestion from autocomplete.

### Parameters
- **label** (str) - The full tag label including count (e.g., “hooves (95430)”).
- **value** (str) - The clean tag value (e.g., “hooves”).
- **type** (str | None) - The tag category (e.g., “general”, “copyright”). Currently always None.

### Attributes
- **label** (str) - The full tag label including count (e.g., “hooves (95430)”).
- **value** (str) - The clean tag value without count information.
- **type** (str | None) - The category of the tag (general/copyright/other). Currently always None.
```

--------------------------------

### Post Object Properties

Source: https://b3yc0d3.github.io/rule34Py/api/rule34Py/post.html

Access various attributes of a Post object, such as its ID, score, URLs, tags, and content type.

```APIDOC
## Post Object Properties

### Properties
* **id** (_int_) - The unique numeric identifier of post.
* **hash** (_str_) - The unique rule34 hash of post.
* **score** (_int_) - Get the score of post.
* **size** (_list[int]_) - The Post’s graphical dimension size. Returns a list of the image’s graphical dimensions, as [width, height].
* **image** (_str_) - The Post’s full-resolution image URL.
* **preview** (_str_) - A URL to the Post’s preview image.
* **sample** (_str_) - The Post’s sample image URL.
* **owner** (_str_) - The Post’s creator username.
* **tags** (_list_) - The Post’s tags.
* **file_type** (_str_) - The Post’s image file type. One of ["image", "gif", "video"].
* **directory** (_int_) - The Post’s storage directory id.
* **change** (_int_) - The Post’s latest update time.
* **content_type** (_str_) - The Post’s content type. Represents the value of `file_type` from the JSON. Can be one of: `image`, `gif`, `video`.
* **rating** (_str_) - The Post’s content objectionability rating. Can be `e` (Explicit), `s` (Safe), or `q` (Questionable).
* **thumbnail** (_str_) - The Post’s thumbnail image URL.
* **video** (_str_) - The Post’s full-resolution video URL.
```

--------------------------------

### get_comments

Source: https://b3yc0d3.github.io/rule34Py/api/rule34Py/rule34.html

Retrieve the comments left on a post.

```APIDOC
## get_comments

### Description
Retrieve the comments left on a specific post. Note that due to a bug in the rule34 site API, the creation timestamp in returned comments may be inaccurate.

### Method
```
get_comments(_post_id : int_)
```

### Parameters
#### Path Parameters
- **post_id** (int) - Required - The Post's ID number.

### Returns
- List of PostComment objects. Returns an empty list if the post has no comments.

### Raises
- requests.HTTPError: The backing HTTP GET operation failed.
```

--------------------------------

### rule34Py.post_comment

Source: https://b3yc0d3.github.io/rule34Py/api/rule34Py/rule34.html

Functions for retrieving comments for a specific post.

```APIDOC
## `post_comment` Module

### Description

- **Description**: This module provides functionality to fetch comments associated with a particular post.

### Function

- **`get_post_comments(post_id, limit=SEARCH_RESULT_MAX, pid=0)`**
  - **Description**: Retrieves comments for a given post ID.
  - **Parameters**:
    - `post_id` (int) - The ID of the post for which to retrieve comments.
    - `limit` (int) - Optional - The maximum number of comments to retrieve. Defaults to `SEARCH_RESULT_MAX`.
    - `pid` (int) - Optional - The page number for pagination. Defaults to 0.
  - **Returns**: A list of comment objects.

### Usage Example

```python
# from rule34Py import post_comment
#
# comments = post_comment.get_post_comments(1234567, limit=5)
# for comment in comments:
#     print(f"Comment: {comment['comment']}")
```
```

--------------------------------

### rule34Py.rule34.tag_map

Source: https://b3yc0d3.github.io/rule34Py/api/rule34Py/rule34.html

Retrieves a mapping of country and district codes to their top tags. This method relies on the interactive website and is subject to rate limiting.

```APIDOC
## rule34Py.rule34.tag_map

### Description
Retrieve the tag map points. This method uses the interactive website and is rate-limited.

### Method
tag_map

### Parameters
None

### Response
#### Success Response (dict[str, str])
A mapping of country and district codes to their top tag. 3-letter keys are ISO-3 character country codes, 2-letter keys are US-state codes.

#### Response Example
```json
{
  "USA": "new york",
  "CAN": "toronto"
}
```

### Raises
* **requests.HTTPError** – The backing HTTP GET operation failed.
```

--------------------------------

### PostComment Class

Source: https://b3yc0d3.github.io/rule34Py/api/rule34Py/post_comment.html

Represents a comment on a Rule34 post. This class provides access to various attributes of the comment.

```APIDOC
## class rule34Py.post_comment.PostComment

### Description
A post comment.

### Parameters
* **id** (_int_) - The comment’s numeric ID on Rule34.
* **owner_id** (_int_) - The numeric ID of the comment author.
* **body** (_str_) - The comment’s body text.
* **post_id** (_int_) - The numeric ID of the attached post.
* **creation** (_str_) - The timestamp string of when the post was made.

### Properties
* **author_id** (_int_) - The comment author’s unique user ID.
* **body** (_str_) - The comment’s body text.
* **creation** (_str_) - Timestamp string of when the comment was created.
* **id** (_int_) - The comment’s unique numeric ID.
* **post_id** (_int_) - The numeric ID of the attached post.
```

--------------------------------

### TopTagsPage Parsing

Source: https://b3yc0d3.github.io/rule34Py/api/rule34Py/html.html

Provides functionality to parse the rule34.xxx/index.php?Page=toptags page and extract top tag rankings.

```APIDOC
## TopTagsPage

### Description
The rule34.xxx/index.php?Page=toptags page. Parses the useful information from the page’s html.

### Class
`rule34Py.html.TopTagsPage(html: str)`

### Parameters
* **html** (str) - The Top Tags page HTML, as a string.

### Attributes
* **top_tags** (list[TopTag]) - The top-tags ranking list on this page.

### Static Methods
* **top_tags_from_html(html: str) -> list[TopTag]**

Parse the “Top 100 tags, global” table from the page.

Parameters:
    
**html** (str) – The Top Tags page HTML, as a string.

Returns:
    
A list of TopTags representing the top 100 chart.
Return type:
    
list[_TopTag_]
```

--------------------------------

### ICame Class

Source: https://b3yc0d3.github.io/rule34Py/api/rule34Py/icame.html

Represents an entry on the Rule34.xxx iCame top 100 rankings. It stores the character's name and a count of how often people came on the character.

```APIDOC
## class ICame(_character_name : str, _count : int)

### Description
An iCame contestant. Represents an entry on the Rule34.xxx iCame top 100 rankings.

### Parameters
* **character_name** (str) - The name of the character.
* **count** (int) - A count of how often people came on the character.

### Properties
* **character_name** (str) - The name of the character.
* **count** (int) - A count of how often people came on the character.
* **tag_url** (str) - The character tag page URL.
```

--------------------------------

### PoolHistoryEvent Class

Source: https://b3yc0d3.github.io/rule34Py/api/rule34Py/pool.html

Represents a Rule34 Pool history record.

```APIDOC
## class rule34Py.pool.PoolHistoryEvent

### Description
A Rule34 Pool history record.

### Parameters
* **date** (datetime) - The datetime of the historical event.
* **updater_uname** (str) - The user name who initiated the event.
* **post_ids** (list[int]) - A list of the Pool posts that were affected by the event.

### Attributes
* **date** (datetime) - The datetime of the pool history event.
* **updater_uname** (str) - The user name who initiated the event.
* **post_ids** (list[int]) - A list of the Pool posts that were affected by the event.
```