pmp 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 20ab2639c7b9fadf21969f73537adca2253ff409
+  data.tar.gz: 2bd71ffb8dcfc812eab677e8b951070475dfcfb3
+SHA512:
+  metadata.gz: 6ade468f61ff12b0a71bb8479c4145a750f6680fec62dac610f64e763923afd2d81417a60e0b5e274c127113b4da0c1e786cc86c1fac9ec153ba79368229d472
+  data.tar.gz: 5be84ad2ec152d24da4a8d9968752a43b59380faf8e0392beb0cf747d6a09328ec5c8b27f8062fcbb3f3825af697c264f1789c1005fba12f829856a3978e16bc

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/.ruby-version

@@ -0,0 +1 @@
+2.0.0-p247

data/Gemfile

@@ -0,0 +1,5 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in pmp.gemspec
+gemspec
+

data/Guardfile

@@ -0,0 +1,20 @@
+# A sample Guardfile
+# More info at https://github.com/guard/guard#readme
+
+guard 'bundler' do
+  watch('Gemfile')
+  # Uncomment next line if Gemfile contain `gemspec' command
+  watch(/^.+\.gemspec/)
+end
+
+guard :minitest do
+  # with Minitest::Unit
+  watch(%r{^test/(.*)\/?test_(.*)\.rb})
+  watch(%r{^lib/(.*/)?([^/]+)\.rb})     { |m| "test/#{m[1]}test_#{m[2]}.rb" }
+  watch(%r{^test/spec_helper\.rb})      { 'test' }
+
+  # with Minitest::Spec
+  watch(%r{^spec/(.*)_spec\.rb})
+  watch(%r{^lib/pmp/(.+)\.rb})         { |m| "spec/#{m[1]}_spec.rb" }
+  watch(%r{^spec/spec_helper\.rb}) { 'spec' }
+end

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 PRX, Andrew Kuklewicz
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,136 @@
+# PMP gem
+
+Gem to make it easier to use the PMP API, which is a hypermedia API using the collection.doc+json format.
+
+https://github.com/publicmediaplatform/pmpdocs/wiki
+
+Very big hat tip to the hyperresource gem: https://github.com/gamache/hyperresource
+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'pmp'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install pmp
+
+## Usage
+
+You can go through the `PMP::Client` as a convenience or start with a `PMP::CollectionDocument`
+
+```ruby
+
+# so you need a few things, like the endpoint, default is "https://api.pmp.io"
+endpoint = "https://api-sandbox.pmp.io"
+
+# and you need credentials, the gem doesn't help you create these (yet)
+client_id = "thisisnota-real-client-id-soverysorry"
+client_secret = "thisisnotarealsecreteither"
+
+# construct the client, setting some config in there
+# this will automatically get a token as there is not one set
+pmp = PMP::Client.new(client_id: client_id, client_secret: client_secret, endpoint: endpoint)
+
+# or if you have a token already
+token = 'thisisnotatoken'
+pmp = PMP::Client.new(oauth_token: token, endpoint: endpoint)
+
+# or if you want to get a token
+pmp = PMP::Client.new(client_id: client_id, client_secret: client_secret, endpoint: endpoint)
+oauth_token = pmp.token
+
+# get the token string out of the token response
+puts oauth_token.token
+> 'thisisnotatoken'
+
+# so let's get the root doc - an PMP::CollectionDocument instance
+root = pmp.root
+
+# or we can get it without the client, since PMP::CollectionDocument defaults to root
+root = PMP::CollectionDocument.new(oauth_token: token, endpoint: endpoint)
+
+# wanna get an attribute, act like it is a ruby attribute
+puts root.guid
+> '04224975-e93c-4b17-9df9-96db37d318f3'
+
+# want to get the links, you can get a list of them by the rels
+puts root.links.keys.sort
+> ["creator", "edit", "navigation", "query"]
+
+# want to get the creator link?
+puts root.links["creator"]
+> #<PMP::Link href="https://api-sandbox.pmp.io/docs/af676335-21df-4486-ab43-e88c1b48f026">
+
+# get the same thing as a method
+puts root.creator
+> #<PMP::Link href="https://api-sandbox.pmp.io/docs/af676335-21df-4486-ab43-e88c1b48f026">
+
+# like the root doc itself, this is lazy loaded
+# but ask for an attribute on there, and you'll get the doc loaded up
+puts root.creator.guid
+
+#### http get request to link href occurs, loads info about the creator
+> 'af676335-21df-4486-ab43-e88c1b48f026'
+
+```
+
+## Saving and Deleting
+
+Once you have a doc, you can save or delete it like so:
+
+```ruby
+
+# create a new blank doc, will generatr a guid automatically if not present
+doc = PMP::CollectionDocument.new()
+doc.title = "this is an example, ok?"
+doc.save
+
+# get that guid!
+guid = doc.guid
+
+# how about the link to self
+self_href = doc.self.href
+
+# get a new doc using self, could just have used the link, this is a bad example perhaps
+doc = PMP::CollectionDocument.new(href: self_href)
+
+# update an existing attribute
+doc.title = "this is another awesome example, cool?"
+
+# can add an attribute (doesn't check schema yet)
+doc.adding_an_attribute = "this will get saved as a new attribute adding-an-attribute"
+
+# can add links (doesn't check schema yet)
+doc.links['some-new-link'] = PMP::Link.new(doc, {href:'http://somenewlink.io'})
+new_link = doc.some_new_link
+
+# save changes
+doc.save
+
+# never mind, delete it
+doc.delete
+
+
+```
+
+## To Do
+
+Think about integrating this lovely json schema parsing project: https://github.com/google/autoparse
+
+or this one: https://github.com/hoxworth/json-schema
+
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,11 @@
+require 'bundler/gem_tasks'
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.libs.push 'lib'
+  t.libs.push 'test'
+  t.test_files = FileList['spec/**/*_spec.rb']
+  t.verbose = true
+end
+
+task :default => :test

