### Quickstart Examples for rule34Py

Source: https://github.com/b3yc0d3/rule34py/blob/master/docs/index.md

Demonstrates various functionalities of the rule34Py client, including fetching comments, posts, searching by tags, and retrieving random posts. Ensure you set your API key and user ID before use.

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

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

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

```python
# Get top 100 icame.
client.icame()
```

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

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

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

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

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

### Install Dependencies and Build Project

Source: https://github.com/b3yc0d3/rule34py/blob/master/docs/dev/developer-guide.md

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 and Run Project Tests

Source: https://github.com/b3yc0d3/rule34py/blob/master/docs/dev/contributing.md

Install project dependencies if not already done, then execute the project's test suite using `make check`. Ensure all tests pass to confirm your changes do not introduce regressions.

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

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

### Install Rule34Py and Requests

Source: https://github.com/b3yc0d3/rule34py/blob/master/docs/tutorials/downloader.md

Install the necessary Python libraries using pip. This is the first step before using the rule34Py module.

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

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

### Install Dependencies and Lint Project Sources

Source: https://github.com/b3yc0d3/rule34py/blob/master/docs/dev/contributing.md

Install project dependencies if not already done, then run the project linter using `make lint`. This command utilizes `ruff` to check all project sources for style and potential errors.

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

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

### Install Dependencies and Run Tests

Source: https://github.com/b3yc0d3/rule34py/blob/master/tests/README.md

Install project dependencies using poetry and then run the pytest test suite. Ensure the PYTHONPATH is set to include the current directory.

```bash
poetry install
PYTHONPATH=. poetry run pytest tests/
```

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

### Install rule34Py using pip

Source: https://github.com/b3yc0d3/rule34py/blob/master/README.md

Install the rule34Py package from the Python Package Index using pip.

```bash
pip install rule34Py
```

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

### Get Project Version

Source: https://github.com/b3yc0d3/rule34py/blob/master/docs/guides/package-metadata.md

Retrieve the project's PEP440 compliant version using the importlib.metadata.version method.

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

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

### Initialize rule34Py Client and Get Post

Source: https://github.com/b3yc0d3/rule34py/blob/master/docs/api/rule34Py/rule34.md

Instantiate the Rule34Py client, set API credentials, and retrieve a specific post by its ID.

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

post = client.get_post(1234)
```

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

### Get Post API

Source: https://github.com/b3yc0d3/rule34py/blob/master/docs/api/rule34Py/api_urls.md

Fetches details for a specific post in JSON format from the rule34.xxx API.

```APIDOC
## GET_POST

### Description
The JSON Post endpoint.

### Endpoint
https://api.rule34.xxx/index.php?page=dapi&s=post&q=index&id={POST_ID}&json=1

### Parameters
#### Query Parameters
- **POST_ID** (integer) - Required - The ID of the post to retrieve.
- **json** (integer) - Required - Set to 1 to receive the response in JSON format.
```

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

### Get License Information

Source: https://github.com/b3yc0d3/rule34py/blob/master/docs/guides/package-metadata.md

Extract the package's SPDX license identifier by interrogating the 'License' field in the package metadata.

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

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

### Common Make Targets

Source: https://github.com/b3yc0d3/rule34py/blob/master/docs/dev/developer-guide.md

A list of common make targets for managing the rule34Py project, including installation, testing, and building artifacts.

```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 Tag Autocomplete Suggestions

Source: https://github.com/b3yc0d3/rule34py/blob/master/docs/api/rule34Py/rule34.md

Retrieve tag suggestions based on a partial input string. The results are ordered by popularity.

```python
suggestions = client.autocomplete(tag_string="blue")
```

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

### Define Search Tags

Source: https://github.com/b3yc0d3/rule34py/blob/master/docs/tutorials/downloader.md

Specify the tags to use for searching posts. This example excludes posts tagged 'video' and sorts results by score. You can use various tag syntaxes supported by the site.

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

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

### rule34Py.rule34.rule34Py.get_post

Source: https://github.com/b3yc0d3/rule34py/blob/master/docs/api/rule34Py/rule34.md

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

