repository·master·Indexed 19 days ago
https://github.com/joalla/discogs_clientA Python client for the Discogs REST-API used to query the Discogs database for artists, releases, labels, and users. It supports managing Marketplace inventory and user data (profiles, collections, wantlists, and orders) via OAuth 1.0a or User-token authentication.
The python3-discogs-client is a Python module used to interact with the Discogs REST-API. It allows developers to:
To manage a user's collection, you must use an authenticated Client object. You can access the user's identity via d.identity(), which returns a User object containing collection_folders.
Items in a collection are returned as CollectionItemInstance objects. These objects link a specific instance of a release to a folder and provide metadata like date_added and rating.
To find all copies of a specific release across all folders, use the collection_items(release_id) method. This is often faster than iterating through folders manually.
me = d.identity()
# Iterate through all items in the entire collection (Folder 0)
for item in me.collection_folders[0].releases:
print(item)
# Get all instances of a specific release ID across all folders
release_instances = me.collection_items(22155985)
for instance in release_instances:
print(instance.folder_id)
print(instance.release.title)When you fetch data (e.g., via d.release(id)), the returned objects contain various properties and methods representing the Discogs data model.
If you need to access raw data that has not been explicitly mapped to a property in the client, you can use the .data property, which contains the underlying dictionary from the API response.
To discover available properties on an object, you can use Python's built-in dir() function or inspect the discogs_client.models module.
release = d.release(1293022)
print(release.title)
artists = release.artists
# Accessing unmapped raw data
print(release.data.keys())OAuth is used when building applications that act as a proxy for other users, allowing them to manage their profile, collection, wantlist, and marketplace via your app.
To use OAuth, you first need a consumer key and consumer secret, which you obtain from the Discogs developer settings by creating an application.
You can initialize the Client with your consumer credentials. If you already have an OAuth token and secret saved, you can provide them immediately to skip the authorization flow.
import discogs_client
# Initialize with consumer credentials only
d = discogs_client.Client(
'my_user_agent/1.0',
consumer_key='my_consumer_key',
consumer_secret='my_consumer_secret'
)
# OR initialize with existing tokens
d = discogs_client.Client(
'my_user_agent/1.0',
consumer_key='my_consumer_key',
consumer_secret='my_consumer_secret',
token='my_token',
secret='my_token_secret'
)You can access almost all data available on a Discogs Release page using the release method on a Client object. Most release data can be queried without authentication, but certain features like searching, collection querying, or fetching album art require an authenticated client.
Commonly available attributes on a Release object include:
artists: A list of Artist objects.formats: A list of dictionaries containing release types (e.g., Vinyl, CD) and descriptions.genres: A list of genre strings.images: A list of dictionaries containing image URLs (requires authentication for URLs).tracklist: A list of Track objects.community: A CommunityDetails object containing ratings, wants, haves, and contributors.data: A dictionary containing the release ID and its resource_url.# Authenticate using your Client object
d = discogs_client.Client(config.agent, user_token=config.my_token)
# Access a specific release
release = d.release(20017387)
print(release.artists[0].name)
print(release.formats)
print(release.genres)
print(release.tracklist[0].title)
print(release.community.rating)To remove a marketplace listing, retrieve or instantiate a Listing object and call its .delete() method.
listing.delete()To update a listing, retrieve it from an inventory (optionally using .sort() to find a specific item), modify its attributes directly, and then call .save() to persist the changes to the Discogs API.
Sort criteria and order are managed via discogs_client.utils.Sort.
inventory = me.inventory # Get up to date inventory
inventory.sort( # Sort by price in descending order
Sort.By.PRICE, # == 'price'
Sort.Order.DESCENDING) # == 'desc'
listing = inventory[0] # Get the first item, i.e. most expensive
listing.price = 34.99 # Update its price
listing.save() # Save changes made to listingYou can read a user's public inventory without authentication. Access the inventory via the inventory attribute of a user object, then use .page(index) to retrieve paginated results.
user = d.user('username') # gets a user with username
inventory = user.inventory # get that user's inventory
first_page = inventory.page(0) # get the first page
first_listing = first_page[0] # get the first listing from that page
release = first_listing.release # get the release from the releaseThe documentation is built using Sphinx. To generate the HTML version of the documentation:
docs/ directory.make html.docs/build/html/index.html using a web browser.If you encounter issues with stale builds, clean the build directory before rebuilding using make clean; make html.
Recommended Python versions: 3.9 or 3.11.
Note: You may ignore warnings regarding unexpected indentation in docstrings (e.g., WARNING: Unexpected indentation).
cd docs
make html
# Or to clean and rebuild:
make clean; make htmlTo build and edit the documentation locally, you must install Sphinx and its required dependencies. From the root of the repository, use pip with the [docs] extra to install the necessary packages in editable mode.
pip install -e '.[docs]'The following methods are used to manipulate a user's collection. Note that these methods require CollectionItemInstance objects as arguments.
folder.add_release(release_id) or pass a Release object.folder.remove_release(instance). This deletes the item from the collection completely.folder.uncategorize_release(instance). This removes the item from a specific folder but keeps it in the user's collection (moving it to the Uncategorized folder).folder.move_release(instance, target_folder_id) to move an item from one folder to another.# Add a release to a specific folder
me.collection_folders[2].add_release(17392219)
# Remove a specific instance from a folder (deletes from collection)
folder = me.collection_folders[2]
folder.remove_release(folder.releases[0])
# Move a release to a different folder
# First, find the target folder ID
target_folder_id = 1
for instance in me.collection_items(22155985):
current_folder = me.collection_folders[instance.folder_id]
current_folder.move_release(instance, target_folder_id)User-token Authentication is a simple method for scripts or applications that only represent a single user (e.g., a personal store-front). You must first generate a token in your Discogs account settings under Settings > Developers > Generate new token.
When using this method, you are limited to information accessible by your specific user account and cannot make requests on behalf of other users.
import discogs_client
d = discogs_client.Client('my_user_agent/1.0', user_token='my_user_token')