localwiki_client 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 57676e3cee0822abe0c07ab173531579f1cccb21
-  data.tar.gz: c7b7b0370f9372cca7b2149e0374737a04fca115
+  metadata.gz: bb9cc507732637d939aa2fdea6e73523e17b0765
+  data.tar.gz: c2eaa613db6c5df7cb2dad1940d693fa0a16907b
 SHA512:
-  metadata.gz: 9a420a1750d4d72858603feff2eeb7656e27649526b5138eeffb8d933fc685e5de239515df86f2cbaed82e46c1b760c0d28b18122d1816f27d34f1218fcc0a9c
-  data.tar.gz: 254a56caf270b691b689ea326f8d3000ebe211aedfece5b411646f9609997ccc06c9caefe0b03d1ecbe80c322cdac7a17b1f189c16288c918138fadc4d407bd9
+  metadata.gz: a62093cafaa6429868d66ff1c4a15187f37c9e93b8fec8666bc9d36602884feba589b18a201aca253aee61e57b193e3d72c61b023ac4acd3dfdd7113cb94fc60
+  data.tar.gz: 6368549d3fa07caf1678080786626cbcd14442c1864ed176774ce6ef80665a7b6190f0f15b467b8da57dabbd13db055da09b9d62cea6c82f3d0e083c840dbe9a

data/.gitignore

@@ -1,4 +1,5 @@
 .yardoc
 doc/
 .idea
-Gemfile.lock
+Gemfile.lock
+coverage

data/History.txt

@@ -1,3 +1,8 @@
+=== 0.3.0 / 2013-03-28
+
+* Localwiki::Resource subclasses used to represent resources
+* Better docs
+
 === 0.2.0 / 2013-03-16
 
 * Implemented CRUD methods

data/README.md

@@ -5,7 +5,7 @@ LocalwikiClient
 Synopsis
 --------
 
-A thin client for the Localwiki API
+A helper client for the Localwiki API
 
 http://localwiki.readthedocs.org/en/latest/api.html
 
@@ -23,26 +23,34 @@ Usage
 
     # read access
     wiki = LocalwikiClient.new 'seattlewiki.net'
-    wiki.site_name
+    wiki.site.name
     => SeattleWiki
-    wiki.count('user')
+    wiki.count(:user)
     => 47
+    map = wiki.fetch(:map, 'Luna Park Cafe')
+    => #<Localwiki::Map>
+    map.page
+    => '/api/page/Luna_Park_Cafe'
+    map.single_point?
+    => true
+    [map.lat, map.long]
+    => [47.570641, -122.370919]
 
     # write access
     wiki = LocalwikiClient.new 'seattlewiki.net', 'myusername', 'myapikey'
-    page_json = {name: 'Current Events', content: 'Coming Soon!'}.to_json
-    response = wiki.create('page', page_json)
+    json = {name: 'Current Events', content: 'Coming Soon!'}.to_json
+    response = wiki.create(:page, json)
     response.status
     => 201
 
 Features / Problems
 -------------------
 
-* #create, #read (#fetch), #update, #delete provide basic CRUD functionality
-* #list fetches all (or with a limit) of a specific type of resource
-* #fetch_version retrieves version history for a resource
+* \#create, #read (#fetch), #update, #delete provide basic CRUD functionality
+* \#list fetches all (or with a limit) of a specific type of resource
+* \#fetch_version retrieves version history for a resource
 * a few helper methods exist, more to come
-    * #count, #page_by_name, #unique_authors
+* \#count, #page_by_name, #unique_authors
 
 
 Compatibility

data/Rakefile

@@ -24,6 +24,12 @@ RSpec::Core::RakeTask.new(:integration) do |t|
   t.rspec_opts = ['-f d']
 end
 
+desc "Run code coverage"
+task :coverage do
+  ENV['COVERAGE'] = '1'
+  Rake::Task['spec'].invoke
+end
+
 desc "Flog the code! (*nix only)"
 task :flog do
   system('find lib -name \*.rb | xargs flog')

data/integration/helper.rb

