epo-ops 0.2.6 → 0.3.0

data/lib/epo_ops/rate_limit.rb

@@ -0,0 +1,47 @@
+module EpoOps
+  class RateLimit
+    WEEKLY_QUOTA_RESET_TIME = 604_800
+    HOURLY_QUOTA_RESET_TIME = 600
+    BASE_RESET_TIME = 60
+
+    attr_reader :attr
+
+    def initialize(http_header)
+      fail "Rate Limit data should be a Hash but is #{http_header.inspect} (#{http_header.class.name})" unless http_header.is_a?(Hash)
+      @attr = http_header
+    end
+
+    def limit_reached?
+      @attr.key?('x-rejection-reason')
+    end
+
+    def rejection_reason
+      return nil unless @attr['x-rejection-reason']
+      case @attr['x-rejection-reason']
+      when 'RegisteredQuotaPerWeek' then :weekly_quota
+      when 'IndividualQuotaPerHour' then :hourly_quota
+      else :unknown_reason
+      end
+    end
+
+    def hourly_quota
+      quota = @attr['x-individualquotaperhour-used']
+      quota.to_i if quota
+    end
+
+    def weekly_quota
+      quota = @attr['x-registeredquotaperweek-used']
+      quota.to_i if quota
+    end
+
+    def reset_at
+      return unless limit_reached?
+
+      case rejection_reason
+      when :weekly_quota then Time.now.to_i + WEEKLY_QUOTA_RESET_TIME
+      when :hourly_quota then Time.now.to_i + HOURLY_QUOTA_RESET_TIME
+      else Time.now.to_i + BASE_RESET_TIME
+      end
+    end
+  end
+end

data/lib/epo_ops/register.rb

@@ -0,0 +1,100 @@
+require 'epo_ops'
+require 'epo_ops/client'
+require 'epo_ops/util'
+require 'epo_ops/logger'
+require 'epo_ops/ipc_class_util'
+
+module EpoOps
+  # Access to the {http://ops.epo.org/3.1/rest-services/register register}
+  # endpoint of the EPO OPS API.
+  #
+  # By now you can search and retrieve patents by using the type `application`
+  # in the `epodoc` format.
+  #
+  # Search queries are limited by size, not following these limits
+  # will result in errors. You should probably use {.search} which handles the
+  # limits itself.
+  #
+  # For more fine grained control use {.raw_search} and {.raw_biblio}
+  #
+  # @see Limits
+  # @see SearchQueryBuilder
+  class Register
+    # A helper method which creates queries that take API limits into account.
+    # @param patent_count [Integer] number of overall results expected.
+    #   See {.published_patents_count}
+    #
+    # @return [Array] of Strings, each a query to put into {Register.raw_search}
+    # @see EpoOps::Limits
+    def self.split_by_size_limits(ipc_class, date, patent_count)
+      max_interval = Limits::MAX_QUERY_INTERVAL
+      (1..patent_count).step(max_interval).map do |start|
+        range_end = [start + max_interval - 1, patent_count].min
+        EpoOps::SearchQueryBuilder.build(ipc_class, date, start, range_end)
+      end
+    end
+
+    # Makes the requests to find how many patents are in each top
+    # level ipc class on a given date.
+    #
+    # @param date [Date] date on which patents should be counted
+    # @return [Hash] Hash ipc_class => count (ipc_class A-H)
+    def self.patent_counts_per_ipc_class(date)
+      %w( A B C D E F G H ).inject({}) do |mem, icc|
+        mem[icc] = published_patents_counts(icc, date)
+        mem
+      end
+    end
+
+    # @param date [Date]
+    # @param ipc_class [String] up to now should only be between A-H
+    # @return [Integer] number of patents with given parameters
+    def self.published_patents_counts(ipc_class = nil, date = nil)
+      query = SearchQueryBuilder.build(ipc_class, date, 1, 2)
+      minimum_result_set = Register.raw_search(query)
+      minimum_result_set.count
+    end
+
+    # Search method returning all unique register references on a given
+    # date, with optional ipc_class.
+    # @note This method does more than one query; it may happen that you
+    #   exceed your API limits
+    # @return [Array] Array of {SearchEntry}
+    def self.search(ipc_class = nil, date = nil)
+      queries = all_queries(ipc_class, date)
+      search_entries = queries.map { |query| raw_search(query) }
+      applications = search_entries.collect(&:patents)
+
+      EpoOps::RegisterSearchResult.new(applications,applications.count)
+    end
+
+    # @return [Array] Array of Strings containing queries applicable to
+    #   {Register.raw_search}.
+    # builds all queries necessary to find all patent references on a given
+    # date.
+    def self.all_queries(ipc_class = nil, date = nil)
+      count = published_patents_counts(ipc_class, date)
+      if count > Limits::MAX_QUERY_RANGE
+        IpcClassUtil.children(ipc_class).flat_map { |ic| all_queries(ic, date) }
+      else
+        split_by_size_limits(ipc_class, date, count)
+      end
+    end
+
+    # @param query A query built with {EpoOps::SearchQueryBuilder}
+    # @param raw if `true` the result will be the raw response as a nested
+    #   hash. if false(default) the result will be parsed further, returning a
+    #   list of [SearchEntry]
+    # @return [RegisterSearchResult]
+    def self.raw_search(query, raw = false)
+      data = Client.request(
+        :get,
+        '/3.1/rest-services/register/search?' + query
+      ).parsed
+
+      EpoOps::Factories::RegisterSearchResultFactory.build(data)
+    rescue EpoOps::Error::NotFound
+      raw ? nil : EpoOps::RegisterSearchResult::NullResult.new
+    end
+  end
+end

