1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
|
# 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](https://python3-discogs-client.readthedocs.io/en/latest/contributing.html#submitting).
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.
[](
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
Get listings/releases from a user's inventory (this does not require authentication)
```python
>>> 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.
```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, 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](https://github.com/joalla/discogs_client/discussions).
## 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/contributing.html).
|
