cartodb-rb-client 0.1.8

data/.gitignore

@@ -0,0 +1,5 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*
+bin/

data/.rvmrc

@@ -0,0 +1,2 @@
+rvm use --create 1.9.2@cartodb-rb-client > /dev/null
+rvm wrapper current textmate

data/Gemfile

@@ -0,0 +1,12 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in cartodb-rb-client.gemspec
+gemspec
+
+group :development do
+  gem "rspec", "~> 2.3.0"
+  gem "bundler", "~> 1.0.0"
+  gem "rcov", ">= 0"
+  gem 'ruby-debug', :platforms => :mri_18
+  gem 'ruby-debug19', :require => 'ruby-debug', :platforms => :mri_19
+end

data/LICENSE

@@ -0,0 +1,28 @@
+Copyright (c) 2011, Vizzuality 
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+1. Redistributions of source code must retain the above copyright
+   notice, this list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright
+   notice, this list of conditions and the following disclaimer in the
+   documentation and/or other materials provided with the distribution.
+3. All advertising materials mentioning features or use of this software
+   must display the following acknowledgement:
+   This product includes software developed by Vizzuality.
+4. Neither the name of Vizzuality nor the
+   names of its contributors may be used to endorse or promote products
+   derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS "AS IS" AND ANY
+EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL <COPYRIGHT HOLDER> BE LIABLE FOR ANY
+DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+

data/README.markdown