data/lib/epo_ops/register_search_result.rb

@@ -0,0 +1,40 @@
+module EpoOps
+  # A simple wrapper for register search query result.
+  class RegisterSearchResult
+    include Enumerable
+
+    def initialize(patents,count,raw_data = nil)
+      @patents = patents
+      @count = count
+      @raw_data = raw_data
+    end
+
+    # The number of patents that match the query string. Offsets and API query limits do not apply
+    # so that the actual number of patents returned can be much smaller.
+    # @see EpoOps::Limits
+    # @return [integer] The number of applications matching the query.
+    attr_reader :count
+
+    # @return [Array] the patents returned by the search. Patentapplication data is not complete
+    attr_reader :patents
+
+    def each
+      patents.each do |patent|
+        yield(patent)
+      end
+    end
+
+    # Represents queries with no results
+    class NullResult < EpoOps::RegisterSearchResult
+      def initialize(data=nil) ; end
+
+      def count
+        0
+      end
+
+      def patents
+        []
+      end
+    end
+  end
+end

data/lib/epo_ops/search_query_builder.rb

@@ -0,0 +1,65 @@
+require 'epo_ops/limits'
+require 'epo_ops/logger'
+
+module EpoOps
+  # This Builder helps creating a search query using
+  # {https://www.loc.gov/standards/sru/cql/ CQL} (Common Query Language or
+  # Contextual Query Language) with the identifiers specified by the EPO in
+  # the OPS Documentation chapter 4.2 ({https://www.epo.org/searching-for-patents/technical/espacenet/ops.html Link})
+  # - use tab Downloads and see file 'OPS version 3.1 documentation').
+  class SearchQueryBuilder
+    # Build the query with the given parameters. Invalid ranges are fixed
+    # automatically and you will be notified about the changes
+    # @return [String]
+    def self.build(ipc_class, date, range_start = nil, range_end = nil)
+      validated_range = validate_range range_start, range_end
+      "q=#{build_params(ipc_class, date)}&Range=#{validated_range[0]}-#{validated_range[1]}"
+    end
+
+    private
+
+    def self.build_params(ipc_class, date)
+      [build_date(date), build_class(ipc_class)].compact.join(' and ')
+    end
+
+    def self.build_date(date)
+      if date
+        "pd=#{('%04d' % date.year)}"\
+        "#{('%02d' % date.month)}"\
+        "#{('%02d' % date.day)}"
+      end
+    end
+
+    def self.build_class(ipc_class)
+      "ic=#{ipc_class}" if ipc_class
+    end
+
+    # Fixes the range given so that they meed the EPO APIs rules. The range
+    #  may only be 100 elements long, the maximum allowed value is 2000.
+    # If the given window is out of range, it will be moved preserving the
+    # distance covered.
+    # @see EpoOps::Limits
+    # @return array with two elements: [range_start, range_end]
+    def self.validate_range(range_start, range_end)
+      range_start = 1 unless range_start
+      range_end = 10 unless range_end
+      if range_start > range_end
+        range_start, range_end = range_end, range_start
+        Logger.debug('range_start was bigger than range_end, swapped values')
+      elsif range_end - range_start > Limits::MAX_QUERY_INTERVAL - 1
+        range_end = range_start + Limits::MAX_QUERY_INTERVAL - 1
+        Logger.debug("range invalid, set to: #{[range_start, range_end]}")
+      end
+      if range_start < 1
+        range_end = range_end - range_start + 1
+        range_start = 1
+        Logger.debug("range_start must be > 0, set to: #{[range_start, range_end]}")
+      elsif range_end > Limits::MAX_QUERY_RANGE
+        range_start = Limits::MAX_QUERY_RANGE - (range_end - range_start)
+        range_end = Limits::MAX_QUERY_RANGE
+        Logger.debug("range_end was too big, set to: #{[range_start, range_end]}")
+      end
+      [range_start, range_end]
+    end
+  end
+end

