hubba 0.5.2 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8362d3b3f03aadf2fb3708be499e3daeccfe343d
-  data.tar.gz: ce865016b107b78fbd72d3817364040551d61596
+  metadata.gz: 338508b7de32e5872cb8d7c2d84ccbee8f2af484
+  data.tar.gz: 9995ea758dd641965ada299c49c2d46837bfbf03
 SHA512:
-  metadata.gz: 37c9ed873b55c67f5db957ea663222f3a6c0bb9ee8e4b5c58ca52917159407e1cf88e2bba9f86bcf63d42431a531dc09c0954bd9e9f1c66a0b4dab724c34534d
-  data.tar.gz: 9fbb4951feade4506e5721c9cb635856227f346def9f11d50557048f8acb41e1e927901617de5177d9c8363c2513b9bfa3b354b7bc5f532c77f1b53e6d0dd525
+  metadata.gz: 34904326c8d6ba4461fe2e76b2f6708a4b539ccb2d1f08eb702013b4146f4f71d958894dc314d6b7d49e202fa59ddd701a8cd32fa4f5c7b926453219e4ad6682
+  data.tar.gz: 82506b15eef45965858b73fc151b52a0b63f09764ec076e4dc1bef740f03e92e1d0bb0a40bb6bb2f7419738bec52887f4e6036a689871b75b399b1efb7f90c85

data/Manifest.txt

@@ -3,19 +3,12 @@ Manifest.txt
 README.md
 Rakefile
 lib/hubba.rb
-lib/hubba/cache.rb
-lib/hubba/client.rb
+lib/hubba/config.rb
 lib/hubba/github.rb
+lib/hubba/reposet.rb
 lib/hubba/stats.rb
+lib/hubba/update.rb
+lib/hubba/update_traffic.rb
 lib/hubba/version.rb
-test/cache/users~geraldb~orgs.json
-test/cache/users~geraldb~repos.json
 test/helper.rb
-test/stats/jekyll~minima.json
-test/stats/openblockchains~awesome-blockchains.json
-test/stats/opendatajson~factbook.json.json
-test/stats/poole~hyde.json
-test/test_cache.rb
 test/test_config.rb
-test/test_stats.rb
-test/test_stats_tmp.rb

data/README.md

@@ -10,8 +10,134 @@ hubba gem - (yet) another (lite) GitHub HTTP API client / library
 
 ## Usage
 
-TBD
 