```APIDOC
## get_post(post_id: int)

### Description
Get a Post by its ID.

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

### Returns
[Post](post.md#rule34Py.post.Post) | None - 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 Top iCame Objects

Source: https://github.com/b3yc0d3/rule34py/blob/master/docs/api/rule34Py/rule34.md

Fetch a list of the top 100 iCame objects. This method also uses the interactive website and is rate-limited.

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

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

### Get Package Maintainer Information

Source: https://github.com/b3yc0d3/rule34py/blob/master/docs/guides/package-metadata.md

Extract the package's maintainer and maintainer email by querying the 'Maintainer' and 'Maintainer-email' fields.

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

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

### Get a Pool of Posts

Source: https://github.com/b3yc0d3/rule34py/blob/master/docs/api/rule34Py/rule34.md

Retrieve a specific pool of posts using its ID. Note that this method interacts with the website directly and is subject to rate limiting.

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

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

### Host Documentation Locally

Source: https://github.com/b3yc0d3/rule34py/blob/master/docs/dev/developer-guide.md

Serves the built documentation locally using Python's http.server module. Navigate to the build/html directory first.

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

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

### Build Project Documentation

Source: https://github.com/b3yc0d3/rule34py/blob/master/docs/dev/developer-guide.md

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

```bash
make html
```

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

### File Downloader Tutorial

Source: https://context7.com/b3yc0d3/rule34py/llms.txt

A tutorial demonstrating how to search for posts and download resulting image files.

```APIDOC
## File Downloader Tutorial

A complete example showing how to search for posts and download the resulting image files to disk.

```python
from pathlib import Path
import requests
from rule34Py import rule34Py

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

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

results = client.search(tags=TAGS, limit=DOWNLOAD_LIMIT)

for post in results:
    url = post.image
    if not url:
        print(f"  Skipping post {post.id}: no image URL (type={post.content_type})")
        continue
    filename = Path(url).name
    print(f"Downloading post {post.id} -> {filename}")
    try:
        resp = requests.get(url, timeout=30)
        resp.raise_for_status()
        with open(filename, "wb") as fp:
            fp.write(resp.content)
        print(f"  Saved {len(resp.content):,} bytes.")
    except requests.HTTPError as e:
        print(f"  Failed to download: {e}")

# Expected output (example):
# Downloading post 9876543 -> abc123def456.jpg
#   Saved 1,048,576 bytes.
# Downloading post 9876542 -> def456abc123.png
#   Saved 2,097,152 bytes.
```
```

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

### Initialize rule34Py Client and Make API Calls

Source: https://github.com/b3yc0d3/rule34py/blob/master/README.md

Demonstrates how to initialize the rule34Py client, set API credentials, and perform various API operations like fetching comments, posts, searching by tags, and retrieving random posts.

```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()
```

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

### rule34Py.rule34.rule34Py.random_post

Source: https://github.com/b3yc0d3/rule34py/blob/master/docs/api/rule34Py/rule34.md

Get a random post. This method behaves similarly to the website’s Post > Random function.

```APIDOC
## random_post()

### Description
Get a random post.

This method behaves similarly to the website’s Post > Random function.

