rarbg 1.1.1 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 875767e85f80c778779be897867dffad4731f9f8a4a7dca68cd76b47be386b5a
-  data.tar.gz: 1a340ef687b05465ff2290fc8feec5324102d90514c657641b47411149cfd7eb
+  metadata.gz: 6ae0fc9cbd49bc0297737148b66e9c08164e1ebb4e0e1e7237d0e0c3385d4165
+  data.tar.gz: 76ae543821aa6204da813588d4020bfaf8d9f0462f88cea1c7e8299ee9b84fac
 SHA512:
-  metadata.gz: 9a8fca5afbe015a0d4fdb33a2ff3fcd77090b680e519c064d9686c291f5aa3366aa9ea456ae770042c79b5bc8bb7ba7477dfa945c85ee8327befa2b1052adeb2
-  data.tar.gz: 1d64bf8971f55b9bebaa8cd19cc45d0667f77b53fbba7fa896ad81d8099f40ffb649e5d32994fdd20cca0c11f8fdf849bfdb2661982d54a5f4d4f25d4918ca99
+  metadata.gz: c486d18f7621cfa1aa6305145dda201e60c5a05a4c53637efe68908efcb296adb7094af575ab77253c6286098269a1daaa5561ad140d9274a40786de9ebe2c50
+  data.tar.gz: f1974c700b3f66ec529e123a92ae8619fca9c9f014f9a7b7d6d3381b0aa95890e05f70706f3e20a62bacaa677a0b758cab3885a634e300a24fdc634310640f95

data/.github/CODEOWNERS

@@ -0,0 +1,4 @@
+# These owners will be the default owners for everything in the repo.
+# Unless a later match takes precedence, they will be requested for review
+# when someone opens a pull request.
+* @epistrephein

data/.github/{ISSUE_TEMPLATE.md → ISSUE_TEMPLATE/BUG_REPORT.md}

@@ -1,8 +1,12 @@
-## Bug description
-A clear and concise description of what the bug is.
+---
+name: Bug Report
+about: Report something that isn't working as expected.
+
+---
 
-## Expected behavior
-A clear and concise description of what you expected to happen.
+## Bug description
+A clear and concise description of what the bug is, what you expected to happen
+and what happened instead.
 
 ## Steps to reproduce
 1. Instantiate object...
@@ -10,9 +14,9 @@ A clear and concise description of what you expected to happen.
 3. Error is raised...
 
 ## Environment
- - Gem version:
- - Ruby version:
- - OS and version:
+- Gem version:
+- Ruby version:
+- OS and version:
 
 ## Logs
 If applicable, add logs or screenshots to help explain your problem.

data/.github/ISSUE_TEMPLATE/FEATURE_REQUEST.md

@@ -0,0 +1,18 @@
+---
+name: Feature request
+about: Suggest an idea for this project.
+
+---
+
+## Feature description
+A clear and concise description of what problem you're trying to solve and what
+you'd want to happen.
+
+## Possible implementations
+If possible, suggest a way to add this feature.
+
+## Alternatives considered
+A description of any alternative solutions or features you've considered.
+
+## Additional context
+Add any other context about the feature here.

data/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,14 @@
+## Pull Request description
+A clear and concise explanation of what changes your PR introduces and why this
+was needed.
+
+## Pull Request checklist
+
+- [ ] My code is a **bug fix** (non-breaking change which fixes an issue)
+- [ ] My code is a **new feature** (non-breaking change which adds functionality)
+- [ ] My code introduces a **breaking change** (fix or feature that would cause existing functionality to change)
+- [ ] My code follows the code style of this project
+- [ ] My change requires a change to the documentation
+- [ ] I have updated the documentation accordingly
+- [ ] I have added tests to cover my changes
+- [ ] All new and existing tests passed

data/.gitignore

@@ -32,6 +32,10 @@ Gemfile.lock
 *.log
 *.log.[0-9]*
 
+# Pry
+.pryrc
+.pry_history
+
 # RVM
 .rvmrc
 

data/.rspec

@@ -1,4 +1,4 @@
+--color
 --format documentation
 --order random
---color
 --require spec_helper

data/.rubocop.yml

