RubyGems - twelvedata_ruby - Versions diffs - 0.1.1 - Mend

twelvedata_ruby 0.1.1

Files changed (54) hide show

checksums.yaml +7 -0
data/.gitignore +13 -0
data/CHANGELOG.md +5 -0
data/CODE_OF_CONDUCT.md +84 -0
data/Gemfile +6 -0
data/Gemfile.lock +80 -0
data/LICENSE.txt +21 -0
data/README.md +125 -0
data/Rakefile +12 -0
data/bin/console +22 -0
data/bin/setup +8 -0
data/doc/TwelvedataRuby.html +353 -0
data/doc/TwelvedataRuby/BadRequestResponseError.html +178 -0
data/doc/TwelvedataRuby/Client.html +1443 -0
data/doc/TwelvedataRuby/Endpoint.html +1478 -0
data/doc/TwelvedataRuby/EndpointError.html +247 -0
data/doc/TwelvedataRuby/EndpointNameError.html +167 -0
data/doc/TwelvedataRuby/EndpointParametersKeysError.html +167 -0
data/doc/TwelvedataRuby/EndpointRequiredParametersError.html +167 -0
data/doc/TwelvedataRuby/Error.html +318 -0
data/doc/TwelvedataRuby/ForbiddenResponseError.html +178 -0
data/doc/TwelvedataRuby/InternalServerResponseErro.html +178 -0
data/doc/TwelvedataRuby/NotFoundResponseError.html +178 -0
data/doc/TwelvedataRuby/PageNotFoundResponseError.html +178 -0
data/doc/TwelvedataRuby/ParameterTooLongResponseError.html +178 -0
data/doc/TwelvedataRuby/Request.html +683 -0
data/doc/TwelvedataRuby/Response.html +1622 -0
data/doc/TwelvedataRuby/ResponseError.html +565 -0
data/doc/TwelvedataRuby/TooManyRequestsResponseError.html +178 -0
data/doc/TwelvedataRuby/UnauthorizedResponseError.html +178 -0
data/doc/TwelvedataRuby/Utils.html +503 -0
data/doc/_index.html +315 -0
data/doc/class_list.html +51 -0
data/doc/css/common.css +1 -0
data/doc/css/full_list.css +58 -0
data/doc/css/style.css +497 -0
data/doc/file.README.html +194 -0
data/doc/file_list.html +56 -0
data/doc/frames.html +17 -0
data/doc/index.html +194 -0
data/doc/js/app.js +314 -0
data/doc/js/full_list.js +216 -0
data/doc/js/jquery.js +4 -0
data/doc/method_list.html +707 -0
data/doc/top-level-namespace.html +110 -0
data/lib/twelvedata_ruby.rb +43 -0
data/lib/twelvedata_ruby/client.rb +148 -0
data/lib/twelvedata_ruby/endpoint.rb +271 -0
data/lib/twelvedata_ruby/error.rb +90 -0
data/lib/twelvedata_ruby/request.rb +54 -0
data/lib/twelvedata_ruby/response.rb +132 -0
data/lib/twelvedata_ruby/utils.rb +36 -0
data/twelvedata_ruby.gemspec +37 -0
metadata +201 -0

data/doc/top-level-namespace.html ADDED Viewed