### Returns
[Post](post.md#rule34Py.post.Post) - A random Post object.

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

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

### Initialize rule34Py Client with Authentication

Source: https://context7.com/b3yc0d3/rule34py/llms.txt

Create a rule34Py client instance and set your API credentials. API key and user ID are required for REST API requests. Credentials can also be set via environment variables.

```python
import rule34Py as r34

client = r34.rule34Py()
client.api_key = "abc123...128-char-key...xyz"  # 128-character hex string
client.user_id = "1234567"                       # 7-digit user ID

# Credentials can also be supplied via environment variables (set before running):
# export R34_CAPTCHA_CLEARANCE=<cf_clearance token>
# export R34_USER_AGENT=<your browser user-agent>
```

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

### random_post_id()

Source: https://github.com/b3yc0d3/rule34py/blob/master/docs/api/rule34Py/rule34.md

Gets a random Post ID by utilizing the website's 'random post' function and capturing the redirect.

```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 you use the “random post” function.

### NOTE
This method uses the interactive website and is rate-limited.

### Returns
A random post ID.

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

### Return type
int
```

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

### Get a Random Post

Source: https://github.com/b3yc0d3/rule34py/blob/master/docs/api/rule34Py/rule34.md

Retrieve a single random post, similar to the website's 'Post > Random' functionality.

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

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

### Post Class Initialization

Source: https://github.com/b3yc0d3/rule34py/blob/master/docs/api/rule34Py/post.md

Demonstrates how to initialize a Post object directly with its attributes.

```APIDOC
## Post(id: int, hash: str, score: int, size: list, image: str, preview: str, sample: str, owner: str, tags: list, file_type: str, directory: int, change: int)

A Rule34 Post object.

This class is mostly a pythonic representation of the Rule34.xxx JSON API post object.

* **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.
```

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

### Get Comments for a Post

Source: https://github.com/b3yc0d3/rule34py/blob/master/docs/api/rule34Py/rule34.md

Retrieve all comments associated with a specific post ID. If the post has no comments, an empty list is returned.

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

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

### Run Unit Tests

Source: https://github.com/b3yc0d3/rule34py/blob/master/docs/dev/developer-guide.md

Runs the project's unit tests using the 'check' make target. This requires the build environment to be set up.

```bash
make test
```

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

### Complete Rule34 Downloader Script

Source: https://github.com/b3yc0d3/rule34py/blob/master/docs/tutorials/downloader.md

This is the complete script combining client initialization, tag definition, search, and image downloading. It includes setting an API key and user ID.

```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)
```

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

### Initialize Rule34Py Client

Source: https://github.com/b3yc0d3/rule34py/blob/master/docs/tutorials/downloader.md

Import the rule34Py module and create a client instance to interact with the Rule34.xxx API. The client handles API endpoint communication and data marshalling.

```python
from rule34Py import rule34Py

client = rule34Py()
```

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

### Clone Repository

Source: https://github.com/b3yc0d3/rule34py/blob/master/docs/dev/developer-guide.md

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 Class from_json Method

Source: https://github.com/b3yc0d3/rule34py/blob/master/docs/api/rule34Py/post.md

Shows how to create a Post object by parsing a JSON string from the Rule34 API.

```APIDOC
## static from_json(json: str) -> Post

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

* **Parameters:**
  **json** (*str*) – The JSON string to parse.
* **Returns:**
  The rule34Py.Post representation of the object.
* **Return type:**
  [Post](#rule34Py.post.Post)
```

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

### Set Rule34Py API Credentials

Source: https://github.com/b3yc0d3/rule34py/blob/master/docs/guides/api-credentials.md

Configure your API key and user ID for the rule34Py client. 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"
```

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

### Get a Random Post or Post ID

Source: https://context7.com/b3yc0d3/rule34py/llms.txt

Retrieves a random post or just its ID, similar to the website's 'Random Post' button. Fetching only the ID is faster as it involves a single HTTP request. This function uses the interactive site and is rate-limited.

```python
from rule34Py import rule34Py

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

# Get just the random post ID (faster, only one HTTP request)
random_id = client.random_post_id()
print(f"Random post ID: {random_id}")

# Get the full Post object for a random post
random_post = client.random_post()
print(f"Random post:    {random_post.id} by {random_post.owner} ({random_post.content_type})")
print(f"Tags:           {random_post.tags[:5]}")
```

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

### Record Mock34 Responses

Source: https://github.com/b3yc0d3/rule34py/blob/master/tests/README.md

Enable response recording mode for the mock34 fixture by setting the R34_RECORD_RESPONSES environment variable to True. This will proxy requests to the live API and save responses for future use. Then, run the pytest suite.

```bash
export R34_RECORD_RESPONSES=True
# From the top level of the project ...
PYTHONPATH=. poetry run pytest tests/
```

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

### Download Image Files

Source: https://context7.com/b3yc0d3/rule34py/llms.txt

Searches for posts based on tags and downloads the resulting image files to disk. Handles potential errors during download and skips posts without image URLs.

```python
from pathlib import Path
import requests
from rule34Py import rule34Py

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

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

results = client.search(tags=TAGS, limit=DOWNLOAD_LIMIT)

for post in results:
    url = post.image
    if not url:
        print(f"  Skipping post {post.id}: no image URL (type={post.content_type})")
        continue
    filename = Path(url).name
    print(f"Downloading post {post.id} -> {filename}")
    try:
        resp = requests.get(url, timeout=30)
        resp.raise_for_status()
        with open(filename, "wb") as fp:
            fp.write(resp.content)
        print(f"  Saved {len(resp.content):,} bytes.")
    except requests.HTTPError as e:
        print(f"  Failed to download: {e}")
```

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

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

Source: https://github.com/b3yc0d3/rule34py/blob/master/docs/guides/captcha-clearance.md

Configure the rule34Py client with your obtained cf_clearance token and user-agent. This is necessary for workflows that interact with the rule34.xxx website directly, bypassing the REST API.

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

```

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

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

Source: https://github.com/b3yc0d3/rule34py/blob/master/docs/guides/captcha-clearance.md

Alternatively, set the R34_CAPTCHA_CLEARANCE and R34_USER_AGENT environment variables. The rule34Py module will automatically pick these up for its interactive site interactions.

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

```

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

### Download Rule34 Posts

Source: https://github.com/b3yc0d3/rule34py/blob/master/docs/tutorials/downloader.md

Search for posts using the defined tags and download a specified number of images. This code iterates through the search results, fetches image URLs, and saves the image content to local files.

```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)
```

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

### Retrieve Post by ID with rule34Py

Source: https://context7.com/b3yc0d3/rule34py/llms.txt

Fetch a single post's full metadata using its numeric Rule34 ID. Returns None if the post does not exist.

```python
from rule34Py import rule34Py

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

