tqdm 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: cd2cc2ae1f682e5a99a462698ec94a5363752ad2
-  data.tar.gz: ee799a36386c9a151fe555e0d856d56bf0650e66
+  metadata.gz: 18fbbebb6aadc15bb9b2cea3caf012e49e087908
+  data.tar.gz: 3da06e2b16e451592014ebdf94b0012ad165d589
 SHA512:
-  metadata.gz: be8161fd9956a94aa0bf195b7b1de88c3e063c4438b6ab88ba47019c2948ee1ccb31dfe1442930ac6023a8bdb64feaa9a15368f650c25a819fc39f9390631102
-  data.tar.gz: ae7f1c956f1f10121130909124f4d26794fea5fd94690f6ba8420db3f1b0ac060b7f4728123c4525cd0c1f809445b80d08c7256d078f0297cb9e96fc21945fcc
+  metadata.gz: 0aefc092a3fb9a925107689fe03eaf8196393a60331fcb41031bca5159423693e65db4bd5cf60a333cb0d16c1cb0eaf9dfe5682003955665d1bdedcf0ea49d70
+  data.tar.gz: 7bdd329b81bca2cc2951753815c7459f58ac6009b8dffa8e5a650cbb921f67cc7ac7b4e976478a5fd9d09fcbcea82842757dc80d1f8b83a28ebd55adc711abca

data/.yardopts

@@ -0,0 +1,4 @@
+--readme README.md
+--charset utf-8
+--markup markdown
+'lib/**/*.rb'

data/README.md

@@ -2,22 +2,32 @@
 
 tqdm-ruby is a small utility to show a progress indicator while iterating through an Enumerable object.
 
-It is a port of the excellent tdqm library for python: <a href="https://github.com/tqdm/tqdm" target="_blank">https://github.com/tqdm/tqdm</a>.
+It is a port of the excellent [tdqm library][tqdm] for python.
 
-Call #tqdm on any `Enumerable`, which enhances the object so that iterating over it will produce an animated progress bar on `$stderr`.
+Call `#tqdm` on any `Enumerable`, which enhances the object so that iterating over it will produce an animated progress bar on `$stderr`.
 
-    require 'tqdm'
-    (0...1000).tqdm.each {|x| sleep 0.01 }
+```ruby
+require 'tqdm'
+(0...1000).tqdm.each { |x| sleep 0.01 }
+```
 
 The default output looks like this:
 