@@ -0,0 +1,110 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>
+  Top Level Namespace
+    &mdash; Documentation by YARD 0.9.26
+</title>
+  <link rel="stylesheet" href="css/style.css" type="text/css" />
+  <link rel="stylesheet" href="css/common.css" type="text/css" />
+<script type="text/javascript">
+  pathId = "";
+  relpath = '';
+</script>
+  <script type="text/javascript" charset="utf-8" src="js/jquery.js"></script>
+  <script type="text/javascript" charset="utf-8" src="js/app.js"></script>
+  </head>
+  <body>
+    <div class="nav_wrap">
+      <iframe id="nav" src="class_list.html?1"></iframe>
+      <div id="resizer"></div>
+    </div>
+    <div id="main" tabindex="-1">
+      <div id="header">
+        <div id="menu">
+    <a href="_index.html">Index</a> &raquo;
+    <span class="title">Top Level Namespace</span>
+</div>
+        <div id="search">
+    <a class="full_list_link" id="class_list_link"
+        href="class_list.html">
+        <svg width="24" height="24">
+          <rect x="0" y="4" width="24" height="4" rx="1" ry="1"></rect>
+          <rect x="0" y="12" width="24" height="4" rx="1" ry="1"></rect>
+          <rect x="0" y="20" width="24" height="4" rx="1" ry="1"></rect>
+        </svg>
+    </a>
+</div>
+        <div class="clear"></div>
+      </div>
+      <div id="content"><h1>Top Level Namespace
+</h1>
+<div class="box_info">
+</div>
+<h2>Defined Under Namespace</h2>
+<p class="children">
+      <strong class="modules">Modules:</strong> <span class='object_link'><a href="TwelvedataRuby.html" title="TwelvedataRuby (module)">TwelvedataRuby</a></span>
+</p>
+</div>
+      <div id="footer">
+  Generated on Tue Jul 13 08:56:46 2021 by
+  <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
+  0.9.26 (ruby-3.0.1).
+</div>
+    </div>
+  </body>
+</html>

data/lib/twelvedata_ruby.rb ADDED Viewed

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+require_relative "twelvedata_ruby/utils"
+require_relative "twelvedata_ruby/error"
+require_relative "twelvedata_ruby/endpoint"
+require_relative "twelvedata_ruby/request"
+require_relative "twelvedata_ruby/response"
+require_relative "twelvedata_ruby/client"
+# The one module that all the classes and modules of this gem are namespaced
+module TwelvedataRuby
+  # Holds the current version
+  # @return [String] version number
+  VERSION = "0.1.1"
+  # A convenient and clearer way of getting and overriding default attribute values of the singleton `Client.instance`
+  #
+  # @param [Hash] options the optional Hash object that may contain values to override the defaults
+  # @option options [Symbol, String] :apikey the private key from Twelvedata API key
+  # @option options [Integer, String] :connect_timeout milliseconds
+  #
+  #  @example Passing a nil options
+  #    TwelvedataRuby.client
+  #
+  #  The singleton instance  object returned will use the default values  for its attributes
+  #
+  #  @example Passing values of `:apikey` and `:connect_timeout`
+  #    TwelvedataRuby.client(apikey: "my-twelvedata-apikey", connect_timeout: 3000)
+  #
+  #  @example or, chain with other Client instance method
+  #    TwelvedataRuby.client(apikey: "my-twelvedata-apikey", connect_timeout: 3000).quote(symbol: "IBM")
+  #
+  #  In the last example, calling `#quote`, a valid API endpoint, an instance method with the same name
+  #  was dynamically defined and then fired up an API request to Twelvedata.
+  #
+  # @return [Client] singleton instance
+  def self.client(**options)
+    client = Client.instance
+    client.options = (client.options || {}).merge(options)
+    client
+  end
+end

