1py-ApeTag (formally pylibape/py-apev2tag) is a pure Python library for
2manipulating both APEv2 and ID3v1 tags. It aims for standards compliance with
3the APE spec (http://wiki.hydrogenaudio.org/index.php?title=APEv2_specification).
4APE is the standard tagging format for Musepack (.mpc) and Monkey's Audio files
5(.ape), and it can also be used with mp3s as an alternative to the mess that is
6ID3v2.x (technically, it can be used on any file type and is not limited to
7storing just audio file metadata).
8
9The module is in written in pure Python, so it should be useable on all
10platforms that Python supports. It has been tested on Windows and OpenBSD.
11The minimum python version required should be 2.2, since the code uses
12list comprehensions (testing has only been done on 2.4). Modifying the code to
13work with Python 2.0 shouldn't be difficult, though there aren't any plans to
14do so.
15
16The library is complete, but it hasn't been widely used, so there may still be
17some bugs in it. I haven't found any bugs in my normal use of it that I
18haven't already fixed, though.
19
20The public functions should be named obviously. There are functions for
21creating, replacing, updating, and deleting APE and ID3 tags both separately
22and together. There are also functions for getting the fields and the raw
23string for the tags, as well as checking for existence of tags. There are also
24advanced modify functions that take callback functions allowing complete
25manipulation of the tags. Public function arguments, return values, and
26various notes are stored in the module docstring.
27
28To run the tests for the library, run python test_ApeTag.py.
29
30If you find any bugs, would like additional documentation, or want to submit a
31patch, please use Sourceforge (http://sourceforge.net/projects/pylibape/).
32
33The most current source code can be accessed via anonymous SVN at
34svn://code.jeremyevans.net/py-ApeTag/. Note that the library isn't modified on a
35regular basis, so it is unlikely to be different from the latest release.
36
37Thank you for downloading this library. I hope you find it useful.
38
39Changelog:
401.2 - 2007-11-06
41- Raise error if APE footer flags wrong, instead of assuming no tag exists in
42 file
43
441.1 - 2007-11-06
45- Allow use of read only flag on APE tag itself
46
471.0 - 2007-01-13
48- Replace manual test files with automated unittest-based test suite
49- Ensure UTF-8 encoding for tag items marked "external"
50- Check for matching header and footer tag sizes and item counts
51- Return boolean for hastags
52- Join values with commas when creating ID3 tags from APE fields, instead of
53 taking the first value
54- Work with small file sizes (including zero byte files)
55- In updatetags, make removefields case insensitive when removing fields
56 from the ID3 tag
57- Fix createid3 being defined the same as updateid3, and thus giving errors on
58 files without ID3 tags
59- Make APEv2 Date field correspond to ID3v1 year field if it is an integer
60- Add shebang line for running library directly
61
620.12 - 2005-09-03
63- Convert the the library to use callback functions internally for modifying
64 tags
65- New has* functions to check for the existence of tags
66- New print* functions for pretty printing tag fields
67- New modify* functions that allow for user defined callbacks
68- Ability to call the library on the command line with filenames (prints the
69 tag fields for each file)
70- Fix bugs in id3 tagging when both tags are modified simultaneously
71- Small performance improvements offsetting the speed reduction due to callback
72 functions
73
740.11 - 2005-04-02
75- Add getrawtags and gettagfields public functions that return a tuple of
76 strings and dicts, respectively for the APE and ID3 tags. This results in a
77 substantial speedup compared to calling the functions for the APE and ID3
78 tags separately.
79- Add ability to specify type and readonly flag for ApeItems on initialization
80- Only use unicode for utf8 ApeItems; binary, external, and reserved items use
81 regular strings.
82
830.10 - 2005-03-21
84- Better automated conversion from APE fields to ID3 fields in functions that
85 modify both tags
86- Update the ID3 and APE tags at the same time if modifying both tags (instead
87 of opening and closing the file twice)
88
890.9 - 2005-03-20
90- Rename module from apev2tag to ApeTag
91- Remove apev2tag and id3tag functions, the helper functions that debuted in
92 0.8 are now the public interface to the library
93- Significant internal changes, most notably error handling during APE tag
94 parsing (fixing a possible denial of service caused by a malicious tag) and
95 automated closing of files opened by the library
96- Return values for the APE create, update, replace, and getfields functions
97 have changed, they now returns of dict with ApeItem (a list subclass with
98 unicode strings) values, instead of the previous dict with values that could
99 be strings, unicode strings, could be lists, or dicts.
100- Easier benchmarking in speedtest, defaults to test all functions
101- Added ability to read, create, and modify the read only tag flag.
102- Added ability to modify the maximum size of APE tags (default still 8K)
103
1040.8 - 2005-03-13
105- Helper functions such as createtags, deletetags, getrawapev2, getid3fields,
106 etc. added so you don't have to call id3tag and apev2tag directly with the
107 appropriate action.
108- You can now pass a filename instead of a file-like object to any of the
109 public functions.
110- Revised tests removing much of the duplicative code
111- Line endings for all files converted to LF (was a mix of LF and CRLF before)
112
1130.7 - 2005-02-05
114- Entire code base refactored, resulting in major performance enhancements in
115 parsing and writing APEv2 tags (over twice as fast as 0.6)
116- Code made simpler, more modular, and less duplicative
117- Internal functions changed to private functions
118- TagError class simplified, now raised similar to other exceptions
119- Private module variables added (acting as constants)
120- Import of string removed (hasn't been necessary since 0.5)
121
1220.6 - 2004-07-17
123- Rename module from pylibape to apev2tag
124- Rename functions from ape and id3 to apev2tag and id3tag
125- Instead of searching through the last 8K of the file, use the information in
126 the APEv2 tag footer to locate the rest of the tag
127- Minor fixes elsewhere
128
1290.5 - 2004-02-14
130- Initial public release
131