kitcat 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: f6c930e9f26d08132fc15fa533107ebd5d8f9c43
+  data.tar.gz: 898f7a3fa58d3b38cf85692aee414b0b9dab82d3
+SHA512:
+  metadata.gz: 16cec3058a3b816289dfc6b2cf7adc8bea0b210a07103596c4096e66b436012056cfee8d8ae55d5019a27966d1e7951510d7f764e557a5bfc952235d5a21f1db
+  data.tar.gz: d3af7d89498d41509cd026c0ee3f72c1294584d28a2f18e5e8daf19fafa1834ff8777b8ee775072bae413499dcf61b5c4336942a87aa6a3fb5bbcf7a08ac5a16

data/CONTRIBUTING.md

@@ -0,0 +1,11 @@
+# Contributing
+
+1. Submit a ticket with your issue here at Github. Make sure your ticket clearly describes the bug (with steps to reproduce it) or desired feature.
+1. Fork the repository.
+1. Create a topic branch based on master branch if you want your feature/bugfix to be released in the next versions. Alternatively, you can base your branch on
+a release branch if you want your bugfix to be part of a particular version.
+1. Make sure you split your work into reasonable commits (`git rebase` can be your friend)
+1. Write a test for your new feature/bugfix
+1. Run whole test suite to make sure you didn't break anything.
+1. Create a PR to the main repository.
+1. Link the PR to the Github Issue ticket.

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 Simply Business
+
+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,37 @@
+[![Build Status](https://travis-ci.org/simplybusiness/kitcat.svg?branch=master)](https://travis-ci.org/simplybusiness/kitcat)
+[![Coverage Status](https://coveralls.io/repos/github/simplybusiness/kitcat/badge.svg?branch=develop)](https://coveralls.io/github/simplybusiness/kitcat?branch=develop)
+[![Code Climate](https://codeclimate.com/github/simplybusiness/kitcat/badges/gpa.svg)](https://codeclimate.com/github/simplybusiness/kitcat)
+
+# KitCat
+
+*Sometimes schema migrations are just not enough.*
+
+Data migration framework written in plain Ruby. Although originally created for migrating data in MongoDb, currently it is pretty **generic**, since it **does not depend** on any web framework.
+
+## Features of Framework
+
+This is a small migration framework that offers the following functionality for free:
+
+1. Logging
+2. Progress Bar
+3. Gracefully handling when user interrupts (Ctrl+C or `kill <process_id>`)
+
+## Example Usage
+
+Assuming that the migration strategy is implemented with a class `MigrationStrategy`, then executing a migration is quite simple:
+
+``` ruby
+migration_strategy  = MigrationStrategy.new
+migration_framework = KitCat::Framework.new(migration_strategy)
+migration_framework.execute
+```
+
+The above will run the migration and will create a log file inside the `log` directory (which is created if not present)
+
+[How to implement MigrationStrategy](./docs/STRATEGY.md)
+
+# Testing
+
+```bash
+  bundle exec rake
+```

data/Rakefile

@@ -0,0 +1,9 @@
+require 'rspec/core/rake_task'
+require 'rubocop/rake_task'
+require 'bundler/audit/task'
+
+RSpec::Core::RakeTask.new :spec
+RuboCop::RakeTask.new :rubocop
+Bundler::Audit::Task.new
+
+task default: [:spec, :rubocop, 'bundle:audit']

data/lib/kitcat/framework.rb

@@ -0,0 +1,191 @@
+require 'ruby-progressbar'
+require 'active_model'
+require 'active_support/core_ext'
+
+module KitCat
+  class Framework
+    attr_reader :last_item_processed,
+                :migration_name,
+                :number_of_items_processed,
+                :migration_strategy
+
+    # @params migration_strategy {Object}
+    #           Instance implementing the methods of +KitCat::Callbacks+
+    #
+    #         migration_name {String} Optional.
+    #           The name of the migration. Used as tag in log file name. If not given, a random/unique one is used.
+    #
+    #         number_of_items_to_process {Integer} Optional.
+    #           If given, the processing will stop after processing that many number of items.
+    #
+    #         progress_bar {Boolean} Optional.
+    #           When +True+. it will instantiate a use a progress bar, incrementing that by 1 every time
+    #           the +migration_strategy+ finishes processing an item. The total load will be calculated based on the
+    #           result of +migration_strategy#criteria#count+.
+    #           When +False+, progress bar will not be used
+    #
+    #         progress_bar_output Optional. Defaults to STDOUT. Anything that responds to
+    #           #print, #flush, #tty? and #puts.
+    #           It is taken into account only if progress bar is enabled.
+    #
+    def initialize(migration_strategy,
+                   migration_name: nil,
+                   number_of_items_to_process: nil,
+                   progress_bar: true,
+                   progress_bar_output: STDOUT)
+      @migration_strategy         = migration_strategy
+      @migration_name             = build_migration_name(migration_name)
+      @number_of_items_to_process = number_of_items_to_process
+      @last_item_processed        = nil
+      @progress_bar               = initialize_progress_bar(progress_bar, progress_bar_output)
+    end
+
+    def execute
+      @interrupted = false
+      Signal.trap('TERM') { @interrupted = true }
+      Signal.trap('INT') { @interrupted = true }
+      start_logging
+
+      @number_of_items_processed = 0
+
+      items.each do |item|
+        if migration_strategy.process(item)
+
+          log_success(item)
+
+          @number_of_items_processed += 1
+
+          increment_progress_bar
+
+          @last_item_processed = item
+
+          break unless process_more?
+        else
+          log_failure(item)
+
+          break
+        end
+        if @interrupted
+          handle_user_interrupt
+          break
+        end
+      end
+      end_logging
+    end
+
+    def number_of_items_to_process
+      @number_of_items_to_process ||= migration_strategy.criteria.count
+    end
+
+    def log_file_path
+      @log_file_path ||= File.join(log_dir, build_log_file_name)
+    end
+
+    def progress_bar?
+      !@progress_bar.nil?
+    end
+
+    def progress
+      return -1 unless progress_bar?
+      @progress_bar.progress
+    end
+
+    private
+
+    def items
+      return enum_for(:items) unless block_given?
+
+      enum = migration_strategy.criteria.each
+
+      loop do
+        yield enum.next
+      end
+    end
+
+    def log_dir
+      @log_dir ||= FileUtils.mkdir_p(File.join(Dir.pwd, 'log'))
+    end
+
+    def build_log_file_name
+      "migration-#{migration_name}-#{timestamp}.log"
+    end
+
+    def timestamp
+      Time.now.to_s(:number)
+    end
+
+    def build_migration_name(migration_name)
+      result = migration_name || migration_strategy.class.name.delete(':').underscore.upcase
+      result.gsub(/\W/, '').upcase
+    end
+
+    def initialize_progress_bar(progress_bar_flag, output)
+      create_progress_bar(output) if progress_bar_flag || progress_bar_flag.nil?
+    end
+
+    def create_progress_bar(output)
+      @progress_bar = ProgressBar.create(total:  migration_strategy.criteria.count,
+                                         output: output,
+                                         progress_mark: ' ',
+                                         remainder_mark: '-',
+                                         length: terminal_width,
+                                         format: "%a %bᗧ%i %p%% %e")
+    end
+
+    def start_logging
+      logger.info 'Start Processing...'
+    end
+
+    def end_logging
+      logger.info '...end of processing'
+    end
+
+    def logger
+      @logger ||= Logger.new(log_file_path)
+    end
+
+    def log_success(item)
+      log_line(item) { |method| logger.info "...successfully processed item: #{item.try(method)}" }
+    end
+
+    def log_failure(item)
+      log_line(item) { |method| logger.error "...error while processing item: #{item.try(method)}" }
+    end
+
+    def log_line(item)
+      method = item.respond_to?(:to_log) ? :to_log : :to_s
+      yield method
+    end
+
+    def log_interrupt_callback_start
+      logger.info '...user interrupted, calling interrupt callback on migration strategy...'
+    end
+
+    def log_interrupt_callback_finish
+      logger.info '......end of interrupt callback after user interruption'
+    end
+
+    def process_more?
+      @number_of_items_to_process.nil? || @number_of_items_processed < @number_of_items_to_process
+    end
+
+    def increment_progress_bar
+      return unless progress_bar?
+      @progress_bar.increment
+    end
+
+    def handle_user_interrupt
+      log_interrupt_callback_start
+      migration_strategy.interrupt_callback if migration_strategy.respond_to?(:interrupt_callback)
+      log_interrupt_callback_finish
+      true
+    end
+
+    # The following is to correctly calculate the width of the terminal
+    # so that the progress bar occupies the whole width
+    #
+    def terminal_width
+      TerminalWidthCalculator.calculate
+    end
+  end
+end

data/lib/kitcat/terminal_width_calculator.rb

@@ -0,0 +1,39 @@
+module KitCat
+  module TerminalWidthCalculator
+    class << self
+      def calculate
+        default_width = 80
+
+        term_width = calculate_term_width
+
+        term_width > 0 ? term_width : default_width
+      end
+
+      private
+
+      def calculate_term_width
+        if ENV['COLUMNS'] =~ /^\d+$/
+          ENV['COLUMNS'].to_i
+        elsif tput_case?
+          `tput cols`.to_i
+        elsif stty_case?
+          `stty size`.scan(/\d+/).map(&:to_i)[1]
+        end
+      rescue
+        0
+      end
+
+      def tput_case?
+        (RUBY_PLATFORM =~ /java/ || !STDIN.tty? && ENV['TERM']) && shell_command_exists?('tput')
+      end
+
+      def stty_case?
+        STDIN.tty? && shell_command_exists?('stty')
+      end
+
+      def shell_command_exists?(command)
+        ENV['PATH'].split(File::PATH_SEPARATOR).any? { |d| File.exist? File.join(d, command) }
+      end
+    end
+  end
+end

data/lib/kitcat.rb

@@ -0,0 +1,2 @@
+require 'kitcat/framework'
+require 'kitcat/terminal_width_calculator'

metadata

@@ -0,0 +1,164 @@
+--- !ruby/object:Gem::Specification
+name: kitcat
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Simply Business
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2016-05-04 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ruby-progressbar
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: activemodel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: timecop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: coveralls
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: bundler-audit
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: initially created for data migrations. Provides logging, progess bar
+  and graceful handling
+email:
+- tech@simplybusiness.co.uk
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Rakefile
+- lib/kitcat/framework.rb
+- lib/kitcat/terminal_width_calculator.rb
+- lib/kitcat.rb
+- LICENSE
+- CONTRIBUTING.md
+- README.md
+homepage: https://github.com/simplybusiness/kitcat
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.0.14
+signing_key: 
+specification_version: 4
+summary: a framework to support data processing
+test_files: []