data/lib/epo_ops/token_store.rb

@@ -0,0 +1,33 @@
+require 'oauth2'
+require 'epo_ops'
+
+module EpoOps
+  # This class saves the token in memory, you may want to subclass this and
+  # overwrite #token if you want to store it somewhere else.
+  #
+  class TokenStore
+    def token
+      @token = generate_token if !@token || @token.expired?
+
+      @token
+    end
+
+    def reset
+      @token = nil
+    end
+
+    protected
+
+    def generate_token
+      client = OAuth2::Client.new(
+        EpoOps.config.consumer_key,
+        EpoOps.config.consumer_secret,
+        site: 'https://ops.epo.org/',
+        token_url: '/3.1/auth/accesstoken',
+        raise_errors: false
+      )
+
+      client.client_credentials.get_token
+    end
+  end
+end

data/lib/epo_ops/token_store/redis.rb

@@ -0,0 +1,45 @@
+require 'redis'
+require 'connection_pool'
+
+module EpoOps
+  class TokenStore
+    class Redis < TokenStore
+      def initialize(redis_host)
+        fail "Please install gems 'redis' and 'connection_pool' to use this feature" unless defined?(::Redis) && defined?(ConnectionPool)
+
+        @redis = ConnectionPool.new(size: 5, timeout: 5) { ::Redis.new(host: redis_host) }
+      end
+
+      def token
+        token = nil
+        @redis.with do |conn|
+          token = conn.get("epo_token_#{id}")
+        end
+
+        token.present? ? OAuth2::AccessToken.new(client, token) : generate_token
+      end
+
+      def reset
+        @redis.with do |conn|
+          conn.del("epo_token_#{id}")
+        end
+      end
+
+      private
+
+      def id
+        Digest::MD5.hexdigest(EpoOps.config.consumer_key + EpoOps.config.consumer_secret)
+      end
+
+      def generate_token
+        token = super
+
+        @redis.with do |conn|
+          conn.set("epo_token_#{id}", token.token, ex: token.expires_in, nx: true)
+        end
+
+        token
+      end
+    end
+  end
+end

data/lib/epo_ops/util.rb

