API Reference

This is the API reference for ao3.py.

Here are the relevant models and functions that allow interaction with AO3.

Client

class ao3.Client(*, session: ClientSession | None = None)

Represents a client that interacts with AO3’s frontend.

Parameters:

session (aiohttp.ClientSession | None, optional) – The asynchronous HTTP session to make requests with. If not passed in, automatically generated. Closing it is not handled automatically by the class.

await login(username: str | None = None, password: str | None = None) → None

Logs into AO3 with the specified credentials.

Parameters:

• username (str | None, optional) – The AO3 account username. By default None.

• password (str | None, optional) – The AO3 account password. By default None.

Raises:

LoginError – Logging into your AO3 account failed, either due to wrong credentials or some other reason.

await get_work(work_id: int) → Work

Returns a work with the given ID.

Parameters:

work_id (int) – The ID to search for.

Returns:

The found work.

Return type:

Work

Raises:

HTTPException – The id could not be used to find a valid work.

await get_series(series_id: int) → Series

Returns a series with the given ID.

Parameters:

series_id (int) – The ID to search for.

Returns:

The found series.

Return type:

Series

Raises:

HTTPException – The id could not be used to find a valid series.

await get_user(username: str) → User

Returns a user with the given username.

Parameters:

username (str) – The username to search for.

Returns:

The found user.

Return type:

User

Raises:

HTTPException – The username could not be used to find a valid user.

await search_works(options: WorkSearchOptions) → WorkSearch

Search for works based in the given options.

Parameters:

options (WorkSearchOptions) – The options with which to narrow the search. See WorkSearchOptions for more information.

Returns:

A search result object.

Return type:

WorkSearch

async for ... in work_search_pages(options: WorkSearchOptions, start: int = 1, stop: int = 2, step: int = 1) → AsyncGenerator[WorkSearch, None]

Returns an asynchronous generator for work search results based on the given options through multiple pages of results. It stops at the first empty results page.

Can only iterate forwards, to reliably prevent requests to nonexistent pages from looping for longer than necessary.

Parameters:

• options (WorkSearchOptions) – The options with which to narrow the search. See WorkSearchOptions for more information.

• start (int, optional) – The starting page. By default 1.

• stop (int, optional) – The stopping page, which won’t be included in the final result. By default 2.

• step (int, optional) – The step size through which to iterate through the pages. By default 1.

Yields:

WorkSearch – The search result object holding the results for a particular page.

await search_people(page: int = 1, any_field: str = '', names: list[str] | None = None, fandoms: list[str] | None = None) → PeopleSearch

Search for people based in the given options.

Parameters:

• page (int, optional) – The page number of the results to get. By default 1.

• any_field (str, optional) – Text which can apply to any of the below fields. By default the empty string.

• names (list[str] | None, optional) – The names of the people to search. By default None.

• fandoms (list[str] | None, optional) – The names of the fandoms within which to search. By default None.

Returns:

A search result object.

Return type:

PeopleSearch

async for ... in people_search_pages(any_field: str = '', names: list[str] | None = None, fandoms: list[str] | None = None, start: int = 1, stop: int = 2, step: int = 1) → AsyncGenerator[PeopleSearch, None]

Returns an asynchronous generator for people search results based on the given options through multiple pages of results. It stops at the first empty results page.

Can only iterate forwards, to reliably prevent requests to nonexistent pages from looping for longer than necessary.

Parameters:

• any_field (str, optional) – Text which can apply to any of the below fields. By default the empty string.

• names (list[str] | None, optional) – The names of the people to search. By default None.

• fandoms (list[str] | None, optional) – The names of the fandoms within which to search. By default None.

• start (int, optional) – The starting page. By default 1.

• stop (int, optional) – The stopping page, which won’t be included in the final result. By default 2.

• step (int, optional) – The step size through which to iterate through the pages. By default 1.

Yields:

PeopleSearch – The search result object holding the results for a particular page.

Raises:

RuntimeError – The start, stop, and step aren’t configured for forward iteration.

await search_bookmarks(options: BookmarkSearchOptions) → BookmarkSearch

Search for bookmarks based in the given options.

Parameters:

