poms 1.2.2 → 2.0.0.a

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2cf1cb8d138dfb0cc64941c91166579039374f9f
-  data.tar.gz: 211325fcdf33276731f6955fff221311b3678e50
+  metadata.gz: f7ebd9df85593c5327fcc07f65eb00d38a8639a0
+  data.tar.gz: 652743af2c085d204cbf078138e1a20e2e5ffbb9
 SHA512:
-  metadata.gz: 943723499c03b7dfa58465c365d07787aede3b30d710332bbc6c046fce03f6050ece00da032c9416c41e09383668e69bf0ff9ea9c5b5be6bcae153765b75aab7
-  data.tar.gz: e73de97e4ef76cfd6db078e671d2ced5c4582e5021ec5132041e76fdee3246d86625a72fe83981c5174079fd9509eaf46f17becc12b706c04f634256833fa44d
+  metadata.gz: abadd1025995b03d9aefba6dd42e773de7dfc53b4afd16992cfec2bdb9eb438de2c201436cffee1f76d10d0b732c86990a6686c6b7ca45f8ec611bdb8e1dd1d3
+  data.tar.gz: 6c5b371f5e6f9d2ff52b97f13bd0b75a8cbfe19aa936f6f36539ca228853bbfb508028afcb65f5df9b08e11cf7edea3e6f3e49299536227eba00f0c86620b976

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.rubocop.yml

@@ -0,0 +1,24 @@
+require: rubocop-rspec
+
+AllCops:
+  Exclude:
+    - bin/*
+    - poms.gemspec
+
+Style/Documentation:
+  Exclude:
+    - 'lib/poms/has_ancestors.rb'
+    - spec/**/*_spec.rb
+
+Style/BlockDelimiters:
+  Exclude:
+    - 'spec/**/*.rb'
+
+Style/AndOr:
+  Exclude:
+    - 'lib/poms.rb' # here we do rely on how `or` has lower precedence than `||`
+    - 'lib/poms/configuration.rb' # here we do rely on how `or` has lower precedence than `||`
+
+ModuleLength:
+  Exclude:
+    - spec/**/*_spec.rb # specs are only in module for easier access to functions

data/.ruby-version

@@ -0,0 +1 @@
+2.3.0

data/.todo.reek

@@ -0,0 +1,50 @@
+---
+UncommunicativeVariableName:
+  exclude:
+  - Poms::Fields#available_until
+  - Poms::Fields#odi_streams
+  - Poms::MergedSeries#serie_mids
+  - Poms
+DuplicateMethodCall:
+  exclude:
+  - Poms::Api::Client#handle_response
+  - Poms::Api::RequestExecution#headers
+  - Poms::Builderless::Clip#position
+  - Poms::Builderless::Clip#video_url
+  - Poms::Field
+UtilityFunction:
+  exclude:
+  - Poms::Api::RequestExecution#execute_ssl_request
+  - Poms::Fields
+NilCheck:
+  exclude:
+  - Poms::Fields#odi_streams
+TooManyStatements:
+  exclude:
+  - Poms::Fields#odi_streams
+  - Poms::Api::Auth#sign
+  - Poms::Api::Drivers::NetHttp#attempt_request
+  - Poms::Api::PaginationClient#execute
+LongParameterList:
+  exclude:
+  - Poms::MergedSeries#serie_mids
+  - Poms::Api::Client#post
+  - Poms::Api::JsonClient#post
+FeatureEnvy:
+  exclude:
+  - Poms#first
+  - Poms::Api::Client#handle_response
+  - Poms::Api::Drivers::NetHttp#attempt_request
+  - Poms::Api::Drivers::NetHttp#execute
+  - Poms::Api::Drivers::NetHttp#prepare_request
+  - Poms::Api::Drivers::NetHttp#request_to_net_http_request
+  - Poms::Api::PaginationClient#execute
+NestedIterators:
+  exclude:
+  - Poms::Api::PaginationClient#execute
+Attribute:
+  exclude:
+  - Poms::Configuration#base_uri
+  - Poms::Configuration#key
+  - Poms::Configuration#secret
+  - Poms::Configuration#origin

data/CHANGELOG.md

@@ -3,6 +3,7 @@
 ## 1.2.2
 
 * Fix issue with description type that did not exist.
+* Add some more specs to the field classes to catch values that are empty.
 
 ## 1.2.1
 

data/Gemfile

@@ -2,3 +2,7 @@ source 'https://rubygems.org'
 
 # Specify your gem's dependencies in poms.gemspec
 gemspec
+
+group :development, :test do
+  require 'pry'
+end

