class TextFrame(Frame):
"""Text strings.
Text frames support casts to unicode or str objects, as well as
list-like indexing, extend, and append.
Iterating over a TextFrame iterates over its strings, not its
characters.
Text frames have a 'text' attribute which is the list of strings,
and an 'encoding' attribute; 0 for ISO-8859 1, 1 UTF-16, 2 for
UTF-16BE, and 3 for UTF-8. If you don't want to worry about
encodings, just set it to 3.
"""
_framespec = [
EncodingSpec('encoding'),
MultiSpec('text', EncodedTextSpec('text'), sep=u'\u0000'),
]
def __bytes__(self):
return text_type(self).encode('utf-8')
def __str__(self):
return u'\u0000'.join(self.text)
def __eq__(self, other):
if isinstance(other, bytes):
return bytes(self) == other
elif isinstance(other, text_type):
return text_type(self) == other
return self.text == other
__hash__ = Frame.__hash__
def __getitem__(self, item):
return self.text[item]
def __iter__(self):
return iter(self.text)
def append(self, value):
"""Append a string."""
return self.text.append(value)
def extend(self, value):
"""Extend the list by appending all strings from the given list."""
return self.text.extend(value)
def _pprint(self):
return " / ".join(self.text)
class NumericPartTextFrame(TextFrame):
"""Multivalue numerical text strings.
These strings indicate 'part (e.g. track) X of Y', and unary plus
returns the first value::
frame = TRCK('4/15')
track = +frame # track == 4
"""
_framespec = [
EncodingSpec('encoding'),
MultiSpec('text', EncodedNumericPartTextSpec('text'), sep=u'\u0000'),
]
def __pos__(self):
return int(self.text[0].split("/")[0])
class NumericTextFrame(TextFrame):
"""Numerical text strings.
The numeric value of these frames can be gotten with unary plus, e.g.::
frame = TLEN('12345')
length = +frame
"""
_framespec = [
EncodingSpec('encoding'),
MultiSpec('text', EncodedNumericTextSpec('text'), sep=u'\u0000'),
]
def __pos__(self):
"""Return the numerical value of the string."""
return int(self.text[0])
class COMM(TextFrame):
"""User comment.
User comment frames have a descrption, like TXXX, and also a three
letter ISO language code in the 'lang' attribute.
"""
_framespec = [
EncodingSpec('encoding'),
StringSpec('lang', 3),
EncodedTextSpec('desc'),
MultiSpec('text', EncodedTextSpec('text'), sep=u'\u0000'),
]
@property
def HashKey(self):
return '%s:%s:%r' % (self.FrameID, self.desc, self.lang)
def _pprint(self):
return "%s=%r=%s" % (self.desc, self.lang, " / ".join(self.text))
class TXXX(TextFrame):
"""User-defined text data.
TXXX frames have a 'desc' attribute which is set to any Unicode
value (though the encoding of the text and the description must be
the same). Many taggers use this frame to store freeform keys.
"""
_framespec = [
EncodingSpec('encoding'),
EncodedTextSpec('desc'),
MultiSpec('text', EncodedTextSpec('text'), sep=u'\u0000'),
]
@property
def HashKey(self):
return '%s:%s' % (self.FrameID, self.desc)
def _pprint(self):
return "%s=%s" % (self.desc, " / ".join(self.text))
class TimeStampTextFrame(TextFrame):
"""A list of time stamps.
The 'text' attribute in this frame is a list of ID3TimeStamp
objects, not a list of strings.
"""
_framespec = [
EncodingSpec('encoding'),
MultiSpec('text', TimeStampSpec('stamp'), sep=u','),
]
def __bytes__(self):
return text_type(self).encode('utf-8')
def __str__(self):
return ','.join([stamp.text for stamp in self.text])
def _pprint(self):
return " / ".join([stamp.text for stamp in self.text])
class PairedTextFrame(Frame):
"""Paired text strings.
Some ID3 frames pair text strings, to associate names with a more
specific involvement in the song. The 'people' attribute of these
frames contains a list of pairs::
[['trumpet', 'Miles Davis'], ['bass', 'Paul Chambers']]
Like text frames, these frames also have an encoding attribute.
"""
_framespec = [
EncodingSpec('encoding'),
MultiSpec('people', EncodedTextSpec('involvement'),
EncodedTextSpec('person'))
]
def __eq__(self, other):
return self.people == other
__hash__ = Frame.__hash__
