speaky_csv 0.0.3 → 0.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 7fad11aca11ab34b9b05459bbc6282ec467d060a
-  data.tar.gz: 0beefbd6193709798f83e1c083022514840d65f8
+  metadata.gz: 1d5c7405ab99d006069011e4008088bbd2ff062b
+  data.tar.gz: 4b6e533cd7619fb4a8bdb9c01bddbf28d4b59fc3
 SHA512:
-  metadata.gz: 611f717ba2b8539ec43ca525699d92baef358b5950c11d5c6035adba41b2bcd94d3297a42b7a5fb22b92cfc24993e53921d0d0d5c02658416878ca0bb9b88d74
-  data.tar.gz: 3f2dfd7c80f985470eff75bc58745a88b54a43b27f4d214410f870468abc7c908a2c11fc7da88de37ed857452b231462e8b1cf8685de4a6d9f3e28875d269255
+  metadata.gz: 4f1a2152d8b1ecb4cb05cb0f682ebba9cd65f2b8fdeb9e4e733899abfc55e4be9d87e5473aebd420a7e6276a4136d21743a93d149b7ef9376f2e8055714f033b
+  data.tar.gz: 07e0c6cc87f6f47454e8a28eb27d75e9176cf7ef7fd9e943f3428fb474c4defff85bfa88580f081c1b95ccefba171d483e80971bfc997075cb038f4e3c632ab8

data/Guardfile

@@ -1,5 +1,5 @@
 guard :rspec, cmd: 'rspec' do
   watch(%r{^spec/.+_spec\.rb$})
-  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/#{m[1]}_spec.rb" }
+  watch(%r{^lib/(.+)\.rb$})     { 'spec' }
   watch('spec/spec_helper.rb')  { 'spec' }
 end

data/README.md

@@ -2,104 +2,293 @@
 
 CSV imports and exports for ActiveRecord.
 
-## For example
+Speaky CSV features:
 
-Lets say there exists a User class:
+* An easy to use API,
+* Speedy stream processing using enumerators.
 
-    # in app/models/user.rb
-    class User < ActiveRecord::Base
-      ...
-    end
+## Installation
 
-Speaky can be used to import and export user records. The definition of
-the csv format could look like this:
+Add this line to your application's Gemfile:
 
-    # in app/csv/user_csv.rb
-    class UserCsv < SpeakyCsv::Base
-      define_csv_fields do |config|
-        config.field :id, :email, :roles
-      end
-    end
+    gem 'speaky_csv'
 
-Now lets import some user records. An import csv will always have an
-initial header row, with each following row representing a user record.
-lets import the following csv file (whitespace for clarity):
+And then execute:
 
-    # my_import.csv
-    id, email,              roles
-    22, admin@example.test, admin
-      , newbie@user.test,   user
+    $ bundle
 
-This file can be imported like this:
+Or install it yourself as:
 
-    File.open "my_import.csv", "r" do |io|
-      importer = UserCsv.new.active_record_importer io, User
-      importer.each { |user| user.save }
-    end
+    $ gem install speaky_csv
 
-## Custom CSV formats
+## Usage
 
-Speaky
+Let's say you build software for your local public library and there
+exists a Book model:
 
+```ruby
+# in app/models/book.rb
+class Book < ActiveRecord::Base
+  # ...
+end
+```
 
-Speaky allows customization of csv files to a degree, but some
-conventions need to be followed.
+Speaky can be used to import and export book records using csv files.
+The definition of the csv format could look like this:
 
-At a high level, the csv
-ends up looking similar to the way active record data gets serialized
-into form parameters which will be familiar to many rails developers.
-The advantage of this approach is that associated records be imported
-and exported.
+```ruby
+# in app/csvs/book_csv.rb
+class BookCsv < SpeakyCsv::Base
+  define_csv_fields do |config|
+    config.field :id, :author
+  end
+end
+```
 
-## Installation
+This defines a CSV format that looks like this:
 
