Search

Processor operations that search for and match given items with remote items.

Searches for matches on remote APIs, matches the item to the best matching result from the query, and assigns the ID of the matched object back to the item.

Classes:

ItemSearchResult([matched, unmatched, skipped])	Stores the results of the searching process.
SearchConfig(match_fields[, ...])	Key settings related to a search algorithm.
RemoteItemSearcher(matcher, object_factory)	Searches for remote matches for a list of item collections.

class musify.processors.search.ItemSearchResult(matched=(), unmatched=(), skipped=())

Bases: Result, Generic

Stores the results of the searching process.

Attributes:

matched	Sequence of Items for which matches were found from the search.
unmatched	Sequence of Items for which matches were not found from the search.
skipped	Sequence of Items which were skipped during the search.

matched: Sequence[TypeVar(T, bound= MusifyItemSettable)] = ()

Sequence of Items for which matches were found from the search.

unmatched: Sequence[TypeVar(T, bound= MusifyItemSettable)] = ()

Sequence of Items for which matches were not found from the search.

skipped: Sequence[TypeVar(T, bound= MusifyItemSettable)] = ()

Sequence of Items which were skipped during the search.

class musify.processors.search.SearchConfig(match_fields, search_fields_1=(TagFields.NAME,), search_fields_2=(), search_fields_3=(), result_count=10, min_score=0.1, max_score=0.8, allow_karaoke=False)

Bases: object

Key settings related to a search algorithm.

Attributes:

match_fields	The fields to match results on.
search_fields_1	A sequence of the tag names to use as search fields in the 1st pass.
search_fields_2	If no results are found from the tag names in search_fields_1 on the 1st pass, an optional sequence of the tag names to use as search fields in the 2nd pass.
search_fields_3	If no results are found from the tag names in search_fields_2 on the 2nd pass, an optional sequence of the tag names to use as search fields in the 3rd pass.
result_count	The number of the results to request when querying the API.
min_score	The minimum acceptable score for an item to be considered a match.
max_score	The maximum score for an item to be considered a perfect match.
allow_karaoke	When True, items determined to be karaoke are allowed when matching added items.

match_fields: TagField | Iterable[TagField]

The fields to match results on.

search_fields_1: Sequence[TagField] = (TagFields.NAME,)

A sequence of the tag names to use as search fields in the 1st pass.

search_fields_2: Iterable[TagField] = ()

If no results are found from the tag names in search_fields_1 on the 1st pass, an optional sequence of the tag names to use as search fields in the 2nd pass.

search_fields_3: Iterable[TagField] = ()

If no results are found from the tag names in search_fields_2 on the 2nd pass, an optional sequence of the tag names to use as search fields in the 3rd pass.

result_count: int = 10

The number of the results to request when querying the API.

min_score: float = 0.1

The minimum acceptable score for an item to be considered a match.

max_score: float = 0.8

The maximum score for an item to be considered a perfect match. After this score is reached by an item, any other items are disregarded as potential matches.

allow_karaoke: bool = False

When True, items determined to be karaoke are allowed when matching added items. Skip karaoke results otherwise.

class musify.processors.search.RemoteItemSearcher(matcher, object_factory)

Bases: Processor

Searches for remote matches for a list of item collections.

Parameters:

• matcher (ItemMatcher) – The ItemMatcher to use when comparing any changes made by the user in remote playlists during the checking operation

• object_factory (RemoteObjectFactory) – The RemoteObjectFactory to use when creating new remote objects. This must have a RemoteAPI assigned for this processor to work as expected.

Attributes:

search_settings	The SearchSettings for each RemoteObjectType
api	The RemoteAPI to call
logger	The MusifyLogger for this object
matcher	The ItemMatcher to use when comparing any changes made by the user in remote playlists during the checking operation
factory	The RemoteObjectFactory to use when creating new remote objects.

Methods:

search(collections)	Searches for remote matches for the given list of item collections.
as_dict()	Return a dictionary representation of the key attributes of this object.

search_settings: dict[RemoteObjectType, SearchConfig] = {RemoteObjectType.TRACK: SearchConfig(match_fields={<TagFields.ARTIST: 32>, <TagFields.TITLE: 65>, <TagFields.ALBUM: 30>, <TagFields.LENGTH: 16>}, search_fields_1=[<TagFields.NAME: 1000>, <TagFields.ARTIST: 32>], search_fields_2=[<TagFields.NAME: 1000>, <TagFields.ALBUM: 30>], search_fields_3=[<TagFields.NAME: 1000>], result_count=10, min_score=0.1, max_score=0.8, allow_karaoke=False), RemoteObjectType.ALBUM: SearchConfig(match_fields={<TagFields.ARTIST: 32>, <TagFields.LENGTH: 16>, <TagFields.ALBUM: 30>}, search_fields_1=[<TagFields.NAME: 1000>, <TagFields.ARTIST: 32>], search_fields_2=[<TagFields.NAME: 1000>], search_fields_3=(), result_count=5, min_score=0.1, max_score=0.7, allow_karaoke=False)}

The SearchSettings for each RemoteObjectType

property api: RemoteAPI

The RemoteAPI to call

logger: MusifyLogger

The MusifyLogger for this object

matcher

The ItemMatcher to use when comparing any changes made by the user in remote playlists during the checking operation

factory

The RemoteObjectFactory to use when creating new remote objects.

async search(collections)

Searches for remote matches for the given list of item collections.

Returns:

dict[str, ItemSearchResult[TypeVar(T, bound= MusifyItemSettable)]] – Map of the collection’s name to its ItemSearchResult object.

as_dict()

Return a dictionary representation of the key attributes of this object.

Return type:

dict[str, Any]

The results of this function are used to produce the following:

• A JSON representation of the object when calling json()

• The string representation of the object when calling str() on the object

• The representation of the object when calling repr() on the object