# waifuim.py
[](https://pypi.org/project/waifuim.py/)
[](https://pypi.org/project/waifuim.py/)
[](https://github.com/Waifu-im/waifuim.py/blob/main/LICENSE)
A Python wrapper for waifu.im API.
## Table of Contents
- [Installation](#Installation)
- [Usage](#Usage)
- [License](#License)
## Installation
**Python 3.6 or higher is required.**
Install from PyPI
```shell
$ pip install waifuim.py
```
Install from source
```shell
$ pip install git+https://github.com/Waifu-im/waifuim.py
```
## Usage
For now, you can only use WaifuAioClient which is async. Maybe a sync client will be released in the future.
Most of the methods returns an `Image` instance, the attributes are the same from the ones returned by the API.
### Examples with WaifuAioClient
```python
import asyncio
from waifuim import WaifuAioClient
async def main():
wf = WaifuAioClient()
# Get a completely random image
image = await wf.search()
# Get an image by tags
image = await wf.search(
included_tags=['waifu','maid'],
excluded_tags=['ero'],
)
image = await wf.search(
excluded_tags=['maid'],
is_nsfw='null',
height="<=252"
)
# Get sfw waifu images ordered by FAVORITES
images = await wf.search(
included_tags=['waifu'],
is_nsfw='null',
many=True,
order_by='FAVORITES',
)
# Get a user favorites
favorites = await wf.fav(
token='if not provided, use the one in the client constructor',
)
# Edit your favorites
await wf.fav_delete(3133)
await wf.fav_insert(
3133,
user_id=11243585148445,
token='user_id and token are optional',
)
fav_state = await wf.fav_toggle(4401)
# will be equal to 'INSERTED' or 'DELETED'
await wf.close()
# You can also use a context manager but for multiple request it is not recommended
async with WaifuAioClient() as wf:
# Do your stuff
asyncio.run(main())
```
### The Image and Tag instance
In most of the case the methods will return an `Image` instance.
The attributes are the same as the json keys that the api returns.
```python
image = await wf.search()
>>> <waifuim.types.Image object at 0x76217ccf10>
image.url
>>> 'https://cdn.waifu.im/1982.jpg'
str(image)
>>> 'https://cdn.waifu.im/1982.jpg'
image.signature
>>> aa48cd9dc6b64367
image.tags[0]
>>> <waifuim.types.Tag object at 0x73214ccf10>
image.tags[0].name
>>> 'waifu'
```
### Some useful kwargs in the constructor
```python
from waifuim import WaifuAioClient
wf = WaifuAioClient(
session=an_aiohttpClientSession_created_asynchronously,
app_name="TheNameOfYourApplication",
token="The default token to use in routes requiring authentication.",
)
# ...
```
## License
MIT © [Buco](https://github.com/Waifu-im/waifuim.py/blob/main/LICENSE)
Raw data
{
"_id": null,
"home_page": "https://github.com/Waifu-im/waifuim.py",
"name": "waifuim.py",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": null,
"author": "Buco",
"author_email": "bucolo33fr@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/11/30/b2935afe6fb1b5387664150bc0332e5c39ba5ffd22e570c00c719639819e/waifuim.py-4.3.0.tar.gz",
"platform": null,
"description": "# waifuim.py\r\n[](https://pypi.org/project/waifuim.py/)\r\n[](https://pypi.org/project/waifuim.py/)\r\n[](https://github.com/Waifu-im/waifuim.py/blob/main/LICENSE)\r\n\r\nA Python wrapper for waifu.im API.\r\n\r\n## Table of Contents\r\n- [Installation](#Installation)\r\n- [Usage](#Usage)\r\n- [License](#License)\r\n\r\n## Installation\r\n**Python 3.6 or higher is required.**\r\n\r\nInstall from PyPI\r\n```shell\r\n$ pip install waifuim.py\r\n```\r\n\r\nInstall from source\r\n```shell\r\n$ pip install git+https://github.com/Waifu-im/waifuim.py\r\n```\r\n\r\n## Usage\r\nFor now, you can only use WaifuAioClient which is async. Maybe a sync client will be released in the future.\r\nMost of the methods returns an `Image` instance, the attributes are the same from the ones returned by the API.\r\n\r\n### Examples with WaifuAioClient\r\n```python\r\nimport asyncio\r\n\r\nfrom waifuim import WaifuAioClient\r\n\r\nasync def main():\r\n\r\n wf = WaifuAioClient()\r\n \r\n # Get a completely random image\r\n image = await wf.search()\r\n \r\n # Get an image by tags\r\n image = await wf.search(\r\n included_tags=['waifu','maid'],\r\n excluded_tags=['ero'],\r\n )\r\n\r\n image = await wf.search(\r\n excluded_tags=['maid'],\r\n is_nsfw='null',\r\n height=\"<=252\"\r\n )\r\n \r\n # Get sfw waifu images ordered by FAVORITES\r\n images = await wf.search(\r\n included_tags=['waifu'],\r\n is_nsfw='null',\r\n many=True,\r\n order_by='FAVORITES',\r\n )\r\n \r\n # Get a user favorites\r\n favorites = await wf.fav(\r\n token='if not provided, use the one in the client constructor',\r\n )\r\n \r\n # Edit your favorites\r\n await wf.fav_delete(3133)\r\n await wf.fav_insert(\r\n 3133,\r\n user_id=11243585148445,\r\n token='user_id and token are optional',\r\n )\r\n fav_state = await wf.fav_toggle(4401)\r\n # will be equal to 'INSERTED' or 'DELETED'\r\n \r\n await wf.close()\r\n \r\n # You can also use a context manager but for multiple request it is not recommended\r\n \r\n async with WaifuAioClient() as wf:\r\n # Do your stuff\r\n\r\nasyncio.run(main())\r\n```\r\n\r\n### The Image and Tag instance\r\nIn most of the case the methods will return an `Image` instance.\r\nThe attributes are the same as the json keys that the api returns.\r\n```python\r\n\r\nimage = await wf.search()\r\n>>> <waifuim.types.Image object at 0x76217ccf10>\r\n\r\nimage.url\r\n>>> 'https://cdn.waifu.im/1982.jpg'\r\n\r\nstr(image)\r\n>>> 'https://cdn.waifu.im/1982.jpg'\r\n\r\nimage.signature\r\n>>> aa48cd9dc6b64367\r\n\r\nimage.tags[0]\r\n>>> <waifuim.types.Tag object at 0x73214ccf10>\r\n\r\nimage.tags[0].name\r\n>>> 'waifu'\r\n```\r\n\r\n### Some useful kwargs in the constructor\r\n```python\r\nfrom waifuim import WaifuAioClient\r\n\r\nwf = WaifuAioClient(\r\n session=an_aiohttpClientSession_created_asynchronously,\r\n app_name=\"TheNameOfYourApplication\",\r\n token=\"The default token to use in routes requiring authentication.\",\r\n)\r\n\r\n# ...\r\n```\r\n\r\n## License\r\nMIT \u00c2\u00a9 [Buco](https://github.com/Waifu-im/waifuim.py/blob/main/LICENSE)\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Python wrapper for waifu.im API.",
"version": "4.3.0",
"project_urls": {
"Homepage": "https://github.com/Waifu-im/waifuim.py",
"Issue tracker": "https://github.com/Waifu-im/waifuim.py/issues"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "1130b2935afe6fb1b5387664150bc0332e5c39ba5ffd22e570c00c719639819e",
"md5": "143d5bf72f5113dbff4c3fc7850828d7",
"sha256": "4c0293f7f93d5166160f789d120a3c4f350f9e0aae756b686f33da8b5e4d9645"
},
"downloads": -1,
"filename": "waifuim.py-4.3.0.tar.gz",
"has_sig": false,
"md5_digest": "143d5bf72f5113dbff4c3fc7850828d7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 8911,
"upload_time": "2024-03-31T15:45:55",
"upload_time_iso_8601": "2024-03-31T15:45:55.725763Z",
"url": "https://files.pythonhosted.org/packages/11/30/b2935afe6fb1b5387664150bc0332e5c39ba5ffd22e570c00c719639819e/waifuim.py-4.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-31 15:45:55",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Waifu-im",
"github_project": "waifuim.py",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "waifuim.py"
}
JSON
