aioe621 
A simple asynchronous httpx+pydantic wrapper over the e621 API.
The library API is considered unstable until version 1.0.0. Minor releases may include breaking changes.
Quickstart
from aioe621 import Client
from aioe621.schemas.posts import Post
import asyncio
# a user agent is required
client = Client(user_agent="MyProject/1.0 (by username on e621)")
async def main() -> None:
post: Post = await client.posts.get(5937863)
print(f"i love {post.tags.artist[0]}!!!")
asyncio.run(main())
Installation
pip install aioe621
or using uv (recommended):
uv add aioe621
TagSet
TagSet is a small query-building helper around e621's tag syntax. It behaves mostly like a normal set[str]
(it actually inherits from actually frozenset[Tag]), but adds convenient methods for composing searches.
Using TagSet is not required. All endpoints that accept tags also work with other "Tag"-like or "Tag list"-like
types (including plain strings and iterables of strings). TagSet is provided as a convenience for building, combining,
and reusing complex queries.
Build searches fluently
# find posts by the same artists, but include a specific feature
query = post.tags.artist.with_tag("tail")
print(str(query)) # cool_artist tail
posts = await client.posts.list(tags=query)
Exclude tags
Negated tags are useful for filtering out things you don't want:
# with the same species, but no humans
# each list item here is like a blacklist line in e621
query = post.tags.species.with_blacklist(["human"])
# or you could just do .with_tag("-human")
Which for a post of a dog with a cat produces the equivalent of canine feline -human
Combine tag groups
Tag groups can be merged together:
# search for the characters of the specific artists and copyrights
query = post.tags.character + post.tags.species + post.tags.copyright
Build reusable search presets
Because TagSet is composable, you can keep common searches around:
from aioe621.objects import TagSet
from aioe621.enums import PostRating
anthro_pups_with_fangs = TagSet({"fangs", "canine", "-feral"})
rating = PostRating.SAFE # just "s" or "safe" also works!
favorites = anthro_pups_with_fangs.with_rating(rating)
All TagSet methods
| Method | Purpose |
|---|---|
+ |
Combine tag groups |
with_tag() |
Add a tag |
with_tags() |
Add multiple tags |
with_blacklist() |
Add and negate lists of TagSet, like the e621 blacklist |
negated_tags() |
Negate tags |
with_order() |
Add search ordering |
with_rating() |
Add search rating |
flattened() |
Flatten into a str |
Schema helpers
Some schema objects provide small helper methods that use the attached client to fetch related resources.
Post
# get posts that have this post as their parent
children: Sequence[Post] = await post.fetch_children()
# get the parent if it has one
parent: Post | None = await post.fetch_parent()
Pool
pool = await client.pools.get(12345)
# this is only the ids
print(pool.post_ids) # [69420, 42069, ...]
# fetch the full Post objects
posts: list[Post] = await pool.fetch_posts()
print(posts[0].rating) # PostRating.EXPLICIT
Currently implemented API endpoints
| e621 API | aioe621 |
|---|---|
GET /posts.json |
.posts.list |
GET /posts/{id}.json |
.posts.get |
GET /posts/random.json |
.posts.random |
GET /popular.json |
.posts.popular |
GET /tags.json |
.tags.list and tags.get_by_name |
GET /tags/{id}.json |
.tags.get |
GET /pools.json |
.pools.list |
GET /pools/{id}.json |
.pools.get |
GET /forum_posts.json |
.forum.posts |
GET /forum_posts/{id}.json |
.forum.post |
GET /forum_topics.json |
.forum.topics |
GET /forum_topics/{id}.json |
.forum.topic |
Metadata
Release files for aioe621 0.10.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| aioe621-0.10.0.tar.gz | 12.2 kB | Without provenance | Details for aioe621-0.10.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| aioe621-0.10.0-py3-none-any.whl | Python 3 | none | any | Details for aioe621-0.10.0-py3-none-any.whl |
Total release size: 30.2 kB
Release files / aioe621-0.10.0.tar.gz
| Download URL | aioe621-0.10.0.tar.gz |
|---|---|
| Size | 12.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
90e79b129881be9f69fb3bc8c2a36a4b3a7de58062160df596715fc02b977975
|
|
BLAKE2b-256 checksum How to use checksums |
977c0559260d4d72ceac9a7871ba732f1579211255a1ae4247df1f10fe52b8dc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.11.31 {"installer":{"name":"uv","version":"0.11.31","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / aioe621-0.10.0-py3-none-any.whl
| Download URL | aioe621-0.10.0-py3-none-any.whl |
|---|---|
| Size | 18.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d3177fc1b5ef77bb4889d7bc8a662b20e13e195e895f54088b0510ea027f5742
|
|
BLAKE2b-256 checksum How to use checksums |
f780d148184717dffc32242f0edbb90edbd4363f091878a393fbcd1b318e61ad
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.11.31 {"installer":{"name":"uv","version":"0.11.31","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for aioe621 0.10.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.