rsteamshot 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 90dfdeeddcdf96528bc802b870093361da7f2822
-  data.tar.gz: 45521a0f3db408209f9c15328034b49fbb3bb8bd
+  metadata.gz: d404603632e6df914e39a96d01b81da6f04dee91
+  data.tar.gz: e19e08b0e3270260f5a546b2eb5fbee44401478c
 SHA512:
-  metadata.gz: 3404ffe22ae4de7ed6f02683e6615d08ee6aab41de51d06e7b6b05f1d2b8ec56ea83c7ab9cd4a01c15bad012db26eb875dcd4cbdd4f26a0481756f2316c62285
-  data.tar.gz: 8e207fd127e0b851917c5be2ce3ea062018af5d502d362a5b12d2a78e13e3bf01b80ed01b4d45cd2895ec9ee2516e03e15660db0a58f4e173e1c079c9328fcfb
+  metadata.gz: b9f83b823cbc2bbce3f1cb090cf137ab9b0ce665dd2b06f366c27bbc73789da71a90f7da711cc306ae357f6b8dd5360428dffc593c34103d65c8bcc6abe5708a
+  data.tar.gz: 3019a6ae3d5a7b342a9de5a15605e99aa53217018e2d219f677f5b1d3575e63ce6b4e28b1c10676cd16eb552115a0d5661f68cb44d36e064cb4361ebbf9cd238

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Change Log
 
