ao3-py 2025.1.1__tar.gz

ao3_py-2025.1.1/.github/workflows/pypi.yml

@@ -0,0 +1,19 @@
+name: pypi
+
+on: push
+
+jobs:
+  pypi:
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@master
+      - uses: actions/setup-python@master
+        with:
+          python-version: "3.x"
+      - run: |
+          python -m pip install build --user
+          python -m build --sdist --wheel --outdir dist
+      - uses: pypa/gh-action-pypi-publish@master
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}

ao3_py-2025.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 OrganRemoved
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ao3_py-2025.1.1/PKG-INFO

@@ -0,0 +1,55 @@
+Metadata-Version: 2.4
+Name: ao3-py
+Version: 2025.1.1
+Summary: an unofficial python sdk for Archive Of Our Own (AO3)
+License: MIT License
+License-File: LICENSE
+Requires-Python: >=3
+Requires-Dist: beautifulsoup4
+Requires-Dist: lxml
+Requires-Dist: requests
+Description-Content-Type: text/markdown
+
+# ao3-py
+
+An unofficial python sdk for [Archive Of Our Own (AO3)](https://archiveofourown.org).
+
+## Feature
+
+- Completely type hint
+- Object orient
+- Lazy loading
+
+## Quick Start
+
+### Installation
+
+#### Install from PYPI
+```sh
+pip install --no-cache --upgrade ao3-py
+```
+
+#### Install from Github
+
+```sh
+pip install --no-cache --upgrade git+https://github.com/OrganRemoved/ao3-py.git
+```
+
+or
+
+```sh
+pip install --no-cache --upgrade https://github.com/OrganRemoved/ao3-py/archive/refs/heads/main.zip
+```
+
+### Example
+```python
+from ao3 import AO3
+
+client = AO3()
+
+client.get_fandom(...)
+
+client.get_tag(...)
+
+client.get_work(...)
+```

ao3_py-2025.1.1/README.md

@@ -0,0 +1,43 @@
+# ao3-py
+
+An unofficial python sdk for [Archive Of Our Own (AO3)](https://archiveofourown.org).
+
+## Feature
+
+- Completely type hint
+- Object orient
+- Lazy loading
+
+## Quick Start
+
+### Installation
+
+#### Install from PYPI
+```sh
+pip install --no-cache --upgrade ao3-py
+```
+
+#### Install from Github
+
+```sh
+pip install --no-cache --upgrade git+https://github.com/OrganRemoved/ao3-py.git
+```
+
+or
+
+```sh
+pip install --no-cache --upgrade https://github.com/OrganRemoved/ao3-py/archive/refs/heads/main.zip
+```
+
+### Example
+```python
+from ao3 import AO3
+
+client = AO3()
+
+client.get_fandom(...)
+
+client.get_tag(...)
+
+client.get_work(...)
+```

ao3_py-2025.1.1/ao3/ao3.py

@@ -0,0 +1,52 @@
+import logging
+from typing import Literal
+
+import requests
+
+from ao3.fandom import Fandom
+from ao3.tag import Tag
+from ao3.work import Work
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="[%(asctime)s][%(levelname)s][%(module)s:%(funcName)s:%(lineno)d]: %(message)s",
+)
+
+
+class AO3:
+    def __init__(self) -> None:
+        self.session = requests.Session()
+
+    def get_fandom(
+        self,
+        fandom: Literal[
+            "Anime & Manga",
+            "Books & Literature",
+            "Cartoons & Comics & Graphic Novels",
+            "Celebrities & Real People",
+            "Movies",
+            "Music & Bands",
+            "Other Media",
+            "Theater",
+            "TV Shows",
+            "Video Games",
+            "Uncategorized Fandoms",
+        ],
+    ) -> Fandom:
+        return Fandom(session=self.session, name=fandom)
+
+    def get_tag(self, tag: str, page: int = 1, view_adult: bool = True) -> Tag:
+        return Tag(
+            session=self.session,
+            name=tag,
+            href=f"/tags/{tag}/works",
+            page=page,
+            view_adult=view_adult,
+        )
+
+    def get_work(self, work_id: int, chapter_id: int | None = None) -> Work:
+        return (
+            Work(session=self.session, href=f"/works/{work_id}/chapters/{chapter_id}")
+            if chapter_id
+            else Work(session=self.session, href=f"/works/{work_id}")
+        )

ao3_py-2025.1.1/ao3/ao3.pyi

@@ -0,0 +1,28 @@
+from typing import Literal
+
+from ao3.fandom import Fandom
+from ao3.tag import Tag
+from ao3.work import Work
+
+class AO3:
+    def __init__(self) -> None: ...
+    def get_fandom(
+        self,
+        fandom: Literal[
+            "Anime & Manga",
+            "Books & Literature",
+            "Cartoons & Comics & Graphic Novels",
+            "Celebrities & Real People",
+            "Movies",
+            "Music & Bands",
+            "Other Media",
+            "Theater",
+            "TV Shows",
+            "Video Games",
+            "Uncategorized Fandoms",
+        ],
+    ) -> Fandom: ...
+    def get_tag(self, tag: str, page: int = 1, view_adult: bool = True) -> Tag: ...
+    def get_work(
+        self, work_id: int, chapter_id: int | None = None, entire_work: bool = False
+    ) -> Work: ...

ao3_py-2025.1.1/ao3/fandom.py

@@ -0,0 +1,71 @@
+import re
+from dataclasses import KW_ONLY, dataclass, field
+from functools import cached_property
+from typing import List
+from urllib.parse import urljoin
+
+import requests
+from bs4 import BeautifulSoup
+
+from ao3.tag import Tag
+
+
+@dataclass
+class Fandom:
+    _: KW_ONLY
+
+    session: requests.Session = field(default_factory=requests.Session)
+
+    name: str
+
+    def __post_init__(self) -> None:
+        soup = BeautifulSoup(
+            self.session.get("https://archiveofourown.org/media").text, features="lxml"
+        )
+
+        for li in soup.find("ul", {"class": "media fandom index group"}).find_all(  # type: ignore
+            "li", {"class": "medium listbox group"}
+        ):
+            if heading := li.find("h3", {"class": "heading"}).find(
+                "a", string=self.name
+            ):
+                self.href = heading["href"]
+
+                self.hot_tags = [
+                    Tag(
+                        session=self.session,
+                        name=a.text,
+                        href=a["href"],
+                        works_count=int(
+                            re.search(
+                                r"\((?P<works_count>\d+)\)", fandom.text
+                            ).groupdict()["works_count"]  # type: ignore
+                        ),
+                    )
+                    for fandom in li.find("ol", {"class": "index group"}).find_all("li")
+                    if (a := fandom.find("a", {"class": "tag"}))
+                ]
+
+    @cached_property
+    def tags(self) -> List[Tag]:
+        soup = BeautifulSoup(
+            self.session.get(urljoin("https://archiveofourown.org", self.href)).text,
+            features="lxml",
+        )
+
+        return [
+            Tag(
+                session=self.session,
+                name=a.text,
+                href=a["href"],
+                letter=li["id"].split("-")[1],
+            )
+            for li in soup.find(
+                "ol", {"class": "alphabet fandom index group"}
+            ).find_all("li", {"class": "letter listbox group"})  # type: ignore
+            for li_ in li.find("ul", {"class": "tags index group"}).find_all("li")
+            if (a := li_.find("a", {"class": "tag"}))
+        ]
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(name={self.name})"

ao3_py-2025.1.1/ao3/fandom.pyi

@@ -0,0 +1,18 @@
+from dataclasses import KW_ONLY, dataclass
+from typing import List
+
+import requests
+
+from ao3.tag import Tag
+
+@dataclass
+class Fandom:
+    _: KW_ONLY
+
+    session: requests.Session
+
+    name: str
+    href: str | None = None
+
+    hot_tags: List[Tag] | None = None
+    tags: List[Tag] | None = None

ao3_py-2025.1.1/ao3/tag.py

@@ -0,0 +1,201 @@
+import re
+from dataclasses import KW_ONLY, dataclass, field
+from itertools import groupby
+from operator import itemgetter
+from typing import Any, Type
+from urllib.parse import urljoin, urlparse
+
+import requests
+from bs4 import BeautifulSoup
+
+
+class Descriptor:
+    def __set_name__(self, owner: Type["Tag"], name: str) -> None:
+        self.name = f"_{name}"
+
+    def __get__(self, instance: "Tag", owner: Type["Tag"]) -> Any:
+        if instance is None:
+            return self
+
+        if not hasattr(instance, self.name):
+            from ao3.work import Work
+
+            resp = instance.session.get(
+                urljoin("https://archiveofourown.org", instance.href),
+                params={"page": instance.page, "view_adult": instance.view_adult},
+            )
+
+            soup = BeautifulSoup(resp.text, features="lxml")
+
+            if urlparse(resp.url).path.endswith("/works"):
+                if works_count := re.search(
+                    r"(?P<works_count>[0-9,]+) Works",
+                    soup.find("h2", {"class": "heading"}).text,  # type: ignore
+                ):
+                    setattr(
+                        instance,
+                        "_works_count",
+                        int(works_count.groupdict()["works_count"].replace(",", "")),
+                    )
+
+                works = []
+
+                for li in soup.find("ol", {"class": "work index group"}).find_all(  # type: ignore
+                    "li", {"role": "article"}
+                ):
+                    header = li.find("div", {"class": "header module"})
+
+                    title = header.find("h4", {"class": "heading"}).find("a")
+
+                    work = Work(session=instance.session, href=title["href"])
+
+                    setattr(work, "_title", title.text)
+
+                    if elem := header.find("h4", {"class": "heading"}).find(
+                        "a", {"rel": "author"}
+                    ):
+                        setattr(work, "_author", elem.text)
+
+                    rating, warnings, category, complete = header.find(
+                        "ul", {"class": "required-tags"}
+                    ).find_all("li")
+
+                    setattr(
+                        work,
+                        "_complete",
+                        bool(complete.find("span", {"class": "complete-yes"})),
+                    )
+
+                    for class_, grouper in groupby(
+                        li.find("ul", {"class": "tags commas"}).find_all("li"),
+                        key=itemgetter("class"),
+                    ):
+                        match class_:
+                            case ["warnings"]:
+                                setattr(
+                                    work,
+                                    "_archive_warning",
+                                    [
+                                        Tag(
+                                            session=instance.session,
+                                            name=a.text,
+                                            href=a["href"],
+                                        )
+                                        for tag in grouper
+                                        if (a := tag.find("a", {"class": "tag"}))
+                                    ],
+                                )
+
+                            case ["relationships"]:
+                                setattr(
+                                    work,
+                                    "_relationships",
+                                    [
+                                        Tag(
+                                            session=instance.session,
+                                            name=a.text,
+                                            href=a["href"],
+                                        )
+                                        for tag in grouper
+                                        if (a := tag.find("a", {"class": "tag"}))
+                                    ],
+                                )
+
+                            case ["characters"]:
+                                setattr(
+                                    work,
+                                    "_characters",
+                                    [
+                                        Tag(
+                                            session=instance.session,
+                                            name=a.text,
+                                            href=a["href"],
+                                        )
+                                        for tag in grouper
+                                        if (a := tag.find("a", {"class": "tag"}))
+                                    ],
+                                )
+
+                            case ["freeforms"]:
+                                setattr(
+                                    work,
+                                    "_additional_tags",
+                                    [
+                                        Tag(
+                                            session=instance.session,
+                                            name=a.text,
+                                            href=a["href"],
+                                        )
+                                        for tag in grouper
+                                        if (a := tag.find("a", {"class": "tag"}))
+                                    ],
+                                )
+
+                    stats = li.find("dl", {"class": "stats"})
+
+                    if elem := stats.find("dd", {"class": "language"}):
+                        setattr(work, "_language", elem.text)
+
+                    if elem := stats.find("dd", {"class": "words"}):
+                        setattr(work, "_words", int(elem.text.replace(",", "")))
+
+                    if elem := stats.find("dd", {"class": "chapters"}):
+                        chapter, chapter_count = elem.text.split("/")
+
+                        setattr(work, "_chapter_number", int(chapter))
+                        setattr(
+                            work,
+                            "_chapter_count",
+                            None if chapter_count == "?" else int(chapter_count),
+                        )
+
+                    if elem := stats.find("dd", {"class": "comments"}):
+                        setattr(work, "_comments", int(elem.text))
+
+                    if elem := stats.find("dd", {"class": "kudos"}):
+                        setattr(work, "_kudos", int(elem.text))
+
+                    if elem := stats.find("dd", {"class": "hits"}):
+                        setattr(work, "_hits", int(elem.text.replace(",", "")))
+
+                    if elem := li.find("blockquote", {"class": "userstuff summary"}):
+                        setattr(work, "_summary", "\n".join(elem.strings).strip())
+
+                    works.append(work)
+
+                setattr(instance, "_works", works)
+
+            else:
+                raise NotImplementedError
+
+        if not hasattr(instance, self.name):
+            setattr(instance, self.name, None)
+            return
+
+        return getattr(instance, self.name)
+
+    def __set__(self, instance: "Tag", value: Any) -> None:
+        setattr(instance, f"_{value}", value)
+
+
+@dataclass
+class Tag:
+    _: KW_ONLY
+
+    session: requests.Session = field(default_factory=requests.Session)
+
+    name: str
+    href: str
+
+    view_adult: bool = True
+
+    letter: str | None = None
+
+    works: Descriptor = Descriptor()
+    works_count: Descriptor = Descriptor()
+    bookmarks: Descriptor = Descriptor()
+    page: int = 1
+    page_count: Descriptor = Descriptor()
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(name={self.name})"

ao3_py-2025.1.1/ao3/tag.pyi

@@ -0,0 +1,25 @@
+from dataclasses import KW_ONLY, dataclass
+from typing import List
+
+import requests
+
+from ao3.work import Work
+
+@dataclass
+class Tag:
+    _: KW_ONLY
+
+    session: requests.Session
+
+    name: str
+    href: str
+
+    view_adult: bool = True
+
+    letter: str | None = None
+
+    works: List[Work] | None = None
+    works_count: int | None = None
+    bookmarks: int | None = None
+    page: int | None = None
+    page_count: int | None = None

ao3_py-2025.1.1/ao3/work.py

@@ -0,0 +1,303 @@
+from dataclasses import KW_ONLY, dataclass, field
+from datetime import datetime
+from typing import Any, Type
+from urllib.parse import urljoin, urlparse
+
+import requests
+from bs4 import BeautifulSoup
+
+
+@dataclass
+class Chapter:
+    _: KW_ONLY
+
+    session: requests.Session = field(default_factory=requests.Session, repr=False)
+
+    title: str | None = None
+    summary: str | None = None
+    notes: str | None = None
+    article: str | None = None
+    end_notes: str | None = None
+
+
+class Descriptor:
+    def __set_name__(self, owner: Type["Work"], name: str) -> None:
+        self.name = f"_{name}"
+
+    def __get__(self, instance: "Work", owner: Type["Work"]) -> Any:
+        if instance is None:
+            return self
+
+        if not hasattr(instance, self.name):
+            from ao3.tag import Tag
+
+            resp = instance.session.get(
+                urljoin("https://archiveofourown.org", instance.href)
+            )
+
+            soup = BeautifulSoup(resp.text, features="lxml")
+
+            for dd in (
+                soup.find("div", {"class": "wrapper"})
+                .find("dl", {"class": "work meta group"})  # type: ignore
+                .find_all("dd")  # type: ignore
+            ):
+                match dd["class"]:
+                    case ["rating", "tags"]:
+                        setattr(
+                            instance,
+                            "_rating",
+                            [
+                                Tag(
+                                    session=instance.session,
+                                    name=a.text,
+                                    href=a["href"],
+                                )
+                                for a in dd.find("ul", {"class": "commas"}).find_all(
+                                    "a", {"class": "tag"}
+                                )
+                            ],
+                        )
+
+                    case ["warning", "tags"]:
+                        setattr(
+                            instance,
+                            "_archive_warning",
+                            [
+                                Tag(
+                                    session=instance.session,
+                                    name=a.text,
+                                    href=a["href"],
+                                )
+                                for a in dd.find("ul", {"class": "commas"}).find_all(
+                                    "a", {"class": "tag"}
+                                )
+                            ],
+                        )
+
+                    case ["category", "tags"]:
+                        setattr(
+                            instance,
+                            "_category",
+                            [
+                                Tag(
+                                    session=instance.session,
+                                    name=a.text,
+                                    href=a["href"],
+                                )
+                                for a in dd.find("ul", {"class": "commas"}).find_all(
+                                    "a", {"class": "tag"}
+                                )
+                            ],
+                        )
+
+                    case ["fandom", "tags"]:
+                        setattr(
+                            instance,
+                            "_fandom",
+                            [
+                                Tag(
+                                    session=instance.session,
+                                    name=a.text,
+                                    href=a["href"],
+                                )
+                                for a in dd.find("ul", {"class": "commas"}).find_all(
+                                    "a", {"class": "tag"}
+                                )
+                            ],
+                        )
+
+                    case ["relationship", "tags"]:
+                        setattr(
+                            instance,
+                            "_relationships",
+                            [
+                                Tag(
+                                    session=instance.session,
+                                    name=a.text,
+                                    href=a["href"],
+                                )
+                                for a in dd.find("ul", {"class": "commas"}).find_all(
+                                    "a", {"class": "tag"}
+                                )
+                            ],
+                        )
+
+                    case ["language"]:
+                        setattr(instance, "_language", dd.text.strip())
+
+                    case ["stats"]:
+                        stats = dd.find("dl", {"class": "stats"})
+
+                        if elem := stats.find("dd", {"class": "published"}):
+                            setattr(
+                                instance,
+                                "_published",
+                                datetime.fromisoformat(elem.text),
+                            )
+
+                        if elem := stats.find("dd", {"class": "status"}):
+                            setattr(
+                                instance, "_status", datetime.fromisoformat(elem.text)
+                            )
+                            setattr(instance, "_complete", False)
+                        else:
+                            setattr(instance, "_status", None)
+                            setattr(instance, "_complete", True)
+
+                        if elem := stats.find("dd", {"class": "words"}):
+                            setattr(instance, "_words", int(elem.text.replace(",", "")))
+
+                        if elem := stats.find("dd", {"class": "chapters"}):
+                            chapter, chapter_count = elem.text.split("/")
+
+                            setattr(instance, "_chapter_number", int(chapter))
+                            setattr(
+                                instance,
+                                "_chapter_count",
+                                None if chapter_count == "?" else int(chapter_count),
+                            )
+
+                        if elem := stats.find("dd", {"class": "comments"}):
+                            setattr(
+                                instance, "_comments", int(elem.text.replace(",", ""))
+                            )
+
+                        if elem := stats.find("dd", {"class": "kudos"}):
+                            setattr(instance, "_kudos", int(elem.text.replace(",", "")))
+
+                        if elem := stats.find("dd", {"class": "hits"}):
+                            setattr(instance, "_hits", int(elem.text.replace(",", "")))
+
+            workskin = soup.find("div", {"id": "workskin"})
+
+            preface = workskin.find("div", {"class": "preface group"})  # type: ignore
+
+            setattr(
+                instance,
+                "_title",
+                preface.find("h2", {"class": "title heading"}).text.strip(),  # type: ignore
+            )
+
+            if elem := preface.find("h3", {"class": "byline heading"}).find(  # type: ignore
+                "a",
+                {"rel": "author"},  # type: ignore
+            ):
+                setattr(instance, "_author", elem.text)  # type: ignore
+            else:
+                setattr(instance, "_author", None)
+
+            if elem := preface.find("div", {"class": "summary module"}):  # type: ignore
+                setattr(
+                    instance,
+                    "_summary",
+                    "\n".join(
+                        elem.find("blockquote", {"class": "userstuff"}).strings  # type: ignore
+                    ).strip(),
+                )
+
+            chapters = []
+
+            for chapter in workskin.find("div", {"id": "chapters"}).find_all(  # type: ignore
+                "div", {"class": "chapter"}, recursive=False
+            ):
+                c = Chapter(session=instance.session)
+
+                if elem := chapter.find("h3", {"class": "title"}):
+                    setattr(c, "title", elem.text)
+
+                if elem := chapter.find("div", {"id": "summary"}):
+                    setattr(
+                        c,
+                        "summary",
+                        "\n".join(
+                            elem.find("blockquote", {"class": "userstuff"}).strings
+                        ).strip(),
+                    )
+
+                if (elem := chapter.find("div", {"id": "notes"})) and (
+                    notes := elem.find("blockquote", {"class": "userstuff"})
+                ):
+                    setattr(c, "notes", "\n".join(notes.strings).strip())
+
+                if elem := chapter.find("div", {"role": "article"}):
+                    setattr(c, "article", "\n".join(elem.strings).strip())
+
+                if elem := chapter.find("div", {"class": "end notes module"}):
+                    setattr(
+                        c,
+                        "end_notes",
+                        "\n".join(
+                            elem.find("blockquote", {"class": "userstuff"}).strings
+                        ).strip(),
+                    )
+
+                chapters.append(c)
+
+            if elem := workskin.find("div", {"class": "userstuff"}):  # type: ignore
+                chapters.append(
+                    Chapter(session=instance.session, article="\n".join(elem.strings))  # type: ignore
+                )
+
+            setattr(instance, "_chapters", chapters)
+
+        if not hasattr(instance, self.name):
+            setattr(instance, self.name, None)
+            return
+
+        return getattr(instance, self.name)
+
+    def __set__(self, instance: "Work", value: Any) -> None:
+        setattr(instance, f"_{value}", value)
+
+
+@dataclass
+class Work:
+    _: KW_ONLY
+
+    session: requests.Session = field(default_factory=requests.Session)
+
+    href: str
+
+    work_id: Descriptor = Descriptor()
+    chapter_id: Descriptor = Descriptor()
+
+    rating: Descriptor = Descriptor()
+    archive_warning: Descriptor = Descriptor()
+    fandoms: Descriptor = Descriptor()
+    relationships: Descriptor = Descriptor()
+    characters: Descriptor = Descriptor()
+    additional_tags: Descriptor = Descriptor()
+    language: Descriptor = Descriptor()
+
+    published: Descriptor = Descriptor()
+    status: Descriptor = Descriptor()
+    words: Descriptor = Descriptor()
+    chapter_number: Descriptor = Descriptor()
+    chapter_count: Descriptor = Descriptor()
+    comments: Descriptor = Descriptor()
+    kudos: Descriptor = Descriptor()
+    bookmarks: Descriptor = Descriptor()
+    hits: Descriptor = Descriptor()
+
+    author: Descriptor = Descriptor()
+    title: Descriptor = Descriptor()
+    summary: Descriptor = Descriptor()
+
+    chapters: Descriptor = Descriptor()
+
+    def __post_init__(self) -> None:
+        match [part for part in urlparse(self.href).path.split("/") if part]:
+            case ["works", work_id, "chapters", chapter_id]:
+                setattr(self, "_work_id", int(work_id))
+                setattr(self, "_chapter_id", int(chapter_id))
+
+            case ["works", work_id]:
+                setattr(self, "_work_id", int(work_id))
+                setattr(self, "_chapter_id", None)
+
+            case _:
+                raise ValueError(f"Unknow href: {self.href}")
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(name={self.title}, author={self.author})"

ao3_py-2025.1.1/ao3/work.pyi

@@ -0,0 +1,56 @@
+from dataclasses import KW_ONLY, dataclass
+from datetime import datetime
+from typing import List
+
+import requests
+
+from ao3.tag import Tag
+
+@dataclass
+class Chapter:
+    _: KW_ONLY
+
+    session: requests.Session
+
+    title: str | None = None
+    summary: str | None = None
+    notes: str | None = None
+    article: str | None = None
+    end_notes: str | None = None
+
+@dataclass
+class Work:
+    _: KW_ONLY
+
+    session: requests.Session
+
+    href: str | None = None
+
+    work_id: int | None = None
+    chapter_id: int | None = None
+
+    rating: List[Tag] | None = None
+    archive_warning: List[Tag] | None = None
+    fandoms: List[Tag] | None = None
+    relationships: List[Tag] | None = None
+    characters: List[Tag] | None = None
+    additional_tags: List[Tag] | None = None
+    language: str | None = None
+
+    complete: bool | None = None
+
+    published: datetime | None = None
+    status: datetime | None = None
+    words: int | None = None
+    chapter_number: int | None = None
+    chapter_count: int | None = None
+    comments: int | None = None
+    kudos: int | None = None
+    bookmarks: int | None = None
+    hits: int | None = None
+
+    author: str | None = None
+    title: str | None = None
+    summary: str | None = None
+
+    chapters: List[Chapter] | None = None

ao3_py-2025.1.1/pyproject.toml

@@ -0,0 +1,15 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ao3-py"
+version  = "2025.1.1"
+dependencies = ["beautifulsoup4", "lxml","requests"]
+requires-python = ">=3"
+description = "an unofficial python sdk for Archive Of Our Own (AO3)"
+readme = "README.md"
+license = {text = "MIT License"}
+
+[tool.hatch.build.targets.wheel]
+packages = ["ao3"]