ken 0.1.3 → 0.2.0

data/README.textile

@@ -107,6 +107,9 @@ Freebase itself doesn't.~
                 #<Resource id="/guid/9202a8c04000641f8000000002fa20d3" name="Everything's Gone Green">, ... ]
     # e.g. => ["1980"]
   end
+  
+  # alternatively you can access them directly
+  resource.attribute('/music/artist/album') # => #<Attribute property="/music/artist/album">
 </code>
 </pre>
 
@@ -223,7 +226,7 @@ h3. Low Level API
 Sometimes you may want to do specific queries instead of inspecting Resources as a whole.
 In such a case you would want to use Ken's low level API.
 
-_mqlread_ works like the regular _mqlread service_, except that you are able to pass ruby hashes instead of JSON.
+_mqlread_ works like the regular _mqlread service_, except that you are able to pass Ruby hashes instead of JSON.
 And you don't have to deal with HTTP, parameter encoding and parsing JSON.
 
 <pre>
@@ -243,6 +246,62 @@ And you don't have to deal with HTTP, parameter encoding and parsing JSON.
 </code>
 </pre>
 
+
+h3. Topic API
+
+Please first have a look at the official "Topic HTTP API documentation":http://www.freebase.com/docs/topic_api . 
+
+The API provides general meta-data such as name, description, links and images for a given topic,
+as well as all properties directly related to that topic in the graph.
+The API wraps a series of MQL queries that are needed to get this data, which otherwise must be performed separately.
+So for gaining common interest information about a specific topic the Topic API is a way faster alternative to mqlread.
+
+The latest update of Ken provides an easy way to access Freebase Topics using Ruby.
+As usual Ken wraps the JSON result of the web service to convenient Ruby Objects.
+
+For now Ken only returns simple properties. Support for so called mediator properties (aka 'CVT') will be added later.
+To be honest, I just don't know how to wrap them appropriately using the existing Ken object model. Any API ideas are welcome, btw! ;)
+However, in the meanwhile you can access CVT's by using the plain JSON result returned by the low level Ken.session.topic method.
+
+
+The API for Topics is quite the same as for Resources.
+
+<pre>
+<code>
+t = Ken::Topic.get("/en/new_order")
+  # => <Topic id="/en/new_order" name="New Order">
+    
+t.types
+  # => [ #<Type id="/music/artist" name="Musical Artist">, #<Type id="/music/musical_group" name="Musical Group">, ... ]
+
+t.views
+  # => [ #<View type="/music/artist">, #<View type="/music/musical_group">, ... ]
+    
+t.properties
+  # => [ #<Property id="/music/artist/similar_artist" expected_type="/music/artist">, ... ]
+
+t.attributes
+  # => [ #<Attribute property="/music/artist/similar_artist">, #<Attribute property="/music/artist/album">, ... ]
+
+</code>
+</pre>
+
+Additionally you can access some general meta-data, most importantly the topic's description which otherwise would need an additional request to the raw service.
+
+<pre>
+<code>
+
+t.name # => "New Order"
+t.description # => "New Order were an English musical group formed in 1980 by Bernard Sumner ... "
+t.aliases # => [ "NewOrder", "Englandneworder" ]
+t.webpages # => [ {"url"=>"http://en.wikipedia.org/wiki/index.html?curid=22146", "text"=>"Wikipedia"}, ... ]
+t.url # => "http://www.freebase.com/view/en/new_order"
+t.thumbnail => "http://api.freebase.com/api/trans/image_thumb/en/new_order"
+
+</code>
+</pre>
+
+
 h2. Project Status
 
 h3. Features
@@ -255,6 +314,7 @@ h3. Features
 * Low Level API (mqlread)
 * Rails and Merb support
 * Views on Resources to group Attributes based on the Resource's types
+* Accessing Topics using the new Freebase Topic API
 
 h3. Roadmap
 

data/VERSION

@@ -1 +1 @@
-0.1.3
+0.2.0

data/ken.gemspec

@@ -1,15 +1,15 @@
 # Generated by jeweler
-# DO NOT EDIT THIS FILE
-# Instead, edit Jeweler::Tasks in Rakefile, and run `rake gemspec`
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
 # -*- encoding: utf-8 -*-
 
 Gem::Specification.new do |s|
   s.name = %q{ken}
