# 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](https://pypi.org/project/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](
https://python3-discogs-client.readthedocs.org),
ask for help, suggest features and help others in the [discussion section of our
github repo](https://github.com/joalla/discogs_client/discussions). If you'd
like to contribute your code, you are welcome to submit a pull-request as
described [here](contribution.md).

There also is the _long running_ thread ["Continuation of the Python Discogs API
Client"](https://www.discogs.com/forum/thread/822690) on the Discogs developer
forum we use to announce releases and other news.

[![Coverage Status](
https://coveralls.io/repos/github/joalla/discogs_client/badge.svg)](
https://coveralls.io/github/joalla/discogs_client)

## Installation

Install [the client from PyPI](https://pypi.org/project/python3-discogs-client/)
using your favorite package manager.

```sh
$ pip3 install python3-discogs-client
```

## Quickstart

### Instantiating the client object

```python
>>> import discogs_client
>>> d = discogs_client.Client('ExampleApplication/0.1')
```

_For more information, have a look at the
[quickstart section](
https://python3-discogs-client.readthedocs.org/en/latest/quickstart.html)
in our documentation pages._


### Authorization

There are two different authorization methods you can choose from depending on
your requirements:
[User-token](
https://python3-discogs-client.readthedocs.org/en/latest/authentication.html#user-token-authorization)
and [OAuth](
https://python3-discogs-client.readthedocs.org/en/latest/authentication.html#oauth-authorization)
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](
https://python3-discogs-client.readthedocs.org/en/latest/authentication.html#user-token-authentication)
on the Discogs website.

```python
>>> d = discogs_client.Client('ExampleApplication/0.1', user_token="my_user_token")
```

_Head to the [authentication
section](https://python3-discogs-client.readthedocs.org/en/latest/authentication.html#oauth-authentication)
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:

```python
>>> 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:

```python
>>> artist.id
1
>>> artist == d.artist(1)
True
```

You can drill down as far as you like.

```python
>>> releases = d.search('Bit Shifter', type='artist')[0].releases[1].\
...     versions[0].labels[0].releases
>>> len(releases)
134
```

_Have a look at the
[searching](
https://python3-discogs-client.readthedocs.org/en/latest/quickstart.html#searching)
and [fetching data](
https://python3-discogs-client.readthedocs.org/en/latest/fetching_data.html)
sections in our documentation pages._


## Marketplace listing

As an authenticated user you can add, edit and delete your own marketplace listings.

```python
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](
https://python3-discogs-client.readthedocs.org/en/latest/listing.html) in our
docs._


## For more information

- Read through [python3-discogs-client.readthedocs.org](https://python3-discogs-client.readthedocs.org) for step by step instructions.
- Check the [discogs_client Python package documentation](https://python3-discogs-client.readthedocs.org/en/latest/discogs_client.html) to find out details on specific modules, classes, methods, ...
- Or just spin up a REPL and use `dir()` on things :)


## Contributing

1. Fork this repo
2. Create a feature branch
3. Open a pull-request

Some more helpful information on this topic can be found in the [contribution section in our docs](https://python3-discogs-client.readthedocs.org/en/latest/contribution.html).