# PyGelbooru
PyGelbooru is an unofficial and lightweight asynchronous library for the [Gelbooru](https://gelbooru.com/) API.
# Installation
This library requires [Python 3.6](https://www.python.org) or above.
You can install the library through pip as follows,
```shell script
pip install pygelbooru
```
## Usage
### Searching
The primary use for this library is, naturally, to search for images with specific tags.
This can be done as so:
```python
from pygelbooru import Gelbooru
# API key/user ID is optional, but access may be limited without them
gelbooru = Gelbooru('API_KEY', 'USER_ID')
results = await gelbooru.search_posts(tags=['dog ears', '1girl'], exclude_tags=['nude'])
[<GelbooruImage(id=5105386, filename='b77e69be0a4b...dde071dc.jpeg', owner='anon2003')>,
<GelbooruImage(id=5105161, filename='bf169f891ebe...02bceb5e.jpeg', owner='cpee')>,
<GelbooruImage(id=5104148, filename='46df3ebe2d41...4316d218e.jpg', owner='danbooru')>,
<GelbooruImage(id=5104080, filename='e8eec23d151e...419293401.png', owner='anon2003')>,
<GelbooruImage(id=5103937, filename='5bf279f3c546...be3fc53c8.jpg', owner='danbooru')>,
...
```
Tags **can** contain spaces when passed as arguments, they will simply be reformated with underscores before being queried, so you don't need to reformat them yourself.
Results are returned as a list of GelbooruImage containers. When cast to a string, this will return the image_url,
```python
str(results[0])
'https://img2.gelbooru.com/images/b7/7e/b77e69be0a4b581eac597527dde071dc.jpeg'
```
You can also pull other information returned by the API,
https://github.com/FujiMakoto/pygelbooru/blob/master/pygelbooru/gelbooru.py#L32-L47
### Searching (Random)
In addition to searching for a large list of images, PyGelbooru also provides a helper method for when you're really just after a single, random image that matches the specified tags.
This method will automatically pull a random image from the last 20,000 Gelbooru image submissions.
```python
result = await gelbooru.random_post(tags=['cat ears', '1girl', 'cat hood', 'bell'], exclude_tags=['nude'])
<GelbooruImage(id=5106718, filename='bbbdfbf9e883...161753514.png', owner='6498')>
```
### Comments
You can fetch post comments directly from the GelbooruImage container,
```python
post = await gelbooru.get_post(5099841)
await post.get_comments()
[<GelbooruComment(id=2486074, author='Anonymous', created_at='2020-01-28 08:47')>]
```
### Tags
Besides searching for images, you can also pull information on tags as follows,
```python
await gelbooru.tag_list(name='dog ears')
<GelbooruTag(id=773, name='dog_ears', count=22578)>
# Use "name_pattern" to search for partial matches to a specified tag
await gelbooru.tag_list(name_pattern='%splatoon%', limit=4)
[<GelbooruTag(id=892683, name='splatoon_(series)', count=11353)>,
<GelbooruTag(id=759189, name='splatoon_2', count=3488)>,
<GelbooruTag(id=612372, name='aori_(splatoon)', count=2266)>,
<GelbooruTag(id=612374, name='hotaru_(splatoon)', count=2248)>]
```
Raw data
{
"_id": null,
"home_page": "https://github.com/FujiMakoto/pygelbooru",
"name": "pygelbooru",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "gelbooru, anime, artwork, anime artwork, booru",
"author": "Makoto",
"author_email": "FujiMakoto@users.noreply.github.com",
"download_url": "https://files.pythonhosted.org/packages/b0/ea/27b0776b380022c3f3ecf0fbcce020709d686f2dd79e0921190bc9817b3a/pygelbooru-1.0.0.tar.gz",
"platform": null,
"description": "# PyGelbooru\r\n\r\n\r\nPyGelbooru is an unofficial and lightweight asynchronous library for the [Gelbooru](https://gelbooru.com/) API.\r\n\r\n# Installation\r\nThis library requires [Python 3.6](https://www.python.org) or above.\r\n\r\nYou can install the library through pip as follows,\r\n```shell script\r\npip install pygelbooru\r\n```\r\n\r\n## Usage\r\n\r\n### Searching\r\nThe primary use for this library is, naturally, to search for images with specific tags.\r\n\r\nThis can be done as so:\r\n```python\r\nfrom pygelbooru import Gelbooru\r\n\r\n# API key/user ID is optional, but access may be limited without them\r\ngelbooru = Gelbooru('API_KEY', 'USER_ID')\r\n\r\nresults = await gelbooru.search_posts(tags=['dog ears', '1girl'], exclude_tags=['nude'])\r\n[<GelbooruImage(id=5105386, filename='b77e69be0a4b...dde071dc.jpeg', owner='anon2003')>,\r\n <GelbooruImage(id=5105161, filename='bf169f891ebe...02bceb5e.jpeg', owner='cpee')>,\r\n <GelbooruImage(id=5104148, filename='46df3ebe2d41...4316d218e.jpg', owner='danbooru')>,\r\n <GelbooruImage(id=5104080, filename='e8eec23d151e...419293401.png', owner='anon2003')>,\r\n <GelbooruImage(id=5103937, filename='5bf279f3c546...be3fc53c8.jpg', owner='danbooru')>,\r\n ...\r\n ```\r\nTags **can** contain spaces when passed as arguments, they will simply be reformated with underscores before being queried, so you don't need to reformat them yourself.\r\n\r\nResults are returned as a list of GelbooruImage containers. When cast to a string, this will return the image_url,\r\n```python\r\nstr(results[0])\r\n'https://img2.gelbooru.com/images/b7/7e/b77e69be0a4b581eac597527dde071dc.jpeg'\r\n```\r\n\r\nYou can also pull other information returned by the API,\r\nhttps://github.com/FujiMakoto/pygelbooru/blob/master/pygelbooru/gelbooru.py#L32-L47\r\n\r\n### Searching (Random)\r\nIn addition to searching for a large list of images, PyGelbooru also provides a helper method for when you're really just after a single, random image that matches the specified tags.\r\n\r\nThis method will automatically pull a random image from the last 20,000 Gelbooru image submissions.\r\n\r\n```python\r\nresult = await gelbooru.random_post(tags=['cat ears', '1girl', 'cat hood', 'bell'], exclude_tags=['nude'])\r\n<GelbooruImage(id=5106718, filename='bbbdfbf9e883...161753514.png', owner='6498')>\r\n```\r\n\r\n### Comments\r\n\r\nYou can fetch post comments directly from the GelbooruImage container,\r\n```python\r\npost = await gelbooru.get_post(5099841)\r\nawait post.get_comments()\r\n[<GelbooruComment(id=2486074, author='Anonymous', created_at='2020-01-28 08:47')>]\r\n```\r\n\r\n### Tags\r\nBesides searching for images, you can also pull information on tags as follows,\r\n```python\r\nawait gelbooru.tag_list(name='dog ears')\r\n<GelbooruTag(id=773, name='dog_ears', count=22578)>\r\n\r\n# Use \"name_pattern\" to search for partial matches to a specified tag\r\nawait gelbooru.tag_list(name_pattern='%splatoon%', limit=4)\r\n[<GelbooruTag(id=892683, name='splatoon_(series)', count=11353)>,\r\n <GelbooruTag(id=759189, name='splatoon_2', count=3488)>,\r\n <GelbooruTag(id=612372, name='aori_(splatoon)', count=2266)>,\r\n <GelbooruTag(id=612374, name='hotaru_(splatoon)', count=2248)>]\r\n```\r\n",
"bugtrack_url": null,
"license": "gpl-3.0",
"summary": "PyGelbooru is an unofficial and lightweight asynchronous library for Gelbooru compatible API's.",
"version": "1.0.0",
"project_urls": {
"Download": "https://github.com/FujiMakoto/pygelbooru/archive/v0.5.0.tar.gz",
"Homepage": "https://github.com/FujiMakoto/pygelbooru"
},
"split_keywords": [
"gelbooru",
" anime",
" artwork",
" anime artwork",
" booru"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "d680454665c21a121f83b36f9effa89924b9e563744c8ff47875668f2b8519a7",
"md5": "e97d45a8741e2c01c3f47cfd62965d6e",
"sha256": "bda4076da5cdd79e16aa2513165796bcbc8e35f03ab1423a08f5052b1bb59c95"
},
"downloads": -1,
"filename": "pygelbooru-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e97d45a8741e2c01c3f47cfd62965d6e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 19561,
"upload_time": "2025-07-25T10:33:41",
"upload_time_iso_8601": "2025-07-25T10:33:41.425298Z",
"url": "https://files.pythonhosted.org/packages/d6/80/454665c21a121f83b36f9effa89924b9e563744c8ff47875668f2b8519a7/pygelbooru-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "b0ea27b0776b380022c3f3ecf0fbcce020709d686f2dd79e0921190bc9817b3a",
"md5": "c4538d482e9a63db11101b08b79906da",
"sha256": "832fa7329a03bab1e45fa8c891a58084bda701e70ac4d48eae5260eaee4b3655"
},
"downloads": -1,
"filename": "pygelbooru-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "c4538d482e9a63db11101b08b79906da",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 19904,
"upload_time": "2025-07-25T10:33:43",
"upload_time_iso_8601": "2025-07-25T10:33:43.126037Z",
"url": "https://files.pythonhosted.org/packages/b0/ea/27b0776b380022c3f3ecf0fbcce020709d686f2dd79e0921190bc9817b3a/pygelbooru-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-25 10:33:43",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "FujiMakoto",
"github_project": "pygelbooru",
"github_not_found": true,
"lcname": "pygelbooru"
}
JSON
