yb.youtube.stats¶

Read live video metadata & engagement numbers from the YouTube Data API v3.

A read-only companion to yb.youtube.api: fetch a flattened, typed, human-friendly view of a video’s live numbers (views, likes, dislikes, comments, …) together with content and status details — all in one request — with optional field selection, named field groups (presets like "engagement"), and an ASCII-table rendering for quick terminal reading.

Simple things simple:

>>> from yb.youtube import video_metadata
>>> video_metadata("VIDEO_ID", group="engagement")
{'views': 666, 'likes': 11, 'dislikes': 0, 'comments': 0, ...}

Readable table for a terminal:

>>> print(video_metadata("VIDEO_ID", group="engagement", as_table=True))
field              value
-----------------  -----
views                666
likes                 11
...

Pick exact fields and order, or compare several videos at once:

>>> video_metadata("VIDEO_ID", fields=["title", "views", "likes"])
>>> print(video_metadata(["ID1", "ID2"], group="engagement", as_table=True))

Note

dislikes is only returned by the API to a video’s owner; for other people’s videos it comes back as None. With no group/fields you get every available field (“take whatever is there”).

Module Attributes

`DEFAULT_PARTS`	Parts fetched by default — everything a single `videos.list` call needs to populate the flattened fields below.
`FIELD_GROUPS`	a group name -> the ordered fields it selects.

Functions

`flatten_video`(resource)	Flatten a raw `videos.list` item into a friendly, typed, ordered dict.
`render_table`(data, *[, fields])	Render metadata as an ASCII table.
`resolve_fields`(*[, group, fields, available])	Resolve the ordered field list to show.
`select_fields`(flat, *[, group, fields])	Return an ordered subset of `flat` per `fields`/`group`.
`video_metadata`(video_id, *[, group, fields, ...])	Fetch a video's live metadata & engagement numbers.

yb.youtube.stats.DEFAULT_PARTS = 'snippet,statistics,contentDetails,status'¶: Parts fetched by default — everything a single videos.list call needs to populate the flattened fields below.

yb.youtube.stats.FIELD_GROUPS: dict[str, list[str]] = {'content': ['duration', 'duration_seconds', 'definition', 'dimension', 'has_captions', 'has_custom_thumbnail', 'licensed_content', 'projection'], 'engagement': ['views', 'likes', 'dislikes', 'comments', 'favorites', 'like_view_pct', 'comment_view_pct'], 'identity': ['id', 'url', 'title', 'channel_title', 'channel_id', 'category_id', 'published_at'], 'overview': ['title', 'url', 'privacy', 'published_at', 'duration', 'views', 'likes', 'comments'], 'status': ['privacy', 'upload_status', 'made_for_kids', 'embeddable', 'license', 'public_stats_viewable']}¶

a group name -> the ordered fields it selects. "engagement" is the headline one (the live numbers); the rest are common practical cuts.

Type:: Named presets

yb.youtube.stats.flatten_video(resource)[source]¶

Flatten a raw videos.list item into a friendly, typed, ordered dict.

Pure: pass the dict returned by the API. Missing pieces (from a partial part= request, disabled stats, or an unauthorized dislike count) become None rather than raising, so callers never have to guard the shape.

Return type:: dict

yb.youtube.stats.render_table(data, *, fields=None)[source]¶

Render metadata as an ASCII table.

A single flat dict renders as a two-column field | value table; a list of flat dicts renders one row per video with fields as columns.

Return type:: str

yb.youtube.stats.resolve_fields(*, group=None, fields=None, available=None)[source]¶

Resolve the ordered field list to show.

Precedence: explicit fields > named group > every available field. An unknown group raises KeyError naming the valid options.

Return type:: list[str]

yb.youtube.stats.select_fields(flat, *, group=None, fields=None)[source]¶

Return an ordered subset of flat per fields/group.

Return type:: dict

yb.youtube.stats.video_metadata(video_id, *, group=None, fields=None, part='snippet,statistics,contentDetails,status', as_table=False, service=None, **cred_kwargs)[source]¶

Fetch a video’s live metadata & engagement numbers.

Parameters:

video_id (Union[str, Iterable[str]]) – A single video id or an iterable of ids (batched, ≤50/call).
group (str | None) – Name of a preset field set from FIELD_GROUPS (e.g. "engagement"). Ignored if fields is given.
fields (Optional[Sequence[str]]) – Explicit ordered field names to keep (overrides group). With neither group nor fields you get every field.
part (str) – videos.list parts to request (default covers all fields).
as_table (bool) – When True, return a ready-to-print ASCII table string instead of the dict/list.
service – An authenticated YouTube service; else built from cred_kwargs (e.g. token_file=...).

Return type:

dict | list[dict] | str

Returns:

A flat dict for one id / list[dict] for many — or an ASCII table str when as_table=True.