eco-helpers 0.6.17 → 0.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4adc2bd05f27cb6889d9ea3f6320c1951c9a839aa3fc74f638bd947367f1a650
-  data.tar.gz: c4139a3e9d310133a4e93811734db707ef3c7fa1fa2ae486a5aac032b2f87260
+  metadata.gz: a2c5373e513f2c43cd593684e28011ce9b0646a4457e19c31a5590f5cac0d743
+  data.tar.gz: d1985d695d0a8c390593a76f6cc65dbf8ebcbb584f6b1e6fd0032706be6c4299
 SHA512:
-  metadata.gz: 490118493a087bcdfbb9db88b3a1560dfe82aa3c0816e6391d59da1185a0da16aa3db0089b7c0416518f68b7874793fa318113d1ca1e68d250e0dedff15f194e
-  data.tar.gz: 620aed9f3d3bed82ecf514de399998ea963cc83a1ecdf63ad45f44d954840483f8189934d979038883a24e880e8eff91e7a8622531bcbaeee22d1b28e05798bf
+  metadata.gz: 4101d84e2d20cdc95459277316177570af81d1fd9ef38aadba6f41d7df424a093d12619efaf4a811cc2374cb812235f86a3602ebf18b26ef8d33cfe469d5c89b
+  data.tar.gz: 25b6df7e98d964fb7b53685fa98f31eb0983138b8a3754404d5dd5704669adf69fee0bbe91162eca35234b0fcf5b6af09b3d053c995e9470371b2d880758d2f9

data/.gitignore

@@ -1 +1,20 @@
+# it's a gem, ignore the lockfile
+Gemfile.lock
+
+# build artifacts
 *.gem
+/.bundle/
+/vendor/bundle
+/spec/reports/
+/tmp/
+/pkg/
+
+# docs
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+
+# rspec failure tracking
+.rspec_status
+scratch.rb

data/.yardopts

@@ -1,7 +1,7 @@
 --readme README.md
 --charset utf-8
---markup-provider redcarpet
---markup markdown
+--markup-provider=redcarpet
+--markup=markdown
 --no-private
 --output-dir ./doc
 'lib/**/*.rb'

data/Gemfile

@@ -0,0 +1,6 @@
+source "https://rubygems.org"
+
+git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
+
+# Specify your gem's dependencies in eco-helpers.gemspec
+gemspec

data/Rakefile

@@ -0,0 +1,27 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "yard"
+require "redcarpet"
+
+desc "run the specs"
+RSpec::Core::RakeTask.new(:spec)
+
+desc "run rspec showing backtrace"
+RSpec::Core::RakeTask.new(:spec_trace) do |task|
+  task.rspec_opts = ['--backtrace']
+end
+
+desc "run rspec stopping on first fail, and show backtrace"
+RSpec::Core::RakeTask.new(:spec_fast) do |task|
+  task.rspec_opts = ['--fail-fast', '--backtrace']
+end
+
+# default task name is yard
+desc "Yard: generate all the documentation"
+YARD::Rake::YardocTask.new(:doc) do |t|
+  #t.files = ['lib/**/*.rb']
+end
+
+task :default     => [:spec]
+task :rspec_trace => :spec_trace
+task :rspec_fast  => :spec_fast

data/eco-helpers.gemspec

@@ -22,15 +22,18 @@ Gem::Specification.new do |s|
   #s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
   s.require_paths = ["lib"]
 
+  s.add_development_dependency "bundler",   "~> 1.16"
   s.add_development_dependency "rspec",     "~> 3",   ">= 3.8"
+  s.add_development_dependency "rake",      "~> 10.0"
   s.add_development_dependency "yard",      "~> 0.9", ">= 0.9.18"
   s.add_development_dependency "redcarpet", "~> 3.4", ">= 3.4.0"
 
