# Booru
Python bindings for Booru imageboards
<a href="http://sinkaroid.github.io/booru"><img align="right" src="https://cdn.discordapp.com/attachments/952117487166705747/961124440400351232/mataa.png" width="400"></a>
- [Booru](#booru)
- [Features](#features)
- [Features availability](#this-library-vs-the-competition)
- [Usage](#usage)
- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Example](#example)
- [search](#search)
- [search_image](#search_image)
- [find_tags](#find_tags)
- [booru.resolve()](#booruresolve)
- [Import specific booru client](#search)
- [Testing cases](https://github.com/sinkaroid/booru/actions)
- [The core](https://github.com/sinkaroid/booru/actions)
- [Tags completion](https://github.com/sinkaroid/booru/actions/workflows/find_tags.yml)
- [Documentation](#documentation)
- [Legal](#legal)
----
<div align="center">
<a href="https://github.com/sinkaroid/booru/actions/workflows/find_tags.yml"><img src="https://github.com/sinkaroid/booru/workflows/Tags completion/badge.svg"></a>
<a href="https://codeclimate.com/github/sinkaroid/booru/maintainability"><img src="https://api.codeclimate.com/v1/badges/c334d91994d1d84b8d7d/maintainability" /></a>
Python bindings for the imageboards.
It is takes a much more functionalities to interacts with ease, and featureful. Making your interaction significantly tidier, less of pain, and hopefully will be reusable.
<b>
<a href="https://github.com/sinkaroid/booru/blob/master/CONTRIBUTING.md">Contributing</a> •
<a href="https://sinkaroid.github.io/booru">Documentation</a> •
<a href="https://github.com/sinkaroid/booru/issues/new/choose">Report Issues</a>
</b>
</div>
## Features
- Plenty of imageboards
- Search random & gacha returns
- Tags block, resolved safety tags concerns
- Tags finder, tags & query completion
- Parses and returns the image only
- Documented and tested
- Easy to use, check your intelisense
## Usage
Async context, and it's recommended use [asyncio](https://docs.python.org/3/library/asyncio.html) / https://sinkaroid.github.io/booru
### Prerequisites
<table>
<td><b>NOTE:</b> Python 3.7 or above</td>
</table>
### Installation
`pip install booru`
## This library vs. the Competition
**Features availability** for this library
| Booru | Status | Random | Tags block | Tags finder | Get images | Gacha |
| ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | ---------- | ----- | ----- | ----- |
| [Gelbooru](https://gelbooru.com/) | [![status](https://github.com/sinkaroid/booru/workflows/Gelbooru/badge.svg)](https://github.com/sinkaroid/booru/actions/workflows/gel.yml) | `Yes` | `Yes` | `Yes` | `Yes` | `Yes` |
| [Danbooru](https://danbooru.donmai.us/) | [![status](https://github.com/sinkaroid/booru/workflows/Danbooru/badge.svg)](https://github.com/sinkaroid/booru/actions/workflows/danbo.yml) | `Yes` | `Yes` | `Yes` | `Yes` | `Yes` |
| [Rule34](https://rule34.xxx) | [![status](https://github.com/sinkaroid/booru/workflows/Rule34/badge.svg)](https://github.com/sinkaroid/booru/actions/workflows/r34.yml) | `Yes` | `Yes` | `Yes` | `Yes` | `Yes` |
| [Realbooru](https://realbooru.com/) | [![status](https://github.com/sinkaroid/booru/workflows/Realbooru/badge.svg)](https://github.com/sinkaroid/booru/actions/workflows/real.yml) | `Yes` | `Yes` | `Yes` | `Yes` | `Yes` |
| [Tbib](https://tbib.org/) | [![status](https://github.com/sinkaroid/booru/workflows/Tbib/badge.svg)](https://github.com/sinkaroid/booru/actions/workflows/tbib.yml) | `Yes` | `Yes` | `Yes` | `Yes` | `Yes` |
| [Xbooru](https://xbooru.com/) | [![status](https://github.com/sinkaroid/booru/workflows/Xbooru/badge.svg)](https://github.com/sinkaroid/booru/actions/workflows/xbo.yml) | `Yes` | `Yes` | `Yes` | `Yes` | `Yes` |
| [Safebooru](https://safebooru.org/) | [![status](https://github.com/sinkaroid/booru/workflows/Safebooru/badge.svg)](https://github.com/sinkaroid/booru/actions/workflows/safe.yml) | `Yes` | `Yes` | `Yes` | `Yes` | `Yes` |
| [Yandere](https://yande.re/) | [![status](https://github.com/sinkaroid/booru/workflows/Yandere/badge.svg)](https://github.com/sinkaroid/booru/actions/workflows/yande.yml) | `Yes` | `Yes` | `Yes` | `Yes` | `Yes` |
| [Lolibooru](https://lolibooru.moe/) | [![status](https://github.com/sinkaroid/booru/workflows/Lolibooru/badge.svg)](https://github.com/sinkaroid/booru/actions/workflows/loli.yml) | `Yes` | `Yes` | `Yes` | `Yes` | `Yes` |
| [Konachan](https://konachan.com/) | [![status](https://github.com/sinkaroid/booru/workflows/Konachan/badge.svg)](https://github.com/sinkaroid/booru/actions/workflows/kona.yml) | `Yes` | `Yes` | `Yes` | `Yes` | `Yes` |
| [Konachan.net](https://konachan.net/) | [![status](https://github.com/sinkaroid/booru/workflows/KonachanNet/badge.svg)](https://github.com/sinkaroid/booru/actions/workflows/konanet.yml) | `Yes` | `Yes` | `Yes` | `Yes` | `Yes` |
| [Hypnohub](https://hypnohub.net/) | [![status](https://github.com/sinkaroid/booru/workflows/Hypnohub/badge.svg)](https://github.com/sinkaroid/booru/actions/workflows/hypno.yml) | `Yes` | `Yes` | `Yes` | `Yes` | `Yes` |
| [E621](https://e621.net/) | [![status](https://github.com/sinkaroid/booru/workflows/E621/badge.svg)](https://github.com/sinkaroid/booru/actions/workflows/e6.yml) | `Yes` | `No` | `No` | `Yes` | `Yes` |
| [E926](https://e926.net/) | [![status](https://github.com/sinkaroid/booru/workflows/E926/badge.svg)](https://github.com/sinkaroid/booru/actions/workflows/e9.yml) | `Yes` | `No` | `No` | `Yes` | `Yes` |
| [Derpibooru](https://derpibooru.org/) | [![status](https://github.com/sinkaroid/booru/workflows/Derpibooru/badge.svg)](https://github.com/sinkaroid/booru/actions/workflows/derpi.yml) | `Yes` | `No` | `No` | `Yes` | `Yes` |
| [Furbooru](https://furbooru.org/) | [![status](https://github.com/sinkaroid/booru/workflows/Furbooru/badge.svg)](https://github.com/sinkaroid/booru/actions/workflows/fur.yml) | `Yes` | `No` | `No` | `Yes` | `Yes` |
| [ATFbooru](https://booru.allthefallen.moe/) | [![status](https://github.com/sinkaroid/booru/workflows/ATFbooru/badge.svg)](https://github.com/sinkaroid/booru/actions/workflows/atf.yml) | `Yes` | `Yes` | `Yes` | `Yes` | `Yes` |
| [Behoimi](http://behoimi.org/) | [![status](https://github.com/sinkaroid/booru/workflows/Behoimi/badge.svg)](https://github.com/sinkaroid/booru/actions/workflows/behoi.yml) | `Yes` | `No` | `No` | `Yes` | `Yes` |
| [Paheal](https://rule34.paheal.net/) | [![status](https://github.com/sinkaroid/booru/workflows/Paheal/badge.svg)](https://github.com/sinkaroid/booru/actions/workflows/paheal.yml) | `Yes` | `No` | `No` | `Yes` | `Yes` |
## Example
### **search()**
Takes parameter `(query: str, block: str = "", limit: int = 100, page: int = 1, random: bool = True, gacha: bool = False)`
```py
import asyncio
import booru
async def main():
dan = booru.Danbooru()
res = await dan.search(query="cat_girl", block="futanari")
print(res) ## this is <class 'str'>
print(booru.resolve(res)) ## this is <class 'list'>
asyncio.run(main())
```
- You will never gets content which contains futa tags.
You can also import specific booru client.
```py
from booru import Rule34
some_booru = Rule34()
## do with r34
```
### **search_image()**
Takes parameter `(query: str, block: str = "", limit: int = 100, page: int = 1)`
```py
import asyncio
from booru import Rule34
async def main():
r34 = Rule34()
img = await r34.search_image(query="cat_girl", block="futanari")
print(img)
asyncio.run(main())
```
- This will parses image url only, instead object
### **find_tags()**
You want to wildcard or query completion like the browser do?
<center>
<table>
<tr>
<td align="center"><img src="https://cdn.discordapp.com/attachments/1046495201176334467/1050354442966413352/rounded_corners_3.png" width="340px;" alt=""/><br />What browser looks like</td>
<td align="center"><img src="https://cdn.discordapp.com/attachments/1046495201176334467/1050354442651836506/rounded_corners_4.png" width="340px;" alt=""/><br />This library also</td>
</tr>
</table>
</center><br>
```py
import asyncio
from booru import Danbooru, resolve
async def main():
dan = Danbooru()
find_tags = await dan.find_tags("jeanne") ## arbitrary tags
wildcard = resolve(find_tags)
print(wildcard)
asyncio.run(main())
```
- Get the `wildcard[0]` for the best match.
## booru.resolve()
You will need this for every object, this library designed to be neat and clean returns, although it must be reparsed to the string first, that's why `booru.resolve()` exist.
## Documentation
The documentation can be found https://sinkaroid.github.io/booru
## Legal
This tool can be freely copied, modified, altered, distributed without any attribution whatsoever. However, if you feel
like this tool deserves an attribution, mention it. It won't hurt anybody
> Licence: WTF.
Raw data
{
"_id": null,
"home_page": "https://github.com/sinkaroid/booru",
"name": "booru",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "booru,gelbooru,rule34,safebooru,xbooru,tbib,realbooru,hypnohub,danbooru,atfbooru,yandere,konachan,konachan.net,lolibooru,e621,e926,derpibooru,furbooru,behoimi,paheal",
"author": "sinkaroid",
"author_email": "anakmancasan@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/c6/ce/dab00e2396eb4bd779ad016a2e1fb09de246bc9a89d676cd7c62d98e0b3f/booru-1.0.21.tar.gz",
"platform": null,
"description": "# Booru\r\nPython bindings for Booru imageboards\r\n\r\n<a href=\"http://sinkaroid.github.io/booru\"><img align=\"right\" src=\"https://cdn.discordapp.com/attachments/952117487166705747/961124440400351232/mataa.png\" width=\"400\"></a>\r\n\r\n- [Booru](#booru)\r\n - [Features](#features)\r\n - [Features availability](#this-library-vs-the-competition)\r\n - [Usage](#usage)\r\n - [Prerequisites](#prerequisites)\r\n - [Installation](#installation)\r\n - [Example](#example)\r\n - [search](#search)\r\n - [search_image](#search_image)\r\n - [find_tags](#find_tags)\r\n - [booru.resolve()](#booruresolve)\r\n - [Import specific booru client](#search)\r\n - [Testing cases](https://github.com/sinkaroid/booru/actions)\r\n - [The core](https://github.com/sinkaroid/booru/actions)\r\n - [Tags completion](https://github.com/sinkaroid/booru/actions/workflows/find_tags.yml)\r\n - [Documentation](#documentation)\r\n - [Legal](#legal) \r\n\r\n----\r\n\r\n<div align=\"center\">\r\n\r\n<a href=\"https://github.com/sinkaroid/booru/actions/workflows/find_tags.yml\"><img src=\"https://github.com/sinkaroid/booru/workflows/Tags completion/badge.svg\"></a>\r\n<a href=\"https://codeclimate.com/github/sinkaroid/booru/maintainability\"><img src=\"https://api.codeclimate.com/v1/badges/c334d91994d1d84b8d7d/maintainability\" /></a>\r\n\r\nPython bindings for the imageboards.\r\nIt is takes a much more functionalities to interacts with ease, and featureful. Making your interaction significantly tidier, less of pain, and hopefully will be reusable.\r\n\r\n<b>\r\n<a href=\"https://github.com/sinkaroid/booru/blob/master/CONTRIBUTING.md\">Contributing</a> \u2022\r\n<a href=\"https://sinkaroid.github.io/booru\">Documentation</a> \u2022\r\n<a href=\"https://github.com/sinkaroid/booru/issues/new/choose\">Report Issues</a>\r\n</b>\r\n</div>\r\n\r\n## Features\r\n- Plenty of imageboards\r\n- Search random & gacha returns\r\n- Tags block, resolved safety tags concerns\r\n- Tags finder, tags & query completion\r\n- Parses and returns the image only\r\n- Documented and tested\r\n- Easy to use, check your intelisense\r\n\r\n## Usage\r\nAsync context, and it's recommended use [asyncio](https://docs.python.org/3/library/asyncio.html) / https://sinkaroid.github.io/booru\r\n\r\n### Prerequisites\r\n<table>\r\n\t<td><b>NOTE:</b> Python 3.7 or above</td>\r\n</table>\r\n\r\n### Installation\r\n`pip install booru`\r\n\r\n\r\n## This library vs. the Competition\r\n\r\n**Features availability** for this library \r\n\r\n| Booru | Status | Random | Tags block | Tags finder | Get images | Gacha |\r\n| ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | ---------- | ----- | ----- | ----- | \r\n| [Gelbooru](https://gelbooru.com/) | [![status](https://github.com/sinkaroid/booru/workflows/Gelbooru/badge.svg)](https://github.com/sinkaroid/booru/actions/workflows/gel.yml) | `Yes` | `Yes` | `Yes` | `Yes` | `Yes` | \r\n| [Danbooru](https://danbooru.donmai.us/) | [![status](https://github.com/sinkaroid/booru/workflows/Danbooru/badge.svg)](https://github.com/sinkaroid/booru/actions/workflows/danbo.yml) | `Yes` | `Yes` | `Yes` | `Yes` | `Yes` | \r\n| [Rule34](https://rule34.xxx) | [![status](https://github.com/sinkaroid/booru/workflows/Rule34/badge.svg)](https://github.com/sinkaroid/booru/actions/workflows/r34.yml) | `Yes` | `Yes` | `Yes` | `Yes` | `Yes` | \r\n| [Realbooru](https://realbooru.com/) | [![status](https://github.com/sinkaroid/booru/workflows/Realbooru/badge.svg)](https://github.com/sinkaroid/booru/actions/workflows/real.yml) | `Yes` | `Yes` | `Yes` | `Yes` | `Yes` | \r\n| [Tbib](https://tbib.org/) | [![status](https://github.com/sinkaroid/booru/workflows/Tbib/badge.svg)](https://github.com/sinkaroid/booru/actions/workflows/tbib.yml) | `Yes` | `Yes` | `Yes` | `Yes` | `Yes` | \r\n| [Xbooru](https://xbooru.com/) | [![status](https://github.com/sinkaroid/booru/workflows/Xbooru/badge.svg)](https://github.com/sinkaroid/booru/actions/workflows/xbo.yml) | `Yes` | `Yes` | `Yes` | `Yes` | `Yes` | \r\n| [Safebooru](https://safebooru.org/) | [![status](https://github.com/sinkaroid/booru/workflows/Safebooru/badge.svg)](https://github.com/sinkaroid/booru/actions/workflows/safe.yml) | `Yes` | `Yes` | `Yes` | `Yes` | `Yes` | \r\n| [Yandere](https://yande.re/) | [![status](https://github.com/sinkaroid/booru/workflows/Yandere/badge.svg)](https://github.com/sinkaroid/booru/actions/workflows/yande.yml) | `Yes` | `Yes` | `Yes` | `Yes` | `Yes` | \r\n| [Lolibooru](https://lolibooru.moe/) | [![status](https://github.com/sinkaroid/booru/workflows/Lolibooru/badge.svg)](https://github.com/sinkaroid/booru/actions/workflows/loli.yml) | `Yes` | `Yes` | `Yes` | `Yes` | `Yes` | \r\n| [Konachan](https://konachan.com/) | [![status](https://github.com/sinkaroid/booru/workflows/Konachan/badge.svg)](https://github.com/sinkaroid/booru/actions/workflows/kona.yml) | `Yes` | `Yes` | `Yes` | `Yes` | `Yes` | \r\n| [Konachan.net](https://konachan.net/) | [![status](https://github.com/sinkaroid/booru/workflows/KonachanNet/badge.svg)](https://github.com/sinkaroid/booru/actions/workflows/konanet.yml) | `Yes` | `Yes` | `Yes` | `Yes` | `Yes` | \r\n| [Hypnohub](https://hypnohub.net/) | [![status](https://github.com/sinkaroid/booru/workflows/Hypnohub/badge.svg)](https://github.com/sinkaroid/booru/actions/workflows/hypno.yml) | `Yes` | `Yes` | `Yes` | `Yes` | `Yes` | \r\n| [E621](https://e621.net/) | [![status](https://github.com/sinkaroid/booru/workflows/E621/badge.svg)](https://github.com/sinkaroid/booru/actions/workflows/e6.yml) | `Yes` | `No` | `No` | `Yes` | `Yes` | \r\n| [E926](https://e926.net/) | [![status](https://github.com/sinkaroid/booru/workflows/E926/badge.svg)](https://github.com/sinkaroid/booru/actions/workflows/e9.yml) | `Yes` | `No` | `No` | `Yes` | `Yes` | \r\n| [Derpibooru](https://derpibooru.org/) | [![status](https://github.com/sinkaroid/booru/workflows/Derpibooru/badge.svg)](https://github.com/sinkaroid/booru/actions/workflows/derpi.yml) | `Yes` | `No` | `No` | `Yes` | `Yes` | \r\n| [Furbooru](https://furbooru.org/) | [![status](https://github.com/sinkaroid/booru/workflows/Furbooru/badge.svg)](https://github.com/sinkaroid/booru/actions/workflows/fur.yml) | `Yes` | `No` | `No` | `Yes` | `Yes` | \r\n| [ATFbooru](https://booru.allthefallen.moe/) | [![status](https://github.com/sinkaroid/booru/workflows/ATFbooru/badge.svg)](https://github.com/sinkaroid/booru/actions/workflows/atf.yml) | `Yes` | `Yes` | `Yes` | `Yes` | `Yes` | \r\n| [Behoimi](http://behoimi.org/) | [![status](https://github.com/sinkaroid/booru/workflows/Behoimi/badge.svg)](https://github.com/sinkaroid/booru/actions/workflows/behoi.yml) | `Yes` | `No` | `No` | `Yes` | `Yes` | \r\n| [Paheal](https://rule34.paheal.net/) | [![status](https://github.com/sinkaroid/booru/workflows/Paheal/badge.svg)](https://github.com/sinkaroid/booru/actions/workflows/paheal.yml) | `Yes` | `No` | `No` | `Yes` | `Yes` | \r\n\r\n## Example\r\n### **search()**\r\nTakes parameter `(query: str, block: str = \"\", limit: int = 100, page: int = 1, random: bool = True, gacha: bool = False)`\r\n```py\r\nimport asyncio\r\nimport booru\r\n\r\nasync def main():\r\n dan = booru.Danbooru()\r\n res = await dan.search(query=\"cat_girl\", block=\"futanari\")\r\n print(res) ## this is <class 'str'>\r\n print(booru.resolve(res)) ## this is <class 'list'>\r\n\r\nasyncio.run(main())\r\n``` \r\n- You will never gets content which contains futa tags.\r\n\r\nYou can also import specific booru client.\r\n```py\r\nfrom booru import Rule34\r\nsome_booru = Rule34()\r\n\r\n## do with r34\r\n```\r\n\r\n### **search_image()**\r\nTakes parameter `(query: str, block: str = \"\", limit: int = 100, page: int = 1)`\r\n```py\r\nimport asyncio\r\nfrom booru import Rule34\r\n\r\nasync def main():\r\n r34 = Rule34()\r\n img = await r34.search_image(query=\"cat_girl\", block=\"futanari\")\r\n print(img)\r\n\r\nasyncio.run(main())\r\n``` \r\n- This will parses image url only, instead object\r\n\r\n### **find_tags()**\r\nYou want to wildcard or query completion like the browser do? \r\n<center>\r\n<table>\r\n <tr>\r\n <td align=\"center\"><img src=\"https://cdn.discordapp.com/attachments/1046495201176334467/1050354442966413352/rounded_corners_3.png\" width=\"340px;\" alt=\"\"/><br />What browser looks like</td>\r\n <td align=\"center\"><img src=\"https://cdn.discordapp.com/attachments/1046495201176334467/1050354442651836506/rounded_corners_4.png\" width=\"340px;\" alt=\"\"/><br />This library also</td>\r\n\r\n </tr>\r\n</table>\r\n</center><br>\r\n\r\n```py\r\nimport asyncio\r\nfrom booru import Danbooru, resolve\r\n\r\nasync def main():\r\n dan = Danbooru()\r\n find_tags = await dan.find_tags(\"jeanne\") ## arbitrary tags\r\n wildcard = resolve(find_tags)\r\n print(wildcard)\r\n\r\nasyncio.run(main())\r\n```\r\n- Get the `wildcard[0]` for the best match.\r\n\r\n## booru.resolve()\r\nYou will need this for every object, this library designed to be neat and clean returns, although it must be reparsed to the string first, that's why `booru.resolve()` exist.\r\n\r\n## Documentation\r\nThe documentation can be found https://sinkaroid.github.io/booru\r\n\r\n## Legal\r\nThis tool can be freely copied, modified, altered, distributed without any attribution whatsoever. However, if you feel\r\nlike this tool deserves an attribution, mention it. It won't hurt anybody\r\n> Licence: WTF.\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python bindings for Booru imageboards",
"version": "1.0.21",
"split_keywords": [
"booru",
"gelbooru",
"rule34",
"safebooru",
"xbooru",
"tbib",
"realbooru",
"hypnohub",
"danbooru",
"atfbooru",
"yandere",
"konachan",
"konachan.net",
"lolibooru",
"e621",
"e926",
"derpibooru",
"furbooru",
"behoimi",
"paheal"
],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "d67d91089d6fff624c40269538dba4fa",
"sha256": "b1350a8112189955bc29954d89b87d6065cd764271d52b8fa2de82ac9066ac53"
},
"downloads": -1,
"filename": "booru-1.0.21.tar.gz",
"has_sig": false,
"md5_digest": "d67d91089d6fff624c40269538dba4fa",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 17436,
"upload_time": "2022-12-08T11:04:58",
"upload_time_iso_8601": "2022-12-08T11:04:58.798172Z",
"url": "https://files.pythonhosted.org/packages/c6/ce/dab00e2396eb4bd779ad016a2e1fb09de246bc9a89d676cd7c62d98e0b3f/booru-1.0.21.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-12-08 11:04:58",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "sinkaroid",
"github_project": "booru",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "aiohttp",
"specs": [
[
">=",
"3.8.3"
]
]
},
{
"name": "beautifulsoup4",
"specs": [
[
">=",
"4.11.1"
]
]
},
{
"name": "xmltodict",
"specs": [
[
">=",
"0.13.0"
]
]
}
],
"lcname": "booru"
}