Merge pull request #165 from joalla/foldermove

Move release between folders / Remove from all folders

Author: JOJ0

.github/workflows/discogs_client-build.yml

@@ -11,7 +11,7 @@ jobs:
     runs-on: ubuntu-20.04
     strategy:
       matrix:
-        python-version: ['3.8', '3.9', '3.10', '3.11', '3.12']
+        python-version: ['3.9', '3.10', '3.11', '3.12', '3.13']
     steps:
     - uses: actions/checkout@v4
     - name: Set up Python ${{ matrix.python-version }}

discogs_client/models.py

@@ -745,7 +745,7 @@ class CollectionFolder(PrimaryAPIObject):
     count = SimpleField()  #:
 
     def __init__(self, client, dict_):
-        super(CollectionFolder, self).__init__(client, dict_)
+        super().__init__(client, dict_)
 
     @property
     def releases(self):
@@ -754,14 +754,34 @@ def releases(self):
 
     def add_release(self, release):
         release_id = release.id if isinstance(release, Release) else release
-        add_release_url = self.fetch('resource_url') + '/releases/{}'.format(release_id)
-        self.client._post(add_release_url, None)
+        resource_url = self.fetch('resource_url')
+        self.client._post(f"{resource_url}/releases/{release_id}", None)
 
     def remove_release(self, instance):
+        """Remove a collection item entirely.
+        """
         if not isinstance(instance, CollectionItemInstance):
             raise TypeError('instance must be of type CollectionItemInstance')
-        instance_url = self.fetch('resource_url') + '/releases/{0}/instances/{1}'.format(instance.id, instance.instance_id)
-        self.client._delete(instance_url)
+        resource_url = self.fetch('resource_url')
+        self.client._delete(f"{resource_url}/releases/{instance.id}/instances/{instance.instance_id}")
+
+    def move_release(self, instance, target_folder_id):
+        """Move a collection item to another folder.
+
+        Moving to folder id 1 moves to the "Uncategorized" folder.
+        """
+        if not isinstance(instance, CollectionItemInstance):
+            raise TypeError('instance must be of type CollectionItemInstance')
+        resource_url = self.fetch('resource_url')
+        self.client._post(
+            f"{resource_url}/releases/{instance.id}/instances/{instance.instance_id}",
+            {"folder_id": target_folder_id},
+        )
+
+    def uncategorize_release(self, instance):
+        """Move a collection item to the "Uncategorized" folder.
+        """
+        self.move_release(instance, 1)
 
     def __repr__(self):
         return '<CollectionFolder {0!r} {1!r}>'.format(self.id, self.name)

discogs_client/tests/test_models.py

@@ -1,5 +1,5 @@
 import unittest
-from discogs_client.models import Artist, Release, ListItem, CollectionValue
+from discogs_client.models import Artist, Release, ListItem, CollectionValue, CollectionItemInstance
 from discogs_client.tests import DiscogsClientTestCase
 from discogs_client.exceptions import HTTPError
 
@@ -265,7 +265,6 @@ def test_listing(self):
         self.assertEqual(method, 'GET')
         self.assertEqual(url, '/marketplace/listings/150899904')
 
-
     def test_collection(self):
         """Collection folders can be manipulated"""
         # Fetch the users collection folders from the filesystem
@@ -314,6 +313,41 @@ def test_collection(self):
         self.assertEqual(method, 'POST')
         self.assertEqual(url, '/users/example/collection/folders/1/releases/1')
 