-  s.add_dependency 'ecoportal-api', '~> 0.4', '>= 0.4.2'
-  s.add_dependency 'faker',         '~> 1',   '>= 1.9'
-  s.add_dependency 'distribution',  '~> 0.7', '>= 0.7.3'
-  s.add_dependency 'thor',          '~> 0',   '>= 0.20'
-  s.add_dependency 'aws-sdk-s3',    '~> 1.30',  '>= 1.30.1'
-  s.add_dependency 'aws-sdk-ses',   '~> 1.14',  '>= 1.14.0'
+  s.add_dependency 'ecoportal-api', '~> 0.4',  '>= 0.4.2'
+  s.add_dependency 'thor',          '~> 0',    '>= 0.20'
+  s.add_dependency 'nokogiri',      '~> 1.6',  '>= 1.6.8'
+  s.add_dependency 'aws-sdk-s3',    '~> 1.30', '>= 1.30.1'
+  s.add_dependency 'aws-sdk-ses',   '~> 1.14', '>= 1.14.0'
   s.add_dependency 'dotenv',        '~> 2.6',  '>= 2.6.0'
+  s.add_dependency 'faker',         '~> 1',    '>= 1.9'
+  s.add_dependency 'distribution',  '~> 0.7',  '>= 0.7.3'
 end

data/lib/eco/api.rb

@@ -6,7 +6,8 @@ module Eco
 end
 
 require_relative 'api/common'
-require_relative 'api/organization'
 require_relative 'api/usecases'
+require_relative 'api/policies'
+require_relative 'api/organization'
 require_relative 'api/session'
 require_relative 'api/eco_faker'

data/lib/eco/api/common/people.rb

@@ -7,12 +7,12 @@ module Eco
   end
 end
 
-require_relative 'people/types'
 require_relative 'people/person_modifier'
 require_relative 'people/person_factory'
 require_relative 'people/base_parser'
 require_relative 'people/person_parser'
 require_relative 'people/default_parsers'
+require_relative 'people/person_entry_attribute_mapper'
 require_relative 'people/person_entry'
 require_relative 'people/entries'
 require_relative 'people/entry_factory'

data/lib/eco/api/common/people/base_parser.rb

@@ -2,13 +2,43 @@ module Eco
   module API
     module Common
       module People
+
+        # @example Example of usage:
+        #  class ExampleParser < Eco::API::Common::People::BaseParser
+        #    def process
+        #      @parsers.define_attribute("example") do |parser|
+        #        parser.def_parser  do |str, deps|
+        #          i = value.to_i rescue 0
+        #          i +=5 if deps.dig(:sum_5)
+        #          i
+        #        end.def_serializer do |value|
+        #          value.to_s
+        #        end
+        #      end
+        #    end
+        #  end
+        #  pparser = Eco::API::Common::People::PersonParser.new
+        #  ExampleParser.new(pparser)
+        #  pparser.parse("example","3") # out: 3
+        #  pparser.parse("example","3", deps: {sum_5: true}) # out: 8
+        #  pparser.serialise("example, 8) # out: "8"
+        #
+        # Helper class to inherit from to ease the definition of attribute parsers in a `PersonParser` object,
+        # mostly used in for configuration loading.
         class BaseParser
+
+          # @param parsers [Eco::API::Common::People::PersonParser] set of attribute parsers/serialisers.
+          # @param options [Hash] keyword arguments to be used in the `process` method of the child class.
           def initialize(parsers, **options)
             @parsers = parsers
             @options = options
           end
 
-          def process; end
+          # Method to be overriden by the child class.
+          # @note this method is called to load the definition of the attribute parser/serializer.
+          def process
+            raise "Method needs to be overriden in the child class #{self.class}"
+          end
         end
       end
     end

data/lib/eco/api/common/people/default_parsers.rb

@@ -22,9 +22,12 @@ module Eco
 
             SelectParser.new(self, select_hashes: select_hashes).process
             BooleanParser.new(self).process
-            NumericParser.new(self, schema: @schema).process
+            NumericParser.new(self).process
             DateParser.new(self).process
             MultiParser.new(self).process
+
+            # FORMAT PARSER
+            CSVParser.new(self).process
           end
 
         end