@@ -3,7 +3,7 @@ require 'localwiki_client'
 
 def test_env_vars_set?
   return true if ENV['localwiki_client_user'] && ENV['localwiki_client_apikey']
-  puts "\nTo add or modify tests in the spec folder you need to do two things:"
+  puts "\nTo run all tests in the integration folder you need to do two things:"
   puts "\tContact sethvincent@gmail.com to request a username and apikey on the test server."
   puts "\tSet these two environment variables:\n\t\texport localwiki_client_user=USERNAME\n\t\texport localwiki_client_apikey=APIKEY"
 end

data/integration/live_saltlake_wiki_spec.rb

@@ -5,11 +5,11 @@ describe 'LIVE saltlakewiki.org' do
   subject { Localwiki::Client.new 'saltlakewiki.org' }
 
   context '#time_zone' do
-    it {subject.time_zone.should eq 'America/Chicago' }
+    it {subject.site.time_zone.should eq 'America/Chicago' }
   end
 
   context '#language_code' do
-    it {subject.language_code.should eq 'en-us'}
+    it {subject.site.language_code.should eq 'en-us'}
   end
 
   context '#total_resources("user")' do

data/integration/live_test_wiki_spec.rb

@@ -1,26 +1,26 @@
 require File.expand_path("../helper", __FILE__)
 
-if test_env_vars_set?
+describe 'LIVE testwiki instance' do
 
-  describe 'LIVE testwiki instance' do
+  before(:all) do
+    @wiki = Localwiki::Client.new 'ec2-54-234-151-52.compute-1.amazonaws.com',
+                                  ENV['localwiki_client_user'],
+                                  ENV['localwiki_client_apikey']
+  end
 
-    before(:all) {
-      @wiki = Localwiki::Client.new 'ec2-54-234-151-52.compute-1.amazonaws.com',
-                                    ENV['localwiki_client_user'],
-                                    ENV['localwiki_client_apikey']
-      }
+  if test_env_vars_set?
 
     context "CRUD methods" do
 
       before(:all) do
         require 'securerandom'
         @pagename = "TestPage#{SecureRandom.uuid}"
+        json = {name: @pagename, content: '<p>Created!</p>'}.to_json
+        @create_response = @wiki.create('page', json)
       end
 
       it "#create('page', json) response.status is 201" do
-        json = {name: @pagename, content: '<p>Created!</p>'}.to_json
-        response = @wiki.create('page', json)
-        response.status.should eq 201
+        @create_response.status.should eq 201
       end
 
       it "#read('page', 'TestPage<uuid>') response.status is 200" do
@@ -42,6 +42,21 @@ if test_env_vars_set?
       end
 
     end
+  end
+
+  context "#list" do
+
+    before(:all) do
+      @response = @wiki.list('page', 2)
+    end
+
+    it "returns collection of resources objects" do
+      @response['objects'].first.keys.length.should be > 1
+    end
+
+    it "limit parameter limits number of resources returned" do
+      @response['objects'].length.should eq 2
+    end
 
   end
-end
+end

data/lib/localwiki/client.rb

@@ -10,168 +10,201 @@ module Localwiki
 
     # hostname of the server we'd like to point at
     attr_accessor :hostname
-    
-    # site resource - display name of wiki
-    attr_reader   :site_name
-    
-    # site resource - time zone of server, example: 'America/Chicago'
-    attr_reader   :time_zone      
-    
-    # site resource - language code of the server, example: 'en-us'
-    attr_reader   :language_code  
+
+    # localwiki site resource
+    attr_reader   :site
 
     ##
     # Create a LocalWikiClient instance
-    #
-    # @example LocalwikiClient.new 'seattlewiki.net'
-    #
+    # @param hostname domain host of localwiki server
+    # @param user localwiki username
+    # @param apikey localwiki user's apikey provided by the localwiki server administrator
+    # @example Connect to http\:\/\/seattlewiki.net
+    #   wiki = LocalwikiClient.new 'seattlewiki.net'
+    # @example Connect to http\:\/\/seattlewiki.net with user and apikey for write access
+    #   wiki = LocalwikiClient.new 'seattlewiki.net', 'myusername', '89f17088f43b5ae22779365b8d1ff0ed076'
     def initialize hostname, user=nil, apikey=nil
