wiki_music.library.tags_handler and tags_io modules¶

Warning

Documentation is stil under construction some things might not be up to date.

library.tags_io¶

Expose high level tag writing and reading functions.

wiki_music.library.tags_io.read_tags(song_file: pathlib.Path) → Dict[str, Union[str, list, bytes]]¶

Convenience function which takes care of reading tags from file.

Abstracts away from low level mutagen API. If no tags are read, function can guess track title from file name, assumming some decent formating.

See also

wiki_music.constants.tags.TAGS: for list of supported tags
wiki_music.library.tags_handler: low level implemetation of tags handling built on mutagen library

Parameters:	song_file (Path) – path to song on disk
Returns:	dictionary of tag labels with coresponding values if the file could be loaded. If not then the dictionary is empty
Return type:	dict

wiki_music.library.tags_io.write_tags(data: SongDict)¶

Convenience function which takes care of writing data to tags.

See also

wiki_music.constants.tags.TAGS: for list of supported tags
wiki_music.library.tags_handler: low level implemetation of tags handling built on mutagen library

Parameters:	data (dict) – containes dictionary of tag names and coresponding values

wiki_music.library.tags_io.supported_tags()¶: Print a list of wiki_music supported tags.

library.tags_handler¶

Low level tags handling implementation based on mutagen library.

wiki_music.library.tags_handler.File(filename: Union[str, pathlib.Path]) → TagBase¶

Class factory which returns coresponding class based on file type.

Note

Currently supported types are: mp3, flac, m4a

Raises:	`UnsupportedFileType` – if file is not one of supported types
Returns:	one of the low level tag handling classes
Return type:	TagBase

class wiki_music.library.tags_handler.tag_base.SelectiveDict(*args)¶

Bases: dict

A subclass of a dictionary which remembers which keys are being changed.

Behaviur is archieved by simply overriding the __setitem__ method.

writable¶

a set of keys(tags) that were changed, and should be written to file

Type:	set

save_items()¶

Method simillar to dict.items().

Difference if this method loops through key-value pairs that have changed since the creation of this dictionary instance.

to_dict()¶

Cast contents of selective dict to dict.

Returns:	tags dictionary
Return type:	dict

library.tags_handler.mp3¶

Module for handling mp3 tags.

class wiki_music.library.tags_handler.mp3.TagMp3(filename: Path)¶

Bases: wiki_music.library.tags_handler.tag_base.TagBase

A low level implementation of tag handling for mp3 files.

_map_keys¶

a maping between highlevel tag names and lowlevel tag names used by mutagen impementation of tags for specific file type

Type:	dict

_reverse_map¶

reversed _map_keys dictionary

Type:	dict

_tags¶

private attribute which caches the read tags and records any occuring changes, it is exposed in class API through tags property

Type:	Selective_dict

See also

SelectiveDict: a subclass of a dictionary in which tags are stored, does remember changes in tags, so only the changed tags can be written
wiki_music.constants.tags.TAGS: for list of supported tags

Parameters:	filename (str) – path to song file with tags

static _get_default_tag(tag_name: str) → Union[bytes, str, list]¶

Return default value with corret type for each supported tag.

Parameters:	tag_name (str) – name of the tag which default value is desired

static _get_reversed(map_keys: Dict[str, str]) → Dict[str, Union[str, Callable]]¶

Swaps keys and values in dictionary.

Given a dictionary of [keys, values] it returns a reversed version with [values, key] while preserving order of items if is an instance of collections.OderedDict.

Returns:	dictionary with switched keys and values
Return type:	dict

static _key2str(key)¶

From string like <class ‘mutagen.id3.TCOM’> get the name TCOM.

Returns:	string reptresentation of mutagen.ID3 class tag name
Return type:	str

_open(filename: Path)¶: Function reading mp3 file to mutagen.id3.ID3 class.

static _process_tag(tag_name: str, tag: List[T]) → Union[bytes, str, list]¶

Postprocessing of each tag based on its expected type.

Parameters:	tag (List[Any]) – tag or a list of tags to be processed tag_name (str) – string identifying tag

_read() → Dict[str, Union[str, bytes]]¶

Reads tags from an open mutagen file to dictionary.

Tags are stored as key-value pairs. Tries to avoid all the pitfalls of different tag formats.

Returns:	dictionary of tag names and values
Return type:	dict

_write(tag: str, value: Union[str, bytes])¶

Write single tag to file.

Converts high level tag name, to low level which is specific for each implementation and write to file tags.

save()¶: Write tags to song file and than save to disk.

tags¶

Reads and returns file tags.

If the tags are present it reads them from a suplied file and casts them from dictionary to SelectiveDict type to record occured changes.

Returns:	dictionary containing tag labes and their values
Return type:	SelectiveDict