@@ -38,3 +41,4 @@ require_relative 'default_parsers/boolean_parser'
 require_relative 'default_parsers/numeric_parser'
 require_relative 'default_parsers/date_parser'
 require_relative 'default_parsers/multi_parser'
+require_relative 'default_parsers/csv_parser'

data/lib/eco/api/common/people/default_parsers/csv_parser.rb

@@ -0,0 +1,37 @@
+module Eco
+  module API
+    module Common
+      module People
+        class DefaultParsers
+          class CSVParser < People::BaseParser
+
+            def process
+              @parsers.define_attribute(:csv, dependencies: @options) do |parser|
+                parser.def_parser  do |data, deps|
+                  arr_hash = []
+                  CSV.parse(data, headers: true).each do |row|
+                    row_hash = row.headers.uniq.each_with_object({}) do |attr, hash|
+                      hash[attr] = row[attr]
+                    end
+                    arr_hash.push(row_hash)
+                  end
+                  arr_hash
+                end.def_serializer do |array_hash, deps|
+                  arr_rows = []
+                  unless array_hash.empty?
+                    header = array_hash.first.keys
+                    arr_rows = array_hash.map do |csv_row|
+                      CSV::Row.new(header, csv_row.values_at(*header))
+                    end
+                  end
+                  CSV::Table.new(arr_rows).to_csv
+                end
+              end
+            end
+
+          end
+        end
+      end
+    end
+  end
+end

data/lib/eco/api/common/people/default_parsers/numeric_parser.rb

@@ -8,7 +8,6 @@ module Eco
             def process
               @parsers.define_attribute(:number, dependencies: @options) do |parser|
                 parser.def_parser  do |value, deps|
-                  #deps[:schema]&.fields[deps["attr"]].parse_text(value)
                   value = value.to_s.strip == "" ? nil : (value.to_f rescue nil)
                 end.def_serializer do |value|
                   value.is_a?(Array) ? value.map { |v| v.to_s } : value.to_s

data/lib/eco/api/common/people/entries.rb

@@ -2,26 +2,22 @@ module Eco
   module API
     module Common
       module People
+        # Class meant to offer a _collection_ of entries, normally used to get parsed input data.
+        # @attr_reader entries [Array<Eco::API::Common::PersonEntry] a pure `Array` object.
         class Entries <  Eco::Language::Models::Collection
-
           # build the shortcuts of Collection
           attr_collection :id, :external_id, :email, :name, :supervisor_id
 
           alias_method :entries, :to_a
 
-          include Common::People
-
           def initialize(data = [], klass:, factory:)
             super(data, klass: klass, factory: factory)
             @caches_init = false
           end
 
           def [](id_or_ext)
-            self.id(id_or_ext) || self.external_id(id_or_ext)
+            id(id_or_ext) || external_id(id_or_ext)
           end
-          #def []=(id, value)
-          #  if self.id?(id)
-          #end
 
           def id(*args)
             attr('id', *args).first
@@ -34,16 +30,16 @@ module Eco
           def entry(id: nil, external_id: nil, email: nil)
             init_caches
             pers = @by_id[id]&.first if id
-            pers = @by_external_id[external_id&.strip]&.first if !pers && !external_id.to_s.strip.empty?
-            pers = @by_email[email&.downcase.strip]&.first if !pers && !email.to_s.strip.empty?
+            pers = @by_external_id[external_id&.strip]&.first    if !pers && !external_id.to_s.strip.empty?
+            pers = @by_email[email&.downcase.strip]&.first       if !pers && !email.to_s.strip.empty?
             pers = @by_external_id[email&.downcase.strip]&.first if !pers && !email.to_s.strip.empty?
             pers
           end
 
           def find(object)
-            id = object.respond_to?("id")? object.send("id") : nil
+            id          = object.respond_to?("id")?          object.send("id") : nil
             external_id = object.respond_to?("external_id")? object.send("external_id") : nil
-            email = object.respond_to?("email")? object.send("email") : nil
+            email       = object.respond_to?("email")?       object.send("email") : nil
             entry(id: id, external_id: external_id, email: email)
           end
 