data/lib/pmp.rb

@@ -0,0 +1,22 @@
+# -*- encoding: utf-8 -*-
+
+require 'rubygems'
+require 'active_support/all'
+
+require 'pmp/version'
+
+require 'pmp/utils'
+require 'pmp/configuration'
+require 'pmp/connection'
+require 'pmp/response'
+require 'pmp/parser'
+
+require 'pmp/links'
+require 'pmp/link'
+require 'pmp/collection_document'
+
+require 'pmp/token'
+require 'pmp/client'
+
+module PMP
+end

data/lib/pmp/client.rb

@@ -0,0 +1,17 @@
+# -*- encoding: utf-8 -*-
+
+module PMP
+  class Client
+
+    include Configuration
+
+    def token(opts={})
+      PMP::Token.new(opts).get_token
+    end
+
+    def root(opts={}, &block)      
+      PMP::CollectionDocument.new(opts, &block)
+    end
+
+  end
+end

data/lib/pmp/collection_document.rb

@@ -0,0 +1,126 @@
+require 'ostruct'
+
+module PMP
+
+  # Using OpenStruct for now - perhaps use ActiveModel? hmm...
+  class CollectionDocument < OpenStruct
+
+    include Configuration
+    include Connection
+    include Parser
+
+    # the href/url string to retrieve info for this resource
+    attr_accessor :href
+
+    # keep a ref to response obj if this resulted from one
+    # should this be private?
+    attr_accessor :response
+
+    # keep a ref to original doc from which this obj was created
+    # should this be private?
+    attr_accessor :original
+
+    # all collection docs have a version
+    # default is '1.0'
+    attr_accessor :version
+
+    # has this resource actually been loaded from remote url or json document?
+    attr_accessor :loaded
+
+    # private var to save links obj, to handle link additions
+    attr_accessor :links
+
+    # document is the original json derived doc used to create this resource
+    # assumption is that doc is a parsed json doc confirming to collection.doc+json
+    # TODO: check if this is a json string or hash, for now assume it has been mashified
+    def initialize(options={}, &block)
+      super()
+
+      self.links    = PMP::Links.new(self)
+
+      self.href     = options.delete(:href)
+
+      # if there is a doc to be had, pull it out
+      self.response = options.delete(:response)
+      self.original = options.delete(:document)
+
+      apply_configuration(options)
+
+      if !loaded? && !href
+        self.href = endpoint
+      end
+
+      yield(self) if block_given?
+    end
+
+    def attributes
+      HashWithIndifferentAccess.new(marshal_dump.delete_if{|k,v| links.keys.include?(k.to_s)})
+    end
+
+    def response=(resp)
+      unless (!resp || loaded?)
+        @response = resp
+        self.original = resp.body
+      end
+    end
+
+    def original=(doc)
+      unless (!doc || loaded?)
+        @original = doc
+        parse(@original)
+        self.loaded = true
+      end
+    end
+
+    def load
+      if !loaded?
+        self.response = request(:get, self.href || self.self.url)
+        self.loaded = true
+      end
+    end
+    alias_method :get, :load
+
+    def save
+      save_link = self.edit
+      raise 'Edit link does not specify saving via put' unless (save_link && save_link.hints.allow.include?('PUT'))
+      set_guid_if_blank
+      url = save_link.where(guid: self.guid).url
+      request(:put, url, self)
+    end
+
+    def delete
+      delete_link = self.edit
+      raise 'Edit link does not specify deleting' unless (delete_link && delete_link.hints.allow.include?('DELETE'))
+      raise 'No guid specified to delete' if self.guid.blank?
+
+      url = delete_link.where(guid: self.guid).url
+      request(:put, url, self)
+    end
+
+    def loaded?
+      !!self.loaded
+    end
+
+    # url includes any params - full url
+    def request(method, url, body=nil) # :nodoc:
+      raw = connection(options.merge({url: url})).send(method) do |request|
+        if [:post, :put].include?(method.to_sym) && !body.blank?
+          request.body = body.is_a?(String) ? body : body.to_json
+        end
+      end
+
+      # may not need this, but remember how we made this response
+      PMP::Response.new(raw, {method: method, url: url, body: body})
+    end
+
+    def set_guid_if_blank
+      self.guid = SecureRandom.uuid if guid.blank?
+    end
+
+    def method_missing(method, *args)
+      load if (method.to_s.last != '=') && !loaded?
+      super
+    end
+
+  end
+end

