football-butler 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ac3e5bc4938cd010674e12b86aa82cadfe6e726e547bf74b819ba837513bc6be
+  data.tar.gz: 5d8ab6c615a5118b917b1ac11dcf92cccf657112d67472b678b2a1af9efa10b7
+SHA512:
+  metadata.gz: c71e8b4d174abbb48a2c2810b0b963e63f6fd879772e77c1869b8fa6870fe59dc22ead56a898bfdbc65065e3e969930987d5c169667330fda36c6d043a90c7de
+  data.tar.gz: f94ff67c41f1cca54a54eea7c70dc3674dc6ef184868e6656ba3ac4d100704c8054026c9894c4ac9eb7dfa88c63a9dd2d7d712b7c6262607441dd8e1f174fcc0

data/lib/football/butler.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+require 'httparty'
+require "football/butler/version"
+require "football/butler/base"
+require "football/butler/configuration"
+require "football/butler/tier"
+require 'football/butler/api'
+require 'football/butler/competitions'
+require 'football/butler/matches'
+require 'football/butler/areas'
+require 'football/butler/teams'
+
+module Football
+  module Butler
+    include Configuration
+    include Tier
+
+    class << self
+      def get(path:, filters: {}, result: :default)
+        Api.get(path: path, filters: filters, result: result)
+      end
+
+      def logger
+        @@logger ||= defined?(Rails) && Rails.logger ? Rails.logger : Logger.new(STDOUT)
+      end
+
+      def logger=(logger)
+        @@logger = logger
+      end
+    end
+  end
+end

data/lib/football/butler/api.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+require 'httparty'
+
+module Football
+  module Butler
+    class Api < Base
+      RETRIES = 2
+
+      class << self
+        def get(path:, filters: {}, result: :default)
+          Configuration.wait_on_limit ?
+            get_with_wait(path: path, filters: filters, result: result) :
+            get_default(path: path, filters: filters, result: result)
+        end
+
+        private
+
+        def get_default(path:, filters: {}, result: :default)
+          return invalid_config_result if invalid_config?
+          response = process_http_party(path, filters)
+          process_response(response, result)
+        end
+
+        def get_with_wait(path:, filters: {}, result: :default)
+          return invalid_config_result if invalid_config?
+
+          if Tier.limit_exceeded?
+            log("Tier.limit_exceeded, sleeping for #{Tier.get_sleep_seconds} seconds now ...")
+            sleep(Tier.get_sleep_seconds) unless Rails.env.test?
+          end
+
+          response = process_http_party(path, filters)
+          Tier.set_from_response_headers(response)
+
+          if reached_limit?(response)
+            response = process_retry(path, filters)
+          end
+
+          process_response(response, result)
+        end
+
+        def process_retry(path, filters)
+          response  = nil
+          retries   = 0
+
+          while retries <= RETRIES
+            retries +=1
+
+            log("Tier.limit_exceeded again (retry #{retries}), sleeping for #{Tier.get_sleep_seconds} seconds now ...")
+            sleep(Tier.get_sleep_seconds) unless Rails.env.test?
+
+            response = process_http_party(path, filters)
+            Tier.set_from_response_headers(response)
+
+            break unless reached_limit?(response)
+          end
+          response
+        end
+
+        def process_http_party(path, filters)
+          headers = {
+            "X-Auth-Token": Configuration.api_token
+          }
+          url   = "#{Configuration.api_endpoint}/#{path}"
+          query = filters || {}
+
+          http_party_get(url, headers, query)
+        end
+
+        def process_response(response, result)
+          if response.dig('message')
+            error_message(response['message'])
+          else
+            case result
+            when :default
+              response
+            else
+              response&.keys&.include?(result.to_s) ? response[result.to_s] : nil
+            end
+          end
+        end
+
+        def http_party_get(url, headers, query)
+          HTTParty.get "#{url}",
+                       headers: headers,
+                       query: query,
+                       format: :json
+        end
+
+        def invalid_config?
+          Configuration.api_token.blank? || Configuration.api_endpoint.blank?
+        end
+
+        def log(text)
+          "\n\nFootball::Butler::VERSION: #{Football::Butler::VERSION} - #{text}\n\n"
+        end
+      end
+    end
+  end
+end