+### Step 0:  Secrets, Secrets, Secrets - Your Authentication Token
+
+Note: Set your GitHub env credentials (personal access token preferred) e.g.
+
+```
+set HUBBA_TOKEN=abcdef0123456789
+#   - or -
+set HUBBA_USER=you
+set HUBBA_PASSWORD=topsecret
+```
+
+
+### Step 1: Get a list of all your repos
+
+Use the GitHub API to get a list of all your repos:
+
+``` ruby
+require 'hubba'
+
+h = Hubba.reposet( 'geraldb' )
+pp h
+
+File.open( './repos.yml', 'w' ) { |f| f.write( h.to_yaml ) }
+```
+
+resulting in:
+
+``` yaml
+geraldb (11):
+- austria
+- catalog
+- chelitas
+- geraldb.github.io
+- logos
+- sandbox
+- talks
+- web-proxy-win
+- webcomponents
+- webpub-reader
+- wine.db.tools
+
+openfootball (41):
+- africa-cup
+- austria
+- club-world-cup
+- clubs
+- confed-cup
+- copa-america
+- copa-libertadores
+- copa-sudamericana
+- deutschland
+# ...
+```
+
+
+Note: If you have more than one account (e.g. an extra robot account or such)
+you can add them along e.g.
+
+
+``` ruby
+h = Hubba.reposet( 'geraldb', 'yorobot' )
+pp h
+```
+
+
+Note: By default all your repos from organizations get auto-included -
+use the `orgs: false` option to turn off auto-inclusion.
+
+Note: By default all (personal) repos, that is, repos in your primary (first)
+account that are forks get auto-excluded.
+
+
+
+### Step 2: Update repo statistics (daily / weekly / monthly)
+
+
+#### Basics (commits, stars, forks, topics, etc.)
+
+Use `update_stats` to
+to get the latest commit, star count and more for all your repos
+listed in `./repos.yml` via the GitHub API:
+
+``` ruby
+Hubba.update_stats( './repos.yml' )
+```
+
+Note: By default the datafiles (one per repo)
+get stored in the `./data` directory.
+
+
+#### Traffic (page views, clones, referrers, etc.)
+
+Use `update_traffic` to
+to get the latest traffic stats (page views, clones, referrers, etc.)
+for all your repos listed in `./repos.yml` via the GitHub API.
+
+``` ruby
+Hubba.update_traffic( './repos.yml' )
+```
+
+Note: Access to traffic statistics via the GitHub API
+requires push access for your GitHub (personal access) token.
+
+
+
+
+### Step 3: Generate some statistics / analytics reports
+
+
+See the [hubba-reports gem](https://github.com/rubycoco/git/tree/master/hubba-reports) on how to use pre-built/pre-packaged ready-to-use
+github statistics / analytics reports.
+
+
+
+That's all for now.
+
+
+
+## Installation
+
+Use
+
+    gem install hubba
+
+or add the gem to your Gemfile
+
+    gem 'hubba'
 
 
 ## License

data/lib/hubba.rb

@@ -1,13 +1,46 @@
 # 3rd party (our own)
 require 'webclient'
 
+
+###############
+## helpers
+
+def save_json( path, data )    ## data - hash or array
+  File.open( path, 'w:utf-8' ) do |f|
+    f.write( JSON.pretty_generate( data ))
+  end
+end
+
+def save_yaml( path, data )
+  File.open( path, 'w:utf-8' ) do |f|
+    f.write( data.to_yaml )
+  end
+end
+
+
+
 # our own code
 require 'hubba/version'   # note: let version always go first
-require 'hubba/cache'
-require 'hubba/client'
+require 'hubba/config'
 require 'hubba/github'
+require 'hubba/reposet'
+
+### update stats (github data) machinery
 require 'hubba/stats'
+require 'hubba/update'
+require 'hubba/update_traffic'
+
+
+
+
+############
+# add convenience alias for alternate spelling - why? why not?
+module Hubba
+  GitHub = Github
+end
 
 
 # say hello
-puts Hubba.banner    if defined?($RUBYCOCO_DEBUG)
+puts Hubba.banner
+
+

data/lib/hubba/config.rb

@@ -0,0 +1,51 @@
+module Hubba
+
+class Configuration
+  def data_dir()          @data_dir || './data'; end
+  def data_dir=( value )  @data_dir = value;     end
+
+  ###  todo/check: rename to/use tmp_dir - why? why not?
+  def cache_dir()         @cache_dir || './cache'; end
+  def cache_dir=( value ) @cache_dir = value;      end
+
+
+  # try default setup via ENV variables
+  def token()            @token || ENV[ 'HUBBA_TOKEN' ]; end
+  def token=( value )    @token = value;                 end
+
+  # todo/check: use HUBBA_LOGIN - why? why not?
+  def user()             @user     || ENV[ 'HUBBA_USER' ]; end
+  def password()         @password || ENV[ 'HUBBA_PASSWORD' ]; end
+  def user=( value )     @user     = value;                end
+  def password=( value ) @password = value;                end
+
+end  # class Configuration
+
+
+## lets you use
+##   Hubba.configure do |config|
+##      config.token    = 'secret'
+##        -or-
+##      config.user     = 'testdada'
+##      config.password = 'secret'
+##   end
+##
+##   move configure block to GitHub class - why? why not?
+##   e.g. GitHub.configure do |config|
+##          ...
+##        end
+
+
+def self.configuration
+ @configuration ||= Configuration.new
+end
+class << self
+  alias_method :config, :configuration
+end
+
+
+def self.configure
+ yield( configuration )
+end
+
+end # module Hubba

data/lib/hubba/github.rb

@@ -1,89 +1,57 @@
 module Hubba
 
-class Configuration
-   attr_accessor :token
 
-   attr_accessor :user
-   attr_accessor :password
-
-   def initialize
-     # try default setup via ENV variables
-     @token    = ENV[ 'HUBBA_TOKEN' ]
-
-     @user     = ENV[ 'HUBBA_USER' ]    ## use HUBBA_LOGIN - why? why not?
-     @password = ENV[ 'HUBBA_PASSWORD' ]
-   end
-end
-
-## lets you use
-##   Hubba.configure do |config|
-##      config.token    = 'secret'
-##      #-or-
-##      config.user     = 'testdada'
-##      config.password = 'secret'
-##   end
-##
-##   move configure block to GitHub class - why? why not?
-##   e.g. GitHub.configure do |config|
-##          ...
-##        end
-
-
-def self.configuration
-  @configuration ||= Configuration.new
-end
-
-def self.configure
-  yield( configuration )
-end
-
-
-class Resource
-  attr_reader :data
-  def initialize( data )
-    @data = data
+class Github
+  BASE_URL = 'https://api.github.com'
+
+  ###############
+  ## (nested) classes for "wrapped" response (parsed json body)
+  class Resource
+    attr_reader :data
+    def initialize( data )
+      @data = data
+    end
   end
-end
 
-class Repos < Resource
-  def names
-    ## sort by name
-    data.map { |item| item['name'] }.sort
+  class Repos < Resource
+    def names
+      ## sort by name
+      data.map { |item| item['name'] }.sort
+    end
   end
-end
 
-class Orgs < Resource
-  def logins
-    ## sort by name
-    data.map { |item| item['login'] }.sort
+  class Orgs < Resource
+    def logins
+      ## sort by name
+      data.map { |item| item['login'] }.sort
+    end
+    alias_method :names, :logins   ## add name alias - why? why not?
   end
-  alias_method :names, :logins   ## add name alias - why? why not?
-end
-
 
 
-class Github
-
-def initialize( cache_dir: './cache' )
-   @cache  = Cache.new( cache_dir )
-
-   @client = if Hubba.configuration.token
-               Client.new( token: Hubba.configuration.token )
-             elsif Hubba.configuration.user &&
-                   Hubba.configuration.password
-               Client.new( user:     Hubba.configuration.user,
-                           password: Hubba.configuration.password )
-             else
-               Client.new
-             end
 
-   @offline = false
+def initialize( token: nil,
+                user:  nil,
+                password: nil )
+   @token    = nil
+   @user     = nil
+   @password = nil
+
+   if token                         ## 1a) give preference to passed in token
+     @token     = token
+   elsif user && password           ## 1b)  or passed in user/password credentials
+     @user      = user
+     @password  = password
+   elsif Hubba.config.token         ## 2a) followed by configured (or env) token
+     @token     = Hubba.config.token
+   elsif Hubba.config.user && Hubba.config.password   ## 2b)
+     @user      = Hubba.config.user
+     @password  = Hubba.config.password
+   else                             ## 3)
+     ## no token or credentials passed in or configured
+   end
 end
 
-def offline!()  @offline = true; end   ## switch to offline  - todo: find a "better" way - why? why not?
-def online!()   @offline = false; end
-def offline?()  @offline == true; end
-def online?()   @offline == false; end
 
 
 def user( name )
@@ -108,6 +76,7 @@ def user_orgs( name )
 end
 
 
+
 def org( name )
   Resource.new( get "/orgs/#{name}" )
 end
@@ -122,25 +91,120 @@ def repo( full_name )   ## full_name (handle) e.g. henrythemes/jekyll-starter-th
   Resource.new( get "/repos/#{full_name}" )
 end
 
+def repo_languages( full_name )
+  Resource.new( get "/repos/#{full_name}/languages" )
+end
+
+def repo_topics( full_name )
+  ## note: requires "api preview" accept headers (overwrites default v3+json)
+  ##  e.g. application/vnd.github.mercy-preview+json
+  Resource.new( get( "/repos/#{full_name}/topics", preview: 'mercy' ) )
+end
+
+
 def repo_commits( full_name )
   Resource.new( get "/repos/#{full_name}/commits" )
 end
 
 
+def repo_traffic_clones( full_name )
+ # Get repository clones
+ # Get the total number of clones and breakdown per day or week
+ #   for the last 14 days.
+ # Timestamps are aligned to UTC midnight of the beginning of the day or week.
+ # Week begins on Monday.
+ Resource.new( get "/repos/#{full_name}/traffic/clones" )
+end
+
+def repo_traffic_views( full_name )
+ # Get page views
+ # Get the total number of views and breakdown per day or week
+ #  for the last 14 days.
+ # Timestamps are aligned to UTC midnight of the beginning of the day or week.
+ # Week begins on Monday.
+ Resource.new( get "/repos/#{full_name}/traffic/views" )
+end
+
+
+def repo_traffic_popular_paths( full_name )
+ # Get top referral paths
+ # Get the top 10 popular contents over the last 14 days.
+ Resource.new( get "/repos/#{full_name}/traffic/popular/paths" )
+end
+
+def repo_traffic_popular_referrers( full_name )
+ # Get top referral sources
+ # Get the top 10 referrers over the last 14 days.
+ Resource.new( get "/repos/#{full_name}/traffic/popular/referrers" )
+end
+
+
+
+
 private
-def get( request_uri )
-  if offline?
-    @cache.get( request_uri )
+def get( request_uri, preview: nil )
+
+  puts "GET #{request_uri}"
+
+  ## note: request_uri ALWAYS starts with leading /, thus use + for now!!!
+  #          e.g. /users/geraldb
+  #               /users/geraldb/repos
+  url = BASE_URL + request_uri
+
+
+  headers = {}
+  ## add default headers if nothing (custom) set / passed-in
+  headers['User-Agent'] = "ruby/hubba v#{VERSION}"          ## required by GitHub API
+  headers['Accept']     =  if preview   # e.g. mercy or ???
+                             "application/vnd.github.#{preview}-preview+json"
+                           else
+                             'application/vnd.github.v3+json'  ## default - recommend by GitHub API
+                           end
+
+  auth = []
+  ## check if credentials (user/password) present - if yes, use basic auth
+  if @token
+    puts "  using (personal access) token - starting with: #{@token[0..6]}**********"
+    headers['Authorization'] = "token #{@token}"
+    ## token works like:
+    ##  curl -H 'Authorization: token my_access_token' https://api.github.com/user/repos
+  elsif @user && @password
+    puts "  using basic auth - user: #{@user}, password: ***"
+    ## use credential auth "tuple" (that is, array with two string items) for now
+    ##  or use Webclient::HttpBasicAuth or something - why? why not?
+    auth = [@user, @password]
+    # req.basic_auth( @user, @password )
   else
-    @client.get( request_uri )
+    puts "  using no credentials (no token, no user/password)"
   end
-end
 
-end  # class Github
+  res = Webclient.get( url,
+                       headers: headers,
+                       auth:    auth )
 
-############
-# add convenience alias for alternate spelling - why? why not?
-GitHub = Github
+  # Get specific header
+  # response["content-type"]
+  # => "text/html; charset=UTF-8"
 
+  # Iterate all response headers.
+  # puts "HTTP HEADERS:"
+  # res.headers.each do |key, value|
+  #  puts "  #{key}: >#{value}<"
+  # end
+  # puts
 
-end # module Hubba
+  # => "location => http://www.google.com/"
+  # => "content-type => text/html; charset=UTF-8"
+  # ...
+
+  if res.status.ok?
+    res.json
+  else
+    puts "!! HTTP ERROR: #{res.status.code} #{res.status.message}:"
+    pp res.raw
+    exit 1
+  end
+end  # method get
+
+end  # class Github
+end  # module Hubba