3.1 KiB
src/core/naming.py
Pool file naming convention.
Every movie in the pool is named Title (YYYY) [tmdbid-N].ext — a title, a
four-digit year in parentheses, and (when known) the TMDb id in brackets, which
is exactly the form Jellyfin matches on. The [tmdbid-N] part is optional: a
plain Title (YYYY) is still valid (Jellyfin then matches by name). The year
lets two same-named films coexist and makes the filename self-describing.
A 3D movie additionally carries a .3D.<FORMAT> tag right before the
extension (Jellyfin's own convention — https://jellyfin.org/docs/general/server/media/movies/):
Title (YYYY) [tmdbid-N].3D.HSBS.ext. FORMAT is one of
THREE_D_FORMATS; Jellyfin reads it case-insensitively but Curator always
writes it upper-case for a single canonical form.
These helpers build, validate and parse the stem (the filename without its extension).
Source: src/core/naming.py
Functions
is_valid_year
function · line 35
is_valid_year(year: object) -> bool
True when year is (or stringifies to) exactly four digits.
canonical_pool_stem
function · line 40
canonical_pool_stem(title: str, year: object, tmdb_id: object=None, format_3d: object=None) -> str
Build the canonical pool stem Title (YYYY) (+ [tmdbid-N] /
.3D.<FORMAT> if given).
Raises:
ValueError: the title is empty, the year is not four digits, a given
tmdb_id is not a positive integer, or format_3d isn't one
of THREE_D_FORMATS.
parse_pool_stem
function · line 73
parse_pool_stem(stem: str) -> tuple[str, int] | None
Split a canonical stem into (title, year); None if it isn't one.
A trailing [tmdbid-N] is tolerated and dropped (use parse_tmdb_id
to read it), so the returned title is always the clean title.
parse_tmdb_id
function · line 85
parse_tmdb_id(stem: str) -> int | None
Read the [tmdbid-N] from a canonical stem, or None if absent.
parse_3d_format
function · line 93
parse_3d_format(stem: str) -> str | None
Read the .3D.<FORMAT> tag from a canonical stem (upper-cased), or
None if absent.
is_canonical_pool_stem
function · line 102
is_canonical_pool_stem(stem: str) -> bool
True when stem matches the Title (YYYY) convention.
year_from_filename
function · line 107
year_from_filename(name: str) -> str | None
Best-effort four-digit year guessed from a raw (release) filename.
Prefers a parenthesised year (… (1999) …) and otherwise falls back to the
last standalone 19xx/20xx run. Used only to pre-fill the import dialog — the
user confirms it. Returns the year as a string, or None.
three_d_format_from_filename
function · line 129
three_d_format_from_filename(name: str) -> str | None
Best-effort 3D format guessed from a raw (release) filename, e.g.
Avatar.2009.3D.HSBS.BluRay.mkv → "HSBS". Unlike parse_3d_format
this doesn't require the rest of the name to be a canonical pool stem — used
to pre-fill a version label while importing. Returns None if absent.