lib/mutagen/easyid3.py

   1 # Simpler (but far more limited) API for ID3 editing
   2 # Copyright 2006 Joe Wreschnig
   3 #
   4 # This program is free software; you can redistribute it and/or modify
   5 # it under the terms of version 2 of the GNU General Public License as
   6 # published by the Free Software Foundation.
   7 #
   8 # $Id: id3.py 3086 2006-04-04 02:13:21Z piman $
   9
  10 """Easier access to ID3 tags.
  11
  12 EasyID3 is a wrapper around mutagen.id3.ID3 to make ID3 tags appear
  13 more like Vorbis or APEv2 tags.
  14 """
  15
  16 import mutagen.id3
  17 from mutagen import Metadata
  18 from mutagen._util import DictMixin
  19 from mutagen.id3 import ID3, error, delete
  20
  21 __all__ = ['EasyID3', 'Open', 'delete']
  22
  23 class EasyID3(DictMixin, Metadata):
  24     """A file with an ID3 tag.
  25
  26     Like Vorbis comments, EasyID3 keys are case-insensitive ASCII
  27     values. Only a subset of ID3 frames (those with simple text keys)
  28     are supported; EasyID3.valid_keys maps human-readable EasyID3
  29     names to ID3 frame IDs.
  30
  31     To use an EasyID3 class with mutagen.mp3.MP3:
  32         from mutagen.mp3 import MP3
  33         from mutagen.easyid3 import EasyID3
  34         MP3(filename, ID3=EasyID3)
  35     """
  36
  37     valid_keys = {
  38         "album": "TALB",
  39         "composer": "TCOM",
  40         "genre": "TCON",
  41         "date": "TDRC",
  42         "lyricist": "TEXT",
  43         "title": "TIT2",
  44         "version": "TIT3",
  45         "artist": "TPE1",
  46         "tracknumber": "TRCK",
  47         }
  48     """Valid keys for EasyID3 instances."""
  49
  50     def __init__(self, filename=None):
  51         self.__id3 = ID3()
  52         self.load = self.__id3.load
  53         self.save = self.__id3.save
  54         self.delete = self.__id3.delete
  55         if filename is not None:
  56             self.load(filename)
  57
  58     filename = property(lambda s: s.__id3.filename,
  59                         lambda s, fn: setattr(s.__id3, 'filename', fn))
  60
  61     _size = property(lambda s: s._id3.size,
  62                      lambda s, fn: setattr(s.__id3, '_size', fn))
  63
  64     def __TCON_get(self, frame):
  65         return frame.genres
  66
  67     def __TCON_set(self, frame, value):
  68         frame.encoding = 3
  69         if not isinstance(value, list):
  70             value = [value]
  71         frame.genres = value
  72
  73     def __TDRC_get(self, frame):
  74         return [stamp.text for stamp in frame.text]
  75
  76     def __TDRC_set(self, frame, value):
  77         self.__id3.add(mutagen.id3.TDRC(encoding=3, text=value))
  78
  79     def __text_get(self, frame):
  80         return list(frame)
  81
  82     def __text_set(self, frame, value):
  83         frame.encoding = 3
  84         if not isinstance(value, list):
  85             value = [value]
  86         frame.text = value
  87
  88     def __getitem__(self, key):
  89         key = key.lower()
  90         if key in self.valid_keys:
  91             frame = self.valid_keys[key]
  92             getter = self.__mungers.get(frame, self.__default)[0]
  93             return getter(self, self.__id3[frame])
  94         else: raise ValueError("%r is not a valid key" % key)
  95
  96     def __setitem__(self, key, value):
  97         key = key.lower()
  98         if key in self.valid_keys:
  99             frame = self.valid_keys[key]
 100             setter = self.__mungers.get(frame, self.__default)[1]
 101             if frame not in self.__id3:
 102                 frame = mutagen.id3.Frames[frame](encoding=3, text=value)
 103                 self.__id3.loaded_frame(frame)
 104             else:
 105                 setter(self, self.__id3[frame], value)
 106         else: raise ValueError("%r is not a valid key" % key)
 107
 108     def __delitem__(self, key):
 109         key = key.lower()
 110         if key in self.valid_keys:
 111             del(self.__id3[self.valid_keys[key]])
 112         else: raise ValueError("%r is not a valid key" % key)
 113
 114     def keys(self):
 115         return [k for (k, v) in self.valid_keys.items() if v in self.__id3]
 116
 117     def pprint(self):
 118         """Print tag key=value pairs."""
 119         strings = []
 120         for key in self.keys():
 121             values = self[key]
 122             for value in values:
 123                 strings.append("%s=%s" % (key, value))
 124         return "\n".join(strings)
 125
 126     __mungers = {
 127         "TCON": (__TCON_get, __TCON_set),
 128         "TDRC": (__TDRC_get, __TDRC_set),
 129         }
 130
 131     __default = (__text_get, __text_set)
 132
 133 Open = EasyID3