-  s.version = "0.1.3"
+  s.version = "0.2.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["michael"]
-  s.date = %q{2009-10-23}
+  s.date = %q{2009-11-02}
   s.email = %q{ma[at]zive[dot]at}
   s.extra_rdoc_files = [
     "LICENSE",
@@ -35,6 +35,7 @@ Gem::Specification.new do |s|
      "lib/ken/property.rb",
      "lib/ken/resource.rb",
      "lib/ken/session.rb",
+     "lib/ken/topic.rb",
      "lib/ken/type.rb",
      "lib/ken/util.rb",
      "lib/ken/view.rb",
@@ -43,12 +44,14 @@ Gem::Specification.new do |s|
      "tasks/spec.rb",
      "test/fixtures/music_artist.json",
      "test/fixtures/the_police.json",
+     "test/fixtures/the_police_topic.json",
      "test/integration/ken_test.rb",
      "test/test_helper.rb",
      "test/unit/attribute_test.rb",
      "test/unit/property_test.rb",
      "test/unit/resource_test.rb",
      "test/unit/session_test.rb",
+     "test/unit/topic_test.rb",
      "test/unit/type_test.rb",
      "test/unit/view_test.rb"
   ]
@@ -64,6 +67,7 @@ Gem::Specification.new do |s|
      "test/unit/property_test.rb",
      "test/unit/resource_test.rb",
      "test/unit/session_test.rb",
+     "test/unit/topic_test.rb",
      "test/unit/type_test.rb",
      "test/unit/view_test.rb",
      "examples/artist.rb",
@@ -89,3 +93,4 @@ Gem::Specification.new do |s|
     s.add_dependency(%q<addressable>, [">= 0"])
   end
 end
+

data/lib/ken/attribute.rb

@@ -1,6 +1,5 @@
 module Ken
   class Attribute
-    
     include Extlib::Assertions
     attr_reader :property
     
@@ -53,6 +52,12 @@ module Ken
       @property.value_type?
     end
     
+    # type, which attribute values of that property are expected to have
+    # @api public
+    def expected_type
+      @property.expected_type
+    end
+    
     private
     # initializes the subject if used for the first time
     def subject

data/lib/ken/resource.rb

@@ -1,7 +1,7 @@
 module Ken
   class Resource
     include Extlib::Assertions
-    
+    extend Extlib::Assertions
     attr_reader :data
     
     # initializes a resource using a json result
@@ -11,6 +11,20 @@ module Ken
       @data_fechted = data["/type/reflect/any_master"] != nil
     end
     
+    # Executes an Mql Query against the Freebase API and returns the result wrapped
+    # in a <tt>Resource</tt> Object.
+    #
+    # == Examples
+    #
+    #  Ken::Resource.get('/en/the_police') => #<Resource id="/en/the_police" name="The Police">
+    # @api public
+    def self.get(id)
+      assert_kind_of 'id', id, String
+      result = Ken.session.mqlread(FETCH_DATA_QUERY.merge!(:id => id))
+      raise ResourceNotFound unless result
+      Ken::Resource.new(result)
+    end
+    
     # resource id
     # @api public
     def id
@@ -123,7 +137,7 @@ module Ken
       fetch_data unless data_fetched?
       # master & value attributes
       raw_attributes = Ken::Util.convert_hash(@data["/type/reflect/any_master"])
-      raw_attributes.merge!(Ken::Util.convert_hash(@data["/type/reflect/any_value"]))
+      raw_attributes.merge!(Ken::Util.convert_hash(@data["/type/reflect/any_value"]))      
       @attributes = {}
       raw_attributes.each_pair do |a, d|
         properties.select { |p| p.id == a}.each do |p|

data/lib/ken/session.rb

@@ -19,6 +19,7 @@ module Ken
   class AttributeNotFound < StandardError ; end
   class PropertyNotFound < StandardError ; end
   class ResourceNotFound < StandardError ; end
+  class TopicNotFound < StandardError ; end
   class ViewNotFound < StandardError ; end
   
   # partially taken from chris eppstein's freebase api
@@ -48,7 +49,8 @@ module Ken
       :blurb => '/api/trans/blurb',
       :raw => '/api/trans/raw',
       :login => '/api/account/login',
-      :upload => '/api/service/upload'
+      :upload => '/api/service/upload',
+      :topic => '/experimental/topic',
     }
 
     # get the service url for the specified service.