options (BookmarkSearchOptions) – The options with which to narrow the search. See BookmarkSearchOptions for more information.

Returns:

A search result object.

Return type:

BookmarkSearch

async for ... in bookmark_search_pages(options: BookmarkSearchOptions, start: int = 1, stop: int = 2, step: int = 1) → AsyncGenerator[BookmarkSearch, None]

Returns an asynchronous generator for bookmark search results based on the given options through multiple pages of results. It stops at the first empty results page.

Can only iterate forwards, to reliably prevent requests to nonexistent pages from looping for longer than necessary.

Parameters:

• options (BookmarkSearchOptions) – The options with which to narrow the search. See BookmarkSearchOptions for more information.

• start (int, optional) – The starting page. By default 1.

• stop (int, optional) – The stopping page, which won’t be included in the final result. By default 2.

• step (int, optional) – The step size through which to iterate through the pages. By default 1.

Yields:

BookmarkSearch – The search result object holding the results for a particular page.

Raises:

RuntimeError – The start, stop, and step aren’t configured for forward iteration.

await search_tags(options: TagSearchOptions) → TagSearch

Search for tags based in the given options.

Parameters:

options (TagSearchOptions) – The options with which to narrow the search. See TagSearchOptions for more information.

Returns:

A search result object.

Return type:

TagSearch

async for ... in tag_search_pages(options: TagSearchOptions, start: int = 1, stop: int = 2, step: int = 1) → AsyncGenerator[TagSearch, None]

Returns an asynchronous generator for tag search results based on the given options through multiple pages of results. It stops at the first empty results page.

Can only iterate forwards, to reliably prevent requests to nonexistent pages from looping for longer than necessary.

Parameters:

• options (TagSearchOptions) – The options with which to narrow the search. See TagSearchOptions for more information.

• start (int, optional) – The starting page. By default 1.

• stop (int, optional) – The stopping page, which won’t be included in the final result. By default 2.

• step (int, optional) – The step size through which to iterate through the pages. By default 1.

Yields:

TagSearch – The search result object holding the results for a particular page.

Raises:

RuntimeError – The start, stop, and step aren’t configured for forward iteration.

Models

Work

class ao3.Work

A work on AO3.

This implements the following:

• Page

• KudoableMixin

• BookmarkableMixin

• SubscribableMixin

• CollectableMixin

property id: int

The work’s ID.

Type:

int

property subable_type: str

The type of this item in respect to AO3’s subscription mechanism.

Type:

str

property kudoable_type: str

The type of this item in respect to AO3’s kudo mechanism.

Type:

str

property url: str

The work’s base URL.

Type:

str

title

The work’s title.

Type:

str

authors

The work’s authors, minimized as ao3.Object instances.

Type:

tuple[Object, …]

summary

The work’s summary.

Type:

str

series

The series this work is a part of, minimized as ao3.Object instances.

Type:

tuple[Object, …]

is_restricted

Whether the work is restricted to logged in users.

Type:

bool

rating

The work’s rating.

e.g. “General Audences”, “Teen And Up Audiences”, “Mature”, “Explicit”, “No Rating”.

Type:

str

warnings

The work’s content warnings.

e.g. “Graphic Depictions of Violence”, “Major Character Death”, “Underage”, etc.

Type:

tuple[str, …]

categories

The work’s category tags.

Type:

tuple[str, …]

fandoms

The fandoms this work is a part of.

Type:

tuple[str, …]

relationships

The work’s relationship tags.

Type:

tuple[str, …]

characters

The work’s character tags.

Type:

tuple[str, …]

freeforms

The work’s additional tags.

Type:

tuple[str, …]

all_tags() → Iterator[str]

An lazy iterator that provides all of this work’s “tags” in one go.

This includes, in order: rating, warnings, categories, fandoms, relationships, characters, and additional tags.

Returns:

An iterator for all the work’s tags.

Return type:

Iterator[str]

Yields:

str – The name of a tag.

language

The language this work is written in.

Type:

Language

date_published

The date this work was first published. Might be None.

Type:

datetime.datetime

date_updated

The date this work was last edited. Might be None.

Type:

datetime.datetime

nwords

The number of words in this work.

Type:

int

nchapters

A tuple for the work’s current and expected chapters.

