epo-ops 0.2.6 → 0.3.0

data/lib/epo/ops/ipc_class_hierarchy_loader.rb

@@ -1,62 +0,0 @@
-require 'httparty'
-require 'epo/ops/ipc_class_util'
-
-module Epo
-  module Ops
-    # Usually this should only used internally.
-    # Loads the Hierarchy from the WIPO.
-    # This is used to update IpcClassHierarchy manually.
-    # At the beginning of the year the WIPO publishes a new list of IPC classes.
-    # The IpcClassHierarchy should then be updated. Make sure that the url is
-    # correct!
-    class IpcClassHierarchyLoader
-      # loads data from the WIPO
-      # @return [Hash]
-      def self.load
-        load_url
-      end
-
-      private
-
-      def self.load_url
-        url = 'http://www.wipo.int/ipc/itos4ipc/ITSupport_and_download_area/20160101/IPC_scheme_title_list/EN_ipc_section_#letter_title_list_20160101.txt'
-
-        # There is a file for every letter A-H
-        ('A'..'H').inject({}) do |mem, letter|
-          # Fetch the file from the server
-          response = HTTParty.get(url.gsub('#letter', letter), http_proxyaddr: proxy[:addr], http_proxyport: proxy[:port])
-          file = response.body
-          mem.merge! process_file(file)
-        end
-      end
-
-      def self.process_file(file)
-        # Process every line (There is a line for every class entry, name and description are separated by a \t)
-        file.each_line.inject(Hash.new { |h, k| h[k] = [] }) do |mem, line|
-          next if line.to_s.strip.empty?
-          ipc_class_generic, description = line.split("\t")
-
-          # Some entries in the files have the same ipc class, the first line is
-          # just some kind of headline, the second is the description we want.
-          ipc_class = Epo::Ops::IpcClassUtil.parse_generic_format(ipc_class_generic)
-          if ipc_class.length == 3
-            mem[ipc_class[0]] << ipc_class
-          elsif ipc_class.length == 4
-            mem[ipc_class[0, 3]] << ipc_class
-          end
-          mem
-        end
-      end
-
-      def self.proxy
-        # configure proxy
-        proxy_addr = nil
-        proxy_port = nil
-        unless ENV['http_proxy'].to_s.strip.empty?
-          proxy_addr, proxy_port = ENV['http_proxy'].gsub('http://', '').gsub('/', '').split(':')
-        end
-        { addr: proxy_addr, port: proxy_port }
-      end
-    end
-  end
-end

data/lib/epo/ops/ipc_class_util.rb

@@ -1,73 +0,0 @@
-require 'epo/ops/ipc_class_hierarchy'
-
-module Epo
-  module Ops
-    # Utility functions to work on Strings representing ipc classes.
-    class IpcClassUtil
-
-      # @return [Array] \['A', 'B', …, 'H'\]
-      def self.main_classes
-        %w( A B C D E F G H )
-      end
-
-      # check if the given ipc_class is valid as OPS search parameter
-      # @param [String] ipc_class an ipc class
-      # @return [Boolean]
-      def self.valid_for_search?(ipc_class)
-        ipc_class.match(/\A[A-H](\d{2}([A-Z](\d{1,2}\/\d{2,3})?)?)?\z/)
-      end
-
-      # There is a generic format for ipc classes that does not have
-      # the / as delimiter and leaves space for additions. This parses
-      # it into the format the register search understands
-      # @param [String] generic ipc class in generic format
-      # @return [String] reformatted ipc class
-      # @example
-      #   parse_generic_format('A01B0003140000') #=> 'A01B3/14'
-      def self.parse_generic_format(generic)
-        ipc_class = generic
-        if ipc_class.length > 4
-          match = ipc_class.match(/([A-Z]\d{2}[A-Z])(\d{4})(\d{6})$/)
-          ipc_class = match[1] + (match[2].to_i).to_s + '/' + process_number(match[3])
-        end
-        ipc_class
-      end
-
-      # @param [String] ipc_class an ipc_class
-      # @return [Array] List of all ipc classes one level more specific.
-      # @examples
-      #   children('A')   #=> ['A01', 'A21', 'A22', 'A23', ...]
-      #   children('A62') #=> ['A62B', 'A62C', 'A62D'],
-      # @raise [InvalidIpcClassError] if parameter is not a valid ipc class in
-      #   the format EPO understands
-      # @raise [LevelNotSupportedError] for parameters with ipc class depth >= 3
-      #   e.g. 'A62B' cannot be split further. It is currently not necessary to
-      #   do so, it would only blow up the gem, and you do not want to query for
-      #   all classes at the lowest level, as it takes too many requests.
-      def self.children(ipc_class)
-        return main_classes if ipc_class.nil?
-        valid = valid_for_search?(ipc_class)
-        fail InvalidIpcClassError, ipc_class unless valid
-        map = IpcClassHierarchy::Hierarchy
-        fail LevelNotSupportedError, ipc_class unless map.key? ipc_class
-        map[ipc_class]
-      end
-
-      # An ipc class in invalid format was given, or none at all.
-      class InvalidIpcClassError < StandardError; end
-      # It is currently not supported to split by the most specific class level.
-      # This would result in a large amount of requests.
-      class LevelNotSupportedError < StandardError; end
-
-      private
-
-      def self.process_number(number)
-        result = number.gsub(/0+$/, '')
-        result += '0' if result.length == 1
-        result = '00' if result.length == 0
-
-        result
-      end
-    end
-  end
-end

data/lib/epo/ops/limits.rb

