iTunesLibrary 1.2.2__py3-none-any.whl

ituneslibrary/__init__.py

@@ -0,0 +1,15 @@
+# vi: set syntax=python ts=4 sw=4 sts=4 et ff=unix ai si :
+
+"""
+
+(c) Steve Scholnick <scholnicks@gmail.com>
+MIT License
+
+    https://github.com/scholnicks/itunes-library
+"""
+
+name = "itunes-library"
+__author__ = "Steven Scholnick <scholnicks@gmail.com>"
+__version__ = "1.2.1"
+__copyright__ = "Copyright (c) 2013- Steven Scholnick"
+__license__ = "MIT"

ituneslibrary/library.py

@@ -0,0 +1,184 @@
+# vi: set syntax=python ts=4 sw=4 sts=4 et ff=unix ai si :
+
+"""
+Library - Represents a complete iTunes Library
+
+(c) Steve Scholnick <scholnicks@gmail.com>
+MIT License
+
+    https://github.com/scholnicks/itunes-library
+"""
+
+from abc import ABCMeta
+
+
+def parse(pathToXMLFile, ignoreRemoteSongs=True):
+    """Main method for constructor a Library object"""
+    from . import parser
+
+    return parser.Parser().parse(pathToXMLFile, ignoreRemoteSongs)
+
+
+class Library(object):
+    """Represents a complete iTunes Library"""
+
+    def __init__(self, ignoreRemoteSongs):
+        """Constructor"""
+        super(Library, self).__init__()
+        self.playlists = []
+        self.items = []
+        self.ignoreRemoteSongs = ignoreRemoteSongs
+
+    def addPlaylist(self, playlist):
+        """Adds a playlist"""
+        self.playlists.append(playlist)
+
+    def addItem(self, item):
+        """Adds an item"""
+        if self.ignoreRemoteSongs and item.remote:
+            return
+
+        self.items.append(item)
+
+    def getItemsById(self, trackId):
+        """Returns an item based on its Track Id or None"""
+        trackId = str(trackId)  # all keys are strings, allow for integers to be passed in
+        return next((i for i in self.items if i.getItunesAttribute("Track ID") == trackId), None)
+
+    def getPlaylist(self, name):
+        """Returns a Playlist based on its name or None"""
+        playlist = self.getAllPlaylists(name)
+        return playlist[0] if playlist else None
+
+    def getAllPlaylists(self, name):
+        """Returns all playlists that match the name or an empty list"""
+        return [p for p in self.playlists if p.title == name]
+
+    def getItemsForArtist(self, name):
+        """Returns all items for an artist as a List"""
+        return [i for i in self.items if i.artist == name]
+
+    def __iter__(self):
+        """Allows for quick iteration through the items"""
+        return iter(self.items)
+
+    def __len__(self):
+        """returns the number of items stored in the library"""
+        return len(self.items)
+
+
+class ItunesItem(object):
+    """Abstract Base Class for iTunes items stored in the library"""
+
+    __metaclass__ = ABCMeta
+
+    def __init__(self):
+        """Constructor"""
+        self.itunesAttributes = dict()
+
+    def setItunesAttribute(self, key, value):
+        """Sets an iTunes attribute"""
+        self.itunesAttributes[key] = value
+
+    def getItunesAttribute(self, key):
+        """Returns an iTunes attribute"""
+        return self.itunesAttributes.get(key, None)
+
+    def keys(self):
+        """Returns all of the possible iTunes attribute keys"""
+        return self.itunesAttributes.keys()
+
+    @property
+    def title(self):
+        """Returns the title"""
+        return self.getItunesAttribute("Name")
+
+    @property
+    def remote(self):
+        """returns if the song is remote"""
+        return self.getItunesAttribute("Track Type") == "Remote"
+
+
+class PlayList(ItunesItem):
+    """an iTunes Playlist"""
+
+    def __init__(self):
+        """Constructor"""
+        super(PlayList, self).__init__()
+        self.items = []
+
+    def addItem(self, item):
+        """Adds an item"""
+        self.items.append(item)
+
+    def is_master(self):
+        """returns whether this playlist is the "master" playlist (i.e. the root "Library" playlist)"""
+        return self.itunesAttributes.get("Master", False)
+
+    def is_folder(self):
+        """returns whether this playlist is actually a folder of playlists"""
+        return self.itunesAttributes.get("Folder", False)
+
+    def is_distinguished(self):
+        """returns whether this playlist is a "distinguished" playlist
+        (e.g. "Purchases", "Podcasts", etc.)"""
+        disinguished_kind = self.itunesAttributes.get("Distinguished Kind", None)
+        return disinguished_kind is not None
+
+    def is_smart(self):
+        """returns whether this playlist is a "smart" (i.e. automatic) playlist"""
+        if self.is_folder():
+            return False
+
+        smart_attributes = self.itunesAttributes.get("Smart Criteria", None)
+        return smart_attributes is not None
+
+    def is_regular(self):
+        """returns whether this playlist is a "regular" playlist
+        (i.e. neither a folder, nor a smart playlist, nor a special one, etc.)"""
+        return not (self.is_master() or self.is_folder() or self.is_smart() or self.is_distinguished())
+
+    def __str__(self):
+        """Returns a nice string representation"""
+        return "{}: {}".format(self.title.encode("utf-8"), len(self.items))
+
+    def __repr__(self):
+        """Returns a possible internal representation of this object"""
+        return str(self.__dict__)
+
+    def __iter__(self):
+        """Allows for quick iteration through the items"""
+        return iter(self.items)
+
+    def __len__(self):
+        """returns the number of items stored in this playlist"""
+        return len(self.items)
+
+
+class Item(ItunesItem):
+    """an item stored in the iTunes Playlist"""
+
+    def __init__(self):
+        """Constructor"""
+        super(Item, self).__init__()
+
+    @property
+    def artist(self):
+        """Returns the title"""
+        return self.getItunesAttribute("Artist")
+
+    @property
+    def album(self):
+        """Returns the album name"""
+        return self.getItunesAttribute("Album")
+
+    def __repr__(self):
+        """Returns a possible internal representation of this object"""
+        return str(self.__dict__)
+
+    def __str__(self):
+        """Returns a nice string representation"""
+        artist = self.artist if self.artist else ""
+        album = self.album if self.album else ""
+        title = self.title if self.title else ""
+        return "{} {} {}".format(artist, album, title)