@@ -0,0 +1,27 @@
+AllCops:
+  TargetRubyVersion: 2.3
+  DisplayCopNames: true
+  DisplayStyleGuide: true
+
+Gemspec/RequiredRubyVersion:
+  Enabled: false
+
+Layout/AlignHash:
+  EnforcedHashRocketStyle: table
+  EnforcedColonStyle: table
+
+Layout/FirstParameterIndentation:
+  EnforcedStyle: consistent
+
+Metrics/BlockLength:
+  Exclude:
+    - '*.gemspec'
+  ExcludedMethods:
+    - 'describe'
+    - 'context'
+
+Metrics/LineLength:
+  Max: 90
+
+Style/BracesAroundHashParameters:
+  EnforcedStyle: context_dependent

data/.travis.yml

@@ -3,6 +3,7 @@ language: ruby
 cache: bundler
 script: bundle exec rspec
 rvm:
+  - 2.6.0
   - 2.5.3
   - 2.4.5
   - 2.3.8

data/CHANGELOG.md

@@ -4,8 +4,23 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/),
 and this project adheres to [Semantic Versioning](https://semver.org/).
 
-## Unreleased
-[Diff](https://github.com/epistrephein/rarbg/compare/v1.1.1...master)
+## 1.2.0 - 2019-01-02
+[RubyGems](https://rubygems.org/gems/rarbg/versions/1.2.0) |
+[Release](https://github.com/epistrephein/rarbg/releases/tag/v1.2.0) |
+[Diff](https://github.com/epistrephein/rarbg/compare/v1.1.1...v1.2.0)
+
+#### Fixed
+- Fixed gemspec to not include HTML documentation files.
+- Fixed code style and typos.
+
+#### Added
+- Added rubocop as development dependency to enforce code style.
+- Added GitHub templates for issues and pull requests.
+- Added CONTRIBUTING document with contribution guidelines.
+
+#### Changed
+- Bumped all dependencies to stricter minor version constraint.
+- Rate limit is now stubbed to 0.1 seconds in RSpec to speed up tests.
 
 
 ## 1.1.1 - 2018-10-19
@@ -13,7 +28,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 [Release](https://github.com/epistrephein/rarbg/releases/tag/v1.1.1) |
 [Diff](https://github.com/epistrephein/rarbg/compare/v1.1.0...v1.1.1)
 
-### Changed
+#### Changed
 - Self-host documentation on GitHub pages.
 
 
@@ -33,13 +48,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 [Release](https://github.com/epistrephein/rarbg/releases/tag/v1.0.1) |
 [Diff](https://github.com/epistrephein/rarbg/compare/v1.0.0...v1.0.1)
 
-#### Added
-- Faraday now logs requests to stdout if in verbose mode (`-w` or `-v`).
-
 #### Fixed
 - Fixed code styling and some documentation errors.
 - Fixed IMDb id autocorrect in `search`.
 
+#### Added
+- Faraday now logs requests to stdout if in verbose mode (`-w` or `-v`).
+
 
 ## 1.0.0 – 2018-04-02
 [RubyGems](https://rubygems.org/gems/rarbg/versions/1.0.0) |
@@ -95,9 +110,11 @@ search type must be specified as a keyword argument upon `search`.
 [Diff](https://github.com/epistrephein/rarbg/compare/v0.1.0...v0.1.1)
 
 #### Fixed
-- Fix invalid gemspec
+- Fix invalid gemspec.
 
 
 ## 0.1.0 – 2016-12-21
+[RubyGems](https://rubygems.org/gems/rarbg/versions/0.1.0) |
+[Release](https://github.com/epistrephein/rarbg/releases/tag/v0.1.0)
 
-Initial release. Yanked from [RubyGems](https://rubygems.org).
+Initial release. Yanked from RubyGems.

data/CONTRIBUTING.md

@@ -0,0 +1,92 @@
+# Contributing
+
+First off, thank you for considering contributing to this project.
+
+As part of the open source community, this project thrives thanks to the help
+and the contributions of its users. There are many ways to contribute - from
+submitting bug reports and feature requests, to improving the documentation, or
+writing code which can be incorporated into the codebase.
+
+In these guidelines, you will find the most common scenarios related to
+contributing and information on how to proceed to make sure that your submission
+can be evaluated swiftly and properly.
+
+This project is intended to be a safe, welcoming space for collaboration,
+and contributors are expected to adhere to the
+[Code of Conduct](https://github.com/epistrephein/rarbg/blob/master/CODE_OF_CONDUCT.md).
+
+## Opening an issue
+
+Opening an issue on GitHub is the fastest way to get in touch with the maintainers
+of the project and start a discussion regarding a problem you're experiencing or
+a missing feature you would like to suggest.
+
+For this reason, upon opening a new issue, you'll be able to choose between
+different templates for your submission, with some pre-allocated sections to fill.
+Please try to follow the existing structure of the issue and to provide as much
+information as possible regarding your situation. This will help the maintainers
+to reproduce the bug or effectively consider the feature you'd like to see
+implemented.
+
+If you think your issue doesn't fit into any of the existing templates, or if you
+just have a question regarding the existing functionalities of the project,
+simply open a regular issue and describe the problem in the clearest way possible.
+
+## Contributing with code
+
+If you would like to contribute to the project by writing code, you can open a
+Pull Request on GitHub with your changes and ask a maintainer for a review.
+
+As an open source Ruby gem, this projects uses the most common development tools
+to test, validate, and document the code.
+
+### Tools and integrations
+
+We use [RSpec](http://rspec.info/) as testing framework.  
+The test suite lives in the `spec` directory, and you can run it to test your
+changes with `rake spec`.
+
+We also use [RuboCop](https://docs.rubocop.org/en/latest/) to enforce code style.  
+The configuration file used for this project lives in `.rubocop.yml`. You can check
+the code style of your changes with `rake rubocop`.
+
+The default Rake task, runnable using `rake`, performs code linting via Rubocop
+and then runs the RSpec tests.
+
+Documentation is written as [YARD](https://yardoc.org/) docblocks in the Ruby code.  
+This is rendered as self-hosted Web pages on [GitHub pages](https://epistrephein.github.io/rarbg/).
+Sources are stored in the repository under the `docs` folder and can be automatically
+generated and updated via `rake yard`.  
+The completeness of the documentation is then measured via
+[Inch CI](https://inch-ci.org/github/epistrephein/rarbg).
+
+Continuous integration and automated tests are run on
+[Travis CI](https://travis-ci.org/epistrephein/rarbg) and integrated with the
+GitHub Pull Request flow.
+
+Code quality and test coverage are then scored via
+[CodeClimate](https://codeclimate.com/github/epistrephein/rarbg).
+
+Finally, dependencies are kept up-to-date thanks to
+[Depfu](https://depfu.com/github/epistrephein/rarbg) integration.
+
+### Submitting a PR
+
+This project follows the [GitHub flow](https://guides.github.com/introduction/flow/)
+for Pull Request submissions.
+
+To submit a PR with your proposed changes, follow these steps:
+
+1. [Fork the repo](https://github.com/epistrephein/rarbg/fork) in your GitHub
+userspace and clone it locally
+2. Install the dependencies with bundler (`bin/setup`)
+3. Create a feature branch (`git checkout -b my-new-feature`)
+4. Add your code to the branch and then commit the changes (`git commit -am 'Add some feature'`)
+5. Run the test suite (`rake spec`) and make sure that existing and newly introduced
+tests pass. You can also run Rubocop linting with `rake rubocop`, or just use `rake`
+to run both Rubocop and RSpec tests
+6. Push to your remote branch on GitHub (`git push origin my-new-feature`)
+7. Create a [new pull request](https://github.com/epistrephein/rarbg/pulls)
+
+As for issues, when opening a new Pull Request, please fill out the template with
+all the relevant information in order to reduce the review effort of the maintainers.

data/Gemfile

@@ -1,5 +1,4 @@
 # frozen_string_literal: true
 
 source 'https://rubygems.org'
-
 gemspec

data/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2016-2018 Tommaso Barbato
+Copyright (c) 2016-2019 Tommaso Barbato
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -20,7 +20,7 @@ $ gem install rarbg
 Or add it to your Gemfile and execute `bundle install`
 
 ```ruby
-gem 'rarbg', '~> 1.0'
+gem 'rarbg', '~> 1.2'
 ```
 
 ## Usage
@@ -67,7 +67,6 @@ One search type parameter among `string`, `imdb`, `themoviedb` and `tvdb` is req
 rarbg.search(string: 'Force Awakens')
 
 # Search by IMDB id, in `Movies/x264/1080` and `Movies/x264/720`.
-# Note that 'tt' can be omitted when passing an IMDB id.
 rarbg.search(imdb: 'tt2488496', category: [44, 45])
 
 # Search unranked torrents by TheMovieDB id, sorted by last.
@@ -115,7 +114,14 @@ rarbg.list('a string instead of an hash')
 # => ArgumentError: Expected params hash
 
 rarbg.search(limit: 50)
-# => ArgumentError: At least one parameter required among string, imdb, tvdb, themoviedb for search mode.
+# => ArgumentError: One search parameter required among: string, imdb, tvdb, themoviedb
+```
+
+Lower level connection errors will raise `Faraday::Error` subclasses exceptions.
+
+```ruby
+rarbg.search(string: 'a timeout error')
+# => Faraday::ConnectionFailed: execution expired
 ```
 
 ## Contributing
@@ -135,6 +141,8 @@ You can contribute changes by forking the project and submitting a pull request.
 6. Push to the branch (`git push origin my-new-feature`)
 7. Create a new pull request
 
+For more information about contributing to this project, check out [CONTRIBUTING](https://github.com/epistrephein/rarbg/blob/master/CONTRIBUTING.md).
+
 ## License
 
 This gem is released as open source under the terms of the [MIT License](https://github.com/epistrephein/rarbg/blob/master/LICENSE).

data/Rakefile

@@ -2,9 +2,11 @@
 
 require 'bundler/gem_tasks'
 require 'rspec/core/rake_task'
+require 'rubocop/rake_task'
 require 'yard'
 
 RSpec::Core::RakeTask.new(:spec)
+RuboCop::RakeTask.new(:rubocop)
 YARD::Rake::YardocTask.new(:yard)
 
-task default: :spec
+task default: %i[rubocop spec]

data/lib/rarbg.rb

@@ -4,13 +4,13 @@ require 'rarbg/version'
 require 'rarbg/categories'
 require 'rarbg/api'
 
-# Module shortcut methods
+# Module namespace shortcut methods.
 module RARBG
   class << self
     %i[list search].each do |m|
-      define_method(m) do |*arg|
+      define_method(m) do |*args|
         @rarbg ||= RARBG::API.new
-        @rarbg.send(m, *arg)
+        @rarbg.send(m, *args)
       end
     end
   end

data/lib/rarbg/api.rb

@@ -3,7 +3,7 @@
 require 'faraday'
 require 'faraday_middleware'
 
-# Main namespace for RARBG
+# Main namespace for RARBG.
 module RARBG
   # Default error class for the module.
   class APIError < StandardError; end
@@ -16,10 +16,10 @@ module RARBG
     # App name identifier.
     APP_ID = 'rarbg-rubygem'
 
-    # Default token expiration time.
+    # Default token expiration time (seconds).
     TOKEN_EXPIRATION = 800
 
-    # Default API rate limit.
+    # Default API rate limit (seconds).
     RATE_LIMIT = 2.1
 
     # @return [Faraday::Connection] the Faraday connection object.
@@ -34,7 +34,11 @@ module RARBG
     # @return [Integer] the monotonic timestamp of the last request performed.
     attr_reader :last_request
 
-    # Initialize a new istance of `RARBG::API`.
+    # Supported search parameters.
+    SEARCH_KEYS = %w[string imdb tvdb themoviedb].freeze
+    private_constant :SEARCH_KEYS
+
+    # Initialize a new instance of `RARBG::API`.
     #
     # @example
     #   rarbg = RARBG::API.new
@@ -72,9 +76,9 @@ module RARBG
     # @return [Array<Hash>] Return torrents that match the specified parameters.
     #
     # @raise [ArgumentError] Exception raised if `params` is not an `Hash`.
-    #
     # @raise [RARBG::APIError] Exception raised when request fails or endpoint
     #   responds with an error.
+    # @raise [Faraday::Error] Exception raised on low-level connection errors.
     #
     # @example List last 100 ranked torrents in `Movies/x264/1080`
     #   rarbg = RARBG::API.new
@@ -87,8 +91,8 @@ module RARBG
       raise ArgumentError, 'Expected params hash' unless params.is_a?(Hash)
 
       params.update(
-        mode:   'list',
-        token:  token?
+        mode:  'list',
+        token: token?
       )
       call(params)
     end
@@ -103,7 +107,7 @@ module RARBG
     # @option params [String] :themoviedb Search by The Movie DB id.
     # @option params [Array<Integer>] :category Filter results by category.
     # @option params [Symbol] :format Format results.
-    #   Valid values: `:json`, `:json_extended`. Default: `:json`
+    #   Valid values: `:json`, `:json_extended`. Default: `:json`.
     # @option params [Integer] :limit Limit results number.
     #   Valid values: `25`, `50`, `100`. Default: `25`.
     # @option params [Integer] :min_seeders Filter results by minimum seeders.
@@ -116,16 +120,15 @@ module RARBG
     # @return [Array<Hash>] Return torrents that match the specified parameters.
     #
     # @raise [ArgumentError] Exception raised if `params` is not an `Hash`.
-    #
     # @raise [ArgumentError] Exception raised if no search type param is passed
     #   (among `string`, `imdb`, `tvdb`, `themoviedb`).
-    #
     # @raise [RARBG::APIError] Exception raised when request fails or endpoint
     #   responds with an error.
+    # @raise [Faraday::Error] Exception raised on low-level connection errors.
     #
     # @example Search by IMDb ID, sorted by leechers and in extended format.
     #   rarbg = RARBG::API.new
-    #   rarbg.search(imdb: 'tt012831', sort: :leechers, format: :json_extended)
+    #   rarbg.search(imdb: 'tt2488496', sort: :leechers, format: :json_extended)
     #
     # @example Search unranked torrents by string, with at least 2 seeders.
     #   rarbg = RARBG::API.new
@@ -134,20 +137,21 @@ module RARBG
       raise ArgumentError, 'Expected params hash' unless params.is_a?(Hash)
 
       params.update(
-        mode:   'search',
-        token:  token?
+        mode:  'search',
+        token: token?
       )
       call(params)
     end
 
     private
 
-    # Wrap request for error handling.
+    # Wrap requests for error handling.
     def call(params)
       response = request(validate(params))
 
       return [] if response['error'] == 'No results found'
       raise APIError, response['error'] if response.key?('error')
+
       response.fetch('torrent_results', [])
     end
 
@@ -167,23 +171,20 @@ module RARBG
       Hash[params.reject { |_k, v| v.nil? }.map { |k, v| [k.to_s, v] }]
     end
 
-    # Validate search type parameter.
+    # Validate search type parameters.
     def validate_search!(params)
-      search_keys = %w[string imdb tvdb themoviedb]
-
-      raise(
-        ArgumentError,
-        "At least one parameter required among #{search_keys.join(', ')} " \
-        'for search mode.'
-      ) if (params.keys & search_keys).none?
+      if (params.keys & SEARCH_KEYS).none?
+        raise(ArgumentError,
+              "One search parameter required among: #{SEARCH_KEYS.join(', ')}")
+      end
 
-      search_keys.each do |k|
+      SEARCH_KEYS.each do |k|
         params["search_#{k}"] = params.delete(k) if params.key?(k)
       end
       params
     end
 
-    # Convert ruby sugar to expected value style.
+    # Convert ruby syntax to expected value format.
     def normalize
       {
         'category'    => (->(v) { v.join(';') }),
@@ -194,28 +195,28 @@ module RARBG
 
     # Return or renew auth token.
     def token?
-      if @token.nil? || time >= (@token_time + TOKEN_EXPIRATION)
+      if token.nil? || time >= (token_time.to_f + TOKEN_EXPIRATION)
         response = request(get_token: 'get_token')
         @token = response.fetch('token')
         @token_time = time
       end
-      @token
+      token
     end
 
     # Perform API request.
     def request(params)
       rate_limit!(RATE_LIMIT)
-
-      response = @conn.get(nil, params)
+      response = conn.get(nil, params)
       @last_request = time
 
       return response.body if response.success?
+
       raise APIError, "#{response.reason_phrase} (#{response.status})"
     end
 
     # Rate-limit requests to comply with endpoint limits.
     def rate_limit!(seconds)
-      sleep(0.3) until time >= ((@last_request || 0) + seconds)
+      sleep(0.1) until time >= (last_request.to_f + seconds)
     end
 
     # Monotonic clock for elapsed time calculations.