pupa 0.0.1

data/lib/pupa/models/organization.rb

@@ -0,0 +1,40 @@
+module Pupa
+  # A group with a common purpose or reason for existence that goes beyond the set
+  # of people belonging to it.
+  class Organization < Base
+    self.schema = 'popolo/organization'
+
+    include Concerns::Timestamps
+    include Concerns::Sourceable
+    include Concerns::Nameable
+    include Concerns::Identifiable
+    include Concerns::Contactable
+    include Concerns::Linkable
+
+    attr_accessor :name, :classification, :parent_id, :parent, :founding_date,
+      :dissolution_date, :image
+
+    foreign_key :parent_id
+
+    foreign_object :parent
+
+    # Returns the name of the organization.
+    #
+    # @return [String] the name of the organization
+    def to_s
+      name
+    end
+
+    # @todo Parentless organizations in different jurisdictions can have the
+    #   same name. Add a `jurisdiction` property?
+    def fingerprint
+      hash = super.slice(:classification, :parent_id)
+      {
+        '$or' => [
+          hash.merge('name' => name),
+          hash.merge('other_names.name' => name),
+        ],
+      }
+    end
+  end
+end

data/lib/pupa/models/person.rb

@@ -0,0 +1,35 @@
+module Pupa
+  # A real person, alive or dead.
+  class Person < Base
+    self.schema = 'popolo/person'
+
+    include Concerns::Timestamps
+    include Concerns::Sourceable
+    include Concerns::Nameable
+    include Concerns::Identifiable
+    include Concerns::Contactable
+    include Concerns::Linkable
+
+    attr_accessor :name, :family_name, :given_name, :additional_name,
+      :honorific_prefix, :honorific_suffix, :patronymic_name, :sort_name,
+      :email, :gender, :birth_date, :death_date, :image, :summary, :biography
+
+    # Returns the person's name.
+    #
+    # @return [String] the person's name
+    def to_s
+      name
+    end
+
+    # @todo This will obviously need to be scoped as in Python Pupa, to a
+    #  jurisdiction, post, etc.
+    def fingerprint
+      {
+        '$or' => [
+          {'name' => name},
+          {'other_names.name' => name},
+        ],
+      }
+    end
+  end
+end

data/lib/pupa/models/post.rb

@@ -0,0 +1,28 @@
+module Pupa
+  # A position that exists independent of the person holding it.
+  class Post < Base
+    self.schema = 'popolo/post'
+
+    include Concerns::Timestamps
+    include Concerns::Sourceable
+    include Concerns::Contactable
+    include Concerns::Linkable
+
+    attr_accessor :label, :role, :organization_id, :start_date, :end_date
+
+    foreign_key :organization_id
+
+    # Returns the post's label and organization ID.
+    #
+    # @return [String] the post's label and organization ID
+    def to_s
+      "#{label} in #{organization_id}"
+    end
+
+    # A post should have a unique label within an organization, through it may
+    # share a label with a historical post.
+    def fingerprint
+      super.slice(:label, :organization_id, :end_date)
+    end
+  end
+end

data/lib/pupa/processor/client.rb

@@ -0,0 +1,42 @@
+require 'active_support/cache'
+require 'faraday_middleware'
+require 'faraday_middleware/response_middleware'
+
+require 'pupa/processor/middleware/logger'
+require 'pupa/processor/middleware/parse_html'
+require 'pupa/refinements/faraday_middleware'
+
+using Pupa::Refinements::FaradayMiddleware
+
+module Pupa
+  class Processor
+    # An HTTP client factory.
+    class Client
+      # Returns a configured Faraday HTTP client.
+      #
+      # @param [String] cache_dir a directory in which to cache requests
+      # @param [Integer] expires_in the cache's expiration time in seconds
+      # @param [String] level the log level
+      # @return [Faraday::Connection] a configured Faraday HTTP client
+      def self.new(cache_dir: nil, expires_in: 86400, level: 'INFO') # 1 day
+        Faraday.new do |connection|
+          connection.request :url_encoded
+          connection.use Middleware::Logger, Logger.new('faraday', level: level)
+          # @see http://tools.ietf.org/html/rfc2854
+          # @see http://tools.ietf.org/html/rfc3236
+          connection.use Middleware::ParseHtml, content_type: %w(text/html application/xhtml+xml)
+          # @see http://tools.ietf.org/html/rfc4627
+          connection.use FaradayMiddleware::ParseJson, content_type: /\bjson$/
+          # @see http://tools.ietf.org/html/rfc3023
+          connection.use FaradayMiddleware::ParseXml, content_type: /\bxml$/
+          if cache_dir
+            connection.response :caching do
+              ActiveSupport::Cache::FileStore.new(cache_dir, expires_in: expires_in)
+            end
+          end
+          connection.adapter Faraday.default_adapter # must be last
+        end
+      end
+    end
+  end
+end

data/lib/pupa/processor/dependency_graph.rb

@@ -0,0 +1,18 @@
+require 'tsort'
+
+module Pupa
+  class Processor
+    # A simple implementation of a dependency graph.
+    #
+    # @see http://ruby-doc.org/stdlib-2.0.0/libdoc/tsort/rdoc/TSort.html
+    class DependencyGraph < Hash
+      include TSort
+
+      alias tsort_each_node each_key
+
+      def tsort_each_child(node, &block)
+        fetch(node).each(&block)
+      end
+    end
+  end
+end

data/lib/pupa/processor/helper.rb

