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