@@ -55,18 +51,18 @@ module Eco
             discarded = list.map do |person|
               find(person)
             end.compact
-            newFrom self.to_a - discarded
+            newFrom to_a - discarded
           end
 
           def email_id_maps
-            self.email_present.group_by(:email).transform_values { |person| person.id }
+            email_present.group_by(:email).transform_values { |person| person.id }
           end
 
           def group_by_supervisor
-            self.to_h(:supervisor_id)
+            to_h(:supervisor_id)
           end
 
-          def to_h(attr)
+          def to_h(attr = "id")
             super(attr || "id")
           end
 
@@ -80,9 +76,9 @@ module Eco
 
           def init_caches
             return if @caches_init
-            @by_id = self.to_h('id')
-            @by_external_id = self.to_h('external_id')
-            @by_email = self.to_h('email')
+            @by_id          = to_h
+            @by_external_id = to_h('external_id')
+            @by_email       = to_h('email')
             @caches_init = true
           end
 

data/lib/eco/api/common/people/entry_factory.rb

@@ -2,31 +2,119 @@ module Eco
   module API
     module Common
       module People
+        # @attr_reader person_parser [Eco::API::Common::People::PersonParser] set of attribute, type and format parsers/serializers.
         class EntryFactory
 
           attr_reader :person_parser
 
-          def initialize(schema:, person_parser: nil, fields_mapper: nil, logger: ::Logger.new(IO::NULL))
-            raise "Constructor needs a PersonSchema. Given: #{schema}" if !schema.is_a?(Ecoportal::API::V1::PersonSchema)
-            raise "Expecting PersonParser. Given: #{person_parser}" if person_parser && !person_parser.is_a?(Eco::API::Common::People::PersonParser)
-            raise "Expecting Mapper object. Given: #{fields_mapper}" if fields_mapper && !fields_mapper.is_a?(Eco::Data::Mapper)
+          # @param schema [Ecoportal::API::V1::PersonSchema] schema of person details that the parser will be based upon.
+          # @param person_parser [nil, Eco::API::Common::People::PersonParser] set of attribute, type and format parsers/serializers.
+          # @param attr_map [nil, Eco::Data::Mapper] attribute names mapper to translate external names into internal ones and _vice versa_.
+          # @param logger [Common::Session::Logger, ::Logger] object to manage logs.
+          def initialize(schema:, person_parser: nil, attr_map: nil, logger: ::Logger.new(IO::NULL))
+            fatal "Constructor needs a PersonSchema. Given: #{schema}" if !schema.is_a?(Ecoportal::API::V1::PersonSchema)
+            fatal "Expecting PersonParser. Given: #{person_parser}"    if person_parser && !person_parser.is_a?(Eco::API::Common::People::PersonParser)
+            fatal "Expecting Mapper object. Given: #{fields_mapper}"   if attr_map && !attr_map.is_a?(Eco::Data::Mapper)
 
             @logger = logger
             @schema = Ecoportal::API::V1::PersonSchema.new(JSON.parse(schema.doc.to_json))
 
             default_parser = Eco::API::Common::People::DefaultParsers.new(schema: @schema)
-            @parser = default_parser.merge(person_parser)
+            @person_parser = default_parser.merge(person_parser)
 
-            @fields_mapper = fields_mapper
+            @attr_map = attr_map
           end
 
+          # key method to generate objects of `PersonEntry` that share dependencies via this `EntryFactory` environment.
+          # @note this method is necessary to make the factory object work as a if it was a class `PersonEntry` you can call `new` on.
+          # @param data [Array<Hash>] data to be parsed. The external hashed entry.
+          # @return [Eco::API::Common::People::PersonEntry]
           def new(data, dependencies: {})
-            PersonEntry.new(data, parser: @parser, mapper: @fields_mapper, dependencies: dependencies, logger: @logger)
+            PersonEntry.new(
+              data,
+              person_parser: @person_parser,
+              attr_map:      @attr_map,
+              dependencies:  dependencies,
+              logger:        @logger
+            )
           end
 
