flickr 1.0.2 → 2.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4ac455cf4ac4d354d2eb5c169b563c92150c167364bb43b11ce74f631f3a9ff6
+  data.tar.gz: 42b38c39f413a14db0422fee1a921eccbb771112abbbda6b5e1178988651f10e
+SHA512:
+  metadata.gz: bef5a2e5c09c225a12623dd99018df767ca8b6a77f9fb46b88841293fcbef729be2a381530e117144ad2d613edd4829f7eae9bc204a8409922b72f622e28ea13
+  data.tar.gz: 982840a709e68ef01876bbe75f0132681cf80b54fd8510ff9fbd3461b70961f6bc31c53196dfce610817f27d0aed6ff1d837fe5ce6f49e5ecddbe62ced79d110

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2006 Mael Clerambault <maelclerambault@yahoo.fr>
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,185 @@
+= Flickr
+
+Flickr is a library to access the Flickr[https://flickr.com] API in a simple way.
+It maps exactly the methods described in {the official API documentation}[https://www.flickr.com/services/api/].
+It also tries to present the data returned in a simple and intuitive way.
+The methods are fetched from Flickr when loading the library by using introspection capabilities. So it is always up-to-date with regards to new methods added by Flickr.
+
+The github repository: https://github.com/hanklords/flickraw
+
+= Installation
+Type this in a console (you might need to be superuser)
+
+ gem install flickr
+
+This will recreate the documentation by fetching the method descriptions from Flickr and then virtually plugging them in standard rdoc documentation.
+ $ cd flickr
+ $ rake rdoc
+
+= Features
+
+* Minimal dependencies
+* Complete support of Flickr API. This doesn't require an update of the library
+* Ruby syntax similar to the Flickr API
+* Flickr authentication
+* HTTPS Support
+* Photo upload
+* Proxy support
+* Flickr URLs helpers
+
+= Usage
+
+== Getting started
+
+To use the Flickr API, you must first obtain an API key and shared secret from Flickr. You can do this by logging in to Flickr and creating an application here[https://www.flickr.com/services/apps/create/apply]. API keys are usually granted automatically and instantly.
+
+  require 'flickr'
+
+  # The credentials can be provided as parameters:
+
+  flickr = Flickr.new "YOUR API KEY", "YOUR SHARED SECRET"
+
+  # Alternatively, if the API key and Shared Secret are not provided, Flickr will attempt to read them
+  # from environment variables:
+  # ENV['FLICKR_API_KEY']
+  # ENV['FLICKR_SHARED_SECRET']
+
+  flickr = Flickr.new
+
+  # Flickr will raise an error if either parameter is not explicitly provided, or available via environment variables.
+
+
+== Simple
+
+  list   = flickr.photos.getRecent
+
+  id     = list[0].id
+  secret = list[0].secret
+  info   = flickr.photos.getInfo :photo_id => id, :secret => secret
+
+  puts info.title           # => "PICT986"
+  puts info.dates.taken     # => "2006-07-06 15:16:18"
+
+
+  sizes = flickr.photos.getSizes :photo_id => id
+
+  original = sizes.find { |s| s.label == 'Original' }
+  puts original.width       # => "800" -- may fail if they have no original marked image
+
+== Authentication
+
+  token = flickr.get_request_token
+  auth_url = flickr.get_authorize_url(token['oauth_token'], :perms => 'delete')
+
+  puts "Open this url in your browser to complete the authentication process: #{auth_url}"
+  puts "Copy here the number given when you complete the process."
+  verify = gets.strip
+
+  begin
+    flickr.get_access_token(token['oauth_token'], token['oauth_token_secret'], verify)
+    login = flickr.test.login
+    puts "You are now authenticated as #{login.username} with token #{flickr.access_token} and secret #{flickr.access_secret}"
+  rescue Flickr::FailedResponse => e
+    puts "Authentication failed : #{e.msg}"
+  end
+
+If the user has already been authenticated, you can reuse the access token and access secret:
+
+  flickr.access_token = "... Your access token ..."
+  flickr.access_secret = "... Your access secret ..."
+
+  # From here you are logged:
+  login = flickr.test.login
+  puts "You are now authenticated as #{login.username}"
+
+If you need to have several users authenticated at the same time in your application (ex: a public web application) you need to create separate Flickr objects since it keeps the authentication data internally.
+
+  flickr = Flickr.new
+
+== Upload
+
+  PHOTO_PATH = 'photo.jpg'
+
+  # You need to be authenticated to do that, see the previous examples.
+  flickr.upload_photo PHOTO_PATH, :title => "Title", :description => "This is the description"
+
+== Caching
+
+The first time the Flickr object is instantiated, it will download the current Flickr API definition and dynamically create all the required classes and objects. This is how the gem remains up-to-date without requiring updates.
+
+Unfortunately this adds a significant delay to startup, but the Flickr gem can be configured to cache the API definition to a local file. Just set a file location before the Flickr class is instantiated:
+
+  Flickr.cache = '/tmp/flickr-api.yml'
+  flickr = Flickr.new
+
+== Proxy
+
+  require 'flickr'
+  Flickr.proxy = "https://user:pass@proxy.example.com:3129/"
+
+=== Server Certificate Verification
+
+Server certificate verification is enabled by default. If you don't want to check the server certificate:
+
+  require 'flickr'
+  Flickr.check_certificate = false
+
+=== CA Certificate File Path
+
+OpenSSL::X509::DEFAULT_CERT_FILE is used as a CA certificate file. If you want to change the path:
+
+  require 'flickr'
+  Flickr.ca_file = '/path/to/cacert.pem'
+
+You can also specify a path to a directory with a number of certifications:
+
+  Flickr.ca_path = '/path/to/certificates'
+
+== Flickr URL Helpers
+
+There are some helpers to build Flickr urls:
+
+=== url, url_m, url_s, url_t, url_b, url_z, url_q, url_n, url_c, url_o
+
+  # url_s : Square
+  # url_q : Large Square
+  # url_t : Thumbnail
+  # url_m : Small
+  # url_n : Small 320
+  # url   : Medium
+  # url_z : Medium 640
+  # url_c : Medium 800
+  # url_b : Large
+  # url_o : Original
+
+  info = flickr.photos.getInfo(:photo_id => "3839885270")
+  Flickr.url_b(info) # => "https://farm3.static.flickr.com/2485/3839885270_6fb8b54e06_b.jpg"
+
+=== url_profile
+
+  info = flickr.photos.getInfo(:photo_id => "3839885270")
+  Flickr.url_profile(info) # => "https://www.flickr.com/people/41650587@N02/"
+
+=== url_photopage
+
+  info = flickr.photos.getInfo(:photo_id => "3839885270")
+  Flickr.url_photopage(info) # => "https://www.flickr.com/photos/41650587@N02/3839885270"
+
+=== url_photoset, url_photosets
+
+  info = flickr.photos.getInfo(:photo_id => "3839885270")
+  Flickr.url_photosets(info) # => "https://www.flickr.com/photos/41650587@N02/sets/"
+
+=== url_short, url_short_m, url_short_s, url_short_t
+
+  info = flickr.photos.getInfo(:photo_id => "3839885270")
+  Flickr.url_short(info) # => "https://flic.kr/p/6Rjq7s"
+
+=== url_photostream
+
+  info = flickr.photos.getInfo(:photo_id => "3839885270")
+  Flickr.url_photostream(info) # => "https://www.flickr.com/photos/41650587@N02/"
+
+== Examples
+
+See the _examples_ directory to find more examples.

data/examples/auth.rb

@@ -0,0 +1,22 @@
+require 'flickr'
+
+# This is how to authenticate on flickr website.
+# You need an API key for that, see https://www.flickr.com/services/api/keys/
+API_KEY = ''
+SHARED_SECRET = ''
+
+flickr = Flickr.new API_KEY, SHARED_SECRET
+token = flickr.get_request_token
+auth_url = flickr.get_authorize_url(token['oauth_token'], :perms => 'delete')
+
+puts "Open this url in your browser to complete the authentication process: #{auth_url}"
+puts "Copy here the number given when you complete the process."
+verify = gets.strip
+
+begin
+  flickr.get_access_token(token['oauth_token'], token['oauth_token_secret'], verify)
+  login = flickr.test.login
+  puts "You are now authenticated as #{login.username} with token #{flickr.access_token} and secret #{flickr.access_secret}"
+rescue Flickr::FailedResponse => e
+  puts "Authentication failed: #{e.msg}"
+end

data/examples/interestingness.rb

@@ -0,0 +1,7 @@
+require 'flickr'
+
+# Get the list of the 20 most recent 'interesting photos'
+
+flickr = Flickr.new
+list = flickr.interestingness.getList :per_page => 20
+list.each { |photo| puts "'#{photo.title}' id=#{photo.id} secret=#{photo.secret}" }

data/examples/search.rb

@@ -0,0 +1,20 @@
+require 'flickr'
+
+# search for pictures taken within 60 miles of new brunswick, between 1890-1920
+
+flickr = Flickr.new
+new_b = flickr.places.find :query => "new brunswick"
+latitude = new_b[0]['latitude'].to_f
+longitude = new_b[0]['longitude'].to_f
+
+# within 60 miles of new brunswick, let's use a bbox
+radius = 1
+args = {}
+args[:bbox] = "#{longitude - radius},#{latitude - radius},#{longitude + radius},#{latitude + radius}"
+
+# requires a limiting factor, so let's give it one
+args[:min_taken_date] = '1890-01-01 00:00:00'
+args[:max_taken_date] = '1920-01-01 00:00:00'
+args[:accuracy] = 1 # the default is street only granularity [16], which most images aren't...
+discovered_pictures = flickr.photos.search args
+discovered_pictures.each { |p| url = Flickr.url p; puts url }

data/examples/sinatra.rb

@@ -0,0 +1,31 @@
+require 'flickr'
+require 'sinatra'
+
+API_KEY = ''
+SHARED_SECRET = ''
+use Rack::Session::Pool
+
+get '/authenticate' do
+  flickr = Flickr.new API_KEY, SHARED_SECRET
+  token = flickr.get_request_token(:oauth_callback => to('check'))
+  session[:token] = token
+  redirect flickr.get_authorize_url(token['oauth_token'], :perms => 'delete')
+end
+
+get '/check' do
+  token = session.delete :token
+  session[:auth_flickr] = @auth_flickr = Flickr.new
+  @auth_flickr.get_access_token(token['oauth_token'], token['oauth_token_secret'], params['oauth_verifier'])
+
+  redirect to('/authenticated')
+end
+
+get '/authenticated' do
+  @auth_flickr = session[:auth_flickr]
+
+  login = @auth_flickr.test.login
+  %{
+You are now authenticated as <em>#{login.username}</em>
+with token <strong>#{@auth_flickr.access_token}</strong> and secret <strong>#{@auth_flickr.access_secret}</strong>.
+  }
+end

data/examples/upload.rb

@@ -0,0 +1,16 @@
+require 'flickr'
+
+# This is how to upload photos on flickr.
+# You need to be authenticated to do that.
+
+API_KEY       = ''
+SHARED_SECRET = ''
+ACCESS_TOKEN  = ''
+ACCESS_SECRET = ''
+PHOTO_PATH    = 'photo.jpg'
+
+flickr = Flickr.new API_KEY, SHARED_SECRET
+flickr.access_token = ACCESS_TOKEN
+flickr.access_secret = ACCESS_SECRET
+
+flickr.upload_photo PHOTO_PATH, :title => 'Title', :description => 'This is the description'

data/examples/web_oauth.rb

@@ -0,0 +1,47 @@
+require 'flickr'
+
+# A short howto for web flow authentication on the flickr website.
+# This would live inside a rails controller or alternative framework equivalent
+# Error handling left out for clarity :-)
+# Added by Darren Greaves (https://github.com/boncey/)
+#
+# You need an API key first, see https://www.flickr.com/services/api/keys/
+API_KEY = ''
+SHARED_SECRET = ''
+
+# This is the URL Flickr will redirect your users to once they agree to access
+@callback_url = 'http://localhost:3000/auth_controller/callback'
+
+# Users should hit this method to get the link which sends them to flickr
+def auth
+  flickr = Flickr.new API_KEY, SHARED_SECRET
+  token = flickr.get_request_token(:oauth_callback => URI.escape(@callback_url))
+  # You'll need to store the token somewhere for when the user is returned to the callback method
+  # I stick mine in memcache with their session key as the cache key
+
+  @auth_url = flickr.get_authorize_url(token['oauth_token'], :perms => 'delete')
+  # Stick @auth_url in your template for users to click
+end
+
+# Your users browser will be redirected here from Flickr (see @callback_url above)
+def callback
+  flickr = Flickr.new
+
+  request_token = # Retrieve from cache or session etc - see above
+  oauth_token = params[:oauth_token]
+  oauth_verifier = params[:oauth_verifier]
+
+  raw_token = flickr.get_access_token(request_token['oauth_token'], request_token['oauth_token_secret'], oauth_verifier)
+  # raw_token is a hash like this {"user_nsid"=>"92023420%40N00", "oauth_token_secret"=>"XXXXXX", "username"=>"boncey", "fullname"=>"Darren%20Greaves", "oauth_token"=>"XXXXXX"}
+  # Use URI.unescape on the nsid and name parameters
+
+  oauth_token = raw_token["oauth_token"]
+  oauth_token_secret = raw_token["oauth_token_secret"]
+
+  # Store the oauth_token and oauth_token_secret in session or database
+  #   and attach to a Flickr instance before calling any methods requiring authentication
+
+  # Attach the tokens to your flickr instance - you can now make authenticated calls with the flickr object
+  flickr.access_token = oauth_token
+  flickr.access_secret = oauth_token_secret
+end

data/flickr_rdoc.rb

@@ -0,0 +1,128 @@
+require "rdoc"
+require "rdoc/parser/ruby"
+require "nokogiri"
+
+FLICKR_API_URL = 'https://www.flickr.com/services/api'
+
+FakedToken = Struct.new :text, :kind
+
+module RDoc
+  class FlickrParser < Parser::Ruby
+    parse_files_matching(/flickr\.rb$/)
+
+    def scan
+      super
+
+      fr = @top_level.find_module_named 'Flickr'
+      k = fr.add_class NormalClass, 'Flickr', 'Flickr::Request'
+      k.record_location @top_level
+      @stats.add_class 'Flickr'
+
+      add_flickr_methods(Flickr, k)
+      @top_level
+    end
+
+    private
+
+    def add_flickr_methods(obj, doc)
+      flickr = Flickr.new
+      obj.constants.each { |const_name|
+        const = obj.const_get const_name
+        if const.is_a?(Class) && const < Flickr::Request
+          name = const.name.sub(/.*::/, '')
+          k = doc.add_class NormalClass, name, 'Flickr::Request'
+          k.record_location @top_level
+          @stats.add_class name
+
+          m = AnyMethod.new nil, name.downcase
+          m.comment = "Returns a #{name} object."
+          m.params = ''
+          m.singleton = false
+          doc.add_method m
+          @stats.add_method m
+
+          add_flickr_methods(const, k)
+        end
+      }
+
+      obj.flickr_methods.each { |name|
+        flickr_method = obj.request_name + '.' + name
+        info = flickr.reflection.getMethodInfo :method_name => flickr_method
+
+        m = AnyMethod.new nil, name
+        m.comment = flickr_method_comment(info)
+        m.params = flickr_method_args(info)
+        m.singleton = false
+
+        m.start_collecting_tokens
+        m.add_token FakedToken.new( %{
+# Generated automatically from flickr api
+  def #{name}(*args)
+    @flickr.call '#{flickr_method}', *args
+  end
+} )
+        doc.add_method m
+         @stats.add_method m
+      }
+    end
+
+    def flickr_method_comment(info)
+      description = Nokogiri::HTML(info.method.description.to_s).text
+
+      if info.respond_to? :arguments
+        args = info.arguments.select { |arg| arg.name != 'api_key' }
+
+        arguments = "<b>Arguments</b>\n"
+        if args.size > 0
+          args.each { |arg|
+            arguments << "[#{arg.name} "
+            arguments << "<em>(required)</em> " if arg.optional == '0'
+            arguments << "] "
+            arguments << "#{Nokogiri::HTML(arg.to_s).text}\n"
+          }
+        end
+      end
+
+      if info.respond_to? :errors
+        errors = "<b>Error codes</b>\n"
+        info.errors.each { |e|
+          errors << "* #{e.code}: <em>#{e.message}</em>\n\n"
+          errors << "  #{Nokogiri::HTML(e.to_s).text}\n"
+        }
+      end
+
+      if info.method.respond_to? :response
+        response = "<b>Returns</b>\n"
+        raw = Nokogiri::HTML(info.method.response.to_s).text
+        response << raw.lines.collect { |line| line.insert(0, ' ') }.join
+      else
+        response = ''
+      end
+
+      str = "{#{info.method.name}}[#{FLICKR_API_URL}/#{info.method.name}.html] request.\n\n"
+      str << description << "\n\n"
+      str << arguments << "\n\n"
+      str << errors << "\n\n"
+      str << response << "\n\n"
+    end
+
+    def flickr_method_args(info)
+      str = ''
+      if info.respond_to? :arguments
+        args = info.arguments.select { |arg| arg.name != 'api_key' }
+
+        if args.size > 0
+          str << '('
+          args.each { |arg|
+            str << ":#{arg.name} => '#{arg.name}'"
+            str << ','
+          }
+          str.chomp! ','
+          str << ')'
+        end
+      end
+      str
+    end
+
+  end
+end