@@ -1,22 +0,0 @@
-module Epo
-  module Ops
-    # The register search is limited by some parameters. With one
-    # query one may only request as many as
-    # {Epo::Ops::Limits::MAX_QUERY_INTERVAL} references at once.
-    # Considering this, you have to split your requests by this
-    # interval.  Nevertheless, the maximum value you may use is
-    # {Epo::Ops::Limits::MAX_QUERY_RANGE}. If you want to retrieve more
-    # references you must split by other parameters.
-    # @see Register
-    class Limits
-      # @return [Integer] The range in which you can search is limited, say you
-      #   cannot request all patents of a given class at once, you probably must
-      #   split your requests by additional conditions.
-      MAX_QUERY_RANGE = 2000
-
-      # @return [Integer] The maximum number of elements you may search with one
-      #   query. Ignoring this will result in errors.
-      MAX_QUERY_INTERVAL = 100
-    end
-  end
-end

data/lib/epo/ops/logger.rb

@@ -1,11 +0,0 @@
-module Epo
-  module Ops
-    # Simple logger writing some notifications to standard output.
-    class Logger
-      # Just hands the parameter to puts.
-      def self.log(output)
-        puts output
-      end
-    end
-  end
-end

data/lib/epo/ops/rate_limit.rb

@@ -1,49 +0,0 @@
-module Epo
-  module Ops
-    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
-end

data/lib/epo/ops/register.rb

@@ -1,152 +0,0 @@
-require 'epo/ops'
-require 'epo/ops/client'
-require 'epo/ops/util'
-require 'epo/ops/bibliographic_document'
-require 'epo/ops/logger'
-require 'epo/ops/ipc_class_util'
-
-module Epo
-  module Ops
-    # Access to the {http://ops.epo.org/3.2/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 Epo::Ops::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
-          Epo::Ops::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, true)
-        return 0 if minimum_result_set.empty?
-        minimum_result_set['world_patent_data']['register_search']['total_result_count'].to_i
-      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.flat_map { |query| raw_search(query) }
-        search_entries.uniq { |se| se.application_reference.epodoc_reference }
-      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 {Epo::Ops::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 [Array] containing {SearchEntry}
-      def self.raw_search(query, raw = false)
-        hash = Client.request(:get, register_api_string + 'search?' + query).parsed
-        return parse_search_results(hash) unless raw
-        hash
-      rescue Epo::Ops::Error::NotFound
-        []
-      end
-
-      # @param search_entry [SearchEntry] a search entry which should be
-      #   retrieved.
-      # @return [BibliographicDocument] a parsed document.
-      def self.biblio(search_entry)
-        raw_biblio(search_entry.application_reference.epodoc_reference)
-      end
-
-      # @param reference_id [String] identifier for document. Format similar to
-      #   EP1000000
-      # @param format [String] epodoc is a format defined by the EPO for a
-      #   document id. see their documentation.
-      # @param type [String] may be `application` or `publication` make sure
-      #   that the `reference_id` is matching
-      # @param raw [Boolean] flag if the result should be returned as a raw Hash
-      #   or parsed as {BibliographicDocument}
-      # @return [BibliographicDocument, Hash]
-      def self.raw_biblio(reference_id, type = 'application', format = 'epodoc', raw = false)
-        request = "#{register_api_string}#{type}/#{format}/#{reference_id}/biblio"
-        result = Client.request(:get, request).parsed
-        raw ? result : BibliographicDocument.new(result)
-      end
-
-      Reference = Struct.new(:country, :doc_number, :date) do
-        def epodoc_reference
-          country + doc_number
-        end
-      end
-
-      SearchEntry = Struct.new(:publication_reference, :application_reference, :ipc_classes)
-
-      private
-
-      def self.parse_search_results(result)
-        path = %w(world_patent_data register_search register_documents register_document bibliographic_data)
-
-        list = Util.find_in_data(result, path)
-        list.map do |entry|
-          publication_reference = Reference.new(
-            entry['publication_reference']['document_id']['country'],
-            entry['publication_reference']['document_id']['doc_number'],
-            entry['publication_reference']['document_id']['date'])
-          application_reference = Reference.new(
-            entry['application_reference']['document_id']['country'],
-            entry['application_reference']['document_id']['doc_number'])
-          ipc_classes = entry['classifications_ipcr']['classification_ipcr']['text'].split(';;').map(&:strip)
-          SearchEntry.new(publication_reference, application_reference, ipc_classes)
-        end
-      end
-
-      def self.register_api_string
-        "/#{Epo::Ops::API_VERSION}/rest-services/register/"
-      end
-    end
-  end
-end

data/lib/epo/ops/search_query_builder.rb

@@ -1,65 +0,0 @@
-require 'epo/ops/limits'
-require 'epo/ops/logger'
-
-module Epo
-  module Ops
-    # 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 = 1, 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 Epo::Ops::Limits
-      # @return array with two elements: [range_start, range_end]
-      def self.validate_range(range_start, range_end)
-        if range_start > range_end
-          range_start, range_end = range_end, range_start
-          Logger.log('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.log("range invalid, set to: #{[range_start, range_end]}")
-        end
-        if range_start < 1
-          range_end = range_end - range_start + 1
-          range_start = 1
-          Logger.log("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.log("range_end was too big, set to: #{[range_start, range_end]}")
-        end
-        [range_start, range_end]
-      end
-    end
-  end
-end

data/lib/epo/ops/token_store.rb

@@ -1,35 +0,0 @@
-require 'oauth2'
-require 'epo/ops'
-
-module Epo
-  module Ops
-    # 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(
-          Epo::Ops.config.consumer_key,
-          Epo::Ops.config.consumer_secret,
-          site: 'https://ops.epo.org/',
-          token_url: "/#{Epo::Ops::API_VERSION}/auth/accesstoken",
-          raise_errors: false
-        )
-
-        client.client_credentials.get_token
-      end
-    end
-  end
-end