redd 0.4.3 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4553516b4e115c4b603eb9f378570473fed71770
-  data.tar.gz: 37c75fce0d09befdf315579170c94915b2d8e11a
+  metadata.gz: 0d5b672f674cc48bf220c0a76b7074de9c509e13
+  data.tar.gz: 3fb2b44e36f0ed4f38c3633a4134c4cf85b0e48b
 SHA512:
-  metadata.gz: ef8a7779756ce298e48cc1fedef4c8e8c903d8dd047c4e56ff523b8e2cee599c65afb1c5a241623918a02f0a87e5540e66978aa97c00c9ff79c05024f3bfdaa8
-  data.tar.gz: f8e76f3d3377234c633f2240b3ae575f02d4b529cd7632426d98df69c6a91ca61b62b9ad4f81b0bedac5a7383e8d87ba07a7449c1e9776294cb77a4dececb0fd
+  metadata.gz: 884382cf0fa1c690f9743e30992fc58b09bc7310660057034505b8c66ccea813c8442dde09e610ca610a6a21122c62cde61fdb5f33abfcc81a15efc2fa63d366
+  data.tar.gz: a7db6250cbdf1a3e3b5613af36245d5fcb44eb824d340cfa025b920caea59d3d99d2cfdc30052762ac2c594a955eb710e9baecd5116a2a5a8e5cff91ebc63820

data/README.md

@@ -1,10 +1,11 @@
 <p align="center">
-  <img src="github/redd.png?raw=true" alt="redd"><br>
+  <img src="https://i.imgur.com/2JfE4M1.png" alt="redd"><br>
   <a href="http://badge.fury.io/rb/redd"><img src="https://badge.fury.io/rb/redd.svg" alt="Gem Version" height="18"></a>
   <a href="https://travis-ci.org/avidw/redd"><img src="https://travis-ci.org/avidw/redd.svg?branch=master" alt="Build Status"></a>
 </p>
 