-Add this line to your application's Gemfile:
+    id,author
+    3,Stevenson
+    19,Melville
+    1,Macaulay
 
-    gem 'speaky_csv'
+## Exporting
 
-And then execute:
+Creating a csv file from records in a database can be done with the
+exporter:
 
-    $ bundle
+```ruby
+# in app/csvs/book_csv.rb
+class BookCsv < SpeakyCsv::Base
+  define_csv_fields do |config|
+    config.field :id, :author, :_destroy
+  end
+end
 
-Or install it yourself as:
+books = [
+  Book.create!(author: 'Stevenson'),
+  Book.create!(author: 'Melville'),
+  Book.create!(author: 'Macaulay'),
+]
 
-    $ gem install speaky_csv
+exporter = BookCsv.exporter books
 
-## Usage
+io = StringIO.new
+exporter.each { |row| io.write row }
+```
+
+`io` will have the following contents:
+
+    id,author,_destroy
+    2,Stevenson,false
+    3,Melville,false
+    4,Macaulay,false
+
+##### With Associations
+
+Associations can also be exported.
+
+```ruby
+# in app/csvs/book_csv.rb
+class BookCsv < SpeakyCsv::Base
+  define_csv_fields do |config|
+    config.field :id, :author
+
+    config.belongs_to :publisher do |p|
+      p.field :id, :name
+    end
+
+    config.has_many :reviews do |r|
+      r.field :id, :tomatoes, :publication
+    end
+  end
+end
+```
+
+This defines a CSV format that looks like this:
+
+    id,author,publisher_id,publisher_name
+    3,Stevenson,22,Blam Ltd
+    19,Melville,,
+    1,Macaulay,83,NY Tiempo,reviews_0_id,8,reviews_0_tomatoes,50,review_0_publication,Daily
+
+Since a book only ever has one publisher, these can get dedicated
+columns with headers (the `publisher_id` and `publisher_name` columns).
+Reviews are more tricky because there can be several that need to be
+serialized to a single csv row. Speaky CSV uses a convention similar to
+how rails and rack deal with query parameters for things like multi
+select form inputs.
+
+## Importing
+
+Now lets import some books. Speaky will expect an import to have
+an initial header row, and each subsequent row to represent a user record.
+Columns can be in any order.
+
+Let's create a book by importing a csv.
+
+```ruby
+csv_io = StringIO.new <<-CSV
+id,author
+,Sneed
+CSV
+```
+
+Notice the empty id column. This tells Speaky that the operation is
+a create. The file can be imported like this:
+
+```ruby
+importer = BookCsv.active_record_importer csv_io, Book
+importer.each { |book| book.save }
+Book.last.author == 'Sneed' # => true
+```
+
+This importer is an `active record importer`, which means that `#each`
+will return active record instances. There is also an `attribute importer`
+that will return hashes of attribute name => values. See the rdoc for
+more info on that.
+
+##### Update
+
+Let's change the author value:
+
+```ruby
+csv_io = StringIO.new <<-CSV
+id,author
+1,Simon Sneed
+CSV
+```
+
+Now there is an id value in the csv. Having an id value will cause
+Speaky to find the record with the given id and update it.
+
+```ruby
+importer = BookCsv.active_record_importer csv_io, Book
+importer.each { |book| book.save }
+expect(Book.last.author).to eq 'Simon Sneed'
+```
+
+If a record with the given id isn't found, the importer will return a
+nil for that row instead of an active record and add a message a log
+file:
+
+```ruby
+csv_io = StringIO.new <<-CSV
+id,author
+234,I dont exist
+CSV
+
+importer = BookCsv.active_record_importer csv_io, Book
+importer.to_a # => [nil]
+importer.log  # => '...[row 1] record not found with primary key: "234"....'
+```
+
+For more info on the log file see below.
+
+##### Destroy
+
+To destroy the record, we'll need to change the csv format to add a
+`_destroy` field. If this column contains a true value like: 'true' or
+'1', the record will be marked for destruction.
+
+Marking an active record for destruction is documented here:
+http://api.rubyonrails.org/v4.2.0/classes/ActiveRecord/AutosaveAssociation.html#method-i-marked_for_destruction-3F
+
+```ruby
+# in app/csvs/book_csv.rb
+class BookCsv < SpeakyCsv::Base
+  define_csv_fields do |config|
+    config.field :id, :author, :_destroy
+  end
+end
+
+csv_io = StringIO.new <<-CSV
+id,_destroy
+1,true
+CSV
+
+importer = BookCsv.active_record_importer csv_io, Book
+book = importer.to_a.first
+if book.marked_for_destruction?
+  book.destroy
+end
+```
+
+##### With Associations
+
+Speaky uses the active record `accepts_nested_attributes_for` feature to
+deal with importing association data.
+
+For example, if a belongs\_to association is configured:
+
+```ruby
+# in app/csvs/book_csv.rb
+class BookCsv < SpeakyCsv::Base
+  define_csv_fields do |config|
+    config.field :id, :author
+
+    config.belongs_to :publisher do |p|
+      p.field :id, :name
+    end
+  end
+end
+```
+
+And the csv file being imported is this:
+
+    id,author,publisher_id,publisher_name
+    3,Stevenson,22,Blam Ltd
 