data/README.md

@@ -1,7 +1,9 @@
+[ ![Codeship Status for brightin/poms](https://codeship.com/projects/c2baf9b0-ea8d-0132-2258-628e55ad70cc/status?branch=master)](https://codeship.com/projects/83157)
+
 # Poms
 
 The Poms gem provides an interface to the Dutch public broadcaster API: POMS. It
-is a couchdb service that is publicly available.
+reads from the Frontend API.
 
 ## Installation
 
@@ -17,17 +19,63 @@ Or install it yourself as:
 
     $ gem install poms
 
+## Configuration
+
+The Poms API is only accessible to authenticated accounts. In order to make authenticated requests to the service, the module needs to be configured before making requests. This can be done in a Rails initializer for instance.
+
+In order to configure the module:
+
+    Poms.configure do |config|
+      config.key    = '**poms key**'
+      config.origin = '**poms origin**'
+      config.secret = '**poms secret**'
+    end
+
+`configure` can also read environment variables. `ENV['POMS_KEY']`,  `ENV['POMS_ORIGIN']`, `ENV['POMS_SECRET']` are used in this case.
+
+The `configure` function can also be provided with the `base_url` in case you want to access the test environment for instance.
+
 ## Usage
 
-The `Poms` module contains various ways to query the Poms CouchDB service. The simplest way to get something is to use the `fetch` function, which takes a MID.
+The `Poms` module contains various ways to interact with the Poms service based on the API it exposes. The simplest way to get something is to use the `first` of `first!` function, which takes a MID (Media ID) used internally to identify all objects.
+
+    Poms.first('mid')
+
+This returns a Hash of the json of the response provided by the Poms service. In this case this is a single object from Poms.
+
+In order to do more advanced querying you might want to get the members or descendants of an object. `members` simply returns all objects that are members of the object with the requested mid.
+
+    Poms.members('mid')
+
+The result is a lazy enumerator (as the results are paginated on Poms) that contains all the members.
+
+The `descendants` function allows query parameters to be entered that are taken in account by the Poms service.
+
+    Poms.descendants('mid', {})
+
+The result is similar to the members function, but each item contains metadata from the search query and the actual result is in the `result` key of the item hash.
+
+The `poms` module contains a number of other functions that may be useful when you want to get some specific info from Poms. Also take a look at the examples in the `examples` directory of this project.
+
+## Fields
+
+The hashes that are returned from Poms can be nested to a high degree, making it harder to get some specific fields from them. The `Poms::Fields` module provides helper functions to access things like title, descriptions and images.
+
+    Poms::Fields.title(poms_item)
+
+This will return the title with the `MAIN` type.
 
-    Poms.fetch('mid')
+## Searching
 
-This returns an OpenStruct-like object that wraps the json of the Poms response.
+For reference of possible search options, see the [POMS API wiki](http://wiki.publiekeomroep.nl/display/npoapi/Media-+en+gids-API).
 
-For some more advanced querying, you can use functions like `fetch_clip` which also takes a MID, but returns a `Clip` object, that is a little easier to work with.
+For Ruby we try to adhere to conventional naming and we map this to the relevant Poms API fields.
 
-You can also query collections in a way to get back multiple episodes. This is tied to the views in the Poms CouchDB service and is documented on the wiki of the NPO.
+Gem | API
+---|---
+`starts_at` | `"sortDates": { "begin" } `
+`ends_at` | `"sortDates": { "end" } `
+`type` | `{ "facets": { "subsearch": { "types" } } }`
 
 ## Contributing
 

data/bin/ci-run

@@ -0,0 +1,57 @@
+#!/bin/bash --login
+#
+# Usage: bin/ci-run [--help|--job N]
+#
+# Run all tasks required for a Continuous Integration job. Also see ci-setup.
+#
+# Options:
+#
+#   --job N May be used for CI parallelisation. Use this number to do only part
+#           of the usual work, for example by invoking different test scripts.
+#   --help  Display this message.
+#
+# Examples:
+#
+#   Run all the tests for this project:
+#
+#     bin/ci-run
+#
+#   Run only part of the test suite:
+#
+#     bin/ci-run --job 1
+
+set -e
+
+# Run the actual tests for this project. The exit code of this function is
+# determines the outcome of the CI build.
+#
+# TODO adapt the Rake command invokation below into something that makes sense for
+#      your particular project.
+run_tests() {
+  # RVM is not activated in non-login shells, so we do so manually.
+  RUBY_VERSION=$(cat .ruby-version)
+  echo "Using Ruby $RUBY_VERSION"
+  source $(rvm $RUBY_VERSION do rvm env --path)
+
+  set -x
+  bundle exec rubocop
+  bundle exec reek
+  bundle exec rspec
+}
+
+# Print help for this script by printing its top comment block (without the
+# comment markers).
+show_help() {
+  awk '/^# Usage/,/^$/' $0 | cut -c 3-
+  exit 1
+}
+
+if [[ $# -ge 1 ]]
+then
+  case $1 in
+    "--job" ) run_tests $2;;
+    * )       show_help;;
+  esac
+else
+  run_tests
+fi

data/bin/ci-setup

@@ -0,0 +1,46 @@
+#!/bin/bash --login
+#
+# Usage: bin/ci-setup [--help]
+#
+# Set up a Codeship CI VM for running a test suite. Also see ci-run.
+#
+# Options:
+#
+#   --help  Display this message.
+
+set -e
+
+# Perform the steps necessary to set up the CI environment for testing. This
+# should include languages, services, package managers, environment, etc.
+setup() {
+  set -x
+  # Read the required version of Ruby from the Gemfile and use RVM to install it
+  rvm use $(cat .ruby-version) --install
+
+  # To use Node.js as Javascript runtime, uncomment the following lines.
+  # nvm install 0.12
+  # nvm use 0.12
+
+  # If the project has a package.json file and javascript dependencies, you can
+  # install them here.
+  # npm install
+
+  # Install Ruby dependencies with Bundler.
+  bundle install
+
+  set +x
+}
+
+# Print help for this script by printing its top comment block (without the
+# comment markers).
+show_help() {
+  awk '/^# Usage/,/^$/' $0 | cut -c 3-
+  exit 1
+}
+
+if [[ $# -ge 1 ]]
+then
+  show_help
+else
+  setup
+fi

data/bin/reek

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+#
+# This file was generated by Bundler.
+#
+# The application 'reek' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require "pathname"
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("reek", "reek")

data/bin/rspec

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+#
+# This file was generated by Bundler.
+#
+# The application 'rspec' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require "pathname"
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("rspec-core", "rspec")

data/bin/rubocop

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+#
+# This file was generated by Bundler.
+#
+# The application 'rubocop' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require "pathname"
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("rubocop", "rubocop")

data/examples/fetch.rb

@@ -0,0 +1,16 @@
+require 'poms'
+
+# Initialize poms with the correct credentials
+Poms.configure do |config|
+  config.key    = '**poms key**'
+  config.origin = '**poms origin**'
+  config.secret = '**poms secret**'
+end
+
+# Get a single entity from POMS by mid
+Poms.first('POMS_S_NTR_2342303')
+# => A hash representing the data corresponding to the given MID
+
+# Fetch multiple entities
+Poms.fetch(%w(WO_TELEAC_003061 POMS_EO_622912))
+# => An array of hashes representing data corresponding to those MIDs

data/examples/search.rb

@@ -0,0 +1,17 @@
+require 'poms'
+
+# You can build a search params hash using Poms::Api::Search
+query = Poms::Api::Search.build(starts_at: Time.now, ends_at: 2.weeks.from_now)
+
+# And use it to query the poms API
+Poms.descendants('VPWON_1251179', query)
+# => Returns all media that is a descendant of the media by the given mid, and
+# was broadcasted between now and next week
+
+# This example will fetch all media that is of type "BROADCAST"
+query = Poms::Api::Search.build(starts_at: Time.now, type: 'BROADCAST')
+
+# Use it
+Poms.descendants('VPWON_1251179', query)
+# => Returns all media that is a descendant of the media by the given mid, has
+# not aired yet and is a broadcast

data/lib/poms.rb

@@ -1,184 +1,112 @@
-require 'active_support'
-require 'open-uri'
+require 'active_support/all'
+require 'poms/api/uris'
+require 'poms/api/json_client'
+require 'poms/api/pagination_client'
+require 'poms/errors'
+require 'poms/api/search'
+require 'poms/configuration'
 require 'json'
-require 'poms/base'
-require 'poms/version'
-require 'poms/builder'
-require 'poms/schedule_event'
-require 'poms/broadcast'
-require 'poms/season'
-require 'poms/series'
-require 'poms/views'
-require 'poms/fields'
-require 'poms/timestamp'
-require 'poms/builderless/broadcast'
-require 'poms/builderless/clip'
-require 'poms/merged_series'
-require 'poms/poms_error'
 
-# Module that allows interfacing with the POMS CouchDB service.
-# rubocop:disable Metrics/ModuleLength
+# Main interface for the POMS gem
+#
+# Strategy
+# 1 -- Build a request object that can be executed
+#      (PostRequest || GetRequest object)
+# 2 -- Execute the request. Retry on failures (max 10?)
+# 3 -- Parse responded JSON. Extract fields if necessary
 module Poms
-  extend self
+  module_function
 
-  URL = 'http://docs.poms.omroep.nl'
-  MEDIA_PATH = '/media/'
-  BROADCASTS_VIEW_PATH =
-    '/media/_design/media/_view/broadcasts-by-broadcaster-and-start'
-  ANCESTOR_AND_TYPE_PATH = '/media/_design/media/_view/by-ancestor-and-type'
-  ANCESTOR_AND_SORTDATE_PATH =
-    '/media/_design/media/_view/by-ancestor-and-sortdate'
-  CHANNEL_AND_START_PATH =
-    '/media/_design/media/_view/broadcasts-by-channel-and-start'
-  VALID_CHANNELS = /^NED(1|2|3)$/
-
-  def fetch(mid)
-    return nil if mid.nil?
-    hash = fetch_raw_json mid
-    Builder.process_hash hash
-  end
-
-  def fetch_clip(mid)
-    clip_hash = fetch_raw_json(mid)
-    Builderless::Clip.new(clip_hash)
-  end
-
-  def fetch_playlist_clips(mid)
-    uri = Views.by_group(mid)
-    playlist_hash = get_bare_json(uri)
-    playlist_hash['rows'].map do |hash|
-      Builderless::Clip.new(hash['doc'])
+  def configure
+    @config = Configuration.new do |config|
+      yield config if block_given?
     end
+    nil
   end
 
-  def fetch_raw_json(mid)
-    uri = [MEDIA_PATH, mid].join
-    get_json(uri)
-  end
-
-  alias_method :fetch_broadcast, :fetch_raw_json
-
-  def fetch_group(mid)
-    uri = Views.by_group(mid)
-    get_bare_json(uri)
-  end
-
-  def upcoming_broadcasts(zender, start_time = Time.now,
-                          end_time = Time.now + 7.days)
-    view_params = broadcast_view_params(zender, start_time, end_time)
-    uri = [BROADCASTS_VIEW_PATH, view_params].join
-    hash = get_json(uri)
-    hash['rows'].map { |item| Builder.process_hash item['doc'] }
-  end
-
-  def fetch_descendants_for_serie(mid, type = 'BROADCAST')
-    uri = Views.descendants_by_type(mid, type)
-    hash = get_bare_json(uri) || { 'rows' => [] }
-    hash['rows'].map { |item| Builder.process_hash item['doc'] }
-  end
-
-  alias_method :fetch_broadcasts_for_serie, :fetch_descendants_for_serie
-
-  def fetch_descendants_by_date_for_serie(mid, start_time = 1.week.ago)
-    view_params = ancestor_sortdate_params(mid, start_time)
-    uri = [ANCESTOR_AND_SORTDATE_PATH, view_params].join
-    hash = get_json(uri) || { 'rows' => [] }
-    hash['rows'].map { |item| Builder.process_hash item['doc'] }
-  end
-
-  def fetch_descendant_mids(mid, type = 'BROADCAST')
-    uri = Views.descendants_by_type(mid, type, include_docs: false)
-    hash = get_bare_json(uri) || { 'rows' => [] }
-    hash['rows'].map { |item| item['id'] }
-  end
-
-  def fetch_broadcasts_by_channel_and_start(channel, start_time = 1.week.ago,
-                                            end_time = Time.now)
-    view_params = channel_params(channel, start_time, end_time)
-    uri = [CHANNEL_AND_START_PATH, view_params].join
-    hash = get_json(uri)
-    hash['rows'].map { |item| Builder.process_hash item['doc'] }
-  end
-
-  def fetch_current_broadcast(channel)
-    uri = Views.broadcasts_by_channel_and_start(channel)
-    hash = get_bare_json(uri)
-    row = hash['rows'].first
-    Builderless::Broadcast.new(row['doc']) if row
-  end
-
-  def fetch_current_broadcast_and_key(channel)
-    hash = get_json(channel_and_start_uri(
-                      channel, Time.now, 1.day.ago, limit: 1, descending: true)
-                   )
-    { key: get_first_key(hash), broadcast: get_first_broadcast(hash) }
+  # Returns the first result for a mid if it is not an error.
+  #
+  # @param [String] mid MID to find in POMS
+  # @return [Hash, nil]
+  def first(mid)
+    first!(mid)
+  rescue Errors::HttpMissingError
+    nil
   end
 
-  def fetch_next_broadcast(channel)
-    hash = get_json(channel_and_start_uri(
-                      channel, Time.now, 1.day.from_now, limit: 1)
-                   )
-    get_first_broadcast(hash)
+  # Like `first`, but raises `Api::Client::HttpMissingError` when the requested
+  # MID could not be found.
+  #
+  # @param [String] mid
+  # @raise Api::Client::HttpMissingError
+  def first!(mid)
+    Api::JsonClient.get(
+      Api::Uris::Media.single(config.base_uri, mid),
+      config.credentials
+    )
   end
 
-  def fetch_next_broadcast_and_key(channel)
-    hash = get_json(channel_and_start_uri(
-                      channel, Time.now, 1.day.from_now, limit: 1)
-                   )
-    { key: get_first_key(hash), broadcast: get_first_broadcast(hash) }
+  def fetch(arg)
+    Api::JsonClient.post(
+      Api::Uris::Media.multiple(config.base_uri),
+      Array(arg),
+      config.credentials
+    )
   end
 
-  def broadcast_view_params(zender, start_time, end_time)
-    zender = zender.capitalize
-    "?startkey=[\"#{zender}\",#{start_time.to_i * 1000}]" \
-    "&endkey=[\"#{zender}\",#{end_time.to_i * 1000}]" \
-    '&reduce=false&include_docs=true'
+  def descendants(mid, search_params = {})
+    Api::PaginationClient.post(
+      Api::Uris::Media.descendants(config.base_uri, mid),
+      Api::Search.build(search_params),
+      config.credentials
+    )
   end
 
-  def ancestor_type_params(mid, type)
-    "?reduce=false&key=[\"#{mid}\",\"#{type}\"]&include_docs=true"
+  def members(mid)
+    Api::PaginationClient.get(
+      Api::Uris::Media.members(config.base_uri, mid),
+      config.credentials
+    )
   end
 
-  def ancestor_sortdate_params(mid, start_time = 1.month.ago)
-    end_time_i    = 1.week.from_now.to_i * 1000
-    start_time_i  = start_time.to_i * 1000
-    "?reduce=false&startkey=[\"#{mid}\",#{start_time_i}]" \
-    "&endkey=[\"#{mid}\",#{end_time_i}]&include_docs=true"
+  # Gets the merged serie mids as a hash. Expects a JSON response from
+  # the server with a `map` key.
+  #
+  # @return [Hash] a hash with old_mid => new_mid pairs
+  def merged_series
+    Api::JsonClient.get(
+      Api::Uris::Media.redirects(config.base_uri),
+      config
+    ).fetch('map')
   end
 
-  def channel_params(channel, start_time, end_time)
-    "?startkey=[\"#{channel}\",#{start_time.to_i * 1000}]" \
-    "&endkey=[\"#{channel}\",#{end_time.to_i * 1000}]" \
-    '&reduce=false&include_docs=true'
+  # Fetches the event for current broadcast on the given channel
+  #
+  # @param channel The channel name
+  def scheduled_now(channel)
+    Poms::Api::JsonClient.get(
+      Poms::Api::Uris::Schedule.now(config.base_uri, channel),
+      config.credentials
+    )
   end
 
-  def get_json(uri)
-    get_bare_json(URI.escape([URL, uri].join))
+  # Fetches the event for the next broadcast on a given channel
+  #
+  # @param channel The channel name
+  def scheduled_next(channel)
+    Poms::Api::JsonClient.get(
+      Poms::Api::Uris::Schedule.next(config.base_uri, channel),
+      config.credentials
+    )
   end
 
-  private
-
-  def get_bare_json(uri)
-    JSON.parse(open(uri).read)
-  rescue OpenURI::HTTPError => e
-    raise e unless e.message.match(/404/)
-    nil
+  def reset_config
+    @config = nil
   end
 
-  def channel_and_start_uri(channel, start_time, end_time, options = {})
-    query_options = options.blank? ? '' : "&#{options.to_query}"
-    view_params = channel_params(channel, start_time, end_time)
-    [CHANNEL_AND_START_PATH, view_params, query_options].join
+  def config
+    @config or raise Errors::NotConfigured
   end
 
-  def get_first_broadcast(hash)
-    rows = hash['rows']
-    Builder.process_hash(rows.empty? ? {} : rows.first['doc'])
-  end
-
-  def get_first_key(hash)
-    rows = hash['rows']
-    rows.empty? ? [] : rows.first['key']
-  end
+  private_class_method :config
 end
-# rubocop:enable Metrics/ModuleLength