library.tags_handler.m4a¶

Module for handling m4a tags.

class wiki_music.library.tags_handler.m4a.TagM4a(filename: Path)¶

Bases: wiki_music.library.tags_handler.tag_base.TagBase

A low level implementation of tag handling for m4a files.

_map_keys¶

a maping between highlevel tag names and lowlevel tag names used by mutagen impementation of tags for specific file type

Type:	dict

_reverse_map¶

reversed _map_keys dictionary

Type:	dict

_tags¶

private attribute which caches the read tags and records any occuring changes, it is exposed in class API through tags property

Type:	Selective_dict

See also

SelectiveDict: a subclass of a dictionary in which tags are stored, does remember changes in tags, so only the changed tags can be written
wiki_music.constants.tags.TAGS: for list of supported tags

Parameters:	filename (str) – path to song file with tags

static _get_default_tag(tag_name: str) → Union[bytes, str, list]¶

Return default value with corret type for each supported tag.

Parameters:	tag_name (str) – name of the tag which default value is desired

static _get_reversed(map_keys: Dict[str, str]) → Dict[str, Union[str, Callable]]¶

Swaps keys and values in dictionary.

Given a dictionary of [keys, values] it returns a reversed version with [values, key] while preserving order of items if is an instance of collections.OderedDict.

Returns:	dictionary with switched keys and values
Return type:	dict

_open(filename: Path)¶: Function reading m4a file to mutagen.mp4.MP4 class.

static _process_tag(tag_name: str, tag: List[T]) → Union[bytes, str, list]¶

Postprocessing of each tag based on its expected type.

Parameters:	tag (List[Any]) – tag or a list of tags to be processed tag_name (str) – string identifying tag

_read() → Dict[str, Union[str, bytes]]¶

Reads tags from an open mutagen file to dictionary.

Tags are stored as key-value pairs. Tries to avoid all the pitfalls of different tag formats.

Returns:	dictionary of tag names and values
Return type:	dict

_write(tag: str, value: Union[str, bytes])¶

Write single tag to file.

Converts high level tag name, to low level which is specific for each implementation and write to file tags.

save()¶: Write tags to song file and than save to disk.

tags¶

Reads and returns file tags.

If the tags are present it reads them from a suplied file and casts them from dictionary to SelectiveDict type to record occured changes.

Returns:	dictionary containing tag labes and their values
Return type:	SelectiveDict

library.tags_handler.flac¶

Module for handling flac tags.

class wiki_music.library.tags_handler.flac.TagFlac(filename: Path)¶

Bases: wiki_music.library.tags_handler.tag_base.TagBase

A low level implementation of tag handling for flac files.

_map_keys¶

a maping between highlevel tag names and lowlevel tag names used by mutagen impementation of tags for specific file type

Type:	dict

_reverse_map¶

reversed _map_keys dictionary

Type:	dict

_tags¶

private attribute which caches the read tags and records any occuring changes, it is exposed in class API through tags property

Type:	Selective_dict

See also

SelectiveDict: a subclass of a dictionary in which tags are stored, does remember changes in tags, so only the changed tags can be written
wiki_music.constants.tags.TAGS: for list of supported tags

Parameters:	filename (str) – path to song file with tags

static _get_default_tag(tag_name: str) → Union[bytes, str, list]¶

Return default value with corret type for each supported tag.

Parameters:	tag_name (str) – name of the tag which default value is desired

static _get_reversed(map_keys: Dict[str, str]) → Dict[str, Union[str, Callable]]¶

Swaps keys and values in dictionary.

Given a dictionary of [keys, values] it returns a reversed version with [values, key] while preserving order of items if is an instance of collections.OderedDict.

Returns:	dictionary with switched keys and values
Return type:	dict

_open(filename: Path)¶: Function reading flac file to mutagen.flac.FLAC class.

static _process_tag(tag_name: str, tag: List[T]) → Union[bytes, str, list]¶

Postprocessing of each tag based on its expected type.

Parameters:	tag (List[Any]) – tag or a list of tags to be processed tag_name (str) – string identifying tag

_read() → Dict[str, Union[str, bytes]]¶

Reads tags from an open mutagen file to dictionary.

Tags are stored as key-value pairs. Tries to avoid all the pitfalls of different tag formats.

Returns:	dictionary of tag names and values
Return type:	dict

_write(tag: str, value: Union[str, bytes])¶

Write single tag to file.

Converts high level tag name, to low level which is specific for each implementation and write to file tags.

save()¶: Write tags to song file and than save to disk.

tags¶

Reads and returns file tags.

If the tags are present it reads them from a suplied file and casts them from dictionary to SelectiveDict type to record occured changes.

Returns:	dictionary containing tag labes and their values
Return type:	SelectiveDict