codenamev_bitbucket_api 0.4.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: cc4fce64074332f0f3496e0f986c20b07565720e91cdfabcd64c05235c6b49ad
+  data.tar.gz: d8dd76817622dc3c600f5aafddec3caa21f8fe9dca64e67ca5f3cf2c09b76414
+SHA512:
+  metadata.gz: 69ab08f6cb0db0b7ecf33b072b793f40858fb30bc9194f2986ad30604894e1b33d81611f5b4b48cc0159ddb80effd2978918ffd829f0990e1c0c132ec01ba813
+  data.tar.gz: 983e6da829c7c7015f88971ef092dee0b94f7febb9247e29581806b631e195779802a1fea132b05c7fcaf23c9e940b27896fbef1e3ca4d3aca8ebf951cf4d7f7

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/arguments.rb

@@ -0,0 +1,248 @@
+# encoding: utf-8
+
+module BitBucket
+  class API
+    # A class responsible for handilng request arguments
+    class Arguments
+      include Normalizer
+      include ParameterFilter
+      include Validations
+
+      AUTO_PAGINATION = 'auto_pagination'.freeze
+
+      # Parameters passed to request
+      attr_reader :params
+
+      # The remaining unparsed arguments
+      attr_reader :remaining
+
+      # The request api
+      attr_reader :api
+
+      # Initialize an Arguments
+      #
+      # @param [Hash] options
+      #
+      # @option options [Array[String]] :required
+      #   arguments that must be present before request is fired
+      #
+      # @option options [BitBucket::API] :api
+      #   the reference to the current api
+      #
+      # @api public
+      def initialize(options = {}, &block)
+        normalize! options
+
+        @api      = options.fetch('api')
+        @required = options.fetch('required', []).map(&:to_s)
+        @optional = options.fetch('optional', []).map(&:to_s)
+        @assigns  = {}
+
+        yield_or_eval(&block)
+      end
+
+      # Specify required attribute(s)
+      #
+      # @api public
+      def require(*attrs, &block)
+        attrs_clone = attrs.clone
+        @required = Array(attrs_clone)
+        self
+      end
+      alias :required :require
+
+      # Specify optional attribute(s)
+      #
+      # @api public
+      def optional(*attrs, &block)
+      end
+
+      # Hash like access to request arguments
+      #
+      # @param [String, Symbol] property
+      #   the property name
+      #
+      # @api public
+      def [](property)
+        @assigns[property.to_s]
+      end
+
+      def []=(property, value)
+        @assigns[property.to_s] = value
+      end
+
+      def method_missing(method_name, *args, &block)
+        if @assigns.key?(method_name.to_s)
+          self[method_name]
+        else
+          super
+        end
+      end
+
+      def respond_to_missing?(method_name, include_private = false)
+        @assigns.key?(method_name) || super
+      end
+
+      # Parse arguments to allow for flexible api calls
+      #
+      # Arguments can be part of parameters hash or be simple string arguments.
+      #
+      # @api public
+      def parse(*args, &block)
+        options = ParamsHash.new(args.extract_options!)
+        normalize! options
+
+        if args.size.zero?  # Arguments are inside the parameters hash
+          parse_hash(options)
+        else
+          parse_array(*args)
+        end
+        @params    = options
+        @remaining = args[@required.size..-1]
+        extract_pagination(options)
+
+        yield_or_eval(&block)
+        self
+      end
+
+      # Remove unknown keys from parameters hash.
+      #
+      # = Parameters
+      #  :recursive - boolean that toggles whether nested filtering should be applied
+      #
+      def permit(keys, key=nil, options={})
+        filter! keys, (key.nil? ? params : params[key]), options if keys.any?
+        self
+      end
+
+      # Check if required keys are present inside parameters hash.
+      #
+      # @api public
+      def assert_required(required)
+        assert_required_keys required, params
+        self
+      end
+
+      # Check if parameters match expected values.
+      #
+      # @api public
+      def assert_values(values, key=nil)
+        assert_valid_values values, (key.nil? ? params : params[key])
+        self
+      end
+
+      private
+
+      # Parse array arguments and assign in order to required properties
+      #
+      # @param [Array[Object]] args
+      #
+      # @raise ArgumentError
+      #
+      # @return [nil]
+      #
+      # @api public
+      def parse_array(*args)
+        assert_presence_of(*args)
+        @required.each_with_index do |req, indx|
+          @assigns[req] = args[indx]
+        end
+        check_requirement!(*args)
+      end
+
+      # Remove required arguments from parameters and
+      # validate their presence(if not nil or empty string).
+      #
+      # @param [Hash[String]] options
+      #
+      # @return [nil]
+      #
+      # @api private
+      def parse_hash(options)
+        options.each { |key, val| remove_required(options, key, val) }
+        hash = update_required_from_global
+        check_requirement!(*hash.keys)
+      end
+
+      # Remove required property from hash
+      #
+      # @param [Hash[String]] options
+      #   the options to check
+      #
+      # @param [String] key
+      #   the key to remove
+      #
+      # @param [String] val
+      #   the value to assign
+      #
+      # @api private
+      def remove_required(options, key, val)
+        if @required.include?(key.to_s)
+          assert_presence_of(val)
+          options.delete(key)
+          @assigns[key.to_s] = val
+        end
+      end
+
+      # Update required property from globals if not present
+      #
+      # @return [Hash[String]]
+      #
+      # @api private
+      def update_required_from_global
+        @required.reduce({}) do |hash, property|
+          if @assigns.key?(property)
+            hash[property] = self[property]
+          elsif api_property?(property)
+            hash[property] = api.send(:"#{property}")
+            self[property] = hash[property]
+          end
+          hash
+        end
+      end
+
+      # Check if api has non-empty property
+      #
+      # @param [String] property
+      #   the property to check
+      #
+      # @return [Boolean]
+      #
+      # @api private
+      def api_property?(property)
+        api.respond_to?(:"#{property}") && api.send(:"#{property}")
+      end
+
+      # Check if required arguments are present.
+      #
+      #
+      def check_requirement!(*args)
+        args_length     = args.length
+        required_length = @required.length
+
+        if args_length < required_length
+          raise ArgumentError, "Wrong number of arguments " \
+            "(#{args_length} for #{required_length}). " \
+            "Expected `#{@required.join(', ')}` as required arguments, " \
+            "but got `#{args.join(", ")}`."
+        end
+      end
+
+      # Find auto_pagination parameter in options hash
+      #
+      def extract_pagination(options)
+        if (value = options.delete(AUTO_PAGINATION))
+          api.auto_pagination = value
+        end
+      end
+
+      # Evaluate a block
+      #
+      # @api privte
+      def yield_or_eval(&block)
+        return unless block
+        block.arity > 0 ? yield(self) : instance_eval(&block)
+      end
+    end # Arguments
+  end # Api
+end # BitBucket

