File: README.mkd

package info (click to toggle)
python-discogs-client 2.3.5-2
  • links: PTS, VCS
  • area: main
  • in suites: bookworm, sid
  • size: 344 kB
  • sloc: python: 1,160; makefile: 9; sh: 8
file content (230 lines) | stat: -rw-r--r-- 6,062 bytes parent folder | download
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
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
# python3-discogs-client

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](#contributing).

[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 this README page or search and ask in the API section of the Discogs developer forum at https://www.discogs.com/forum/topic/1082.

[![Build Status](https://travis-ci.org/joalla/discogs_client.svg?branch=master)](https://travis-ci.org/joalla/discogs_client)
[![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
$ pip install python3-discogs-client
```

## Quickstart

### Instantiating the client object

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

### Authorization (optional)

There are a couple of different authorization methods you can choose from depending on your requirements.

#### OAuth authentication ####

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:

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

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

```python
>>> d.get_access_token('verifier-here')
('access-token-here', 'access-secret-here')
```

Now you can make requests on behalf of the user.

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

#### User-token authentication ####

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.

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

### 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
```

## Artist

Query for an artist using the artist's name:

    >>> artist = d.artist(956139)
    >>> print artist
    <Artist "...">
    >>> 'name' in artist.data.keys()
    True

### Special properties

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)
    [...]

## Release

Query for a release using its Discogs ID:

    >>> release = d.release(221824)

### Special properties

Get the title of this `Release`:

    >>> release.title
    u'...'

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

## MasterRelease

Query for a master release using its Discogs ID:

    >>> master_release = d.master(120735)

### Special properties

Get the key `Release` for this `MasterRelease`:

    >>> master_release.main_release
    <Release "...">

Get the title of this `MasterRelease`:

    >>> master_release.title
    u'...'
    >>> 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
    [...]

## Label

Query for a label using the label's name:

    >>> label = d.label(6170)

### Special properties

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">


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

### For more information

Check the included documentation, or just spin up a REPL and use `dir()` on things :)