post = client.get_post(4153825)

if post is None:
    print("Post not found.")
else:
    print(f"Post ID:   {post.id}")
    print(f"Hash:      {post.hash}")
    print(f"Score:     {post.score}")
    print(f"Owner:     {post.owner}")
    print(f"Tags:      {post.tags}")
    print(f"Type:      {post.content_type}")
    if post.content_type == "video":
        print(f"Video URL: {post.video}")
    else:
        print(f"Image URL: {post.image}")

# Expected output (example):
# Post ID:   4153825
# Hash:      d41d8cd98f00b204e9800998ecf8427e
# Score:     87
# Owner:     artistname
# Tags:      ['solo', 'female', 'neko', ...]
# Type:      image
# Image URL: https://us.rule34.xxx/images/3456/d41d8c...jpg
```

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

### Iterate Through Search Results

Source: https://github.com/b3yc0d3/rule34py/blob/master/docs/api/rule34Py/rule34.md

Use the `iter_search` method to efficiently iterate through post search results, fetching additional pages as needed. This is useful for processing a large number of posts without loading them all into memory at once. Specify tags to filter results, or leave empty to retrieve all posts.

```python
for post in client.iter_search(tags=["cat", "_1girl"], max_results=100):
    print(post.id)
```

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

### rule34Py.autocomplete()

Source: https://context7.com/b3yc0d3/rule34py/llms.txt

Look up tag suggestions based on a partial string. Returns results ordered by popularity (descending). Useful for building tag-search UIs.

```APIDOC
## `rule34Py.autocomplete()` — Tag Autocomplete Suggestions

### Description
Look up tag suggestions based on a partial string. Returns results ordered by popularity (descending). Useful for building tag-search UIs.

### Parameters
- **partial_tag** (str) - Required - The partial tag string to get suggestions for.

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

client = rule34Py()
suggestions = client.autocomplete("neko")
```

### Response
#### Success Response
- **suggestions** (list) - A list of tag suggestion objects. Each object contains `value` and `label` attributes.

### Response Example
```json
[
  {
    "value": "neko",
    "label": "neko (1234567)"
  },
  {
    "value": "neko_ears",
    "label": "neko_ears (98765)"
  }
]
```
```

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

### rule34Py.get_post()

Source: https://context7.com/b3yc0d3/rule34py/llms.txt

Fetch a single post's full metadata using its numeric Rule34 ID. Returns None if the post does not exist.

```APIDOC
## rule34Py.get_post()

### Description
Fetch a single post's full metadata using its numeric Rule34 ID. Returns `None` if the post does not exist.

### Method
```python
client.get_post(post_id: int)
```

### Parameters
- **post_id** (int) - Required - The unique numeric ID of the post to retrieve.

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

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

post = client.get_post(4153825)

if post is None:
    print("Post not found.")
else:
    print(f"Post ID:   {post.id}")
    print(f"Hash:      {post.hash}")
    print(f"Score:     {post.score}")
    print(f"Owner:     {post.owner}")
    print(f"Tags:      {post.tags}")
    print(f"Type:      {post.content_type}")
    if post.content_type == "video":
        print(f"Video URL: {post.video}")
    else:
        print(f"Image URL: {post.image}")
```