-Subclass SpeakyCsv::Base and define a csv format for an active
-record class. For example:
+Then speaky will find a Booking record with id `3` and call:
 
-    # in app/csv/user_csv.rb
-    class UserCsv < SpeakyCsv::Base
-      define_csv_fields do |config|
-        config.field :id, :first_name, :last_name, :email
+```ruby
+booking.publisher_attributes = {id: '22', name: 'Blam Ltd'}
+```
 
-        config.has_many :roles do |r|
-          r.field :role_name
-        end
-      end
+For a has\_many association, if the configuration looked like this:
+
+```ruby
+# in app/csvs/book_csv.rb
+class BookCsv < SpeakyCsv::Base
+  define_csv_fields do |config|
+    config.field :id, :author
+
+    config.has_many :reviews do |r|
+      r.field :id, :tomatoes, :publication
     end
+  end
+end
+```
+
+And an import csv looked like this:
+
+    id,author,publisher_id,publisher_name
+    1,Macaulay,83,NY Tiempo,reviews_0_id,8,reviews_0_tomatoes,50,review_0_publication,Daily
 
-See the rdoc for more details on how to configure the format.
+The speaky will find a Booking record with id `1` and call:
 
-Once the format is defined records can be exported like this:
+```ruby
+booking.reviews_attributes = [{id: '8', tomatoes: '50', publication: 'Daily'}]
+```
 
-    $ exporter = UserCsv.new.exporter(User.all)
-    $ File.open('users.csv', 'w') { |io| exporter.each { |row| io.write row } }
+## Log Messages
 
-TODO:
+Importers and exporters use a `Logger` instance to write messages during
+processing. The default logger writes to a string that can be retrieved
+by the `#log` method. A custom Logger can be set by the `#logger=`
+method.
 
-* describe importing to attribute list
-* describe importing to to active records
-* describe how to transform with an enumerator
+See `Logger` in the ruby stdlib for more details.
 
-## Recommendations
+## Best Practices
 
-* Add `id` and `_destroy` fields for active record models
+* Configure speaky with `id` and `_destroy` fields for active record models
 * For associations, use `nested_attributes_for` and add `id` and
   `_destroy` fields
-* Use optimistic locking and add `lock_version` to csv
+* Use optimistic locking and configure a `lock_version` field
+* Consider building a draft or preview feature for importing which
+  doesn't persist the record by calling `save` but instead reports what
+  the changes would be using `ActiveModel::Dirty`
 
 ## TODO
 
@@ -108,11 +297,13 @@ TODO:
 * [x] export validations
 * [x] attr import validations
 * [x] active record import validations
-* [ ] `has_one` associations
+* [x] `has_one` associations
 * [ ] required fields (make `lock_version` required for example)
 * [ ] transformations for values via accessors on class