-**redd** is an API wrapper for [reddit](http://reddit.com/dev/api) written in ruby that focuses on being *simple and extensible*.
+**redd** is an API wrapper for [reddit](http://reddit.com/dev/api) written in ruby that focuses on being *simple and extensible*.  
+Check out the latest documentation on [RubyDoc](http://rubydoc.info/github/avidw/redd/master/frames).
 
 ---
 
@@ -36,20 +37,16 @@ Ruby and redd make creating reddit bots accessible and fun. To demonstrate, let'
    require "redd"
    #=> true
    
-   r = Redd.client "HelloWorldBot", "hunter2"
+   r = Redd.client "HelloWorldBot", "hunter2",
+                    user_agent: "HelloWorldBot v1.0 by /u/you"
    # => #<Redd::Client::Authenticated:0xY4D4y4D4y4dA ...
-   
-   # This is generally a good thing to do:
-   r.user_agent = "HelloWorldBot v1.0 (Redd), written by /u/Mustermind"
    ```
 
 3. **Scouting**  
    Redd has a really cool method similar to praw's `helpers.comment_stream` that "streams" comments to you while avoiding duplicates. You won't have to take care of rate-limiting either; Redd `sleep`s after requests to avoid ratelimit errors. If you want to write a rate limiting class yourself, take a look at `lib/redd/rate_limit.rb`
    ```ruby
    r.comment_stream "test" do |comment|
-     if comment.body =~ /^Hello\?$/i
-       comment.reply "World!"
-     end
+     comment.reply "World!" if comment.body =~ /^Hello\?$/i
    end
    ```
 
@@ -58,9 +55,7 @@ Ruby and redd make creating reddit bots accessible and fun. To demonstrate, let'
    ```ruby
    begin
      r.comment_stream "test" do |comment|
-       if comment.body =~ /^Hello\?$/i
-         comment.reply "World!"
-       end
+       comment.reply "World!" if comment.body =~ /^Hello\?$/i
      end
    rescue Redd::Error::RateLimited => e
      time_left = e.time

data/lib/redd.rb

@@ -1,15 +1,3 @@
 require "redd/client/unauthenticated"
 require "redd/client/authenticated"
 require "redd/client/oauth2"
-
-module Redd
-  def self.client(username = nil, password = nil, redirect_uri = nil, options = {})
-    if redirect_uri
-      Redd::Client::OAuth2.new(username, password, redirect_uri, options)
-    elsif username && password
-      Redd::Client::Authenticated.new_from_credentials(username, password, options)
-    else
-      Redd::Client::Unauthenticated.new
-    end
-  end
-end

data/lib/redd/base.rb

@@ -6,22 +6,25 @@ module Redd
     include Memoizable
 
     # @!attribute [r] attributes
-    # @return [Hash] A list of attributes returned by reddit for this object.
+    #   @return [Hash] A list of attributes returned by reddit for this object.
     attr_reader :attributes
     alias_method :to_h, :attributes
 
     # @!attribute [r] client
-    # @return The client instance used to make requests with this object.
+    #   @return The client instance used to make requests with this object.
     attr_reader :client
 
-    # Define and memoize the method that returns a key from the
-    # attributes hash.
+    # Define and memoize the method that returns a key from the attributes
+    # hash.
+    #
     # @param [Symbol, String] attr The attribute to construct a method out of.
     def self.attr_reader(attr)
       define_attribute_method(attr)
       define_predicate_method(attr)
     end
 
+    # @param method [#to_sym] An attribute of the class
+    # @return The attribute requested
     def [](method)
       send(method.to_sym)
     rescue NoMethodError
@@ -37,13 +40,14 @@ module Redd
       @attributes[:kind] = attributes[:kind]
     end
 
-    private
-
+    # Create a new method with the given name that accesses the @attributes.
     def self.define_attribute_method(method)
       define_method(method) { @attributes[method] }
       memoize method
     end
 
+    # Create a new method with the given name that accesses the @attributes.
+    # @return [Boolean]
     def self.define_predicate_method(method)
       define_method(:"#{method}?") { !!@attributes[method] }
       memoize :"#{method}?"

data/lib/redd/client/authenticated.rb

@@ -41,7 +41,8 @@ module Redd
       # @return [String] The returned modhash used when making requests.
       attr_reader :modhash
 
-      def new_from_credentials(username, password, options = {})
+      def self.new_from_credentials(username, password, options = {})
+        @username = username
         Redd::Client::Unauthenticated.new.login(username, password, options)
       end
 

data/lib/redd/client/authenticated/account.rb

@@ -1,7 +1,9 @@
 module Redd
   module Client
     class Authenticated
+      # Methods to manage the logged-in user
       module Account
+        # @return [Redd::Object::User] The logged-in user.
         def me
           object_from_response :get, "/api/me.json"
         end

data/lib/redd/client/authenticated/apps.rb

@@ -1,6 +1,7 @@
 module Redd
   module Client
     class Authenticated
+      # Methods to interact with OAuth2 Apps
       module Apps
         # Low-Priority
         #

data/lib/redd/client/authenticated/flair.rb

@@ -1,7 +1,22 @@
 module Redd
   module Client
     class Authenticated
+      # Methods to interact with link and user flairs.
       module Flair
+        # Get a list of everbody on the subreddit with a user flair.
+        #
+        # @param subreddit [Redd::Object::Subreddit, String] The subreddit to
+        #   find the users in.
+        # @param params [Hash] A list of params to send with the request.
+        # @option params [String] :after Return results after the given
+        #   fullname.
+        # @option params [String] :before Return results before the given
+        #   fullname.
+        # @option params [Integer] :count (0) The number of items already seen
+        #   in the listing.
+        # @option params [1..1000] :limit (25) The maximum number of things to
+        #   return.
+        # @return [Array<Hash>] An array of users.
         def get_flair_list(subreddit, params = {})
           name = extract_attribute(subreddit, :display_name)
 
@@ -11,21 +26,32 @@ module Redd
           get(path, params)[:users]
         end
 
-        # @see http://ruby-doc.org/core-1.9.3/String.html#method-i-casecmp
+        # Get the flair of a user.
+        #
+        # @param subreddit [Redd::Object::Subreddit, String] The subreddit to
+        #   find the user in.
+        # @param user [Redd::Object::User, String] The user to find.
+        # @return [Hash, nil] Flair info about the user or nil if nobody was
+        #   found.
         def get_flair(subreddit, user)
+          display_name = extract_attribute(subreddit, :display_name)
           username = extract_attribute(user, :name)
           options = {name: username}
 
-          flair = get_flair_list(subreddit, options).first
+          flair = get_flair_list(display_name, options).first
           flair if flair[:user].casecmp(username.downcase) == 0
         end
 
+        # Set the flair of a user or link.
+        # @param subreddit [Redd::Object::Subreddit, String] The subreddit to
+        #   find the user in.
+        # @param user_or_link [Redd::Object::Subreddit, Redd::Object::User]
+        #   The user or link to set the flair to.
+        # @param text [String] The text to set the flair to.
+        # @param css_class [String] The css_class of the flair.
         def set_flair(subreddit, user_or_link, text = "", css_class = "")
           name = extract_attribute(subreddit, :display_name)
-
-          path = "/api/flair"
-          path = path.prepend("/r/#{name}")
-          params = {api_type: "json", text: text, css_class: css_class}
+          path = "/r/#{name}/api/flair"
 
           case user_or_link
           when Redd::Object::User
@@ -36,7 +62,7 @@ module Redd
             fail "You should provide a User or Submission object."
           end
 
-          post path, params
+          post path, api_type: "json", text: text, css_class: css_class
         end
       end
     end

data/lib/redd/client/authenticated/gold.rb

@@ -1,6 +1,7 @@
 module Redd
   module Client
     class Authenticated
+      # Methods to gild a user, link or comment
       module Gold
         # Low-Priority
         #

data/lib/redd/client/authenticated/links_comments.rb

@@ -1,17 +1,36 @@
 module Redd
   module Client
     class Authenticated
+      # Methods to deal with comments and links
       module LinksComments
+        # Submit a link or a text post to a subreddit.
+        #
+        # @param title [String] The title of the submission.
+        # @param kind [:self, :link] The type of submission to make.
+        # @param text_or_url [String] The url of the post if :link or the
+        #   content of the post if :text
+        # @param subreddit [Redd::Object::Submission, String] The subreddit
+        #   to submit to.
+        # @param captcha [String] A possible captcha result to send if one
+        #   is required.
+        # @param identifier [String] The identifier for the captcha if one
+        #   is required.
+        # @param options [Hash] A hash of additional options to send.
+        # @option options [Boolean] :resubmit (false) Whether to post a link
+        #   to a subreddit despite it having been posted there before.
+        # @option options [Boolean] :resubmit (false) Whether to automatically
+        #   save the post to the user's account after posting.
         def submit(
-          title, kind, text_or_url, captcha = nil, identifier = nil,
+          title, kind, text_or_url, subreddit, captcha = nil, identifier = nil,
           options = {}
         )
-          # Set required parameters
+
           params = {
             api_type: "json", extension: "json", title: title, kind: kind
           }
+          sr_name = extract_attribute(subreddit, :display_name)
+          params << {sr: sr_name}
 
-          # Set url or selftext depending on kind
           case kind.to_sym
           when :self
             params[:text] = text_or_url
@@ -19,16 +38,18 @@ module Redd
             params[:url] = text_or_url
           end
 
-          # Optional captcha
           params << {captcha: captcha, iden: identifier} if captcha
-
-          # Fill in the rest of the options
           params << options
 
           post "/api/submit", params
         end
 
-        # @todo return the edited object.
+        # Add a comment to a link, reply to a comment or reply to a message.
+        # Bit of an all-purpose method, this one.
+        #
+        # @param thing [Redd::Object::Submission, Redd::Object::Comment,
+        #   Redd::Object::PrivateMessage, String] A thing to add a comment to.
+        # @param text [String] The text to comment.
         def add_comment(thing, text)
           fullname = extract_fullname(thing)
           post "/api/comment", api_type: "json", text: text, thing_id: fullname
@@ -36,33 +57,54 @@ module Redd
 
         alias_method :reply, :add_comment
 
+        # Delete a thing.
+        #
+        # @param thing [Redd::Object::Submission, Redd::Object::Comment,
+        #   String] A thing to delete.
         def delete(thing)
           fullname = extract_fullname(thing)
           post "/api/del", id: fullname
         end
 
-        # @todo return the edited object.
+        # Edit a thing.
+        #
+        # @param thing [Redd::Object::Submission, Redd::Object::Comment,
+        #   String] A thing to delete.
+        # @param text [String] The new text.
         def edit(thing, text)
           fullname = extract_fullname(thing)
-          post "/api/editusertext",
-            api_type: "json", text: text, thing_id: fullname
+          post "/api/editusertext", api_type: "json",
+                                    thing_id: fullname,
+                                    text: text
         end
 
+        # Hide a link from the logged-in user.
+        #
+        # @param thing [Redd::Object::Submission, String] A link to hide.
         def hide(thing)
           fullname = extract_fullname(thing)
           post "/api/hide", id: fullname
         end
 
+        # Unhide a previously hidden link.
+        #
+        # @param thing [Redd::Object::Submission, String] A link to show.
         def unhide(thing)
           fullname = extract_fullname(thing)
           post "/api/unhide", id: fullname
         end
 
+        # Mark a link as "NSFW" (Not Suitable For Work)
+        #
+        # @param thing [Redd::Object::Submission, String] A link to mark.
         def mark_as_nsfw(thing)
           fullname = extract_fullname(thing)
           post "/api/marknsfw", id: fullname
         end
 
+        # Remove the NSFW label from the link.
+        #
+        # @param thing [Redd::Object::Submission, String] A link to mark.
         def unmark_as_nsfw(thing)
           fullname = extract_fullname(thing)
           post "/api/unmarknsfw", id: fullname
@@ -70,11 +112,20 @@ module Redd
 
         alias_method :mark_as_safe, :unmark_as_nsfw
 
+        # Report the link or comment to the subreddit moderators.
+        #
+        # @param thing [Redd::Object::Submission, Redd::Object::Comment,
+        #   String] A link to report.
         def report(thing)
           fullname = extract_fullname(thing)
           post "/api/report", id: fullname
         end
 
+        # Save a link or comment (if gilded) to the user's account.
+        #
+        # @param thing [Redd::Object::Submission, Redd::Object::Comment,
+        #   String] A link to save.
+        # @param category [String] A category to save to (if gilded).
         def save(thing, category = nil)
           fullname = extract_fullname(thing)
           params = {id: fullname}
@@ -82,19 +133,38 @@ module Redd
           post "/api/save", params
         end
 
+        # Remove the link or comment from the user's saved links.
+        #
+        # @param thing [Redd::Object::Submission, Redd::Object::Comment,
+        #   String] A link to unsave.
         def unsave(thing)
           fullname = extract_fullname(thing)
           post "/api/unsave", id: fullname
         end
 
+        # Upvote the thing.
+        #
+        # @param thing [Redd::Object::Submission, Redd::Object::Comment,
+        #   String] A link or comment to upvote.
+        # @see #vote
         def upvote(thing)
           vote(thing, 1)
         end
 
+        # Downvote the thing.
+        #
+        # @param thing [Redd::Object::Submission, Redd::Object::Comment,
+        #   String] A link or comment to downvote.
+        # @see #vote
         def downvote(thing)
           vote(thing, -1)
         end
 
+        # Clear the user's vote on the thing.
+        #
+        # @param thing [Redd::Object::Submission, Redd::Object::Comment,
+        #   String] A link or comment to remove the vote on.
+        # @see #vote
         def unvote(thing)
           vote(thing, 0)
         end
@@ -103,6 +173,12 @@ module Redd
 
         private
 
+        # Set a vote on the thing.
+        #
+        # @param thing [Redd::Object::Submission, Redd::Object::Comment,
+        #   String] A link or comment to set a vote on.
+        # @note Votes must be cast by humans only! Your script can proxy a
+        #   user's actions, but it cannot decide what to vote.
         def vote(thing, direction)
           fullname = extract_fullname(thing)
           post "/api/vote", id: fullname, dir: direction

data/lib/redd/client/authenticated/live.rb

@@ -1,6 +1,7 @@
 module Redd
   module Client
     class Authenticated
+      # Methods to interact with /r/live threads
       module Live
         # Low-priority
         #

data/lib/redd/client/authenticated/moderation.rb

@@ -1,69 +1,118 @@
 module Redd
   module Client
     class Authenticated
+      # Methods for moderating subreddits
       module Moderation
+        # Approve a submission.
+        # @param thing [Redd::Object::Submission] The link to approve.
         def approve(thing)
           fullname = extract_fullname(thing)
           post "/api/approve", id: fullname
         end
 
+        # Remove a submission.
+        # @param thing [Redd::Object::Submission] The link to remove.
         def remove(thing)
           fullname = extract_fullname(thing)
           post "/api/remove", id: fullname
         end
 
+        # Distinguish a link or comment with a sigil to show that it has
+        # been created by a moderator.
+        #
+        # @param thing [Redd::Object::Submission, Redd::Object::Comment]
+        #   The link or comment to distinguish.
+        # @param how [:yes, :no, :admin, :special] How to distinguish the
+        #   thing.
         def distinguish(thing, how = :yes)
           fullname = extract_fullname(thing)
           post "/api/distinguish", api_type: "json", id: fullname, how: how
         end
 
+        # Remove the sigil that shows a thing was created by a moderator.
+        # @param thing [Redd::Object::Submission, Redd::Object::Comment]
+        #   The link or comment to undistinguish.
         def undistinguish(thing)
           distinguish(thing, :no)
         end
 
+        # Accept a moderator invite from a subreddit.
+        # @param subreddit [Redd::Object::Subreddit] The subreddit to accept
+        #   the invitation from.
         def accept_moderator_invite(subreddit)
           name = extract_attribute(subreddit, :display_name)
           post "/r/#{name}/api/accept_moderator_invite", api_type: "json"
         end
 
+        # Stop being a contributor of the subreddit.
+        # @param subreddit [Redd::Object::Subreddit] The subreddit to stop
+        #   being a contributor of.
         def leave_contributor_status(subreddit)
           fullname = extract_fullname(subreddit)
           post "/api/leavecontributor", id: fullname
         end
 
+        # Stop being a moderator of the subreddit.
+        # @param subreddit [Redd::Object::Subreddit] The subreddit to stop
+        #   being a moderator of.
         def leave_moderator_status(subreddit)
           fullname = extract_fullname(subreddit)
           post "/api/leavemoderator", id: fullname
         end
 
+        # Stop getting any moderator-related reports on the thing.
+        # @param thing [Redd::Object::Submission, Redd::Object::Comment]
+        #   The thing to stop getting reports on.
         def ignore_reports(thing)
-          fullname = extract_fullname(subreddit)
+          fullname = extract_fullname(thing)
           post "/api/ignore_reports", id: fullname
         end
 
+        # Start getting moderator-related reports on the thing again.
+        # @param thing [Redd::Object::Submission, Redd::Object::Comment]
+        #   The thing to start getting reports on.
         def unignore_reports(thing)
-          fullname = extract_fullname(subreddit)
+          fullname = extract_fullname(thing)
           post "/api/unignore_reports", id: fullname
         end
 
-        def get_reports(*args)
-          get_submissions(:reports, *args)
-        end
-
-        def get_spam(*args)
-          get_submissions(:spam, *args)
-        end
-
-        def get_modqueue(*args)
-          get_submissions(:modqueue, *args)
-        end
-
-        def get_unmoderated(*args)
-          get_submissions(:unmoderated, *args)
+        # @!method get_reports
+        # @!method get_spam
+        # @!method get_modqueue
+        # @!method get_unmoderated
+        #
+        # Get the appropriate listing.
+        # @param subreddit [Redd::Object::Subreddit] The subreddit to query.
+        # @param params [Hash] A list of params to send with the request.
+        #
+        # @see #get_submissions
+        %w(reports spam modqueue unmoderated).each do |sort|
+          define_method :"get_#{sort}" do |subreddit = nil, params = {}|
+            get_submissions(sort, subreddit, params)
+          end
         end
 
         private
 
+        # Get a listing to moderator-related subreddits.
+        #
+        # @param type [:reports, :spam, :modqueue, :unmoderated] How the
+        #   results are sorted.
+        # @param subreddit [Redd::Object::Subreddit, String] The subreddit to
+        #   query.
+        # @param params [Hash] A list of params to send with the request.
+        # @option params [String] :after Return results after the given
+        #   fullname.
+        # @option params [String] :before Return results before the given
+        #   fullname.
+        # @option params [Integer] :count (0) The number of items already seen
+        #   in the listing.
+        # @option params [1..100] :limit (25) The maximum number of things to
+        #   return.
+        # @option params :location No idea what this does.
+        # @option params [:links, :comments] :only The type of things to show.
+        # @return [Redd::Object::Listing] A listing of submissions or comments.
+        #
         def get_submissions(type, subreddit = nil, params = {})
           subreddit_name = extract_attribute(subreddit, :display_name)
           path = "/about/#{type}.json"