Metadata-Version: 2.4
Name: cs-id3
Version: 20260531
Summary: Support for ID3 tags. A cs.binary based parser/transcriber for ID3 tags and a convenience wrapper for Doug Zongker's pyid3lib: http://pyid3lib.sourceforge.net/
Keywords: python3
Author-email: Cameron Simpson <cs@cskk.id.au>
Description-Content-Type: text/markdown
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Requires-Dist: cs.binary>=20260531
Requires-Dist: cs.buffer>=20250428
Requires-Dist: cs.logutils>=20250323
Requires-Dist: cs.pfx>=20250914
Requires-Dist: cs.threads>=20260531
Project-URL: MonoRepo Commits, https://bitbucket.org/cameron_simpson/css/commits/branch/main
Project-URL: Monorepo Git Mirror, https://github.com/cameron-simpson/css
Project-URL: Monorepo Hg/Mercurial Mirror, https://hg.sr.ht/~cameron-simpson/css
Project-URL: Source, https://github.com/cameron-simpson/css/blob/main/lib/python/cs/id3.py

Support for ID3 tags.
A cs.binary based parser/transcriber for ID3 tags
and a convenience wrapper for Doug Zongker's pyid3lib:
http://pyid3lib.sourceforge.net/

*Latest release 20260531*:
Provide value_type for the BinarySingleValue subclasses.

Short summary:
* `EnhancedTagFrame`: An Enhanced Tag.
* `ID3`: Wrapper for pyid3lib.tag.
* `ID3V1Frame`: An ID3V1 or ID3v1.1 data frame as described in wikipedia: https://en.wikipedia.org/wiki/ID3.
* `ID3V22TagDataFrame`: An ID3 v2.2.0 tag data frame.
* `ID3V23TagDataFrame`: An ID3 v2.3.0 tag data frame.
* `ID3V2Frame`: An ID3v2 frame, based on the document at: https://web.archive.org/web/20120527211939/http://www.unixgods.org/~tilo/ID3/docs/id3v2-00.html.
* `ID3V2Size`: An ID3v2 size field, a big endian 4 byte field of 7-bit values, high bit 0.
* `ID3V2Tags`: An `ID3V2Tags` maps ID3V2 tag information as a `SimpleNamespace`.
* `ISO8859_1NULString`: A NUL terminated string encoded with ISO8859-1.
* `padded_text`: Encode `text` using `encoding`, crop to a maximum of `length` bytes, pad with NULs to `length` if necessary.
* `parse_padded_text`: Fetch `length` bytes from `bfr`, strip trailing NULs, decode using `encoding` (default `'ascii'`), strip trailling whitepsace.
* `TextEncodingClass`: A trite class to parse the single byte text encoding field.
* `TextInformationFrameBody`: A text information frame.
* `UCS2NULString`: A NUL terminated string encoded with UCS-2.

Module contents:
- <a name="EnhancedTagFrame"></a>`class EnhancedTagFrame(cs.binary.SimpleBinary)`: An Enhanced Tag.

*`EnhancedTagFrame.parse(bfr)`*:
Parse an enhanced tag.

*`EnhancedTagFrame.transcribe(self)`*:
Transcribe the enhanced tag.
- <a name="ID3"></a>`class ID3(types.SimpleNamespace)`: Wrapper for pyid3lib.tag.

  OBSOLETE.
  Going away when I'm sure the other classes cover all this stuff off.

*`ID3.__getitem__(self, key)`*:
Fetch the text of the specified frame.

*`ID3.__setitem__(self, key, value)`*:
Set a frame text to `value`.

*`ID3.clean(self, attr)`*:
Strip NULs and leading and trailing whitespace.

*`ID3.flush(self)`*:
Update the ID3 tags in the file if modified, otherwise no-op.
Clears the modified flag.

*`ID3.get_frame(self, frameid)`*:
Return the frame with the specified `frameid`, or None.

*`ID3.tag`*:
The tag mapping from `self.pathname`.
- <a name="ID3V1Frame"></a>`class ID3V1Frame(cs.binary.SimpleBinary)`: An ID3V1 or ID3v1.1 data frame as described in wikipedia:
  https://en.wikipedia.org/wiki/ID3

  The following fields are defined:
  * `title`: up to 30 ASCII characters
  * `artist`: up to 30 ASCII characters
  * `album`: up to 30 ASCII characters
  * `year`: 4 digit ASCII year
  * `comment`: up to 30 ASCII bytes, NUL or whitespace padded,
    up to 28 ASCII bytes if `track` is nonzero
  * `track`: 0 for no track, a number from 1 through 255 otherwise;
    if nonzero then the comment field may only be up to 28 bytes long
  * `genre_id`: a number value from 0 to 255

*`ID3V1Frame.parse(bfr)`*:
Parse a 128 byte ID3V1 or ID3v1.1 record.

