ranobelib-python-sdk 0.3.0__tar.gz → 0.4.0__tar.gz

{ranobelib_python_sdk-0.3.0 → ranobelib_python_sdk-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ranobelib-python-sdk
-Version: 0.3.0
+Version: 0.4.0
 Summary: Async Python SDK for ranobelib.me: title metadata, chapter/volume downloads, and export to epub/fb2/txt/pdf
 Keywords: ranobelib,ranobe,novel,webnovel,epub,fb2,sdk
 Author: LLIJIYAPNIK
@@ -18,6 +18,7 @@ Classifier: Typing :: Typed
 Requires-Dist: ebooklib>=0.20
 Requires-Dist: httpx>=0.27
 Requires-Dist: pydantic>=2.7
+Requires-Dist: rich>=15.0.0
 Requires-Dist: weasyprint>=69.0
 Requires-Python: >=3.11
 Project-URL: Homepage, https://github.com/LLIJIYAPNIK/ranobelib-python-sdk

{ranobelib_python_sdk-0.3.0 → ranobelib_python_sdk-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ranobelib-python-sdk"
-version = "0.3.0"
+version = "0.4.0"
 description = "Async Python SDK for ranobelib.me: title metadata, chapter/volume downloads, and export to epub/fb2/txt/pdf"
 readme = "README.md"
 license = "MIT"
@@ -29,6 +29,7 @@ dependencies = [
     "ebooklib>=0.20",
     "httpx>=0.27",
     "pydantic>=2.7",
+    "rich>=15.0.0",
     "weasyprint>=69.0",
 ]
 

{ranobelib_python_sdk-0.3.0 → ranobelib_python_sdk-0.4.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "ranobelib-python-sdk"
-version = "0.3.0"
+version = "0.4.0"
 description = "Async Python SDK for ranobelib.me: title metadata, chapter/volume downloads, and export to epub/fb2/txt/pdf"
 readme = "README.md"
 license = "MIT"
@@ -24,6 +24,7 @@ dependencies = [
     "ebooklib>=0.20",
     "httpx>=0.27",
     "pydantic>=2.7",
+    "rich>=15.0.0",
     "weasyprint>=69.0",
 ]
 

{ranobelib_python_sdk-0.3.0 → ranobelib_python_sdk-0.4.0}/src/ranobelib/__init__.py

@@ -13,6 +13,7 @@ from ranobelib.exceptions import (
 )
 from ranobelib.models import Chapter, ChapterBranch, Title, Volume
 from ranobelib.sdk import RanobeLib
+from ranobelib.sizing import chapter_size, volume_size
 
 __all__ = [
     "AmbiguousChapter",
@@ -29,4 +30,6 @@ __all__ = [
     "TitleNotFoundError",
     "Volume",
     "VolumeNotFoundError",
+    "chapter_size",
+    "volume_size",
 ]

ranobelib_python_sdk-0.4.0/src/ranobelib/console.py

@@ -0,0 +1,72 @@
+"""Console output for RanobeLib: progress bars and full-mode operation logging.
+
+Behind ``RanobeLib``'s ``verbosity`` parameter (``False`` by default, ``"progress_only"``,
+or ``"full"`` — see CLAUDE.md's roadmap entry for why these three, and why this prints
+directly via ``rich`` rather than going through ``logging``). ``Reporter`` is the single
+object that knows which of the three modes is active; every call site (``sdk.py``, the
+exporters) just calls ``log()``/``progress()`` unconditionally and lets ``Reporter`` decide
+whether that produces any output.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterator
+from contextlib import contextmanager
+from typing import Literal
+
+from rich.console import Console
+from rich.progress import BarColumn, MofNCompleteColumn, Progress, TextColumn, TimeElapsedColumn
+
+Verbosity = Literal["full", "progress_only"] | Literal[False]
+"""``False``: silent. ``"progress_only"``: progress bars only. ``"full"``: progress bars
+plus a line logged for every title/chapters-list/chapter-content fetch (cache hit or API)."""
+
+
+class Reporter:
+    """Console output gated by a ``Verbosity`` level, backed by a single ``rich.Console``."""
+
+    def __init__(self, verbosity: Verbosity, *, console: Console | None = None) -> None:
+        """Initialize the reporter.
+
+        Args:
+            verbosity: The active output level.
+            console: Custom ``rich.console.Console`` to print through, e.g. one writing to
+                an in-memory stream for tests. Defaults to a new ``Console()`` (stdout) —
+                only constructed at all when ``verbosity`` isn't ``False``, so a silent
+                ``RanobeLib`` never touches the terminal.
+        """
+        self._verbosity = verbosity
+        if not verbosity:
+            self._console = None
+        else:
+            self._console = console if console is not None else Console()
+
+    def log(self, message: str) -> None:
+        """Print ``message``, only when verbosity is ``"full"``.
+
+        ``markup=False``: messages embed literal ``[cache]``/``[api]`` prefixes (see
+        ``sdk.py``'s choke points), which rich's default markup parsing would otherwise try
+        to interpret as style tags.
+        """
+        if self._verbosity == "full" and self._console is not None:
+            self._console.log(message, markup=False)
+
+    @contextmanager
+    def progress(self, description: str, total: int) -> Iterator[Callable[[], None]]:
+        """A progress bar shown for ``"progress_only"``/``"full"``, a no-op otherwise.
+
+        Yields a zero-argument callable: call it once per completed step.
+        """
+        if not self._verbosity or total == 0:
+            yield lambda: None
+            return
+
+        with Progress(
+            TextColumn("[progress.description]{task.description}"),
+            BarColumn(),
+            MofNCompleteColumn(),
+            TimeElapsedColumn(),
+            console=self._console,
+        ) as progress:
+            task_id = progress.add_task(description, total=total)
+            yield lambda: progress.advance(task_id)

{ranobelib_python_sdk-0.3.0 → ranobelib_python_sdk-0.4.0}/src/ranobelib/exporters/__init__.py

@@ -9,6 +9,7 @@ from __future__ import annotations
 
 import importlib
 import pkgutil
+from collections.abc import Callable
 from pathlib import Path
 from typing import ClassVar, Protocol, TypeVar, runtime_checkable
 
@@ -22,7 +23,14 @@ class Exporter(Protocol):
     format: ClassVar[str]
     """The registry key this exporter is selected by, e.g. ``"txt"``."""
 
-    async def export(self, title: Title, chapters: list[Chapter], output_path: Path) -> Path:
+    async def export(
+        self,
+        title: Title,
+        chapters: list[Chapter],
+        output_path: Path,
+        *,
+        on_chapter: Callable[[], None] | None = None,
+    ) -> Path:
         """Write ``chapters`` (in the given order) to ``output_path``.
 
         ``async`` since embedding illustrations (epub, pdf) requires downloading them —
@@ -33,6 +41,10 @@ class Exporter(Protocol):
             title: The chapters' parent title, for metadata (name, authors, ...).
             chapters: The chapters to include, in the order they should appear.
             output_path: Where to write the exported file.
+            on_chapter: Called once per chapter processed, if given — drives
+                ``RanobeLib.export()``'s progress bar (see CLAUDE.md's roadmap step 23).
+                For epub/pdf this covers the per-chapter embedding step, not the earlier
+                illustration-download step, which isn't itself progress-reported.
 
         Returns:
             ``output_path``, once the file has been written.

{ranobelib_python_sdk-0.3.0 → ranobelib_python_sdk-0.4.0}/src/ranobelib/exporters/epub.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import html
+from collections.abc import Callable
 from pathlib import Path
 from typing import ClassVar
 
@@ -39,7 +40,14 @@ class EpubExporter:
         """
         self._transport = transport
 
-    async def export(self, title: Title, chapters: list[Chapter], output_path: Path) -> Path:
+    async def export(
+        self,
+        title: Title,
+        chapters: list[Chapter],
+        output_path: Path,
+        *,
+        on_chapter: Callable[[], None] | None = None,
+    ) -> Path:
         """Write ``chapters`` to ``output_path`` as an EPUB file.
 
         Downloads the title's cover and every image referenced in the chapters' content and
@@ -50,6 +58,8 @@ class EpubExporter:
             title: The chapters' parent title; supplies metadata, cover, and authors.
             chapters: The chapters to include, in the order they should appear.
             output_path: Where to write the ``.epub`` file.
+            on_chapter: Called once per chapter embedded, if given — after illustrations
+                have already been downloaded, see the ``Exporter`` protocol's docstring.
 
         Returns:
             ``output_path``.
@@ -107,6 +117,8 @@ class EpubExporter:
             book.add_item(doc)
             spine.append(doc)
             toc.append(doc)
+            if on_chapter is not None:
+                on_chapter()
 
         book.toc = toc
         book.add_item(epub.EpubNcx())

{ranobelib_python_sdk-0.3.0 → ranobelib_python_sdk-0.4.0}/src/ranobelib/exporters/fb2.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import datetime
 import xml.etree.ElementTree as ET
+from collections.abc import Callable
 from html.parser import HTMLParser
 from pathlib import Path
 from typing import ClassVar
@@ -126,7 +127,7 @@ def _build_description(title: Title) -> ET.Element:
     return description
 
 
-def _build_body(chapters: list[Chapter]) -> ET.Element:
+def _build_body(chapters: list[Chapter], on_chapter: Callable[[], None] | None) -> ET.Element:
     body = ET.Element(_tag("body"))
     for chapter in chapters:
         section = ET.SubElement(body, _tag("section"))
@@ -134,6 +135,8 @@ def _build_body(chapters: list[Chapter]) -> ET.Element:
         ET.SubElement(section_title, _tag("p")).text = chapter_heading(chapter)
         for paragraph in html_to_fb2_paragraphs(chapter.content or ""):
             section.append(paragraph)
+        if on_chapter is not None:
+            on_chapter()
     return body
 
 
@@ -143,20 +146,28 @@ class Fb2Exporter:
 
     format: ClassVar[str] = "fb2"
 
-    async def export(self, title: Title, chapters: list[Chapter], output_path: Path) -> Path:
+    async def export(
+        self,
+        title: Title,
+        chapters: list[Chapter],
+        output_path: Path,
+        *,
+        on_chapter: Callable[[], None] | None = None,
+    ) -> Path:
         """Write ``chapters`` to ``output_path`` as FB2 XML.
 
         Args:
             title: The chapters' parent title; supplies ``description`` metadata.
             chapters: The chapters to include, in the order they should appear.
             output_path: Where to write the ``.fb2`` file.
+            on_chapter: Called once per chapter written, if given.
 
         Returns:
             ``output_path``.
         """
         root = ET.Element(_tag("FictionBook"))
         root.append(_build_description(title))
-        root.append(_build_body(chapters))
+        root.append(_build_body(chapters, on_chapter))
 
         tree = ET.ElementTree(root)
         ET.indent(tree, space="  ")

{ranobelib_python_sdk-0.3.0 → ranobelib_python_sdk-0.4.0}/src/ranobelib/exporters/pdf.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 import asyncio
 import base64
 import html
+from collections.abc import Callable
 from pathlib import Path
 from typing import ClassVar
 
@@ -98,13 +99,23 @@ if weasyprint is not None:
             """
             self._transport = transport
 
-        async def export(self, title: Title, chapters: list[Chapter], output_path: Path) -> Path:
+        async def export(
+            self,
+            title: Title,
+            chapters: list[Chapter],
+            output_path: Path,
+            *,
+            on_chapter: Callable[[], None] | None = None,
+        ) -> Path:
             """Write ``chapters`` to ``output_path`` as a PDF file.
 
             Args:
                 title: The chapters' parent title; supplies metadata, cover, and authors.
                 chapters: The chapters to include, in the order they should appear.
                 output_path: Where to write the ``.pdf`` file.
+                on_chapter: Called once per chapter rendered to HTML, if given — after
+                    illustrations have already been downloaded, see the ``Exporter``
+                    protocol's docstring.
 
             Returns:
                 ``output_path``.
@@ -135,9 +146,12 @@ if weasyprint is not None:
                 for url, data in images.items()
             }
 
-            body = _title_page_html(title, cover_data_uri) + "".join(
-                _chapter_html(chapter, url_to_data_uri) for chapter in chapters
-            )
+            chapter_html_parts = []
+            for chapter in chapters:
+                chapter_html_parts.append(_chapter_html(chapter, url_to_data_uri))
+                if on_chapter is not None:
+                    on_chapter()
+            body = _title_page_html(title, cover_data_uri) + "".join(chapter_html_parts)
             document = (
                 f"<html><head><meta charset='utf-8'><style>{_PAGE_CSS}</style></head>"
                 f"<body>{body}</body></html>"

{ranobelib_python_sdk-0.3.0 → ranobelib_python_sdk-0.4.0}/src/ranobelib/exporters/txt.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+from collections.abc import Callable
 from html.parser import HTMLParser
 from pathlib import Path
 from typing import ClassVar
@@ -69,13 +70,21 @@ class TxtExporter:
 
     format: ClassVar[str] = "txt"
 
-    async def export(self, title: Title, chapters: list[Chapter], output_path: Path) -> Path:
+    async def export(
+        self,
+        title: Title,
+        chapters: list[Chapter],
+        output_path: Path,
+        *,
+        on_chapter: Callable[[], None] | None = None,
+    ) -> Path:
         """Write ``chapters`` to ``output_path`` as plain text.
 
         Args:
             title: The chapters' parent title; only its name is used.
             chapters: The chapters to include, in the order they should appear.
             output_path: Where to write the ``.txt`` file.
+            on_chapter: Called once per chapter written, if given.
 
         Returns:
             ``output_path``.
@@ -84,6 +93,8 @@ class TxtExporter:
         for chapter in chapters:
             body = html_to_text(chapter.content or "")
             sections.append(f"{chapter_heading(chapter)}\n\n{body}")
+            if on_chapter is not None:
+                on_chapter()
 
         output_path.write_text("\n\n\n".join(sections) + "\n", encoding="utf-8")
         return output_path

{ranobelib_python_sdk-0.3.0 → ranobelib_python_sdk-0.4.0}/src/ranobelib/sdk.py

@@ -9,6 +9,7 @@ from typing import Any, Self
 
 from ranobelib.cache import DEFAULT_CACHE_DIR, DiskCache
 from ranobelib.client import ApiClient
+from ranobelib.console import Reporter, Verbosity
 from ranobelib.exceptions import (
     AmbiguousChapter,
     ChapterNotFoundError,
@@ -19,6 +20,7 @@ from ranobelib.exceptions import (
 from ranobelib.exporters import EXPORTERS
 from ranobelib.models import Chapter, ChapterBranch, Title, Volume
 from ranobelib.numbering import parse_slug_url
+from ranobelib.sizing import DEFAULT_AVERAGE_IMAGE_SIZE, DEFAULT_SAMPLE_SIZE, chapter_size
 
 _INFO_FIELDS = [
     "background",
@@ -51,6 +53,7 @@ class RanobeLib:
         *,
         cache_dir: str | Path | None = None,
         cache_ttl: float | None = None,
+        verbosity: Verbosity = False,
     ) -> None:
         """Initialize the SDK for a title.
 
@@ -63,12 +66,18 @@ class RanobeLib:
             cache_ttl: Seconds after which a cached response is treated as stale and
                 re-fetched. ``None`` (the default) means cached responses never expire on
                 their own — see ``refresh=True`` on individual methods to force one anyway.
+            verbosity: Console output level. ``False`` (default): silent. ``"progress_only"``:
+                progress bars during ``download_title()``/``export()``/``estimate_title_size()``.
+                ``"full"``: the same progress bars, plus a line logged for every title/
+                chapter-list/chapter-content fetch, noting whether it was served from the
+                disk cache or the API.
         """
         self._slug_url = parse_slug_url(url)
         self._client = ApiClient()
         self._cache = DiskCache(
             cache_dir if cache_dir is not None else DEFAULT_CACHE_DIR, ttl=cache_ttl
         )
+        self._reporter = Reporter(verbosity)
 
     async def __aenter__(self) -> Self:
         return self
@@ -288,12 +297,102 @@ class RanobeLib:
             raise MultipleTitleTranslationsError(self._slug_url, chapters=unresolved)
 
         chapters = []
-        for index, (volume_str, number, selected_branch_id) in enumerate(planned):
-            chapters.append(await self._fetch_chapter(volume_str, number, selected_branch_id))
-            if chapter_delay and index < len(planned) - 1:
-                await asyncio.sleep(chapter_delay)
+        with self._reporter.progress(f"Downloading {self._slug_url}", len(planned)) as advance:
+            for index, (volume_str, number, selected_branch_id) in enumerate(planned):
+                chapters.append(await self._fetch_chapter(volume_str, number, selected_branch_id))
+                advance()
+                if chapter_delay and index < len(planned) - 1:
+                    await asyncio.sleep(chapter_delay)
         return _group_into_volumes(chapters)
 
+    async def estimate_title_size(
+        self,
+        *,
+        sample_size: int = DEFAULT_SAMPLE_SIZE,
+        average_image_size: int = DEFAULT_AVERAGE_IMAGE_SIZE,
+        branch_id: int | None = None,
+        translation_index: int | None = None,
+    ) -> int:
+        """Estimate the whole title's download size in bytes, from a sample of its chapters.
+
+        Fetches the chapter list (cheap, cached), then the content of up to ``sample_size``
+        chapters spread evenly across the title — not just the first ones, since early and
+        late chapters can differ in length — and extrapolates the sample's average
+        ``sizing.chapter_size()`` across the title's total chapter count. This trades
+        exactness for cost: an exact total requires fetching every chapter's content, the
+        same cost as ``download_title()`` itself, which defeats the purpose of checking
+        "is this worth downloading" *before* paying that cost.
+
+        Sampled chapters go through the same disk cache as any other chapter fetch, so a
+        later ``download_title()`` call doesn't refetch them.
+
+        Args:
+            sample_size: How many chapters to sample. Clamped to the number of chapters the
+                title actually has (or that resolve to a usable translation, see below) if
+                that's fewer.
+            average_image_size: Forwarded to ``sizing.chapter_size()`` for each sampled
+                chapter.
+            branch_id: Same meaning as ``download_title(branch_id=...)`` — which translation
+                to sample for chapters that have more than one. Mutually exclusive with
+                ``translation_index``.
+            translation_index: Same meaning as ``download_title(translation_index=...)``.
+                Mutually exclusive with ``branch_id``.
+
+        Returns:
+            The estimated size in bytes, or ``0`` if the title has no chapters, or none of
+            its chapters have a translation ``branch_id``/``translation_index`` resolves.
+
+        Raises:
+            ValueError: If both ``branch_id`` and ``translation_index`` are given, or if
+                ``sample_size`` is less than 1.
+
+        Note:
+            Unlike ``download_title()``, a chapter with more than one translation that
+            ``branch_id``/``translation_index`` doesn't resolve is skipped when picking the
+            sample rather than raising ``MultipleTitleTranslationsError`` — an estimate
+            doesn't need a specific translation to be correct, only *a* chapter's worth of
+            this title's content to measure.
+        """
+        if branch_id is not None and translation_index is not None:
+            raise ValueError("Pass at most one of branch_id or translation_index, not both.")
+        if sample_size < 1:
+            raise ValueError(f"sample_size must be at least 1, got {sample_size}.")
+
+        raw_chapters = await self._get_chapters()
+        if not raw_chapters:
+            return 0
+
+        resolvable: list[tuple[str, str, int | None]] = []
+        for item in raw_chapters:
+            volume_str: str = item["volume"]
+            number: str = item["number"]
+            branches = item.get("branches") or []
+            if len(branches) <= 1:
+                resolvable.append((volume_str, number, None))
+                continue
+            resolved, selected = _resolve_bulk_branch_id(
+                branches, branch_id=branch_id, translation_index=translation_index
+            )
+            if resolved:
+                resolvable.append((volume_str, number, selected))
+
+        if not resolvable:
+            return 0
+
+        size = min(sample_size, len(resolvable))
+        step = max(1, len(resolvable) // size)
+        sample = [resolvable[index] for index in range(0, len(resolvable), step)][:size]
+
+        total_sample_bytes = 0
+        with self._reporter.progress(f"Sampling {self._slug_url}", len(sample)) as advance:
+            for volume_str, number, selected_branch_id in sample:
+                chapter = await self._fetch_chapter(volume_str, number, selected_branch_id)
+                total_sample_bytes += chapter_size(chapter, average_image_size=average_image_size)
+                advance()
+
+        average_bytes = total_sample_bytes / len(sample)
+        return round(average_bytes * len(raw_chapters))
+
     async def export(self, chapters: list[Chapter], *, fmt: str, path: str | Path) -> Path:
         """Export chapters to a file.
 
@@ -311,7 +410,8 @@ class RanobeLib:
             available = ", ".join(sorted(EXPORTERS)) or "(none registered)"
             raise ValueError(f"Unknown export format {fmt!r}. Available: {available}")
         title = await self.get_info()
-        return await exporter_cls().export(title, chapters, Path(path))
+        with self._reporter.progress(f"Exporting to {fmt}", len(chapters)) as advance:
+            return await exporter_cls().export(title, chapters, Path(path), on_chapter=advance)
 
     async def _build_volume(self, volume: int, raw_chapters: list[dict[str, Any]]) -> Volume:
         volume_str = str(volume)
@@ -330,7 +430,9 @@ class RanobeLib:
         if not refresh:
             cached = self._cache.get(key)
             if cached is not None:
+                self._reporter.log(f"[cache] title metadata for {self._slug_url}")
                 return cached  # type: ignore[no-any-return]
+        self._reporter.log(f"[api] fetching title metadata for {self._slug_url}")
         data = await self._client.get_title(self._slug_url, fields=_INFO_FIELDS)
         self._cache.set(key, data)
         return data
@@ -340,7 +442,9 @@ class RanobeLib:
         if not refresh:
             cached = self._cache.get(key)
             if cached is not None:
+                self._reporter.log(f"[cache] chapter list for {self._slug_url}")
                 return cached  # type: ignore[no-any-return]
+        self._reporter.log(f"[api] fetching chapter list for {self._slug_url}")
         data = await self._client.get_chapters(self._slug_url)
         self._cache.set(key, data)
         return data
@@ -352,7 +456,9 @@ class RanobeLib:
         if not refresh:
             cached = self._cache.get(key)
             if cached is not None:
+                self._reporter.log(f"[cache] chapter {volume_str}/{number}")
                 return Chapter.model_validate(cached)
+        self._reporter.log(f"[api] fetching chapter {volume_str}/{number}")
         data = await self._client.get_chapter(
             self._slug_url, number=number, volume=volume_str, branch_id=branch_id
         )

ranobelib_python_sdk-0.4.0/src/ranobelib/sizing.py

@@ -0,0 +1,62 @@
+"""Rough size estimation for already-fetched chapters/volumes, and whole-title sampling.
+
+The API exposes no content-length or image-size field anywhere (see docs/api-notes.md), so
+any size here is necessarily approximate for the image portion: chapter text is measured
+exactly (the UTF-8 byte length of ``Chapter.content``), but each embedded ``<img>`` is
+assumed to weigh ``average_image_size`` bytes rather than downloaded to measure precisely —
+doing that would cost the same network traffic this module exists to help avoid paying
+upfront. The result approximates the underlying content size, not a specific export
+format's file size (epub's zip compression, pdf's layout overhead, fb2's XML verbosity are
+not modeled) — enough to decide whether a title is worth downloading, not to predict an
+exported file's exact byte count.
+"""
+
+from __future__ import annotations
+
+from ranobelib.exporters._illustrations import extract_image_urls
+from ranobelib.models import Chapter, Volume
+
+DEFAULT_AVERAGE_IMAGE_SIZE = 150_000
+"""Assumed bytes per embedded image when its real size isn't fetched. A rough guess, not
+measured — override with a better estimate for a given title if you have one."""
+
+DEFAULT_SAMPLE_SIZE = 5
+"""Default number of chapters ``RanobeLib.estimate_title_size()`` samples."""
+
+
+def chapter_size(chapter: Chapter, *, average_image_size: int = DEFAULT_AVERAGE_IMAGE_SIZE) -> int:
+    """Estimate a fetched chapter's size in bytes: exact text plus assumed-average images.
+
+    Args:
+        chapter: A chapter with content already fetched (e.g. via ``get_chapter()``).
+        average_image_size: Assumed bytes per ``<img>`` referenced in the chapter's content.
+
+    Raises:
+        ValueError: If ``chapter.content`` is ``None`` (not yet fetched — see
+            ``Chapter``'s docstring for when that happens).
+    """
+    if chapter.content is None:
+        raise ValueError(
+            f"Chapter {chapter.volume}/{chapter.number} has no content to size — "
+            "fetch it first, e.g. via get_chapter()."
+        )
+    text_bytes = len(chapter.content.encode("utf-8"))
+    image_count = len(extract_image_urls(chapter.content))
+    return text_bytes + image_count * average_image_size
+
+
+def volume_size(volume: Volume, *, average_image_size: int = DEFAULT_AVERAGE_IMAGE_SIZE) -> int:
+    """Estimate a fetched volume's size in bytes: the sum of its chapters' ``chapter_size()``.
+
+    Args:
+        volume: A volume whose chapters have content already fetched (e.g. via
+            ``get_volume()``).
+        average_image_size: Forwarded to ``chapter_size()`` for each chapter.
+
+    Raises:
+        ValueError: If any chapter in ``volume.chapters`` has no content — see
+            ``chapter_size()``.
+    """
+    return sum(
+        chapter_size(chapter, average_image_size=average_image_size) for chapter in volume.chapters
+    )