eco-helpers 1.5.0 → 1.5.5

data/lib/eco/api/organization/presets_factory.rb

@@ -42,6 +42,11 @@ module Eco
           compile(*preset_names)
         end
 
+        # @return [Array<String>] all the abilities
+        def keys
+          @abilities.keys
+        end
+
         private
 
         def init_custom(file = DEFAULT_CUSTOM)
@@ -104,21 +109,25 @@ module Eco
 
         def compile(*preset_names)
           fatal("You need to specify an existing file for the custom presets.") if !@presets_custom
-          @presets_custom.values_at(*preset_names).compact.reduce(empty_model) do |p1, p2|
+          @presets_custom.values_at(*preset_names).compact.reduce({}) do |p1, p2|
             merge(p1, p2)
           end
         end
 
         def merge(preset1, preset2)
-          @abilities.map do |key, values|
+          keys = preset1.keys | preset2.keys
+
+          @abilities.each_with_object({}) do |(key, values), result|
+            next unless keys.include?(key)
             idx = [
               values.index(preset1[key]),
               values.index(preset2[key])
             ].compact.max
-            [key, idx && values[idx]]
-          end.to_h
+            result[key] = idx && values[idx]
+          end
         end
 
+        # unsused: only play with the given abilities
         def empty_model
           JSON.parse(@abilities.to_json).transform_values {|v| nil }
         end

data/lib/eco/api/organization/presets_values.json

@@ -2,6 +2,7 @@
   "files": [null, "download", "upload", "browse", "administrate"],
   "data": [null, "view", "update", "administrate", "implement"],
   "reports": [null, "view", "edit", "administrate"],
+  "tasks": [null, "reassign_self", "reassign", "administrate"],
   "organization": [null, "view", "administrate", "implement"],
   "person_core": [null, "attach", "view_people_manager", "dashboard"],
   "person_core_create": [null, "create"],

data/lib/eco/api/policies.rb

@@ -1,12 +1,12 @@
 module Eco
   module API
+    # @todo the autoloading happens on `add`, and there could be multiple pending children to load.
+    #   This could translate into the policies not being loaded in order
     class Policies < Eco::API::UseCases
-      attr_reader :policies
+      autoloads_children_of "Eco::API::Common::Loaders::Policy"
+      autoload_namespace_ignore "Eco::API"
 
-      def add(policy)
-        raise "Expected Eco::API::Policies::Policy object. Given: #{policy}" unless policy.is_a?(Eco::API::Policies::Policy)
-        super(policy)
-      end
+      attr_reader :policies
 
       def define(name, type: :transform, &block)
         Eco::API::Policies::Policy.new(name, type: type, root: self, &block).tap do |policy|
@@ -14,12 +14,16 @@ module Eco
         end
       end
 
-      def launch(people:, session:, job:, options: {})
+      def add(policy)
+        raise "Expected Eco::API::Policies::Policy object. Given: #{policy}" unless policy.is_a?(Eco::API::Policies::Policy)
+        super(policy)
+      end
 
+      def launch(people:, session:, job:, options: {})
         args = {
           people:  people,
           session: session,
-          job: job,
+          job:     job,
           options: options
         }
 

data/lib/eco/api/session.rb

@@ -17,17 +17,13 @@ module Eco
         logger.debug("LINE COMMAND: #{$0} #{ARGV.join(" ")}")
       end
 
-      # Helper to perform multiple operations in one go.
-      # @return [Eco::API::Session::Task] provides shortcuts to manage certain kind of operations.
-      def do
-        @task   ||= Task.new(enviro)
-      end
-
       # @return [Eco::API::Session::Batch] provides helper to launch batch operations.
       def batch
         @batch  ||= Batch.new(enviro)
       end
 
+      # @!group Pure organization helpers
+
       # @see Eco::API::Session::Config#policy_groups
       def policy_groups
         config.policy_groups
@@ -47,6 +43,9 @@ module Eco
       def schemas
         config.schemas
       end
+      # @!endgroup
+
+      # @!group People and Input entries helpers
 
       # @return [String, Ecoportal::API::V1::PersonSchema] current active session's schema
       def schema
@@ -56,7 +55,7 @@ module Eco
 
       # Sets the current target `PersonSchema` of this session.
       # @note observe that it is essential for the parsers/serialisers to identify target/present attributes.
