Managing Release and Collection data
Note that the examples in this chapter are shown using example Python code with print
statements to show the results and require an existing Client object.
Using the Python REPL is another way to test and review data and information available using the Discogs API.
Most data about releases can be queried without having to authenticate using your Client object. Other data including search, querying the records in your collection, or fetching album art requires authentication. See the Authentication section for more information.
Release Data
Almost all data available on a Release page on the Discogs website is available using the python3-discogs-client
library. If you were to run dir()
on the release
object, you would see the following list of all objects available to query, where 20017387 is the release ID. Some common examples are shown below.
# Authenticate using your Client object
d = discogs_client.Client(config.agent, user_token=config.my_token)
print(dir(d.release(20017387)))
['__class__', '__delattr__', '__dict__', '__dir__', '__doc__', '__eq__', '__format__', '__ge__', '__getattribute__', '__gt__', '__hash__', '__init__', '__init_subclass__', '__le__', '__lt__', '__module__', '__ne__', '__new__', '__reduce__', '__reduce_ex__', '__repr__', '__setattr__', '__sizeof__', '__str__', '__subclasshook__', '__weakref__', '_known_invalid_keys', 'artists', 'changes', 'client', 'companies', 'country', 'credits', 'data', 'data_quality', 'delete', 'fetch', 'formats', 'genres', 'id', 'images', 'labels', 'marketplace_stats', 'master', 'notes', 'refresh', 'save', 'status', 'styles', 'thumb', 'title', 'tracklist', 'url', 'videos', 'year']
Artists
print(d.release(20017387).artists[0].name, type(d.release(1443762).artists))
returns a list of Artists associated with the release:
Chvrches <class 'list'>
This returns a list as some releases have multiple artists:
[<Artist 2672269 'Poliça'>, <Artist 4771951 'Stargaze (4)'>] Music For The Long Emergency
Data returns a dictionary including the URL to the page for the given release:
print(d.release(20017387).data)
{'id': 20017387, 'resource_url': 'https://api.discogs.com/releases/20017387'}
Formats
Formats returns a list of dictionaries that includes the kind of release, such as CD, Vinyl, and any other special properties of the release:
print(d.release(20017387).formats)
[{'name': 'Vinyl', 'qty': '1', 'text': 'Red Transparent', 'descriptions': ['LP', 'Album']}]
Genres
Genres returns a list of genres associated with the release:
print(d.release(20017387).genres)
['Electronic', 'Pop']
Images
Images returns a list of all images and its URL associated with the release. You must be authenticated to get the image URL. The first image is is the primary image found on the Release page:
print(d.release(20017387).images[0])
{'type': 'primary', 'uri': 'https://img.discogs.com/XbUkIoS6p-yb9U36xSKethiXs0U=/fit-in/600x600/filters:strip_icc():format(jpeg):mode_rgb():quality(90)/discogs-images/R-20017387-1631064590-2485.jpeg.jpg', 'resource_url': 'https://img.discogs.com/XbUkIoS6p-yb9U36xSKethiXs0U=/fit-in/600x600/filters:strip_icc():format(jpeg):mode_rgb():quality(90)/discogs-images/R-20017387-1631064590-2485.jpeg.jpg', 'uri150': 'https://img.discogs.com/tbjnf4pVYhNvxNRDqZWrXtkKZcc=/fit-in/150x150/filters:strip_icc():format(jpeg):mode_rgb():quality(40)/discogs-images/R-20017387-1631064590-2485.jpeg.jpg', 'width': 600, 'height': 600}
Tracklist
Tracklist returns a list of tracks and track position on the album associated with the release:
print(d.release(20017387).tracklist)
[<Track 'A1' 'Asking For A Friend'>, <Track 'A2' 'He Said She Said'>, <Track 'A3' 'California'>, <Track 'A4' 'Violent Delights'>, <Track 'A5' 'How Not To Drown '>, <Track 'B1' 'Final Girl'>, <Track 'B2' 'Good Girls'>, <Track 'B3' 'Lullabies'>, <Track 'B4' 'Nightmares'>, <Track 'B5' "Better If You Don't">]
print(d.release(20017387).tracklist[0].title)
Asking For A Friend
Community Details
release = d.release(15343679)
community_details = release.community
print(community_details)
print(community_details.rating)
print(community_details.want)
print(community_details.have)
print(community_details.contributors)
<CommunityDetails want/have: 34/74>
<Rating avg: 4.5>
34
74
[<User 1053297 'ManikRecs'>, <User 1241908 'neurosis76'>, <User 8867757 'silyn1'>, <User 3410038 'evasstra'>]
Additional attributes are also available. Learn more about them in the reference docs of the CommunityDetails
class.
Collection Data
To access the collection an authenticated Client object is required.
Assuming the Client
object is called d
:
me=d.identity()
print(me)
will return:
<User 123456 'discogs_username'>
Loop through all the items in the collection:
for item in me.collection_folders[0].releases:
print(item)
<CollectionItemInstance 731053 'DJ-Kicks'>
<CollectionItemInstance 2230329 'Drumlesson Zwei'>
<CollectionItemInstance 6794957 'The K&D Sessions™'>
...
...
The items in the collection always are CollectionItemInstance
objects.
Collection Items by Folder
Folder 0 is a special folder containing all the release in the user’s collection
Folder 1 is the “Uncategorized” folder.
Folders 2 to n are any other collection folders manually created by the user.
To loop through the “Uncategorized” folder:
for item in me.collection_folders[1].releases:
print(item)
Find out more about the available attributes of a CollectionItemInstance
:
print(dir(me.collection_folders[1].releases[123]:
['__class__', '__delattr__', '__dict__', '__dir__', '__doc__', '__eq__', '__format__', '__ge__', '__getattribute__', '__gt__', '__hash__', '__init__', '__init_subclass__', '__le__', '__lt__', '__module__', '__ne__', '__new__', '__reduce__', '__reduce_ex__', '__repr__', '__setattr__', '__sizeof__', '__str__', '__subclasshook__', '__weakref__', '_known_invalid_keys', 'changes', 'client', 'data', 'date_added', 'delete', 'fetch', 'folder_id', 'id', 'notes', 'rating', 'refresh', 'release', 'save']
Get a full Release
object of a collection item:
print(me.collection_folders[1].releases[123].release)
<Release 1692728 'Phylyps Trak II'>
print(me.collection_folders[1].releases[123].release.title)
Phylyps Trak II
Collection Items by Release
As seen in the Collection Items by Folder chapter, collection items can be accessed by iterating through a specific folder or the whole collection.
An alternative approach is using the collection_items()
method which can be faster than iterating through the collection. After passing this method a release_id
or Release
object, it will return a list of CollectionItemInstance
objects.
As it is possible that you have (or physically own) multiple copies of the same release inside one or more collection folders, using this method will return all copies of the release no matter which folder it is located in.
The example code below will print all CollectionItemInstance
s of release 22155985. The attributes of the CollectionItemInstance
s will show additional information, such as the folder it is located in or the details of the Release
.
release_instances = me.collection_items(22155985)
for instance in release_instances:
print(instance)
print(instance.folder_id)
print(instance.release)
Adding a Release to a Collection Folder
me.collection_folders[2].add_release(17392219)
add_release()
also accepts Release
objects
Removing a Release from a Collection Folder
Removing a single release instance identified by its index:
folder = me.collection_folders[2]
releases = folder.releases
# Delete the first instance in releases
folder.remove_release(releases[0])
To filter out which instance to remove we could also use the attributes of the Release
object attached to the CollectionItemInstance
:
folder = me.collection_folders[2]
for instance in folder.releases:
if instance.release.title == "Internet Protocol":
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 collection_items()
method. This way we could delete all the instances from all its containing folders:
release_instances = me.collection_items(22155985)
for instance in release_instances:
folder = me.collection_folders[instance.folder_id]
folder.remove_release(instance)
remove_release()
only accepts CollectionItemInstance
objects
Using fetch()
to get other data
You can use the fetch()
method to get any data from an object, including data that may not be accessible via the objects properties.
An authenticated Client object is required. To understand the Discogs API, see the Discogs API documentation or use the community Postman collection to test the API.
Examples of using the fetch()
method:
release = d.release(1026691)
print(release.id)
print(release.fetch('id'))
print(release.fetch('community')['rating'])
1026691
1026691
{'count': 274, 'average': 4.38}