The expected chapters element might be None if not specified.

Type:

tuple[int | None, int | None]

property is_complete: bool

Whether the work has been completed.

Type:

bool

ncomments

The number of comments on this work.

Type:

int

nkudos

The number of kudos on this work.

Type:

int

nbookmarks

The number of bookmarks on this work.

Type:

int

nhits

The number of hits on this work.

Type:

int

property stats: tuple[int, int, int, int]

A tuple with the most common work stats.

This includes the number of comments, kudos, bookmarks, and hits.

Type:

tuple[int, int, int, int]

await reload() → None

Reloads the item’s corresponding webpage to update its members.

Series

class ao3.Series

A series on AO3.

This implements the following:

• Page

• BookmarkableMixin

• SubscribableMixin

property id: int

The series’s ID.

Type:

int

property subable_type: str

The type of this item in respect to AO3’s subscription mechanism.

Type:

str

property url: str

The series’s base URL.

Type:

str

name

The series name.

Type:

str

creators

The series’s creators, minimized as ao3.Object instances.

Type:

tuple[Object, …]

date_begun

The date the series began.

Might be None, which means unknown.

Type:

datetime.datetime | None

date_updated

The date the series was last updated.

Might be None, which means unknown.

Type:

datetime.datetime | None

description

The series’s description.

Type:

str

notes

Any notes the creators have written for the series.

Type:

str

nwords

The total number of words in the series so far.

Type:

int

nworks

The number of works in the series so far.

Type:

int

is_complete

Whether the series is complete. Defaults to False if unknown.

Type:

bool

nbookmarks

The number of bookmarks on this series.

Type:

int

property stats: tuple[int, int, bool, int]

A tuple with the most common series stats.

This includes the number of words, number of works, completion status, and number of bookmarks.

Type:

tuple[int, int, bool, int]

works_list

A tuple of works that make up this series.

This may take time to load, but will be cached for later references.

Type:

tuple[Work, …]

await reload() → None

Reloads the item’s corresponding webpage to update its members.

User

class ao3.User

A user on AO3.

This implements the following:

• Page

• SubscribableMixin

username

The unique name of the user on AO3.

Type:

str

id: any_property[Self, int]

The user’s ID.

Type:

int

property subable_type: str

The type of this item in respect to AO3’s subscription mechanism.

Type:

str

property url: str

The user’s base URL.

Type:

str

avatar_url

str The URL for the user’s main avatar.

Type:

class

pseuds

A tuple of the user’s pseud names.

Type:

tuple[str, …]

date_joined

The date the user joined AO3. Might be None.

Type:

datetime.datetime | None

bio

The bio blurb on the user’s profile page.

Type:

str

nworks

The number of works this user has written.

Type:

int

nseries

The number of series this user has written.

Type:

int

nbookmarks

The number of bookmarks this user has.

Type:

int

ncollections

The number of collections this user has.

Type:

int

ngifts

The number of gifts this user has been given.

Type:

int

await reload() → None

Reloads the item’s corresponding webpage to update its members.

Object

class ao3.Object(*, id: SupportsInt | str | bytes | bytearray | None = None, name: str | None = None, type: type[object] | None = None)

Represents a generic AO3 object.

This serves as a standin for user items when the full data to form those items isn’t available.

Parameters:

• id (int | None, optional) – The ID of the object. This or name must be provided. Defaults to None.

• name (str | None, optional) – The name of the object. This or id must be provided. Defaults to None.

• type (type[Page] | None, optional) – The type of the object, which can be any Page subclasses. Defaults to None, which is substituted with Object.

id

The ID of the object. Defaults to None.

Type:

int | None, optional

name

The name of the object. Defaults to None.

Type:

str | None, optional

type

The type of the object, which can be any Page subclasses. Defaults to Object.

Type:

type[ao3.abc.Page] | type[Object]

Search

class ao3.Search(http: object, *, payload: Mapping[str, object] | None = None, element: HtmlElement | None = None)

The base class for AO3 search results.

property id: int

The ID of the model. By default 0 for searches.

Type:

int

property search_options: SP

The dataclass of search options that led to these search results.

Type:

SP

abstract property full_total: int

