annie.dataset.layout

Nested video layouts: find videos below a root with a {field} path template (pure).

A flat folder needs no layout — one video per file, id = file stem. Real datasets are often nested (<root>/<group>/<subject>/clip_<part>.mp4), where the file stem alone is neither unique nor informative. A VideoLayout describes such a tree once with a pattern relative to the root, e.g. {group}/{subject}/clip_{part}.mp4; the video id joins the captured fields with _ (g1_s1_a).

{name} captures one path segment, or part of a file name when mixed with literal text; ** matches any number of directories. The captured fields become the video’s labels, so Browse can tag and filter by them. Nothing here knows any particular dataset.

Classes

DiscoveredVideo	One video found by a layout.
DiscoveryReport	The outcome of scanning a root with a layout.
VideoLayout	A path template that finds and names the videos of a nested dataset.

Functions

contains_nested_videos(→ bool)

Whether any non-junk video file sits below root (not directly in it).

Module Contents

annie.dataset.layout.contains_nested_videos(root: pathlib.Path, suffixes: tuple[str, ...]) → bool

Whether any non-junk video file sits below root (not directly in it).

Used to hint that a flat scan found nothing because the videos are nested. Stops at the first hit, so it is cheap on a tree that has videos and only walks fully when it has none.

Parameters:

• root – The folder to look under.

• suffixes – Lower-case dotted video suffixes, e.g. (".mp4",).

Returns:

True if a video file exists in any sub-folder.

class annie.dataset.layout.DiscoveredVideo

One video found by a layout.

path

Absolute path of the file.

video_id

The captured fields joined with _ in pattern order.

fields

The captured template fields, e.g. {"subject": "s1", "part": "x"}.

class annie.dataset.layout.DiscoveryReport

The outcome of scanning a root with a layout.

videos

Discovered videos, sorted by id; a colliding id keeps its first file only.

collisions

Ids that more than one file produced (the extras are dropped).

summary() → str

One line for the Dataset tab: counts, per-field value counts, collisions, examples.

class annie.dataset.layout.VideoLayout

A path template that finds and names the videos of a nested dataset.

pattern

Path of the videos relative to the root, with {field} placeholders.

field_names() → list[str]

The pattern’s field names in order of appearance (unique).

validate() → None

Check the layout is usable.

Raises:

ValueError – If the pattern is empty, absolute, climbs out of the root (..), repeats a field, or has no fields.

match(relative_path: str) → dict[str, str] | None

Return the captured fields if relative_path fits the pattern, else None.

video_id(fields: collections.abc.Mapping[str, str]) → str

Build the video id for a match’s fields: the values joined with _.

discover(root: pathlib.Path) → DiscoveryReport

Scan root recursively for files matching the pattern.

Junk (dotfiles/folders) is skipped. A missing root yields an empty report.

Parameters:

root – The dataset root the pattern is relative to.

Returns:

The sorted videos and any id collisions.

Raises:

ValueError – If the layout is invalid (see validate()).