@@ -0,0 +1,324 @@
+cartoDB Ruby Client
+===================
+
+cartoDB ruby client that allows an easy and simple interaction with the cartoDB API.
+
+Requirements
+-------------
+
+The only requirement is an Internet connection and a working version of the Ruby language interpreter. Current ruby versions supported are 1.8.7 and 1.9.2
+
+Setup
+------
+
+1. Install the client gem:
+
+        gem install cartodb-rb-client
+
+    or if you are using bundler, put this line in your Gemfile:
+
+        gem 'cartodb-rb-client'
+
+2. Log into http://cartodb.com, get your OAUTH credentials and put them in a YAML file:
+
+
+    *cartodb\_config.yml:*
+
+        host: 'YOUR_CARTODB_DOMAIN'
+        oauth_key: 'YOUR_OAUTH_KEY'
+        oauth_secret: 'YOUR_OAUTH_SECRET'
+        oauth_access_token: 'YOUR_OAUTH_ACCES_TOKEN'
+        oauth_access_token_secret: 'YOUR_OAUTH_ACCES_TOKEN_SECRET'
+
+    We also support xAuth protocol. In order to use it, provide your username and password instead of your access token:
+
+        host: 'YOUR_CARTODB_DOMAIN'
+        oauth_key: 'YOUR_OAUTH_KEY'
+        oauth_secret: 'YOUR_OAUTH_SECRET'
+        username: 'YOUR_CARTODB_USERNAME'
+        password: 'YOUR_CARTODB_PASSWORD'
+
+3. Setup your cartoDB connection object. To do so, load the YAML file and assign it to a CartoDB::Config object:
+
+        CartoDB::Settings = YAML.load_file(Rails.root.join('config/cartodb_config.yml'))
+        CartoDB::Connection = CartoDB::Client::Connection.new
+
+And that's it. Now you should be able to run querys against the cartoDB servers using the CartoDB::Connection object.
+
+Rails apps
+----------
+
+If you're developing a Rails app, you just need to add the cartodb\_config.yml file to your rails app config directory. And that's it. You can access cartoDB anywhere in your app's code using the CartoDB::Connection class.
+
+Using the cartoDB API
+-----------
+
+List of supported methods to interact with cartoDB:
+
+####1. Create table.
+
+Creates a new table in cartoDB. The table's name will be normalized, for example, 'table #1' will become 'table\_1'.
+
+Arguments:
+
+- **table\_name**: table's name.
+
+- **schema**: list of fields the table will contain.
+
+- **the\_geom\_type**: Type of geometry the\_geom field will have. Currently we only support 'POINT', but we'll support more types soon.
+
+Example:
+
+    CartoDB::Connection.create_table 'table #1', [{:name => 'field1', :type => 'text'}], 'POINT'
+
+Results:
+
+    {:id => 1,
+     :name => "table_1",
+     :schema =>
+     [["cartodb_id", "number"],
+      ["field1", "string"],
+      ["updated_at", "date"],
+      ["created_at", "date"]]}
+
+####2. Add column.
+
+Adds a new column to an existing table.
+
+Arguments:
+
+- **table_name**: table's name.
+- **column_name**: new column's name.
+- **column_type**: new column's data type. Supported types: string, numeric, date, boolean and geometry.
+
+Example:
+
+    CartoDB::Connection.add\_column 'table_1', 'my_column', 'numeric'
+
+Results:
+
+    []
+
+####3. Drop column.
+
+Removes an existing column in the specified table.
+
+Arguments:
+
+- **table_name**: table's name which column will be dropped.
+- **column_name**: name of the column to be dropped.
+
+Example:
+
+    CartoDB::Connection.drop\_column 'table_1', 'my_column'
+
+Results:
+
+    []
+
+####4. Change column.
+
+Changes name and data type of an existing column.
+
+Arguments:
+
+- **table_name**: table's name which column will be changed.
+- **old_column_name**: current name of the column to be changed.
+- **new_column_name**: new name for the column.
+- **column_type**: new data type of the column.
+
+Example:
+
+    CartoDB::Connection.change\_column 'table_1', 'field1', 'myfield', 'boolean'
+
+Results:
+
+    []
+
+####5. List tables.
+
+List all tables in your cartoDB account.
+
+Example:
+
+    CartoDB::Connection.tables
+
+Results:
+
+    {:total_entries => 1,
+     :tables =>
+     [{:id => 1,
+      :name => "table_1",
+      :privacy => "PUBLIC",
+      :tags => "",
+      :schema =>
+      [["cartodb_id", "number"],
+       ["the_geom", "geometry", "geometry", "point"],
+       ["field1", "string"],
+       ["created_at", "string"],
+       ["updated_at", "string"]],
+      :updated_at => Mon, 12 Sep 2011 00:00:00 +0000,
+      :rows_counted => 1}]}
+
+####6. Table's detail
+
+Shows information about the specified table.
+
+Arguments:
+
+- **table_name**: Name of the table you want to get info.
+
+Example:
+
+    CartoDB::Connection.table 'table_1'
+
+Results:
+
+    {:id => 1,
+     :name => "table_1",
+     :privacy => "PRIVATE",
+     :tags => "",
+     :schema => 
+     [["cartodb_id", "number"],
+      ["myfield", "boolean"],
+      ["updated_at", "date"],
+      ["created_at", "date"]]}
+
+####7. Drop table.
+
+Deletes the specified table.
+
+Arguments:
+
+- **table_name**: Name of the table to delete.
+
+Example:
+
+    CartoDB::Connection.drop_table 'table_1'
+
+Results:
+
+    []
+
+####8. Get single row.
+
+You can get a single row with this method by specifying its cartodb_id.
+
+Arguments:
+
+- **table_name**: Name of the table.
+- **row_id**: Id of the row we want.
+
+Example:
+
+    CartoDB::Connection.row 'table_1', 1
+
+Result:
+
+    {:id => 1,
+     :updated_at => Tue, 13 Sep 2011 00:00:00 +0000,
+     :created_at => Tue, 13 Sep 2011 00:00:00 +0000,
+     :cartodb_id => 1,
+     :field1 => "cartoDB is awesome!"}
+
+
+####9. Insert row.
+
+Inserts a new row in the specified table.
+
+Arguments:
+
+- **table_name**: Name of the table.
+- **row**: A ruby hash with the name of the columns we want to insert
+  data in, and its values.
+
+Example:
+
+    CartoDB::Connection.insert_row 'table_1', :field1 => 'cartoDB is
+awesome!'
+
+Results:
+
+    {:id => 1,
+     :updated_at => Tue, 13 Sep 2011 00:00:00 +0000,
+     :created_at => Tue, 13 Sep 2011 00:00:00 +0000,
+     :cartodb_id => 1,
+     :field1 => "cartoDB is awesome!"}
+
+####10. Update row.
+
+Updates a single row in the specified table.
+
+Arguments:
+
+- **table_name**: Name of the table.
+- **row_id**: Id of the row we want to update.
+- **row**: A ruby hash containing the column names and values for the
+  update.
+
+Example:
+
+    CartoDB::Connection.update_row 'table_1', 1, :field1 => 'cartoDB is
+*really* awesome!'
+
+Result:
+
+    {:id => 1,
+     :updated_at => Tue, 13 Sep 2011 00:00:00 +0000,
+     :created_at => Tue, 13 Sep 2011 00:00:00 +0000,
+     :cartodb_id => 1,
+     :field1 => "cartoDB is *really* awesome!"}
+
+####11. Delete row.
+
+Deletes a row in the specified table.
+
+Arguments:
+
+- **table_name**: Name of the table.
+- **row_id**: Id of the row we want to delete.
+
+Example:
+
+    CartoDB::Connection.delete_row 'table_1', 1
+
+Result:
+
+    {:time => 0.008, :total_rows => 0, :rows => []}
+
+####12. Execute a sql query.
+
+Executes an sql query against your database in cartoDB.
+
+Arguments:
+
+- **sql**: String containing the query we want to execute.
+- **options**: A ruby hash containing optional params to run the query.
+  Currently we support pagination using the :page and :rows_per_page
+parameters in the options argument.
+
+Example:
+
+    # At first, lets introduce some dummy data for the test
+    10.times{ CartoDB::Connection.insert_row 'table_1', :field1 => 'cartoDB is awesome!'}
+
+    # And now, the query itself
+    CartoDB::Connection.query 'SELECT * FROM table_1', :page => 1,
+:rows_per_page => 5
+
+Results:
+
+    {:time=>0.017,
+     :total_rows=>10,
+     :rows=>[{:updated_at=>Tue, 13 Sep 2011 00:00:00 +0000,
+              :created_at=>Tue, 13 Sep 2011 00:00:00 +0000,
+              :cartodb_id=>2,
+              :field1=>"cartoDB is awesome!"},
+              ...
+              ]}
+
+More info
+---------
+
+You can also check the oficial [cartoDB Documentation](http://developers.cartodb.com/) if you want more info about the cartoDB API.
+

data/Rakefile

@@ -0,0 +1,10 @@
+require 'bundler'
+require 'rspec/core/rake_task'
+
+Bundler::GemHelper.install_tasks
+
+if defined? RSpec
+  RSpec::Core::RakeTask.new(:spec)
+
+  task :default => :spec
+end

data/cartodb-rb-client.gemspec

@@ -0,0 +1,34 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "cartodb-rb-client/version"
+require "cartodb-rb-client/install_utils"
+
+Gem::Specification.new do |s|
+  s.name        = "cartodb-rb-client"
+  s.version     = Cartodb::Rb::Client::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["Fernando Espinosa"]
+  s.email       = ["ferdev@vizzuality.com"]
+  s.homepage    = %q{http://github.com/vizzuality/cartodb-rb-client}
+  s.licenses    = ["BSD"]
+  s.summary     = %q{Ruby client for the cartoDB API}
+  s.description = %q{Allows quick and easy connection to the cartodb API.}
+
+  s.required_rubygems_version = ">= 1.3.6"
+
+  s.rubyforge_project = "cartodb-rb-client"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+  s.add_dependency 'typhoeus', '0.2.4'
+  s.add_dependency 'oauth', '0.4.5'
+  s.add_dependency 'mime-types',  '1.16'
+  s.add_dependency 'activesupport', '>= 3.0.0', '<= 3.1.0'
+  s.add_dependency 'i18n', '>= 0.5.0', '<= 0.6.0'
+  s.add_dependency 'rgeo', '0.3.2'
+  s.add_dependency 'rgeo-geojson', '0.2.1'
+  s.add_dependency 'pg', '0.11.0' if postgresql_installed?
+  s.add_dependency 'json', '1.5.3'
+end

data/lib/cartodb-rb-client/cartodb/client/authorization.rb

@@ -0,0 +1,58 @@
+require 'oauth/request_proxy/typhoeus_request'
+
+module CartoDB
+  module Client
+    module Authorization
+
+      def signed_request(request_uri, arguments)
+        arguments[:disable_ssl_peer_verification] = true
+
+        request = Typhoeus::Request.new(request_uri, arguments)
+
+        request.headers.merge!({"Authorization" => oauth_helper(request, request_uri).header})
+
+        request
+      end
+      private :signed_request
+
+      def access_token
+        return @access_token if @access_token
+
+        @access_token ||= if CartoDB::Settings['oauth_access_token'] && CartoDB::Settings['oauth_access_token_secret']
+          OAuth::AccessToken.new(oauth_consumer, CartoDB::Settings['oauth_access_token'], CartoDB::Settings['oauth_access_token_secret'])
+        elsif CartoDB::Settings['username'] && CartoDB::Settings['password']
+
+          x_auth_params = {
+            :x_auth_mode => :client_auth,
+            :x_auth_username => CartoDB::Settings['username'],
+            :x_auth_password => CartoDB::Settings['password']
+          }
+          response = oauth_consumer.request(:post, oauth_consumer.access_token_url,  nil, {}, x_auth_params)
+
+          values = response.body.split('&').inject({}) { |h,v| h[v.split("=")[0]] = v.split("=")[1]; h }
+
+          OAuth::AccessToken.new(oauth_consumer, values["oauth_token"], values["oauth_token_secret"])
+        else
+          nil
+        end
+      end
+      private :access_token
+
+      def oauth_params
+        {:consumer => oauth_consumer, :token => access_token}
+      end
+      private :oauth_params
+
+      def oauth_consumer
+        @oauth_consumer ||= OAuth::Consumer.new(CartoDB::Settings['oauth_key'], CartoDB::Settings['oauth_secret'], :site => CartoDB::Settings['host'])
+      end
+      private :oauth_consumer
+
+      def oauth_helper(request, request_uri)
+        OAuth::Client::Helper.new(request, oauth_params.merge(:request_uri => request_uri))
+      end
+      private :oauth_helper
+
+    end
+  end
+end

data/lib/cartodb-rb-client/cartodb/client/cache.rb

@@ -0,0 +1,14 @@
+module CartoDB
+  module Client
+    class Cache < Hash
+
+      def get(key)
+        self[key]
+      end
+
+      def set(key, object, timeout = 0)
+        self[key] = object
+      end
+    end
+  end
+end

data/lib/cartodb-rb-client/cartodb/client/connection/base.rb

@@ -0,0 +1,44 @@
+module CartoDB
+  module Client
+    module Connection
+      class Base
+
+        attr_reader :active_connection
+
+        def initialize
+          raise Exception.new 'CartoDB settings not found' if CartoDB::Settings.nil?
+
+          @active_connection = if cartodb_settings?
+            CartoDB::Client::Connection::CartoDBConnection.new(settings)
+          elsif postgresql_settings?
+            CartoDB::Client::Connection::PostgreSQL.new(settings)
+          end
+        end
+
+        def method_missing(method, *args, &block)
+          if @active_connection.respond_to?(method)
+            @active_connection.send(method, *args, &block)
+          else
+            super
+          end
+        end
+
+        def settings
+          CartoDB::Settings || {}
+        end
+        private :settings
+
+        def cartodb_settings?
+          settings.has_key?('oauth_key') && settings.has_key?('oauth_secret')
+        end
+        private :cartodb_settings?
+
+        def postgresql_settings?
+          settings.has_key?('host') && settings.has_key?('user') && settings.has_key?('password') && settings.has_key?('database')
+        end
+        private :postgresql_settings?
+
+      end
+    end
+  end
+end