# e621
e621 is a feature-rich high-level e621 and e926 API wrapper.
It provides access to almost all of the endpoints available. The only exceptions are unstable and admin-only endpoints.
e621 API documentation is currently highly undocumented, unstable, and sometimes even untruthful. We tried to wrap it in a sanest possible way, properly documenting all the possible ways to interact with it. However, if you still have any questions, bugs to report, or features to request -- please, create an issue on our [github page]("https://github.com/Hmiku8338/e621-py-stable") and we will reply as soon as we can.
## Installation
```bash
pip install e621-stable
```
## Quickstart
We translate everything the API returns to python data types created with pydantic. Everything is 100% typehinted so you get autocomplete everywhere and your IDE will warn you if you are sending invalid arguments or using nonexistent attributes.
### Creating the api client
* To create the most basic client, all you need to do is
```python
from e621 import E621
api = E621()
```
* If you wish to get information about your account, use your blacklist or create/update/delete any of the e621's entities, you will have to create an api key and put it into the API client as such:
```python
api = E621(("your_e621_login", "your_e621_api_key"))
```
### Searching
The majority of the endpoints allow you to query for a list of their entities, be it posts, pools or tags.
* To search for posts that match the "canine" but not the "3d" tag:
```python
posts = api.posts.search("canine -3d")
# Or
posts = api.posts.search(["canine", "-3d"])
```
* To search for pools whose names start with "hello" and end with "kitty":
```python
posts = api.pools.search(name_matches="hello*kitty")
```
* e621 searching api is paginated, which means that if you want to get a lot of posts, you will have to make multiple requests with a different "page" parameter. To simplify interactions with paginated queries, all of our searching endpoints support the "limit", "page", and "ignore_pagination" parameters. If you wish to get a specific number of entities, simply pass the "limit" and "ignore_pagination" arguments:
```python
tags = api.tags.search(name_matches="large_*", limit=900, ignore_pagination=True)
```
### Accessing Attributes
When you have retrieved the entities, you can access any of their attributes without dealing with json.
```python
for post in posts:
print(post.score.total, post.all_tags, post.relationships.parent_id)
with open(f"{post.id}.{post.file.ext}", "wb") as f:
f.write(requests.get(post.file.url).content)
```
### Getting
Many entities that have unique identifiers (such as post_id or username) support indexing using these ids:
```python
post = api.posts.get(3291457)
posts = api.posts.get([3291457, 3069995])
pool = api.pools.get(28232)
user = api.users.get("fox")
```
### Updating
```python
api.posts.update(3291457, tag_string_diff="canine -male", description="Rick roll?")
```
### Creating
```python
from pathlib import Path
api.posts.create(
tag_string="canine 3d rick_roll",
file=Path("path/to/rickroll.webm"),
rating="s",
sources=[],
description="Rick roll?"
)
```
Raw data
{
"_id": null,
"home_page": "https://github.com/Hmiku8338/e621-py-stable",
"name": "e621-stable",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7,<4.0",
"maintainer_email": "",
"keywords": "e621.net,e621,e926.net,e926,furry,yiff,api,booru",
"author": "Hmiku8338",
"author_email": "hmiku8338@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/ab/59/9d5cff852910812a151e16f59cd8ed661852b90090c40bf190688125bab7/e621_stable-1.0.4.tar.gz",
"platform": null,
"description": "# e621\n\ne621 is a feature-rich high-level e621 and e926 API wrapper.\n\nIt provides access to almost all of the endpoints available. The only exceptions are unstable and admin-only endpoints.\n\ne621 API documentation is currently highly undocumented, unstable, and sometimes even untruthful. We tried to wrap it in a sanest possible way, properly documenting all the possible ways to interact with it. However, if you still have any questions, bugs to report, or features to request -- please, create an issue on our [github page](\"https://github.com/Hmiku8338/e621-py-stable\") and we will reply as soon as we can.\n\n## Installation\n\n```bash\npip install e621-stable\n```\n\n## Quickstart\n\nWe translate everything the API returns to python data types created with pydantic. Everything is 100% typehinted so you get autocomplete everywhere and your IDE will warn you if you are sending invalid arguments or using nonexistent attributes.\n\n### Creating the api client\n\n* To create the most basic client, all you need to do is\n\n```python\nfrom e621 import E621\n\napi = E621()\n```\n\n* If you wish to get information about your account, use your blacklist or create/update/delete any of the e621's entities, you will have to create an api key and put it into the API client as such:\n\n```python\napi = E621((\"your_e621_login\", \"your_e621_api_key\"))\n```\n\n### Searching\n\nThe majority of the endpoints allow you to query for a list of their entities, be it posts, pools or tags.\n\n* To search for posts that match the \"canine\" but not the \"3d\" tag:\n\n```python\nposts = api.posts.search(\"canine -3d\")\n# Or\nposts = api.posts.search([\"canine\", \"-3d\"])\n```\n\n* To search for pools whose names start with \"hello\" and end with \"kitty\":\n\n```python\nposts = api.pools.search(name_matches=\"hello*kitty\")\n```\n\n* e621 searching api is paginated, which means that if you want to get a lot of posts, you will have to make multiple requests with a different \"page\" parameter. To simplify interactions with paginated queries, all of our searching endpoints support the \"limit\", \"page\", and \"ignore_pagination\" parameters. If you wish to get a specific number of entities, simply pass the \"limit\" and \"ignore_pagination\" arguments:\n\n```python\ntags = api.tags.search(name_matches=\"large_*\", limit=900, ignore_pagination=True)\n```\n\n### Accessing Attributes\n\nWhen you have retrieved the entities, you can access any of their attributes without dealing with json.\n\n```python\nfor post in posts:\n print(post.score.total, post.all_tags, post.relationships.parent_id)\n with open(f\"{post.id}.{post.file.ext}\", \"wb\") as f:\n f.write(requests.get(post.file.url).content)\n```\n\n### Getting\n\nMany entities that have unique identifiers (such as post_id or username) support indexing using these ids:\n\n```python\npost = api.posts.get(3291457)\nposts = api.posts.get([3291457, 3069995])\npool = api.pools.get(28232)\nuser = api.users.get(\"fox\")\n```\n\n### Updating\n\n```python\napi.posts.update(3291457, tag_string_diff=\"canine -male\", description=\"Rick roll?\")\n```\n\n### Creating\n\n```python\nfrom pathlib import Path\n\napi.posts.create(\n tag_string=\"canine 3d rick_roll\",\n file=Path(\"path/to/rickroll.webm\"),\n rating=\"s\",\n sources=[],\n description=\"Rick roll?\"\n)\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "e621.net API wrapper written in Python",
"version": "1.0.4",
"split_keywords": [
"e621.net",
"e621",
"e926.net",
"e926",
"furry",
"yiff",
"api",
"booru"
],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "8643d3690509824d49ec3b12879c8fe6",
"sha256": "bedbf0a881de162b1f3a80178676207e2c9ce191ba06ea7035c83c976f597e44"
},
"downloads": -1,
"filename": "e621_stable-1.0.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8643d3690509824d49ec3b12879c8fe6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7,<4.0",
"size": 14944,
"upload_time": "2022-12-25T13:13:58",
"upload_time_iso_8601": "2022-12-25T13:13:58.674983Z",
"url": "https://files.pythonhosted.org/packages/8d/58/7a7131eb81992fda69c6a5e8931aeec6b9576760b0dcce9d7dd2397cb651/e621_stable-1.0.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"md5": "aca7c7733a2be51b8b7b2b1a7a612205",
"sha256": "bd3a24dc2b40b3469b9ba650fa9c278b5bf25360f683052719eaf023ce052f97"
},
"downloads": -1,
"filename": "e621_stable-1.0.4.tar.gz",
"has_sig": false,
"md5_digest": "aca7c7733a2be51b8b7b2b1a7a612205",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7,<4.0",
"size": 14865,
"upload_time": "2022-12-25T13:14:00",
"upload_time_iso_8601": "2022-12-25T13:14:00.915474Z",
"url": "https://files.pythonhosted.org/packages/ab/59/9d5cff852910812a151e16f59cd8ed661852b90090c40bf190688125bab7/e621_stable-1.0.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-12-25 13:14:00",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "Hmiku8338",
"github_project": "e621-py-stable",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "e621-stable"
}
JSON
