reenhanced_bitbucket_api 0.1.6

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: d277a40d6a0329bdffe0c73a4f763114ab5bce42
+  data.tar.gz: a57c2f43ffbf60bb800b1118054d3a10637b6c39
+SHA512:
+  metadata.gz: 25fdcd0f4b728c37f7bb4ecaa6dc10c300f335dfd83647de539732da2f62e4d9cf986797e4402c5c5431257764504fde6fe1efab8b466b1cb9123a68a3612b00
+  data.tar.gz: bb139a3ab32b6ef2ce5a372c13ccb778e6b0ec6d435a8a09f27cfe7d4cf89d993c3db69e7533f731e7c83e7ebb37245c406f39a5e5c8d8e0e2c949d0aecccdcb

data/LICENSE.txt

@@ -0,0 +1,43 @@
+Copyright (c) 2013 James M Cochran
+
+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.
+
+
+Original github_api project:
+Copyright (c) 2011 Piotr Murach
+
+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,169 @@
+# BitBucketAPI
+
+[![Gem Version](https://badge.fury.io/rb/bitbucket_rest_api.png)](http://badge.fury.io/rb/bitbucket_rest_api)
+
+[Wiki](https://github.com/vongrippen/bitbucket/wiki) | [RDocs](http://rubydoc.info/github/vongrippen/bitbucket/master/frames)
+
+A Ruby wrapper for the BitBucket REST API.
+
+## Installation
+
+Install the gem by issuing
+
+```ruby
+gem install bitbucket_rest_api
+```
+
+or put it in your Gemfile and run `bundle install`
+
+```ruby
+gem "bitbucket_rest_api"
+```
+
+## Usage
+
+Create a new client instance
+
+```ruby
+bitbucket = BitBucket.new
+```
+
+At this stage you can also supply various configuration parameters, such as `:user`,`:repo`, `:oauth_token`, `:oauth_secret`, `:basic_auth` which are used throughout the API. These can be passed directly as hash options:
+
+```ruby
+bitbucket = BitBucket.new oauth_token: 'request_token', oauth_secret: 'request_secret'
+```
+
+Alternatively, you can configure the BitBucket settings by passing a block:
+
+```ruby
+bitbucket = BitBucket.new do |config|
+  config.oauth_token   = 'request_token'
+  config.oauth_secret  = 'request_secret'
+  config.client_id     = 'consumer_key'
+  config.client_secret = 'consumer_secret'
+  config.adapter       = :net_http
+end
+```
+
+You can authenticate either using OAuth authentication or through basic authentication by passing your login and password credentials
+
+```ruby
+bitbucket = BitBucket.new login:'vongrippen', password:'...'
+```
+
+or use convenience method:
+
+```ruby
+bitbucket = BitBucket.new basic_auth: 'login:password'
+```
+
+You can interact with BitBucket interface, for example repositories, by issuing following calls that correspond directly to the BitBucket API hierarchy
+
+```ruby
+bitbucket.repos.changesets.all  'user-name', 'repo-name'
+bitbucket.repos.keys.list     'user-name', 'repo-name'
+```
+
+The response is of type [Hashie::Mash] and allows to traverse all the json response attributes like method calls.
+
+## Inputs
+
+Some API methods apart from required parameters such as username or repository name
+allow you to switch the way the data is returned to you, for instance by passing
+a block you can iterate over the list of repositories
+
+```ruby
+bitbucket.repos.list do |repo|
+    puts repo.slug
+end
+```
+
+## Advanced Configuration
+
+The `bitbucket_rest_api` gem will use the default middleware stack which is exposed by calling `stack` on client instance. However, this stack can be freely modified with methods such as `insert`, `insert_after`, `delete` and `swap`. For instance to add your `CustomMiddleware` do
+
+```ruby
+bitbucket = BitBucket.new do |config|
+  config.stack.insert_after BitBucket::Response::Helpers, CustomMiddleware
+end
+```
+
+Furthermore, you can build your entire custom stack and specify other connection options such as `adapter`
+
+```ruby
+bitbucket = BitBucket.new do |config|
+  config.adapter :excon
+
+  config.stack do |builder|
+    builder.use BitBucket::Response::Helpers
+    builder.use BitBucket::Response::Jsonize
+  end
+end
+```
+
+## API
+
+Main API methods are grouped into the following classes that can be instantiated on their own
+
+```ruby
+BitBucket         - full API access
+
+BitBucket::Repos           BitBucket::Issues
+```
+
+Some parts of BitBucket API require you to be authenticated, for instance the following are examples of APIs only for the authenticated user
+
+```ruby
+BitBucket::Issues::Create
+```
+
+You can find out supported methods by calling `actions` on a class instance in your `irb`:
+
+```ruby
+>> BitBucket::Repos.actions                 >> bitbucket.issues.actions
+---                                         ---
+|--> all                                    |--> all
+|--> branches                               |--> comments
+|--> collaborators                          |--> create
+|--> commits                                |--> edit
+|--> contribs                               |--> events
+|--> contributors                           |--> find
+|--> create                                 |--> get
+|--> downloads                              |--> labels
+|--> edit                                   |--> list
+|--> find                                   |--> list_repo
+|--> forks                                  |--> list_repository
+|--> get                                    |--> milestones
+|--> hooks                                  ...
+...
+```
+
+## Configuration
+
+Certain methods require authentication. To get your BitBucket OAuth credentials,
+register an app with BitBucket.
+
+```ruby
+BitBucket.configure do |config|
+  config.oauth_token   = YOUR_OAUTH_REQUEST_TOKEN          # Different for each user
+  config.oauth_secret  = YOUR_OAUTH_REQUEST_TOKEN_SECRET   # Differenct for each user
+  config.client_id     = YOUR_OAUTH_CONSUMER_TOKEN
+  config.client_secret = YOUR_OAUTH_CONSUMER_TOKEN_SECRET
+  config.basic_auth    = 'login:password'
+end
+
+or
+
+BitBucket.new(:oauth_token => YOUR_OAUTH_REQUEST_TOKEN, :oauth_secret => YOUR_OAUTH_REQUEST_TOKEN_SECRET)
+BitBucket.new(:basic_auth => 'login:password')
+```
+
+## Development
+
+Questions or problems? Please post them on the [issue tracker](https://bitbucket.com/vongrippen/bitbucket/issues). You can contribute changes by forking the project and submitting a pull request. You can ensure the tests are passing by running `bundle` and `rake`.
+
+## Copyright
+
+Copyright (c) 2012 James M Cochran.
+Original github_api gem Copyright (c) 2011-2012 Piotr Murach. See LICENSE.txt for further details.

data/Rakefile

@@ -0,0 +1,3 @@
+# encoding: utf-8
+
+require 'bundler/gem_tasks'

data/lib/bitbucket_rest_api/api/actions.rb

@@ -0,0 +1,50 @@
+# encoding: utf-8
+
+module BitBucket
+  class API
+
+    # Returns all API public methods for a given class.
+    def self.inherited(klass)
+      klass.class_eval <<-RUBY_EVAL, __FILE__, __LINE__ + 1
+        def self.actions
+          self.new.api_methods_in(#{klass})
+        end
+        def actions
+          api_methods_in(#{klass})
+        end
+      RUBY_EVAL
+      super
+    end
+
+    def api_methods_in(klass)
+      puts "---"
+      (klass.send(:instance_methods, false) - ['actions']).sort.each do |method|
+        puts "|--> #{method}"
+      end
+      klass.included_modules.each do |mod|
+        if mod.to_s =~ /#{klass}/
+          puts "| \\ #{mod.to_s}"
+          mod.instance_methods(false).each do |met|
+            puts "|  |--> #{met}"
+          end
+          puts "| /"
+        end
+      end
+      puts "---"
+      nil
+    end
+
+    def append_arguments(method)
+      _method = self.method(method)
+      if _method.arity == 0
+        args = "()"
+      elsif _method.arity > 0
+        args = "(few)"
+      else
+        args = "(else)"
+      end
+      args
+    end
+
+  end # API
+end # BitBucket

data/lib/bitbucket_rest_api/api.rb

@@ -0,0 +1,120 @@
+# -*- encoding: utf-8 -*-
+
+require 'bitbucket_rest_api/configuration'
+require 'bitbucket_rest_api/connection'
+require 'bitbucket_rest_api/validations'
+require 'bitbucket_rest_api/request'
+require 'bitbucket_rest_api/core_ext/hash'
+require 'bitbucket_rest_api/core_ext/array'
+require 'bitbucket_rest_api/compatibility'
+require 'bitbucket_rest_api/api/actions'
+require 'bitbucket_rest_api/api_factory'
+
+module BitBucket
+  class API
+    include Authorization
+    include Connection
+    include Request
+
+    # TODO consider these optional in a stack
+    include Validations
+    include ParameterFilter
+    include Normalizer
+
+    attr_reader *Configuration::VALID_OPTIONS_KEYS
+
+    attr_accessor *VALID_API_KEYS
+
+    # Callback to update global configuration options
+    class_eval do
+      Configuration::VALID_OPTIONS_KEYS.each do |key|
+        define_method "#{key}=" do |arg|
+          self.instance_variable_set("@#{key}", arg)
+          BitBucket.send("#{key}=", arg)
+        end
+      end
+    end
+
+    # Creates new API
+    def initialize(options={}, &block)
+      super()
+      setup options
+      set_api_client
+
+      self.instance_eval(&block) if block_given?
+    end
+
+    def setup(options={})
+      options = BitBucket.options.merge(options)
+      Configuration::VALID_OPTIONS_KEYS.each do |key|
+        send("#{key}=", options[key])
+      end
+      process_basic_auth(options[:basic_auth])
+    end
+
+    # Extract login and password from basic_auth parameter
+    def process_basic_auth(auth)
+      case auth
+      when String
+        self.login, self.password = auth.split(':', 2)
+      when Hash
+        self.login    = auth[:login]
+        self.password = auth[:password]
+      end
+    end
+
+    # Assigns current api class
+    def set_api_client
+      BitBucket.api_client = self
+    end
+
+    # Responds to attribute query or attribute clear
+    def method_missing(method, *args, &block) # :nodoc:
+      case method.to_s
+      when /^(.*)\?$/
+        return !self.send($1.to_s).nil?
+      when /^clear_(.*)$/
+        self.send("#{$1.to_s}=", nil)
+      else
+        super
+      end
+    end
+
+    def _update_user_repo_params(user_name, repo_name=nil) # :nodoc:
+      self.user = user_name || self.user
+      self.repo = repo_name || self.repo
+    end
+
+    def _merge_user_into_params!(params)  #  :nodoc:
+      params.merge!({ 'user' => self.user }) if user?
+    end
+
+    def _merge_user_repo_into_params!(params)   #  :nodoc:
+      { 'user' => self.user, 'repo' => self.repo }.merge!(params)
+    end
+
+    # TODO: See whether still needed, consider adding to core_exts
+    def _hash_traverse(hash, &block)
+      hash.each do |key, val|
+        block.call(key)
+        case val
+        when Hash
+          val.keys.each do |k|
+            _hash_traverse(val, &block)
+          end
+        when Array
+          val.each do |item|
+            _hash_traverse(item, &block)
+          end
+        end
+      end
+      return hash
+    end
+
+    def _merge_mime_type(resource, params) # :nodoc:
+                                           #       params['resource'] = resource
+                                           #       params['mime_type'] = params['mime_type'] || :raw
+    end
+
+  end # API
+end # BitBucket

data/lib/bitbucket_rest_api/api_factory.rb

@@ -0,0 +1,30 @@
+# encoding: utf-8
+
+require 'bitbucket_rest_api/core_ext/hash'
+
+module BitBucket
+  class ApiFactory
+
+    # Instantiates a new bitbucket api object
+    def self.new(klass, options={})
+      return create_instance(klass, options) if klass
+      raise ArgumentError, 'must provide klass to be instantiated'
+    end
+
+    # Passes configuration options to instantiated class
+    def self.create_instance(klass, options)
+      options.symbolize_keys!
+      instance = convert_to_constant(klass.to_s).new options
+      BitBucket.api_client = instance
+      instance
+    end
+
+    def self.convert_to_constant(classes)
+      constant = BitBucket
+      classes.split('::').each do |klass|
+        constant = constant.const_get klass
+      end
+      return constant
+    end
+  end
+end # BitBucket

data/lib/bitbucket_rest_api/authorization.rb

@@ -0,0 +1,34 @@
+# encoding: utf-8
+
+module BitBucket
+  module Authorization
+
+    # Check whether authentication credentials are present
+    def authenticated?
+      basic_authed? || oauth_token?
+    end
+
+    # Check whether basic authentication credentials are present
+    def basic_authed?
+      basic_auth? || (login? && password?)
+    end
+
+    # Select authentication parameters
+    def authentication
+      if basic_auth?
+        { :basic_auth => basic_auth }
+      elsif login? && password?
+        { :login => login, :password => password }
+      else
+        { }
+      end
+    end
+
+    private
+
+    def _verify_client # :nodoc:
+      raise ArgumentError, 'Need to provide client_id and client_secret' unless client_id? && client_secret?
+    end
+
+  end # Authorization
+end # BitBucket

data/lib/bitbucket_rest_api/client.rb

@@ -0,0 +1,58 @@
+# encoding: utf-8
+
+module BitBucket
+  class Client < API
+
+    # This is a read-only API to the BitBucket events.
+    # These events power the various activity streams on the site.
+    def events(options = {})
+      raise "Unimplemented"
+      #@events ||= ApiFactory.new 'Events', options
+    end
+
+    def issues(options = {})
+      @issues ||= ApiFactory.new 'Issues', options
+    end
+
+    # An API for users to manage their own tokens.
+    def oauth(options = {})
+      raise "Unimpletmented"
+      #@oauth ||= ApiFactory.new 'Authorizations', options
+    end
+    alias :authorizations :oauth
+
+    def teams(options = {})
+      raise "Unimplemented"
+      #@teams ||= ApiFactory.new 'teams', options
+    end
+
+    def pull_requests(options = {})
+      raise "Unimplemented"
+      #@pull_requests ||= ApiFactory.new 'PullRequests', options
+    end
+
+    def repos(options = {})
+      @repos ||= ApiFactory.new 'Repos', options
+    end
+    alias :repositories :repos
+
+    def search(options = {})
+      raise "Unimplemented"
+      #@search ||= ApiFactory.new 'Search', options
+    end
+
+    # Many of the resources on the users API provide a shortcut for getting
+    # information about the currently authenticated user.
+    def users(options = {})
+      @users ||= ApiFactory.new 'Users', options
+    end
+
+    def user_api(options = {})
+      @user_api ||= ApiFactory.new 'User', options
+    end
+
+    def invitations(options = {})
+      @invitations ||= ApiFactory.new "Invitations", options
+    end
+  end # Client
+end # BitBucket

data/lib/bitbucket_rest_api/compatibility.rb

@@ -0,0 +1,23 @@
+# coding: utf-8
+
+if RUBY_VERSION < "1.9"
+
+  def ruby_18 #:nodoc:
+    yield
+  end
+
+  def ruby_19 #:nodoc:
+    false
+  end
+
+else
+
+  def ruby_18 #:nodoc:
+    false
+  end
+
+  def ruby_19 #:nodoc:
+    yield
+  end
+
+end

data/lib/bitbucket_rest_api/configuration.rb

@@ -0,0 +1,101 @@
+# encoding: utf-8
+
+module BitBucket
+  module Configuration
+
+    VALID_OPTIONS_KEYS         = [
+        :adapter,
+        :client_id,
+        :client_secret,
+        :oauth_token,
+        :oauth_secret,
+        :endpoint,
+        :mime_type,
+        :user_agent,
+        :connection_options,
+        :repo,
+        :user,
+        :login,
+        :password,
+        :basic_auth
+    ].freeze
+
+    # Other adapters are :typhoeus, :patron, :em_synchrony, :excon, :test
+    DEFAULT_ADAPTER            = :net_http
+
+    # By default, don't set an application key
+    DEFAULT_CLIENT_ID          = nil
+
+    # By default, don't set an application secret
+    DEFAULT_CLIENT_SECRET      = nil
+
+    # By default, don't set a user oauth access token
+    DEFAULT_OAUTH_TOKEN        = nil
+
+    # By default, don't set a user oauth access token secret
+    DEFAULT_OAUTH_SECRET       = nil
+
+    # By default, don't set a user login name
+    DEFAULT_LOGIN              = nil
+
+    # By default, don't set a user password
+    DEFAULT_PASSWORD           = nil
+
+    # By default, don't set a user basic authentication
+    DEFAULT_BASIC_AUTH         = nil
+
+    # The endpoint used to connect to BitBucket if none is set, in the event that BitBucket is ever available on location
+    DEFAULT_ENDPOINT           = 'https://bitbucket.org/api/1.0'.freeze
+
+    # The value sent in the http header for 'User-Agent' if none is set
+    DEFAULT_USER_AGENT         = "BitBucket Ruby Gem #{BitBucket::VERSION::STRING}".freeze
+
+    # By default the <tt>Accept</tt> header will make a request for <tt>JSON</tt>
+    DEFAULT_MIME_TYPE          = :json
+
+    # By default uses the Faraday connection options if none is set
+    DEFAULT_CONNECTION_OPTIONS = { }
+
+    # By default, don't set user name
+    DEFAULT_USER               = nil
+
+    # By default, don't set repository name
+    DEFAULT_REPO               = nil
+
+    attr_accessor *VALID_OPTIONS_KEYS
+
+    # Convenience method to allow for global setting of configuration options
+    def configure
+      yield self
+    end
+
+    def self.extended(base)
+      base.set_defaults
+    end
+
+    def options
+      options = { }
+      VALID_OPTIONS_KEYS.each { |k| options[k] = send(k) }
+      options
+    end
+
+    def set_defaults
+      self.adapter            = DEFAULT_ADAPTER
+      self.client_id          = DEFAULT_CLIENT_ID
+      self.client_secret      = DEFAULT_CLIENT_SECRET
+      self.oauth_token        = DEFAULT_OAUTH_TOKEN
+      self.oauth_secret       = DEFAULT_OAUTH_SECRET
+      self.endpoint           = DEFAULT_ENDPOINT
+      self.user_agent         = DEFAULT_USER_AGENT
+      self.connection_options = DEFAULT_CONNECTION_OPTIONS
+      self.mime_type          = DEFAULT_MIME_TYPE
+      self.user               = DEFAULT_USER
+      self.repo               = DEFAULT_REPO
+      self.login              = DEFAULT_LOGIN
+      self.password           = DEFAULT_PASSWORD
+      self.basic_auth         = DEFAULT_BASIC_AUTH
+      self
+    end
+
+  end # Configuration
+end # BitBucket