guardian_searcher 0.1.1 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 102bea1ce30d48d194d5a647b02e19056a5f050b183e72a56c092aff8a99b892
-  data.tar.gz: 865d25653fdec0b4d3ac1ccb71356397605bb4293ab6bdcb821090b571b2d85e
+  metadata.gz: dd89428bf856036e8d19111810e1a8b0bab64c545db11b6b0779b1f7c7654016
+  data.tar.gz: f485ddd884db4a21c9f75a0961640f46143014cbb392ac7de6e894726964cbce
 SHA512:
-  metadata.gz: 1aaa54fb01c01802fd8e4f71fc922ef517631edeba4978ee8431613fdaf46115b92bdedb76917142bf3bafe8215c8e38d9c9fe84c945471435c501f0f2b938c4
-  data.tar.gz: 5df31cf5ebd052c9a2376261a410f2f2298577c4986663832114ccb7f854f7ba50a1063415402972f2e0a6826a82c04ea1ec7606199a417aed01338d00b62032
+  metadata.gz: d67c795dca8079a6768b8ab9bfd44335fde907c110dac3a4fbd3be20cab9da5e0f2ebf125f41003c936b8d13bc486ce33eae3c0e1232f3bfd6b9cd66229ead45
+  data.tar.gz: 4868618271ecc78d2cfc66c1389bba17504072755a06dbdd563cfa5023450ad0bc5674f09416ca728e915c46f931a65c04a912577c84f4e80035f9a899293943

data/.gitignore

@@ -6,7 +6,10 @@
 /pkg/
 /spec/reports/
 /tmp/
-
+# Ignore built gemfiles
+*.gem
 # rspec failure tracking
 Gemfile.lock
 .rspec_status
+.byebug_history
+.DS_Store

data/CHANGELOG.md

@@ -1,5 +1,6 @@
 ## [Unreleased]
 
+
 ## [0.1.0] - 2022-10-01
 
 - Initial release
@@ -7,3 +8,15 @@
 ## [0.1.1] - 2022-10-01
 
 - Fix dependency warnings
+
+## [0.1.2] - 2022-10-04
+
+- Moved options parse in their Options class
+- Updated readme
+
+## [0.1.3] - 2022-10-23
+
+- Added Content class
+- Added Helpers classes ( Generator & Util)
+- Added some additional methods to Base class - search tags and editons endpoints
+- Improved code coverage (Happy Paths only for now)

data/Guardfile

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # A sample Guardfile
 # More info at https://github.com/guard/guard#readme
 
@@ -14,7 +16,7 @@
 #
 # and, you'll have to watch "config/Guardfile" instead of "Guardfile"
 
-# Note: The cmd option is now required due to the increasing number of ways
+# NOTE: The cmd option is now required due to the increasing number of ways
 #       rspec may be run, below are examples of the most common uses.
 #  * bundler: 'bundle exec rspec'
 #  * bundler binstubs: 'bin/rspec'
@@ -40,7 +42,7 @@ guard :rspec, cmd: "bundle exec rspec" do
   dsl.watch_spec_files_for(ruby.lib_files)
 
   # Rails files
-  rails = dsl.rails(view_extensions: %w(erb haml slim))
+  rails = dsl.rails(view_extensions: %w[erb haml slim])
   dsl.watch_spec_files_for(rails.app_files)
   dsl.watch_spec_files_for(rails.views)
 
@@ -69,12 +71,12 @@ guard :rspec, cmd: "bundle exec rspec" do
 end
 
 guard :bundler do
-  require 'guard/bundler'
-  require 'guard/bundler/verify'
+  require "guard/bundler"
+  require "guard/bundler/verify"
   helper = Guard::Bundler::Verify.new
 
-  files = ['Gemfile']
-  files += Dir['*.gemspec'] if files.any? { |f| helper.uses_gemspec?(f) }
+  files = ["Gemfile"]
+  files += Dir["*.gemspec"] if files.any? { |f| helper.uses_gemspec?(f) }
 
   # Assume files are symlinked from somewhere
   files.each { |file| watch(helper.real_path(file)) }

data/README.md

@@ -1,8 +1,11 @@
 # GuardianSearcher
 
-This is a work in progress, and its status is currently not even an alpha version. Tests needs to be implemented and the code is not optimal.
+
+This is a work in progress, and its status is currently an alpha version. Tests needs to be implemented and the code is not optimal.
 The goal of this project is to provide a Ruby wrapper to query the Guardian Api and to experiment with some programming techniques.
 