@@ -0,0 +1,15 @@
+module Pupa
+  class Processor
+    # Processor helper methods.
+    module Helper
+      # Normalizes all whitespace to spaces, removes consecutive spaces, and
+      # strips leading and ending spaces.
+      #
+      # @param [String] a string
+      # @return [String] a clean string
+      def clean(string)
+        string.gsub(/[[:space:]]/, ' ').squeeze(' ').strip
+      end
+    end
+  end
+end

data/lib/pupa/processor/middleware/logger.rb

@@ -0,0 +1,37 @@
+module Pupa
+  class Processor
+    module Middleware
+      # Customizes the Faraday default logger.
+      class Logger < FaradayMiddleware::ResponseMiddleware
+        extend Forwardable
+
+        def initialize(app, logger = nil)
+          super(app)
+          @logger = logger || begin
+            require 'logger'
+            ::Logger.new(STDOUT)
+          end
+        end
+
+        def_delegators :@logger, :debug, :info, :warn, :error, :fatal
+
+        def call(env)
+          info "#{env[:method]} #{env[:url].to_s} #{env[:body].to_s}" # XXX add POST body
+          debug('request') { dump_headers env[:request_headers] }
+          super
+        end
+
+        def on_complete(env)
+          debug('Status') { env[:status].to_s } # XXX switch from info
+          debug('response') { dump_headers env[:response_headers] }
+        end
+
+        private
+
+        def dump_headers(headers)
+          headers.map { |k, v| "#{k}: #{v.inspect}" }.join("\n")
+        end
+      end
+    end
+  end
+end

data/lib/pupa/processor/middleware/parse_html.rb

@@ -0,0 +1,16 @@
+module Pupa
+  class Processor
+    module Middleware
+      # A Faraday response middleware for parsing HTML.
+      #
+      # @see https://github.com/lostisland/faraday_middleware/pull/18
+      class ParseHtml < FaradayMiddleware::ResponseMiddleware
+        dependency 'nokogiri'
+
+        define_parser { |body|
+          Nokogiri::HTML(body) unless body.empty?
+        }
+      end
+    end
+  end
+end

data/lib/pupa/processor/persistence.rb

@@ -0,0 +1,80 @@
+module Pupa
+  class Processor
+    # A proxy class to save plain old Ruby objects to MongoDB.
+    class Persistence
+      # @param [Object] object an object
+      def initialize(object)
+        @object = object
+      end
+
+      # Finds a document matching the selection criteria.
+      #
+      # The selection criteria *must* set a `_type` key in order to determine
+      # the collection to query.
+      #
+      # @param [Hash] selector the selection criteria
+      # @return [Hash,nil] the matched document, or nil
+      # @raises [Pupa::Errors::TooManyMatches] if multiple documents are found
+      def self.find(selector)
+        collection_name = collection_name_from_class_name(selector[:_type].camelize)
+        query = Pupa.session[collection_name].find(selector)
+        case query.count
+        when 0
+          nil
+        when 1
+          query.first
+        else
+          raise Errors::TooManyMatches, "selector matches multiple documents during find: #{collection_name} #{JSON.dump(selector)}"
+        end
+      end
+
+      # Saves an object to MongoDB.
+      #
+      # @return [String] the object's database ID
+      # @raises [Pupa::Errors::TooManyMatches] if multiple documents would be updated
+      def save
+        selector = @object.fingerprint
+        query = collection.find(selector)
+
+        # Run query before callbacks to avoid e.g. timestamps in the selector.
+        @object.run_callbacks(:save) do
+          case query.count
+          when 0
+            @object.run_callbacks(:create) do
+              collection.insert(@object.to_h)
+              @object._id.to_s
+            end
+          when 1
+            query.update(@object.to_h)
+            query.first['_id'].to_s
+          else
+            raise Errors::TooManyMatches, "selector matches multiple documents during save: #{collection_name} #{JSON.dump(selector)}"
+          end
+        end
+      end
+
+    private
+
+      # Returns the name of the collection in which to save the object.
+      #
+      # @return [String] the name of the object's class
+      def self.collection_name_from_class_name(class_name)
+        class_name.demodulize.underscore.pluralize.to_sym
+      end
+
+      # Returns the name of the collection in which to save the object.
+      #
+      # @return [String] the name of the collection in which to save the object
+      def collection_name
+        self.class.collection_name_from_class_name(@object.class.to_s)
+      end
+
+      # Returns the collection in which to save the object.
+      #
+      # @return [Moped::Collection] the collection in which to save the object
+      def collection
+        Pupa.session[collection_name]
+      end
+    end
+  end
+end

data/lib/pupa/processor/yielder.rb

@@ -0,0 +1,50 @@
+# Using fibers instead of enumerators leads to less coupling in the processor.
+# @see https://practicingruby.com/articles/building-enumerable-and-enumerator?u=dc2ab0f9bb
+require 'fiber'
+
+module Pupa
+  class Processor
+    # A lazy enumerator.
+    class Yielder
+      # The given block should yield objects to add to the enumerator.
+      def initialize
+        @fiber = Fiber.new do
+          yield
+          raise StopIteration
+        end
+      end
+
+      # Yields each object in the enumerator to the given block.
+      def each
+        if block_given?
+          loop do
+            yield self.next
+          end
+        else
+          to_enum
+        end
+      end
+
+      # Returns the next object in the enumerator, and moves the internal position
+      # forward. When the position reaches the end, `StopIteration` is raised.
+      def next
+        if @fiber.alive?
+          @fiber.resume
+        else
+          raise StopIteration
+        end
+      end
+
+      # Returns a lazy enumerator.
+      #
+      # @return [Enumerator] a lazy enumerator
+      def to_enum
+        Enumerator.new do |y|
+          loop do
+            y << self.next
+          end
+        end
+      end
+    end
+  end
+end