eco-helpers 1.4.1 → 1.5.3

data/lib/eco/api/session/batch/errors.rb

@@ -2,7 +2,7 @@ module Eco
   module API
     class Session
       class Batch
-        # Helper object linked to a `batch status`
+        # Helper object linked to a `Batch::Status`. Its aim is to manage the errors of the batch status.
         class Errors
 
           # @attr_reader status [Eco::API::Session::Batch::Status] `batch status` this `Errors` object is associated to.
@@ -14,6 +14,8 @@ module Eco
             @status = status
           end
 
+          # @!group Status object shortcuts
+
           # @see [Eco::API::Session::Batch::Status#queue]
           def queue
             status.queue
@@ -24,6 +26,7 @@ module Eco
             status.method
           end
 
+          # @param (see Eco::API::Session::Batch::Status#to_index)
           # @see [Eco::API::Session::Batch::Status#to_index]
           def to_index(*args)
             status.to_index(*args)
@@ -37,6 +40,9 @@ module Eco
           def logger
             status.logger
           end
+          # @!endgroup
+
+          # @!group Pure errors helper methods
 
           # Was there any _Sever_ (reply) **error** as a result of this batch?
           # @return [Boolean] `true` if any of the queried _entries_ got an unsuccessful `Ecoportal::API::Common::BatchResponse`
@@ -44,6 +50,11 @@ module Eco
             queue.any? {|query| !status[query].success?}
           end
 
+          # @return [Integer] the number of `entries` that got error.
+          def count
+            entries.length
+          end
+
           # Input entries that got **error** response from the _Server_.
           # @raise [Exception] if there are elements of the final `queue` that did not get response
           # @note discards those that did not get _response_ from the Server (so those that were not queried)
@@ -67,6 +78,11 @@ module Eco
             end.compact
           end
 
+          # For all the `entries` with errors generates a `Hash` object
+          # @return [Array<Hash>] where each `Hash` has
+          #   1. `:type` -> the error type
+          #   2. `:err` -> the error `class` of that `:type`
+          #   3. `:entry` -> the entry that generated the error
           def errors
             entries.each_with_object([]) do |entry, arr|
               if body = status[entry].body
@@ -83,6 +99,9 @@ module Eco
             end
           end
 
+          # Groups `entries` with error `type`
+          # @return [Hash] where each `key` is a `type` **error** and each value is
+          #   an `Array` of `entries` that got that error
           def by_type
             errors.group_by do |h|
               h[:type]
@@ -90,11 +109,13 @@ module Eco
               arr.map {|h| h[:entry]}
             end
           end
+          # @!endgroup
 
-          def count
-            entries.length
-          end
+          # @!group Messaging methods
 
+          # Generates a `String` specifying the error for the entry `key`.
+          # @param key [Integer, Ecoportal::API::V1::Person]
+          # @return [String] the error description.
           def str(key)
             msg = ""
             unless status.success?(key)
@@ -107,6 +128,8 @@ module Eco
             msg
           end
 
+          # Sorts the entries that got server error by error `type` and generates the error messages.
+          # @return [Array<String>] the errors messages.
           def strs
             by_type.values.flatten(1).each_with_object([]) do |query, msgs|
               msgs.push(str(query))
@@ -136,6 +159,7 @@ module Eco
               logger.info("There were no errors for the current batch '#{method}'!! ;)")
             end
           end
+          # @!endgroup
 
           private
 

data/lib/eco/api/session/batch/feedback.rb

@@ -13,6 +13,8 @@ module Eco
             @job  = job
           end
 
+          # @!group Job shortcut methods
+
           # @see Eco::API::Session::Batch::Job#name
           # @return [String] name of the `batch job`
           def name
@@ -38,6 +40,9 @@ module Eco
           def job_requests
             job.requests
           end
+          # @!endgroup
+
+          # @!group Pure feedback methods
 
           # Slightly modifies the behaviour of `Ecoportal::API::Common::BaseModel#as_update`, so schema details fields show the `alt_id`
           # @note for better feedback
@@ -88,7 +93,7 @@ module Eco
           # Generates the lines of feedback of the current requests
           # @note if `requests` is not provided, it uses the last requests of the parent `Batch::Job` `job`
           # @param requests [Enumerable<Hash>] raw requests as they would be sent to the _Server_
-          # @param max_charts [Integer] the max number of characters for the current feedback message
+          # @param max_chars [Integer] the max number of characters for the current feedback message
           # @param only_stats [Boolean] whether or not should only include a brief summary of stats
           # @return [String] the feedback message
           def generate(requests = nil, max_chars: 800, only_stats: false)
