Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 18 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# YTAPI Python client

Python client for [YTAPI](https://ytapi.dev?utm_source=github): YouTube transcripts, video details, search, channels and playlists over one HTTP API. It works from servers and cloud functions, where fetching YouTube directly tends to get blocked.
Python client for [YTAPI](https://ytapi.dev?utm_source=github): YouTube transcripts, video details, comments, search, channels and playlists over one HTTP API. It works from servers and cloud functions, where fetching YouTube directly tends to get blocked.

- No dependencies beyond the standard library. Python 3.10+.
- Typed responses (`TypedDict`), typed errors, automatic retries and pagination.
Expand Down Expand Up @@ -42,6 +42,21 @@ basic = api.get_basic_info("dQw4w9WgXcQ")
# 1 credit: description, counts, chapters and more.
info = api.get_video_info("dQw4w9WgXcQ")

# Comments, top or newest first: 1 credit per page of about 20.
page = api.get_comments("dQw4w9WgXcQ", sort="top")
for comment in page["comments"]:
print(comment["like_count"], comment["author"]["name"], comment["text"])
# A comment's replies, from its replies_cursor.
if page["comments"]:
top = page["comments"][0]
for reply in api.iter_comment_replies("dQw4w9WgXcQ", top.get("replies_cursor")):
print(" ", reply["text"])

# The "most replayed" graph: 1 credit; free NotFoundError when a video has none.
heatmap = api.get_heatmap("dQw4w9WgXcQ")
for peak in heatmap.get("peaks", []):
print(peak["start_seconds"], peak["intensity"])

# Channels take an @handle, a channel ID (UC...) or a URL.
channel = api.get_channel("@3blue1brown")
for video in api.iter_channel_videos("@3blue1brown", sort_by="popular"):
Expand Down Expand Up @@ -70,7 +85,7 @@ done = api.poll_batch(job["id"], timeout=120)
print(done["successful"], done["credits_deducted"])
```

The iterators (`iter_playlist_videos`, `iter_channel_videos`, `iter_channel_playlists`, `iter_search`) follow `next_cursor` for you. Each page is a request and uses a credit. In a batch, each successful task uses 1 credit and failed tasks are free.
The iterators (`iter_playlist_videos`, `iter_channel_videos`, `iter_channel_playlists`, `iter_search`, `iter_comments`, `iter_comment_replies`) follow `next_cursor` for you. Each page is a request and uses a credit. In a batch, each successful task uses 1 credit and failed tasks are free.

## Errors

Expand All @@ -80,7 +95,7 @@ from ytapi import InsufficientCreditsError, NotFoundError, RateLimitedError, YTA
try:
api.get_transcript("xxxxxxxxxxx")
except NotFoundError as exc:
print(exc.code) # captions_disabled, language_not_found, video_unavailable, ...
print(exc.code) # captions_disabled, comments_disabled, video_unavailable, ...
except RateLimitedError as exc:
print(exc.code, exc.retry_after) # rate_limited or daily_limit_exceeded
except InsufficientCreditsError:
Expand Down
4 changes: 2 additions & 2 deletions pyproject.toml
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
[project]
name = "ytapi-sdk"
version = "0.2.1"
description = "Python client for YTAPI: YouTube transcripts, video details, search, channels and playlists."
version = "0.3.0"
description = "Python client for YTAPI: YouTube transcripts, video details, comments, search, channels and playlists."
readme = "README.md"
requires-python = ">=3.10"
license = "MIT"
Expand Down
2 changes: 1 addition & 1 deletion src/ytapi/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -19,4 +19,4 @@
"YTAPI",
"YTAPIError",
]
__version__ = "0.2.1"
__version__ = "0.3.0"
62 changes: 61 additions & 1 deletion src/ytapi/client.py
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,11 @@
ChannelPlaylist,
ChannelVideo,
ChannelVideosPage,
Comment,
CommentSort,
CommentsPage,
DurationFilter,
Heatmap,
PlaylistPage,
PlaylistVideo,
SearchItem,
Expand All @@ -49,7 +53,7 @@
VideoInfo,
)

_USER_AGENT = "ytapi-python/0.2.0 (+https://docs.ytapi.dev)"
_USER_AGENT = "ytapi-python/0.3.0 (+https://docs.ytapi.dev)"
_ENV_KEYS = ("YTAPI_API_KEY", "YTAPI_KEY")
# A free account's daily limit answers 429 with Retry-After until 00:00 UTC.
# Waiting that long inside a call would hang the caller, so it is raised.
Expand Down Expand Up @@ -137,6 +141,62 @@ def get_video_info(self, video_id: str) -> VideoInfo:
"""Full metadata, including description, counts and chapters. 1 credit."""
return self._request("GET", f"/v1/videos/{_seg(video_id)}/video-info")

def get_heatmap(self, video_id: str) -> Heatmap:
"""The "most replayed" graph: peaks and a 20-part curve. 1 credit.

Many videos have none; that raises ``NotFoundError`` with code
``heatmap_unavailable`` and costs nothing.
"""
return self._request("GET", f"/v1/videos/{_seg(video_id)}/heatmap")

def get_comments(
self,
video_id: str,
*,
sort: CommentSort | None = None,
cursor: str | None = None,
) -> CommentsPage:
"""One page of comments, about 20, top (default) or newest first. 1 credit per page.

Comments turned off raise ``NotFoundError`` with code ``comments_disabled``.
"""
return self._request(
"GET",
f"/v1/videos/{_seg(video_id)}/comments",
query={"sort": sort, "cursor": cursor},
)

def iter_comments(
self, video_id: str, *, sort: CommentSort | None = None
) -> Iterator[Comment]:
"""Every top-level comment, following ``next_cursor``. Each page uses a credit."""
yield from _pages(
lambda cursor: self.get_comments(video_id, sort=sort, cursor=cursor),
"comments",
)

def get_comment_replies(self, video_id: str, cursor: str) -> CommentsPage:
"""One page of replies. ``cursor`` is a comment's ``replies_cursor``,
then the page's ``next_cursor``. 1 credit per page."""
return self._request(
"GET",
f"/v1/videos/{_seg(video_id)}/comments/replies",
query={"cursor": cursor},
)

def iter_comment_replies(
self, video_id: str, replies_cursor: str | None
) -> Iterator[Comment]:
"""Every reply to one comment, starting from its ``replies_cursor``.
Yields nothing when the comment has no replies (an empty cursor)."""
if not replies_cursor:
return
first = replies_cursor
yield from _pages(
lambda cursor: self.get_comment_replies(video_id, cursor or first),
"comments",
)

def get_playlist(self, playlist_id: str, *, cursor: str | None = None) -> PlaylistPage:
"""One page of a playlist. Later pages carry videos only. 1 credit per page."""
return self._request(
Expand Down
3 changes: 2 additions & 1 deletion src/ytapi/errors.py
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,8 @@ class InsufficientCreditsError(YTAPIError):


class NotFoundError(YTAPIError):
"""404. ``code`` is captions_disabled, language_not_found, video_unavailable, or another not-found code."""
"""404. ``code`` is captions_disabled, language_not_found, video_unavailable,
comments_disabled, heatmap_unavailable, or another not-found code."""


class RateLimitedError(YTAPIError):
Expand Down
57 changes: 57 additions & 0 deletions src/ytapi/models.py
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,7 @@
TrackPolicy = Literal["manual_first", "asr_first", "exact_only"]
SearchType = Literal["video", "channel", "playlist", "shorts", "movie"]
SortBy = Literal["newest", "popular", "oldest"]
CommentSort = Literal["top", "newest"]
UploadDate = Literal["hour", "today", "week", "month", "year"]
DurationFilter = Literal["short", "medium", "long"]
SearchSort = Literal["relevance", "rating", "upload_date", "view_count"]
Expand Down Expand Up @@ -145,6 +146,62 @@ class VideoInfo(TypedDict, total=False):
related: list[RelatedVideo] # up to 20


class HeatmapPeak(TypedDict, total=False):
start_seconds: float
end_seconds: float
intensity: float # 0 to 1, relative to the video's own peak
label: str # "Most replayed" on YouTube's own marker


class HeatmapPoint(TypedDict, total=False):
start_seconds: float
end_seconds: float
intensity: float


class Heatmap(TypedDict, total=False):
"""YouTube's "most replayed" graph, condensed to 20 parts."""

video_id: str
length_seconds: int
most_replayed: HeatmapPeak
peaks: list[HeatmapPeak] # up to 5, in time order
curve: list[HeatmapPoint]


class CommentAuthor(TypedDict, total=False):
name: str
channel_id: str
avatar_url: str
is_channel_owner: bool
is_verified: bool
is_artist: bool


class Comment(TypedDict, total=False):
id: str
text: str
author: CommentAuthor
like_count: int # YouTube's rounded figure: "12K" is 12000
like_count_text: str
reply_count: int
published_text: str # relative, such as "3 years ago"
is_edited: bool
is_pinned: bool
is_hearted: bool
replies_cursor: str # pass to get_comment_replies; only when it has replies


class CommentsPage(TypedDict, total=False):
video_id: str
sort: CommentSort # absent on pages of replies
comment_count: int # the video's total, first page only; rounded by YouTube
comment_count_text: str
comments: list[Comment]
has_more: bool
next_cursor: str | None


class PlaylistVideo(TypedDict, total=False):
video_id: str
title: str
Expand Down
68 changes: 68 additions & 0 deletions tests/test_client.py
Original file line number Diff line number Diff line change
Expand Up @@ -172,6 +172,9 @@ def urlopen(request, timeout=None):
),
lambda: client.get_suggestions("next"),
lambda: client.get_batch("batch_1"),
lambda: client.get_heatmap("kCc8FmEb1nY"),
lambda: client.get_comments("kCc8FmEb1nY", sort="newest", cursor="k1"),
lambda: client.get_comment_replies("kCc8FmEb1nY", "r1"),
]
with mock.patch.object(urllib.request, "urlopen", urlopen):
for call in calls:
Expand All @@ -191,8 +194,15 @@ def urlopen(request, timeout=None):
"https://api.ytapi.dev/v1/search",
"https://api.ytapi.dev/v1/search/suggestions",
"https://api.ytapi.dev/v1/batch/batch_1",
"https://api.ytapi.dev/v1/videos/kCc8FmEb1nY/heatmap",
"https://api.ytapi.dev/v1/videos/kCc8FmEb1nY/comments",
"https://api.ytapi.dev/v1/videos/kCc8FmEb1nY/comments/replies",
],
)
comments_query = seen[11][1].split("?", 1)[1]
self.assertIn("sort=newest", comments_query)
self.assertIn("cursor=k1", comments_query)
self.assertEqual(seen[12][1].split("?", 1)[1], "cursor=r1")
playlist_query = seen[2][1].split("?", 1)[1]
self.assertIn("cursor=c1", playlist_query)
video_query = seen[5][1].split("?", 1)[1]
Expand Down Expand Up @@ -481,6 +491,64 @@ def urlopen(request, timeout=None):
self.assertEqual(uploads[0]["title"], "upload")
self.assertEqual(lists[0]["playlist_id"], "PLx")

def test_comment_iterators_follow_cursors(self) -> None:
seen: list[str] = []
pages = {
"/comments": {"has_more": True, "next_cursor": "c2", "comments": [{"id": "a"}]},
"/comments?cursor=c2": {"has_more": False, "next_cursor": None, "comments": [{"id": "b"}]},
"/comments/replies?cursor=r1": {"has_more": True, "next_cursor": "r2", "comments": [{"id": "ra"}]},
"/comments/replies?cursor=r2": {"has_more": False, "comments": [{"id": "rb"}]},
}

def urlopen(request, timeout=None):
tail = request.full_url.split("/v1/videos/vid", 1)[1]
seen.append(tail)
return json_body(pages[tail])

with mock.patch.object(urllib.request, "urlopen", urlopen):
client = self.client()
comments = [c["id"] for c in client.iter_comments("vid")]
replies = [c["id"] for c in client.iter_comment_replies("vid", "r1")]
self.assertEqual(comments, ["a", "b"])
self.assertEqual(replies, ["ra", "rb"])
self.assertEqual(len(seen), 4)

def test_comments_and_heatmap_not_found_codes(self) -> None:
for code, call in [
("comments_disabled", lambda c: c.get_comments("vid")),
("heatmap_unavailable", lambda c: c.get_heatmap("vid")),
]:
def urlopen(request, timeout=None, code=code):
raise error(404, code, code)

with mock.patch.object(urllib.request, "urlopen", urlopen):
with self.assertRaises(NotFoundError) as raised:
call(self.client())
self.assertEqual(raised.exception.code, code)

def test_comment_iterators_keep_the_sort_and_handle_empty_pages(self) -> None:
seen: list[str] = []
pages = {
"/comments?sort=newest": {"has_more": True, "next_cursor": "c2", "comments": [{"id": "a"}]},
"/comments?sort=newest&cursor=c2": {"has_more": False, "comments": [{"id": "b"}]},
"/comments?sort=top": {"has_more": False, "next_cursor": None, "comments": []},
}

def urlopen(request, timeout=None):
tail = request.full_url.split("/v1/videos/vid", 1)[1]
seen.append(tail)
return json_body(pages[tail])

with mock.patch.object(urllib.request, "urlopen", urlopen):
client = self.client()
newest = [c["id"] for c in client.iter_comments("vid", sort="newest")]
empty = list(client.iter_comments("vid", sort="top"))
no_replies = list(client.iter_comment_replies("vid", ""))
self.assertEqual(newest, ["a", "b"])
self.assertEqual(empty, [])
self.assertEqual(no_replies, [])
self.assertEqual(len(seen), 3)

def test_poll_batch_returns_when_the_job_finishes(self) -> None:
statuses = ["pending", "processing", "completed"]

Expand Down
Loading