This is the continuation of the official "Discogs API client for Python", which was deprecated by discogs.com as of June 2020. We, the Joalla Team, think it is a very useful Python module and are continuing maintenance.
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 our documentation pages, ask for help, suggest features and help others in the discussion section of our github repo. If you'd like to contribute your code, you are welcome to submit a pull-request as described here.
There also is the long running thread "Continuation of the Python Discogs API Client" on the Discogs developer forum we use to announce releases and other news.
Install the client from PyPI using your favorite package manager.
$ pip3 install python3-discogs-client
Instantiating the client object
>>> import discogs_client >>> d = discogs_client.Client('ExampleApplication/0.1')
For more information, have a look at the quickstart section in our documentation pages.
There are two different authorization methods you can choose from depending on your requirements: User-token and OAuth authentication.
Note that Authorization is an optional feature of the Discogs API but a lot of basic functionality, like searching for releases, artists, etc. requires users being authenticated already.
This is the quickest way to authenticate and become able to perform requests requiring authentication, such as search (see below).
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")
Head to the authentication section in our docs to learn about the OAuth authentication method.
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.artists >>> 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').releases.\ ... versions.labels.releases >>> len(releases) 134
Have a look at the searching and fetching data sections in our documentation pages.
Get listings/releases from a user's inventory (this does not require authentication)
>>> user = d.user('username') >>> inventory = user.inventory >>> inventory.count 1671 >>> inventory.pages 34 >>> inventory.per_page = 100 >>> inventory.pages 17 >>> first_page = inventory.page(0) >>> first_page # get the first listing on the page <Listing 2314412455 'Bing Crosby - Der Bingle (10")'> >>> first_listing.release <Release 2604203 'Der Bingle'>
As an authenticated user you can add, edit and delete your own marketplace listings.
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-)' )
To learn how to update your inventory and delete listings, have a look at the marketplace listing section in our docs.
For more information
- Read through python3-discogs-client.readthedocs.org for step by step instructions.
- Check the discogs_client Python package documentation to find out details on specific modules, classes, methods, and more.
- Or just spin up a REPL and use
dir()on things :)
- If you have questions or feature requests, please ask in the discussion section.
- Fork this repo
- Create a feature branch
- Open a pull-request
Some more helpful information on this topic can be found in the contribution section in our docs.