data/lib/twelvedata_ruby/client.rb ADDED Viewed

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+require "httpx"
+require "singleton"
+module TwelvedataRuby
+  # Responsible of the actual communication -- sending a valid request
+  #   and receiving the response  -- of the API web server
+  class Client
+    include Singleton
+    # @return [String] the exported shell ENV variable name that holds the apikey
+    APIKEY_ENV_NAME = "TWELVEDATA_API_KEY"
+    # @return [Integer] CONNECT_TIMEOUT default connection timeout in milliseconds
+    CONNECT_TIMEOUT = 120
+    # @return [String] valid URI base url string of the API
+    BASE_URL = "https://api.twelvedata.com"
+    class << self
+      def request(request_objects, opts={})
+        HTTPX.with(options.merge(opts)).request(build_requests(request_objects))
+      end
+      def build_requests(requests)
+        Utils.to_a(requests).map(&:build)
+      end
+      def origin
+        @origin ||= {origin: BASE_URL}
+      end
+      def timeout
+        {timeout: {connect_timeout: instance.connect_timeout}}
+      end
+      def options
+        origin.merge(timeout)
+      end
+    end
+    # @!attribute options
+    #   @return [Hash] the options writeonly attribute that may contain values to override the default attribute values.
+    #     This attribute writer was automatically called in @see TwelvedataRuby.client(**options).
+    # @see TwelvedataRuby.client
+    attr_writer :options
+    # @return [String] apikey value from the instance options Hash object
+    #   but if nill use the value from +ENV[APIKEY_ENV_NAME]+
+    def apikey
+      Utils.empty_to_nil(options[:apikey]) || ENV[apikey_env_var_name]
+    end
+    # The writer method that can be used to pass manually the value of the +apikey+
+    # @param [String] apikey
+    # @return [String] +apikey+ value
+    def apikey=(apikey)
+      options[:apikey] = apikey
+    end
+    def connect_timeout
+      parse_connect_timeout(options[:connect_timeout])
+    end
+    def connect_timeout=(connect_timeout)
+      parse_connect_timeout(connect_timeout)
+    end
+    # The name of the ENVIRONMENT variable that may hold the value of the Twelve Data API key
+    # # @return [String] the ENV variable that will be used to fetch from ENV the value of the API  key
+    def apikey_env_var_name
+      (options[:apikey_env_var_name] || APIKEY_ENV_NAME).upcase
+    end
+    # A setter helper method to configure the ENV variable name of the API key
+    # @param [String] apikey_env_var_name
+    # @return [String] the ENV variable name
+    # @see #apikey_env_var_name
+    def apikey_env_var_name=(apikey_env_var_name)
+      options[:apikey_env_var_name] = apikey_env_var_name
+    end
+    # The actual API fetch that transport the built request object.
+    # +Request#valid?+ guards the actual fetch and instead will return a Hash instance of endpoint errors.
+    # If +Request#valid?+ returns true, request object will be sent to the API and returned response will
+    # will be resolved which may or may not contain a kind of +ResponseError+ instance.
+    # @see Response.resolve for more details
+    # @param [Request] request built API request object that holds the endpoint payload
+    #
+    # @return [NilClass] +nil+ if @param +request+ is not truthy
+    # @return [Hash] :errors if the request is not valid will hold the  endpoint errors details
+    #   @see Endpoint#errors
+    # @return [Response] if +request+ is valid and received an actual response from the API server.
+    #   The response object's #error may or may not return a kind of ResponseError
+    #   @see Response#error
+    # @return [ResponseError] if the response received did not come from the API server itself.
+    #
+    def fetch(request)
+      return nil unless request
+      request.valid? ? Response.resolve(self.class.request(request), request) : {errors: request.errors}
+    end
+    # The entry point in dynamically defining instance methods based on the called the valid endpoint names.
+    # @param [String] endpoint_name valid API endpoint name to fetch
+    # @param [Hash] endpoint_params the optional/required valid query params of the API endpoint.
+    #   If +:apikey+ key-value pair is present, the pair will override the +#apikey+ of singleton client instance
+    #   If +:format+ key-value pair is present and is a valid parameter key and value can only be +:csv+ or +:json+
+    #   If +:filename+ key-value is present and +:format+ is +:csv+, then this is will be added to the payload too.
+    #      Otherwise, this will just discarded and will not be part of the payload
+    #   If endpoint name and query params used are not valid, EndpointError instances will be returned
+    #     actual API fetch will not happen. @see #fetch for the rest of the documentation
+    #
+    # @todo define all the method signatures of the endpoint methods that will meta-programatically defined at runtime.
+    def method_missing(endpoint_name, **endpoint_params, &_block)
+      try_fetch(endpoint_name, endpoint_params) || super
+    end
+    def options
+      @options || @options = {}
+    end
+    def respond_to_missing?(endpoint_name, _include_all=false)
+      Utils.return_nil_unless_true(Endpoint.valid_name?(endpoint_name)) {
+        define_endpoint_method(endpoint_name)
+      } || super
+    end
+    private
+    def build_request(endpoint_name, endpoint_params)
+      Request.new(endpoint_name, **endpoint_params)
+    end
+    def try_fetch(endpoint_name, endpoint_params)
+      respond_to?(endpoint_name) ? fetch(build_request(endpoint_name, endpoint_params)) : nil
+    end
+    def define_endpoint_method(endpoint_name)
+      self.class.define_method(endpoint_name) do |**qparams|
+        fetch(build_request(__method__, qparams))
+      end
+    end
+    def parse_connect_timeout(milliseconds)
+      options[:connect_timeout] = Utils.to_d(milliseconds, CONNECT_TIMEOUT)
+    end
+  end
+end