data/lib/football/butler/areas.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Football
+  module Butler
+    class Areas < Base
+      PATH = :areas
+
+      ## AREA
+      # v2/areas/{id}
+      # returns area object directly as a hash
+      def self.by_id(id:)
+        path = "#{PATH}/#{id}"
+        Api.get(path: path)
+      end
+
+      ## AREAS
+      # v2/areas
+      def self.all(result: PATH)
+        Api.get(path: PATH, result: result)
+      end
+
+      ## ADDITIONAL
+      # v2/areas
+      # v2/areas/{id}
+      # returns area object directly as a hash
+      def self.by_name(name:)
+        areas = all
+        return areas if areas.is_a?(Hash) && areas.with_indifferent_access.dig('message')
+        area  = areas&.detect { |area| area['name'] == name }
+        return not_found_result(name) unless area
+
+        by_id(id: area['id'])
+      end
+    end
+  end
+end

data/lib/football/butler/base.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Football
+  module Butler
+    class Base
+      MSG_INVALID_TOKEN   = 'Your API token is invalid.' # 400
+      MSG_NOT_EXIST       = 'The resource you are looking for does not exist' # 404
+      MSG_REACHED_LIMIT   = 'You reached your request limit.' # 429
+      MSG_INVALID_CONFIG  = 'Invalid Configuration, check empty api_token / api_endpoint!'
+
+      class << self
+        # MESSAGES
+        def invalid_token?(response)
+          response.dig('message') ? response['message'] == MSG_INVALID_TOKEN : false
+        end
+
+        def resource_not_found?(response)
+          response.dig('message') ? response['message'] == MSG_NOT_EXIST : false
+        end
+
+        def reached_limit?(response)
+          response.dig('message') ? response['message'].start_with?(MSG_REACHED_LIMIT) : false
+        end
+
+        # CODES
+        def bad_request?(response)
+          response.dig('errorCode') ? response['errorCode'] == 400 : false
+        end
+
+        # RESULT MESSAGES
+        def not_found_result(*params)
+          error_message("#{params.join(', ')} could not be found.")
+        end
+
+        def invalid_config_result
+          error_message(MSG_INVALID_CONFIG)
+        end
+
+        def error_message(error)
+          { message: error }.with_indifferent_access
+        end
+      end
+    end
+  end
+end

data/lib/football/butler/competitions.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Football
+  module Butler
+    class Competitions < Base
+      PATH = :competitions
+
+      ## COMPETITION
+      # v2/competitions/{id}
+      # returns competition object directly as a hash
+      def self.by_id(id:)
+        path = "#{PATH}/#{id}"
+        Api.get(path: path)
+      end
+
+      ## COMPETITIONS
+      #
+      # areas={AREAS}
+      # plan={PLAN}
+      #
+      # v2/competitions
+      def self.all(result: PATH, filters: Configuration.tier_plan_filter)
+        Api.get(path: PATH, result: result, filters: filters)
+      end
+
+      # v2/competitions?plan={plan}
+      def self.by_plan(plan:, result: PATH, filters: {})
+        filters.merge!({ plan: plan })
+        Api.get(path: PATH, result: result, filters: filters)
+      end
+
+      # v2/competitions?areas={id1, id2, ...}
+      def self.by_areas(ids:, result: PATH, filters: {})
+        filters.merge!({ areas: ids.join(',') })
+        Api.get(path: PATH, result: result, filters: filters)
+      end
+
+      ## ADDITIONAL
+      # v2/competitions/{id}
+      def self.current_match_day(id:)
+        response = by_id(id:id)
+
+        if response.is_a?(Hash) && response.dig('message')
+          response
+        else
+          response['currentSeason']['currentMatchday']
+        end
+      end
+
+      # v2/competitions/{id}
+      def self.seasons(id:)
+        response = by_id(id:id)
+
+        if response.is_a?(Hash) && response.dig('message')
+          response
+        else
+          response['seasons']
+        end
+      end
+    end
+  end
+end