-      @hostname = hostname
       @user = user
       @apikey = apikey
-      create_connection
-      collect_site_details
+      @hostname = hostname
+      initialize_connection @hostname
     end
 
     ##
     # Request total count of given resource
-    # @param resource are "site", "page", "user", "file", "map", "tag", "page_tag"
+    # @param resource_type "site", "page", "user", "file", "map", "tag", "page_tags"
     # @return [Fixnum] resource count
-    # @example wiki.count('user')
-    def count(resource)
-      list(resource.to_s,1)["meta"]["total_count"]
+    # @example Get the number of users
+    #   wiki.count('user')
+    def count(resource_type)
+      path = '/api/' + resource_type.to_s
+      response = http_get(path,{limit: '1'})
+      response["meta"]["total_count"]
     end
 
     ##
     # fetch a page by name ("The Page Name" or "The_Page_Name" or "the page name")
     # @param name "The Page Name" or "The_Page_Name" or "the page name"
-    # @return [Hash] the parsed JSON object from the response body, otherwise the whole http response object
+    # @return [Localwiki::Page] the parsed JSON object from the response body, otherwise the whole http response object
     def page_by_name(name)
-      fetch(:page,"#{name.gsub!(/\s/, '_')}")
+      fetch(:page, name)
     end
 
     ##
     # list of a specific type of resource
-    # @param resource are "site", "page", "user", "file", "map", "tag", "page_tag"
-    # @param limit is an integer
-    # @param params is a hash of query string params
-    # @return [Hash] the parsed JSON object from the response body, otherwise the whole http response object
-    def list(resource,limit=0,params={})
-      uri = '/api/' + resource.to_s
+    # @param resource_type "site", "page", "user", "file", "map", "tag", "page_tags"
+    # @param limit maximum number to return
+    # @param params hash of query string params
+    # @return [Array, Faraday::Response] array of Localwiki::Resource objects, or the http response object
+    # @example Get the first 10 files
+    #   wiki.list(:file, 10)
+    #   #=> [ #<Localwiki::File>, ... ]
+    def list(resource_type,limit=0,params={})
+      path = '/api/' + resource_type.to_s
       params.merge!({limit: limit.to_s})
-      http_get(uri,params)
+      response = http_get(path,params)
+      hydrate_list(resource_type, response['objects'])
     end
 
     ##
     # fetch a specific resource
-    # @param resource are "site", "page", "user", "file", "map", "tag", "page_tag"
-    # @param identifier is id, pagename, slug, etc.
-    # @param params is a hash of query string params
-    # @example wiki.update('page', '<page tag>')
-    # @return [Hash] the parsed JSON object from the response body, otherwise the whole http response object
-    def fetch(resource,identifier,params={})
-      uri = '/api/' + resource.to_s + '/' + slugify(identifier)
-      http_get(uri,params)
+    # @param resource_type "site", "page", "user", "file", "map", "tag", "page_tags"
+    # @param identifier id, pagename, slug, etc.
+    # @param params hash of query string params
+    # @example Get the page with the name 'Schedule'
+    #   wiki.fetch(:page, 'Schedule')
+    #   #=> #<Localwiki::Page>
+    # @return [Localwiki::Resource, Faraday::Response] the resource, or the http response object
+    def fetch(resource_type,identifier,params={})
+      path = '/api/' + resource_type.to_s + '/' + slugify(identifier)
+      hydrate(resource_type, http_get(path,params))
     end
     alias_method :read, :fetch
 
     ##
     # fetch version information for a resource