The total number of results for this search, not just what’s on the current page.

Type:

int

results

The parsed search results. Calculated once than cached.

Returns:

A tuple of parsed search results.

Return type:

tuple[R, …]

Raises:

UnloadedError – The item’s HTML hasn’t been loaded and can’t be parsed.

Work Search

class ao3.WorkSearch(http: object, *, payload: Mapping[str, object] | None = None, element: HtmlElement | None = None)

A page of AO3 work search results.

property full_total: int

The total number of results for this search, not just what’s on the current page.

Type:

int

await reload() → None

Reloads the item’s corresponding webpage to update its members.

class ao3.WorkSearchOptions(page: int = 1, any_field: str = '', title: str = '', author: str = '', revised_at: str = '', complete: bool | None = None, crossover: bool | None = None, single_chapter: bool = False, word_count: ~ao3.utils.Constraint | None = None, language_id: ~ao3.enums.Language | None = None, fandom_names: ~collections.abc.Sequence[str] = <factory>, rating_ids: ~ao3.enums.RatingId | None = None, archive_warning_ids: ~collections.abc.Sequence[~ao3.enums.ArchiveWarningId] = <factory>, category_ids: ~collections.abc.Sequence[~ao3.enums.CategoryId] = <factory>, character_names: ~collections.abc.Sequence[str] = <factory>, relationship_names: ~collections.abc.Sequence[str] = <factory>, freeform_names: ~collections.abc.Sequence[str] = <factory>, hits: ~ao3.utils.Constraint | None = None, kudos_count: ~ao3.utils.Constraint | None = None, comments_count: ~ao3.utils.Constraint | None = None, bookmarks_count: ~ao3.utils.Constraint | None = None, excluded_tag_names: ~collections.abc.Sequence[str] = <factory>, sort_column: str = '_score', sort_direction: ~typing.Literal['asc', 'desc'] = 'desc')

A collection of options to use for searching works on AO3.

any_field

Searches all the fields associated with a work in the AO3 database, including summary, notes and tags, but not the full work text. By default the empty string.

Type:

str, optional

title

Text in the titles of works. By default the empty string.

Type:

str, optional

author

Text in the names of authors of works. By default the empty string.

Type:

str, optional

revised_at

By default the empty string.

Type:

str, optional

complete

Whether to filter by completion status and which type. True is only completed, False is only not completed. By default None, which gets both.

Type:

bool | None, optional

crossover

Whether to filter by completion status and which type. True is only crossovers, False is only non-crossovers. By default None.

Type:

bool | None, optional

single_chapter

Whether all results should be single chapters or “oneshots”. By default False.

Type:

bool, optional

word_count

A word count range with an optional minimum and maximum. See Constraint for more info on how to construct that. By default None.

Type:

Constraint | None, optional

language_id

What language to filter by. By default None.

Type:

Language | None, optional

fandom_names

What fandoms to filter by. By default an empty list.

Type:

Sequence[str], optional

rating_ids

What rating to filter by. By default None.

Type:

RatingId | None, optional

archive_warning_ids

A list of archive warnings to filter by. By default an empty list.

Type:

Sequence[ArchiveWarningId], optional

category_ids

A list of categories to filter by. By default an empty list.

Type:

Sequence[CategoryId], optional

character_names

A list of character tags to filter by. By default an empty list.

Type:

Sequence[str], optional

relationship_names

A list of relationship tags to filter by. By default an empty list.

Type:

Sequence[str], optional

freeform_names

A list of freeform tags to filter by. By default an empty list.

Type:

Sequence[str], optional

hits

A word count range with an optional minimum and maximum. See Constraint for more info on how to construct that. By default None.

Type:

Constraint | None, optional

kudos_count

A word count range with an optional minimum and maximum. See Constraint for more info on how to construct that. By default None.

Type:

Constraint | None, optional

comments_count

A word count range with an optional minimum and maximum. See Constraint for more info on how to construct that. By default None.

Type:

Constraint | None, optional

bookmarks_count

A word count range with an optional minimum and maximum. See Constraint for more info on how to construct that. By default None.

Type:

Constraint | None, optional

excluded_tag_names

A list of tags to exclude from the search results. By default an empty list.

