<h1 align="center"> Waifu-Python </h1>
<div align="center">
A project born out of boredom, designed to simplify and reduce the code related to the [Waifu API](https://github.com/MisfiT2020/Waifu-Python/tree/main#api-included)
</div>
<div align="center">
<a href="https://t.me/ShogunUpdates">
<img src="https://img.shields.io/badge/Telegram-2CA5E0?style=for-the-badge&logo=telegram&logoColor=white" alt="Telegram Badge"/>
</a>
</div>
## Installation
Use the package manager [pip](https://pypi.org/project/waifu-python/) to install **waifu-python**.
```bash
pip install waifu-python
```
## CLI Usage
After installing waifu-python, you can interact with it directly from your terminal. Output for a quick reference:
```bash
╰─ ❯❯ waifu-python
usage: waifu-python [-h] [--limit LIMIT] [--nsfw | --sfw] [--tags] [--list] [api] [query]
Waifu-Python API client
Required Arguments:
api API name
query Search query (tag) if any
options:
-h, --help show this help message and exit
--limit LIMIT Number of images to retrieve
--nsfw Fetch in NSFW mode
--sfw Fetch in SFW mode
--tags Retrieve available tags for the specified API
--list List all available API names with SFW/NSFW availability
```
### Examples
- Fetches available Apis
```bash
waifu-python --list
```
- Fetch a random SFW image from a specific API:
```bash
waifu-python danbooru
```
- Fetch a NSFW image with a specific tag:
```bash
waifu-python konachan "raiden shogun" --nsfw
```
- Retrieve available tags for a given API:
```bash
waifu-python waifuim --tags
```
- Fetch random images with Limits:
```bash
waifu-python random --limit 3
```
- Usage with multiple options:
```bash
waifu-python kemono "raiden shogun" --nsfw --limit 3
```
## Features
- **Flexible Search Input:**
Search queries no longer require underscores or hyphens between words, making it easier to find characters and tags.
For example, searching for `"Raiden Shogun"` will work the same as `"Raiden_Shogun"` or `"Raiden-Shogun"`
- **Character Search:**
Search for characters by name to get targeted results.
- **Tag Retrieval:**
Retrieve available tags from supported [API](https://github.com/MisfiT2020/Waifu-Python/tree/main?tab=readme-ov-file#api-included) to help refine and filter your searches.
- **Random Image Fetching:**
Easily retrieve random images across multiple supported APIs.
- **API-Specific Image Retrieval:**
Fetch random images from a specific API (e.g., **Danbooru, Waifu.im, Waifu.pics, etc.**) based on your preference.
- **CLI Support:**
Use `waifu-python` from the command line for quick access to images and tags.
- **Pixiv Tokens:**
Add support for [Pixiv tokens](https://github.com/MisfiT2020/Waifu-Python/tree/main?tab=readme-ov-file#pixiv-example) with an Auto-refresh Token—no need for manual access token
## API Included
| API | WORKING | TAGS |
| --------------------------------------- | ------- | ---- |
| [AiBooru](https://aibooru.online/) | ✓ | - |
| [Anilist](https://anilist.co/) | ✓ | - |
| [Danborru](https://danbooru.donmai.us/) | ✓ | - |
| [Gelbooru](https://gelbooru.com/) | ✓ | - |
| [Hijiribe](https://hijiribe.donmai.us/) | ✓ | - |
| [Iwara](https://www.iwara.tv/) | ✓ | - |
| [KemonoParty](https://kemono.su/) | ✓ | - |
| [Konachan](https://konachan.net/) | ✓ | - |
| [Nekos.best](https://nekos.best/) | ✓ | ✓ |
| [N-sfw.com](https://n-sfw.com/) | ✓ | ✓ |
| [Pic.re](https://pic.re/) | ✓ | ✓ |
| [Pixiv](https://pixiv.net/) | ✓ | - |
| [Purrbot.site](https://purrbot.site/) | ✓ | - |
| [Rule34](https://rule34.xxx/) | ✓ | - |
| [Safeborru](https://safebooru.org/) | ✓ | - |
| [Sankaku](https://sankaku.app/) | ✓ | - |
| [Tbib](https://tbib.org/) | ✓ | - |
| [Waifu.im](https://www.waifu.im/) | ✓ | ✓ |
| [Waifu.pics](https://waifu.pics/) | ✓ | ✓ |
| [Zerochan](https://www.zerochan.net/) | ✓ | - |
🔹 `Hijiribe` as `hiji` in cli
## Usage Example
```python
import asyncio
from waifu_python import WaifuIm
async def main():
image_data1 = await WaifuIm.fetch_sfw_images()
#Support for tags in Parameters
image_data2 = await WaifuIm.fetch_sfw_images('raiden shogun')
#Retrive tags for the API
tags = await WaifuIm.get_tags()
print(f"Random Image: {image_data1}\n\nRaiden Shogun: {image_data2}\n\nTags{tags}")
asyncio.run(main())
```
## Environment Variables
Create a .env file in your project root and include your Pixiv refresh token:
```python
IWARA_EMAIL=<mail>
IWARA_PASSWORD=<password>
PIXIV_REFRESH_TOKEN=<refresh token>
```
🔹 or Export the variables
## Pixiv Example
```python
from waifu_python import Pixiv
import asyncio
async def main():
tag_search = await Pixiv.fetch_images("raiden shogun") #parameters: download=Bool, max_pages=int #fetches the tag
illust_related = await Pixiv.fetch_images(127318308) #int = pixiv image related
illust_recommended = await Pixiv.fetch_images() #fetches recommended images from pixiv
print(tag_search)
print(illust_related)
print(illust_recommended)
asyncio.run(main())
```
> To get `refresh_token`, see
> [@ZipFile Pixiv OAuth Flow](https://gist.github.com/ZipFile/c9ebedb224406f4f11845ab700124362)
> / [gppt: get-pixivpy-token](https://github.com/eggplants/get-pixivpy-token)
> (Easy to use 👍 base on selenium) /
> [OAuth with Selenium/ChromeDriver](https://gist.github.com/upbit/6edda27cb1644e94183291109b8a5fde)
🔹 Or use command `waifu-python pixiv --login` or `waifu-python pixiv --refresh <old refresh code>`
## **Required Class Functions**
Each module in this library must implement the following functions:
| Function Name | APIs Used | Description |
|----------------------|-----------| ------------|
| `fetch_images` | `Danbooru`, `Pixiv`, `Yandere`, `Gelbooru`, `Rule34` | Fetches both SFW and NSFW images |
| `fetch_sfw_images` | `WaifuIm`, `WaifuPics`, `Safebooru`, `NekosBest`, `NSFWBot`, `PurrBot`, `PicRe`, `Konachan`, `Zerochan`, `Sankaku`, `Tbib`, `Hijiribe`, `Aibooru` | Fetches only SFW images |
| `fetch_nsfw_images` | `WaifuIm`, `WaifuPics`, `Konachan`, `NSFWBot`, `KemonoParty`, `Sankaku`, `Tbib`, `Hijiribe`, `Aibooru` | Fetches only NSFW images |
| `fetch_sfw_gif` | `PurrBot` | Fetches SFW GIFs |
| `fetch_nsfw_gif` | `PurrBot` | Fetches NSFW GIFs |
| `get_tags` | `WaifuIm`, `NekosBest`, `WaifuPics`, `PicRe`, `NSFWBot`, `PurrBot` | Fetches Tags from API |
| `iwara_fetch` & `fetch_random` | `Iwara` | <i>Fetches Url (no search parameter)<i> & <i>fetches random url data</i> |
## Example 1: Fetching Images from Multiple APIs
```python
import asyncio
from waifu_python import *
async def main():
# ----- SFW Images -----
sfw_images = {
"WaifuIm": await WaifuIm.fetch_sfw_images(),
"NekosBest": await NekosBest.fetch_sfw_images(),
"WaifuPics": await WaifuPics.fetch_sfw_images(),
"PicRe": await PicRe.fetch_sfw_images(),
"NSFWBot": await NSFWBot.fetch_sfw_images(),
"PurrBot": await PurrBot.fetch_sfw_images(),
"SafeBooru": await Safebooru.fetch_images(),
"Konachan": await Konachan.fetch_sfw_images(),
"Zerochan": await Zerochan.fetch_sfw_images(),
"Sankaku": await Sankaku.fetch_sfw_images(),
"Tbib": await Tbib.fetch_sfw_images(),
"Hijiribe": await Hijiribe.fetch_sfw_images(),
"Aibooru": await Aibooru.fetch_sfw_images()
}
# ----- NSFW Images/GIFs -----
nsfw_images = {
"WaifuIm": await WaifuIm.fetch_nsfw_images(),
"WaifuPics": await WaifuPics.fetch_nsfw_images(),
"NSFWBot": await NSFWBot.fetch_nsfw_images(),
"Pixiv": await Pixiv.fetch_images(),
"PurrBot GIF": await PurrBot.fetch_nsfw_gif(),
"Danbooru": await Danbooru.fetch_images(),
"Yandere": await Yandere.fetch_images(),
"Rule34": await Rule34.fetch_images(),
"KemonoParty": await KemonoParty.fetch_nsfw_images()
"Sankaku": await Sankaku.fetch_nsfw_images(),
"Tbib": await Tbib.fetch_nsfw_images(),
"Hijiribe": await Hijiribe.fetch_nsfw_images(),
"Pixiv": await Pixiv.fetch_nsfw_images(),
"Aibooru": await Aibooru.fetch_nsfw_images()
}
# ----- Tags -----
tags = {
"WaifuIm": await WaifuIm.get_tags(),
"NekosBest": await NekosBest.get_tags(),
"WaifuPics": await WaifuPics.get_tags(),
"PicRe": await PicRe.get_tags(),
"NSFWBot": await NSFWBot.get_tags(),
"PurrBot": await PurrBot.get_tags()
}
# Display results
print("----- SFW Images -----")
for key, value in sfw_images.items():
print(f"{key}: {value}")
print("\n----- NSFW Images/GIFs -----")
for key, value in nsfw_images.items():
print(f"{key}: {value}")
#------Tags Are Overwhelming------
# print("\n----- Tags -----")
# for key, value in tags.items():
# print(f"{key}: {value}")
asyncio.run(main())
```
## Example 2: Fetching Random Images
```python
import asyncio
from waifu_python import RandomWaifu
async def main():
random_img = await RandomWaifu.get_random_image()
sfw_img = await RandomWaifu.get_random_sfw_image()
nsfw_img = await RandomWaifu.get_random_nsfw_image()
sfw_gif = await RandomWaifu.get_random_sfw_gif()
nsfw_gif = await RandomWaifu.get_random_nsfw_gif()
print("Random Image:", random_img)
print("SFW Image:", sfw_img)
print("NSFW Image:", nsfw_img)
print("SFW GIF:", sfw_gif)
print("NSFW GIF:", nsfw_gif)
if __name__ == "__main__":
asyncio.run(main())
```
### Available Methods for Random Image Fetching
| Function | Description |
|----------|-------------|
| `get_random_image()` | Returns a completely random image (SFW or NSFW). |
| `get_random_sfw_image()` | Returns a random SFW image. |
| `get_random_nsfw_image()` | Returns a random NSFW image. |
| `get_random_sfw_gif()` | Returns a random SFW GIF. |
| `get_random_nsfw_gif()` | Returns a random NSFW GIF. |
## Example 3: Anilist Waifus/Characters
```python
import asyncio
from waifu_python import Anilist
async def main():
waifus = await Anilist.fetch_waifus('Mahiru Shiina')
characters = await Anilist.fetch_characters("eren yeager")
anime = await Anilist.search_anime("kimi no na wa")
print(waifus)
print(characters)
print(anime)
if __name__ == "__main__":
asyncio.run(main())
```
### Available Methods:
| Function | Description | Search Parameter | Returned Fields |
|----------|-------------|------------------| --------------- |
| `fetch_waifus("characterName")` | Fetches waifus only (female characters). | Optional | `name`, `anime`, `image`, `age`, `gender`, `description` |
| `fetch_characters(characterName)` | Fetches all characters (male & female). | Optional | `name`, `anime`, `image`, `age`, `gender`, `description` |
##
🔹 If `character` is not provided, it will return random characters.
## Example 4: Using Waifu API in a Telegram Bot
```python
from pyrogram import Client, filters
from waifu_python import AniList, SafeBooru, Danbooru
app = Client("Raiden", api_id="YOUR_API_ID", api_hash="YOUR_API_HASH", bot_token="YOUR_BOT_TOKEN")
@app.on_message(filters.command("sfw"))
async def send_sfw_image(client, message):
# Use SafeBooru to fetch a random SFW image.
args = message.text.split()
tag = args[1] if len(args) > 1 else None
try:
image_url = await SafeBooru.get_random_image(tag)
if image_url:
await message.reply_photo(image_url)
else:
await message.reply("No SFW image found.")
except Exception as e:
await message.reply(f"Error: {e}")
@app.on_message(filters.command("nsfw"))
async def send_nsfw_image(client, message):
# Use Danbooru to fetch a random NSFW image.
args = message.text.split()
tag = args[1] if len(args) > 1 else None
try:
image_url = await Danbooru.get_random_image(tag)
if image_url:
await message.reply_photo(image_url)
else:
await message.reply("No NSFW image found.")
except Exception as e:
await message.reply(f"Error: {e}")
# --------------------------------- Anilist ----------------------------------
@app.on_message(filters.command("waifu"))
async def send_waifu_image(client, message):
# Fetch a random waifu (female character) from Anilist.
args = message.text.split(maxsplit=1)
search = args[1] if len(args) > 1 else None
try:
waifus = await AniList.fetch_waifus(count=1, search=search)
if not waifus:
await message.reply("No waifus found.")
return
waifu = waifus[0]
description = (waifu['description'][:500] + "..."
if len(waifu['description']) > 500
else waifu['description'])
caption = (
f"**Name:** {waifu['name']}\n"
f"**Anime:** {waifu['anime']}\n"
f"**Age:** {waifu['age']}\n"
f"**Gender:** {waifu['gender']}\n\n"
f"{description}"
)
await message.reply_photo(waifu['image'], caption=caption)
except Exception as e:
await message.reply(f"Error: {e}")
@app.on_message(filters.command("character"))
async def send_character(client, message):
# Fetch a random character (male or female) from Anilist.
args = message.text.split(maxsplit=1)
search = args[1] if len(args) > 1 else None
try:
characters = await AniList.fetch_characters(count=1, search=search)
if not characters:
await message.reply("No characters found.")
return
character = characters[0]
description = (character['description'][:500] + "..."
if len(character['description']) > 500
else character['description'])
caption = (
f"**Name:** {character['name']}\n"
f"**Anime:** {character['anime']}\n"
f"**Age:** {character['age']}\n"
f"**Gender:** {character['gender']}\n\n"
f"{description}"
)
await message.reply_photo(character['image'], caption=caption)
except Exception as e:
await message.reply(f"Error: {e}")
if __name__ == "__main__":
app.run()
```
## Credits & Attributions
- **Pixipy3** – A Pixiv Project [Pixipy3's repo](https://github.com/upbit/pixivpy/tree/master).
- **ZipFile's Gist** – Wiki for Pixiv Tokens [here](https://gist.github.com/ZipFile/c9ebedb224406f4f11845ab700124362).
## Contributing
We welcome contributions to **waifu-python**! If you'd like to improve the project, please follow these steps:
- **Fork** the repository to your own GitHub account.
- **Clone** the project to your local machine.
- **Create a branch** locally with a succinct but descriptive name (e.g. `feature/your-feature`).
- **Commit** your changes to the branch, following any formatting.
- **Push** your changes to your fork.
- **Open a Pull Request** in our repository, so that we can efficiently review your changes.
Thank you for contributing to **waifu-python**!
## License
Copyright (c) [2025] [Misfit]
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
Raw data
{
"_id": null,
"home_page": "https://github.com/MisfiT2020/Waifu-Python",
"name": "waifu-python",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": null,
"author": "Misfit",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/50/ec/78cc24aa7c9dcd97dd4eaa142558e251fe83fff5c4401b98eba2832fd420/waifu_python-1.9.2.tar.gz",
"platform": null,
"description": "\n\n<h1 align=\"center\"> Waifu-Python </h1>\n\n<div align=\"center\">\n\nA project born out of boredom, designed to simplify and reduce the code related to the [Waifu API](https://github.com/MisfiT2020/Waifu-Python/tree/main#api-included)\n\n</div>\n\n<div align=\"center\">\n <a href=\"https://t.me/ShogunUpdates\">\n <img src=\"https://img.shields.io/badge/Telegram-2CA5E0?style=for-the-badge&logo=telegram&logoColor=white\" alt=\"Telegram Badge\"/>\n </a>\n</div>\n\n\n## Installation\n\nUse the package manager [pip](https://pypi.org/project/waifu-python/) to install **waifu-python**.\n\n```bash\npip install waifu-python\n```\n\n## CLI Usage\n\nAfter installing waifu-python, you can interact with it directly from your terminal. Output for a quick reference:\n\n```bash\n\u2570\u2500 \u276f\u276f waifu-python \nusage: waifu-python [-h] [--limit LIMIT] [--nsfw | --sfw] [--tags] [--list] [api] [query]\n\nWaifu-Python API client\n\nRequired Arguments:\n api API name\n query Search query (tag) if any\n\noptions:\n -h, --help show this help message and exit\n --limit LIMIT Number of images to retrieve\n --nsfw Fetch in NSFW mode\n --sfw Fetch in SFW mode\n --tags Retrieve available tags for the specified API\n --list List all available API names with SFW/NSFW availability\n```\n\n### Examples\n- Fetches available Apis\n\n```bash\nwaifu-python --list\n```\n\n- Fetch a random SFW image from a specific API:\n\n```bash\nwaifu-python danbooru\n```\n\n- Fetch a NSFW image with a specific tag:\n\n```bash\nwaifu-python konachan \"raiden shogun\" --nsfw \n```\n\n- Retrieve available tags for a given API:\n\n```bash\nwaifu-python waifuim --tags\n```\n\n- Fetch random images with Limits:\n\n```bash\nwaifu-python random --limit 3\n```\n\n- Usage with multiple options:\n\n```bash\nwaifu-python kemono \"raiden shogun\" --nsfw --limit 3\n```\n\n## Features\n\n- **Flexible Search Input:** \n Search queries no longer require underscores or hyphens between words, making it easier to find characters and tags. \n For example, searching for `\"Raiden Shogun\"` will work the same as `\"Raiden_Shogun\"` or `\"Raiden-Shogun\"` \n\n- **Character Search:** \n Search for characters by name to get targeted results. \n\n- **Tag Retrieval:** \n Retrieve available tags from supported [API](https://github.com/MisfiT2020/Waifu-Python/tree/main?tab=readme-ov-file#api-included) to help refine and filter your searches. \n\n- **Random Image Fetching:** \n Easily retrieve random images across multiple supported APIs. \n\n- **API-Specific Image Retrieval:** \n Fetch random images from a specific API (e.g., **Danbooru, Waifu.im, Waifu.pics, etc.**) based on your preference. \n\n- **CLI Support:**\n Use `waifu-python` from the command line for quick access to images and tags.\n\n- **Pixiv Tokens:**\n Add support for [Pixiv tokens](https://github.com/MisfiT2020/Waifu-Python/tree/main?tab=readme-ov-file#pixiv-example) with an Auto-refresh Token\u2014no need for manual access token \n\n## API Included\n\n| API | WORKING | TAGS |\n| --------------------------------------- | ------- | ---- |\n| [AiBooru](https://aibooru.online/) | \u2713 | - |\n| [Anilist](https://anilist.co/) | \u2713 | - |\n| [Danborru](https://danbooru.donmai.us/) | \u2713 | - |\n| [Gelbooru](https://gelbooru.com/) | \u2713 | - |\n| [Hijiribe](https://hijiribe.donmai.us/) | \u2713 | - |\n| [Iwara](https://www.iwara.tv/) | \u2713 | - |\n| [KemonoParty](https://kemono.su/) | \u2713 | - |\n| [Konachan](https://konachan.net/) | \u2713 | - |\n| [Nekos.best](https://nekos.best/) | \u2713 | \u2713 |\n| [N-sfw.com](https://n-sfw.com/) | \u2713 | \u2713 |\n| [Pic.re](https://pic.re/) | \u2713 | \u2713 |\n| [Pixiv](https://pixiv.net/) | \u2713 | - |\n| [Purrbot.site](https://purrbot.site/) | \u2713 | - |\n| [Rule34](https://rule34.xxx/) | \u2713 | - |\n| [Safeborru](https://safebooru.org/) | \u2713 | - |\n| [Sankaku](https://sankaku.app/) | \u2713 | - |\n| [Tbib](https://tbib.org/) | \u2713 | - |\n| [Waifu.im](https://www.waifu.im/) | \u2713 | \u2713 |\n| [Waifu.pics](https://waifu.pics/) | \u2713 | \u2713 |\n| [Zerochan](https://www.zerochan.net/) | \u2713 | - |\n\n\ud83d\udd39 `Hijiribe` as `hiji` in cli\n\n\n## Usage Example\n\n```python\nimport asyncio\nfrom waifu_python import WaifuIm\n\nasync def main():\n\n image_data1 = await WaifuIm.fetch_sfw_images()\n #Support for tags in Parameters\n image_data2 = await WaifuIm.fetch_sfw_images('raiden shogun')\n #Retrive tags for the API\n tags = await WaifuIm.get_tags()\n\n print(f\"Random Image: {image_data1}\\n\\nRaiden Shogun: {image_data2}\\n\\nTags{tags}\")\n\nasyncio.run(main())\n```\n\n## Environment Variables\n\n Create a .env file in your project root and include your Pixiv refresh token:\n\n```python\nIWARA_EMAIL=<mail>\nIWARA_PASSWORD=<password>\nPIXIV_REFRESH_TOKEN=<refresh token>\n```\n\ud83d\udd39 or Export the variables\n\n## Pixiv Example\n\n```python\nfrom waifu_python import Pixiv\nimport asyncio\n\nasync def main():\n \n tag_search = await Pixiv.fetch_images(\"raiden shogun\") #parameters: download=Bool, max_pages=int #fetches the tag\n illust_related = await Pixiv.fetch_images(127318308) #int = pixiv image related\n illust_recommended = await Pixiv.fetch_images() #fetches recommended images from pixiv\n print(tag_search)\n print(illust_related)\n print(illust_recommended)\n\nasyncio.run(main())\n```\n\n> To get `refresh_token`, see\n> [@ZipFile Pixiv OAuth Flow](https://gist.github.com/ZipFile/c9ebedb224406f4f11845ab700124362)\n> / [gppt: get-pixivpy-token](https://github.com/eggplants/get-pixivpy-token)\n> (Easy to use \ud83d\udc4d base on selenium) /\n> [OAuth with Selenium/ChromeDriver](https://gist.github.com/upbit/6edda27cb1644e94183291109b8a5fde)\n\n\ud83d\udd39 Or use command `waifu-python pixiv --login` or `waifu-python pixiv --refresh <old refresh code>`\n\n\n## **Required Class Functions**\n\nEach module in this library must implement the following functions:\n\n| Function Name | APIs Used | Description |\n|----------------------|-----------| ------------|\n| `fetch_images` | `Danbooru`, `Pixiv`, `Yandere`, `Gelbooru`, `Rule34` | Fetches both SFW and NSFW images |\n| `fetch_sfw_images` | `WaifuIm`, `WaifuPics`, `Safebooru`, `NekosBest`, `NSFWBot`, `PurrBot`, `PicRe`, `Konachan`, `Zerochan`, `Sankaku`, `Tbib`, `Hijiribe`, `Aibooru` | Fetches only SFW images |\n| `fetch_nsfw_images` | `WaifuIm`, `WaifuPics`, `Konachan`, `NSFWBot`, `KemonoParty`, `Sankaku`, `Tbib`, `Hijiribe`, `Aibooru` | Fetches only NSFW images |\n| `fetch_sfw_gif` | `PurrBot` | Fetches SFW GIFs |\n| `fetch_nsfw_gif` | `PurrBot` | Fetches NSFW GIFs |\n| `get_tags` | `WaifuIm`, `NekosBest`, `WaifuPics`, `PicRe`, `NSFWBot`, `PurrBot` | Fetches Tags from API |\n| `iwara_fetch` & `fetch_random` | `Iwara` | <i>Fetches Url (no search parameter)<i> & <i>fetches random url data</i> |\n\n\n## Example 1: Fetching Images from Multiple APIs\n\n```python\nimport asyncio\nfrom waifu_python import *\n\nasync def main():\n # ----- SFW Images -----\n sfw_images = {\n \"WaifuIm\": await WaifuIm.fetch_sfw_images(),\n \"NekosBest\": await NekosBest.fetch_sfw_images(),\n \"WaifuPics\": await WaifuPics.fetch_sfw_images(),\n \"PicRe\": await PicRe.fetch_sfw_images(),\n \"NSFWBot\": await NSFWBot.fetch_sfw_images(),\n \"PurrBot\": await PurrBot.fetch_sfw_images(),\n \"SafeBooru\": await Safebooru.fetch_images(),\n \"Konachan\": await Konachan.fetch_sfw_images(),\n \"Zerochan\": await Zerochan.fetch_sfw_images(),\n \"Sankaku\": await Sankaku.fetch_sfw_images(),\n \"Tbib\": await Tbib.fetch_sfw_images(),\n \"Hijiribe\": await Hijiribe.fetch_sfw_images(),\n \"Aibooru\": await Aibooru.fetch_sfw_images()\n }\n\n # ----- NSFW Images/GIFs -----\n nsfw_images = {\n \"WaifuIm\": await WaifuIm.fetch_nsfw_images(),\n \"WaifuPics\": await WaifuPics.fetch_nsfw_images(),\n \"NSFWBot\": await NSFWBot.fetch_nsfw_images(),\n \"Pixiv\": await Pixiv.fetch_images(),\n \"PurrBot GIF\": await PurrBot.fetch_nsfw_gif(),\n \"Danbooru\": await Danbooru.fetch_images(),\n \"Yandere\": await Yandere.fetch_images(),\n \"Rule34\": await Rule34.fetch_images(),\n \"KemonoParty\": await KemonoParty.fetch_nsfw_images()\n \"Sankaku\": await Sankaku.fetch_nsfw_images(),\n \"Tbib\": await Tbib.fetch_nsfw_images(), \n \"Hijiribe\": await Hijiribe.fetch_nsfw_images(), \n \"Pixiv\": await Pixiv.fetch_nsfw_images(), \n \"Aibooru\": await Aibooru.fetch_nsfw_images()\n }\n\n # ----- Tags -----\n tags = {\n \"WaifuIm\": await WaifuIm.get_tags(),\n \"NekosBest\": await NekosBest.get_tags(),\n \"WaifuPics\": await WaifuPics.get_tags(),\n \"PicRe\": await PicRe.get_tags(),\n \"NSFWBot\": await NSFWBot.get_tags(),\n \"PurrBot\": await PurrBot.get_tags()\n }\n\n # Display results\n print(\"----- SFW Images -----\")\n for key, value in sfw_images.items():\n print(f\"{key}: {value}\")\n\n print(\"\\n----- NSFW Images/GIFs -----\")\n for key, value in nsfw_images.items():\n print(f\"{key}: {value}\")\n\n#------Tags Are Overwhelming------\n# print(\"\\n----- Tags -----\")\n# for key, value in tags.items():\n# print(f\"{key}: {value}\")\n\nasyncio.run(main())\n\n```\n\n## Example 2: Fetching Random Images\n\n```python\nimport asyncio\nfrom waifu_python import RandomWaifu\n\nasync def main():\n\n random_img = await RandomWaifu.get_random_image()\n sfw_img = await RandomWaifu.get_random_sfw_image()\n nsfw_img = await RandomWaifu.get_random_nsfw_image()\n sfw_gif = await RandomWaifu.get_random_sfw_gif()\n nsfw_gif = await RandomWaifu.get_random_nsfw_gif()\n\n print(\"Random Image:\", random_img)\n print(\"SFW Image:\", sfw_img)\n print(\"NSFW Image:\", nsfw_img)\n print(\"SFW GIF:\", sfw_gif)\n print(\"NSFW GIF:\", nsfw_gif)\n\nif __name__ == \"__main__\":\n asyncio.run(main())\n```\n\n### Available Methods for Random Image Fetching\n\n| Function | Description |\n|----------|-------------|\n| `get_random_image()` | Returns a completely random image (SFW or NSFW). |\n| `get_random_sfw_image()` | Returns a random SFW image. |\n| `get_random_nsfw_image()` | Returns a random NSFW image. |\n| `get_random_sfw_gif()` | Returns a random SFW GIF. |\n| `get_random_nsfw_gif()` | Returns a random NSFW GIF. |\n\n\n## Example 3: Anilist Waifus/Characters\n\n```python\nimport asyncio\nfrom waifu_python import Anilist\n\nasync def main():\n\n waifus = await Anilist.fetch_waifus('Mahiru Shiina')\n characters = await Anilist.fetch_characters(\"eren yeager\")\n anime = await Anilist.search_anime(\"kimi no na wa\")\n print(waifus)\n print(characters)\n print(anime)\n \nif __name__ == \"__main__\":\n asyncio.run(main())\n```\n\n### Available Methods:\n\n| Function | Description | Search Parameter | Returned Fields |\n|----------|-------------|------------------| --------------- |\n| `fetch_waifus(\"characterName\")` | Fetches waifus only (female characters). | Optional | `name`, `anime`, `image`, `age`, `gender`, `description` |\n| `fetch_characters(characterName)` | Fetches all characters (male & female). | Optional | `name`, `anime`, `image`, `age`, `gender`, `description` |\n\n##\n\n\ud83d\udd39 If `character` is not provided, it will return random characters.\n\n\n## Example 4: Using Waifu API in a Telegram Bot\n\n```python\nfrom pyrogram import Client, filters\nfrom waifu_python import AniList, SafeBooru, Danbooru\n\napp = Client(\"Raiden\", api_id=\"YOUR_API_ID\", api_hash=\"YOUR_API_HASH\", bot_token=\"YOUR_BOT_TOKEN\")\n\n@app.on_message(filters.command(\"sfw\"))\nasync def send_sfw_image(client, message):\n # Use SafeBooru to fetch a random SFW image.\n args = message.text.split()\n tag = args[1] if len(args) > 1 else None\n try:\n image_url = await SafeBooru.get_random_image(tag)\n if image_url:\n await message.reply_photo(image_url)\n else:\n await message.reply(\"No SFW image found.\")\n except Exception as e:\n await message.reply(f\"Error: {e}\")\n\n@app.on_message(filters.command(\"nsfw\"))\nasync def send_nsfw_image(client, message):\n # Use Danbooru to fetch a random NSFW image.\n args = message.text.split()\n tag = args[1] if len(args) > 1 else None\n try:\n image_url = await Danbooru.get_random_image(tag)\n if image_url:\n await message.reply_photo(image_url)\n else:\n await message.reply(\"No NSFW image found.\")\n except Exception as e:\n await message.reply(f\"Error: {e}\")\n\n# --------------------------------- Anilist ----------------------------------\n\n@app.on_message(filters.command(\"waifu\"))\nasync def send_waifu_image(client, message):\n # Fetch a random waifu (female character) from Anilist.\n args = message.text.split(maxsplit=1)\n search = args[1] if len(args) > 1 else None\n try:\n waifus = await AniList.fetch_waifus(count=1, search=search)\n if not waifus:\n await message.reply(\"No waifus found.\")\n return\n waifu = waifus[0]\n description = (waifu['description'][:500] + \"...\"\n if len(waifu['description']) > 500\n else waifu['description'])\n caption = (\n f\"**Name:** {waifu['name']}\\n\"\n f\"**Anime:** {waifu['anime']}\\n\"\n f\"**Age:** {waifu['age']}\\n\"\n f\"**Gender:** {waifu['gender']}\\n\\n\"\n f\"{description}\"\n )\n await message.reply_photo(waifu['image'], caption=caption)\n except Exception as e:\n await message.reply(f\"Error: {e}\")\n\n@app.on_message(filters.command(\"character\"))\nasync def send_character(client, message):\n # Fetch a random character (male or female) from Anilist.\n args = message.text.split(maxsplit=1)\n search = args[1] if len(args) > 1 else None\n try:\n characters = await AniList.fetch_characters(count=1, search=search)\n if not characters:\n await message.reply(\"No characters found.\")\n return\n character = characters[0]\n description = (character['description'][:500] + \"...\"\n if len(character['description']) > 500\n else character['description'])\n caption = (\n f\"**Name:** {character['name']}\\n\"\n f\"**Anime:** {character['anime']}\\n\"\n f\"**Age:** {character['age']}\\n\"\n f\"**Gender:** {character['gender']}\\n\\n\"\n f\"{description}\"\n )\n await message.reply_photo(character['image'], caption=caption)\n except Exception as e:\n await message.reply(f\"Error: {e}\")\n\nif __name__ == \"__main__\":\n app.run()\n```\n\n## Credits & Attributions\n\n- **Pixipy3** \u2013 A Pixiv Project [Pixipy3's repo](https://github.com/upbit/pixivpy/tree/master).\n- **ZipFile's Gist** \u2013 Wiki for Pixiv Tokens [here](https://gist.github.com/ZipFile/c9ebedb224406f4f11845ab700124362).\n\n\n## Contributing\n\nWe welcome contributions to **waifu-python**! If you'd like to improve the project, please follow these steps:\n\n- **Fork** the repository to your own GitHub account.\n- **Clone** the project to your local machine.\n- **Create a branch** locally with a succinct but descriptive name (e.g. `feature/your-feature`).\n- **Commit** your changes to the branch, following any formatting.\n- **Push** your changes to your fork.\n- **Open a Pull Request** in our repository, so that we can efficiently review your changes.\n\nThank you for contributing to **waifu-python**!\n\n## License\n\n Copyright (c) [2025] [Misfit]\n\n Permission is hereby granted, free of charge, to any person obtaining a copy\n of this software and associated documentation files (the \"Software\"), to deal\n in the Software without restriction, including without limitation the rights\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n copies of the Software, and to permit persons to whom the Software is\n furnished to do so, subject to the following conditions:\n \n The above copyright notice and this permission notice shall be included in all\n copies or substantial portions of the Software.\n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n SOFTWARE.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A project born out of boredom, designed to simplify and reduce the code related to the Waifu API.",
"version": "1.9.2",
"project_urls": {
"Homepage": "https://github.com/MisfiT2020/Waifu-Python"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "696db95295be8166fd3bcbda51c895e200cc4a90ba55df88d92570865782cd30",
"md5": "c8348ee66cbcba05a42930316ebf9e7a",
"sha256": "d27f238d2924883597850ddf4462cbc6085e3713d9d801dde6278fea323cf569"
},
"downloads": -1,
"filename": "waifu_python-1.9.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c8348ee66cbcba05a42930316ebf9e7a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 45160,
"upload_time": "2025-07-14T04:34:05",
"upload_time_iso_8601": "2025-07-14T04:34:05.177832Z",
"url": "https://files.pythonhosted.org/packages/69/6d/b95295be8166fd3bcbda51c895e200cc4a90ba55df88d92570865782cd30/waifu_python-1.9.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "50ec78cc24aa7c9dcd97dd4eaa142558e251fe83fff5c4401b98eba2832fd420",
"md5": "f7be424079d11d93ec59e2c910a88365",
"sha256": "ec47c55479aabbaecaf667be385d38cc73cabdb8303fa03f058cf1b4184049bc"
},
"downloads": -1,
"filename": "waifu_python-1.9.2.tar.gz",
"has_sig": false,
"md5_digest": "f7be424079d11d93ec59e2c910a88365",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 36337,
"upload_time": "2025-07-14T04:34:06",
"upload_time_iso_8601": "2025-07-14T04:34:06.480653Z",
"url": "https://files.pythonhosted.org/packages/50/ec/78cc24aa7c9dcd97dd4eaa142558e251fe83fff5c4401b98eba2832fd420/waifu_python-1.9.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-14 04:34:06",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "MisfiT2020",
"github_project": "Waifu-Python",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "httpx",
"specs": [
[
"==",
"0.28.1"
]
]
},
{
"name": "gallery-dl",
"specs": []
},
{
"name": "httpx_socks",
"specs": []
},
{
"name": "python-dotenv",
"specs": []
}
],
"lcname": "waifu-python"
}
JSON