-    # @param resource are "site", "page", "user", "file", "map", "tag", "page_tag"
-    # @param identifier is id, pagename, slug, etc.
-    # @param params is a hash of query string params
-    # @example wiki.fetch_version('page', 'First Page')
-    # @return [Hash] the parsed JSON object from the response body, otherwise the whole http response object
-    def fetch_version(resource,identifier,params={})
-      uri = '/api/' + resource.to_s + '_version?name=' + identifier
-      http_get(uri,params)
+    # @param resource_type "site", "page", "user", "file", "map", "tag", "page_tags"
+    # @param identifier id, pagename, slug, etc.
+    # @param params hash of query string params
+    # @example Get the version history for page called 'First Page'
+    #   wiki.fetch_version(:page, 'First Page')
+    # @return [Hash, Faraday::Response] hash from json response body, otherwise the http response object
+    def fetch_version(resource_type,identifier,params={})
+      path = '/api/' + resource_type.to_s + '_version?name=' + identifier
+      http_get(path,params)
     end
 
     ##
     # number of unique authors that have modified a resource
-    # @param resource are "site", "page", "user", "file", "map", "tag", "page_tag"
-    # @param identifier is id, pagename, slug, etc.
-    # @param params is a hash of query string params
-    # @example wiki.unique_authors('page', 'First Page')
-    # @return [Fixnum]
-    def unique_authors(resource,identifier,params={})
-      json = fetch_version(resource,identifier,params)
+    # @param resource_type "site", "page", "user", "file", "map", "tag", "page_tags"
+    # @param identifier id, pagename, slug, etc.
+    # @param params hash of query string params
+    # @example Get number of unique authors for the page 'First Page'
+    #   wiki.unique_authors(:page, 'First Page')
+    # @return [Fixnum] number of unique authors
+    def unique_authors(resource_type,identifier,params={})
+      json = fetch_version(resource_type,identifier,params)
       json['objects'].map {|entry| entry['history_user']}.uniq.length
     end
 
     ##
-    # create a specific resource
-    # @param resource are "site", "page", "user", "file", "map", "tag", "page_tag"
-    # @param json is a json object
-    # @example wiki.create('page', <json object containing the page tag>)
-    # @return [HTTPResponse] the http response object
-    def create(resource, json)
-      uri = '/api/' + resource.to_s + '/'
-      http_post(uri, json)
+    # create a specific resource. LocalwikiClient must have been initialized with user and apikey.
+    # @param resource_type "site", "page", "user", "file", "map", "tag", "page_tags"
+    # @param json json string
+    # @example Create a page from the json string
+    #   wiki.create(:page, {name: 'New Page', content: '<p>A New Page!</p>'}.to_json)
+    # @return [Faraday::Response] http response object
+    def create(resource_type, json)
+      path = '/api/' + resource_type.to_s + '/'
+      http_post(path, json)
     end
 
     ##
-    # update a specific resource
-    # @param resource are "site", "page", "user", "file", "map", "tag", "page_tag"
-    # @param identifier is id, pagename, slug, etc.
-    # @param json is a json object
-    # @example wiki.update('page', '<page tag>', <json object>)
-    # @return [HTTPResponse] the http response object
-    def update(resource,identifier,json)
-      uri = '/api/' + resource.to_s + '/' + slugify(identifier)
-      http_put(uri, json)  
+    # update a specific resource. LocalwikiClient must have been initialized with user and apikey.
+    # @param resource_type "site", "page", "user", "file", "map", "tag", "page_tags"
+    # @param identifier id, pagename, slug, etc.
+    # @param json json string
+    # @example Update an existing page with json string
+    #   wiki.update(:page, {name: 'Existing Page', content: '<p>Updated Page!</p>'}.to_json)
+    # @return [Faraday::Response] http response object
+    def update(resource_type,identifier,json)
+      path = '/api/' + resource_type.to_s + '/' + slugify(identifier)
+      http_put(path, json)
     end
 
     ##
-    # delete a specific resource
-    # @param resource are "site", "page", "user", "file", "map", "tag", "page_tag"
-    # @param identifier is id, pagename, slug, etc.
-    # @example wiki.delete('page', '<page tag>')
-    # @return [HTTPResponse] the http response object
-    def delete(resource,identifier)
-      uri = '/api/' + resource.to_s + '/' + slugify(identifier)
-      http_delete(uri)
+    # delete a specific resource. LocalwikiClient must have been initialized with user and apikey.
+    # @param resource_type "site", "page", "user", "file", "map", "tag", "page_tags"
+    # @param identifier id, pagename, slug, etc.
+    # @example Delete the tag 'library'
+    #   wiki.delete(:tag, 'library')
+    # @return [Faraday::Response] http response object
+    def delete(resource_type,identifier)
+      path = '/api/' + resource_type.to_s + '/' + slugify(identifier)
+      http_delete(path)
     end
 
     private
 
     ##
