pexels 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7f9609676bbaebe34889f5c6483f15f41831439eced062f91a7a1eb8fb0c1d8e
-  data.tar.gz: a7be0c896cacd8e3bf02aaf5a87eaee7c0a7c3a17d1118b87f114da208972e0f
+  metadata.gz: 4a5483a85edfd47c6ae8585394c2f14e6de8e8eaf8b149e26594536411a821d4
+  data.tar.gz: '009e00ae30a63f652473bfecd7bc46c5dbfdb839b8c405d1cb5406b7898ce6ae'
 SHA512:
-  metadata.gz: 506d3d399c0cc6655daead44255597131d162808b6b206e32aa7fd60022883703330f2527fb6d092b944ba31a9067b813f6e27f355f7dbc87dcbb3ab95984f2c
-  data.tar.gz: c72ebaa5715f520f74a05941f384bcd1e6db62d45662f07f9a8afbc5236b85c6aa4527a1ccf6f2a74b9d95f36e42fe56c12333ee12411076a8cb6b0170c75105
+  metadata.gz: e55a644d3a0b7ee092796922eb6007d16667b1a5c1d794c66819e896bcde29df05d3129d5f508e48ffb2a54020f36c0fef21d4eb1f18384be0da741d81800012
+  data.tar.gz: e6421cd0f5ac1c92fd57c2af6239a4cb0001db5dcb8fb29349fab688d1508685e9e7ff755d9ffc420bbb365ec3f8fa2ef1fd3409653817aaeafb317833f67040

data/CHANGES.md

@@ -1,5 +1,12 @@
 # Change log
 
+## 0.2.0
+* Fixed incorrect URL for collections endpoints.
+* Added pagination methods `next_page` and `prev_page` to `PaginatedResponse`.
+* Added `total_pages` to `PaginatedResponse`.
+* Extracted `Request` and `Response` objects for reusability.
+* Added `Pexels/Ruby` `User-Agent` header to requests.
+
 ## 0.1.0
 * Add support for returning collections belonging to the API user.
 * Add support for returning media from a collection.

data/README.md

@@ -33,7 +33,9 @@ client.photos.search('Cloud')
 ### Find a specific photo
 
 ```ruby
-client.photos[2014422] || client.photos.find(2014422)
+client.photos[2014422]
+# or
+client.photos.find(2014422)
 ```
 
 ### Browse curated photos
@@ -51,7 +53,9 @@ client.videos.search('waves')
 ### Find a specific photo
 
 ```ruby
-client.videos[2014422] || client.videos.find(2014422)
+client.videos[2014422]
+# or
+client.videos.find(2014422)
 ```
 
 ### Browse popular videos