data/lib/twelvedata_ruby/endpoint.rb ADDED Viewed

@@ -0,0 +1,271 @@
+# frozen_string_literal: true
+module TwelvedataRuby
+  class Endpoint
+    DEFAULT_FORMAT = :json
+    VALID_FORMATS = [DEFAULT_FORMAT, :csv].freeze
+    DEFINITIONS = {
+      api_usage: {
+        parameters: {keys: %i[format]},
+        response: {keys: %i[timestamp current_usage plan_limit]}
+      },
+      stocks: {
+        parameters: {keys: %i[symbol exchange country type format]},
+        response: {data_keys: %i[symbol name currency exchange country type], collection: :data}
+      },
+      forex_pairs: {
+        parameters: {keys: %i[symbol currency_base currency_quote format]},
+        response: {data_keys: %i[symbol currency_group currency_base currency_quote], collection: :data}
+      },
+      cryptocurrencies: {
+        parameters: {keys: %i[symbol exchange currency_base currency_quote format]},
+        response: {data_keys: %i[symbol available_exchanges currency_base currency_quote], collection: :data}
+      },
+      etf: {
+        parameters: {keys: %i[symbol format]},
+        response: {data_keys: %i[symbol name currency exchange], collection: :data}
+      },
+      indices: {
+        parameters: {keys: %i[symbol country format]},
+        response: {data_keys: %i[symbol name country currency], collection: :data}
+      },
+      exchanges: {
+        parameters: {keys: %i[type name code country format]},
+        response: {data_keys: %i[name country code timezone], collection: :data}
+      },
+      cryptocurrency_exchanges: {
+        parameters: {keys: %i[name format]},
+        response: {data_keys: %i[name], collection: :data}
+      },
+      technical_indicators: {
+        parameters: {keys: []},
+        response: {
+          keys: %i[enable full_name description type overlay parameters output_values tinting]
+        }
+      },
+      symbol_search: {
+        parameters: {keys: %i[symbol outputsize], required: %i[symbol]},
+        response: {
+          data_keys: %i[symbol instrument_name exchange exchange_timezone instrument_type country],
+          collection: :data
+        }
+      },
+      earliest_timestamp: {
+        parameters: {keys: %i[symbol interval exchange]},
+        response: {keys: %i[datetime unix_time]}
+      },
+      time_series: {
+        parameters: {
+          keys: %i[symbol interval exchange country type outputsize format],
+          required: %i[symbol interval]
+        },
+        response: {
+          value_keys: %i[datetime open high low close volume],
+          collection: :values,
+          meta_keys: %i[symbol interval currency exchange_timezone exchange type]
+        }
+      },
+      quote: {
+        parameters: {
+          keys: %i[symbol interval exchange country volume_time_period type format],
+          required: %i[symbol],
+        },
+        response: {
+          keys: %i[
+            symbol
+            name
+            exchange
+            currency
+            datetime
+            open
+            high
+            low
+            close
+            volume
+            previous_close
+            change
+            percent_change
+            average_volume
+            fifty_two_week
+          ]
+        }
+      },
+      price: {
+        parameters: {keys: %i[symbol exchange country type format], required: %i[symbol]},
+        response: {keys: %i[price]}
+      },
+      eod: {
+        parameters: {keys: %i[symbol exchange country type], required: %i[symbol]},
+        response: {keys: %i[symbol exchange currency datetime close]}
+      },
+      exchange_rate: {
+        parameters: {keys: %i[symbol format], required: %i[symbol]},
+        response: {keys: %i[symbol rate timestamp]}
+      },
+      currency_conversion: {
+        parameters: {keys: %i[symbol amount format], required: %i[symbol amount]},
+        response: {keys: %i[symbol rate amount timestamp]}
+      },
+      complex_data: {
+        parameters: {
+          keys: %i[symbols intervals start_date end_date dp order timezone methods name],
+          required: %i[symbols intervals start_date end_date]
+        },
+        response: {keys: %i[data status]},
+        http_verb: :post
+      },
+      earnings: {
+        parameters: {keys: %i[symbol exchange country type period outputsize format], required: %i[symbol]},
+        response: {keys: %i[date time eps_estimate eps_actual difference surprise_prc]}
+      },
+      earnings_calendar: {
+        parameters: {keys: %i[format]},
+        response: {
+          keys: %i[
+            symbol
+            name
+            currency
+            exchange
+            country
+            time
+            eps_estimate
+            eps_estimate
+            eps_actual
+            difference
+            surprise_prc
+          ]
+        }
+      }
+    }.freeze
+    class << self
+      def definitions
+        @definitions ||= DEFINITIONS.transform_values {|v|
+          v.merge(
+            parameters: {
+              keys: v[:parameters][:keys].push(:apikey),
+              required: (v[:parameters][:required] || []).push(:apikey)
+            }
+          )
+        }.to_h
+      end
+      def names
+        @names ||= definitions.keys
+      end
+      def default_apikey_params
+        {apikey: Client.instance.apikey}
+      end
+      def valid_name?(name)
+        names.include?(name.to_sym)
+      end
+      def valid_params?(name, **params)
+        new(name, **params).valid?
+      end
+      alias valid? valid_params?
+    end
+    attr_reader :name, :query_params
+    def initialize(name, **query_params)
+      self.name = name
+      self.query_params = query_params
+    end
+    def definition
+      @definition ||= self.class.definitions[name]
+    end
+    def errors
+      (@errors || {}).compact
+    end
+    def name=(name)
+      assign_attribute(:name, name.to_s.downcase.to_sym)
+    end
+    def parameters
+      return @parameters if definition.nil? || @parameters
+      params = definition[:parameters]
+      params.push(:filename) if params.include?(:format) && query_parameters[:format] == :csv
+      params
+    end
+    def parameters_keys
+      keys = parameters&.send(:[], :keys)
+      keys.push(:filename) if keys && query_params && query_params[:format] == :csv
+      keys
+    end
+    def query_params_keys
+      query_params.keys
+    end
+    def query_params=(query_params)
+      if (parameters_keys || []).include?(:format) &&
+          !VALID_FORMATS.include?(query_params[:format])
+        query_params[:format] = DEFAULT_FORMAT
+      end
+      query_params.delete(:filename) if query_params[:filename] && query_params[:format] != :csv
+      assign_attribute(:query_params, self.class.default_apikey_params.merge(query_params.compact))
+    end
+    def required_parameters
+      parameters&.send(:[], :required)
+    end
+    def valid?
+      valid_name? && valid_query_params?
+    end
+    def valid_at_attributes?(*attrs)
+      errors.values_at(*attrs).compact.empty?
+    end
+    def valid_name?
+      valid_at_attributes?(:name)
+    end
+    def valid_query_params?
+      valid_at_attributes?(:parameters_keys, :required_parameters)
+    end
+    private
+    def assign_attribute(attr_name, value)
+      @parameters = nil
+      @definition = nil
+      instance_variable_set(:"@#{attr_name}", value)
+      send(:"validate_#{attr_name}")
+      send(attr_name)
+    end
+    def init_error(attr_name, invalid_values, error_klass=nil)
+      error_klass ||= Kernel.const_get("#{self.class.name}#{Utils.camelize(attr_name)}Error")
+      error_klass.new(endpoint: self, invalid: invalid_values)
+    end
+    def update_errors(attrib, invalids, klass=nil)
+      @errors = errors.merge(attrib => !invalids.nil? && !invalids.empty? ? init_error(attrib, invalids, klass) : nil)
+    end
+    def validate_name
+      is_valid = self.class.valid_name?(name)
+      invalid_name = name.nil? || name.empty? ? "a blank name" : name
+      update_errors(:name, is_valid ? nil : invalid_name)
+      validate_query_params if is_valid && query_params && !valid_query_params?
+    end
+    def validate_query_params
+      return update_errors(:required_parameters, "Invalid name", EndpointError) unless parameters_keys
+      update_errors(:required_parameters, required_parameters.difference(query_params_keys))
+      update_errors(:parameters_keys, query_params_keys.difference(parameters_keys))
+    end
+  end
+end