-* [ ] public stable api for csv format definition
-* [ ] assign attrs one at a time so they don't all fail together
+* [x] public stable api for csv format definition
+* [x] assign attrs one at a time so they don't all fail together
+* [x] decide what empty cells mean
+* [ ] figure out why SpeakyCsv is a class and not a module
 
 ## Contributing
 

data/lib/speaky_csv.rb

@@ -1,6 +1,9 @@
 require 'active_support/all'
 require 'csv'
 
+require 'speaky_csv/config'
+require 'speaky_csv/config_builder'
+
 require 'speaky_csv/active_record_import'
 require 'speaky_csv/attr_import'
 require 'speaky_csv/base'

data/lib/speaky_csv/active_record_import.rb

@@ -73,7 +73,7 @@ module SpeakyCsv
                      end
 
             unless record
-              logger.error "[row #{row_index}] record not found with primary key #{attrs[@config.primary_key]}"
+              logger.error "[row #{row_index}] record not found with primary key: #{attrs[@config.primary_key.to_s].inspect}"
               yielder << nil
               next
             end
@@ -89,11 +89,13 @@ module SpeakyCsv
               end
             end
 
-            @config.has_manys.keys.each do |name|
-              if attrs.key?(name.to_s)
-                # assume nested attributes feature is used
-                attrs["#{name}_attributes"] = attrs.delete name.to_s
-              end
+            @config.has_manys.keys.map(&:to_s).select{|n| attrs.key? n}.each do |name|
+              # assume nested attributes feature is used
+              attrs["#{name}_attributes"] = attrs.delete name
+            end
+
+            @config.has_ones.keys.map(&:to_s).select{|n| attrs.key? n}.each do |name|
+              attrs["#{name}_attributes"] = attrs.delete name.to_s
             end
 
             attrs.each do |attr, value|

data/lib/speaky_csv/attr_import.rb

@@ -37,8 +37,10 @@ module SpeakyCsv
 
           csv.each do |row|
             attrs = {}
+            validate_headers row
             add_fields row, attrs
             add_has_manys row, attrs
+            add_has_ones row, attrs
             yielder << attrs
           end
 
@@ -48,19 +50,24 @@ module SpeakyCsv
       end
     end
 
-    # Adds configured fields to attrs
-    def add_fields(row, attrs)
-      row.headers.compact.each do |h|
-        unless @config.fields.include?(h.to_sym)
-          logger.warn "ignoring unknown column #{h}"
-          next
-        end
-        if @config.export_only_fields.include?(h.to_sym)
+    # TODO: don't warn on has_one headers and clean up clunky loop
+    def validate_headers(row)
+      valid_headers = @config.fields - @config.export_only_fields
+      #valid_headers += @config.has_ones.map
+
+      row.headers.compact.map(&:to_sym).each do |h|
+        unless valid_headers.include?(h)
           logger.warn "ignoring unknown column #{h}"
-          next
         end
+      end
+    end
 
-        attrs[h] = row.field h
+    # Adds configured fields to attrs
+    def add_fields(row, attrs)
+      fields = (@config.fields - @config.export_only_fields).map(&:to_s)
+      fields.each do |name|
+        row.has_key? name or next
+        attrs[name] = row.field name
       end
     end
 
@@ -90,5 +97,17 @@ module SpeakyCsv
         attrs[has_many_name][has_many_index][has_many_field] = has_many_value
       end
     end
+
+    # Adds configured has ones to attrs
+    def add_has_ones(row, attrs)
+      @config.has_ones.each do |name,assoc_config|
+        fields = (assoc_config.fields - assoc_config.export_only_fields).map(&:to_s)
+        fields.each do |f|
+          csv_name = "#{name}_#{f}"
+          row.has_key? csv_name or next
+          (attrs[name.to_s] ||= {})[f] = row.field "#{name}_#{f}"
+        end
+      end
+    end
   end
 end