@@ -117,6 +122,7 @@ module Eco
               end
             end.join("\n")
           end
+          # @!endgroup
 
           private
 

data/lib/eco/api/session/batch/job.rb

@@ -7,7 +7,7 @@ module Eco
         # @attr_reader sets [Array<Symbol>] the parts of the person model this batch is supposed to affect
         # @attr_reader usecase [Eco::API::UseCases::UseCase, nil] when provided: `usecase` that generated this `batch job`
         # @attr_reader status [Eco::API::Session::Batch::Status] if launched: the `status` of the `batch`
-        # @attr_reader feedback [Eco::API::Session::Batch::Feedback] helper class for feedback and decision making
+        # @attr_reader feedback [Eco::API::Session::Batch::Feedback] helper class for feedback and end-user decision making
         class Job < Eco::API::Common::Session::BaseSession
           @types = [:get, :create, :update, :delete]
           @sets  = [:core, :details, :account]
@@ -29,10 +29,11 @@ module Eco
           attr_reader :usecase
           attr_reader :status, :feedback
 
-          # @param e [Eco::API::Common::Session::Environment] requires a session environment, as any child of `Eco::API::Common::Session::BaseSession`
+          # @param e [Eco::API::Common::Session::Environment] requires a session environment, as any child of `Eco::API::Common::Session::BaseSession`.
           # @param name [String] the name of this `batch job`
-          # @param type [Symbol] a valid batch operation
-          # @param usecase [Eco::API::UseCases::UseCase, nil] when provided: `usecase` that generated this `batch job`
+          # @param type [Symbol] a valid batch operation.
+          # @param usecase [Eco::API::UseCases::UseCase, nil] when provided: `usecase` that generated this `batch job`.
+          #   This is necessary to know the `options` used to run the usecase, which could modify the `Batch::Job` behviour.
           def initialize(e, name:, type:, sets:, usecase: nil)
             raise "A name is required to refer a job. Given: #{name}" if !name
             raise "Type should be one of #{self.class.types}. Given: #{type}"    unless self.class.valid_type?(type)
@@ -61,10 +62,21 @@ module Eco
           #   * this job will not be linked to the `Batch::Jobs` model of the current session
           #   * mostly used for error_handlers
           # @return [Eco::API::Session::Batch::Job]
-          def dup(name = "ad-hoc:job-from:#{self.name}", usecase: nil)
+          def dup(name = "ad-hoc:job-from:#{self.name}", usecase: self.usecase)
             self.class.new(enviro, name: name, type: type, sets: sets, usecase: usecase)
           end
 
+          # @return [Eco::API::Session::Batch::Jobs] group of subjobs of this `Batch::Job`
+          def subjobs
+            @subjobs ||= Eco::API::Session::Batch::Jobs.new(enviro, name: "childs-of:#{self.name}")
+          end
+
+          def subjobs_add(name = "ad-hoc:job-from:#{self.name}", usecase: self.usecase, &block)
+            dup(name, usecase: usecase).tap do |subjob|
+              subjobs.add(subjob, &block)
+            end
+          end
+
           # @return [Boolean] `true` if the current batch job is a result of an error_handler
           def error_handler?
             usecase? && usecase.is_a?(Eco::API::Error::Handler)
@@ -81,11 +93,11 @@ module Eco
           end
 
           # Adds an entry(ies) to the job queue.
-          # @param entry [Person, Enumberable<Person>] the person(s) we want to update, carrying the changes to be done.
+          # @param entry [Ecoportal::API::V1::Person, Enumberable<Person>] the person(s) we want to update, carrying the changes to be done.
           # @param unique [Boolean] specifies if repeated entries should be avoided in the queue.
           # @yield [person] callback before launching the batch job request against the server.
-          # @yeldparam param [Person] current person object that that should be treated by the callback before launching the batch.
-          # @return [Void]
+          # @yieldparam param [Person] current person object that that should be treated by the callback before launching the batch.
+          # @return [Eco::API::Session::Batch::Job] this `Batch::Job`.
           def add(entry, unique: true, &block)
             case entry
             when Enumerable
@@ -99,13 +111,9 @@ module Eco
                 end
               end
             end
+            self
           end
 
-          #def match?(type:, sets:)
-          #  sets = [sets].flatten
-          #  type == self.type && (sets.order == self.sets.order)
-          #end
-
           # @return [Boolean] has been this `batch job` launched?
           def pending?
             @pending
@@ -140,21 +148,21 @@ module Eco
           # Processes the `queue` and, unless `simulate` is `true`, launches against the server:
           #   1. pre_processes the queue obtaining the `requests`:
           #     - if the entries of `queue` got pending _callbacks_ (delayed changes), it processes them
