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
| Name | Type | Default | Description |
|---|---|---|---|
files | List[Path] | The files of the item; one for a movie or a book. | |
query | str | Search text, read from the file name or typed by the user. | |
year | Optional[int] | Year read from the file name, or None. | |
candidates | List[Dict[str, Any]] | list() | Search results, best first as the service ranks them. |
selected | Optional[int] | None | Index of the selected candidate, or None if there is none. |
status | str | STATUS_MISSING | STATUS_READY, STATUS_AMBIGUOUS or STATUS_MISSING. |
Attributes
| Name | Type | Description |
|---|---|---|
candidates | List[Dict[str, Any]] | Search results, best first as the service ranks them. |
files | List[Path] | The files of the item; one for a movie or a book. |
query | str | Search text, read from the file name or typed by the user. |
selected | Optional[int] | Index of the selected candidate, or None if there is none. |
status | str | STATUS_READY, STATUS_AMBIGUOUS or STATUS_MISSING. |
year | Optional[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
| Name | Type | Default | Description |
|---|---|---|---|
manager | Any | The media manager (sok.core.media_manager). | |
content_type | ContentType | What to search, such as ContentType.MOVIE. | |
parse | QueryParser | Reads the file name of an item. | |
language | Optional[str] | None | Language of the results, such as "fr-FR", or None. |
same_work | Optional[SameWork] | None | Tells when several results are one work (see evaluate). |
matchasync
async def match( files: Sequence[Path], query: Optional[str] = None,) -> BatchMatch:Search one item.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
files | Sequence[Path] | Files of the item. | |
query | Optional[str] | None | Search 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
APIAuthenticationErrorThe key of the service is missing or wrong.APIRateLimitErrorThe quota of the service is used.
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
| Name | Type | Default | Description |
|---|---|---|---|
items | Sequence[Sequence[Path]] | The files of each item. | |
progress | Optional[Callable[[int, int, Path], None]] | None | Called with (done, total, first file) after each item. |
Returns
List[BatchMatch]The matches, in the order of the items.
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
| Name | Type | Default | Description |
|---|---|---|---|
query | str | Text to search. | |
year | Optional[int] | None | Year in the name, or None. |
title | Optional[str] | None | Title to compare with the results; the query if None. |
author | Optional[str] | None | Author (books) or artist (tracks), or None. |
album | Optional[str] | None | Album of a track, from its tags, or None. |
search_kwargs | Dict[str, Any] | dict() | Extra search parameters, such as the title and the artist of a track for a precise search. |
Attributes
| Name | Type | Description |
|---|---|---|
album | Optional[str] | Album of a track, from its tags, or None. |
author | Optional[str] | Author (books) or artist (tracks), or None. |
query | str | Text to search. |
search_kwargs | Dict[str, Any] | Extra search parameters, such as the title and the artist of a track for a precise search. |
title | Optional[str] | Title to compare with the results; the query if None. |
year | Optional[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
| Name | Type | Description |
|---|---|---|
author | str | |
candidate | Dict[str, Any] |
candidate_authors
def candidate_authors(candidate: Dict[str, Any]) -> List[str]:Authors (books) or artist (music) of a search result, normalized.
Parameters
| Name | Type | Description |
|---|---|---|
candidate | Dict[str, Any] |
candidate_year
def candidate_year(candidate: Dict[str, Any]) -> Optional[int]:Year of a search result, from its first date field.
Parameters
| Name | Type | Description |
|---|---|---|
candidate | Dict[str, Any] |
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
| Name | Type | Default | Description |
|---|---|---|---|
query | str | Title to compare with the results. | |
year | Optional[int] | Year read from the file name, or None. | |
candidates | List[Dict[str, Any]] | Search results. | |
author | Optional[str] | None | Author or artist read from the file, or None. |
same_work | Optional[SameWork] | None | Tells when several matching results are one work. By default every result is a different work (movies). |
album | Optional[str] | None | Album 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) andstrthe status.
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
| Name | Type | Description |
|---|---|---|
files | List[Path] |
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
| Name | Type | Description |
|---|---|---|
text | str |
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
| Name | Type | Description |
|---|---|---|
candidate | Dict[str, Any] |
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
| Name | Type | Description |
|---|---|---|
files | Sequence[Path] |
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
| Name | Type | Description |
|---|---|---|
files | Sequence[Path] |
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
| Name | Type | Description |
|---|---|---|
files | Sequence[Path] |
parse_movie
def parse_movie(files: Sequence[Path]) -> ParsedName:Read a movie file name: "Dune.Part.Two.2024.mkv" → Dune Part Two, 2024.
Parameters
| Name | Type | Description |
|---|---|---|
files | Sequence[Path] |
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
| Name | Type | Description |
|---|---|---|
files | Sequence[Path] |
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
| Name | Type | Description |
|---|---|---|
files | Sequence[Path] |
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
| Name | Type | Description |
|---|---|---|
a | Dict[str, Any] | |
b | Dict[str, Any] |
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
| Name | Type | Description |
|---|---|---|
a | Dict[str, Any] | |
b | Dict[str, Any] |
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
| Name | Type | Description |
|---|---|---|
a | Dict[str, Any] | |
b | Dict[str, Any] |
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
| Name | Type | Description |
|---|---|---|
query | str | |
candidate | Dict[str, Any] |
Attributes
| Name | Value |
|---|---|
DATE_KEYS | ('release_date', 'first_air_date', 'published_date', 'year') |
MAX_CANDIDATES | 5 |
OTHER_RELEASES | ('compilation', 'live', 'remix') |
QueryParser | Callable[[Sequence[Path]], ParsedName] |
SEARCH_CONCURRENCY | 4 |
STATUS_AMBIGUOUS | 'ambiguous' |
STATUS_MISSING | 'missing' |
STATUS_READY | 'ok' |
SameWork | Callable[[Dict[str, Any], Dict[str, Any]], bool] |
TITLE_KEYS | ('title', 'name', 'original_title', 'original_name') |
logger | logging.getLogger(__name__) |