### Response
#### Success Response
Returns a `Post` object with the full metadata for the specified ID, or `None` if the post is not found.

#### Response Example
```json
{
  "id": 4153825,
  "hash": "d41d8cd98f00b204e9800998ecf8427e",
  "score": 87,
  "owner": "artistname",
  "tags": ["solo", "female", "neko", ...],
  "content_type": "image",
  "image": "https://us.rule34.xxx/images/3456/d41d8c...jpg"
}
```
```

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

### rule34Py.search()

Source: https://context7.com/b3yc0d3/rule34py/llms.txt

Search for posts matching one or more tags. Returns up to 1000 results per page and supports pagination, AI-content exclusion, and result count limiting.

```APIDOC
## rule34Py.search()

### Description
Search for posts matching one or more tags. Returns up to 1000 results per page. Supports pagination, AI-content exclusion, and result count limiting.

### Method
```python
client.search(
    tags: list[str],
    exclude_ai: bool = False,
    page_id: int = 0,
    limit: int = 100
)
```

### Parameters
- **tags** (list[str]) - Required - A list of tags to search for. Can include sorting and exclusion modifiers.
- **exclude_ai** (bool) - Optional - If True, excludes posts tagged as AI-generated.
- **page_id** (int) - Optional - The page number to retrieve (0-indexed).
- **limit** (int) - Optional - The maximum number of results to return per page (default 100, max 1000).

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

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

posts = client.search(
    tags=["neko", "sort:score", "-video"],
    exclude_ai=True,
    page_id=0,
    limit=50,
)

for post in posts:
    print(f"ID: {post.id}")
    print(f"  Owner:    {post.owner}")
    print(f"  Score:    {post.score}")
    print(f"  Size:     {post.size[0]}x{post.size[1]}")
    print(f"  Type:     {post.content_type}")
    print(f"  Tags:     {post.tags[:5]}")
    print(f"  Image:    {post.image}")
    print(f"  Thumb:    {post.thumbnail}")
    print(f"  Sample:   {post.sample}")
```

### Response
#### Success Response
Returns a list of `Post` objects matching the search criteria.

#### Response Example
```json
[
  {
    "id": 9876543,
    "owner": "someuser",
    "score": 142,
    "size": [2048, 1536],
    "content_type": "image",
    "tags": ["neko", "solo", "female", "highres", "long_hair"],
    "image": "https://us.rule34.xxx/images/1234/abc123.jpg",
    "thumbnail": "https://us.rule34.xxx/thumbnails/1234/thumbnail_abc123.jpg",
    "sample": "https://us.rule34.xxx/samples/1234/sample_abc123.jpg"
  }
]
```
```

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

### top_tags()

Source: https://github.com/b3yc0d3/rule34py/blob/master/docs/api/rule34Py/rule34.md

Retrieves a list of the top 100 global tags.

```APIDOC
## top_tags() → list[[TopTag](toptag.md#rule34Py.toptag.TopTag)]

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

### Returns
A list of the current top 100 tags, globally.

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

### Return type
list[[*TopTag*](toptag.md#rule34Py.toptag.TopTag)]
```

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

### Post Object Properties

Source: https://github.com/b3yc0d3/rule34py/blob/master/docs/api/rule34Py/post.md

Details the available properties for accessing information about a Post object.