-          #     - unless type == `:create`: if there's a defined `api_excluded` _callback_ it calls it (see `Eco::API::Session::Config::People#api_excluded`)
+          #     - unless type == `:create`: if there's a defined `api_excluded` _callback_ it calls it (see {Eco::API::Session::Config::People#api_excluded})
           #     - transforms the result to a `Eco::API::Organization::People` object
-          #     - if there are `api policies` defined, it passes the entries through them in order (see `Eco::API::Session::Config#policies`)
+          #     - if there are `api policies` defined, it passes the entries through them in order (see {Eco::API::Session::Config#policies})
           #       - this step is **skipped** if the option `-skip-api-policies` was used in the command line
           #     - at this point all the transformations have taken place...
           #     - only include the entries that, after all above, still hold pending changes (`!as_update.empty?`) to be launched as update
           #   2. pre launch checks against the `requests`:
           #     - it generates `stats` (`Eco::API::Session::Batch::RequestStats`) out of the requests
-          #     - if there is a batch policy declared for the current job `type`, it checks compliance against `stats` (`Eco::API::Session::Batch::Policies`),
+          #     - if there is a batch policy declared for the current job `type`, it checks compliance against `stats` (see {Eco::API::Session::Batch::Policies}),
           #       - a non-compliant batch will stop the current session by raising an `Exception`
           #       - this setp is **skipped** if the option `-skip-batch-policy` was used in the command line
           #   3. if we are **not** in `dry-run` (or `simulate`), it:
           #     - backs up the raw queries (`requests`) launched to the Server, if we are **not** in `dry-run` (or `simulate`)
-          #     - **launches the batch** request against the _Server_ (see `Eco::API::Session::Batch#launch`)
-          #     - links the resulting batch `status` to this `Batch::Job` (see `Eco::API::Session::Batch::Status`)
+          #     - **launches the batch** request against the _Server_ (see {Eco::API::Session::Batch#launch})
+          #     - links the resulting batch `status` to this `Batch::Job` (see {Eco::API::Session::Batch::Status})
           #     - prints any `errors` replied by the _Server_
           #   4. the post launch kicks in, and:
           #     - for success requests, it consolidates the associated entries (see `Ecoportal::API::V1::Person#consolidate!`)
@@ -163,7 +171,6 @@ module Eco
           def launch(simulate: false)
             pqueue    = processed_queue
             @requests = pqueue.map {|e| as_update(e)}
-
             pre_checks(requests, simulate: simulate)
 
             unless simulate
@@ -177,8 +184,8 @@ module Eco
               end
             end
 
-            unless requests.empty?
-              logger.info("--- simulate mode (dry-run) --  job '#{name}' -- this would have launched #{type.to_s.upcase}") if simulate
+            unless requests.empty? || !simulate
+              logger.info("--- simulate mode (dry-run) --  job '#{name}' -- this would have launched #{type.to_s.upcase}")
             end
 
             post_launch(queue: pqueue, simulate: simulate)
@@ -186,7 +193,10 @@ module Eco
             return status
           end
 
-          # Provides a text summary of the current status
+          # Provides a text summary of the current status including:
+          #   1. stats of the changes introduced by the job in the different parts of the person model
+          #   2. if the job is compliant with the batch policy
+          #   3. error messages in case they were errors from the server
           # @note if `launch` was not invoked, it specifies so
           # @return [String] the summary
           def summary
@@ -225,6 +235,7 @@ module Eco
             full_queue.select {|entry| !excluded.call(entry, session, options, self)}
           end
 
+          # Applies the changes introduced by api policies
           def apply_policies(pre_queue)
             people(pre_queue).tap do |entries|
               policies = session.config.policies
@@ -234,12 +245,14 @@ module Eco
             end
           end
 
+          # Shortcut to get the batch (belt) policy
           def batch_policy
             unless options.dig(:skip, :batch_policy)
               @batch_policy ||= session.config.batch_policies[self.type]
             end
           end
 
+          # Checks batch policy compliance and displays the feedback on request stats
           def pre_checks(requests, simulate: false)
             only_stats = options.dig(:feedback, :only_stats)
             max_chars  = simulate ? 2500 : 800
@@ -257,6 +270,9 @@ module Eco
             end
           end
 
+          # after launched to the server
+          #   1. `consolidate!` person model if succeeded (person.doc -> person.original_doc)
+          #   2. if there were errors: launch specific error handlers if they are defined for the type of error
           def post_launch(queue: [], simulate: false)
             if !simulate && status
               status.queue.map do |entry|