-          def entries(data)
-            Entries.new(data, klass: PersonEntry, factory: self)
+          # Helper that provides a collection of `Entries`, which in turn provides with further helpers to find and exclude entries.
+          # It accepts a `file:` and `format:` or `data:` but not both options together.
+          # @raise Exception
+          #   - if you try to provide `data:` and `file:` at the same time.
+          #   - if you provide `file:` but omit `format:`.
+          #   - if the `format:` you provide is not a `Symbol`.
+          #   - if there is no _parser/serializer_ defined for `format:`.
+          # @param data [Array<Hash>] data to be parsed. It cannot be used alongside with `file:`
+          # @param file [String] absolute or relative path to the input file. It cannot be used alongside with `data:`.
+          # @param format [Symbol] it must be used when you use the option `file:` (i.e. `:xml`, `:csv`), as it specifies the format of the input `file:`.
+          # @param encoding [String] optional parameter to read `file:` by expecting certain encoding.
+          # @return [Eco::API::Common::People::Entries] collection of `Eco::API::Common::People::PersonEntry`.
+          def entries(data: (no_data = true; nil), file: (no_file = true; nil), format: (no_format = true; nil), encoding: nil)
+            fatal("You should at least use data: or file:, but not both") if no_data == no_file
+            fatal("You must specify a valid format: (symbol) when you use file.") if file && no_format
+            fatal("Format should be a Symbol. Given '#{format}'") if format && !format.is_a?(Symbol)
+            fatal("There is no parser/serializer for format ':#{format.to_s}'") unless no_format || @person_parser.defined?(format)
+
+            if file
+              arr_hash = []
+              if Eco::API::Common::Session::FileManager.file_exists?(file)
+                encoding   ||= Eco::API::Common::Session::FileManager.encoding(file)
+                file_content = File.read(file, encoding: encoding)
+                arr_hash     = @person_parser.parse(format, file_content)
+              end
+              entries(data: arr_hash)
+            else
+              Entries.new(data, klass: PersonEntry, factory: self)
+            end
+          end
+
+          # Helper that generates a file out of `data:`.
+          # @raise Exception
+          #   - if you try to provide `data:` in the wrong format.
+          #   - if you `file:` is empty.
+          #   - if the `format:` you provide is not a `Symbol`.
+          #   - if there is no _parser/serializer_ defined for `format:`.
+          # @param data [Eco::API::Organization::People] data to be parsed.
+          # @param file [String] absolute or relative path to the ouput file.
+          # @param format [Symbol] it specifies the format of the output `file:` (i.e. `:xml`, `:csv`). There must be a parser/serializer defined for it.
+          # @param encoding [String] optional parameter to geneate `file:` content by unsing certain encoding.
+          # @return [Void].
+          def export(data:, file: "export", format: :csv, encoding: "utf-8")
+            fatal("data: Expected Eco::API::Organization::People object. Given: #{data.class}") unless data.is_a?(Eco::API::Organization::People)
+            fatal("A file should be specified.") unless !file.to_s.strip.empty?
+            fatal("Format should be a Symbol. Given '#{format}'") if format && !format.is_a?(Symbol)
+            fatal("There is no parser/serializer for format ':#{format.to_s}'") unless @person_parser.defined?(format)
+
+            run = true
+            if Eco::API::Common::Session::FileManager.file_exists?(file)
+              print "The file '#{file}' already exists. Do you want to overwrite it? (Y/n): "
+              res = STDIN.gets.strip
+              run = ["y", "Y", ""].include?(res)
+            end
+
+            if run
+              deps = {"supervisor_id" => {people: data}}
+
+              data_entries = data.map do |person|
+                self.new(person, dependencies: deps).to_hash
+              end
+
+              File.open(file, "w", enconding: encoding) do |fd|
+                fd.write(@person_parser.serialize(format, data_entries))
+              end
+            end
+
+          end
+
+          private
+
+          def fatal(msg)
+            @logger.fatal(msg)
+            raise msg
           end
+
         end
 
       end