data/lib/football/butler/configuration.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Football
+  module Butler
+    module Configuration
+      # API
+      DEFAULT_API_URL       = "https://api.football-data.org"
+
+      DEFAULT_API_TOKEN     = nil
+      DEFAULT_API_VERSION   = 2
+      DEFAULT_API_ENDPOINT  = "#{DEFAULT_API_URL}/v#{DEFAULT_API_VERSION}"
+      
+      # ADDITIONAL
+      DEFAULT_TIER_PLAN     = nil
+      DEFAULT_WAIT_ON_LIMIT = false
+
+      class << self
+        attr_accessor :api_version, :api_token, :api_endpoint, :tier_plan, :wait_on_limit, :init_done
+
+        def configure
+          raise "You need to configure football-butler first, see readme." unless block_given?
+
+          yield self
+
+          @api_token      ||= DEFAULT_API_TOKEN
+          @api_version    ||= DEFAULT_API_VERSION
+          @api_endpoint   ||= DEFAULT_API_ENDPOINT
+          @tier_plan      ||= DEFAULT_TIER_PLAN
+          @wait_on_limit  ||= DEFAULT_WAIT_ON_LIMIT
+
+          @init_done = true
+
+          true
+        end
+
+        def reconfigure(
+          api_token: nil, api_version: nil, api_endpoint: nil, tier_plan: nil, wait_on_limit: nil
+        )
+
+          reset unless @init_done
+
+          @api_token      = api_token unless api_token.nil?
+          unless api_version.nil?
+            @api_version    = api_version
+            @api_endpoint   = "#{DEFAULT_API_URL}/v#{api_version}" if api_endpoint.nil?
+          end
+          @api_endpoint   = api_endpoint unless api_endpoint.nil?
+          @tier_plan      = tier_plan unless tier_plan.nil?
+          @wait_on_limit  = wait_on_limit unless wait_on_limit.nil?
+
+          true
+        end
+
+        def reset
+          @api_version    = DEFAULT_API_VERSION
+          @api_endpoint   = DEFAULT_API_ENDPOINT
+          @tier_plan      = DEFAULT_TIER_PLAN
+          @wait_on_limit  = DEFAULT_WAIT_ON_LIMIT
+
+          @init_done = true
+
+          true
+        end
+
+        # plan = [ TIER_ONE | TIER_TWO | TIER_THREE | TIER_FOUR ]
+        def tier_plan_filter
+          tier_plan.nil? ? {} : { plan: tier_plan }
+        end
+      end
+    end
+  end
+end

data/lib/football/butler/matches.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Football
+  module Butler
+    class Matches < Base
+      PATH              = :matches
+      STATUS_SCHEDULED  = 'SCHEDULED'
+      STATUS_FINISHED   = 'FINISHED'
+
+      ## MATCH
+      # v2/matches/{id}
+      # returns match object directly as a hash
+      def self.by_id(id:)
+        path = "#{PATH}/#{id}"
+        Api.get(path: path)
+      end
+
+      ## MATCHES
+      #
+      # competitions={competitionIds}
+      # dateFrom={DATE}
+      # dateTo={DATE}
+      # status={STATUS}
+      #
+      # /v2/matches
+      def self.all(result: PATH, filters: {})
+        Api.get(path: PATH, result: result, filters: filters)
+      end
+
+      ## by COMPETITION
+      #
+      # dateFrom={DATE}
+      # dateTo={DATE}
+      # stage={STAGE}
+      # status={STATUS}
+      # matchday={MATCHDAY}
+      # group={GROUP}
+      # season={YEAR}
+      #
+      # v2/competitions/{id}/matches
+      def self.by_competition(id:, result: PATH, filters: {})
+        path = "#{Competitions::PATH}/#{id}/#{PATH}"
+        Api.get(path: path, filters: filters, result: result)
+      end
+
+      # v2/competitions/{id}/matches?season={year}
+      def self.by_competition_and_year(id:, year:, result: PATH, filters: {})
+        path = "#{Competitions::PATH}/#{id}/#{PATH}"
+        filters.merge!({ season: year })
+        Api.get(path: path, filters: filters, result: result)
+      end
+
+      # v2/competitions/{id}/matches?matchday={match_day}
+      def self.by_competition_and_match_day(id:, match_day:, result: PATH, filters: {})
+        path = "#{Competitions::PATH}/#{id}/#{PATH}"
+        filters.merge!({ matchday: match_day })
+        Api.get(path: path, filters: filters, result: result)
+      end
+
+      ## by TEAM
+      #
+      # dateFrom={DATE}
+      # dateTo={DATE}
+      # status={STATUS}
+      # venue={VENUE}
+      # limit={LIMIT}
+      #
+      # v2/teams/{id}/matches
+      def self.by_team(id:, result: PATH, filters: {})
+        path = "#{Teams::PATH}/#{id}/#{PATH}"
+        Api.get(path: path, result: result, filters: filters)
+      end
+
+      # v2/teams/{id}/matches?status={status}
+      def self.by_team_and_status(id:, status:, result: PATH, filters: {})
+        path = "#{Teams::PATH}/#{id}/#{PATH}"
+        filters.merge!({ status: status })
+        Api.get(path: path, result: result, filters: filters)
+      end
+
+      # v2/teams/{team}/matches?status=FINISHED
+      def self.by_team_finished(id:, result: PATH, filters: {})
+        by_team_and_status(id: id, status: STATUS_FINISHED, result: result, filters: filters)
+      end
+
+      # v2/teams/{team}/matches?status=SCHEDULED
+      def self.by_team_scheduled(id:, result: PATH, filters: {})
+        by_team_and_status(id: id, status: STATUS_SCHEDULED, result: result, filters: filters)
+      end
+    end
+  end
+end 