Type:

Sequence[str], optional

sort_column

What filter option to sort by. By default “_score”, which means “Best Match”.

Type:

str, optional

sort_direction

What direction to sort by. By default “desc”.

Type:

Literal[“asc”, “desc”], optional

to_dict() → dict[str, Any]

Serialize the dataclass into a query mapping that AO3 will understand.

Returns:

A mapping of the search options with potentially slight modifications.

Return type:

dict[str, Any]

People Search

class ao3.PeopleSearch(http: object, *, payload: Mapping[str, object] | None = None, element: HtmlElement | None = None)

A page of AO3 people search results.

property full_total: int

The total number of results for this search, not just what’s on the current page.

Type:

int

await reload() → None

Reloads the item’s corresponding webpage to update its members.

class ao3.PeopleSearchOptions(page: int = 1, any_field: str = '', names: ~collections.abc.Sequence[str] = <factory>, fandoms: ~collections.abc.Sequence[str] = <factory>)

A collection of options to use for searching people on AO3.

any_field

Searches all the fields associated with a person in the AO3 database. By default the empty string.

Type:

str, optional

names

What usernames to filter by. By default an empty list.

Type:

Sequence[str], optional

fandoms

What fandoms to filter by, i.e. only pulling users that have written in these fandoms. By default an empty list.

Type:

Sequence[str], optional

to_dict() → dict[str, Any]

Serialize the dataclass into a query mapping that AO3 will understand.

Returns:

A mapping of the search options with potentially slight modifications.

Return type:

dict[str, Any]

Bookmark Search

class ao3.BookmarkSearch(http: object, *, payload: Mapping[str, object] | None = None, element: HtmlElement | None = None)

A page of AO3 bookmark search results.

property full_total: int

The total number of results for this search, not just what’s on the current page.

Type:

int

await reload() → None

Reloads the item’s corresponding webpage to update its members.

class ao3.BookmarkSearchOptions(page: int = 1, any_field: str = '', work_tags: ~collections.abc.Sequence[str] = <factory>, type: ~typing.Literal['Work', 'Series', 'External Work'] | None = None, language_id: ~ao3.enums.Language | None = None, work_updated: str = '', any_bookmark_field: str = '', bookmark_tags: ~collections.abc.Sequence[str] = <factory>, bookmarker: str = '', notes: str = '', recommended: bool = False, with_notes: bool = False, bookmark_date: str = '', sort_column: ~typing.Literal['created_at', 'bookmarkable_date'] | None = None)

A collection of options to use for searching bookmarks on AO3.

any_field

Searches all the fields associated with a work that has been bookmarked in the AO3 database. By default the empty string.

Type:

str, optional

work_tags

What tags to filter by that are on the actual bookmarked work. By default an empty list.

Type:

Sequence[str], optional

type

What type of bookmarked work to filter by. By default None.

Type:

Literal[“Work”, “Series”, “External Work”] | None , optional

language_id

What language to filter by. By default None.

Type:

Language | None, optional

work_updated

A range of time within which the bookmarked work was last updated. By default the empty string.

Type:

str, optional

any_bookmark_field

Searches all the fields associated with a bookmark in the AO3 database, including notes and tags. By default the empty string.

Type:

str, optional

bookmark_tags

A list of bookmark tags to filter by. These are tags not present on the bookmarked work itself. By default an empty list.

Type:

Sequence[str], optional

bookmarker

Text in the names of the bookmarkers to filter by. By default the empty string.

Type:

str, optional

notes

Terms in the notes of the bookmarks to filter by. By default the empty string.

Type:

str, optional

recommended

Whether to limit the search to bookmarks that have been recommended. By default False.

Type:

bool, optional

with_notes

Whether to limit the search to bookmarks that have notes. By default False.

Type:

bool, optional

sort_column

What filter option to sort by. By default “_score”, which means “Best Match”.

Type:

Literal[“created_at”, “bookmarkable_date”] | None, optional

to_dict() → dict[str, Any]

Serialize the dataclass into a query mapping that AO3 will understand.

Returns:

A mapping of the search options with potentially slight modifications.

Return type:

dict[str, Any]

Tag Search

