eyeD3 0.9.8__py3-none-any.whl

eyed3/__about__.py

@@ -0,0 +1,27 @@
+from .__regarding__ import *  # noqa: F403
+
+__project_name__ = project_name
+__version__ = version
+__version_info__ = version_info
+__release_name__ = version_info.release_name
+__years__ = years
+
+__project_slug__ = "eyed3"
+__pypi_name__ = "eyeD3"
+__author__ = author
+__author_email__ = author_email
+__url__ = homepage
+__description__ = description
+# FIXME: __long_description__ not being used anywhere.
+__long_description__ = """
+eyeD3 is a Python module and command line program for processing ID3 tags.
+Information about mp3 files (i.e bit rate, sample frequency,
+play time, etc.) is also provided. The formats supported are ID3
+v1.0/v1.1 and v2.3/v2.4.
+"""
+__license__ = "GNU GPL v3.0"
+__github_url__ = "https://github.com/nicfit/eyeD3",
+__version_txt__ = """%(__project_name__)s %(__version__)s © Copyright %(__years__)s %(__author__)s
+This program comes with ABSOLUTELY NO WARRANTY! See LICENSE for details.
+Run with --help/-h for usage information or read the docs at
+%(__url__)s""" % (locals())

eyed3/__init__.py

@@ -0,0 +1,38 @@
+import sys
+import codecs
+import locale
+from .__about__ import __version__ as version
+
+_DEFAULT_ENCODING = "latin1"
+# The local encoding, used when parsing command line options, console output,
+# etc. The default is always ``latin1`` if it cannot be determined, it is NOT
+# the value shown.
+LOCAL_ENCODING = locale.getpreferredencoding(do_setlocale=True)
+if not LOCAL_ENCODING or LOCAL_ENCODING == "ANSI_X3.4-1968":  # pragma: no cover
+    LOCAL_ENCODING = _DEFAULT_ENCODING
+
+# The local file system encoding, the default is ``latin1`` if it cannot be determined.
+LOCAL_FS_ENCODING = sys.getfilesystemencoding()
+if not LOCAL_FS_ENCODING:  # pragma: no cover
+    LOCAL_FS_ENCODING = _DEFAULT_ENCODING
+
+
+class Error(Exception):
+    """Base exception type for all eyed3 errors."""
+    def __init__(self, *args):
+        super().__init__(*args)
+        if args:
+            # The base class will do exactly this if len(args) == 1,
+            # but not when > 1. Note, the 2.7 base class will, 3 will not.
+            # Make it so.
+            self.message = args[0]
+
+
+from .utils.log import log                                          # noqa: E402
+from .core import load, AudioFile                                   # noqa: E402
+
+del sys
+del codecs
+del locale
+
+__all__ = ["AudioFile", "load", "log", "version", "LOCAL_ENCODING", "LOCAL_FS_ENCODING", "Error"]

eyed3/__regarding__.py

@@ -0,0 +1,48 @@
+"""
+~~~~~~~~~~ DO NOT EDIT THIS FILE! Autogenerated by `regarding` ~~~~~~~~~~
+https://github.com/nicfit/regarding
+"""
+import dataclasses
+from typing import Optional
+
+
+__all__ = ["project_name", "version", "version_info",
+           "author", "author_email", "years", "description", "homepage"]
+
+
+@dataclasses.dataclass
+class Version:
+    major: int
+    minor: int
+    micro: int
+    dev: Optional[int]
+    pre: Optional[tuple[str, int]]
+    post: Optional[int]
+    release_name: Optional[str]
+
+
+project_name = "eyeD3"
+version = "0.9.8"
+version_info = Version(
+    0, 9, 8,
+    None,
+    None,
+    None,
+    "Armed & Dangerous",
+)
+
+author = "Travis Shirk"
+author_email = "travis@pobox.com"
+years = "2002-2025"
+description = "Python audio data toolkit (ID3 and MP3)"
+homepage = "https://eyeD3.nicfit.net/"
+
+
+def versionBanner() -> str:
+    """Return the version string including release name."""
+    v = ""
+    if version:
+        v = version
+        if version_info is not None and version_info.release_name:
+            v = "%s (%s)" % (v, version_info.release_name)
+    return v