data/lib/football/butler/teams.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Football
+  module Butler
+    class Teams < Base
+      PATH = :teams
+
+      ## TEAM
+      # v2/teams/{id}
+      # returns team object directly as a hash
+      def self.by_id(id:)
+        path = "#{PATH}/#{id}"
+        Api.get(path: path)
+      end
+
+      ## COMPETITION
+      #
+      # season={YEAR}
+      # stage={STAGE}
+      #
+      # v2/competitions/{id}/teams
+      def self.by_competition(id:, result: PATH, filters: {})
+        path = "#{Competitions::PATH}/#{id}/#{PATH}"
+        Api.get(path: path, result: result, filters: filters)
+      end
+
+      # v2/competitions/{id}/teams?year={year}
+      def self.by_competition_and_year(id:, year:, result: PATH, filters: {})
+        path = "#{Competitions::PATH}/#{id}/#{PATH}"
+        filters.merge!({ year: year })
+        Api.get(path: path, result: result, filters: filters)
+      end
+    end
+  end
+end

data/lib/football/butler/tier.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Football
+  module Butler
+    module Tier
+      COUNTER_RESET_SAFE_SECONDS = 5
+
+      class << self
+        attr_accessor :available_minute, :counter_reset, :last_request, :total_requests, :sleep_seconds
+
+        def set_from_response_headers(response)
+          if available_minute?(response) && counter_reset?(response)
+            set_tier_from_response(
+              response.headers['x-requests-available-minute'],
+              response.headers['x-requestcounter-reset']
+            )
+          end
+        end
+
+        def set_tier_from_response(available_minute, counter_reset)
+          @available_minute = available_minute.to_i
+          @counter_reset    = counter_reset.to_i
+          @last_request     = Time.current
+
+          @total_requests = @total_requests.is_a?(Integer) ? @total_requests + 1 : 1
+
+          true
+        end
+
+        def available_minute?(response)
+          response&.headers&.dig('x-requests-available-minute')&.present?
+        end
+
+        def counter_reset?(response)
+          response&.headers&.dig('x-requestcounter-reset')&.present?
+        end
+
+        def get_sleep_seconds
+          seconds = @counter_reset.is_a?(Integer) ? @counter_reset : 60
+          result  = COUNTER_RESET_SAFE_SECONDS + seconds
+
+          @sleep_seconds = @sleep_seconds.is_a?(Integer) ?
+                             @sleep_seconds + result : result
+
+          result
+        end
+
+        def limit_exceeded?
+          @available_minute == 0 && @last_request >= 1.minute.ago
+        end
+
+        def reset_total_requests
+          @total_requests = 0
+        end
+
+        def reset_sleep_seconds
+          @sleep_seconds = 0
+        end
+      end
+    end
+  end
+end

data/lib/football/butler/version.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Football
+  module Butler
+    # TIER_ONE initial Version April 2021
+    VERSION = "1.0.0"
+  end
+end

metadata

@@ -0,0 +1,111 @@
+--- !ruby/object:Gem::Specification
+name: football-butler
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Jörg Kirschstein
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2021-04-03 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: byebug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '12.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '12.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: httparty
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.15.7
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.15.7
+description: Get data from https://www.football-data.org
+email:
+- info@joerg-kirschstein.de
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/football/butler.rb
+- lib/football/butler/api.rb
+- lib/football/butler/areas.rb
+- lib/football/butler/base.rb
+- lib/football/butler/competitions.rb
+- lib/football/butler/configuration.rb
+- lib/football/butler/matches.rb
+- lib/football/butler/teams.rb
+- lib/football/butler/tier.rb
+- lib/football/butler/version.rb
+homepage: https://github.com/frontimax/football-butler
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/frontimax/football-butler
+  source_code_uri: https://rubygems.org/gems/football_butler
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.2
+signing_key: 
+specification_version: 4
+summary: Football data via API
+test_files: []