class ao3.TagSearch(http: object, *, payload: Mapping[str, object] | None = None, element: HtmlElement | None = None)

A page of AO3 tag search results.

property full_total: int

The total number of results for this search, not just what’s on the current page.

Type:

int

await reload() → None

Reloads the item’s corresponding webpage to update its members.

class ao3.TagSearchOptions(page: int = 1, name: str = '', fandoms: ~collections.abc.Sequence[str] = <factory>, type: ~typing.Literal['Fandom', 'Character', 'Relationship', 'Freeform'] | None = None, wranging_status: bool | None = None, sort_column: ~typing.Literal['name', 'created_at'] = 'name', sort_direction: ~typing.Literal['asc', 'desc'] = 'asc')

A collection of options to use for searching people on AO3.

any_field

Searches all the fields associated with a person in the AO3 database. By default the empty string.

Type:

str, optional

names

What text in usernames to filter by. By default the empty string.

Type:

str, optional

fandoms

What fandoms to filter by, i.e. only pulling tags that are specific to these fandoms. By default an empty list.

Type:

Sequence[str], optional

type

What type of high-level tag to filter by. By default None.

Type:

Literal[“Fandom”, “Character”, “Relationship”, “Freeform”] | None, optional

wranging_status

Whether to limit tags by a particular wrangling status. True is canonical, False is non-canonical, and None is all. By default None.

Type:

bool | None, optional

sort_direction

What direction to sort by. By default “desc”.

Type:

Literal[“asc”, “desc”], optional

to_dict() → dict[str, Any]

Serialize the dataclass into a query mapping that AO3 will understand.

Returns:

A mapping of the search options with potentially slight modifications.

Return type:

dict[str, Any]

ABCs and Mixins

class ao3.abc.Page(*args, **kwargs)

An protocol/ABC that details the common members and operations of AO3 items.

id

The item’s ID. Unique for all items within their categories, excluding search-related ones that default to 0.

Type:

int

property raw_element: HtmlElement | None

A representation of the raw HTML for this item’s corresponding AO3 webpage.

If not provided, then this is None.

Type:

html.HtmlElement | None

abstractmethod await reload() → None

Reloads the item’s corresponding webpage to update its members.

class ao3.abc.KudoableMixin

A mixin that adds kudo-giving members and functionality to AO3 items that can receive kudos.

The following implement this mixin:

• ao3.Work

This mixin must also implement ao3.abc.Page.

property kudoable_type: str

The type of this item in respect to AO3’s kudo mechanism.

Type:

str

await give_kudos() → None

Give this item a kudo. Currently limited to works.

Fails if a valid auth token can’t be found.

Raises:

• AuthError – Invalid authenticity token was used (might be expired or not logged in).

• KudoError – Something went wrong in the kudoing process.

class ao3.abc.BookmarkableMixin

A mixin that adds bookmark-related members and functionality to AO3 items that can be bookmarked.

The following implement this mixin:

• ao3.Work

• ao3.Series

This mixin must also implement ao3.abc.Page.

await bookmark(notes: str = '', tags: list[str] | None = None, collections: list[str] | None = None, private: bool = False, recommend: bool = False, as_pseud: str | None = None) → None

Adds a bookmark corresponding to this item for the current logged-in user.

Be careful — you can bookmark the same work multiple times.

Parameters:

• notes (str, optional) – The notes to add to this bookmark. By default “”.

• tags (list[str] | None, optional) – The tags to add to this bookmark. By default None.

• collections (list[str] | None, optional) – The collections to add this bookmark to. By default None.

• private (bool, optional) – Whether to make this bookmark private. By default False.

• recommend (bool, optional) – Whether to recommend this bookmark. By default False.

• as_pseud (str | None, optional) – Which pseud to make this bookmark as. By default None, which means the default pseud will be used.

Raises:

• AuthError – Invalid authenticity token was used (might be expired or not logged in).

• UnloadedError – The item hasn’t been loaded.

• BookmarkError – Something went wrong in the bookmarking process.

• PseudError – ID for specified or default pseud could not be found.

await delete_bookmark() → None

Removes a bookmark corresponding to this item.

Raises:

• AuthError – Invalid authenticity token was used (might be expired or not logged in).

