Skip to content

HTTPS clone URL

Subversion checkout URL

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