Skip to main content

aioe621 GitHub Tag

uv PyPI Python Version

GitHub License GitHub Actions Workflow Status

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)

Source distribution for aioe621 0.10.0
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)

Table of built distributions (wheels) for aioe621 0.10.0
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page