• BookmarkError – Something went wrong in the bookmarking process.

class ao3.abc.SubscribableMixin

A mixin that adds subscription-related members and functionality to AO3 items that can be subscribed to.

The following implement this mixin:

• ao3.Work

• ao3.Series

• ao3.User

This mixin must also implement ao3.abc.Page.

property subable_type: str

The type of this item in respect to AO3’s subscription mechanism.

Type:

str

await subscribe() → None

Subscribes the current logged-in user to this item.

Be careful — you can subscribe to the same work multiple times.

Raises:

• AuthError – Invalid authenticity token was used (might be expired or not logged in).

• SubscribeError – Something went wrong in the subscription process.

await unsubscribe() → None

Removes a subscription corresponding to this item.

Raises:

• AuthError – Invalid authenticity token was used (might be expired or not logged in).

• SubscribeError – Something went wrong in the subscription process.

class ao3.abc.CommentableMixin

class ao3.abc.CollectableMixin

A mixin that adds collection-related members and functionality to AO3 items that can be collected.

The following implement this mixin:

• ao3.Work

This mixin must also implement ao3.abc.Page.

await collect(collections: list[str]) → None

Invite and/or collect this item to a list of collections.

Raises:

• AuthError – Invalid authenticity token was used (might be expired or not logged in).

• CollectError – Something went wrong in the collection process.

Enumerations

class ao3.RatingId(value)

An enumeration.

class ao3.ArchiveWarningId(value)

An enumeration.

class ao3.CategoryId(value)

An enumeration.

class ao3.Language(value)

An enumeration.

class ao3.FandomKey(value)

An enumeration.

Utilities

class ao3.utils.Constraint(min_val: int = 0, max_val: int | None = None)

A representation for a constraint on integer amounts via a range.

min_val

The lower end of the constraint. Defaults to 0.

Type:

int, default=0

max_val

The upper bound of the constraint. Defaults to None.

Type:

int | None, optional

ao3.utils.get_id_from_url(url: str, *, will_raise: bool = False) → int | None

Get the work/series ID from an AO3 website url.

Parameters:

• url (str) – The AO3 url. Could be for a series or a work.

• will_raise (bool, optional) – Whether to raise an exception if an id is not found in the given string. Defaults to False.

Returns:

The work/series ID, or None if not found.

Return type:

int | None

Raises:

InvalidURLError – The given URL doesn’t match the expected AO3 work/series URL structure.

Exceptions

exception ao3.AO3Exception

Base exception for AO3.

exception ao3.HTTPException(response: ClientResponse, message: str | None = None)

Exception that’s raised when something goes wrong during an HTTP request.

Parameters:

• response (aiohttp.ClientResponse) – The HTTP response that caused this error.

• message (str) – The given message accompanying this error to be added to the error display.

response

The HTTP response that caused this error.

Type:

aiohttp.ClientResponse

status

The HTTP status or code of the response.

Type:

int

text

The message accompanying this error that will be part of the error display.

Type:

str

exception ao3.LoginFailure

Exception that’s raised when an attempt to log in to AO3 fails.

exception ao3.UnloadedError(message: str | None = None)

Exception that’s raised when the content of an AO3 object hasn’t been loaded, but accessing it was attempted.

exception ao3.AuthError(message: str | None = None)

Exception that’s raised when the authentication token for the AO3 session is invalid.

exception ao3.PseudError(pseud: str | None = None)

Exception that’s raised when a pseud’s ID couldn’t be found.

exception ao3.KudoError(message: str | None = None)

Exception that’s raised when attempting to give a kudo fails.

exception ao3.BookmarkError(message: str | None = None)

Exception that’s raised when attempting to create or access a bookmark fails.

exception ao3.SubscribeError(message: str | None = None)

Exception that’s raised when attempting to create or access a subscription fails.

exception ao3.CollectError(message: str | None = None)

Exception that’s raised when attempting to invite a work to a collection fails.

exception ao3.InvalidURLError

Exception that’s raised when an invalid AO3 url was passed in.

exception ao3.DuplicateCommentError

Exception that’s raised when attempting to post a comment that already exists.

exception ao3.DownloadError

Exception that’s raised when downloading an AO3 work fails.