@@ -271,7 +287,7 @@ module Eco
                 err_types = status.errors.by_type
                 handlers.each do |handler|
                   if entries = err_types[handler.name]
-                    handler_job = self.dup("#{self.name} => #{handler.name}", usecase: handler)
+                    handler_job = subjobs_add("#{self.name} => #{handler.name}", usecase: handler)
                     handler.launch(people: people(entries), session: session, options: options, job: handler_job)
                     handler_job.launch(simulate: simulate)
                   end
@@ -284,6 +300,7 @@ module Eco
             end
           end
 
+          # Keep a copy of the requests for future reference
           def backup_update(requests)
             dir       = config.people.requests_folder
             file      = File.join(dir, "#{type}_data.json")

data/lib/eco/api/session/batch/jobs.rb

@@ -25,7 +25,7 @@ module Eco
             count == 0
           end
 
-          def each(params: {}, &block)
+          def each(&block)
             return to_enum(:each) unless block
             items.each(&block)
           end
@@ -49,15 +49,20 @@ module Eco
             end
           end
 
-          def new(name, type:, sets:, usecase: nil)
+          def new(name, type:, sets:, usecase: nil, &block)
             fatal "Can't create job named '#{name}' because it already exists." if exists?(name)
 
             Batch::Job.new(enviro, name: name, type: type, sets: sets, usecase: usecase).tap do |job|
-              @jobs[name] = job
-              @callbacks[job] = Proc.new if block_given?
+              add(job, &block)
             end
           end
 
+          def add(job)
+            fatal "Expected Eco::API::Session::Batch::Job object. Given #{job.class}" unless job.is_a?(Eco::API::Session::Batch::Job)
+            @jobs[job.name] = job
+            @callbacks[job] = Proc.new if block_given?
+          end
+
           def pending?
             any? {|job| job.pending?}
           end

data/lib/eco/api/session/batch/jobs_groups.rb

@@ -41,7 +41,7 @@ module Eco
             count == 0
           end
 
-          def each(params: {}, &block)
+          def each(&block)
             return to_enum(:each) unless block
             items.each(&block)
           end

data/lib/eco/api/session/batch/request_stats.rb

@@ -5,9 +5,10 @@ module Eco
         # @attr_reader count [Integer] the total number of requests
         # @attr_reader stats [Hash] plain `Hash` with the number of requests that include an attribute
         class RequestStats
-          CORE_ATTRS    = Eco::API::Common::People::PersonParser::CORE_ATTRS
-          ACCOUNT_ATTRS = (Eco::API::Common::People::PersonParser::ACCOUNT_ATTRS + ["permissions_custom"]).uniq
-          DETAILS_ATTRS = ["fields"]
+          CORE_ATTRS     = Eco::API::Common::People::PersonParser::CORE_ATTRS
+          ACCOUNT_ATTRS  = (Eco::API::Common::People::PersonParser::ACCOUNT_ATTRS + ["permissions_custom"]).uniq
+          DETAILS_ATTRS  = ["fields"]
+          BLANKED_PREFIX = "blanked_"
 
           class << self
 
@@ -17,7 +18,10 @@ module Eco
 
             def core_attrs(stats: false, all: false)
               CORE_ATTRS.dup.tap do |attrs|
-                attrs.unshift("core") if stats || all
+                if stats || all
+                  attrs.unshift("core")
+                  attrs.concat(blank_attrs(CORE_ATTRS))
+                end
               end
             end
 
@@ -26,6 +30,7 @@ module Eco
                 if stats || all
                   attrs.unshift("account_remove")
                   attrs.unshift("account") if all
+                  attrs.concat(blank_attrs(ACCOUNT_ATTRS))
                 end
               end
             end
@@ -39,6 +44,20 @@ module Eco
               end
             end
 
+            def blanked_prefix(attr = nil)
+              @blanked_prefix ||= BLANKED_PREFIX
+              return @blanked_prefix unless attr
+              "#{blanked_prefix}#{attr}"
+            end
+
+            def blanked_prefix=(value)
+              @blanked_prefix = value || blanked_prefix
+            end
+
+            def blank_attrs(attrs)
+              attrs.map {|attr| "#{blanked_prefix}#{attr}"}
+            end
+
           end
 
           attr_reader :type, :count
@@ -54,17 +73,22 @@ module Eco
             @stats
           end
 
-          def core_attrs
-            @core_attrs    ||= self.class.core_attrs
-          end
+          def message(percent: false)
+            key_val_delimiter = ": "; attr_delimiter = " ++ "
+            pairs_to_line = Proc.new do |pairs|
+              pairs.map do |p|
+                [p.first.to_s, "#{p.last.to_s}" + (percent ? "%" : "")].join(key_val_delimiter)
+              end.join(attr_delimiter)
+            end
 
