python3-discogs-client

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.

Installation

Install the client from PyPI using your favorite package manager.

$ pip3 install python3-discogs-client

Quickstart

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.

Authorization

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.

User-token authentication

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.

Fetching data

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

Have a look at the searching and fetching data sections in our documentation pages.

Marketplace listing

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[0]  # 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.

Contributing

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.

joalla/discogs_client