-    |####------| 492/1000  49% [elapsed: 00:05 left: 00:05, 88.81 iters/sec]
+![|####------| 492/1000  49% [elapsed: 00:05 left: 00:05, 88.81 iters/sec]](http://i.imgur.com/6y0t7XS.gif)
 
-It works equally well from within [pry](http://pryrepl.org/) and [Jupyter notebooks](https://jupyter.org/).
+It works equally well from within irb, [pry](http://pryrepl.org/), and [Jupyter notebooks](https://jupyter.org/).
+
+*Why not progressbar, ruby-progressbar, etc.?* These have a bazillion formatting options and you typically have to update the progressbar object throughout other code. tqdm pleasantly encourages the laziest imaginable usage, in that you "set it and forget it".
+
+[tqdm]: https://github.com/tqdm/tqdm
 
 ## Install
 
-Add this line to your application's `Gemfile`:
+Install it globally from [Rubygems](https://rubygems.org/gems/tqdm):
+
+    $ gem install tqdm    # (might need sudo on OS X)
+
+*or* add this line to your application's Gemfile:
 
     gem 'tqdm'
 
@@ -25,16 +35,44 @@ And then execute:
 
     $ bundle
 
-Or install it yourself as:
+## Usage
 
-    $ gem install tqdm
+All `Enumerable` objects gain access to the `#tqdm` method, which returns an enhanced object wherein any iteration (by calling `#each` or any of its relatives, e.g., `#each_with_index`, `#each_with_object`, etc.) produces an animated progress bar on `$stderr`.
 
-## Usage
+Options can be provided for `#tqdm`:
+
+```ruby
+require 'tqdm'
+Hash[*(1..1000)].tqdm(desc: "working on it", leave: true).each { |x| sleep 0.01 }
+```
+
+The following options are available:
+
+- `desc`: Short string, describing the progress, added to the beginning of the line
+- `total`: Expected number of iterations, if not given, `self.size` is used
+- `file`: A file-like object to output the progress message to, by default, `$stderr`
+- `leave`: A boolean (default false). Should the progress bar should stay on screen after it's done?
+- `min_interval`: Default is `0.5`. If less than `min_interval` seconds or `min_iters` iterations have passed since the last progress meter update, it is not re-printed (decreases IO thrashing).
+- `min_iters`: Default is `1`. See previous.
+
+[Sequel](http://sequel.jeremyevans.net/) is an amazing database library for Ruby. tqdm can enhance its [`Dataset`](http://sequel.jeremyevans.net/rdoc/classes/Sequel/Dataset.html) objects to show progress while iterating (same options as above):
+
+```ruby
+require 'tqdm/sequel'   # Automatically requires tqdm and sequel
+
+# In-memory database for demonstration purposes
+DB = Sequel.sqlite
+DB.create_table :items do
+  primary_key :id
+  Float :price
+end
 
-All `Enumerable` objects gain access to the `#tqdm` method, which returns an enhanced object wherein any iteration (by calling `#each` or any of its relatives, e.g., `#each_with_index`, `#each_with_object`, etc.) produces an animated progress bar on $stderr.
+# Show progress during big inserts (this isn't new)
+(0..100000).tqdm.each { DB[:items].insert(price: rand * 100) }
 
-    require 'tqdm'
-    (0...100).tqdm.each {|x| sleep 0.01 }
+# Show progress during long SELECT queries
+DB[:items].where{ price > 10 }.tqdm.each { |row| "do some processing here" }
+```
 
 ## Contributing
 

data/lib/core_ext/enumerable.rb

@@ -1,18 +1,23 @@
 require "tqdm"
 
-# This is where the real magic begins
-# All enumerable objects (e.g.) Arrays will have these methods added to them
+# We enhance all enumerable objects (e.g. `Array`, `Hash`, `Range`, ...) by extending the `Enumerable` module.
+# This mixin is only supposed to be present on objects that provide an `#each` method.
+#
+# @see http://ruby-doc.org/core-2.2.3/Enumerable.html
 module Enumerable
   
-  # Upgrades an Enumerable so that any subsequent call to .each will spit out a progress bar
-  # opts is a hash that can include:
-  #   desc: Short string, describing the progress, added to the beginning of the line
-  #   total: Expected number of iterations, if not given, self.size is used
-  #   file: A file-like object to output the progress message to, by default, $stderr
-  #   leave: A boolean (default False) should the progress bar should stay on screen after it's done?
-  #   min_interval: See below
-  #   min_iters: If less than min_interval seconds or min_iters iterations have passed since
+  # Returns a clone of `self` where all calls to `#each` and related methods will print an animated progress bar 
+  # while iterating.
+  #
+  # @param opts [Hash] more options used to control behavior of the progress bar
+  # @option opts [String] :desc a short description added to the beginning of the progress bar
+  # @option opts [Integer] :total (self.size) the expected number of iterations
+  # @option opts [File, IO] :file ($stderr) a file-like object to output the progress bar to
+  # @option opts [Boolean] :leave (false) should the progress bar should stay on screen after it's done?
+  # @option opts [Integer] :min_iters see `:min_interval`
+  # @option opts [Float] :min_interval If less than min_interval seconds or min_iters iterations have passed since
   #              the last progress meter update, it is not updated again.
+  # @return [Enumerable] `self` with the `#each` method wrapped as described above
   def tqdm(opts = {})
     Tqdm::TqdmDecorator.new(self, opts).enhance
   end

data/lib/tqdm.rb

@@ -2,35 +2,89 @@ require "tqdm/version"
 require "tqdm/utils"
 require "core_ext/enumerable"
 
+# Add a progress bar to your loops in a second.
+# A port of Python's [tqdm library](https://github.com/tqdm/tqdm), although we're currently 
+# closer to the feature set of [@noamraph's original release](https://github.com/noamraph/tqdm).
+#
+# Specifically, `Tqdm` enhances `Enumerable` by printing a progress indicator whenever 
+# iterating with `#each` or its close relatives.
+#
+# @author Theodore Pak
+# @see https://github.com/tqdm/tqdm
 module Tqdm
   
+  # The default width of the progress bar, in characters.
+  N_BARS = 10
+  
   class << self
+    # Upgrades `Sequel::Datasets` with the #tqdm method.
+    # @see Enumerable#tqdm
     def enhance_sequel!
       require "tqdm/sequel"
     end
   end
-    
+  
+  # Prints a status line, handling the deletion of previously printed lines with carriage 
+  # returns as necessary. Instantiated by a `TqdmDecorator`.
+  #
+  # @private
   class StatusPrinter
+    # Initialize a new StatusPrinter.
+    #
+    # @param file [File, IO] the status will be printed to this via `#write` and `#flush`
     def initialize(file)
       @file = file
       @last_printed_len = 0
     end
   
-    def print_status(s)
-      @file.write("\r" + s + ' ' * [@last_printed_len - s.size, 0].max)
+    # Prints a line of text to @file, after deleting the previously printed line
+    #
+    # @param line [String] a line of text to be printed
+    # @return [Integer] the number of bytes written
+    def print_status(line)
+      @file.write("\r" + line + ' ' * [@last_printed_len - line.size, 0].max)
       @file.flush
-      @last_printed_len = s.size
+      @last_printed_len = line.size
     end
   end
   
   
+  # Decorates the #each method of an `Enumerable` by wrapping it so that each
+  # iteration produces a pretty progress bar printed to the console or a file handle.
+  #
+  # @note The `Enumerable` is cloned before it is enhanced; it is not modified directly.
+  #
+  # @example Enhances `arr` so that an animated progress bar prints while iterating.
+  #   arr = (0...1000)
+  #   arr_tqdm = TqdmDecorator.new(arr).enhance
+  #   arr_tqdm.each { |x| sleep 0.01 }
   class TqdmDecorator
     
     include Utils
-    
+
+    # Initialize a new TqdmDecorator. Typically you wouldn't use this object, but
+    # would immediately call `#enhance` to retrieve the enhanced `Enumerable`.
+    #
+    # @param enumerable [Enumerable] the Enumerable object to be enhanced
+    # @param opts [Hash] more options used to control behavior of the progress bar
+    # @option opts [String] :desc a short description added to the beginning of the progress bar
+    # @option opts [Integer] :total (self.size) the expected number of iterations
+    # @option opts [File, IO] :file ($stderr) a file-like object to output the progress bar to
+    # @option opts [Boolean] :leave (false) should the progress bar should stay on screen after it's done?
+    # @option opts [Integer] :min_iters see `:min_interval`
+    # @option opts [Float] :min_interval If less than min_interval seconds or min_iters iterations have passed since
+    #              the last progress meter update, it is not updated again.
+    #
+    # @example
+    #   a = (1...1000)
+    #   TqdmDecorator.new(a).enhance.each { |x| sleep 0.01 }
+    #
+    # @example
+    #   a = [1, 2, 3, 4]
+    #   TqdmDecorator.new(a, file: $stdout, leave: true)
     def initialize(enumerable, opts={})
       @enumerable = enumerable
-      @total = opts[:total] || @enumerable.size rescue nil
+      @total = opts[:total] || @enumerable.size rescue @enumerable.count rescue nil
       @prefix = opts[:desc] ? opts[:desc] + ': ' : ''
       @file = opts[:file] || $stderr
       @sp = StatusPrinter.new(@file)
@@ -39,6 +93,7 @@ module Tqdm
       @leave = opts[:leave] || false
     end
     
+    # Starts the textual progress bar.
     def start!
       @start_t = @last_print_t = Time.now
       @last_print_n = 0
@@ -47,11 +102,17 @@ module Tqdm
       @sp.print_status(@prefix + format_meter(0, @total, 0))
     end
     
+    # Called everytime the textual progress bar might need to be updated (i.e. on
+    # every iteration). We still check whether the update is appropriate to print to
+    # the progress bar before doing so, according to the `:min_iters` and `:min_interval`
+    # options.
+    #
+    # @see #initialize
     def increment!
       @n += 1
   
       if @n - @last_print_n >= @min_iters
-        # We check the counter first, to reduce the overhead of time.time()
+        # We check the counter first, to reduce the overhead of Time.now
         cur_t = Time.now
         if cur_t - @last_print_t >= @min_interval
           @sp.print_status(@prefix + format_meter(@n, @total, cur_t - @start_t))
@@ -61,6 +122,8 @@ module Tqdm
       end
     end
     
+    # Prints the final state of the textual progress bar. Based on the `:leave` option, this
+    # may include deleting it entirely.
     def finish!
       if !@leave
         @sp.print_status('')
@@ -73,6 +136,12 @@ module Tqdm
       end
     end
     
+    # Enhances the wrapped `Enumerable`.
+    #
+    # @note The `Enumerable` is cloned (shallow copied) before it is enhanced; it is not modified directly.
+    #
+    # @return [Enumerable] a clone of Enumerable enhanced so that every call to `#each` animates the
+    #   progress bar.
     def enhance
       tqdm = self
       

data/lib/tqdm/sequel.rb

@@ -1,12 +1,25 @@
 require "sequel"
 require "tqdm"
 
+# @see Sequel::Dataset
 module Sequel
   
+  # In order to use `Tqdm` with Sequel Datasets, we can simply extend `Sequel::Dataset`
+  # with the same `#tqdm` method 
+  #
+  # @see Enumerable#tqdm
+  # @see http://sequel.jeremyevans.net/
+  # @see http://sequel.jeremyevans.net/rdoc/classes/Sequel/Dataset.html
   class Dataset
+    
+    # Returns a clone of `self` where all calls to `#each` and related methods will print an animated progress bar 
+    # while iterating.
+    #
+    # @see Enumerable#tqdm
     def tqdm(opts = {})
-      Tqdm::TqdmDecorator.new(self, {total: count}.merge!(opts)).enhance
+      Tqdm::TqdmDecorator.new(self, opts).enhance
     end
+    
   end
   
 end

data/lib/tqdm/utils.rb

@@ -2,11 +2,13 @@ require "tqdm"
 
 module Tqdm
   
-  N_BARS = 10
-  
+  # Utility functions related to `Tqdm`.
   module Utils
   
     # Formats a number of seconds into an hh:mm:ss string.
+    #
+    # @param t [Integer] a number of seconds
+    # @return [String] an hh:mm:ss string
     def format_interval(t)
       mins, s = t.to_i.divmod(60)
       h, m = mins.divmod(60)
@@ -14,11 +16,13 @@ module Tqdm
     end
   
     # Formats a count (n) of total items processed + an elapsed time into a
-    # textual progress meter.
+    # textual progress bar + meter.
+    #
+    # @param n [Integer] number of finished iterations
+    # @param total [Integer, nil] total number of iterations, or nil
+    # @param elapsed [Integer] number of seconds passed since start
+    # @return [String] a textual progress bar + meter
     def format_meter(n, total, elapsed)
-      # n - number of finished iterations
-      # total - total number of iterations, or nil
-      # elapsed - number of seconds passed since start
       total = (n > total ? nil : total) if total
   
       elapsed_str = format_interval(elapsed)

data/lib/tqdm/version.rb

@@ -1,3 +1,4 @@
 module Tqdm
-  VERSION = "0.0.1"
+  # The version of this module and gem by the same name.
+  VERSION = "0.1.0"
 end

data/tqdm.gemspec

@@ -20,4 +20,6 @@ Gem::Specification.new do |spec|
 
   spec.add_development_dependency "bundler", "~> 1.3"
   spec.add_development_dependency "rake"
+  
+  spec.required_ruby_version = '>= 1.9.2'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tqdm
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.0
 platform: ruby
 authors:
 - Theodore Pak
@@ -47,6 +47,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".gitignore"
+- ".yardopts"
 - Gemfile
 - LICENSE.txt
 - README.md
@@ -69,7 +70,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.9.2
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="