*`ID3V1Frame.tagset(self)`*:
Return a `TagSet` with the ID3 tag information.

*`ID3V1Frame.transcribe(self)`*:
Transcribe the ID3V1 frame.
- <a name="ID3V22TagDataFrame"></a>`class ID3V22TagDataFrame(cs.binary.SimpleBinary)`: An ID3 v2.2.0 tag data frame.

  Reference doc: https://id3.org/id3v2-00

*`ID3V22TagDataFrame.tag_id_class(tag_id)`*:
Return the `AbstractBinary` subclass to decode the a tag body from its tag id.
Return `None` for unrecognised ids.
- <a name="ID3V23TagDataFrame"></a>`class ID3V23TagDataFrame(cs.binary.SimpleBinary)`: An ID3 v2.3.0 tag data frame.

  Reference doc: https://id3.org/id3v2.3.0

*`ID3V23TagDataFrame.tag_id_class(tag_id)`*:
Return the `AbstractBinary` subclass to decode the a tag body from its tag id.
Return `None` for unrecognised ids.
- <a name="ID3V2Frame"></a>`class ID3V2Frame(cs.binary.SimpleBinary)`: An ID3v2 frame, based on the document at:
  https://web.archive.org/web/20120527211939/http://www.unixgods.org/~tilo/ID3/docs/id3v2-00.html

*`ID3V2Frame.parse(bfr)`*:
Return an ID3v2 frame as described here:

*`ID3V2Frame.tagset(self)`*:
Return a `TagSet` with the ID3 tag information.

*`ID3V2Frame.transcribe(self)`*:
Transcribe the ID3v2 frame.
- <a name="ID3V2Size"></a>`class ID3V2Size(cs.binary.BinarySingleValue)`: An ID3v2 size field,
  a big endian 4 byte field of 7-bit values, high bit 0.

*`ID3V2Size.VALUE_TYPE`*

*`ID3V2Size.parse_value(bfr)`*:
Read an ID3V2 size field from `bfr`, return the size.

*`ID3V2Size.transcribe_value(size)`*:
Transcribe a size in ID3v2 format.
- <a name="ID3V2Tags"></a>`class ID3V2Tags(types.SimpleNamespace)`: An `ID3V2Tags` maps ID3V2 tag information as a `SimpleNamespace`.

*`ID3V2Tags.__getattr__(self, attr)`*:
Catch frame id attrs and their wordier versions.

*`ID3V2Tags.__setattr__(self, attr, value)`*:
Map attributes to frame ids, set the corresponding `__dict__` entry.
- <a name="ISO8859_1NULString"></a>`class ISO8859_1NULString(cs.binary.BinarySingleValue)`: A NUL terminated string encoded with ISO8859-1.

*`ISO8859_1NULString.VALUE_TYPE`*

*`ISO8859_1NULString.transcribe_value(s)`*:
pylint: disable=arguments-differ
- <a name="padded_text"></a>`padded_text(text, length, encoding='ascii')`: Encode `text` using `encoding`,
  crop to a maximum of `length` bytes,
  pad with NULs to `length` if necessary.
- <a name="parse_padded_text"></a>`parse_padded_text(bfr, length, encoding='ascii')`: Fetch `length` bytes from `bfr`,
  strip trailing NULs,
  decode using `encoding` (default `'ascii'`),
  strip trailling whitepsace.
- <a name="TextEncodingClass"></a>`class TextEncodingClass(cs.binary.BinarySingleValue)`: A trite class to parse the single byte text encoding field.

*`TextEncodingClass.VALUE_TYPE`*
- <a name="TextInformationFrameBody"></a>`class TextInformationFrameBody(cs.binary.SimpleBinary)`: A text information frame.

*`TextInformationFrameBody.parse(bfr)`*:
Parse the text from the frame.

*`TextInformationFrameBody.transcribe(self)`*:
Transcribe the frame.
- <a name="UCS2NULString"></a>`class UCS2NULString(cs.binary.BinarySingleValue)`: A NUL terminated string encoded with UCS-2.

  We're cheating and using UTF16 for this.

*`UCS2NULString.VALUE_TYPE`*

*`UCS2NULString.transcribe_value(s)`*:
Transcribe text as UTF-16-LE with leading BOM and trailing NUL.

# Release Log



*Release 20260531*:
Provide value_type for the BinarySingleValue subclasses.

*Release 20211208*:
* ID3V1 and ID3V2 support.
* ID3V1Frame,ID3V2Frame: new .tagset() method to return a TagSet.
* ID3V1Frame.parse: trim trailing NULs from the comment field.
* Assorted other small changes.

*Release 20160828*:
Use "install_requires" instead of "requires" in DISTINFO.

*Release 20150116.2*:
pyid3lib not on PyPI, remove from requirements and mention in README

*Release 20150116*:
Initial PyPI release.