+## 0.1.3
+
+- Add ability to get an app from a screenshot via the `Rsteamshot::Screenshot#app` method.
+- Specify the path to the Steam apps list file in gem-wide configuration block, instead of passing it into individual methods.
+- Add `Rsteamshot::App#find_by_name` to get the best match for an app based on the provided name. For example, passing "oblivion" will return the app named "The Elder Scrolls IV: Oblivion".
+- Add `Rsteamshot::App#find_by_id` to look up a Steam app by its ID.
+- Add `Rsteamshot::Screenshot#file_size_in_bytes` to get an integer value for how large a screenshot is, in bytes. Thanks [@marcqualie](https://github.com/marcqualie)!
+- Add `Rsteamshot::App#to_h` and `Rsteamshot::App#to_json` to get hash and JSON representations of apps.
+- Remove the need to manually call `Rsteamshot::App#download_apps_list`. It will now automatically be called when `Rsteamshot::App#search` and similar methods are called.
+
 ## 0.1.2
 
 Improve the gem description and set the link to its homepage in the gemspec.

data/README.md

@@ -6,7 +6,7 @@ Rsteamshot is a Ruby gem for getting screenshots a user has uploaded to their St
 
 There's no Steam API that I know of that provides this screenshot data, so this gem works by using [Mechanize](https://github.com/sparklemotion/mechanize) to do web scraping on [steamcommunity.com](http://steamcommunity.com/).
 
-[View source on GitHub](https://github.com/cheshire137/rsteamshot)
+[View source on GitHub](https://github.com/cheshire137/rsteamshot) | [View docs on RubyDoc](http://www.rubydoc.info/gems/rsteamshot/) | [View gem on RubyGems](https://rubygems.org/gems/rsteamshot)
 
 ## Installation
 
@@ -27,27 +27,45 @@ Or install it yourself as:
 ## Usage
 
 ```ruby
+# Specify where the latest list of apps from Steam should be downloaded as a JSON file, and
+# referenced when looking up app IDs:
+Rsteamshot.configure do |config|
+  config.apps_list_path = 'apps-list.json'
+end
+
 # Get screenshots uploaded by a Steam user:
 steam_user_name = 'cheshire137'
-user = Rsteamshot::User.new(steam_user_name, per_page: 10)
+user = Rsteamshot::User.new(steam_user_name)
+user.per_page = 10
 order = 'newestfirst' # also: score, oldestfirst
 screenshots = user.screenshots(order: order)
 screenshots += user.screenshots(order: order, page: 2)
 
-# Find a Steam app by name:
-apps_path = 'apps-list.json'
-Rsteamshot::App.download_apps_list(apps_path)
-apps = Rsteamshot::App.search('witcher 3', apps_path)
-app = apps.first
+# Search Steam apps by name:
+apps = Rsteamshot::App.search('witcher 3')
+# => [#<Rsteamshot::App:0x007feb28b135f8 @id=292030, @name="The Witcher 3: Wild Hunt"...
+apps.size
+# => 18
+
+# Find the best match for a Steam app by name:
+app = Rsteamshot::App.find_by_name('oblivion')
+# => #<Rsteamshot::App:0x007feb25dbd518 @id=22330, @name="The Elder Scrolls IV: Oblivion "...
 
 # Filter a user's screenshots to those for a particular app:
 alice_screenshots = user.screenshots(app_id: '19680')
 
-# Initialize an app directly if you know its ID:
-app_id = '377160'
-app = Rsteamshot::App.new(id: app_id, per_page: 10)
+# Find a Steam app by its ID:
+app = Rsteamshot::App.find_by_id(377160)
+# => #<Rsteamshot::App:0x007ff800438758 @id=377160, @name="Fallout 4"...
+
+# Utility methods for an app:
+app.to_h
+# => {:id=>377160, :name=>"Fallout 4"}
+app.to_json
+# => "{\n  \"id\": 377160,\n  \"name\": \"Fallout 4\"\n}"
 
 # Get screenshots uploaded for a Steam game:
+app.per_page = 10
 order = 'mostrecent' # also: toprated, trendday, trendweek, trendthreemonths, trendsixmonths,
                      # trendyear
 screenshots = app.screenshots(order: order)
@@ -82,6 +100,9 @@ screenshots.each do |screenshot|
   screenshot.file_size
   # => "0.367 MB"
 
+  screenshot.file_size_in_bytes
+  # => 367000
+
   screenshot.width
   # => 1920
 
@@ -101,6 +122,10 @@ screenshots.each do |screenshot|
   screenshot.to_json
   # => "{\n  \"details_url\": \"http://steamcommunity.com/sharedfiles/filedetails/?id=737284878\",
 end
+
+# Force the Steam apps list to be re-downloaded:
+Rsteamshot::App.reset_list
+Rsteamshot::App.download_apps_list
 ```
 
 ## Development

data/lib/rsteamshot.rb

@@ -2,6 +2,7 @@ require 'json'
 require 'mechanize'
 require 'open-uri'
 require 'rsteamshot/app'
+require 'rsteamshot/configuration'
 require 'rsteamshot/screenshot'
 require 'rsteamshot/screenshot_page'
 require 'rsteamshot/screenshot_paginator'
@@ -12,4 +13,17 @@ require 'uri'
 # Public: Contains classes for finding screenshots uploaded by users to Steam. Screenshots
 # are from Steam games (apps).
 module Rsteamshot
+  class << self
+    attr_writer :configuration
+  end
+
+  def self.configuration
+    @configuration ||= Configuration.new
+  end
+
+  # Public: Configure the Rsteamshot gem such as by setting the path to where you have
+  # downloaded the list of Steam apps as a JSON file.
+  def self.configure
+    yield configuration
+  end
 end

data/lib/rsteamshot/app.rb

@@ -2,10 +2,14 @@ module Rsteamshot
   # Public: Represents a Steam app, like a video game. Used to fetch the screenshots
   # that were taken in that app that Steam users have uploaded.
   class App
-    # Public: Exception thrown by Rsteamshot::App#search when the given file is not a valid file
-    # containing Steam apps.
+    # Public: Exception thrown when the configured `apps_list_path` is not a valid file containing
+    # Steam apps.
     class BadAppsFile < StandardError; end
 
+    # Public: Exception thrown when there is no file path configured for saving the list of Steam
+    # apps, or it is a bad path.
+    class BadConfiguration < StandardError; end
+
     # Public: You can fetch this many screenshots at once.
     MAX_PER_PAGE = 50
 
@@ -22,53 +26,71 @@ module Rsteamshot
     # Public: Returns the String name of the Steam app, or nil.
     attr_reader :name
 
-    # Public: Writes a JSON file at the given location with the latest list of apps on Steam.
-    #
-    # path - a String file path
+    # Public: Returns the number of screenshots that will be fetched per page for this app.
+    attr_reader :per_page
+
+    # Public: Writes a JSON file at the location specified in `Rsteamshot.configuration` with the
+    # latest list of apps on Steam. Will be automatically called by #list.
     #
     # Returns nothing.
-    def self.download_apps_list(path)
+    def self.download_apps_list
+      path = Rsteamshot.configuration.apps_list_path
+
+      unless path && path.length > 0
+        raise BadConfiguration, 'no path configured for JSON apps list from Steam'
+      end
+
       File.open(path, 'w') do |file|
         IO.copy_stream(open(APPS_LIST_URL), file)
       end
     end
 
-    # Public: Find Steam apps by name.
-    #
-    # raw_query - a String search query for an app or game on Steam
-    # apps_list_path - a String file path to the JSON file produced by #download_apps_list
+    # Public: Force the list of Steam apps to be re-downloaded the next time #list is called.
+    def self.reset_list
+      @@list = nil
+    end
+
+    # Public: Read the JSON file configured in `apps_list_path` and get a list of Steam apps. Will
+    # download the latest list of Steam apps to `apps_list_path` if the file does not already exist.
     #
-    # Returns an Array of Rsteamshot::Apps.
-    def self.search(raw_query, apps_list_path)
-      return [] unless raw_query
+    # Returns an Array of Hashes for all the Steam apps.
+    def self.list
+      @@list ||= begin
+        path = Rsteamshot.configuration.apps_list_path
+        unless path
+          raise BadAppsFile, 'no path configured for JSON apps list from Steam'
+        end
 
-      unless apps_list_path
-        raise BadAppsFile, 'no path given to JSON apps list from Steam'
-      end
+        download_apps_list unless File.file?(path)
+        raise BadAppsFile, "#{path} is not a file" unless File.file?(path)
 
-      unless File.file?(apps_list_path)
-        raise BadAppsFile, "#{apps_list_path} is not a file"
-      end
+        json = begin
+          JSON.parse(File.read(path))
+        rescue JSON::ParserError
+          raise BadAppsFile, "#{path} is not a valid JSON file"
+        end
 
-      json = begin
-        JSON.parse(File.read(apps_list_path))
-      rescue JSON::ParserError
-        raise BadAppsFile, "#{apps_list_path} is not a valid JSON file"
-      end
+        applist = json['applist']
+        raise BadAppsFile, "#{path} does not have expected JSON format" unless applist
 
-      applist = json['applist']
-      unless applist
-        raise BadAppsFile, "#{apps_list_path} does not have expected JSON format"
-      end
+        apps = applist['apps']
+        raise BadAppsFile, "#{path} does not have expected JSON format" unless apps
 
-      apps = applist['apps']
-      unless apps
-        raise BadAppsFile, "#{apps_list_path} does not have expected JSON format"
+        apps
       end
+    end
+
+    # Public: Find Steam apps by name.
+    #
+    # raw_query - a String search query for an app or game on Steam
+    #
+    # Returns an Array of Rsteamshot::Apps.
+    def self.search(raw_query)
+      return [] unless raw_query
 
       query = raw_query.downcase
       results = []
-      apps.each do |data|
+      list.each do |data|
         next unless data['name']
 
         if data['name'].downcase.include?(query)
@@ -79,6 +101,34 @@ module Rsteamshot
       results
     end
 
+    # Public: Find a Steam app by its name, case insensitive.
+    #
+    # name - the String name of a game or other app on Steam
+    #
+    # Returns an Rsteamshot::App or nil.
+    def self.find_by_name(name)
+      apps = search(name)
+      return if apps.length < 1
+
+      exact_match = apps.detect { |app| app.name.downcase == name }
+      return exact_match if exact_match
+
+      app = apps.shift
+      app = apps.shift while app.name.downcase =~ /\btrailer\b/ && apps.length > 0
+      app
+    end
+
+    # Public: Find a Steam app by its ID.
+    #
+    # id - the String or Integer ID of a game or other app on Steam
+    #
+    # Returns an Rsteamshot::App or nil.
+    def self.find_by_id(id)
+      id = id.to_i
+      app_data = list.detect { |data| data['appid'] == id }
+      new(id: app_data['appid'], name: app_data['name']) if app_data
+    end
+
     # Public: Initialize a Steam app with the given attributes.
     #
     # attrs - the Hash of attributes for this app
@@ -87,15 +137,16 @@ module Rsteamshot
     #         :per_page - how many results to get in each page; defaults to 10; valid range: 1-50;
     #                     Integer
     def initialize(attrs = {})
-      per_page = attrs.delete(:per_page)
-
       attrs.each { |key, value| instance_variable_set("@#{key}", value) }
+      @per_page ||= 10
+      initialize_paginator
+    end
 
-      process_html = ->(html) do
-        cards_from(html).map { |card| screenshot_from(card) }
-      end
-      @paginator = ScreenshotPaginator.new(process_html, max_per_page: MAX_PER_PAGE,
-                                           per_page: per_page, steam_per_page: per_page)
+    # Public: Check if this App is equivalent to another object.
+    #
+    # Returns true if the given object represents the same Steam app.
+    def ==(other)
+      other.class == self.class && other.id == id && other.name == name
     end
 
     # Public: Fetch a list of the newest uploaded screenshots for this app on Steam.
@@ -114,8 +165,42 @@ module Rsteamshot
       @paginator.screenshots(page: page, url: url)
     end
 
+    # Public: Get a hash representation of this app.
+    #
+    # Returns a Hash.
+    def to_h
+      result = { id: id }
+      result[:name] = name if name
+      result
+    end
+
+    # Public: Get a JSON representation of this app.
+    #
+    # Returns a String.
+    def to_json
+      JSON.pretty_generate(to_h)
+    end
+
+    # Public: Set how many screenshots should be fetched at a time for this app.
+    #
+    # value - an Integer
+    #
+    # Returns nothing.
+    def per_page=(value)
+      @per_page = value
+      initialize_paginator
+    end
+
     private
 
+    def initialize_paginator
+      process_html = ->(html) do
+        cards_from(html).map { |card| screenshot_from(card) }
+      end
+      @paginator = ScreenshotPaginator.new(process_html, max_per_page: MAX_PER_PAGE,
+                                           per_page: per_page, steam_per_page: per_page)
+    end
+
     def cards_from(html)
       html.search('.apphub_Card')
     end
@@ -135,7 +220,8 @@ module Rsteamshot
       comment_count = comment_count_from(card)
       Screenshot.new(details_url: details_url, title: title, medium_url: medium_url,
                      full_size_url: full_size_url, user_name: user_name,
-                     user_url: user_url, like_count: like_count, comment_count: comment_count)
+                     user_url: user_url, like_count: like_count, comment_count: comment_count,
+                     app: self)
     end
 
     def urls_from(card)

data/lib/rsteamshot/configuration.rb

@@ -0,0 +1,7 @@
+module Rsteamshot
+  # Public: Configure the Rsteamshot gem.
+  class Configuration
+    # Public: The path to a JSON file that will contain Steam app information.
+    attr_accessor :apps_list_path
+  end
+end

data/lib/rsteamshot/screenshot.rb

@@ -38,6 +38,9 @@ module Rsteamshot
     # Public: Returns Integer count of how many comments people have left on this screenshot.
     attr_reader :comment_count
 
+    # Public: Returns the Rsteamshot::App in which this screenshot was taken.
+    attr_reader :app
+
     # Public: Initialize a screenshot with the given attributes.
     #
     # attrs - the Hash of attributes for this screenshot
@@ -75,6 +78,7 @@ module Rsteamshot
       result[:height] = height if height
       result[:like_count] = like_count if like_count
       result[:comment_count] = comment_count if comment_count
+      result[:app] = app.to_h if app
       result
     end
 
@@ -92,6 +96,21 @@ module Rsteamshot
       self.class.name + '<' + JSON.generate(to_h) + '>'
     end
 
+    # Public: file_size parsed into bytes
+    #
+    # Returns a Integer
+    def file_size_in_bytes
+      unit_multiplier = 1000
+      size, unit = self.file_size.split(' ')
+      bytes = case unit.downcase
+        when 'kb' then size.to_f * unit_multiplier
+        when 'mb' then size.to_f * (unit_multiplier ** 2)
+        when 'gb' then size.to_f * (unit_multiplier ** 3)
+        else size.to_f
+      end
+      bytes.to_i
+    end
+
     private
 
     def has_details?
@@ -113,6 +132,8 @@ module Rsteamshot
         @user_name = user_name_from(author)
         @user_url = user_url_from(author)
 
+        @app = app_from(page)
+
         details_block = details_block_from(page)
         if details_block
           labels_container = details_block.at('.detailsStatsContainerLeft')
@@ -135,6 +156,36 @@ module Rsteamshot
       end
     end
 
+    def app_from(page)
+      app_id = app_id_from(page)
+      app_name = app_name_from(page)
+
+      if app_id && app_name
+        Rsteamshot::App.new(id: app_id, name: app_name)
+      end
+    end
+
+    def app_id_from(page)
+      site_info = page.at('.apphub_OtherSiteInfo')
+      return unless site_info
+
+      store_link = site_info.at('a')
+      return unless store_link
+
+      store_url = store_link['href']
+      return unless store_url
+
+      # e.g., "http://store.steampowered.com/app/22330" => "22330"
+      store_url.downcase.split('/app/').last
+    end
+
+    def app_name_from(page)
+      name_el = page.at('.apphub_AppName')
+      return unless name_el
+
+      name_el.text.strip.gsub(/[[:space:]]\z/, '')
+    end
+
     def details_block_from(page)
       details_blocks = page.search('.rightDetailsBlock')
       details_blocks.detect do |details_block|