-      # @param schema [String, Ecoportal::API::V1::PersonSchema] where `String` can be the _name_ or the _id_ of the schema.
+      # @param value [String, Ecoportal::API::V1::PersonSchema] where `String` can be the _name_ or the _id_ of the schema.
       def schema=(value)
         @schema = to_schema(value)
         self
@@ -64,7 +63,7 @@ module Eco
 
       # Builds the presets using the usergroup ids of the input.
       # @note for each flag/ability it will take the highest among those mapped for the present usergroups.
-      # @param [Ecoportal::API::Internal::Person, Array<String>] the array should be of usegroup names or ids.
+      # @param input [Ecoportal::API::Internal::Person, Array<String>] the array should be of usegroup names or ids.
       # @return [Hash] with custom presets.
       def new_preset(input)
         case input
@@ -77,6 +76,15 @@ module Eco
         end
       end
 
+      # Helper to state the abilities that a person should have with given their usergroups
+      def presets_factory
+        @presets_factory ||= Eco::API::Organization::PresetsFactory.new({
+          presets_custom: file_manager.dir.file(config.people.presets_custom, should_exist: true),
+          presets_map:    file_manager.dir.file(config.people.presets_map,    should_exist: true),
+          enviro:         enviro
+        })
+      end
+
       # Helper to obtain a EntryFactory
       # @param schema [String, Ecoportal::API::V1::PersonSchema] `schema` to which associate the EntryFactory,
       #  where `String` can be the _name_ or the _id_ of the schema.
@@ -86,26 +94,24 @@ module Eco
         schema = to_schema(schema) || self.schema
         return @entry_factories[schema&.id] if @entry_factories.key?(schema&.id)
 
-        # TODO: check PersonEntry#to_internal and #to_external in init_attr_trackers
-        # => when attr_map is avoided, it doesn't work as it should
         mappings = []
         if map_file = config.people.fields_mapper
           mappings = map_file ? file_manager.load_json(map_file) : []
         end
 
-        @entry_factories[schema&.id] = Eco::API::Common::People::EntryFactory.new({
+        @entry_factories[schema&.id] = Eco::API::Common::People::EntryFactory.new(
+          enviro,
           schema:        schema,
           person_parser: config.people.parser,
-          attr_map:      Eco::Data::Mapper.new(mappings),
-          logger:        logger
-        })
+          attr_map:      Eco::Data::Mapper.new(mappings)
+        )
       end
 
       # Helper to obtain a  PersonFactory
       # @param schema [String, Ecoportal::API::V1::PersonSchema] `schema` to which associate the PersonFactory,
       #  where `String` can be the _name_ or the _id_ of the schema.
       # @return [Eco::API::Common::People::PersonFactory] associated to `schema`.
-      #  If `schema` is `nil` or not provided it uses the currently associated to the `session`
+      #   If `schema` is `nil` or not provided it uses the currently associated to the `session`
       def person_factory(schema: nil)
         schema = to_schema(schema) || self.schema
         @person_factories[schema&.id] ||= Eco::API::Common::People::PersonFactory.new(schema: schema)
@@ -115,18 +121,22 @@ module Eco
       # @note the use of these method requires to know which is the expected format of `source`
       # @param attr [String] type (`Symbol`) or attribute (`String`) to target a specific parser.
       # @param source [Any] source value to be parsed.
-      def parse_attribute(attr, source)
+      # @param phase [Symbol] the phase when this parser should be active.
+      def parse_attribute(attr, source, phase = :internal)
         unless parsers = entry_factory.person_parser
           raise "There are no parsers defined"
         end
         parsers.parse(attr, source)
       end
 
+      # @see Eco::API::Common::People::EntryFactory#export
+      # @param (see Eco::API::Common::People::EntryFactory#export)
       def export(*args)
         entry_factory.export(*args)
       end
 
       # @see Eco::API::Common::People::EntryFactory#new
+      # @param (see Eco::API::Common::People::EntryFactory#new)
       # @return [Ecoportal::API::Internal::Person]
       def new_person(**keyed_args)
         person_factory.new(**keyed_args)
@@ -140,6 +150,7 @@ module Eco
       end
 
       # @see Eco::API::Common::People::EntryFactory#entries