-          def account_attrs
-            @account_attrs ||= self.class.account_attrs
+            lines = []
+            lines << pairs_to_line.call(core_pairs(percent: percent))
+            lines << pairs_to_line.call(account_pairs(percent: percent))
+            lines << pairs_to_line.call(details_pairs(percent: percent))
+            lines.join("\n")
           end
 
-          def details_attrs
-            @details_attrs ||= self.class.details_attrs
-          end
+          private
 
           def attr(attr, percent: false, total: count)
             i = @stats["#{attr}"]
@@ -80,52 +104,10 @@ module Eco
             attr("account", percent: percent)
           end
 
-          def account_remove(percent: false)
-            attr("account_remove", percent: percent)
-          end
-
           def details(percent: false)
             attr("details", percent: percent)
           end
 
-          def details_remove(percent: false)
-            attr("details_remove", percent: percent)
-          end
-
-          def fields_average
-            if (fields_num = attr("fields")) && (total = details) > 0
-              (fields_num.to_f / total.to_f).round(2)
-            end
-          end
-
-          def message(percent: false)
-            key_val_delimiter = ": "; attr_delimiter = " ++ "
-            pairs_to_line = Proc.new do |pairs|
-              pairs.map do |p|
-                [p.first.to_s, "#{p.last.to_s}" + (percent ? "%" : "")].join(key_val_delimiter)
-              end.join(attr_delimiter)
-            end
-
-            lines = []
-            lines << pairs_to_line.call(core_pairs(percent: percent))
-            lines << pairs_to_line.call(account_pairs(percent: percent))
-            lines << pairs_to_line.call(details_pairs(percent: percent))
-            lines.join("\n")
-          end
-
-          def model
-
-          end
-
-          private
-
-          def percentage(num, total: count)
-            total ||= count
-            if num
-              (num.to_f / total * 100).round(2)
-            end
-          end
-
           def build(requests)
             Hash.new(0).tap do |stats|
               stats[type] = count
@@ -141,7 +123,12 @@ module Eco
 
           def attrs_to_stat(stats, hash, attrs)
             stats.tap do |st|
-              attrs.each {|attr| st[attr] += 1 if hash.key?(attr)}
+              attrs.each do |attr|
+                if hash.key?(attr)
+                  st[attr] += 1
+                  st[blanked_prefix(attr)]+= 1 if blanked_value?(hash[attr])
+                end
+              end
             end
           end
 
@@ -175,12 +162,13 @@ module Eco
           end
 
           def core_pairs(percent: false)
-            [["core",      core(percent: percent)]] + pairs(core_attrs, percent: percent, total: core)
+            cattrs        = core_attrs + blank_attrs(core_attrs)
+            [["core",     core(percent: percent)]] + pairs(cattrs, percent: percent, total: core)
           end
 
           def account_pairs(percent: false)
-            aattrs         = ["account_remove"] + account_attrs
-            [["account", account(percent: percent)]] + pairs(aattrs, percent: percent, total: account)
+            aattrs         = ["account_remove"] + account_attrs + blank_attrs(account_attrs)
+            [["account",   account(percent: percent)]] + pairs(aattrs, percent: percent, total: account)
           end
 
           def details_pairs(percent: false)
@@ -188,6 +176,55 @@ module Eco
             details_pairs += [["fields", fields_average]] if attr("fields") && fields_average
             details_pairs += pairs(["details_remove"], percent: percent, total: details)
           end
+
+          def fields_average
+            if (fields_num = attr("fields")) && (total = details) > 0
+              (fields_num.to_f / total.to_f).round(2)
+            end
+          end
+
+          def percentage(num, total: count)
+            total ||= count
+            if num
+              (num.to_f / total * 100).round(2)
+            end
+          end
+
+          def core_attrs
+            @core_attrs    ||= self.class.core_attrs
+          end
+
+          def account_attrs
+            @account_attrs ||= self.class.account_attrs
+          end
+
+          def details_attrs
+            @details_attrs ||= self.class.details_attrs
+          end
+
+          def blank_attrs(attrs)
+            self.class.blank_attrs(attrs)
+          end
+
+          def blanked_prefix(attr = nil)
+            self.class.blanked_prefix(attr)
+          end
+
+          def blanked_value?(value)
+            case value
+            when nil
+              true
+            when false
+              true
+            when Numeric
+              value == 0
+            when Array
+              value.compact.empty?
+            when String
+              value.to_s.strip.empty?
+            end
+          end
+
         end
       end
     end