eyed3/core.py

@@ -0,0 +1,484 @@
+"""Basic core types and utilities."""
+import os
+import time
+import functools
+import pathlib
+import dataclasses
+from collections import namedtuple
+from typing import Optional
+
+from . import LOCAL_FS_ENCODING
+from .utils.log import getLogger
+log = getLogger(__name__)
+
+# Audio type selector for no audio.
+AUDIO_NONE = 0
+# Audio type selector for MPEG (mp3) audio.
+AUDIO_MP3 = 1
+
+AUDIO_TYPES = (AUDIO_NONE, AUDIO_MP3)
+
+LP_TYPE = "lp"
+EP_TYPE = "ep"
+EP_MAX_SIZE_HINT = 6
+COMP_TYPE = "compilation"
+LIVE_TYPE = "live"
+VARIOUS_TYPE = "various"
+DEMO_TYPE = "demo"
+SINGLE_TYPE = "single"
+ALBUM_TYPE_IDS = [LP_TYPE, EP_TYPE, COMP_TYPE, LIVE_TYPE, VARIOUS_TYPE,
+                  DEMO_TYPE, SINGLE_TYPE]
+VARIOUS_ARTISTS = "Various Artists"
+
+# A key that can be used in a TXXX frame to specify the type of collection
+# (or album) a file belongs. See :class:`eyed3.core.ALBUM_TYPE_IDS`.
+TXXX_ALBUM_TYPE = "eyeD3#album_type"
+
+# A key that can be used in a TXXX frame to specify the origin of an
+# artist/band. i.e. where they are from.
+# The format is: city<tab>state<tab>country
+TXXX_ARTIST_ORIGIN = "eyeD3#artist_origin"
+
+# A 2-tuple for count and a total count. e.g. track 3 of 10, count of total.
+CountAndTotalTuple = namedtuple("CountAndTotalTuple", "count, total")
+
+
+@dataclasses.dataclass
+class ArtistOrigin:
+    city: str
+    state: str
+    country: str
+
+    def __bool__(self):
+        return bool(self.city or self.state or self.country)
+
+    def id3Encode(self):
+        return "\t".join([(o if o else "") for o in dataclasses.astuple(self)])
+
+
+@dataclasses.dataclass
+class AudioInfo:
+    """A base container for common audio details."""
+
+    # The number of seconds of audio data (i.e., the playtime)
+    time_secs: float
+    # The number of bytes of audio data.
+    size_bytes: int
+
+    def __post_init__(self):
+        self.time_secs = int(self.time_secs * 100.0) / 100.0
+
+
+class Tag:
+    """An abstract interface for audio tag (meta) data (e.g. artist, title,
+    etc.)
+    """
+
+    read_only: bool = False
+
+    def _setArtist(self, val):
+        raise NotImplementedError()  # pragma: nocover
+
+    def _getArtist(self):
+        raise NotImplementedError()  # pragma: nocover
+
+    def _getAlbumArtist(self):
+        raise NotImplementedError()  # pragma: nocover
+
+    def _setAlbumArtist(self, val):
+        raise NotImplementedError()  # pragma: nocover
+
+    def _setAlbum(self, val):
+        raise NotImplementedError()  # pragma: nocover
+
+    def _getAlbum(self):
+        raise NotImplementedError()  # pragma: nocover
+
+    def _setTitle(self, val):
+        raise NotImplementedError()  # pragma: nocover
+
+    def _getTitle(self):
+        raise NotImplementedError()  # pragma: nocover
+
+    def _setTrackNum(self, val):
+        raise NotImplementedError()  # pragma: nocover
+
+    def _getTrackNum(self) -> CountAndTotalTuple:
+        raise NotImplementedError()  # pragma: nocover
+
+    @property
+    def artist(self):
+        return self._getArtist()
+
+    @artist.setter
+    def artist(self, v):
+        self._setArtist(v)
+
+    @property
+    def album_artist(self):
+        return self._getAlbumArtist()
+
+    @album_artist.setter
+    def album_artist(self, v):
+        self._setAlbumArtist(v)
+
+    @property
+    def album(self):
+        return self._getAlbum()
+
+    @album.setter
+    def album(self, v):
+        self._setAlbum(v)
+
+    @property
+    def title(self):
+        return self._getTitle()
+
+    @title.setter
+    def title(self, v):
+        self._setTitle(v)
+
+    @property
+    def track_num(self) -> CountAndTotalTuple:
+        """Track number property.
+        Must return a 2-tuple of (track-number, total-number-of-tracks).
+        Either tuple value may be ``None``.
+        """
+        return self._getTrackNum()
+
+    @track_num.setter
+    def track_num(self, v):
+        self._setTrackNum(v)
+
+    def __init__(self, title=None, artist=None, album=None, album_artist=None, track_num=None):
+        self.title = title
+        self.artist = artist
+        self.album = album
+        self.album_artist = album_artist
+        self.track_num = track_num
+
+
+class AudioFile:
+    """Abstract base class for audio file types (AudioInfo + Tag)"""
+    _tag: Tag = None
+    _info: AudioInfo = None
+
+    def _read(self):
+        """Subclasses MUST override this method and set ``self._info``,
+        ``self._tag`` and ``self.type``.
+        """
+        raise NotImplementedError()
+
+    def initTag(self, version=None):
+        raise NotImplementedError()
+
+    def rename(self, name, fsencoding=LOCAL_FS_ENCODING,
+               preserve_file_time=False):
+        """Rename the file to ``name``.
+        The encoding used for the file name is :attr:`eyed3.LOCAL_FS_ENCODING`
+        unless overridden by ``fsencoding``. Note, if the target file already
+        exists, or the full path contains non-existent directories the
+        operation will fail with :class:`IOError`.
+        File times are not modified when ``preserve_file_time`` is ``True``,
+        ``False`` is the default.
+        """
+        curr_path = pathlib.Path(self.path)
+        ext = curr_path.suffix
+
+        new_path = curr_path.parent / "{name}{ext}".format(**locals())
+        if new_path.exists():
+            raise IOError(f"File '{new_path}' exists, will not overwrite")
+        elif not new_path.parent.exists():
+            raise IOError("Target directory '%s' does not exists, will not "
+                          "create" % new_path.parent)
+
+        os.rename(self.path, str(new_path))
+        if self.tag:
+            self.tag.file_info.name = str(new_path)
+        if preserve_file_time:
+            self.tag.file_info.touch((self.tag.file_info.atime,
+                                      self.tag.file_info.mtime))
+
+        self.path = str(new_path)
+
+    @property
+    def path(self):
+        """The absolute path of this file."""
+        return self._path
+
+    @path.setter
+    def path(self, path):
+        """Set the path"""
+        if isinstance(path, pathlib.Path):
+            path = str(path)
+        self._path = path
+
+    @property
+    def info(self) -> AudioInfo:
+        """Returns a concrete implementation of :class:`eyed3.core.AudioInfo`"""
+        return self._info
+
+    @property
+    def tag(self):
+        """Returns a concrete implementation of :class:`eyed3.core.Tag`"""
+        return self._tag
+
+    @tag.setter
+    def tag(self, t):
+        self._tag = t
+
+    def __init__(self, path):
+        """Construct with a path and invoke ``_read``.
+        All other members are set to None."""
+        if isinstance(path, pathlib.Path):
+            path = str(path)
+        self.path = path
+
+        self.type = None
+        self._info = None
+        self._tag = None
+        self._read()
+
+    def __str__(self):
+        return str(self.path)
+
+
+@functools.total_ordering
+class Date:
+    """
+    A class for representing a date and time (optional). This class differs
+    from ``datetime.datetime`` in that the default values for month, day,
+    hour, minute, and second is ``None`` and not 'January 1, 00:00:00'.
+    This allows for an object that is simply 1987, and not January 1 12AM,
+    for example. But when more resolution is required those vales can be set
+    as well.
+    """
+
+    TIME_STAMP_FORMATS = ["%Y",
+                          "%Y-%m",
+                          "%Y-%m-%d",
+                          "%Y-%m-%dT%H",
+                          "%Y-%m-%dT%H:%M",
+                          "%Y-%m-%dT%H:%M:%S",
+                          # The following end with 'Z' signally time is UTC
+                          "%Y-%m-%dT%HZ",
+                          "%Y-%m-%dT%H:%MZ",
+                          "%Y-%m-%dT%H:%M:%SZ",
+                          # The following are wrong per the specs, but ...
+                          "%Y-%m-%d %H:%M:%S",
+                          "%Y-00-00",
+                          "%Y%m%d",
+                          # Special formats to support ID3v2.3 TDAT and TIME frames.
+                          # See https://github.com/nicfit/eyeD3/pull/623 and frames.Date.date setter
+                          "D%d-%m",
+                          "T%H:%M",
+                          ]
+    """Valid time stamp formats per ISO 8601 and used by `strptime`."""
+
+    @classmethod
+    def __new__(cls, *args, **kwargs):
+        if ([arg for arg in args[1:] if arg is not None] or
+            [kwarg for kwarg in kwargs.values() if kwarg is not None]):
+            return super().__new__(cls)
+        else:
+            return
+
+    def __init__(self, year=None, month=None, day=None,
+                 hour=None, minute=None, second=None):
+        # Validate with datetime
+        from datetime import datetime
+        _ = datetime(year if year is not None else 1899,
+                     month if month is not None else 1,
+                     day if day is not None else 1,
+                     hour if hour is not None else 0,
+                     minute if minute is not None else 0,
+                     second if second is not None else 0)
+
+        self._year = year
+        self._month = month
+        self._day = day
+        self._hour = hour
+        self._minute = minute
+        self._second = second
+
+        # Python's date classes do a lot more date validation than does not
+        # need to be duplicated here.  Validate it
+        _ = Date._validateFormat(str(self))                           # noqa
+
+    @property
+    def year(self):
+        return self._year
+
+    @property
+    def month(self):
+        return self._month
+
+    @property
+    def day(self):
+        return self._day
+
+    @property
+    def hour(self):
+        return self._hour
+
+    @property
+    def minute(self):
+        return self._minute
+
+    @property
+    def second(self):
+        return self._second
+
+    def __eq__(self, rhs):
+        if not rhs:
+            return False
+
+        return (self.year == rhs.year and
+                self.month == rhs.month and
+                self.day == rhs.day and
+                self.hour == rhs.hour and
+                self.minute == rhs.minute and
+                self.second == rhs.second)
+
+    def __ne__(self, rhs):
+        return not (self == rhs)
+
+    def __lt__(self, rhs):
+        if not rhs:
+            return False
+
+        for left, right in ((self.year, rhs.year),
+                            (self.month, rhs.month),
+                            (self.day, rhs.day),
+                            (self.hour, rhs.hour),
+                            (self.minute, rhs.minute),
+                            (self.second, rhs.second)):
+
+            left = left if left is not None else -1
+            right = right if right is not None else -1
+
+            if left < right:
+                return True
+            elif left > right:
+                return False
+
+        return False
+
+    def __hash__(self):
+        return hash(str(self))
+
+    @staticmethod
+    def _validateFormat(s):
+        pdate, fmt = None, None
+        for fmt in Date.TIME_STAMP_FORMATS:
+            try:
+                pdate = time.strptime(s, fmt)
+                break
+            except ValueError:
+                # date string did not match format.
+                continue
+
+        if pdate is None:
+            raise ValueError(f"Invalid date string: {s}")
+
+        assert pdate
+        return pdate, fmt
+
+    @staticmethod
+    def parse(s):
+        """Parses date strings that conform to ISO-8601."""
+        if not isinstance(s, str):
+            s = s.decode("ascii")
+        s = s.strip('\x00')
+
+        pdate, fmt = Date._validateFormat(s)
+
+        # Here is the difference with Python date/datetime objects, some
+        # of the members can be None
+        kwargs = {}
+        if "%Y" in fmt:
+            kwargs["year"] = pdate.tm_year
+        if "%m" in fmt:
+            kwargs["month"] = pdate.tm_mon
+        if "%d" in fmt:
+            kwargs["day"] = pdate.tm_mday
+        if "%H" in fmt:
+            kwargs["hour"] = pdate.tm_hour
+        if "%M" in fmt:
+            kwargs["minute"] = pdate.tm_min
+        if "%S" in fmt:
+            kwargs["second"] = pdate.tm_sec
+
+        return Date(**kwargs)
+
+    def __str__(self):
+        """Returns date strings that conform to ISO-8601.
+        The returned string will be no larger than 17 characters."""
+        s = ""  # the string
+        c = ""  # the separator character
+        if self.year is not None:  # branch 1, aka "there is a year, maybe more"
+            s += "%d" % self.year
+            c = "-"
+            if self.month is not None:  # there is a month
+                s += c + "%s" % str(self.month).rjust(2, '0')
+                if self.day is not None:  # there is a day
+                    s += c + "%s" % str(self.day).rjust(2, '0')
+        else:  # branch 2, aka "we start without a year" aka "D%d-%m" format
+            c = "D"
+            if (self.day is not None) and (self.month is not None):  # checking both
+                s += c + "%s" % str(self.day).rjust(2, '0')
+                c = "-"
+                s += c + "%s" % str(self.month).rjust(2, '0')
+                return s  # We send a "Ddd-mm" string for 'TDAT'
+        # Here is the 'TIME' part, which starts or continues the string from branch 1
+        c = "T"
+        if self.hour is not None:
+            s += c + "%s" % str(self.hour).rjust(2, '0')
+        c = ":"
+        if self.minute is not None:
+            s += c + "%s" % str(self.minute).rjust(2, '0')
+        return s  # We send either a YYYY-mm-ddTHH:MM, or just a THH:MM (for 'TIME')
+
+
+def parseError(ex) -> None:
+    """A function that is invoked when non-fatal parse, format, etc. errors
+    occur. In most cases the invalid values will be ignored or possibly fixed.
+    This function simply logs the error."""
+    log.warning(ex)
+
+
+def load(path, tag_version=None) -> Optional[AudioFile]:
+    """Loads the file identified by ``path`` and returns a concrete type of
+    :class:`eyed3.core.AudioFile`. If ``path`` is not a file an ``IOError`` is
+    raised. ``None`` is returned when the file type (i.e. mime-type) is not
+    recognized.
+    The following AudioFile types are supported:
+
+      * :class:`eyed3.mp3.Mp3AudioFile` - For mp3 audio files.
+      * :class:`eyed3.id3.TagFile` - For raw ID3 data files.
+
+    If ``tag_version`` is not None (the default) only a specific version of
+    metadata is loaded. This value must be a version constant specific to the
+    eventual format of the metadata.
+    """
+    from . import mimetype, mp3, id3
+
+    if not isinstance(path, pathlib.Path):
+        path = pathlib.Path(path)
+    log.debug(f"Loading file: {path}")
+
+    if path.exists():
+        if not path.is_file():
+            raise IOError(f"not a file: {path}")
+    else:
+        raise IOError(f"file not found: {path}")
+
+    mtype = mimetype.guessMimetype(path)
+    log.debug(f"File mime-type: {mtype}")
+
+    if mtype in mp3.MIME_TYPES:
+        return mp3.Mp3AudioFile(path, tag_version)
+    elif mtype == id3.ID3_MIME_TYPE:
+        return id3.TagFile(path, tag_version)
+    else:
+        return None