+      # @param (see Eco::API::Common::People::EntryFactory#entries)
       # @return [Eco::API::Common::People::Entries] collection of entries.
       def entries(*args)
         entry_factory.entries(*args).tap do |collection|
@@ -161,33 +172,52 @@ module Eco
       def discarded_entries
         return @discarded_entries if instance_variable_defined?(:@discarded_entries)
         file = config.people.discarded_file
-        file = file_manager.dir.file(file)
+        fatal("You have not specified the 'discarded_people_file'") unless file = file_manager.dir.file(file)
         @discarded_entries = csv_entries(file)
       end
+      # @!endgroup
+
+      # @!group Session workflow and batch job launces
 
+      # Opens up the `workflow` configuration
       def workflow(io:)
         config.workflow.tap do |wf|
           yield(wf, io) if block_given?
         end
       end
 
+      # Does merge `Eco::API::UseCases::DefaultCases` with the custom cases.
+      # @return [Eco::API::UseCases]
       def usecases
-        @usecases ||= Eco::API::UseCases::DefaultCases.new.merge(config.usecases)
+        @usecases ||= config.usecases.dup.tap do |cases|
+          all_cases = Eco::API::UseCases::DefaultCases.new.merge(config.usecases)
+          cases.merge(all_cases)
+        end
+      end
+
+      # Set of helpers to simplify your code
+      # @see Eco::API::MicroCases
+      # @return [Eco::API::MicroCases]
+      def micro
+        @micro    ||= Eco::API::MicroCases.new(enviro)
       end
 
       def post_launch
         @post_launch ||= config.post_launch.select(usecases)
       end
 
+      # @see Eco::API::UseCases::Case#launch
       def process_case(name, io: nil, type: nil, **params)
         args = { session: self }.merge(params)
         usecases.case(name, type: type).launch(io: io, **args)
       end
 
+      # @return [Eco::API::Session::Batch::JobsGroups]
       def job_groups
         @job_groups ||= Batch::JobsGroups.new(enviro)
       end
 
+      # @return [Eco::API::Session::Batch::Jobs]
       def job_group(name, order: :last)
         case
         when job_groups.exists?(name)
@@ -197,16 +227,28 @@ module Eco
         end
       end
 
+      # Shortcut to create a job of certain type within a group
+      # @return [Eco::API::Session::Batch::Job]
+      def new_job(group, name, type, usecase, sets = [:core, :details, :account])
+        job_group(group).new(name, usecase: usecase, type: type, sets: sets)
+      end
+
+      # @see Eco::API::Session::Batch::JobsGroups#launch
       def jobs_launch(simulate: false)
         job_groups.launch(simulate: simulate)
       end
 
+      # @see Eco::API::Session::Batch::JobsGroups#summary
       def summary
         job_groups.summary
       end
+      # @!endgroup
+
+      # @!group Additional resources
 
       # Sends an email
       # @see Eco::API::Common::Session::Mailer#mail
+      # @param (see Eco::API::Common::Session::Mailer#mail)
       def mail(**kargs)
         if mailer?
           mailer.mail(**kargs)
@@ -229,7 +271,7 @@ module Eco
       def s3upload(content: nil, file: nil, directory: nil, recurse: false, link: false)
         if s3uploader?
           if content == :target
-            path = self.do.s3upload_targets
+            path = micro.s3upload_targets
           elsif content && file
             path = s3uploader.upload(file, content)
           elsif file
@@ -246,18 +288,10 @@ module Eco
           nil
         end
       end
+      # @!endgroup
 
       private
 
-      # Helper to state the abilities that a person should have with given their usergroups
-      def presets_factory
-        @presets_factory ||= Eco::API::Organization::PresetsFactory.new({
-          presets_custom: file_manager.dir.file(config.people.presets_custom, should_exist: true),
-          presets_map:    file_manager.dir.file(config.people.presets_map,    should_exist: true),
-          enviro:         enviro
-        })
-      end
-
       # Comparer to state if 2 schemas are different
       def same_schema? (schema1, schema2)
         eq   = schema1&.id == schema2&.id
@@ -288,4 +322,3 @@ end
 
 require_relative 'session/config'
 require_relative 'session/batch'
-require_relative 'session/task'

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