-    # Get site resource and set instance variables
-    def collect_site_details
-      site = fetch('site','1')
-      @site_name = site['name']
-      @time_zone = site['time_zone']
-      @language_code = site['language_code']
+    # prepend the hostname
+    # @param path path portion of a url
+    # @return [String] entire url
+    def full_url(path)
+      'http://' + @hostname + path.to_s
+    end
+
+    ##
+    # Create the appropriate resource object
+    # @param resource_type "site", "page", "user", "file", "map", "tag", "page_tags"
+    # @param [Hash, Faraday::Response] param object to create resource from, or http response object
+    # @return [Localwiki::Resource, Faraday::Response] resource object, or http response object
+    def hydrate(resource_type,param)
+      # skip if given an http response object
+      return param if param.respond_to? :status
+      Localwiki::make_one(resource_type,param)
     end
 
     ##
-    # create Faraday::Connection instance and set @site
-    def create_connection
-      @site = Faraday.new :url => @hostname
+    # Create array of the appropriate resource objects
+    # @param resource_type "site", "page", "user", "file", "map", "tag", "page_tags"
+    # @param [Array, Faraday::Response] param array of objects to create resources from, or http response object
+    # @return [Array, Faraday::Response] array of resource objects, or http response object
+    def hydrate_list(resource_type,param)
+      # skip if given an http response object
+      return param if param.respond_to? :status
+      param.collect do |json_hash|
+        Localwiki::make_one(resource_type,json_hash)
+      end
+    end
+
+    ##
+    # initialize Faraday::Connection instance. set @conn and @site
+    # @param [String] hostname localwiki server hostname
+    def initialize_connection(hostname)
+      @conn = Faraday.new :url => hostname
+      @site = fetch('site','1')
     end
   
     ##
     # http get request
-    # @param uri /api/<resource>/<resource identifier>
-    # @param params is a hash of query string params
-    # @return [Hash] the parsed JSON object, otherwise the  http response object
-    def http_get(uri,params={})
+    # @param path /api/<resource>/<resource identifier>
+    # @param params hash of query string params
+    # @return [Hash, Faraday::Response] hash from json response body, otherwise the http response object
+    def http_get(path,params={})
       params.merge!({format: 'json'})
-      full_url = 'http://' + @hostname + uri.to_s
-      response = @site.get full_url, params
+      response = @conn.get full_url(path), params
       JSON.parse(response.body) rescue response
     end
     
     ##
     # http post request
-    # @param uri /api/<resource>/
-    # @param json is a json object
-    # @return [HTTPResponse] the http response object
-    def http_post(uri, json)
-      full_url = 'http://' + @hostname + uri.to_s
-      
-      @site.post do |req|
-        req.url full_url
+    # @param path /api/<resource>/
+    # @param json json string
+    # @return [Faraday::Response] http response object
+    def http_post(path, json)
+      @conn.post do |req|
+        req.url full_url(path)
         req.headers['Content-Type'] = 'application/json'
         req.headers['Authorization'] = "ApiKey #{@user}:#{@apikey}"
         req.body = json
@@ -180,14 +213,12 @@ module Localwiki
     
     ##
     # http put request
-    # @param uri /api/<resource>/<resource identifier>
-    # @param json is a json object
-    # @return [HTTPResponse] the http response object
-    def http_put(uri, json)
-      full_url = 'http://' + @hostname + uri.to_s
-      
-      @site.put do |req|
-        req.url full_url
+    # @param path /api/<resource>/<resource identifier>
+    # @param json json string
+    # @return [Faraday::Response] http response object
+    def http_put(path, json)
+      @conn.put do |req|
+        req.url full_url(path)
         req.headers['Content-Type'] = 'application/json'
         req.headers['Authorization'] = "ApiKey #{@user}:#{@apikey}"
         req.body = json
