Skip to content

sok.core.batch

Batch matching: find the online item of many files at once.

Each file (or group of files, such as the .cue and .bin of a game) gets a search query read from its name, the candidates of the online database and a status:

  • Ready: one candidate has the title of the file and, when the file gives them, its year, its author or artist, and its album. It is selected and can be renamed as is. Several candidates can count as one when they are the same work, such as the editions of a book. A track found only on compilations, live or remix releases is not Ready: its own album is still unknown.
  • Pick one: candidates were found, but none or several match exactly. The most likely one is selected, and the user must confirm it.
  • Missing: the search found nothing.

The module has no Qt dependency, so the desktop app and S.O.K Server share it.

BatchMatchdataclass

class BatchMatch(
files: List[Path],
query: str,
year: Optional[int],
candidates: List[Dict[str, Any]] = list(),
selected: Optional[int] = None,
status: str = STATUS_MISSING,
)

Search result of one item of a batch.

Parameters

NameTypeDefaultDescription
filesList[Path]The files of the item; one for a movie or a book.
querystrSearch text, read from the file name or typed by the user.
yearOptional[int]Year read from the file name, or None.
candidatesList[Dict[str, Any]]list()Search results, best first as the service ranks them.
selectedOptional[int]NoneIndex of the selected candidate, or None if there is none.
statusstrSTATUS_MISSINGSTATUS_READY, STATUS_AMBIGUOUS or STATUS_MISSING.
Source

Attributes

NameTypeDescription
candidatesList[Dict[str, Any]]

Search results, best first as the service ranks them.

filesList[Path]

The files of the item; one for a movie or a book.

querystr

Search text, read from the file name or typed by the user.

selectedOptional[int]

Index of the selected candidate, or None if there is none.

statusstr

STATUS_READY, STATUS_AMBIGUOUS or STATUS_MISSING.

yearOptional[int]

Year read from the file name, or None.

fileproperty

Path

The first file, which names the item.

BatchMatcher

class BatchMatcher(
manager: Any,
content_type: ContentType,
parse: QueryParser,
language: Optional[str] = None,
same_work: Optional[SameWork] = None,
)

Search the online database for every item of a batch.

Parameters

NameTypeDefaultDescription
managerAnyThe media manager (sok.core.media_manager).
content_typeContentTypeWhat to search, such as ContentType.MOVIE.
parseQueryParserReads the file name of an item.
languageOptional[str]NoneLanguage of the results, such as "fr-FR", or None.
same_workOptional[SameWork]NoneTells when several results are one work (see evaluate).
Source

matchasync

async def match(
files: Sequence[Path],
query: Optional[str] = None,
) -> BatchMatch:

Search one item.

Parameters

NameTypeDefaultDescription
filesSequence[Path]Files of the item.
queryOptional[str]NoneSearch text typed by the user, instead of the file name. It is then also the title compared with the results; the year of the file name is kept.

Returns

  • BatchMatchThe match. A failed search gives no candidates (Missing).

Raises

Source

match_allasync

async def match_all(
items: Sequence[Sequence[Path]],
progress: Optional[Callable[[int, int, Path], None]] = None,
) -> List[BatchMatch]:

Search every item, a few at a time.

Parameters

NameTypeDefaultDescription
itemsSequence[Sequence[Path]]The files of each item.
progressOptional[Callable[[int, int, Path], None]]NoneCalled with (done, total, first file) after each item.

Returns

  • List[BatchMatch]The matches, in the order of the items.
Source

ParsedNamedataclass

class ParsedName(
query: str,
year: Optional[int] = None,
title: Optional[str] = None,
author: Optional[str] = None,
album: Optional[str] = None,
search_kwargs: Dict[str, Any] = dict(),
)

What the file name of an item tells about it.

Parameters

NameTypeDefaultDescription
querystrText to search.
yearOptional[int]NoneYear in the name, or None.
titleOptional[str]NoneTitle to compare with the results; the query if None.
authorOptional[str]NoneAuthor (books) or artist (tracks), or None.
albumOptional[str]NoneAlbum of a track, from its tags, or None.
search_kwargsDict[str, Any]dict()Extra search parameters, such as the title and the artist of a track for a precise search.
Source

Attributes

NameTypeDescription
albumOptional[str]

Album of a track, from its tags, or None.

authorOptional[str]

Author (books) or artist (tracks), or None.

querystr

Text to search.

search_kwargsDict[str, Any]

Extra search parameters, such as the title and the artist of a track for a precise search.

titleOptional[str]

Title to compare with the results; the query if None.

yearOptional[int]

Year in the name, or None.

Functions

author_matches

def author_matches(author: str, candidate: Dict[str, Any]) -> bool:

True if the author of the file name is an author of the result.

"Herbert" and "F. Herbert" match "Frank Herbert": file names often give the last name. A full name must be the same: "Daft Punk" is not "Data Punk".

Parameters

NameTypeDescription
authorstr
candidateDict[str, Any]
Source

candidate_authors

def candidate_authors(candidate: Dict[str, Any]) -> List[str]:

Authors (books) or artist (music) of a search result, normalized.

Parameters

NameTypeDescription
candidateDict[str, Any]
Source

candidate_year

def candidate_year(candidate: Dict[str, Any]) -> Optional[int]:

Year of a search result, from its first date field.

Parameters

NameTypeDescription
candidateDict[str, Any]
Source