ituneslibrary/parser.py

@@ -0,0 +1,144 @@
+# vi: set syntax=python ts=4 sw=4 sts=4 et ff=unix ai si :
+
+"""
+Parser - Parses the iTunes XML file
+
+(c) Steve Scholnick <scholnicks@gmail.com>
+MIT License
+
+See http://search.cpan.org/~dinomite/Mac-iTunes-Library-1.0/lib/Mac/iTunes/Library/XML.pm for Notes on the ridiculous format for the
+iTunes Library XML file
+
+Thanks to https://github.com/dinomite for deciphering the iTunes Library XML format
+
+    https://github.com/scholnicks/itunes-library
+"""
+
+import xml.sax
+from . import library
+
+DICT_TYPE = "dict"
+ARRAY_TYPE = "array"
+STRING_TYPE = "string"
+INTEGER_TYPE = "integer"
+ITEM_ATTRIBUTES = (INTEGER_TYPE, STRING_TYPE, "date", "data")
+
+
+class Parser(xml.sax.ContentHandler):
+    """Parses the iTunes XML file"""
+
+    def __init__(self):
+        """Constructor"""
+        xml.sax.ContentHandler.__init__(self)
+        self.stack = []
+        self.inPlayLists = False
+        self.inTracks = False
+        self.inMusicFolder = False
+        self.inMajorVersion = False
+        self.inMinorVersion = False
+        self.inApplicationVersion = False
+        self.curKey = ""
+        self.bufferString = ""
+        self.item = None
+        self.lib = None
+
+    def parse(self, pathToXMLFile, ignoreRemoteSongs):
+        """parses the XML file passed in"""
+        self.lib = library.Library(ignoreRemoteSongs)
+        xml.sax.parse(open(pathToXMLFile, "r", encoding="utf8"), self)
+        return self.lib
+
+    def startElement(self, name, attrs):
+        """callback method for SAX parsing"""
+        self.stack.append(name)
+
+        if len(self.stack) == 1:
+            self.lib.version = attrs.getValue("version")
+        elif len(self.stack) == 4:
+            if name == DICT_TYPE:
+                if self.inPlayLists:
+                    self.item = library.PlayList()
+                else:
+                    self.item = library.Item()
+
+    def endElement(self, name):
+        """callback method for SAX parsing"""
+        depth = len(self.stack)
+        self.stack.pop()
+
+        if depth == 3:
+            if name == DICT_TYPE:
+                self.inTracks = False
+            elif name == ARRAY_TYPE:
+                self.inPlayLists = False
+
+            if self.inMusicFolder and name == STRING_TYPE:
+                self.lib.musicFolder = self.bufferString
+                self.inMusicFolder = False
+                self.curKey = ""
+                self.bufferString = ""
+        elif depth == 4:
+            if self.item:
+                if self.inPlayLists:
+                    self.lib.addPlaylist(self.item)
+                else:
+                    self.lib.addItem(self.item)
+
+            if name == DICT_TYPE:
+                self.item = None
+        elif depth == 5:
+            if name in ITEM_ATTRIBUTES:
+                self.item.setItunesAttribute(self.curKey, self.bufferString)
+                self.curKey = ""
+                self.bufferString = ""
+            elif name == "true":
+                self.item.setItunesAttribute(self.curKey, True)
+                self.curKey = ""
+            elif name == "false":
+                self.item.setItunesAttribute(self.curKey, False)
+                self.curKey = ""
+        elif depth == 7:
+            if name == INTEGER_TYPE:
+                track = self.lib.getItemsById(self.bufferString)
+                if track:
+                    self.item.addItem(track)
+
+                self.curKey = ""
+                self.bufferString = ""
+
+    def characters(self, content):
+        """callback method for SAX parsing"""
+        if len(self.stack) == 3:
+            if self.stack[-1] == "key":
+                if content == "Application Version":
+                    self.inApplicationVersion = True
+                elif content == "Major Version":
+                    self.inMajorVersion = True
+                elif content == "Minor Version":
+                    self.inMinorVersion = True
+                elif content == "Tracks":
+                    self.inTracks = True
+                elif content == "Playlists":
+                    self.inPlayLists = True
+            elif self.stack[-1] in ("integer", "string", "true", "false"):
+                if self.inApplicationVersion:
+                    self.lib.applicationVersion = content
+                    self.inApplicationVersion = False
+                elif self.inMajorVersion:
+                    self.lib.majorVersion = content
+                    self.inMajorVersion = False
+                elif self.inMinorVersion:
+                    self.lib.minorVersion = content
+                    self.inMinorVersion = False
+                elif self.inMusicFolder:
+                    self.bufferString += content if content else ""
+        elif len(self.stack) == 5:
+            if self.stack[-1] == "key":
+                self.curKey += content if content else ""
+            elif self.stack[-1] in ITEM_ATTRIBUTES:
+                self.bufferString += content if content else ""
+        elif len(self.stack) == 7:
+            if self.stack[-1] == "key":
+                self.curKey += content
+            elif self.stack[-1] in ("integer", "string", "date"):
+                self.bufferString += content if content else ""