@@ -0,0 +1,52 @@
+module EpoOps
+  class Util
+    # the path should be an array of strings indicating the path you want to go in the hash
+    def self.find_in_data(epo_hash, path)
+      path.reduce(epo_hash) { |res, c| parse_hash_flat(res, c) }
+    end
+
+    def self.parse_hash_flat(hash_layer, target)
+      result = []
+      if hash_layer.nil?
+        return []
+      elsif hash_layer.class == String
+        return []
+      elsif hash_layer.class == Array
+        result.concat(hash_layer.map { |x| parse_hash_flat(x, target) })
+      elsif hash_layer[target]
+        result << hash_layer[target]
+      elsif hash_layer.class == Hash || hash_layer.respond_to?(:to_h)
+        result.concat(hash_layer.to_h.map { |_x, y| parse_hash_flat(y, target) })
+      end
+      result.flatten
+    end
+
+    def self.dig(data,*path)
+      path.flatten.inject(data) do |d,key|
+        if d.is_a? Hash
+          d[key]
+        else
+          nil
+        end
+      end
+    end
+
+    def self.flat_dig(data,*path)
+      path.flatten.inject(data) do |d,key|
+        if d.is_a? Hash
+          d[key].is_a?(Array) ? d[key] : [d[key]]
+        elsif d.is_a? Array
+          d.select {|element| element.is_a? Hash}.flat_map {|element| element[key]}
+        else
+          []
+        end
+      end.reject(&:nil?)
+    end
+
+    def self.parse_change_gazette_num(num)
+      res = /^(?<year>\d{4})\/(?<week>\d{2})$/.match(num)
+      return nil if res.nil?
+      Date.commercial(Integer(res[:year], 10), week = Integer(res[:week], 10))
+    end
+  end
+end

data/lib/epo_ops/version.rb

@@ -0,0 +1,3 @@
+module EpoOps
+  VERSION = '0.3.0'.freeze
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: epo-ops
 version: !ruby/object:Gem::Version
-  version: 0.2.6
+  version: 0.3.0
 platform: ruby
 authors:
 - Max Kießling
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-07-04 00:00:00.000000000 Z
+date: 2016-05-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -174,28 +174,34 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".gitignore"
+- ".travis.yml"
 - Gemfile
 - LICENSE
 - README.md
 - Rakefile
 - epo-ops.gemspec
-- lib/epo/ops.rb
-- lib/epo/ops/address.rb
-- lib/epo/ops/bibliographic_document.rb
-- lib/epo/ops/client.rb
-- lib/epo/ops/error.rb
-- lib/epo/ops/ipc_class_hierarchy.rb
-- lib/epo/ops/ipc_class_hierarchy_loader.rb
-- lib/epo/ops/ipc_class_util.rb
-- lib/epo/ops/limits.rb
-- lib/epo/ops/logger.rb
-- lib/epo/ops/rate_limit.rb
-- lib/epo/ops/register.rb
-- lib/epo/ops/search_query_builder.rb
-- lib/epo/ops/token_store.rb
-- lib/epo/ops/token_store/redis.rb
-- lib/epo/ops/util.rb
-- lib/epo/ops/version.rb
+- lib/epo_ops.rb
+- lib/epo_ops/client.rb
+- lib/epo_ops/error.rb
+- lib/epo_ops/factories.rb
+- lib/epo_ops/factories/name_and_address_factory.rb
+- lib/epo_ops/factories/patent_application_factory.rb
+- lib/epo_ops/factories/register_search_result_factory.rb
+- lib/epo_ops/ipc_class_hierarchy.rb
+- lib/epo_ops/ipc_class_hierarchy_loader.rb
+- lib/epo_ops/ipc_class_util.rb
+- lib/epo_ops/limits.rb
+- lib/epo_ops/logger.rb
+- lib/epo_ops/name_and_address.rb
+- lib/epo_ops/patent_application.rb
+- lib/epo_ops/rate_limit.rb
+- lib/epo_ops/register.rb
+- lib/epo_ops/register_search_result.rb
+- lib/epo_ops/search_query_builder.rb
+- lib/epo_ops/token_store.rb
+- lib/epo_ops/token_store/redis.rb
+- lib/epo_ops/util.rb
+- lib/epo_ops/version.rb
 homepage: https://github.com/FHG-IMW/epo-ops
 licenses: []
 metadata: {}
@@ -215,7 +221,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.5.2
+rubygems_version: 2.4.8
 signing_key: 
 specification_version: 4
 summary: Ruby interface to the European Patent Office API (OPS)