@@ -24,7 +24,7 @@ module Eco
         # @option params [String] :q some text to search. Omit this parameter to target all the people.
         # @return [Array<People>] all the people based on `params`
         def get_people(people = nil, params: {}, silent: false)
-          return launch(people, method: :get, params: params, silent: silent) if people.is_a?(Enumerable)
+          return launch(people, method: :get, params: params, silent: silent).people if people.is_a?(Enumerable)
           return get(params: params, silent: silent)
         end
 
@@ -92,50 +92,7 @@ module Eco
           params = {per_page: DEFAULT_BATCH_BLOCK}.merge(params)
           client = people_api.client
 
-          looping = !params.key?(:page)
-          page    = params[:page] || 1
-
-          people = []; total_pages = nil
-          cursor_id = nil
-          loop do
-            params.merge!(cursor_id: cursor_id) unless !cursor_id
-            people_res, response = client_get(client, params: params.merge(page: page), silent: silent)
-            people += people_res
-
-            total_iterations ||= response.body["total_pages"]
-            no_pages           = !response.body["total_pages"]
-            total_results    ||= response.body["total_results"]
-
-            if !total_iterations
-              total_iterations ||= (total_results.to_f / params[:per_page]).ceil
-            end
-
-            msg = "iteration number: #{page}/#{total_iterations}, got num people #{people_res.length}, with total #{people.length} people got"
-            msg = "search(q=#{params[:q]}) " + msg if params.key?(:q)
-            logger.info(msg) unless silent
-
-            iterate = (no_pages && cursor_id = response.body["cursor_id"]) || (looping && page < total_iterations)
-            break unless iterate
-            page += 1
-          end
-
-          return people
-        end
-
-        def client_get(client, params:, silent: false)
-          response = client.get("/people", params: params)
-          unless response.success?
-            msg  = "Request failed - params: #{params}"
-            msg += "\n Error message: - Status #{response.status}: #{response.body}"
-            fatal msg
-          end
-          people = []
-          response.body["results"].each do |person_hash|
-            person = Ecoportal::API::Internal::Person.new(person_hash)
-            yield person if block_given?
-            people.push(person)
-          end
-          [people, response]
+          return people_api.get_all(params: params, silent: silent)
         end
 
         def batch_from(data, method:, params: {}, silent: false)

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

@@ -2,7 +2,7 @@ module Eco
   module API
     class Session
       class Batch
-        # Helper class to build a hiearchical model of policies
+        # Helper class to build a hierarchical model of policies
         # @example Usage:
         #     class PolicyModel < Eco::API::Session::Batch::BasePolicy
         #       MODEL = {attr1: ["prop1a", "prop1b", {"prop1c": ["prop1c1"]}]}
@@ -37,7 +37,7 @@ module Eco
             end
 
             # Attributes of this level of the model that should be included
-            # @param attr [Symbol, String] each of the subpolicies of the model that should be available
+            # @param attrs [Array<Symbol>, Array<String>] each of the subpolicies of the model that should be available
             def policy_attrs(*attrs)
               attrs = attrs.map(&:to_sym)
 
@@ -82,14 +82,14 @@ module Eco
 
           # @note if there's no `min` defined, it always returns `true`
           # @param value [Integer] value to check if it's in the minimum required
-          # @retrun [Boolen] `true` if `value` is grater or equal to `min`
+          # @return [Boolen] `true` if `value` is grater or equal to `min`
           def min?(value)
             !min || !value|| (min <= value)
           end
 
           # @note if there's no `max` defined, it always returns `true`
           # @param value [Integer] value to check if it's in the maximum allowed
-          # @retrun [Boolen] `true` if `value` is lesser or equal to `min`
+          # @return [Boolen] `true` if `value` is lesser or equal to `min`
           def max?(value)
             !max || !value || (max >= value)
           end
@@ -109,7 +109,7 @@ module Eco
             !empty?
           end
 
-          def each(params: {}, &block)
+          def each(&block)
             return to_enum(:each) unless block
             items.each(&block)
           end
@@ -212,7 +212,8 @@ module Eco
           end
 
           def model_attr(hash)
-            hash[self.attr] || hash[self.attr.to_s] if model_attr?(hash)
+            return hash[self.attr] if hash.key?(self.attr)
+            hash[self.attr.to_s]   if model_attr?(hash)
           end
 
           private

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