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”).

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: Mapping) → dict

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.

yb.youtube.stats.render_table(data: Mapping | Sequence[Mapping], *, fields: Sequence[str] | None = None) → str

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.

yb.youtube.stats.resolve_fields(*, group: str | None = None, fields: Sequence[str] | None = None, available: Iterable[str] | None = None) → list[str]

Resolve the ordered field list to show.

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

yb.youtube.stats.select_fields(flat: Mapping, *, group: str | None = None, fields: Sequence[str] | None = None) → dict

Return an ordered subset of flat per fields/group.

yb.youtube.stats.video_metadata(video_id: str | Iterable[str], *, group: str | None = None, fields: Sequence[str] | None = None, part: str = 'snippet,statistics,contentDetails,status', as_table: bool = False, service=None, **cred_kwargs) → dict | list[dict] | str

Fetch a video’s live metadata & engagement numbers.

Parameters:

• video_id – A single video id or an iterable of ids (batched, ≤50/call).

• group – Name of a preset field set from FIELD_GROUPS (e.g. "engagement"). Ignored if fields is given.

• fields – Explicit ordered field names to keep (overrides group). With neither group nor fields you get every field.

• part – videos.list parts to request (default covers all fields).

• as_table – 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=...).

Returns:

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