ddollar-octopi 0.0.13

data/.gitignore

@@ -0,0 +1,3 @@
+examples/github.yml
+rdoc/
+pkg/

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Felipe Coury
+
+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.rdoc

@@ -0,0 +1,169 @@
+= octopi
+
+Octopi is a Ruby interface to GitHub API v2 (http://develop.github.com).
+
+To install it as a Gem, just run:
+
+  $ sudo gem install octopi
+
+Get notifications via Twitter, following @octopi_gem:
+http://twitter.com/octopi_gem
+  
+== Authenticated Usage
+
+=== Seamless authentication using .gitconfig defaults
+
+If you have your <tt>~/.gitconfig</tt> file in place, and you have a [github] section (if you don't, take a look at this GitHub Guides entry: http://github.com/guides/tell-git-your-user-name-and-email-address), you can use seamless authentication using this method:
+
+  authenticated do |g|
+    repo = g.repository("api-labrat")
+    (...)
+  end
+  
+=== Explicit authentication
+
+Sometimes, you may not want to get authentication data from <tt>~/.gitconfig</tt>. You want to use GitHub API authenticated as a third party. For this use case, you have a couple of options too.
+
+<b>1. Providing login and token inline:</b>
+
+  authenticated_with "mylogin", "mytoken" do |g|
+    repo = g.repository("api-labrat")
+    issue = repo.open_issue :title => "Sample issue", 
+      :body => "This issue was opened using GitHub API and Octopi"
+    puts issue.number
+  end
+  
+<b>2. Providing a YAML file with authentication information:</b>
+
+Use the following format:
+
+  #
+  # Octopi GitHub API configuration file
+  #
+
+  # GitHub user login and token
+  login: github-username
+  token: github-token
+
+  # Trace level
+  # Possible values:
+  #   false - no tracing, same as if the param is ommited
+  #   true  - will output each POST or GET operation to the stdout
+  #   curl  - same as true, but in addition will output the curl equivalent of each command (for debugging)
+  trace: curl
+  
+And change the way you connect to:
+
+  authenticated_with :config => "github.yml" do |g|
+    (...)
+  end
+  
+== Anonymous Usage
+
+This reflects the usage of the API to retrieve information on a read-only fashion, where the user doesn't have to be authenticated.
+
+=== Users API
+
+Getting user information
+
+  user = User.find("fcoury")
+  puts "#{user.name} is being followed by #{user.followers.join(", ")} and following #{user.following.join(", ")}"
+
+The bang methods `followers!` and `following!` retrieves a full User object for each user login returned, so it has to be used carefully.
+
+  user.followers!.each do |u|
+    puts "  - #{u.name} (#{u.login}) has #{u.public_repo_count} repo(s)"
+  end
+  
+Searching for user
+
+  users = User.find_all("silva")
+  puts "#{users.size} users found for 'silva':"
+  users.each do |u|
+    puts "  - #{u.name}"
+  end
+
+=== Repositories API
+
+  repo = user.repository("octopi") # same as: Repository.find("fcoury", "octopi")
+  puts "Repository: #{repo.name} - #{repo.description} (by #{repo.owner}) - #{repo.url}"
+  puts "      Tags: #{repo.tags and repo.tags.map {|t| t.name}.join(", ")}"
+  
+Search:
+
+  repos = Repository.find_all("ruby", "git")
+  puts "#{repos.size} repository(ies) with 'ruby' and 'git':"
+  repos.each do |r|
+    puts "  - #{r.name}"
+  end
+  
+Issues API integrated into the Repository object:
+
+  issue = repo.issues.first
+  puts "First open issue: #{issue.number} - #{issue.title} - Created at: #{issue.created_at}"
+
+Single issue information:
+
+  issue = repo.issue(11)
+
+Commits API information from a Repository object:
+
+  first_commit = repo.commits.first
+  puts "First commit: #{first_commit.id} - #{first_commit.message} - by #{first_commit.author['name']}"
+  
+Single commit information:
+
+  puts "Diff:"
+  first_commit.details.modified.each {|m| puts "#{m['filename']} DIFF: #{m['diff']}" }
+
+== Tracing
+
+=== Levels
+
+You can can use tracing to enable better debugging output when something goes wrong. There are 3 tracing levels: 
+
+* false (default) - no tracing
+* true - will output each GET and POST calls, along with URL and params
+* curl - same as true, but additionally outputs the curl command to replicate the issue
+
+If you choose curl tracing, the curl command equivalent to each command sent to GitHub will be output to the stdout, like this example:
+
+  => Trace on: curl
+  POST: /issues/open/webbynode/api-labrat params: body=This issue was opened using GitHub API and Octopi, title=Sample issue
+  ===== curl version
+  curl -F 'body=This issue was opened using GitHub API and Octopi' -F 'login=mylogin' -F 'token=mytoken' -F 'title=Sample issue' http://github.com/api/v2/issues/open/webbynode/api-labrat
+  ==================
+  
+=== Enabling
+
+Tracing can be enabled in different ways, depending on the API feature you're using:
+
+<b>Anonymous (this will be improved later):</b>
+
+  ANONYMOUS_API.trace_level = "trace-level"
+  
+<b>Seamless authenticated</b>
+
+  authenticated :trace => "trace-level" do |g|; ...; end
+  
+<b>Explicitly authenticated</b>
+
+Current version of explicit authentication requires a :config param to a YAML file to allow tracing. For enabling tracing on a YAML file refer to the config.yml example presented on the Explicit authentication section.
+
+== Author
+
+* Felipe Coury - http://felipecoury.com
+* HasMany.info blog - http://hasmany.info
+
+== Contributors
+
+In alphabetical order:
+
+* Brandon Calloway - http://github.com/bcalloway
+* runpaint - http://github.com/runpaint
+
+Thanks guys!
+
+== Copyright
+
+Copyright (c) 2009 Felipe Coury. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,83 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "octopi"
+    gem.summary = %Q{A Ruby interface to GitHub API v2}
+    gem.email = "felipe.coury@gmail.com"
+    gem.homepage = "http://github.com/fcoury/octopi"
+    gem.authors = ["Felipe Coury"]
+    gem.rubyforge_project = "octopi"
+
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+rescue LoadError
+  puts "Jeweler not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
+end
+
+begin
+  require 'rake/contrib/sshpublisher'
+  namespace :rubyforge do
+
+    desc "Release gem and RDoc documentation to RubyForge"
+    task :release => ["rubyforge:release:gem", "rubyforge:release:docs"]
+
+    namespace :release do
+      desc "Publish RDoc to RubyForge."
+      task :docs => [:rdoc] do
+        config = YAML.load(
+            File.read(File.expand_path('~/.rubyforge/user-config.yml'))
+        )
+
+        host = "#{config['username']}@rubyforge.org"
+        remote_dir = "/var/www/gforge-projects/octopi/"
+        local_dir = 'rdoc'
+
+        Rake::SshDirPublisher.new(host, remote_dir, local_dir).upload
+      end
+    end
+  end
+rescue LoadError
+  puts "Rake SshDirPublisher is unavailable or your rubyforge environment is not configured."
+end
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/*_test.rb'
+  test.verbose = false
+end
+
+begin
+  require 'rcov/rcovtask'
+  Rcov::RcovTask.new do |test|
+    test.libs << 'test'
+    test.pattern = 'test/**/*_test.rb'
+    test.verbose = true
+  end
+rescue LoadError
+  task :rcov do
+    abort "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
+  end
+end
+
+
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  if File.exist?('VERSION.yml')
+    config = YAML.load(File.read('VERSION.yml'))
+    version = "#{config[:major]}.#{config[:minor]}.#{config[:patch]}"
+  else
+    version = ""
+  end
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "octopi #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+

data/VERSION.yml

@@ -0,0 +1,4 @@
+--- 
+:patch: 13
+:major: 0
+:minor: 0

data/contrib/backup.rb

@@ -0,0 +1,100 @@
+require File.join(File.dirname(__FILE__), '..', 'lib', 'octopi')
+
+USAGE_MSG = <<EOF
+Usage: #{$0} <user> [<directory>]
+
+Performs a backup of the named user's GitHub.com data.
+
+This script will fetch the repositories, along with their metadata and
+associated issues, for the named user. It will also retrieve the user's
+profile, and those of his followers. This data will be stored in
+<directory>/<user>. If a directory is not supplied, ~/.github-backup will be
+used instead.
+EOF
+# TODO: Accept list of targets as argument. The main use case is somebody
+# wanting all of their repositories checked out, without the performane hit
+# and clutter of the extraneous metadata,
+include Octopi
+
+class Object
+  def to_yaml_file(file)
+    File.open("#{file}.yaml", 'w') do |f|
+      YAML.dump(self, f)
+    end
+  end
+end
+
+TARGETS = [:user, :followers, :repositories, :issues]
+
+@user, @basedir = ARGV
+raise ArgumentError, USAGE_MSG unless @user
+@basedir ||= File.expand_path("~/.github-backup")
+@basedir = File.join(@basedir,@user)
+TARGETS.map{|k| k.to_s}.each do |dir|
+  dir = File.join(@basedir,dir)
+  FileUtils.mkdir_p(dir) unless File.exists? dir
+end  
+
+@user = User.find(@user)
+
+def user
+  puts "* Saving profile"
+  @user.to_yaml_file(@user.login)
+end
+
+def followers
+  @user.followers!.each do |follower|
+    puts "* #{follower.login} (#{follower.name})"
+    follower.to_yaml_file(follower.login)
+  end  
+end
+
+def repositories
+  @user.repositories.each do |repo|
+    puts "* #{repo.name} (#{repo.description})\n---"
+    
+    git_dir = File.join(repo.name,'.git')
+    # FIXME: Instead of just checking for a Git directory, we could try `git
+    # pull`, and if that indicates that the repository doesn't exist, `git
+    # clone`
+    if File.exists? git_dir
+      Dir.chdir repo.name do
+        # FIXME: If this fails, try deleting the clone and re-cloning?
+        # FIXME: Confirm this is the best solution as opposed to re-cloning
+        # every time, using `git fetch` or `git clone --mirror`.
+        system("git pull")
+      end
+    else  
+      system("git clone #{repo.clone_url}")
+    end
+    repo.to_yaml_file(repo.name)
+    puts
+  end
+end
+
+# TODO: For forked repositories whose parents have issue trackers, get their
+# issues instead.
+def issues
+  FileUtils.mkdir_p @user.repositories.map{|r| r.name}
+  @user.repositories.each do |repo|
+    puts "#{repo.name}"
+    Dir.chdir(repo.name) do
+      repo.all_issues.each do |issue|
+        puts "* #{issue.title} [#{issue.state}]"
+        issue.to_yaml_file(issue.number)
+      end
+    end  
+  end    
+end
+
+TARGETS.each do |target|
+  target.to_s.each do |title|
+    puts title.capitalize
+    title.length.times {print '#'}
+  end  
+  puts
+  Dir.chdir(File.join(@basedir, target.to_s)) do
+    send(target)
+  end
+  puts
+end  

data/examples/authenticated.rb

@@ -0,0 +1,20 @@
+require File.join(File.dirname(__FILE__), '..', 'lib', 'octopi')
+
+include Octopi
+
+authenticated :trace => "curl" do |g|
+  repo = g.repository("api-labrat")
+  
+  issue = repo.open_issue :title => "Sample issue", 
+    :body => "This issue was opened using GitHub API and Octopi"
+  puts "Successfully opened issue \##{issue.number}"
+  
+  # # labels = issue.add_label "Working", "Todo"
+  # # puts "Labels: #{labels.inspect}"
+  
+  issue.close
+  puts "Successfully closed issue \##{issue.number}"
+  
+  # labels = issue.remove_label "Todo"
+  # puts "Successfully removed label Todo. Current labels: #{labels.inspect}"
+end

data/examples/github.yml.example

@@ -0,0 +1,14 @@
+#
+# Octopi GitHub API configuration file
+#
+
+# GitHub user login and token
+login: github-username
+token: github-token
+
+# Trace level
+# Possible values:
+#   false - no tracing, same as if the param is ommited
+#   true  - will output each POST or GET operation to the stdout
+#   curl  - same as true, but in addition will output the curl equivalent of each command (for debugging)
+trace: curl

data/examples/issues.rb

@@ -0,0 +1,18 @@
+require File.join(File.dirname(__FILE__), '..', 'lib', 'octopi')
+
+include Octopi
+
+user = User.find("fcoury")
+puts user.name
+
+repo = user.repository("octopi")
+puts repo.description
+
+issue = Issue.find_all(user.login, repo.name).first
+puts "First open issue: #{issue.number} - #{issue.title} - Created at: #{issue.created_at}"
+
+issue2 = repo.issues.first
+puts "First open issue: #{issue.number} - #{issue.title} - Created at: #{issue.created_at}"
+
+issue3 = repo.issue(issue2.number)
+puts "First open issue: #{issue.number} - #{issue.title} - Created at: #{issue.created_at}"

data/examples/overall.rb

@@ -0,0 +1,50 @@
+require File.join(File.dirname(__FILE__), '..', 'lib', 'octopi')
+
+include Octopi
+
+# user information
+user = User.find("fcoury")
+puts "#{user.name} is being followed by #{user.followers.join(", ")} and following #{user.following.join(", ")}"
+
+# the bang version of followers and following 
+# fetches user object for each user, but is 
+# a lot more expensive
+user.followers!.each do |u|
+  puts "  - #{u.name} (#{u.login}) has #{u.public_repo_count} repo(s)"
+end
+
+# search user
+users = User.find_all("silva")
+puts "#{users.size} users found for 'silva':"
+users.each do |u|
+  puts "  - #{u.name}"
+end
+
+# repository information
+# to get all repos for user: user.repositories
+repo = user.repository("octopi") # same as: Repository.find("fcoury", "octopi")
+puts "Repository: #{repo.name} - #{repo.description} (by #{repo.owner}) - #{repo.url}"
+puts "      Tags: #{repo.tags and repo.tags.map {|t| t.name}.join(", ")}"
+
+issue = repo.issues.first
+puts "Sample open issue: #{issue.number} - #{issue.title} - Created at: #{issue.created_at}"
+
+# commits of a the repository
+commit = repo.commits.first
+puts "Commit: #{commit.id} - #{commit.message} - by #{commit.author['name']}"
+
+# single commit information
+# details is the same as: Commit.find(commit)
+puts "Diff:"
+commit.details.modified.each {|m| puts "#{m['filename']} DIFF: #{m['diff']}" }
+
+# repository search
+repos = Repository.find_all("ruby", "git")
+puts "#{repos.size} repository(ies) with 'ruby' and 'git':"
+repos.each do |r|
+  puts "  - #{r.name}"
+end
+
+# connect "user", "<< token >>" do |github|
+#   puts github.user.name
+# end