@@ -94,29 +96,36 @@ module Ken
     end
     
     def raw_content(id, options = {})
-      puts raw_service_url
       response = http_request raw_service_url+id, options
       Ken.logger.info "<<< Received Raw Content Response: #{response}"
       response
     end
     
     def blurb_content(id, options = {})
-      puts blurb_service_url
       response = http_request blurb_service_url+id, options
       Ken.logger.info "<<< Received Blurb Content Response: #{response}"
       response
     end
+    
+    def topic(id, options = {})
+      options.merge!({:id => id})
+      
+      response = http_request topic_service_url+"/standard", options
+      result = JSON.parse response
+      inner = result[id]
+      handle_read_error(inner)
+      Ken.logger.info "<<< Received Topic Response: #{inner['result'].inspect}"
+      inner['result']
+    end
 
     protected
     # returns parsed json response from freebase mqlread service
     def get_query_response(query, cursor=nil)
-      envelope = { :qname => {:query => query }}
+      envelope = { :qname => {:query => query, :escape => false }}
       envelope[:qname][:cursor] = cursor if cursor
       
       response = http_request mqlread_service_url, :queries => envelope.to_json
-      
       result = JSON.parse response
-      
       inner = result['qname']
       handle_read_error(inner)
       Ken.logger.info "<<< Received Response: #{inner['result'].inspect}"
@@ -132,7 +141,7 @@ module Ken
     def http_request(url, parameters = {})
       params = params_to_string(parameters)
       url << '?'+params unless params !~ /\S/
-
+            
       return Net::HTTP.get_response(::URI.parse(url)).body
       
       fname = "#{MD5.md5(params)}.mql"

data/lib/ken/topic.rb

