fix: simplify names of playlist (folder) creation methods

pyrekordbox/xml.py

@@ -559,12 +559,45 @@ def _update_count(self):
     def _update_entries(self):
         self._element.attrib["Entries"] = str(len(self._element))
 
-    def add_folder_node(self, name):
+    def add_playlist_folder(self, name):
+        """Add a new playlist folder as child to this node.
+
+        Parameters
+        ----------
+        name : str
+            The name of the new playlist folder.
+
+        Returns
+        -------
+        folder_node : Node
+            The newly created playlist folder node.
+        """
+        if self.is_playlist:
+            raise ValueError("Sub-elements can only be added to a folder node!")
+
         node = Node.folder(self._element, name)
         self._update_count()
         return node
 
-    def add_playlist_node(self, name, keytype="TrackID"):
+    def add_playlist(self, name, keytype="TrackID"):
+        """Add a new playlist as child to this node.
+
+        Parameters
+        ----------
+        name : str
+            The name of the new playlist.
+        keytype : {'TrackID', 'Location'} str
+            The type of key the playlist uses to store the tracks. Can either be
+            'TrackID' or 'Location'.
+
+        Returns
+        -------
+        playlist_node : Node
+            The newly created playlist node.
+        """
+        if self.is_playlist:
+            raise ValueError("Sub-elements can only be added to a folder node!")
+
         node = Node.playlist(self._element, name, keytype)
         self._update_count()
         return node
@@ -726,7 +759,19 @@ def get_track(self, index=None, TrackID=None):
         Returns
         -------
         track : Track
-            The track object.
+            The XML track element.
+
+        Examples
+        --------
+        Get track by index
+
+        >>> file = RekordboxXml("database.xml")
+        >>> track = file.get_track(0)
+
+        or by ``TrackID``
+
+        >>> track = file.get_track(TrackID=1)
+
         """
         if index is None and TrackID is None:
             raise ValueError("Either index or TrackID has to be specified!")
@@ -749,6 +794,25 @@ def get_track_ids(self):
         return [int(el.attrib["TrackID"]) for el in elements]
 
     def get_playlist(self, *names):
+        """Returns a playlist or playlist folder with the given path.
+
+        Parameters
+        ----------
+        *names : str
+            Names in the path. If no names are given the root playlist folder is
+            returned.
+
+        Returns
+        -------
+        node : Node
+            The playlist or playlist folder node.
+
+        Examples
+        --------
+        >>> file = RekordboxXml("database.xml")
+        >>> playlist = file.get_playlist("Folder", "Sub Playlist")
+
+        """
         node = self._root_node
         if not names:
             return node
@@ -757,10 +821,31 @@ def get_playlist(self, *names):
         return node
 
     def _update_track_count(self):
+        """Updates the track count element."""
         num_tracks = len(self._collection.findall(f".//{Track.TAG}"))
         self._collection.attrib["Entries"] = str(num_tracks)
 
     def add_track(self, location, **kwargs):
+        """Add a new track element to the Rekordbox XML collection.
+
+        Parameters
+        ----------
+        location : str
+            The file path of the track.
+        kwargs :
+            Keyword arguments which are used to fill the track attributes. If no
+            argument for ``TrackID`` is given the ID is auto-incremented.
+
+        Returns
+        -------
+        track : Track
+            The newly created XML track element.
+
+        Examples
+        --------
+        >>> file = RekordboxXml("database.xml")
+        >>> _ = file.add_track("path/to/track.wav")
+        """
         if "TrackID" not in kwargs:
             kwargs["TrackID"] = self._last_id + 1
         track = Track(self._collection, location, **kwargs)
@@ -769,13 +854,62 @@ def add_track(self, location, **kwargs):
         return track
 
     def remove_track(self, track):
+        """Remove a track element from the Rekordbox XML collection.
+
+        Parameters
+        ----------
+        track : Track
+            The XML track element to remove.
+
+        Examples
+        --------
+        >>> file = RekordboxXml("database.xml")
+        >>> t = file.get_track(0)
+        >>> file.remove_track(t)
+
+        """
         self._collection.remove(track._element)  # noqa
         self._update_track_count()
 
     def add_playlist_folder(self, name):
+        """Add a new top-level playlist folder to the XML collection.
+
+        Parameters
+        ----------
+        name : str
+            The name of the new playlist folder.
+
+        Returns
+        -------
+        folder_node : Node
+            The newly created playlist folder node.
+
+        See Also
+        --------
+        Node.add_playlist_folder
+        """
         return self._root_node.add_folder_node(name)
 
-    def add_playlist_node(self, name, keytype="TrackID"):
+    def add_playlist(self, name, keytype="TrackID"):
+        """Add a new top-level playlist to the XML collection.
+
+        Parameters
+        ----------
+        name : str
+            The name of the new playlist.
+        keytype : {'TrackID', 'Location'} str
+            The type of key the playlist uses to store the tracks. Can either be
+            'TrackID' or 'Location'.
+
+        Returns
+        -------
+        playlist_node : Node
+            The newly created playlist node.
+
+        See Also
+        --------
+        Node.add_playlist
+        """
         return self._root_node.add_folder_node(name, keytype)
 
     def tostring(self, indent=None):