ituneslibrary-1.2.2.dist-info/METADATA

@@ -0,0 +1,71 @@
+Metadata-Version: 2.4
+Name: iTunesLibrary
+Version: 1.2.2
+Summary: itunesLibrary represents an iTunes Library.
+License-Expression: MIT
+License-File: LICENSE
+Keywords: iTunes,Apple,Music,Library,XML
+Author: Steve Scholnick
+Author-email: scholnicks@gmail.com
+Requires-Python: >=3.13
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.13
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Topic :: Utilities
+Requires-Dist: docopt-ng (>=0.9.0,<0.10.0)
+Project-URL: Homepage, https://pypi.org/project/iTunesLibrary/
+Project-URL: Repository, https://github.com/scholnicks/itunes-library/
+Description-Content-Type: text/markdown
+
+# itunesLibrary
+==============
+
+itunesLibrary represents an iTunes Library. It allows the caller to retrieve items, playlists, etc.
+
+itunesLibrary is a port of Drew Stephen's excellent Perl module, https://github.com/dinomite/Mac-iTunes-Library. The Perl
+library will be **not** re-created verbatim.
+
+Installation :
+```bash
+pip install itunesLibrary
+```
+
+## Example Code
+
+```python
+import os
+from itunesLibrary import library
+
+path = os.path.join(os.getenv("HOME"),"Music/iTunes/iTunes Music Library.xml")
+
+# must first parse...
+lib = library.parse(path)
+
+print(len(lib))    # number of items stored
+
+for playlist in lib.playlists:
+    for item in playlist.items:
+        print(item)          # perform function on each item in the playlist
+
+# get a single playlist
+playlist = lib.getPlaylist("Gray")
+
+# check the playlist type
+assert(not playlist.is_smart())
+assert(not playlist.is_folder())
+
+# get a list of all of the David Bowie songs
+bowie_items = lib.getItemsForArtist("David Bowie")
+
+# get a single song
+single_song = lib.getItemsById("16116")
+
+# get the iTunes application version
+print(lib.applicationVersion)
+```
+
+## Contributors
+* scholnicks@gmail.com
+* software@froissart.eu
+

ituneslibrary-1.2.2.dist-info/RECORD

@@ -0,0 +1,7 @@
+ituneslibrary/__init__.py,sha256=NhxwsZP22MI5Y1tBnhPDqisUePgP6p9jFDf8mWfxbgI,351
+ituneslibrary/library.py,sha256=VHg0kAM4BrjL5sb9cJmMuT8v3exO1YP24QMU4FRWMq0,5692
+ituneslibrary/parser.py,sha256=A2HSIhtDmb3wMI4IjkjqzvNrgMIBb7Jd42zOyfcjsZg,5154
+ituneslibrary-1.2.2.dist-info/METADATA,sha256=tlANokjkqYy8a5WWtf9O-6NOyFqQMkgo19AHConQt8s,1919
+ituneslibrary-1.2.2.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
+ituneslibrary-1.2.2.dist-info/licenses/LICENSE,sha256=wT_mfbxynx42y5DZ0-Kuf_pie3PaQPeK5nXUL8_V1WQ,1073
+ituneslibrary-1.2.2.dist-info/RECORD,,

ituneslibrary-1.2.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 2.2.1
+Root-Is-Purelib: true
+Tag: py3-none-any

ituneslibrary-1.2.2.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021- Steve Scholnick
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.