@@ -60,6 +64,57 @@ client.videos[2014422] || client.videos.find(2014422)
 client.videos.popular
 ```
 
+### List all collections
+
+Note: this is limited to collections belonging to the API user.
+
+```ruby
+client.collections.all
+```
+
+### Get all media for a collection
+
+```ruby
+client.collections['collection-id'].media
+# or
+client.collections.find('collection-id').media
+```
+
+You can also filter for only `photos` or `videos`.
+
+```ruby
+client.collections['collection-id', type: 'photos'].media
+client.collections['collection-id', type: 'videos'].media
+```
+
+## Rate Limiting
+
+After performing a request, you can access your remaining rate limit via the client.
+
+```ruby
+client.ratelimit_remaining
+```
+
+## Pagination
+
+Requests that return multiple objects are paginated. You can pass in `page` and `per_page` options to these requests to get a specific page. You can also access the total number of results by accessing `total_results` on the response. 
+
+Note: The Pexels API returns a maximum of 80 records for one request.
+
+```ruby
+response = client.photos.search('dog', page: 2, per_page: 50)
+response.total_results #=> 1000
+response.total_pages #= 20
+```
+
+If there are further pages, you can also paginate through the API client:
+
+```ruby
+response = client.photos.search('dog', page: 2, per_page: 50)
+response.prev_page # queries page 1
+response.next_page # queries page 3
+```
+
 ## Running the test suite
 
 You'll need your own API key to run the test suite, you can get one on the [Pexels API Key management page](https://www.pexels.com/api/new/)

data/lib/pexels.rb

@@ -23,6 +23,8 @@ module Pexels
 end
 
 require_relative 'pexels/client'
+require_relative 'pexels/client/request'
+require_relative 'pexels/client/response'
 require_relative 'pexels/client/collections'
 require_relative 'pexels/client/photos'
 require_relative 'pexels/client/videos'

data/lib/pexels/client.rb

@@ -1,47 +1,29 @@
-require 'requests'
-
-class Pexels::Client
-  attr_reader :api_key,
-              :ratelimit_remaining
-
-  def initialize(api_key = ENV['PEXELS_API_KEY'])
-    @api_key = api_key
-  end
-
-  def photos
-    @photos ||= Pexels::Client::Photos.new(self)
-  end
-
-  def videos
-    @videos ||= Pexels::Client::Videos.new(self)
-  end
-
-  def collections
-    @collections ||= Pexels::Client::Collections.new(self)
-  end
-
-  def request(path, method: 'GET', params: {})
-    url = File.join(Pexels.api_base_url, path)
-    headers = {
-      'Authorization' => api_key
-    }.merge(Pexels.local_headers)
-
-    puts "Requesting #{url} with #{headers}" if ENV['DEBUG']
-
-    results = Requests.request(
-      method,
-      url,
-      params: params,
-      headers: headers
-    )
-
-    @ratelimit_remaining = results.headers['x-ratelimit-remaining']&.first&.to_i
-
-    return JSON.parse(results.body)
-  rescue StandardError => exception
-    raise Pexels::APIError.new(exception)
+module Pexels
+  class Client
+    attr_reader :api_key,
+                :ratelimit_remaining
+
+    def initialize(api_key = ENV['PEXELS_API_KEY'])
+      @api_key = api_key
+    end
+
+    def photos
+      @photos ||= Pexels::Client::Photos.new(self)
+    end
+
+    def videos
+      @videos ||= Pexels::Client::Videos.new(self)
+    end
+
+    def collections
+      @collections ||= Pexels::Client::Collections.new(self)
+    end
+
+    def request(path, method: 'GET', params: {})
+      request = Request.new(api_key, path, method, params)
+      request.call.tap do |response|
+        @ratelimit_remaining = response.ratelimit_remaining
+      end
+    end
   end
 end
-
-require 'pexels/client/photos'
-require 'pexels/client/videos'

data/lib/pexels/client/collections.rb

@@ -5,7 +5,7 @@ class Pexels::Client::Collections
 
   def all(per_page: 15, page: 1)
     response = @client.request(
-      '/collections',
+      "#{Pexels.api_version}/collections",
       params: {
         per_page: per_page,
         page: page
@@ -16,7 +16,7 @@ class Pexels::Client::Collections
 
   def [](id, type: nil, per_page: 15, page: 1)
     response = @client.request(
-      "/collections/#{id}",
+      "#{Pexels.api_version}/collections/#{id}",
       params: {
         per_page: per_page,
         page: page,

data/lib/pexels/client/photos.rb

@@ -6,7 +6,7 @@ class Pexels::Client::Photos
 
   def [](id)
     response = @client.request("#{Pexels.api_version}/photos/#{id}")
-    Pexels::Photo.new(response)
+    Pexels::Photo.new(response.body)
   end
   alias_method :find, :[]
 

data/lib/pexels/client/request.rb

@@ -0,0 +1,53 @@
+require 'requests'
+
+module Pexels
+  class Client
+    class Request
+      attr_reader :api_key, :path, :method, :params
+
+      def initialize(api_key, path, method, params)
+        @api_key = api_key
+        @path = path
+        @method = method
+        @params = params
+      end
+
+      def call
+        log_request if ENV['DEBUG']
+
+        Response.new(self, execute)
+
+      rescue StandardError => exception
+        raise Pexels::APIError.new(exception)
+      end
+
+      private
+
+      def execute
+        Requests.request(
+          method,
+          url,
+          params: params,
+          headers: headers
+        )
+      end
+
+      def url
+        @url ||= File.join(Pexels.api_base_url, path)
+      end
+
+      def headers
+        @headers = {
+          'Authorization' => api_key,
+          'User-Agent' => "Pexels/Ruby (#{Pexels::VERSION})"
+        }.merge(Pexels.local_headers)
+      end
+
+      def log_request
+        puts "Requesting #{url}"
+        puts " → params: #{params}"
+        puts " → headers: #{headers}"
+      end
+    end
+  end
+end

data/lib/pexels/client/response.rb

@@ -0,0 +1,29 @@
+require 'requests'
+
+module Pexels
+  class Client
+    class Response
+      attr_reader :request, :response
+
+      def initialize(request, response)
+        @request = request
+        @response = response
+      end
+
+      def body
+        JSON.parse(response.body)
+
+      rescue JSON::JSONError => exception
+        raise Pexels::APIError.new(exception)
+      end
+
+      def headers
+        response.headers
+      end
+
+      def ratelimit_remaining
+        headers['x-ratelimit-remaining']&.first&.to_i
+      end
+    end
+  end
+end

data/lib/pexels/client/videos.rb

@@ -6,7 +6,7 @@ class Pexels::Client::Videos
 
   def [](id)
     response = @client.request("/videos/videos/#{id}")
-    Pexels::Video.new(response)
+    Pexels::Video.new(response.body)
   end
   alias_method :find, :[]
 

data/lib/pexels/collection_media_set.rb

@@ -5,7 +5,7 @@ module Pexels
 
     attr_reader :id
 
-    def initialize(attrs)
+    def initialize(response)
       super
       @id = attrs.fetch('id')
       @data = attrs.fetch('media', []).map do |attrs|

data/lib/pexels/collection_set.rb

@@ -3,7 +3,7 @@ module Pexels
     alias_method :collections, :data
     public :collections
 
-    def initialize(attrs)
+    def initialize(response)
       super
       @data = attrs.fetch('collections', []).map { |attrs| Pexels::Collection.new(attrs) }
     end

data/lib/pexels/paginated_response.rb

@@ -1,3 +1,5 @@
+require 'cgi'
+
 module Pexels
   class PaginatedResponse
     include Enumerable
@@ -5,18 +7,25 @@ module Pexels
     attr_reader :total_results,
       :page,
       :per_page,
-      :next_page,
       :data
 
     private :data
 
-    def initialize(attrs)
+    def initialize(response)
+      @response = response
+      @attrs = @response.body
+
       @total_results = attrs.fetch('total_results', nil)
       @page = attrs.fetch('page')
       @per_page = attrs.fetch('per_page')
+      @prev_page = attrs.fetch('prev_page', nil)
       @next_page = attrs.fetch('next_page', nil)
     end
 
+    def total_pages
+      total_results.fdiv(per_page).ceil
+    end
+
     def each(&block)
       if block_given?
         data.each(&block)
@@ -24,5 +33,31 @@ module Pexels
         to_enum(:each)
       end
     end
+
+    def next_page
+      return unless @next_page
+
+      request.params[:page] = extract_page(@next_page)
+      self.class.new(request.call)
+    end
+
+    def prev_page
+      return unless @prev_page
+
+      request.params[:page] = extract_page(@next_page)
+      self.class.new(request.call)
+    end
+
+    private
+
+    attr_reader :response, :attrs
+
+    def request
+      response.request
+    end
+
+    def extract_page(url)
+      CGI.parse(URI.parse(url).query)['page'].first
+    end
   end
 end

data/lib/pexels/photo_set.rb

@@ -3,7 +3,7 @@ module Pexels
     alias_method :photos, :data
     public :photos
 
-    def initialize(attrs)
+    def initialize(response)
       super
       @data = attrs.fetch('photos', []).map { |attrs| Pexels::Photo.new(attrs) }
 

data/lib/pexels/version.rb

@@ -1,3 +1,3 @@
 module Pexels
-  VERSION = '0.1.0'
+  VERSION = '0.2.0'
 end

data/lib/pexels/video_set.rb

@@ -3,7 +3,7 @@ module Pexels
     alias_method :videos, :data
     public :videos
 
-    def initialize(attrs)
+    def initialize(response)
       super
       @data = attrs.fetch('videos', []).map { |attrs| Pexels::Video.new(attrs) }
 

data/pexels.gemspec

@@ -11,5 +11,7 @@ Gem::Specification.new do |s|
   s.license     = 'MIT'
   s.files       = `git ls-files`.split("\n")
 
+  s.required_ruby_version = '>= 2.4.0'
+
   s.add_dependency('requests', '~> 1.0.2')
 end

data/test/client_test.rb

@@ -15,7 +15,7 @@ class TestClient < Minitest::Test
     assert remaining >= 0
 
     @client.photos.search('test')
-    assert_equal remaining, @client.ratelimit_remaining + 1
+    assert_equal @client.ratelimit_remaining, remaining - 1
   end
 
   def test_exceptions
@@ -26,7 +26,7 @@ class TestClient < Minitest::Test
         @client.photos.search('test')
         raise 'this shouldnt happen'
       rescue StandardError => exception
-        assert exception.is_a? Pexels::APIError
+        assert_kind_of Pexels::APIError, exception
         assert exception.message != 'this shouldnt happen'
       end
     end

data/test/collection_test.rb

@@ -9,28 +9,30 @@ class TestCollections < Minitest::Test
   end
 
   def test_all
-    search_result = @client.collections.all
+    collection = @client.collections.all
 
-    assert search_result.is_a? Pexels::CollectionSet
-    assert_equal search_result.per_page, 15
-    assert_equal search_result.page, 1
+    assert_kind_of Pexels::CollectionSet, collection
+    assert_equal collection.per_page, 15
+    assert_equal collection.page, 1
 
-    assert search_result.collections.is_a? Array
-    assert search_result.collections.any?
-    assert search_result.first.is_a? Pexels::Collection
+    assert collection.collections.is_a? Array
+    assert collection.collections.any?
+    assert collection.first.is_a? Pexels::Collection
 
-    search_result_with_params = @client.collections.all(per_page: 1, page: 2)
-    assert_equal search_result_with_params.per_page, 1
-    assert_equal search_result_with_params.page, 2
-    assert_equal search_result_with_params.collections.length, 1
+    collection_with_params = @client.collections.all(per_page: 1, page: 2)
+    assert_equal collection_with_params.per_page, 1
+    assert_equal collection_with_params.page, 2
+    assert_equal collection_with_params.collections.length, 1
+    assert_kind_of Pexels::CollectionSet, collection_with_params.next_page
+    assert_kind_of Pexels::CollectionSet, collection_with_params.prev_page
   end
 
   def test_get_collection_media
     collection = @client.collections[@collection.id]
-    assert collection.is_a? Pexels::CollectionMediaSet
+    assert_kind_of Pexels::CollectionMediaSet, collection
     assert_equal collection.id, @collection.id
 
-    assert collection.media.is_a? Array
+    assert_kind_of Array, collection.media
     assert collection.media.any?
 
     assert_includes([Pexels::Photo, Pexels::Video], collection.media.first.class)
@@ -41,29 +43,29 @@ class TestCollections < Minitest::Test
 
   def test_get_collection_photos
     collection = @client.collections[@collection.id, type: 'photos']
-    assert collection.is_a? Pexels::CollectionMediaSet
-    assert collection.media.is_a? Array
+    assert_kind_of Pexels::CollectionMediaSet, collection
+    assert_kind_of Array, collection.media
     assert collection.media.all? { |m| m.is_a?(Pexels::Photo) }
   end
 
   def test_get_collection_videos
     collection = @client.collections[@collection.id, type: 'videos']
-    assert collection.is_a? Pexels::CollectionMediaSet
-    assert collection.media.is_a? Array
+    assert_kind_of Pexels::CollectionMediaSet, collection
+    assert_kind_of Array, collection.media
     assert collection.media.all? { |m| m.is_a?(Pexels::Video) }
   end
 
   def test_get_collection_invalid_type
     collection = @client.collections[@collection.id, type: 'foo']
-    assert collection.is_a? Pexels::CollectionMediaSet
-    assert collection.media.is_a? Array
+    assert_kind_of Pexels::CollectionMediaSet, collection
+    assert_kind_of Array, collection.media
     assert collection.any?
   end
 
   def test_get_collection_pagination
     collection = @client.collections[@collection.id, per_page: 1, page: 1]
-    assert collection.is_a? Pexels::CollectionMediaSet
-    assert collection.media.is_a? Array
+    assert_kind_of Pexels::CollectionMediaSet, collection
+    assert_kind_of Array, collection.media
     assert collection.media.any?
 
     assert_equal collection.per_page, 1

data/test/photo_test.rb

@@ -11,9 +11,9 @@ class TestPhoto < Minitest::Test
   def test_successful_searches
     search_result = @client.photos.search('test')
 
-    assert search_result.is_a? Pexels::PhotoSet
-    assert search_result.next_page.is_a? String
-    assert search_result.total_results.is_a? Integer
+    assert_kind_of Pexels::PhotoSet, search_result
+    assert_kind_of Pexels::PhotoSet, search_result.next_page
+    assert_kind_of Integer, search_result.total_results
     assert_equal search_result.per_page, 15
     assert_equal search_result.page, 1
 
@@ -25,13 +25,14 @@ class TestPhoto < Minitest::Test
     assert_equal search_result_with_params.per_page, 1
     assert_equal search_result_with_params.page, 2
     assert_equal search_result_with_params.photos.length, 1
+    assert_kind_of Pexels::PhotoSet, search_result_with_params.prev_page
   end
 
   def test_curated_photos
     search_result = @client.photos.curated
 
-    assert search_result.is_a? Pexels::PhotoSet
-    assert search_result.next_page.is_a? String
+    assert_kind_of Pexels::PhotoSet, search_result
+    assert_kind_of Pexels::PhotoSet, search_result.next_page
     assert_equal search_result.per_page, 15
     assert_equal search_result.page, 1
 
@@ -43,6 +44,7 @@ class TestPhoto < Minitest::Test
     assert_equal search_result_with_params.per_page, 1
     assert_equal search_result_with_params.page, 2
     assert_equal search_result_with_params.photos.length, 1
+    assert_kind_of Pexels::PhotoSet, search_result_with_params.prev_page
   end
 
   def test_get_photo

data/test/video_test.rb

@@ -11,8 +11,9 @@ class TestVideo < Minitest::Test
   def test_successful_searches
     search_result = @client.videos.search('test')
 
-    assert search_result.is_a? Pexels::VideoSet
-    assert search_result.total_results.is_a? Integer
+    assert_kind_of Pexels::VideoSet, search_result
+    assert_kind_of Pexels::VideoSet, search_result.next_page
+    assert_kind_of Integer, search_result.total_results
     assert_equal search_result.per_page, 15
     assert_equal search_result.page, 1
 
@@ -24,12 +25,14 @@ class TestVideo < Minitest::Test
     assert_equal search_result_with_params.per_page, 1
     assert_equal search_result_with_params.page, 2
     assert_equal search_result_with_params.videos.length, 1
+    assert_kind_of Pexels::VideoSet, search_result_with_params.prev_page
   end
 
   def test_popular_videos
     search_result = @client.videos.popular
 
-    assert search_result.is_a? Pexels::VideoSet
+    assert_kind_of Pexels::VideoSet, search_result
+    assert_kind_of Pexels::VideoSet, search_result.next_page
     assert_equal search_result.per_page, 15
     assert_equal search_result.page, 1
 
@@ -41,6 +44,7 @@ class TestVideo < Minitest::Test
     assert_equal search_result_with_params.per_page, 1
     assert_equal search_result_with_params.page, 2
     assert_equal search_result_with_params.videos.length, 1
+    assert_kind_of Pexels::VideoSet, search_result_with_params.prev_page
   end
 
   def test_get_video

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: pexels
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Pexels dev team
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-04-09 00:00:00.000000000 Z
+date: 2021-04-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: requests
@@ -42,6 +42,8 @@ files:
 - lib/pexels/client.rb
 - lib/pexels/client/collections.rb
 - lib/pexels/client/photos.rb
+- lib/pexels/client/request.rb
+- lib/pexels/client/response.rb
 - lib/pexels/client/videos.rb
 - lib/pexels/collection.rb
 - lib/pexels/collection_media_set.rb
@@ -73,7 +75,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 2.4.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="