@@ -196,13 +227,11 @@ module Localwiki
 
     ##
     # http delete request
-    # @param uri /api/<resource>/<resource identifier>
-    # @return [HTTPResponse] the http response object
-    def http_delete(uri)
-      full_url = 'http://' + @hostname + uri.to_s
-
-      @site.delete do |req|
-        req.url full_url
+    # @param path /api/<resource>/<resource identifier>
+    # @return [Faraday::Response] http response object
+    def http_delete(path)
+      @conn.delete do |req|
+        req.url full_url(path)
         req.headers['Content-Type'] = 'application/json'
         req.headers['Authorization'] = "ApiKey #{@user}:#{@apikey}"
       end
@@ -211,7 +240,6 @@ module Localwiki
     ##
     # create human readable identifier that is used to create clean urls
     # @param string
-    # @example slugify('My Page') == 'My_Page'
     # @return [String]
     def slugify(string)
       string.to_s.strip.gsub(' ', "_")

data/lib/localwiki/resource.rb

@@ -0,0 +1,76 @@
+require 'ostruct'
+
+module Localwiki
+
+  ##
+  # create instance (of correct type) for resource
+  # @param type resource type "site", "page", "user", "file", "map", "tag", "page_tags"
+  # @param json_hash [Hash] hash object from parsed json
+  # @return new instance - child class of Localwiki::Resource
+  def self.make_one(type, json_hash)
+    klass_name = type.to_s.split('_').map {|s|s.capitalize}.join
+    Object.const_get('Localwiki').const_get(klass_name).new(json_hash)
+  end
+
+  ##
+  # simple OpenStruct object to allow attribute access on resources (instead of hash key access)
+  class Resource < OpenStruct
+
+    # raw json string used to instanciate object
+    attr_reader :json
+
+    ##
+    # create instance of resource
+    # @param [Hash] json_hash hash object from parsed json
+    def initialize json_hash
+      @json = json_hash
+      super
+    end
+  end
+
+  # http://localwiki.readthedocs.org/en/latest/api.html#site
+  class Site < Resource; end
+
+  # http://localwiki.readthedocs.org/en/latest/api.html#pages
+  class Page < Resource; end
+
+  ##
+  # represents map object returned from server
+  # http://localwiki.readthedocs.org/en/latest/api.html#maps
+  class Map < Resource
+
+    def single_point?
+      self.points && self.points['coordinates'].size == 1
+    end
+
+    def line?
+      self.lines
+    end
+
+    def poly?
+      self.polys
+    end
+
+    def lat
+      self.points['coordinates'].first[0] if self.single_point?
+    end
+
+    def long
+      self.points['coordinates'].first[1] if self.single_point?
+    end
+
+  end
+
+  # http://localwiki.readthedocs.org/en/latest/api.html#files
+  class File < Resource; end
+
+  # http://localwiki.readthedocs.org/en/latest/api.html#tags
+  class Tag < Resource; end
+
+  # http://localwiki.readthedocs.org/en/latest/api.html#page-tags
+  class PageTags < Resource; end
+
+  # http://localwiki.readthedocs.org/en/latest/api.html#users
+  class User < Resource; end
+
+end

data/lib/localwiki/version.rb

@@ -1,5 +1,5 @@
 module Localwiki
 
-  VERSION = '0.2.0'
+  VERSION = '0.3.0'
 
 end

data/lib/localwiki_client.rb

@@ -1,6 +1,7 @@
 $LOAD_PATH.unshift(File.dirname(__FILE__)) unless
     $LOAD_PATH.include?(File.dirname(__FILE__)) || $LOAD_PATH.include?(File.expand_path(File.dirname(__FILE__)))
 
+require 'localwiki/resource'
 require 'localwiki/client'
 require 'localwiki/version'
 

data/localwiki_client.gemspec

@@ -22,6 +22,7 @@ Gem::Specification.new do |s|
   s.add_development_dependency('webmock', '>= 1.8.0', '< 1.10')
   s.add_development_dependency('yard')
   s.add_development_dependency('kramdown')
+  s.add_development_dependency('simplecov')
 
   s.add_development_dependency('rb-fsevent')