README.rst
1=================
2soundcloud-python
3=================
4
5.. image:: https://travis-ci.org/soundcloud/soundcloud-python.svg
6 :target: https://travis-ci.org/soundcloud/soundcloud-python
7
8A friendly wrapper around the `Soundcloud API`_.
9
10.. _Soundcloud API: http://developers.soundcloud.com/
11
12Installation
13------------
14
15To install soundcloud-python, simply: ::
16
17 pip install soundcloud
18
19Or if you're not hip to the pip: ::
20
21 easy_install soundcloud
22
23Basic Use
24---------
25
26To use soundcloud-python, you must first create a `Client` instance,
27passing at a minimum the client id you obtained when you `registered
28your app`_: ::
29
30 import soundcloud
31
32 client = soundcloud.Client(client_id=YOUR_CLIENT_ID)
33
34The client instance can then be used to fetch or modify resources: ::
35
36 tracks = client.get('/tracks', limit=10)
37 for track in tracks:
38 print track.title
39 app = client.get('/apps/124')
40 print app.permalink_url
41
42.. _registered your app: http://soundcloud.com/you/apps/
43
44Authentication
45--------------
46
47All `OAuth2 authorization flows`_ supported by the Soundcloud API are
48available in soundcloud-python. If you only need read-only access to
49public resources, simply provide a client id when creating a `Client`
50instance: ::
51
52 import soundcloud
53
54 client = soundcloud.Client(client_id=YOUR_CLIENT_ID)
55 track = client.get('/tracks/30709985')
56 print track.title
57
58If however, you need to access private resources or modify a resource,
59you will need to have a user delegate access to your application. To do
60this, you can use one of the following OAuth2 authorization flows.
61
62**Authorization Code Flow**
63
64The `Authorization Code Flow`_ involves redirecting the user to soundcloud.com
65where they will log in and grant access to your application: ::
66
67 import soundcloud
68
69 client = soundcloud.Client(
70 client_id=YOUR_CLIENT_ID,
71 client_secret=YOUR_CLIENT_SECRET,
72 redirect_uri='http://yourapp.com/callback'
73 )
74 redirect(client.authorize_url())
75
76Note that `redirect_uri` must match the value you provided when you
77registered your application. After granting access, the user will be
78redirected to this uri, at which point your application can exchange
79the returned code for an access token: ::
80
81 access_token, expires, scope, refresh_token = client.exchange_token(
82 code=request.args.get('code'))
83 render_text("Hi There, %s" % client.get('/me').username)
84
85
86**User Credentials Flow**
87
88The `User Credentials Flow`_ allows you to exchange a username and
89password for an access token. Be cautious about using this flow, it's
90not very kind to ask your users for their password, but may be
91necessary in some use cases: ::
92
93 import soundcloud
94
95 client = soundcloud.Client(
96 client_id=YOUR_CLIENT_ID,
97 client_secret=YOUR_CLIENT_SECRET,
98 username='jane@example.com',
99 password='janespassword'
100 )
101 print client.get('/me').username
102
103.. _`OAuth2 authorization flows`: http://developers.soundcloud.com/docs/api/authentication
104.. _`Authorization Code Flow`: http://developers.soundcloud.com/docs/api/authentication#user-agent-flow
105.. _`User Credentials Flow`: http://developers.soundcloud.com/docs/api/authentication#user-credentials-flow
106
107Examples
108--------
109
110Resolve a track and print its id: ::
111
112 import soundcloud
113
114 client = soundcloud.Client(client_id=YOUR_CLIENT_ID)
115
116 track = client.get('/resolve', url='http://soundcloud.com/forss/flickermood')
117
118 print track.id
119
120Upload a track: ::
121
122 import soundcloud
123
124 client = soundcloud.Client(access_token="a valid access token")
125
126 track = client.post('/tracks', track={
127 'title': 'This is a sample track',
128 'sharing': 'private',
129 'asset_data': open('mytrack.mp4', 'rb')
130 })
131
132 print track.title
133
134Start following a user: ::
135
136 import soundcloud
137
138 client = soundcloud.Client(access_token="a valid access token")
139 user_id_to_follow = 123
140 client.put('/me/followings/%d' % user_id_to_follow)
141
142Update your profile description: ::
143
144 import soundcloud
145
146 client = soundcloud.Client(access_token="a valid access token")
147 client.put('/me', user={
148 'description': "a new description"
149 })
150
151Proxy Support
152-------------
153
154If you're behind a proxy, you can specify it when creating a client: ::
155
156 import soundcloud
157
158 proxies = {
159 'http': 'example.com:8000'
160 }
161 client = soundcloud.Client(access_token="a valid access token",
162 proxies=proxies)
163
164The proxies kwarg is a dictionary with protocols as keys and host:port as values.
165
166Redirects
167---------
168
169By default, 301 or 302 redirects will be followed for idempotent methods. There are certain cases where you may want to disable this, for example: ::
170
171 import soundcloud
172
173 client = soundcloud.Client(access_token="a valid access token")
174 track = client.get('/tracks/293/stream', allow_redirects=False)
175 print track.location
176
177Will print a tracks streaming URL. If ``allow_redirects`` was omitted, a binary stream would be returned instead.
178
179Running Tests
180-------------
181
182To run the tests, run: ::
183
184 $ pip install -r requirements.txt
185 $ nosetests --with-doctest
186 ..................
187
188Success!
189
190Contributing
191------------
192
193Contributions are awesome. You are most welcome to `submit issues`_,
194or `fork the repository`_.
195
196soundcloud-python is published under a `BSD License`_.
197
198.. _`submit issues`: https://github.com/soundcloud/soundcloud-python/issues
199.. _`fork the repository`: https://github.com/soundcloud/soundcloud-python
200.. _`BSD License`: https://github.com/soundcloud/soundcloud-python/blob/master/README
201