```APIDOC
#### *property* change *: int*

The Post’s latest update time.

* **Returns:**
  An int representing the UNIX timestamp of the Post’s latest update/change.

#### *property* content_type *: str*

The Post’s content type.

Represents the value of `file_type` from the JSON.

* **Returns:**
  A string indicating the Post’s content type.
  : - `image`: A static image.
    - `gif`: An animated image (gif, webm, or other format).
    - `video`: A video file.

#### *property* directory *: int*

The Post’s storage directory id.

* **Returns:**
  A numeric representation of the Post’s storage directory.

#### *property* hash *: str*

The unique rule34 hash of post.

* **Returns:**
  The hash associated with the post.

#### *property* id *: int*

The unique numeric identifier of post.

* **Returns:**
  The unique numeric identifier associated with the post.

#### *property* image *: str*

The Post’s full-resolution image URL.

* **Returns:**
  A string URL to the full-resolution image of the Post.

#### *property* owner *: str*

The Post’s creator username.

* **Returns:**
  The string username of the Post creator.

#### *property* rating *: str*

The Post’s content objectionability rating.

* **Returns:**
  A string representing the post’s rating.
  : - `e` = Explicit
    - `s` = Safe
    - `q` = Questionable

#### *property* sample *: str*

The Post’s sample image URL.

* **Returns:**
  A string URL to the sample image.

#### *property* score *: int*

Get the score of post.

* **Returns:**
  The post’s score.

#### *property* size *: list[int]*

The Post’s graphical dimension size.

* **Returns:**
  A list of the image’s graphical dimensions, as [width, height].

#### *property* tags *: list*

The Post’s tags.

* **Returns:**
  A List of the Post’s tags.

#### *property* thumbnail *: str*

The Post’s thumbnail image URL.

* **Returns:**
  A string URL to the Post’s thumbnail image.

#### *property* video *: str*

The Post’s full-resolution video URL.

* **Returns:**
  A string URL to the full-resolution video URL.
```

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

### rule34Py.rule34.rule34Py.autocomplete

Source: https://github.com/b3yc0d3/rule34py/blob/master/docs/api/rule34Py/rule34.md

Retrieve tag suggestions based on partial input. This method is useful for providing auto-completion in search interfaces.

```APIDOC
## autocomplete(tag_string: str)

### Description
Retrieve tag suggestions based on partial input.

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

### Returns
list[[AutocompleteTag](autocomplete_tag.md#rule34Py.autocomplete_tag.AutocompleteTag)] - A list of AutocompleteTag objects matching the search query, ordered by popularity (descending).

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

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

### set_base_site_rate_limit(enabled)

Source: https://github.com/b3yc0d3/rule34py/blob/master/docs/api/rule34Py/rule34.md

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

```APIDOC
## set_base_site_rate_limit(enabled: bool)

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

### Parameters
* **enabled** (*bool*)
```

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

### Configure Captcha Clearance

Source: https://context7.com/b3yc0d3/rule34py/llms.txt

Sets Cloudflare captcha clearance tokens and User-Agent for accessing the interactive PHP site. Can be configured via instance attributes or environment variables.

```python
import rule34Py as r34

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

# Set clearance after completing captcha in your browser:
client.captcha_clearance = "your_cf_clearance_token_here"  # ~450 chars
client.user_agent = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"

# Or configure via environment variables before launching Python:
# export R34_CAPTCHA_CLEARANCE="your_cf_clearance_token"
# export R34_USER_AGENT="Mozilla/5.0 ..."

# Now interactive-site methods (icame, get_pool, random_post, top_tags) will work:
pool = client.get_pool(28)
print(pool.name)

# Disable the 1-req/sec rate limiter on the base site (not recommended):
client.set_base_site_rate_limit(False)
```

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

### Tag Autocomplete Suggestions

Source: https://context7.com/b3yc0d3/rule34py/llms.txt

Provides tag suggestions based on a partial string input. Results are ordered by popularity in descending order, making it useful for building tag-search user interfaces. Ensure your API key and user ID are set.

```python
from rule34Py import rule34Py

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

suggestions = client.autocomplete("neko")

for tag in suggestions[:5]:
    print(f"Value: {tag.value:30s}  Label: {tag.label}")
```

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

### User Profile API

Source: https://github.com/b3yc0d3/rule34py/blob/master/docs/api/rule34Py/api_urls.md

Fetches an HTML page of a user's profile from rule34.xxx.

```APIDOC
## USER_PAGE

### Description
An HTML User profile URL.

### Endpoint
https://api.rule34.xxx/index.php?page=account&s=profile&id={USER_ID}

### Parameters
#### Query Parameters
- **USER_ID** (integer) - Required - The ID of the user whose profile to view.
```

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

### Pool Page

Source: https://github.com/b3yc0d3/rule34py/blob/master/docs/api/rule34Py/api_urls.md

Retrieves an HTML page displaying a specific pool from rule34.xxx.

```APIDOC
## POOL