data/lib/pmp/configuration.rb

@@ -0,0 +1,90 @@
+# -*- encoding: utf-8 -*-
+
+require 'active_support/concern'
+
+module PMP
+  module Configuration 
+
+    extend ActiveSupport::Concern
+
+    VALID_OPTIONS_KEYS = [
+      :client_id,
+      :client_secret,
+      :oauth_token,
+      :adapter,
+      :endpoint,
+      :user_agent,
+      :debug
+    ].freeze
+
+    # this you need to get from pmp, not covered by this
+    DEFAULT_CLIENT_ID     = nil
+    DEFAULT_CLIENT_SECRET = nil
+    
+    # Adapters are whatever Faraday supports - I like excon alot, so I'm defaulting it
+    DEFAULT_ADAPTER       = :excon
+    
+    # The api endpoint for YQL
+    DEFAULT_ENDPOINT      = 'https://api.pmp.io/'.freeze
+    
+    # The value sent in the http header for 'User-Agent' if none is set
+    DEFAULT_USER_AGENT    = "PMP Ruby Gem #{PMP::VERSION}".freeze
+    
+    # debug is defaulted to the ENV['DEBUG'], see below
+
+    attr_accessor *VALID_OPTIONS_KEYS
+
+    included do
+
+      attr_accessor :options
+
+      VALID_OPTIONS_KEYS.each do |key|
+        define_method "#{key}=" do |arg|
+          self.instance_variable_set("@#{key}", arg)
+          self.options.merge!({:"#{key}" => arg})
+        end
+      end
+
+    end
+
+    def apply_configuration(opts={})
+      reset! unless @options
+      self.options = options.merge(opts)
+      VALID_OPTIONS_KEYS.each do |key|
+        send("#{key}=", options[key])
+      end
+    end
+
+    # Convenience method to allow for global setting of configuration options
+    def configure
+      yield self
+    end
+
+    # Reset configuration options to their defaults
+    def reset!
+      @options = {}
+      self.client_id     = DEFAULT_CLIENT_ID
+      self.client_secret = DEFAULT_CLIENT_SECRET
+      self.adapter       = DEFAULT_ADAPTER
+      self.endpoint      = DEFAULT_ENDPOINT
+      self.user_agent    = DEFAULT_USER_AGENT
+      self.debug         = ENV['DEBUG']
+      self
+    end
+
+    def options
+      options = {}
+      VALID_OPTIONS_KEYS.each { |k| options[k] = send(k) }
+      options
+    end
+
+    module ClassMethods
+
+      def keys
+        VALID_OPTIONS_KEYS
+      end      
+
+    end
+
+  end
+end