guardian_searcher 0.1.2 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bbf80793abdcb30ddb0acb6ff62cc97bf5d2e230881d2057e391f61c3490fa4e
-  data.tar.gz: c6df4f2b8cd92f9ba2ae7fa29ae57eb3e4ad3d2a7637176e0c1a8ec53b7f654e
+  metadata.gz: e3df7ad5dba2bad5467f4f3b0b09dc360a7e8c2b097dfddbb6bbc126ba997af1
+  data.tar.gz: 700a5915369af7e4313b4e94601d5d68a3e83f164fd3e7f6ef702a26fae8f350
 SHA512:
-  metadata.gz: 6d5779ce66ac3507594a07a52db236e1c581729e8b2b05d27ff11287ef8e9dce7eb69b54a9f80298a0fc2d096d3b952f1eb8fc64d3b389713fbedfd0a8e70720
-  data.tar.gz: de83958f007a38e71bfe15d4637aa645feb2d88e370582cef5de3c4fc67a9daf720fae26bd4062e7a32ce7c6a5921aa42d8d5b57be8af8f51514ec2cd8e3fda9
+  metadata.gz: 3f53981c222f1409b0541b555f07b59dd2aa64847d6680255008ac739f40e2a66669d6dc3be1fe6d012c86bac6fe15aef691577510715a3f573b3a5453bc1d67
+  data.tar.gz: 295dfad1a4a45d31543c264f24a0c76c4e0354fc0b666293b9f810e9727e0b5ea7c5fc4e909e22f8de89ac5e4749fa6d8316e6999d8d4cc082b12b948a0447f5

data/.github/workflows/gem-test.yml

@@ -0,0 +1,28 @@
+---
+name: Guardian Searcher gem test suite
+run-name: ${{ github.actor }} is running the test suite
+on:
+  push:
+    branches: [develop]
+  pull_request:
+    branches: [main]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby-version: ['2.7', '3.0', '3.1', '3.3']
+    steps:
+      - uses: actions/checkout@v3
+      - name: Install Ruby ${{ matrix.ruby-version }}
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby-version }}
+          bundler-cache: true
+      - name: Install dependencies
+        run: bundle install
+      - name: Run tests
+        run: bundle exec rake spec
+
+

data/.gitignore

@@ -11,4 +11,6 @@
 # rspec failure tracking
 Gemfile.lock
 .rspec_status
+.byebug_history
 .DS_Store
+project_context.txt

data/.ruby-version

@@ -0,0 +1 @@
+3.3.1

data/CHANGELOG.md

@@ -1,4 +1,8 @@
 ## [Unreleased]
+- Parse results and return an exception based on the Guardian API response
+
+## [0.1.4] - 2026-06-28
+- Moved API key from URL query string to request header to prevent leakage in logs
 
 ## [0.1.0] - 2022-10-01
 
@@ -7,3 +11,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,12 @@
 # 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.