### Description
An HTML Pool URL.

### Endpoint
https://rule34.xxx/index.php?page=pool&s=show&id={POOL_ID}

### Parameters
#### Query Parameters
- **POOL_ID** (integer) - Required - The ID of the pool to view.
```

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

### Paginated Search Iterator with rule34Py

Source: https://context7.com/b3yc0d3/rule34py/llms.txt

Iterate over all search results across multiple pages without manual pagination. Useful for processing large result sets or bulk downloads.

```python
from rule34Py import rule34Py

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

# Iterate over the first 2500 posts tagged "dragon", across multiple pages
count = 0
for post in client.iter_search(tags=["dragon"], max_results=2500):
    print(f"[{count+1}] Post {post.id}: {post.content_type} by {post.owner}")
    count += 1

# Without max_results, iterates until all results are exhausted:
# for post in client.iter_search(tags=["dragon"]):
#     ...

```

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

### Autocomplete API

Source: https://github.com/b3yc0d3/rule34py/blob/master/docs/api/rule34Py/api_urls.md

Provides tag autocompletion suggestions for the rule34.xxx website.

```APIDOC
## AUTOCOMPLETE

### Description
The tags autocomplete URL for rule34.xxx.

### Endpoint
https://api.rule34.xxx/autocomplete.php?q={q}

### Parameters
#### Query Parameters
- **q** (string) - Required - The query string for tag autocompletion.
```

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

### tagmap()

Source: https://github.com/b3yc0d3/rule34py/blob/master/docs/api/rule34Py/rule34.md

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

```APIDOC
## tagmap() → list[[TopTag](toptag.md#rule34Py.toptag.TopTag)]

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

### WARNING
This method is deprecated.

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

### Returns
A list of the current top 100 tags, globally.

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