@@ -0,0 +1,194 @@
+module Ken
+  class Topic
+    include Extlib::Assertions
+    extend Extlib::Assertions
+    
+    attr_reader :data
+    
+    # initializes a topic using a json result
+    def initialize(data)
+      assert_kind_of 'data', data, Hash
+      @data = data
+      @schema_loaded, @attributes_loaded = false, false
+    end
+    
+    # Retrieves a topic using the Topic API by Freebase
+    # returns a <tt>Topic</tt> Object.
+    #
+    # == Examples
+    #
+    #  Ken::Topic.get('/en/the_police') => #<Topic id="/en/the_police" name="The Police">
+    # @api public
+    def self.get(id)
+      assert_kind_of 'id', id, String
+      result = Ken.session.topic(id)
+      raise TopicNotFound unless result
+      Ken::Topic.new(result)
+    end
+    
+    # topic id
+    # @api public
+    def id
+      @data["id"] || ""
+    end
+    
+    # topic aliases
+    def aliases
+      @data["alias"]
+    end
+    
+    # topic freebase url
+    def url
+      @data["url"]
+    end
+    
+    # topic name
+    # @api public
+    def name
+      text
+    end
+    
+    # topic description
+    # @api public
+    def description
+      @data["description"]
+    end
+    
+    # topic text
+    # @api public
+    def text
+      @data["text"]
+    end
+    
+    # topic thumbnail
+    def thumbnail
+      @data["thumbnail"]
+    end
+    
+    # @api public
+    def to_s
+      name || id || ""
+    end
+
+    # @api public
+    def inspect
+      result = "#<Topic id=\"#{id}\" name=\"#{name || "nil"}\">"
+    end
+    
+    # topic webpages
+    # currently returned as an array of hashes containing the keys "text" and "url"
+    # that hashes may be wrapped into a Webpage class later
+    # @api public
+    def webpages
+      @data["webpage"]
+    end
+    
+    # returns all assigned types
+    # @api public
+    def types
+      load_schema! unless schema_loaded?
+      @types
+    end
+    
+    # returns individual type based on the requested type id
+    # @api public
+    def type(type)
+      types.each { |t| return t if t.id =~ /^#{Regexp.escape(type)}$/}
+      nil
+    end
+    
+    # returns all the properties from all assigned types
+    # @api public
+    def properties
+      @properties = Ken::Collection.new
+      types.each do |type|
+        @properties.concat(type.properties)
+      end
+      @properties
+    end
+    
+    # returns all attributes for every type the topic is an instance of
+    # @api public
+    def attributes
+      load_attributes! unless attributes_loaded?
+      @attributes.values
+    end 
+    
+    # returns all available views based on the assigned types
+    # @api public
+    def views
+      @views ||= Ken::Collection.new(types.map { |type| Ken::View.new(self, type) })
+    end
+    
+    # returns individual view based on the requested type id
+    # @api public
+    def view(type)
+      views.each { |v| return v if v.type.id =~ /^#{Regexp.escape(type)}$/}
+      nil
+    end
+    
+    
+    # search for an attribute by name and return it
+    # @api public
+    def attribute(name)
+      attributes.each { |a| return a if a.property.id == name }
+      nil
+    end
+    
+    # returns true if type information is already loaded
+    # @api public
+    def schema_loaded?
+      @schema_loaded
+    end
+    
+    # returns true if attributes are already loaded
+    # @api public
+    def attributes_loaded?
+      @attributes_loaded
+    end
+    
+    private
+    
+    # loads the full set of attributes using reflection
+    # information is extracted from master, value and reverse attributes
+    # @api private
+    def load_attributes!
+      load_schema! unless schema_loaded?
+      
+      @attributes = {}
+      @data["properties"].each do |id, data|
+        # skip mediator properties for now
+        if !data["properties"]
+          values = []
+          data["values"].each do |value|
+            values << { "id" => value["id"], "name" => value["text"], "value" => value["text"] }
+          end
+          @attributes[id] = Ken::Attribute.create(values, properties.select { |p| p.id == id }.first)
+        end
+      end
+      
+      @attributes_loaded = true
+    end
+    
+    # loads the topic's metainfo
+    # @api private
+    def load_schema!
+      result = {}
+      
+      @data["type"].each do |type|
+        result[type["id"]] = { "id" => type["id"], "name" => type["text"], "properties" => [] }
+      end
+      @data["properties"].each do |id, data|        
+        result[id.gsub(/\/\w*$/, "")]["properties"] << {
+          "expected_type" => data["expected_type"]["id"],
+          "id" => id,
+          "name" => data["text"],
+          "unique" => true 
+        }
+      end
+      @types = Ken::Collection.new(result.values.map { |type| Ken::Type.new(type) })
+      @schema_loaded = true
+    end
+    
+  end # class Topic
+end # module Ken

data/lib/ken/view.rb

@@ -1,15 +1,14 @@
-# provides an interface to view a resource as a specific type
+# provides an interface to view a subject (resource or topic) as a specific type
 # provides an interface for working with attributes, properties
 module Ken
   class View
     
     include Extlib::Assertions
     
-    # initializes a resource by json result
-    def initialize(resource, type)
-      assert_kind_of 'resource', resource, Ken::Resource
+    # initializes a subject (resource or topic) by json result
+    def initialize(subject, type)
       assert_kind_of 'type', type, Ken::Type
-      @resource, @type = resource, type
+      @subject, @type = subject, type
     end
     
     # @api public
@@ -31,7 +30,7 @@ module Ken
     # returns attributes which are member of the view's type
     # @api public
     def attributes
-      @resource.attributes.select { |a| a.property.type == @type}
+      @subject.attributes.select { |a| a.property.type == @type}
     end
     
     # search for an attribute by name and return it
@@ -44,7 +43,7 @@ module Ken
     # returns properties which are member of the view's type    
     # @api public
     def properties
-      @resource.properties.select { |p| p.type == @type}
+      @subject.properties.select { |p| p.type == @type}
     end
     
     # delegate to attribute

data/lib/ken.rb

@@ -8,13 +8,14 @@ require 'addressable/uri'
 dir = Pathname(__FILE__).dirname.expand_path + 'ken'
 
 require dir + 'util'
+require dir + 'session'
 require dir + 'resource'
 require dir + 'type'
 require dir + 'view'
 require dir + 'property'
 require dir + 'attribute'
 require dir + 'collection'
-require dir + 'session'
+require dir + 'topic'
 require dir + 'logger'
 
 # init logger as soon as the library is required
@@ -117,10 +118,7 @@ module Ken
   #  Ken.get('/en/the_police') => #<Resource id="/en/the_police" name="The Police">
   # @api public
   def self.get(id)
-    assert_kind_of 'id', id, String
-    result = Ken.session.mqlread(FETCH_DATA_QUERY.merge!(:id => id))
-    raise ResourceNotFound unless result
-    Ken::Resource.new(result)
+    Ken::Resource.get(id)
   end
   
 end # module Ken