+    def test_collection_move_release(self):
+        """Collection items can be moved to another folder"""
+        # Fetch the users collection folders from the filesystem
+        u = self.d.user("example")
+        self.assertEqual(u.collection_folders[2].id, 2)
+
+        # Mock expected responses for move_release test using "MemoryFetcher"
+        self.m._fetcher.fetcher.responses = {
+            "/users/example/collection/folders": (b'''
+                {"folders": [
+                    {"resource_url": "/users/example/collection/folders/0", "id": 0, "name": "All"},
+                    {"resource_url": "/users/example/collection/folders/1", "id": 1, "name": "Uncategorized folder"},
+                    {"resource_url": "/users/example/collection/folders/2", "id": 2, "name": "Collection folder 2"}
+                ]}
+            ''', 200),
+            # Mock the response of the POST request to the instance resource URL
+            "/users/example/collection/folders/1/releases/123456/instances/123": (b"", 204),
+        }
+
+        # Bind the user to the MemoryFetcher
+        u.client = self.m
+
+        # Mock a collection item instance
+        instance = CollectionItemInstance(
+            client=u.client,
+            dict_={"id": 123456, "instance_id": 123}
+        )
+        # Perform the move
+        u.collection_folders[1].move_release(instance, 2)
+
+        # Verify
+        method, url, _, _ = self.m._fetcher.last_request
+        self.assertEqual(method, "POST")
+        self.assertEqual(url, "/users/example/collection/folders/1/releases/123456/instances/123")
+
     def test_delete_object(self):
         """Can request DELETE on an APIObject"""
         u = self.d.user('example')

docs/source/conf.py

@@ -80,7 +80,8 @@
 # MyST extenstion configuration
 myst_heading_anchors = 7
 myst_enable_extensions = [
-    "substitution"
+    "substitution",
+    "colon_fence",
 ]
 myst_substitutions = {
   "class": "I'm a **substitution**"

docs/source/fetching_data.md

@@ -231,7 +231,7 @@ me.collection_folders[2].add_release(17392219)
 _{meth}`.add_release` also accepts {class}`.Release` objects_
 
 
-### Removing a Release from a Collection Folder
+### Removing a Release from the Collection
 
 Removing a single release instance identified by its index:
 
@@ -242,6 +242,10 @@ releases = folder.releases
 folder.remove_release(releases[0])
 ```
 
+:::{caution}
+The {meth}`.remove_release` method deletes from the collection entirely. To remove an instance from a folder only, use the {meth}`.uncategorize_release` method.
+:::
+
 To filter out which instance to remove we could also use the attributes of the {class}`.Release` object attached to the {class}`.CollectionItemInstance`:
 
 ```python
@@ -251,16 +255,34 @@ for instance in folder.releases:
         folder.remove_release(instance)
 ```
 
-Another approach to removing instances from collection folders if we know a release ID already would be to make use of the {meth}`.collection_items` method. This way we could delete all the instances from all its containing folders:
+### Removing a Release from a Folder
+
+To remove a release from a collection folder, we need to know the release ID already and  make use of the {meth}`.collection_items` method. This way we could remove all the instances from all its containing folders (uncategorize them):
 
 ```python
 release_instances = me.collection_items(22155985)
 for instance in release_instances:
     folder = me.collection_folders[instance.folder_id]
-    folder.remove_release(instance)
+    folder.uncategorize_release(instance)
+```
+
+### Moving a Release to a Different Folder
+
+To move a release from a collection folder to another one, again we need to know the release ID already and make use of the {meth}`.collection_items` method. We also need to know the ID of the target folder we want to move to (use {attr}`.collection_folders`). We move all the instances from all its containing folders to a specified target folder:
+
+```python
+release_instances = me.collection_items(22155985)
+target_folder = 1
+for folder in me.collection_folders:
+    if folder.name == "My Target Folder":
+        target_folder = folder.id
+
+for instance in release_instances:
+    folder = me.collection_folders[instance.folder_id]
+    folder.move_release(instance, target_folder)
 ```
 
-_{meth}`.remove_release` only accepts {class}`.CollectionItemInstance` objects_
+_{meth}`.remove_release`, {meth}`.move_release` and {meth}`.uncategorize_release` only accept {class}`.CollectionItemInstance` objects_
 
 
 ## Using {meth}`~discogs_client.models.PrimaryAPIObject.fetch` to get other data