evaluate

def evaluate(
query: str,
year: Optional[int],
candidates: List[Dict[str, Any]],
author: Optional[str] = None,
same_work: Optional[SameWork] = None,
album: Optional[str] = None,
) -> Tuple[Optional[int], str]:

Choose the candidate to select and the status of an item.

Parameters

NameTypeDefaultDescription
querystrTitle to compare with the results.
yearOptional[int]Year read from the file name, or None.
candidatesList[Dict[str, Any]]Search results.
authorOptional[str]NoneAuthor or artist read from the file, or None.
same_workOptional[SameWork]NoneTells when several matching results are one work. By default every result is a different work (movies).
albumOptional[str]NoneAlbum of a track, from its tags: a result on that album is the one.

Returns

  • Optional[int]The index of the candidate to select (None without candidates) and
  • strthe status.
Source

group_game_files

def group_game_files(files: List[Path]) -> List[List[Path]]:

Put the files of one game together: a .cue and its .bin, the discs.

Files of the same folder whose names only differ by their extension or a "(Disc N)" / "(Track N)" part are one game.

Parameters

NameTypeDescription
filesList[Path]
Source

normalize_title

def normalize_title(text: str) -> str:

Reduce a title to its letters and digits, for comparison.

Accents, case, punctuation and spaces are ignored, and "&" counts as "and": "Dune: Part Two" and "dune.part.two" are the same title.

Parameters

NameTypeDescription
textstr
Source

on_other_release

def on_other_release(candidate: Dict[str, Any]) -> bool:

True for a track result on a compilation, a live or a remix release.

The album the track came out on is then still unknown, so such a result is never Ready on its own.

Parameters

NameTypeDescription
candidateDict[str, Any]
Source

parse_album

def parse_album(files: Sequence[Path]) -> ParsedName:

Read the tracks of an album: its title, artist and year.

The album and the artist most tracks give in their tags (the album artist first), then the name of the folder: "Daft Punk - Discovery (2001)". A year the results do not give is not compared (see evaluate).

Parameters

NameTypeDescription
filesSequence[Path]
Source

parse_book

def parse_book(files: Sequence[Path]) -> ParsedName:

Read a book file name: "Frank Herbert - Dune.epub" → Dune, by Herbert.

The author is added to the search, which finds the right book more often, but only the title and the author are compared with the results. The year is left out: it is often the year of the first edition, while the results are later editions.

Parameters

NameTypeDescription
filesSequence[Path]
Source

parse_game

def parse_game(files: Sequence[Path]) -> ParsedName:

Read a game file name: "Crash Bandicoot (USA) (Track 2).bin" → Crash Bandicoot.

The region and the other tags are left out of the search.

Parameters

NameTypeDescription
filesSequence[Path]
Source

parse_movie

def parse_movie(files: Sequence[Path]) -> ParsedName:

Read a movie file name: "Dune.Part.Two.2024.mkv" → Dune Part Two, 2024.

Parameters

NameTypeDescription
filesSequence[Path]
Source

parse_series

def parse_series(files: Sequence[Path]) -> ParsedName:

Read the episodes of a series: "Severance.S01E02.mkv" → Severance.

The title is the one the type detector gives the series (from the file name, or from the folders above a season folder), so the search and the group of the analysis agree. A year in the name ("Doctor.Who.2005.…") is the year of the first season.

Parameters

NameTypeDescription
filesSequence[Path]
Source

parse_track

def parse_track(files: Sequence[Path]) -> ParsedName:

Read a track: its tags first (artist, title, album), then its name.

Tags are what players show and are usually right; file names of downloads are often "01 - Title.mp3" with no artist.

Parameters

NameTypeDescription
filesSequence[Path]
Source

same_album

def same_album(a: Dict[str, Any], b: Dict[str, Any]) -> bool:

Two results with the same title and artist are one album, such as its explicit and clean versions.

Parameters

NameTypeDescription
aDict[str, Any]
bDict[str, Any]
Source

same_book

def same_book(a: Dict[str, Any], b: Dict[str, Any]) -> bool:

Two results with the same title and authors are editions of one book.

Parameters

NameTypeDescription
aDict[str, Any]
bDict[str, Any]
Source

same_track

def same_track(a: Dict[str, Any], b: Dict[str, Any]) -> bool:

Two results are the same track on the same album.

A compilation, a live or a remix release does not count as another album: the track still came out on the first one.

Parameters

NameTypeDescription
aDict[str, Any]
bDict[str, Any]
Source

title_matches

def title_matches(query: str, candidate: Dict[str, Any]) -> bool:

True if the candidate has the query as title or original title.

Parameters

NameTypeDescription
querystr
candidateDict[str, Any]
Source

Attributes

NameValue
DATE_KEYS('release_date', 'first_air_date', 'published_date', 'year')
MAX_CANDIDATES5
OTHER_RELEASES('compilation', 'live', 'remix')
QueryParserCallable[[Sequence[Path]], ParsedName]
SEARCH_CONCURRENCY4
STATUS_AMBIGUOUS'ambiguous'
STATUS_MISSING'missing'
STATUS_READY'ok'
SameWorkCallable[[Dict[str, Any], Dict[str, Any]], bool]
TITLE_KEYS('title', 'name', 'original_title', 'original_name')
loggerlogging.getLogger(__name__)
Built with Kiln