+[![Gem Version](https://badge.fury.io/rb/guardian_searcher.svg)](https://badge.fury.io/rb/guardian_searcher)
+
+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 +61,93 @@ 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 - remember to check for the response code first - 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
+```
+
+However if you want the gem to take care of the response codes and use its built in errors just use
+
+```ruby
+response = searcher.search('your keyword', { from_date: '2022-10-01', page_size: 10 })
+results = GuardianSearcher::SearchResult.parse_with_codes(response)
+```
+
+This will return a `SearchResult` object or one of the following errors
+
+```ruby
+GuardianUnauthorizedError   # when a 401 is returned
+GuardianBadRequestError     # when a 400 is returned
+GuardianInternalServerError # when a 500 is returned
+GuardianUnknownError        # when an error code is not among the above ones
+```
+
+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,38 +1,72 @@
 # 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, nil, headers)
+    end
 
-      url = @base_uri + "/search?q=#{q}&#{opt}&api-key=#{@api_key}"
-      Faraday.get(url)
+    def search_sections(query, options = {})
+      url = sections_uri + query_string(query, options)
+      Faraday.get(url, nil, headers)
     end
 
-    def search_sections(q, options = {})
-      opt = build_options(options)
-      url = @base_uri + "/sections?q=#{q}&#{opt}&api-key=#{@api_key}"
-      Faraday.get(url)
+    def search_tags(query, options = {})
+      url = tags_uri + query_string(query, options)
+      Faraday.get(url, nil, headers)
+    end
+
+    def search_editions(query, options = {})
+      url = editions_uri + query_string(query, options)
+      Faraday.get(url, nil, headers)
     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}"
+    end
+
     def build_options(options)
       Options.new(options).build_options
     end
+
+    def headers
+      { "api-key" => @api_key }
+    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
+        define_singleton_method("#{attr_name}=".to_sym) do |value|
+          instance_variable_set("@#{attr_name}", value)
+        end
+
+        define_singleton_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,19 +1,21 @@
 # frozen_string_literal: true
 
 module GuardianSearcher
-  class OptionsNotHashError < StandardError; end
-  class OptionsNotSupportedError < StandardError; end
-
+  # the class maps the options passed to the ones needed
+  # by the Guardian API for searching
   class Options < Hash
-    private attr_accessor :options
-
     def method_missing(method_name, *args, &blk)
       return options.[](method_name, &blk) if @options.key?(method_name)
 
       super(method_name, *args, &blk)
     end
 
+    def respond_to_missing?(method_name, *args)
+      @options.key?(method_name) || super(method_name, *args)
+    end
+
     def initialize(options)
+      super
       raise OptionsNotHashError unless options.is_a?(Hash)
 
       @options = options
@@ -27,6 +29,7 @@ module GuardianSearcher
         valid_option?(key)
         opt += "&#{map_option(key)}=#{value}"
       end
+      return opt
     end
 
     def valid_option?(option)
@@ -41,5 +44,9 @@ module GuardianSearcher
         page: "page"
       }[key]
     end
+
+    private
+
+    attr_accessor :options
   end
 end

data/lib/guardian_searcher/search_result.rb

@@ -4,24 +4,45 @@ require "json"
 
 module GuardianSearcher
   class SearchResult
-    attr_reader :results, :start, :page_size, :pages, :current_page
+    attr_reader :results, :start, :page_size, :pages, :current_page, :editions
 
     def initialize(
       current_page: nil,
       results: nil,
       page_size: nil,
       pages: nil,
-      start: nil
+      start: nil,
+      editions: nil
     )
-
       @current_page = current_page
       @results = results
       @page_size = page_size
       @pages = pages
       @start = start
+      @editions = editions
+    end
+
+    def self.parse_with_codes(response: nil)
+      raise GuardianSearcher::GuardianSearcherUndefinedResponse unless response
+
+      case response.status
+      when 200
+        parse_results(body: response.body)
+      when 400
+        message = JSON.parse(response.body)["message"]
+        raise GuardianSearcher::GuardianBadRequestError, message
+      when 401
+        message = JSON.parse(response.body)["message"]
+        raise GuardianSearcher::GuardianUnauthorizedError, message
+      when 500
+        message = JSON.parse(response.body)["message"]
+        raise GuardianSearcher::GuardianInternalServerError, message
+      else
+        raise GuardianSearcher::GuardianUnknownError, "Unknown error, check Faraday response"
+      end
     end
 
-    def self.parse_results(body: nil)
+    def self.parse_results(body:)
       return unless body
 
       body = JSON.parse(body)

data/lib/guardian_searcher/section_result.rb

@@ -3,18 +3,9 @@
 require "json"
 
 module GuardianSearcher
+  # The class parses the search results and creates a new
+  # SearchResults object with an editions variable
   class SectionResult
-    attr_reader :results, :editions
-
-    def initialize(
-      results: nil,
-      editions: nil
-    )
-
-      @results = results
-      @editions = editions
-    end
-
     def self.parse_results(body: nil)
       return unless body
 

data/lib/guardian_searcher/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module GuardianSearcher
-  VERSION = "0.1.2"
+  VERSION = "0.1.4"
 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,11 @@ require_relative "guardian_searcher/options"
 module GuardianSearcher
   class Error < StandardError; end
   class GuardianApyKeyError < StandardError; end
+  class GuardianUnauthorizedError < StandardError; end
+  class GuardianBadRequestError < StandardError; end
+  class GuardianInternalServerError < StandardError; end
+  class GuardianUnknownError < StandardError; end
+  class GuardianSearcherUndefinedResponse < 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.4
 platform: ruby
 authors:
 - Alain Mauri
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-10-04 00:00:00.000000000 Z
+date: 2026-06-29 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
@@ -100,9 +114,11 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".github/workflows/gem-test.yml"
 - ".gitignore"
 - ".rspec"
 - ".rubocop.yml"
+- ".ruby-version"
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - Gemfile
@@ -117,6 +133,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
@@ -144,8 +162,11 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.15
+rubygems_version: 3.5.23
 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: []