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'>

Get the title of the Release:

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 CollectionItemInstances of release 22155985. The attributes of the CollectionItemInstances 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}