data/lib/bitbucket_rest_api/api/config/property.rb

@@ -0,0 +1,30 @@
+# encoding: utf-8
+
+module BitBucket
+  class API
+    class Config
+
+      # Property objects provide an interface for configuration options
+      class Property
+
+        attr_reader :name
+        attr_reader :default
+        attr_reader :required
+
+        def initialize(name, options)
+          @name = name
+          @default = options.fetch(:default, nil)
+          @required = options.fetch(:required, nil)
+          @options = options
+        end
+
+        # @api private
+        def define_accessor_methods(properties)
+          properties.define_reader_method(self, self.name, :public)
+          properties.define_writer_method(self, "#{self.name}=", :public)
+        end
+      end # Property
+
+    end # Config
+  end # Api
+end # BitBucket

data/lib/bitbucket_rest_api/api/config/property_set.rb

@@ -0,0 +1,118 @@
+# encoding: utf-8
+
+module BitBucket
+  class API
+    class Config
+      # Class responsible for storing configuration properties
+      class PropertySet
+        include Enumerable
+
+        attr_reader :parent
+
+        attr_reader :properties
+
+        # Initialize an PropertySet
+        #
+        # @param [Object] parent
+        # @param [Set] properties
+        #
+        # @return [undefined]
+        #
+        # @api private
+        def initialize(parent = nil, properties = Set.new)
+          @parent = parent
+          @properties = properties
+          @map = {}
+        end
+
+        # Iterate over properties
+        #
+        # @yield [property]
+        #
+        # @yieldparam [Property] property
+        #
+        # @return [self]
+        #
+        # @api public
+        def each
+          return to_enum unless block_given?
+          @map.each { |name, property| yield property if name.is_a?(Symbol) }
+          self
+        end
+
+        # Adds property to the set
+        #
+        # @example
+        #   properties_set << property
+        #
+        # @param [Property] property
+        #
+        # @return [self]
+        #
+        # @api public
+        def <<(property)
+          properties << property
+          update_map(property.name, property.default)
+          property.define_accessor_methods(self)
+          self
+        end
+
+        # Access property by name
+        #
+        # @api public
+        def [](name)
+          @map[name]
+        end
+        alias_method :fetch, :[]
+
+        # Set property value by name
+        #
+        # @api public
+        def []=(name, property)
+          update_map(name, property)
+        end
+
+        # Update map with index
+        #
+        # @api private
+        def update_map(name, property)
+          @map[name.to_sym] = @map[name.to_s.freeze] = property
+        end
+
+        # Convert properties to a hash of property names and
+        # corresponding values
+        #
+        # @api public
+        def to_hash
+          properties.each_with_object({}) do |property, props|
+            name = property.name
+            props[name] = self[name]
+          end
+        end
+
+        # Check if properties exist
+        #
+        # @api public
+        def empty?
+          @map.empty?
+        end
+
+        # @api private
+        def define_reader_method(property, method_name, visibility)
+          property_set = self
+          parent.send(:define_method, method_name) { property_set[property.name] }
+          parent.send(visibility, method_name)
+        end
+
+        # @api private
+        def define_writer_method(property, method_name, visibility)
+          property_set = self
+          parent.send(:define_method, method_name) do |value|
+            property_set[property.name]= value
+          end
+          parent.send(visibility, method_name)
+        end
+      end # PropertySet
+    end # Config
+  end # Api
+end # BitBucket