guardian_searcher 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bbf80793abdcb30ddb0acb6ff62cc97bf5d2e230881d2057e391f61c3490fa4e
-  data.tar.gz: c6df4f2b8cd92f9ba2ae7fa29ae57eb3e4ad3d2a7637176e0c1a8ec53b7f654e
+  metadata.gz: dd89428bf856036e8d19111810e1a8b0bab64c545db11b6b0779b1f7c7654016
+  data.tar.gz: f485ddd884db4a21c9f75a0961640f46143014cbb392ac7de6e894726964cbce
 SHA512:
-  metadata.gz: 6d5779ce66ac3507594a07a52db236e1c581729e8b2b05d27ff11287ef8e9dce7eb69b54a9f80298a0fc2d096d3b952f1eb8fc64d3b389713fbedfd0a8e70720
-  data.tar.gz: de83958f007a38e71bfe15d4637aa645feb2d88e370582cef5de3c4fc67a9daf720fae26bd4062e7a32ce7c6a5921aa42d8d5b57be8af8f51514ec2cd8e3fda9
+  metadata.gz: d67c795dca8079a6768b8ab9bfd44335fde907c110dac3a4fbd3be20cab9da5e0f2ebf125f41003c936b8d13bc486ce33eae3c0e1232f3bfd6b9cd66229ead45
+  data.tar.gz: 4868618271ecc78d2cfc66c1389bba17504072755a06dbdd563cfa5023450ad0bc5674f09416ca728e915c46f931a65c04a912577c84f4e80035f9a899293943

data/.gitignore

@@ -11,4 +11,5 @@
 # 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/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
@@ -57,6 +60,77 @@ results = searcher.search('your keyword', { from_date: '2022-10-01', page_size:
 
 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
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

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,6 +33,7 @@ Gem::Specification.new do |spec|
   # spec.add_dependency "example-gem", "~> 1.0"
   spec.add_dependency "faraday", "~> 2.2"
 
+  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"

data/lib/guardian_searcher/base.rb

@@ -1,36 +1,66 @@
 # 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 base_uri
+      "https://content.guardianapis.com"
+    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

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,9 +1,6 @@
 # frozen_string_literal: true
 
 module GuardianSearcher
-  class OptionsNotHashError < StandardError; end
-  class OptionsNotSupportedError < StandardError; end
-
   class Options < Hash
     private attr_accessor :options
 

data/lib/guardian_searcher/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module GuardianSearcher
-  VERSION = "0.1.2"
+  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.2
+  version: 0.1.3
 platform: ruby
 authors:
 - Alain Mauri
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-10-04 00:00:00.000000000 Z
+date: 2022-10-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -24,6 +24,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.2'
+- !ruby/object:Gem::Dependency
+  name: byebug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '11'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '11'
 - !ruby/object:Gem::Dependency
   name: guard
   requirement: !ruby/object:Gem::Requirement
@@ -117,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
@@ -147,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: []