+Documentation of TheGuardian API is [Here](https://open-platform.theguardian.com/documentation/)
+
 If you wanna try it you need to have an API key and use it as an environment variable.
 
 ```bash
@@ -26,7 +29,107 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+```ruby
+  # To include the gem in your code
+  require 'guardian_searcher'
+
+  # To initialise the gem
+  searcher = GuardianSearcher::Search.new(api_key: <your-api-key>)
+
+  # Simplest usage
+  results = searcher.search('your keyword') 
+```
+
+There are some supported option that will be mapped to the api query and these are in the Options
+class
+
+```ruby
+{
+  from_date: "from-date",
+  to_date: "to-date",
+  page_size: "page-size",
+  page: "page"
+}
+```
+
+In this way your search could become something like
+
+```ruby
+results = searcher.search('your keyword', { from_date: '2022-10-01', page_size: 10 })
+```
+
+If you add something unsupported it will throw an `OptionsNotSupportedError`
+
+The results of the search can be used as they are, a Farady response object or you can parse them using `GuardianSearcher::SearchResult` in the following way:
+
+```ruby
+response_body = searcher.search('your keyword', { from_date: '2022-10-01', page_size: 10 }).body
+results = GuardianSearcher::SearchResult.parse_results(body: response_body)
+```
+This will return a `SearchResult` object which the following attributes:
+
+```ruby
+@current_page
+@results # an array with all the search results
+@page_size # paging size
+@pages # number of pages
+@start # starting page
+```
+
+Of interest the structure of a single element of the results array, which is an Hash array similar to this
+
+```ruby
+{"id"=>"football/2022/sep/23/player-mutiny-exposes-deeper-issues-within-spanish-womens-football",
+    "type"=>"article",
+    "sectionId"=>"football",
+    "sectionName"=>"Football",
+    "webPublicationDate"=>"2022-09-23T19:20:09Z",
+    "webTitle"=>"Player mutiny exposes deeper issues within Spanish women’s football | Sid Lowe",
+    "webUrl"=>"https://www.theguardian.com/football/2022/sep/23/player-mutiny-exposes-deeper-issues-within-spanish-womens-football",
+    "apiUrl"=>"https://content.guardianapis.com/football/2022/sep/23/player-mutiny-exposes-deeper-issues-within-spanish-womens-football",
+    "isHosted"=>false,
+    "pillarId"=>"pillar/sport",
+    "pillarName"=>"Sport"}
+```
+At this point you can use the `SearchResult` object as it is or you could convert it to an Array of `Content` objects in the following way:
+```ruby
+generator = GuardianSearcher::Helpers::Generator.new
+# results is the SearchResult object created before which has an attribute
+# called results. Not a great name choice but sorry about that
+contents = generator.generate(results.results, "GuardianSearcher::Content")
+```
+
+Each element of the `contents` Array will be an instance of the `Content` class, with a number of attributes that depends on the returned results i.e. that
+if an element of the results attribute is something like:
+```ruby
+{"id"=>"football/2022/jun/27/football-transfer-rumours-chelsea-to-sign-matthijs-de-ligt-from-juventus",
+    "type"=>"article",
+    "sectionId"=>"football",
+    "sectionName"=>"Football",
+    "webPublicationDate"=>"2022-06-27T08:42:20Z",
+    "webTitle"=>"Football transfer rumours: Chelsea to sign Matthijs de Ligt from Juventus? ",
+    "webUrl"=>"https://www.theguardian.com/football/2022/jun/27/football-transfer-rumours-chelsea-to-sign-matthijs-de-ligt-from-juventus",
+    "apiUrl"=>"https://content.guardianapis.com/football/2022/jun/27/football-transfer-rumours-chelsea-to-sign-matthijs-de-ligt-from-juventus",
+    "isHosted"=>false,
+    "pillarId"=>"pillar/sport",
+    "pillarName"=>"Sport"}
+```
+One element of the `contents` array will be something like:
+
+```ruby
+<GuardianSearcher::Content:0x0000000150b7fe70
+  @api_url="https://content.guardianapis.com/football/2022/jun/27/football-transfer-rumours-chelsea-to-sign-matthijs-de-ligt-from-juventus",
+  @id="football/2022/jun/27/football-transfer-rumours-chelsea-to-sign-matthijs-de-ligt-from-juventus",
+  @is_hosted=false,
+  @pillar_id="pillar/sport",
+  @pillar_name="Sport",
+  @section_id="football",
+  @section_name="Football",
+  @type="article",
+  @web_publication_date="2022-06-27T08:42:20Z",
+  @web_title="Football transfer rumours: Chelsea to sign Matthijs de Ligt from Juventus? ",
+  @web_url="https://www.theguardian.com/football/2022/jun/27/football-transfer-rumours-chelsea-to-sign-matthijs-de-ligt-from-juventus">
+```
 
 ## Development
 

data/guardian_searcher.gemspec

@@ -8,7 +8,10 @@ Gem::Specification.new do |spec|
   spec.authors       = "Alain Mauri"
   spec.email         = "wildeng@hotmail.com"
 
-  spec.summary       = "A wrapper to search articles from The Guardian"
+  spec.summary       = "A wrapper to search articles from The Guardian, using its open API.
+    You need to register and get your api key to properly use this gem.
+    It uses Faraday to make the API calls and has some classes that should help in formatting
+    the results as easy to manage Ruby object."
   spec.homepage      = "https://alainmauri.eu"
   spec.license       = "MIT"
   spec.required_ruby_version = Gem::Requirement.new(">= 2.7.0")
@@ -30,10 +33,12 @@ Gem::Specification.new do |spec|
   # spec.add_dependency "example-gem", "~> 1.0"
   spec.add_dependency "faraday", "~> 2.2"
 
-  spec.add_development_dependency 'vcr', "~> 6.1"
-  spec.add_development_dependency 'guard', "~> 2.18"
-  spec.add_development_dependency 'guard-bundler', "~> 3.0"
-  spec.add_development_dependency 'guard-rspec', "~> 4.7"
+  spec.add_development_dependency "byebug", "~> 11"
+  spec.add_development_dependency "guard", "~> 2.18"
+  spec.add_development_dependency "guard-bundler", "~> 3.0"
+  spec.add_development_dependency "guard-rspec", "~> 4.7"
+  spec.add_development_dependency "simplecov", "~> 0.21"
+  spec.add_development_dependency "vcr", "~> 6.1"
   # For more information and examples about making a new gem, checkout our
   # guide at: https://bundler.io/guides/creating_gem.html
 end

data/lib/guardian_searcher/base.rb

@@ -1,42 +1,68 @@
 # frozen_string_literal: true
 
 module GuardianSearcher
+  # Class that handles the basic functionality for the Guardian Reader gem
   class Base
     include Faraday
+
     attr_reader :api_key
-    attr_accessor :base_uri
 
     def initialize(api_key: nil)
-      @base_uri = "https://content.guardianapis.com"
-
       raise GuardianApyKeyError unless api_key
 
       @api_key = api_key
     end
 
     # Options needs to be passed following Guardian API docs
-    def search(q, options = {})
-      opt = build_options(options)
+    def search(query, options = {})
+      url = search_uri + query_string(query, options)
+      Faraday.get(url)
+    end
 
-      url = @base_uri + "/search?q=#{q}&#{opt}&api-key=#{@api_key}"
+    def search_sections(query, options = {})
+      url = sections_uri + query_string(query, options)
       Faraday.get(url)
     end
 
-    def search_sections(q, options = {})
-      opt = build_options(options)
-      url = @base_uri + "/sections?q=#{q}&#{opt}&api-key=#{@api_key}"
+    def search_tags(query, options = {})
+      url = tags_uri + query_string(query, options)
+      Faraday.get(url)
+    end
+
+    def search_editions(query, options = {})
+      url = editions_uri + query_string(query, options)
       Faraday.get(url)
     end
 
     private
 
-    def build_options(options)
-      return {} if options.empty?
+    def base_uri
+      "https://content.guardianapis.com"
+    end
 
-      opt = ""
-      options.each do |key, value|
-        opt += "&#{key}=#{value}"
-      end
+    def sections_uri
+      "#{base_uri}/sections"
+    end
+
+    def search_uri
+      "#{base_uri}/search"
+    end
+
+    def tags_uri
+      "#{base_uri}/tags"
+    end
+
+    def editions_uri
+      "#{base_uri}/editions"
+    end
+
+    def query_string(q, options = {})
+      opt = build_options(options)
+      "?q=#{q}&#{opt}&api-key=#{@api_key}"
+    end
+
+    def build_options(options)
+      Options.new(options).build_options
     end
   end
 end

data/lib/guardian_searcher/content.rb

@@ -1,6 +1,22 @@
 # frozen_string_literal: true
 
 module GuardianSearcher
-  class Content < GuardianSearcher::Base
+  class Content
+    include GuardianSearcher::Helpers::Util
+    def initialize(attributes)
+      attributes.each do |key, attribute_value|
+        attr_name = key
+        attr_name = snakecase(key) unless key.is_a? Symbol
+        self.class.send(:define_method, "#{attr_name}=".to_sym) do |value|
+          instance_variable_set("@#{attr_name}", value)
+        end
+
+        self.class.send(:define_method, attr_name.to_sym) do
+          instance_variable_get("@#{attr_name}")
+        end
+
+        send("#{attr_name}=".to_sym, attribute_value)
+      end
+    end
   end
 end

data/lib/guardian_searcher/helpers/generator.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module GuardianSearcher
+  module Helpers
+    # The class helps generating an array of object from the passed parameters
+    # It can be used to generate e.g. an array of Content objects, each one
+    # initialised with the data of a single results Hash coming from the Guardian
+    # API response
+    class Generator
+      def generate(results, klass)
+        content = []
+        results.each do |result|
+          content << Object.const_get(klass).new(result)
+        end
+        content
+      end
+    end
+  end
+end

data/lib/guardian_searcher/helpers/util.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module GuardianSearcher
+  module Helpers
+    module Util
+      # this method comes from the facets library
+      # I took it from there because it was easier for
+      # what I have in mind
+      #
+      # original here https://github.com/rubyworks/facets
+      # docs here https://www.rubydoc.info/github/rubyworks/facets/String:snakecase
+      def snakecase(key)
+        return unless key.is_a? String
+
+        key.gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+           .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+           .tr("-", "_")
+           .gsub(/\s/, "_")
+           .gsub(/__+/, "_")
+           .downcase
+      end
+    end
+  end
+end

data/lib/guardian_searcher/options.rb

@@ -1,18 +1,42 @@
-module GuardianSearcher
-  class OptionsNotHashError < StandardError; end
-  class OptionsNotSupportedError < StandardError; end
+# frozen_string_literal: true
 
+module GuardianSearcher
   class Options < Hash
     private attr_accessor :options
 
     def method_missing(method_name, *args, &blk)
-      return self.options.[](method_name, &blk) if @options.has_key?(method_name)
+      return options.[](method_name, &blk) if @options.key?(method_name)
+
       super(method_name, *args, &blk)
     end
-    
+
     def initialize(options)
       raise OptionsNotHashError unless options.is_a?(Hash)
+
       @options = options
     end
+
+    def build_options
+      return {} if options.empty?
+
+      opt = ""
+      options.each do |key, value|
+        valid_option?(key)
+        opt += "&#{map_option(key)}=#{value}"
+      end
+    end
+
+    def valid_option?(option)
+      raise OptionsNotSupportedError unless %i[from_date to_date page_size page].include?(option)
+    end
+
+    def map_option(key)
+      {
+        from_date: "from-date",
+        to_date: "to-date",
+        page_size: "page-size",
+        page: "page"
+      }[key]
+    end
   end
 end

data/lib/guardian_searcher/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module GuardianSearcher
-  VERSION = "0.1.1"
+  VERSION = "0.1.3"
 end

data/lib/guardian_searcher.rb

@@ -3,6 +3,9 @@
 require_relative "guardian_searcher/version"
 require "faraday"
 require_relative "guardian_searcher/base"
+require_relative "guardian_searcher/helpers/util"
+require_relative "guardian_searcher/helpers/generator"
+require_relative "guardian_searcher/content"
 require_relative "guardian_searcher/search"
 require_relative "guardian_searcher/search_result"
 require_relative "guardian_searcher/section_result"
@@ -11,4 +14,6 @@ require_relative "guardian_searcher/options"
 module GuardianSearcher
   class Error < StandardError; end
   class GuardianApyKeyError < StandardError; end
+  class OptionsNotHashError < StandardError; end
+  class OptionsNotSupportedError < StandardError; end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: guardian_searcher
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.3
 platform: ruby
 authors:
 - Alain Mauri
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-10-01 00:00:00.000000000 Z
+date: 2022-10-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -25,19 +25,19 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '2.2'
 - !ruby/object:Gem::Dependency
-  name: vcr
+  name: byebug
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '6.1'
+        version: '11'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '6.1'
+        version: '11'
 - !ruby/object:Gem::Dependency
   name: guard
   requirement: !ruby/object:Gem::Requirement
@@ -80,6 +80,34 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '4.7'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.21'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.21'
+- !ruby/object:Gem::Dependency
+  name: vcr
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.1'
 description:
 email: wildeng@hotmail.com
 executables: []
@@ -103,6 +131,8 @@ files:
 - lib/guardian_searcher.rb
 - lib/guardian_searcher/base.rb
 - lib/guardian_searcher/content.rb
+- lib/guardian_searcher/helpers/generator.rb
+- lib/guardian_searcher/helpers/util.rb
 - lib/guardian_searcher/options.rb
 - lib/guardian_searcher/search.rb
 - lib/guardian_searcher/search_result.rb
@@ -133,5 +163,8 @@ requirements: []
 rubygems_version: 3.2.15
 signing_key:
 specification_version: 4
-summary: A wrapper to search articles from The Guardian
+summary: A wrapper to search articles from The Guardian, using its open API. You need
+  to register and get your api key to properly use this gem. It uses Faraday to make
+  the API calls and has some classes that should help in formatting the results as
+  easy to manage Ruby object.
 test_files: []