This is an active fork of the official "Discogs API client for Python", which was deprecated by discogs.com as of June 2020. We think it is a very useful Python module and decided to continue maintaining it. If you'd like to contribute your code, you are very welcome to submit a pull-request as described here.
python3-discogs-client enables you to query the Discogs database (discogs.com) through its REST-API for information on artists, releases, labels, users, Marketplace listings, and more. It also supports OAuth 1.0a authorization, which allows you to change user data such as profile information, collections and wantlists, inventory, and orders.
Find usage information on this README page or search and ask in the API section of the Discogs developer forum at https://www.discogs.com/forum/topic/1082.
Install the client from PyPI using your favorite package manager.
$ pip install python3-discogs-client
>>> import discogs_client
>>> d = discogs_client.Client('ExampleApplication/0.1')
There are a couple of different authorization methods you can choose from depending on your requirements.
This method will allow your application to make requests on behalf of any user who logs in.
For this, specify your app's consumer key and secret:
>>> d.set_consumer_key('key-here', 'secret-here')
>>> # Or you can do this when you instantiate the Client
Then go through the OAuth 1.0a process. In a web app, we'd specify a callback_url
. In this example, we'll use the OOB flow.
>>> d.get_authorize_url()
('request-token', 'request-secret', 'authorize-url-here')
The client will hang on to the access token and secret, but in a web app, you'd want to persist those and pass them into a new Client
instance on the next request.
Next, visit the authorize URL, authenticate as a Discogs user, and get the verifier:
>>> d.get_access_token('verifier-here')
('access-token-here', 'access-secret-here')
Now you can make requests on behalf of the user.
>>> me = d.identity()
>>> "I'm {0} ({1}) from {2}.".format(me.name, me.username, me.location)
u"I'm Joe Bloggs (example) from Portland, Oregon."
>>> len(me.wantlist)
3
>>> me.wantlist.add(d.release(5))
>>> len(me.wantlist)
4
This is one of the simplest ways to authenticate and become able to perform requests requiring authentication, such as search (see below). The downside is that you'll be limited to the information only your user account can see (i.e., no requests on behalf of other users).
For this, you'll need to generate a user-token from your developer settings on the Discogs website.
>>> d = discogs_client.Client('ExampleApplication/0.1', user_token="my_user_token")
Use methods on the client to fetch objects. You can search for objects:
>>> results = d.search('Stockholm By Night', type='release')
>>> results.pages
1
>>> artist = results[0].artists[0]
>>> artist.name
u'Persuader, The'
Or fetch them by ID:
>>> artist.id
1
>>> artist == d.artist(1)
True
You can drill down as far as you like.
>>> releases = d.search('Bit Shifter', type='artist')[0].releases[1].\
... versions[0].labels[0].releases
>>> len(releases)
134
Query for an artist using the artist's name:
>>> artist = d.artist(956139)
>>> print artist
<Artist "...">
>>> 'name' in artist.data.keys()
True
Get a list of Artist
s representing this artist's aliases:
>>> artist.aliases
[...]
Get a list of Release
s by this artist by page number:
>>> artist.releases.page(1)
[...]
Query for a release using its Discogs ID:
>>> release = d.release(221824)
Get the title of this Release
:
>>> release.title
'...'
Get a list of all Artist
s associated with this Release
:
>>> release.artists
[<Artist "...">]
Get the tracklist for this Release
:
>>> release.tracklist
[...]
Get the MasterRelease
for this Release
:
>>> release.master
<MasterRelease "...">
Get a list of all Label
s for this Release
:
>>> release.labels
[...]
Query for a master release using its Discogs ID:
>>> master_release = d.master(120735)
Get the key Release
for this MasterRelease
:
>>> master_release.main_release
<Release "...">
Get the title of this MasterRelease
:
>>> master_release.title
'...'
>>> master_release.title == master_release.main_release.title
True
Get a list of Release
s representing other versions of this MasterRelease
by page number:
>>> master_release.versions.page(1)
[...]
Get the tracklist for this MasterRelease
:
>>> master_release.tracklist
[...]
Query for a label using the label's name:
>>> label = d.label(6170)
Get a list of Release
s from this Label
by page number:
>>> label.releases.page(1)
[...]
Get a list of Label
s representing sublabels associated with this Label
:
>>> label.sublabels
[...]
Get the Label
's parent label, if it exists:
>>> label.parent_label
<Label "Warp Records Limited">
Backing off and auto retry when API rate limit is hit is enabled by default and can be disabled as follows:
>>> import discogs_client
>>> d = discogs_client.Client('ExampleApplication/0.1')
>>> d.backoff_enabled = False
As an authenticated user you can add, edit and delete your own Listing
s
from discogs_client import Condition, Status, Sort
# Add new listing
me.inventory.add_listing(
release=15246519, # Also accepts Release object
condition=Condition.MINT, # condition set to 'Mint (M)'
price=29.99,
status=Status.DRAFT, # status set to 'Draft'
sleeve_condition=Condition.NEAR_MINT # sleeve condition set to 'Near Mint (NM or M-)'
)
# Get most expensive listing and update its price
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 listing
# Delete the listing
listing.delete()
- Fork this repo
- Create a feature branch
- Open a pull-request
Check the included documentation, or just spin up a REPL and use dir()
on things :)