tradingview-screener 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 98dcc60a6b081a91a83d869aa27e5bb214eebc94b12cf6646db98f1a35c4fede
+  data.tar.gz: d9edd2c6cfb433d5a66a41e49d76ff2add1c82e1d4657a63cedfcae7f2a67539
+SHA512:
+  metadata.gz: d4c6d6ca81ff9c6aeaeba7935e64fa154924efae09a40b3e369ea4612b35f9939d7eafaec53a4dec3553e79e5279d653de26f8a13bb67b6931c34e90c3e11631
+  data.tar.gz: 636af5fc960959ee4a172ff7ef9547cebf72cfdf6778c73711795249c644b8930f74bac660c3af5aa1c6f2ca8ff529c49fc7f9796cdcb8b068e89f1f1c6305da

data/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+## 0.2.0
+
+### Changed
+- Gem/package name is `tradingview-screener` (RubyGems hyphen convention); require remains `tradingview_screener`.
+- Extracted into a standalone publishable gem.
+- Removed implicit ActiveSupport dependency (`presence` / `blank?`).
+- Pure Ruby runtime: only stdlib + optional `socksify` for SOCKS proxies.
+- Added a tracked Ruby version for reproducible development with RVM.
+- Added strict gem validation and a Ruby 3.1-3.4 CI test matrix.
+- Clarified Ruby support, unofficial API status, and the release workflow.
+
+### Added
+- ActiveRecord-style `Relation` / `Base` / scopes API.
+- Built-in momentum trend, momentum scalping, and open-range breakout scopes.
+- `ScreenData` parser/converter for saved TradingView screener URLs/HTML.
+- HTTP and SOCKS proxy support on the scanner client.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Victor Yang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,179 @@
+# tradingview-screener
+
+ActiveRecord-style Ruby client for TradingView's scanner API.
+
+Inspired by [shner-elmo/TradingView-Screener](https://github.com/shner-elmo/TradingView-Screener), but designed like Rails ORM relations — not a Python port.
+
+This is an unofficial client and is not affiliated with or endorsed by TradingView. The scanner endpoints are not a guaranteed public API and may change without notice.
+
+Gem name uses hyphens (`tradingview-screener`); the require path and module use underscores:
+
+```ruby
+require "tradingview_screener"
+# also works: require "tradingview/screener"  # Bundler default for hyphen gems
+TradingviewScreener::Stock
+```
+
+If Bundler does not load it automatically, set:
+
+```ruby
+gem "tradingview-screener", require: "tradingview_screener"
+```
+
+## Install
+
+Ruby 3.1 or newer is required.
+
+### From a local path
+
+```ruby
+# Gemfile
+gem "tradingview-screener", path: "../tradingview-screener"
+```
+
+### From RubyGems
+
+```ruby
+# Gemfile
+gem "tradingview-screener", "~> 0.2"
+```
+
+```bash
+gem install tradingview-screener
+```
+
+SOCKS proxies are optional. If you need them:
+
+```ruby
+gem "socksify", "~> 1.7"
+```
+
+## Quick start
+
+```ruby
+require "tradingview_screener"
+
+rows = TradingviewScreener::Stock
+  .where(close: 10..300)
+  .where(volume: TradingviewScreener::Predicates.gt(1_000_000))
+  .where(TradingviewScreener::Stock[:close].gt(TradingviewScreener::Stock[:SMA20]))
+  .order(volume: :desc)
+  .limit(20)
+  .to_a
+
+rows.first["ticker"]  # => "NASDAQ:NVDA"
+```
+
+## ORM-shaped API
+
+| ActiveRecord | tradingview-screener |
+|---|---|
+| `Model.where(a: 1)` | `Stock.where(is_primary: true)` |
+| `where(price: 10..20)` | `where(close: 10..300)` |
+| `where(status: %w[a b])` | `where(type: %w[stock fund])` |
+| `order(created_at: :desc)` | `order(premarket_volume: :desc)` |
+| `limit` / `offset` | same |
+| `select(:id, :name)` | `select("name", "close")` |
+| `scope :active, -> { ... }` | same |
+| `default_scope` | same |
+| `all` / `to_a` / `count` / `pluck` / `first` | same |
+| relation is immutable chain | same |
+
+### Operators
+
+```ruby
+where(volume: TradingviewScreener::Predicates.gt(1_000_000))
+where(market_cap_basic: TradingviewScreener::Predicates.gte(1_000_000_000))
+where(ATRP: TradingviewScreener::Predicates.lt(6))
+
+# Arel-like nodes
+where(TradingviewScreener::Stock[:close].gt(TradingviewScreener::Stock[:SMA20]))
+where(TradingviewScreener::Stock[:typespecs].has(["common"]))
+```
+
+### Scopes
+
+```ruby
+class MyScreen < TradingviewScreener::Base
+  market "america"
+  default_scope { where(is_primary: true) }
+
+  scope :liquid, -> {
+    where("AvgValue.Traded_10d" => TradingviewScreener::Predicates.gt(50_000_000))
+  }
+  scope :wide_atr, -> {
+    where(ATRP: TradingviewScreener::Predicates.gt(1))
+      .where(ATRP: TradingviewScreener::Predicates.lt(6))
+  }
+end
+
+MyScreen.liquid.wide_atr.order(volume: :desc).limit(50).load
+```
+
+### Built-in momentum scopes
+
+```ruby
+TradingviewScreener::Stock.momentum_trend_long.to_a
+TradingviewScreener::Stock.momentum_trend_short.ids
+TradingviewScreener::Stock.momentum_scalping_long.to_a
+TradingviewScreener::Stock.open_range_breakout_short.ids
+```
+
+### Saved screener URL / screen_data
+
+```ruby
+rel = TradingviewScreener::Stock.from_screener_url(
+  "https://www.tradingview.com/screener/YOUR_SCREEN_ID/",
+  cookies: {
+    "sessionid" => ENV.fetch("TRADINGVIEW_SESSIONID"),
+    "sessionid_sign" => ENV.fetch("TRADINGVIEW_SESSIONID_SIGN")
+  }
+)
+rel.to_a
+```
+
+### Cookies / proxy
+
+```ruby
+TradingviewScreener::Stock.momentum_trend_long.load(
+  cookies: {
+    "sessionid" => ENV.fetch("TRADINGVIEW_SESSIONID"),
+    "sessionid_sign" => ENV.fetch("TRADINGVIEW_SESSIONID_SIGN")
+  },
+  proxy: "http://user:pass@127.0.0.1:7890"
+)
+```
+
+## Debugging
+
+```ruby
+rel = TradingviewScreener::Stock
+  .where(TradingviewScreener::Stock[:close].gt(TradingviewScreener::Stock[:SMA20]))
+  .limit(10)
+
+puts rel.to_sql      # JSON payload sent to scanner
+puts rel.scanner_url
+```
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rake build   # => pkg/tradingview-screener-0.2.0.gem
+gem build tradingview-screener.gemspec --strict
+```
+
+Before publishing, verify that the version is not already in use and inspect the package:
+
+```bash
+gem build tradingview-screener.gemspec --strict
+gem contents --show-install-dir tradingview-screener # after installing the built gem
+gem push tradingview-screener-0.2.0.gem
+```
+
+RubyGems MFA is required for releases. Source code and issue tracking are available on [GitHub](https://github.com/Youngv/tradingview-screener).
+
+## License
+
+MIT

data/lib/tradingview/screener.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+# Bundler/RubyGems map gem "tradingview-screener" to require "tradingview/screener".
+require_relative "../tradingview_screener"

data/lib/tradingview_screener/base.rb

@@ -0,0 +1,291 @@
+# frozen_string_literal: true
+
+module TradingviewScreener
+  # ActiveRecord-style model base.
+  #
+  #   class Stock < TradingviewScreener::Base
+  #     market "america"
+  #     default_scope { where(is_primary: true) }
+  #     scope :liquid, -> { where(volume: gt(1_000_000)) }
+  #   end
+  #
+  #   Stock.liquid.where(close: 10..300).order(volume: :desc).limit(20).load
+  class Base
+    class << self
+      def inherited(subclass)
+        super
+        subclass.instance_variable_set(:@scopes, {})
+        subclass.instance_variable_set(:@default_scopes, [])
+      end
+
+      def market(name = nil)
+        if name.nil?
+          @default_market
+        else
+          @default_market = name.to_s
+        end
+      end
+      alias default_market market
+
+      def columns(*names)
+        if names.empty?
+          @default_columns
+        else
+          @default_columns = names.flatten.map(&:to_s)
+        end
+      end
+      alias default_columns columns
+
+      def default_limit(value = nil)
+        if value.nil?
+          @default_limit
+        else
+          @default_limit = Integer(value)
+        end
+      end
+
+      def default_order_values
+        @default_order
+      end
+      alias default_order default_order_values
+
+      def order_by(column, direction = :desc)
+        @default_order = [{ "sortBy" => column.to_s, "sortOrder" => direction.to_s == "asc" ? "asc" : "desc" }]
+      end
+
+      def default_where
+        @default_where
+      end
+
+      def default_filter2
+        @default_filter2
+      end
+
+      def filter2(value)
+        @default_filter2 = value
+      end
+
+      def scope(name, body = nil, &block)
+        callable = body || block
+        raise ArgumentError, "scope needs a callable" unless callable
+
+        scopes[name.to_sym] = callable
+        define_singleton_method(name) do |*args, **kwargs|
+          rel = all
+          result =
+            if callable.arity.nonzero? || kwargs.any?
+              rel.instance_exec(*args, **kwargs, &callable)
+            else
+              rel.instance_exec(&callable)
+            end
+          result.nil? ? none : result
+        end
+      end
+
+      def default_scope(body = nil, &block)
+        callable = body || block
+        raise ArgumentError, "default_scope needs a callable" unless callable
+
+        default_scopes << callable
+      end
+
+      def all
+        rel = Relation.new(self)
+        default_scopes.reduce(rel) do |memo, callable|
+          result = memo.instance_exec(&callable)
+          result.nil? ? memo : result
+        end
+      end
+
+      def none
+        all.none
+      end
+
+      def where(...) = all.where(...)
+      def rewhere(...) = all.rewhere(...)
+      def select(...) = all.select(...)
+      def order(...) = all.order(...)
+      def limit(...) = all.limit(...)
+      def offset(...) = all.offset(...)
+      def market!(...) = all.market(...)
+      def tickers(...) = all.tickers(...)
+      def merge(...) = all.merge(...)
+      def except(...) = all.except(...)
+      def load(**kwargs) = all.load(**kwargs)
+      def to_a(**kwargs) = all.to_a(**kwargs)
+      def count(**kwargs) = all.count(**kwargs)
+      def first(...) = all.first(...)
+      def last(...) = all.last(...)
+      def pluck(...) = all.pluck(...)
+      def pick(...) = all.pick(...)
+      def ids(**kwargs) = all.ids(**kwargs)
+      def exists?(**kwargs) = all.exists?(**kwargs)
+      def find_each(**opts, &block) = all.to_a(**opts).each(&block)
+
+      def [](name)
+        Field.new(name)
+      end
+
+      def unscoped
+        Relation.new(self)
+      end
+
+      def from_payload(payload)
+        Relation.from_payload(self, payload)
+      end
+
+      def from_screen_data(screen_data)
+        from_payload(ScreenData.to_payload(screen_data))
+      end
+
+      def from_screener_url(url, cookies: nil, proxy: nil, timeout: 20)
+        fetched = ScreenData.fetch(url, cookies: cookies, proxy: proxy, timeout: timeout)
+        from_payload(fetched["payload"])
+      end
+
+      protected
+
+      def scopes
+        @scopes ||= {}
+      end
+
+      def default_scopes
+        @default_scopes ||= []
+      end
+    end
+  end
+
+  # Convenience root model for US equities.
+  class Stock < Base
+    market "america"
+    order_by "market_cap_basic", :desc
+    default_limit 50
+
+    default_scope do
+      where(is_primary: true)
+    end
+
+    scope :primary, -> { where(is_primary: true) }
+
+    scope :priced_between, lambda { |min, max|
+      where(close: min..max)
+    }
+
+    # Captured from live MT LONG / MT SHORT TradingView screeners.
+    scope :momentum_trend_long, lambda {
+      select(
+        "ticker-view", "close", "type", "typespecs", "pricescale", "minmov", "fractional", "minmove2",
+        "currency", "change", "volume", "relative_volume_10d_calc", "market_cap_basic",
+        "fundamental_currency_code", "price_earnings_ttm", "earnings_per_share_diluted_ttm",
+        "earnings_per_share_diluted_yoy_growth_ttm", "dividends_yield_current", "sector.tr",
+        "market", "sector", "AnalystRating", "AnalystRating.tr", "premarket_change", "premarket_volume"
+      ).where(
+        "AvgValue.Traded_10d" => gt(50_000_000),
+        ATRP: gt(1)
+      ).where(
+        market_cap_basic: gte(1_000_000_000),
+        premarket_volume: gt(30_000),
+        "relative_volume_intraday|5" => gt(1.1),
+        ATRP: lt(6),
+        close: 10..300
+      ).where(
+        TradingviewScreener::Stock[:close].gt(TradingviewScreener::Stock[:SMA20])
+      ).order(premarket_volume: :desc).limit(100)
+    }
+
+    scope :momentum_trend_short, lambda {
+      select(
+        "ticker-view", "close", "type", "typespecs", "pricescale", "minmov", "fractional", "minmove2",
+        "currency", "change", "volume", "relative_volume_10d_calc", "market_cap_basic",
+        "fundamental_currency_code", "price_earnings_ttm", "earnings_per_share_diluted_ttm",
+        "earnings_per_share_diluted_yoy_growth_ttm", "dividends_yield_current", "sector.tr",
+        "market", "sector", "AnalystRating", "AnalystRating.tr", "premarket_change", "premarket_volume"
+      ).where(
+        TradingviewScreener::Stock[:close].lt(TradingviewScreener::Stock[:SMA20]),
+        "relative_volume_intraday|5" => gt(1.1),
+        premarket_volume: gt(30_000),
+        ATRP: lt(6)
+      ).where(
+        ATRP: gt(1),
+        "AvgValue.Traded_10d" => gt(50_000_000),
+        market_cap_basic: gte(1_000_000_000),
+        close: 10..300
+      ).order(market_cap_basic: :desc).limit(100)
+    }
+
+    # Captured from live MS LONG / MS SHORT TradingView screeners.
+    scope :momentum_scalping_long, lambda {
+      select(
+        "ticker-view", "close", "type", "typespecs", "pricescale", "minmov", "fractional", "minmove2",
+        "currency", "change", "volume", "relative_volume_10d_calc", "market_cap_basic",
+        "fundamental_currency_code", "price_earnings_ttm", "earnings_per_share_diluted_ttm",
+        "earnings_per_share_diluted_yoy_growth_ttm", "dividends_yield_current", "sector.tr",
+        "market", "sector", "AnalystRating", "AnalystRating.tr", "premarket_change", "premarket_volume"
+      ).where(
+        close: 10..300,
+        "relative_volume_intraday|5" => gt(1.1),
+        ATRP: lt(6),
+        market_cap_basic: gte(1_000_000_000),
+        premarket_gap: gt(0.5),
+        premarket_volume: gt(30_000)
+      ).where(
+        premarket_gap: lt(8),
+        ATRP: gt(1)
+      ).order(premarket_volume: :desc).limit(100)
+    }
+
+    scope :momentum_scalping_short, lambda {
+      select(
+        "ticker-view", "close", "type", "typespecs", "pricescale", "minmov", "fractional", "minmove2",
+        "currency", "change", "volume", "relative_volume_10d_calc", "market_cap_basic",
+        "fundamental_currency_code", "price_earnings_ttm", "earnings_per_share_diluted_ttm",
+        "earnings_per_share_diluted_yoy_growth_ttm", "dividends_yield_current", "sector.tr",
+        "market", "sector", "AnalystRating", "AnalystRating.tr", "premarket_change", "premarket_volume"
+      ).where(
+        premarket_gap: gt(-8),
+        market_cap_basic: gte(1_000_000_000)
+      ).where(
+        ATRP: gt(1)
+      ).where(
+        ATRP: lt(6),
+        premarket_volume: gt(30_000),
+        "relative_volume_intraday|5" => gt(1.1),
+        premarket_gap: lt(-0.5),
+        close: 10..300
+      ).order(premarket_volume: :desc).limit(100)
+    }
+
+    # Captured from live ORB LONG / ORB SHORT TradingView screeners.
+    scope :open_range_breakout_long, lambda {
+      select(
+        "ticker-view", "close", "type", "typespecs", "pricescale", "minmov", "fractional", "minmove2",
+        "currency", "change", "volume", "relative_volume_10d_calc", "market_cap_basic",
+        "fundamental_currency_code", "price_earnings_ttm", "earnings_per_share_diluted_ttm",
+        "earnings_per_share_diluted_yoy_growth_ttm", "dividends_yield_current", "sector.tr",
+        "market", "sector", "AnalystRating", "AnalystRating.tr"
+      ).where(
+        market_cap_basic: gte(1_000_000_000),
+        average_volume_10d_calc: gt(3_000_000),
+        close: 10..300,
+        ATRP: gt(5),
+        premarket_gap: gt(2)
+      ).order(market_cap_basic: :desc).limit(100)
+    }
+
+    scope :open_range_breakout_short, lambda {
+      select(
+        "ticker-view", "close", "type", "typespecs", "pricescale", "minmov", "fractional", "minmove2",
+        "currency", "change", "volume", "relative_volume_10d_calc", "market_cap_basic",
+        "fundamental_currency_code", "price_earnings_ttm", "earnings_per_share_diluted_ttm",
+        "earnings_per_share_diluted_yoy_growth_ttm", "dividends_yield_current", "sector.tr",
+        "market", "sector", "AnalystRating", "AnalystRating.tr"
+      ).where(
+        close: 10..300,
+        premarket_gap: lt(-3),
+        average_volume_10d_calc: gt(3_000_000),
+        ATRP: gt(5),
+        market_cap_basic: gte(1_000_000_000)
+      ).order(market_cap_basic: :desc).limit(100)
+    }
+  end
+end