### Return type
list[[*TopTag*](toptag.md#rule34Py.toptag.TopTag)]
```

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

### rule34Py.top_tags()

Source: https://context7.com/b3yc0d3/rule34py/llms.txt

Retrieve the current top-100 most-used tags globally on rule34.xxx, including each tag's rank and share of all posts.

```APIDOC
## `rule34Py.top_tags()` — Top 100 Global Tags

### Description
Retrieve the current top-100 most-used tags globally on rule34.xxx, including each tag's rank and share of all posts.

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

client = rule34Py()
top = client.top_tags()
```

### Response
#### Success Response
- **top_tags** (list) - A list of tag objects. Each object contains `rank`, `tagname`, and `percentage` attributes.

### Response Example
```json
[
  {
    "rank": 1,
    "tagname": "female",
    "percentage": "18%"
  },
  {
    "rank": 2,
    "tagname": "solo",
    "percentage": "14%"
  }
]
```
```

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

### rule34Py.rule34.rule34Py.icame

Source: https://github.com/b3yc0d3/rule34py/blob/master/docs/api/rule34Py/rule34.md

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

```APIDOC
## icame()

### Description
Retrieve a list of the top 100 iCame objects.

### NOTE
This method uses the interactive website and is rate-limited.

### Returns
list[[ICame](icame.md#rule34Py.icame.ICame)] - The current top 100 iCame objects.

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

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

### ICAME Page

Source: https://github.com/b3yc0d3/rule34py/blob/master/docs/api/rule34Py/api_urls.md

Provides a link to the HTML ICAME page on rule34.xxx.

```APIDOC
## ICAME

### Description
The HTML ICAME page URL.

### Endpoint
https://rule34.xxx/index.php?page=icame
```

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

### rule34Py.rule34.rule34Py.get_pool

Source: https://github.com/b3yc0d3/rule34py/blob/master/docs/api/rule34Py/rule34.md

Retrieve a pool of Posts by its ID. Note that this method uses the interactive website and is subject to rate limiting.

```APIDOC
## get_pool(pool_id: int)

### Description
Retrieve a pool of Posts.

### NOTE
This method uses the interactive website and is rate-limited.

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

### Returns
[Pool](pool.md#rule34Py.pool.Pool) - A Pool object representing the requested pool.

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

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

### Retrieve a Pool of Posts

Source: https://context7.com/b3yc0d3/rule34py/llms.txt

Fetches a curated collection of posts by its numeric pool ID. This function uses the interactive site and is subject to a rate limit of 1 request per second. Ensure your API key and user ID are set.

```python
from rule34Py import rule34Py

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

pool = client.get_pool(28)

print(f"Pool ID:     {pool.pool_id}")
print(f"Name:        {pool.name}")
print(f"Description: {pool.description}")
print(f"Posts ({len(pool.posts)} total): {pool.posts[:10]}")  # first 10 IDs
```

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

### search(tags, exclude_ai, page_id, limit)

Source: https://github.com/b3yc0d3/rule34py/blob/master/docs/api/rule34Py/rule34.md

Searches for posts based on provided tags and filters. Supports pagination and excluding AI-generated content.

```APIDOC
## search(tags: list[str] = [], exclude_ai: bool = False, page_id: int | None = None, limit: int = 1000)

### Description
Search for posts.

### 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).

### Returns
A list of Post objects, representing the search results.

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

### Return type
list[[*Post*](post.md#rule34Py.post.Post)]
```

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

### AutocompleteTag Class

Source: https://github.com/b3yc0d3/rule34py/blob/master/docs/api/rule34Py/autocomplete_tag.md

Represents a tag suggestion from autocomplete. The 'type' parameter is currently always None due to an API change.

```APIDOC
## class rule34Py.autocomplete_tag.AutocompleteTag(label: str, value: str, type: str | None)

### 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”).

### IMPORTANT
Due to switching from the website endpoint to the REST API endpoint, the `type` is currently always **None**.

### Attributes
#### label *: str*

The full tag label including count (e.g., “hooves (95430)”).

#### type *: str | None*

The category of the tag (general/copyright/other).

#### value *: str*

The clean tag value without count information.
```

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

### Search Posts by Tag with rule34Py

Source: https://context7.com/b3yc0d3/rule34py/llms.txt

Search for posts matching specified tags, with options for sorting, excluding content types, and limiting results. This method returns up to 1000 results per page.

```python
from rule34Py import rule34Py

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

# Search for posts tagged "neko", sorted by score, excluding videos and AI content
posts = client.search(
    tags=["neko", "sort:score", "-video"],
    exclude_ai=True,
    page_id=0,
    limit=50,
)

for post in posts:
    print(f"ID: {post.id}")
    print(f"  Owner:    {post.owner}")
    print(f"  Score:    {post.score}")
    print(f"  Size:     {post.size[0]}x{post.size[1]}")
    print(f"  Type:     {post.content_type}")   # "image", "gif", or "video"
    print(f"  Tags:     {post.tags[:5]}")        # first 5 tags
    print(f"  Image:    {post.image}")
    print(f"  Thumb:    {post.thumbnail}")
    print(f"  Sample:   {post.sample}")

# Expected output (example):
# ID: 9876543
#   Owner:    someuser
#   Score:    142
#   Size:     2048x1536
#   Type:     image
#   Tags:     ['neko', 'solo', 'female', 'highres', 'long_hair']
#   Image:    https://us.rule34.xxx/images/1234/abc123.jpg
#   Thumb:    https://us.rule34.xxx/thumbnails/1234/thumbnail_abc123.jpg
#   Sample:   https://us.rule34.xxx/samples/1234/sample_abc123.jpg
```

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

### Captcha Clearance Configuration

Source: https://context7.com/b3yc0d3/rule34py/llms.txt

Configure Cloudflare captcha clearance for accessing the interactive PHP site.

```APIDOC
## Captcha Clearance Configuration

For methods that access the interactive PHP site, Cloudflare captcha defenses may require manual clearance. Pass the `cf_clearance` cookie and matching `User-Agent` from your browser to the client.

```python
import rule34Py as r34

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

# Set clearance after completing captcha in your browser:
client.captcha_clearance = "your_cf_clearance_token_here"  # ~450 chars
client.user_agent = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"

# Or configure via environment variables before launching Python:
# export R34_CAPTCHA_CLEARANCE="your_cf_clearance_token"
# export R34_USER_AGENT="Mozilla/5.0 ..."

# Now interactive-site methods (icame, get_pool, random_post, top_tags) will work:
pool = client.get_pool(28)
print(pool.name)

# Disable the 1-req/sec rate limiter on the base site (not recommended):
client.set_base_site_rate_limit(False)
```
```