Metadata-Version: 2.1
Name: cs.id3
Version: 20211208
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/
Home-page: https://bitbucket.org/cameron_simpson/css/commits/all
Author: Cameron Simpson
Author-email: cs@cskk.id.au
License: GNU General Public License v3 or later (GPLv3+)
Keywords: python3
Platform: UNKNOWN
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+)
Description-Content-Type: text/markdown

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 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.

## Class `EnhancedTagFrame(cs.binary.SimpleBinary,types.SimpleNamespace,cs.binary.AbstractBinary,cs.binary.BinaryMixin)`

An Enhanced Tag.

### Method `EnhancedTagFrame.parse(bfr)`

Parse an enhanced tag.

### Method `EnhancedTagFrame.transcribe(self)`

Transcribe the enhanced tag.

## Class `ID3(types.SimpleNamespace)`

Wrapper for pyid3lib.tag.

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

### Method `ID3.__getitem__(self, key)`

Fetch the text of the specified frame.

### Method `ID3.__setitem__(self, key, value)`

Set a frame text to `value`.

### Method `ID3.clean(self, attr)`

Strip NULs and leading and trailing whitespace.

### Method `ID3.flush(self, *a, **kw)`

Update the ID3 tags in the file if modified, otherwise no-op.
Clears the modified flag.

### Method `ID3.get_frame(self, frameid)`

Return the frame with the specified `frameid`, or None.

### Property `ID3.tag`

The tag mapping from `self.pathname`.

## Class `ID3V1Frame(cs.binary.SimpleBinary,types.SimpleNamespace,cs.binary.AbstractBinary,cs.binary.BinaryMixin)`

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

### Method `ID3V1Frame.parse(bfr)`

Parse a 128 byte ID3V1 or ID3v1.1 record.

### Method `ID3V1Frame.tagset(self)`

Return a `TagSet` with the ID3 tag information.

### Method `ID3V1Frame.transcribe(self)`

Transcribe the ID3V1 frame.

## Class `ID3V22TagDataFrame(cs.binary.SimpleBinary,types.SimpleNamespace,cs.binary.AbstractBinary,cs.binary.BinaryMixin)`

An ID3 v2.2.0 tag data frame.

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

### Method `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.

## Class `ID3V23TagDataFrame(cs.binary.SimpleBinary,types.SimpleNamespace,cs.binary.AbstractBinary,cs.binary.BinaryMixin)`

An ID3 v2.3.0 tag data frame.

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

### Method `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.

## Class `ID3V2Frame(cs.binary.SimpleBinary,types.SimpleNamespace,cs.binary.AbstractBinary,cs.binary.BinaryMixin)`

An ID3v2 frame, based on the document at:
https://web.archive.org/web/20120527211939/http://www.unixgods.org/~tilo/ID3/docs/id3v2-00.html

### Method `ID3V2Frame.parse(bfr)`

Return an ID3v2 frame as described here:

### Method `ID3V2Frame.tagset(self)`

Return a `TagSet` with the ID3 tag information.

### Method `ID3V2Frame.transcribe(self)`

Transcribe the ID3v2 frame.

## Class `ID3V2Size(cs.binary.BinarySingleValue,cs.binary.AbstractBinary,cs.binary.BinaryMixin)`

An ID3v2 size field,
a big endian 4 byte field of 7-bit values, high bit 0.

### Method `ID3V2Size.parse_value(bfr)`

Read an ID3V2 size field from `bfr`, return the size.

### Method `ID3V2Size.transcribe_value(size)`

Transcribe a size in ID3v2 format.

## Class `ID3V2Tags(types.SimpleNamespace)`

An `ID3V2Tags` maps ID3V2 tag information as a `SimpleNamespace`.

### Method `ID3V2Tags.__getattr__(self, attr)`

Catch frame id attrs and their wordier versions.

### Method `ID3V2Tags.__setattr__(self, attr, value)`

Map attributes to frame ids, set the corresponding `__dict__` entry.

## Class `ISO8859_1NULString(cs.binary.BinarySingleValue,cs.binary.AbstractBinary,cs.binary.BinaryMixin)`

A NUL terminated string encoded with ISO8859-1.

### Method `ISO8859_1NULString.transcribe_value(s)`

pylint: disable=arguments-differ

## Function `padded_text(text, length, encoding='ascii')`

Encode `text` using `encoding`,
crop to a maximum of `length` bytes,
pad with NULs to `length` if necessary.

## Function `parse_padded_text(bfr, length, encoding='ascii')`

Fetch `length` bytes from `bfr`,
strip trailing NULs,
decode using `encoding` (default `'ascii'`),
strip trailling whitepsace.

## Class `TextEncodingClass(cs.binary.BinarySingleValue,cs.binary.AbstractBinary,cs.binary.BinaryMixin)`

A trite class to parse the single byte text encoding field.

## Class `TextInformationFrameBody(cs.binary.SimpleBinary,types.SimpleNamespace,cs.binary.AbstractBinary,cs.binary.BinaryMixin)`

A text information frame.

### Method `TextInformationFrameBody.parse(bfr)`

Parse the text from the frame.

### Method `TextInformationFrameBody.transcribe(self)`

Transcribe the frame.

## Class `UCS2NULString(cs.binary.BinarySingleValue,cs.binary.AbstractBinary,cs.binary.BinaryMixin)`

A NUL terminated string encoded with UCS-2.

We're cheating and using UTF16 for this.

### Method `UCS2NULString.transcribe_value(s)`

Transcribe text as UTF-16-LE with leading BOM and trailing NUL.

# Release Log



*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.

