dropbox-api 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
data/.gitignore ADDED
@@ -0,0 +1,7 @@
1
+ *.gem
2
+ .bundle
3
+ Gemfile.lock
4
+ pkg/*
5
+ spec/connection.yml
6
+ bin
7
+ coverage
data/.rspec ADDED
@@ -0,0 +1 @@
1
+ --color
data/Gemfile ADDED
@@ -0,0 +1,9 @@
1
+ source "http://rubygems.org"
2
+
3
+ # Specify your gem's dependencies in dropbox-api.gemspec
4
+ gemspec
5
+
6
+ gem "rspec"
7
+ gem "rake"
8
+ gem 'simplecov'
9
+ gem "ruby-debug19"
data/LICENSE ADDED
@@ -0,0 +1,22 @@
1
+ Copyright (c) 2011 Marcin Bunsch, Future Simple Inc.
2
+
3
+ Permission is hereby granted, free of charge, to any person
4
+ obtaining a copy of this software and associated documentation
5
+ files (the "Software"), to deal in the Software without
6
+ restriction, including without limitation the rights to use,
7
+ copy, modify, merge, publish, distribute, sublicense, and/or sell
8
+ copies of the Software, and to permit persons to whom the
9
+ Software is furnished to do so, subject to the following
10
+ conditions:
11
+
12
+ The above copyright notice and this permission notice shall be
13
+ included in all copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
16
+ EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
17
+ OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
18
+ NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
19
+ HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
20
+ WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
21
+ FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
22
+ OTHER DEALINGS IN THE SOFTWARE.
data/README.markdown ADDED
@@ -0,0 +1,289 @@
1
+ Dropbox::API - Dropbox Ruby API client
2
+ =========
3
+
4
+ A Ruby client for the DropBox REST API.
5
+
6
+ Goal:
7
+
8
+ To deliver a more Rubyesque experience when using the DropBox API.
9
+
10
+ Current state:
11
+
12
+ First release, whole API covered.
13
+
14
+ Configuration
15
+ -------------
16
+
17
+ In order to use this client, you need to have an app created on https://www.dropbox.com/developers/apps.
18
+
19
+ Once you have it, put this configuration somewhere in your code, before you start working with the client.
20
+
21
+ ```ruby
22
+ Dropbox::API::Config.app_key = YOUR_APP_TOKEN
23
+ Dropbox::API::Config.app_secret = YOUR_APP_SECRET
24
+ Dropbox::API::Config.mode = "sandbox" # if you have a single-directory app or "dropbox" if it has access to the whole dropbox
25
+ ```
26
+
27
+ Dropbox::API::Client
28
+ --------------------
29
+
30
+ The client is the base for all communication with the API and wraps around almost all calls
31
+ available in the API.
32
+
33
+ In order to create a Dropbox::API::Client object, you need to have the configuration set up for OAuth.
34
+ Second thing you need is to have the user authorize your app using OAuth. Here's a short intro
35
+ on how to do this:
36
+
37
+ ```ruby
38
+ consumer = Dropbox::API::OAuth.consumer(:authorize)
39
+ request_token = consumer.get_request_token
40
+ request_token.authorize_url(:oauth_callback => 'http://yoursite.com/callback')
41
+ # Here the user goes to Dropbox, authorizes the app and is redirected
42
+ # The oauth_token will be available in the params
43
+ request_token.get_access_token(:oauth_verifier => oauth_token)
44
+ ```
45
+
46
+ Now that you have the oauth token and secret, you can create a new instance of the Dropbox::API::Client, like this:
47
+
48
+ ```ruby
49
+ client = Dropbox::API::Client.new :token => token, :secret => secret
50
+ ```
51
+
52
+ Rake-based authorization
53
+ ------------------------
54
+
55
+ Dropbox::API supplies you with a helper rake which will authorize a single client. This is useful for development and testing.
56
+
57
+ In order to have this rake available, put this on your Rakefile:
58
+
59
+ ```ruby
60
+ require "dropbox-api/tasks"
61
+ Dropbox::API::Tasks.install
62
+ ```
63
+
64
+ You will notice that you have a new rake task - dropbox:authorize
65
+
66
+ When you call this Rake task, it will ask you to provide the consumer key and secret. Afterwards it will present you with an authorize url on Dropbox.
67
+
68
+ Simply go to that url, authorize the app, then press enter in the console.
69
+
70
+ The rake task will output valid ruby code which you can use to create a client.
71
+
72
+ What differs this from the DropBox Ruby SDK?
73
+ --------------------------------------------
74
+
75
+ A few things:
76
+
77
+ * It's using the ruby oauth gem, instead of reinventing the wheel and implementing OAuth communication
78
+ * It treats files and directories as Ruby objects with appropriate classes, on which you can perform operations
79
+
80
+ Consider the following example which takes all files with names like 'test.txt' and copies them with a suffix '.old'
81
+
82
+ This is how it would look using the SDK:
83
+
84
+ ```ruby
85
+ # Because you need the session with the right access token, you need to create one instance per user
86
+ @session = DropboxSession.new(APP_TOKEN, APP_SECRET)
87
+ @session.set_access_token(ACCESS_TOKEN, ACCESS_SECRET)
88
+ @client = DropboxClient.new(@session, :app_folder)
89
+ # The result is a hash, so we need to call a method on the client, supplying the right key from the hash
90
+ @client.search('/', 'test.txt').each do |hash|
91
+ @client.file_copy(hash['path'], hash['path'] + ".old")
92
+ end
93
+ ```
94
+
95
+ With Dropbox::API, you can clean it up, first you put the app token and secret in a config or initializer file:
96
+
97
+ ```ruby
98
+ Dropbox::API::Config.app_key = APP_TOKEN
99
+ Dropbox::API::Config.app_secret = APP_SECRET
100
+ ```
101
+
102
+ And when you want to use it, just create a new client object with a specific access token and secret:
103
+
104
+ ```ruby
105
+ # The app token and secret are read from config, that's all you need to have a client ready for one user
106
+ @client = Dropbox::API::Client.new(:token => ACCESS_TOKEN, :secret => ACCESS_SECRET)
107
+ # The file is a Dropbox::API::File object, so you can call methods on it!
108
+ @client.search('test.txt').each do |file|
109
+ file.copy(file.path + ".old2")
110
+ end
111
+ ```
112
+
113
+ What differs this from the dropbox gem?
114
+ --------------------------------------
115
+
116
+ Dropbox::API does not extend the Ruby primitives, like the dropbox gem:
117
+
118
+ https://github.com/RISCfuture/dropbox/tree/master/lib/dropbox/extensions
119
+
120
+ Dropbox::API::Client methods
121
+ ----------------------------
122
+
123
+ ### Dropbox::API::Client#account
124
+
125
+ Returns a simple object with information about the account:
126
+
127
+ ```ruby
128
+ client.account # => #<Dropbox::API::Object>
129
+ ```
130
+
131
+ For more info, see [https://www.dropbox.com/developers/reference/api#account-info](https://www.dropbox.com/developers/reference/api#account-info)
132
+
133
+ ### Dropbox::API::Client#find
134
+
135
+ When provided a path, returns a single file or directory
136
+
137
+ ```ruby
138
+ client.find 'file.txt' # => #<Dropbox::API::File>
139
+ ```
140
+
141
+ ### Dropbox::API::Client#ls
142
+
143
+ When provided a path, returns a list of files or directories within that path
144
+
145
+ By default it's the root path:
146
+
147
+ ```ruby
148
+ client.ls # => [#<Dropbox::API::File>, #<Dropbox::API::Dir>]
149
+ ```
150
+
151
+ But you can provide your own path:
152
+
153
+ ```ruby
154
+ client.ls 'somedir' # => [#<Dropbox::API::File>, #<Dropbox::API::Dir>]
155
+ ```
156
+
157
+ ### Dropbox::API::Client#mkdir
158
+
159
+ Creates a new directory and returns a Dropbox::API::Dir object
160
+
161
+ ```ruby
162
+ client.mkdir 'new_dir' # => #<Dropbox::API::Dir>
163
+ ```
164
+
165
+ ### Dropbox::API::Client#upload
166
+
167
+ Stores a file with a provided body under a provided name and returns a Dropbox::API::File object
168
+
169
+ ```ruby
170
+ client.upload 'file.txt', 'file body' # => #<Dropbox::API::File>
171
+ ```
172
+
173
+ ### Dropbox::API::Client#download
174
+
175
+ Downloads a file with a provided name and returns it's content
176
+
177
+ ```ruby
178
+ client.download 'file.txt' # => 'file body'
179
+ ```
180
+
181
+ ### Dropbox::API::Client#search
182
+
183
+ When provided a pattern, returns a list of files or directories within that path
184
+
185
+ Be default is searches the root path:
186
+
187
+ ```ruby
188
+ client.search 'pattern' # => [#<Dropbox::API::File>, #<Dropbox::API::Dir>]
189
+ ```
190
+
191
+ However, you can specify your own path:
192
+
193
+ ```ruby
194
+ client.search 'pattern', :path => 'somedir' # => [#<Dropbox::API::File>, #<Dropbox::API::Dir>]
195
+ ```
196
+
197
+ Dropbox::API::File and Dropbox::API::Dir methods
198
+ ----------------------------
199
+
200
+ These methods are shared by Dropbox::API::File and Dropbox::API::Dir
201
+
202
+ ### Dropbox::API::File#copy | Dropbox::API::Dir#copy
203
+
204
+ Copies a file/directory to a new specified filename
205
+
206
+ ```ruby
207
+ file.copy 'newfilename.txt' # => #<Dropbox::API::File>
208
+ ```
209
+
210
+ ### Dropbox::API::File#move | Dropbox::API::Dir#move
211
+
212
+ Moves a file/directory to a new specified filename
213
+
214
+ ```ruby
215
+ file.move 'newfilename.txt' # => #<Dropbox::API::File>
216
+ ```
217
+
218
+ ### Dropbox::API::File#delete | Dropbox::API::Dir#delete
219
+
220
+ Deletes a file/directory
221
+
222
+ ```ruby
223
+ file.delete 'newfilename.txt' # => #<Dropbox::API::File>
224
+ ```
225
+
226
+
227
+ Dropbox::API::File methods
228
+ ----------------------------
229
+
230
+ ### Dropbox::API::File#revisions
231
+
232
+ Returns an Array of Dropbox::API::File objects with appropriate rev attribute
233
+
234
+ For more info, see [https://www.dropbox.com/developers/reference/api#revisions](https://www.dropbox.com/developers/reference/api#revisions)
235
+
236
+ ### Dropbox::API::File#restore
237
+
238
+ Restores a file to a specific revision
239
+
240
+ For more info, see [https://www.dropbox.com/developers/reference/api#restore](https://www.dropbox.com/developers/reference/api#restore)
241
+
242
+ ### Dropbox::API::File#share_url
243
+
244
+ Returns the link to a file page in Dropbox
245
+
246
+ For more info, see [https://www.dropbox.com/developers/reference/api#shares](https://www.dropbox.com/developers/reference/api#shares)
247
+
248
+ ### Dropbox::API::File#direct_url
249
+
250
+ Returns the link to a file in Dropbox
251
+
252
+ For more info, see [https://www.dropbox.com/developers/reference/api#media](https://www.dropbox.com/developers/reference/api#media)
253
+
254
+ ### Dropbox::API::File#thumbnail
255
+
256
+ Returns the thumbnail for an image
257
+
258
+ For more info, see [https://www.dropbox.com/developers/reference/api#thumbnail](https://www.dropbox.com/developers/reference/api#thumbnail)
259
+
260
+ ### Dropbox::API::File#download
261
+
262
+ Downloads a file and returns it's content
263
+
264
+ ```ruby
265
+ file.download # => 'file body'
266
+ ```
267
+
268
+ Dropbox::API::Dir methods
269
+ ----------------------------
270
+
271
+ ### Dropbox::API::Dir#ls
272
+
273
+ Returns a list of files or directorys within that directory
274
+
275
+ ```ruby
276
+ dir.ls # => [#<Dropbox::API::File>, #<Dropbox::API::Dir>]
277
+ ```
278
+
279
+ Testing
280
+ ---------
281
+
282
+ In order to run tests, you need to have an application created and authorized. Put all tokens in spec/connection.yml and you're good to go.
283
+
284
+ Check out spec/connection.sample.yml for an example.
285
+
286
+ Copyright
287
+ ---------
288
+
289
+ Copyright (c) 2011 Marcin Bunsch, Future Simple Inc. See LICENSE for details.
data/Rakefile ADDED
@@ -0,0 +1,4 @@
1
+ require 'bundler/gem_tasks'
2
+
3
+ require "dropbox-api/tasks"
4
+ Dropbox::API::Tasks.install
@@ -0,0 +1,24 @@
1
+ # -*- encoding: utf-8 -*-
2
+ $:.push File.expand_path("../lib", __FILE__)
3
+ require "dropbox-api/version"
4
+
5
+ Gem::Specification.new do |s|
6
+ s.name = "dropbox-api"
7
+ s.version = Dropbox::API::VERSION
8
+ s.authors = ["Marcin Bunsch"]
9
+ s.email = ["marcin@futuresimple.com"]
10
+ s.homepage = ""
11
+ s.summary = "A Ruby client for the DropBox REST API."
12
+ s.description = "To deliver a more Rubyesque experience when using the DropBox API."
13
+
14
+ s.rubyforge_project = "dropbox-api"
15
+
16
+ s.add_dependency 'yajl-ruby'
17
+ s.add_dependency 'oauth'
18
+ s.add_dependency 'hashie'
19
+
20
+ s.files = `git ls-files`.split("\n")
21
+ s.test_files = `git ls-files -- {test,spec,features}/*`.split("\n")
22
+ s.executables = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
23
+ s.require_paths = ["lib"]
24
+ end
@@ -0,0 +1,21 @@
1
+ require "oauth"
2
+ require "yajl"
3
+ require "hashie"
4
+
5
+ module Dropbox
6
+ module API
7
+
8
+ end
9
+ end
10
+
11
+ require "dropbox-api/version"
12
+ require "dropbox-api/util/config"
13
+ require "dropbox-api/util/oauth"
14
+ require "dropbox-api/util/error"
15
+ require "dropbox-api/util/util"
16
+ require "dropbox-api/objects/object"
17
+ require "dropbox-api/objects/fileops"
18
+ require "dropbox-api/objects/file"
19
+ require "dropbox-api/objects/dir"
20
+ require "dropbox-api/connection"
21
+ require "dropbox-api/client"
@@ -0,0 +1,46 @@
1
+ require "dropbox-api/client/raw"
2
+ require "dropbox-api/client/files"
3
+
4
+ module Dropbox
5
+ module API
6
+
7
+ class Client
8
+
9
+ attr_accessor :raw, :connection
10
+
11
+ def initialize(options = {})
12
+ @connection = Dropbox::API::Connection.new(:token => options.delete(:token),
13
+ :secret => options.delete(:secret))
14
+ @raw = Dropbox::API::Raw.new :connection => @connection
15
+ @options = options
16
+ end
17
+
18
+ include Dropbox::API::Client::Files
19
+
20
+ def find(filename)
21
+ ls(filename).first
22
+ end
23
+
24
+ def ls(path = '')
25
+ Dropbox::API::Dir.init({'path' => path}, self).ls
26
+ end
27
+
28
+ def account
29
+ Dropbox::API::Object.init(self.raw.account, self)
30
+ end
31
+
32
+ def mkdir(path)
33
+ response = raw.create_folder :path => path
34
+ Dropbox::API::Dir.init(response, self)
35
+ end
36
+
37
+ def search(term, options = {})
38
+ options[:path] ||= ''
39
+ results = raw.search({ :query => term }.merge(options))
40
+ Dropbox::API::Object.convert(results, self)
41
+ end
42
+
43
+ end
44
+
45
+ end
46
+ end
@@ -0,0 +1,31 @@
1
+ module Dropbox
2
+ module API
3
+
4
+ class Client
5
+
6
+ module Files
7
+
8
+ def download(path, options = {})
9
+ root = options.delete(:root) || Dropbox::API::Config.mode
10
+ url = ['', "files", root, path].compact.join('/')
11
+ connection.get_raw(:content, url)
12
+ end
13
+
14
+ def upload(path, data, options = {})
15
+ root = options.delete(:root) || Dropbox::API::Config.mode
16
+ query = Dropbox::API::Util.query(options)
17
+ url = ['', "files_put", root, path].compact.join('/')
18
+ response = connection.put(:content, "#{url}?#{query}", data, {
19
+ 'Content-Type' => "application/octet-stream",
20
+ "Content-Length" => data.length.to_s
21
+ })
22
+ Dropbox::API::File.init(response, self)
23
+ end
24
+
25
+ end
26
+
27
+ end
28
+
29
+ end
30
+ end
31
+