v0.3.1: fix search pagination docs (continuation_token, not pagination.next_page_token); live test for the README example

Author: TubeAgentKit

README.md

@@ -88,10 +88,11 @@ print(to_text(result))        # one block of plain text
 ### Search
 
 ```python
-client.search("lofi beats", type="video", limit=10)
+first_page = client.search("lofi beats", type="video", limit=10)
 
-# Pagination
-page2 = client.search(page_token=first_page["pagination"]["next_page_token"])
+# Pagination: pass continuation_token back as page_token
+if first_page.get("continuation_token"):
+    page2 = client.search(page_token=first_page["continuation_token"])
 ```
 
 ### Channels

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "getyoutubetranscript"
-version = "0.3.0"
+version = "0.3.1"
 description = "YouTube transcript API for Python: get YouTube video transcripts, captions and subtitles with timestamps, search YouTube, and list channel and playlist videos. No proxies or headless browser."
 readme = "README.md"
 requires-python = ">=3.9"

src/getyoutubetranscript/__init__.py

@@ -13,7 +13,7 @@
 from .formatters import format_transcript, to_json, to_srt, to_text, to_timed_text, to_vtt
 from .types import Segment, TranscriptData
 
-__version__ = "0.3.0"
+__version__ = "0.3.1"
 
 __all__ = [
     "Client",

src/getyoutubetranscript/client.py

@@ -184,9 +184,9 @@ def search(
         Args:
             query: Search query. Required for a first page unless
                 ``page_token`` is given.
-            page_token: Continuation token from a previous response's
-                ``pagination.next_page_token``, to fetch the next page. Treat
-                as opaque - don't construct it yourself.
+            page_token: The ``continuation_token`` from a previous response,
+                to fetch the next page. Treat as opaque - don't construct it
+                yourself. Expires after 24 hours.
             type: Restrict results to ``"video"`` (default) or ``"channel"``.
                 Never mixes both kinds in one response.
             country: Two-letter region code, e.g. ``"us"``.
@@ -196,7 +196,8 @@ def search(
         Returns:
             dict with ``query``, and either ``video_results`` or
             ``channel_results`` depending on ``type``, plus
-            ``pagination.next_page_token`` when more results are available.
+            ``continuation_token`` for the next page (missing or ``None`` when
+            there are no more pages, so read it with ``.get()``).
 
         Raises:
             ValueError: if neither ``query`` nor ``page_token`` is given.

tests/live/test_live_api.py

@@ -71,6 +71,18 @@ def test_search_live(client: Client):
     assert len(result["video_results"]) > 0
 
 
+def test_search_pagination_live(client: Client):
+    """The README pagination example: continuation_token goes back in as page_token."""
+    first_page = client.search("lofi beats", type="video", limit=10)
+    assert "pagination" not in first_page
+    token = first_page.get("continuation_token")
+    assert token, "first page should offer a next page"
+    page2 = client.search(page_token=token)
+    assert page2["video_results"]
+    first_titles = {v.get("title") for v in first_page["video_results"]}
+    assert not first_titles & {v.get("title") for v in page2["video_results"]}
+
+
 def test_get_credits_live(client: Client):
     """Free endpoint - safe to run often."""
     result = client.get_credits()