Instruction:
Can you create a Python 3 function that
refreshes the matchers dictionary.

Response:
def matchers_refresh(self):
        '''
        Refresh the matchers
        '''
        log.debug('Refreshing matchers.')
        self.matchers = salt.loader.matchers(self.opts)


Instruction:
Write a Python 3 script for
refreshing the pillar data.

Response:
def pillar_refresh(self, force_refresh=False, notify=False):
        '''
        Refresh the pillar
        '''
        if self.connected:
            log.debug('Refreshing pillar. Notify: %s', notify)
            async_pillar = salt.pillar.get_async_pillar(
                self.opts,
                self.opts['grains'],
                self.opts['id'],
                self.opts['saltenv'],
                pillarenv=self.opts.get('pillarenv'),
            )
            try:
                self.opts['pillar'] = yield async_pillar.compile_pillar()
                if notify:
                    evt = salt.utils.event.get_event('minion', opts=self.opts, listen=False)
                    evt.fire_event({'complete': True}, tag=salt.defaults.events.MINION_PILLAR_COMPLETE)
            except SaltClientError:
                # Do not exit if a pillar refresh fails.
                log.error('Pillar data could not be refreshed. '
                          'One or more masters may be down!')
            finally:
                async_pillar.destroy()
        self.module_refresh(force_refresh, notify)
        self.matchers_refresh()
        self.beacons_refresh()


Instruction:
Create a Python 3 function for
refreshing the functions and returners.

Response:
def manage_schedule(self, tag, data):
        '''
        Refresh the functions and returners.
        '''
        func = data.get('func', None)
        name = data.get('name', None)
        schedule = data.get('schedule', None)
        where = data.get('where', None)
        persist = data.get('persist', None)

        funcs = {'delete': ('delete_job', (name, persist)),
                 'add': ('add_job', (schedule, persist)),
                 'modify': ('modify_job',
                            (name, schedule, persist)),
                 'enable': ('enable_schedule', ()),
                 'disable': ('disable_schedule', ()),
                 'enable_job': ('enable_job', (name, persist)),
                 'disable_job': ('disable_job', (name, persist)),
                 'postpone_job': ('postpone_job', (name, data)),
                 'skip_job': ('skip_job', (name, data)),
                 'reload': ('reload', (schedule,)),
                 'list': ('list', (where,)),
                 'save_schedule': ('save_schedule', ()),
                 'get_next_fire_time': ('get_next_fire_time',
                                        (name,))}

        # Call the appropriate schedule function
        try:
            alias, params = funcs.get(func)
            getattr(self.schedule, alias)(*params)
        except TypeError:
            log.error('Function "%s" is unavailable in salt.utils.scheduler',
                      func)


Instruction:
How would you implement a function in Python 3 that
manages Beacons related to a specific tag.

Response:
def manage_beacons(self, tag, data):
        '''
        Manage Beacons
        '''
        func = data.get('func', None)
        name = data.get('name', None)
        beacon_data = data.get('beacon_data', None)
        include_pillar = data.get('include_pillar', None)
        include_opts = data.get('include_opts', None)

        funcs = {'add': ('add_beacon', (name, beacon_data)),
                 'modify': ('modify_beacon', (name, beacon_data)),
                 'delete': ('delete_beacon', (name,)),
                 'enable': ('enable_beacons', ()),
                 'disable': ('disable_beacons', ()),
                 'enable_beacon': ('enable_beacon', (name,)),
                 'disable_beacon': ('disable_beacon', (name,)),
                 'list': ('list_beacons', (include_opts,
                                           include_pillar)),
                 'list_available': ('list_available_beacons', ()),
                 'validate_beacon': ('validate_beacon', (name,
                                                         beacon_data)),
                 'reset': ('reset', ())}

        # Call the appropriate beacon function
        try:
            alias, params = funcs.get(func)
            getattr(self.beacons, alias)(*params)
        except AttributeError:
            log.error('Function "%s" is unavailable in salt.beacons', func)
        except TypeError as exc:
            log.info(
                'Failed to handle %s with data(%s). Error: %s',
                tag, data, exc,
                exc_info_on_loglevel=logging.DEBUG
            )


Instruction:
Write a Python 3 function for
setting the salt - minion main process environment according to the data contained in the minion event data.

Response:
def environ_setenv(self, tag, data):
        '''
        Set the salt-minion main process environment according to
        the data contained in the minion event data
        '''
        environ = data.get('environ', None)
        if environ is None:
            return False
        false_unsets = data.get('false_unsets', False)
        clear_all = data.get('clear_all', False)
        import salt.modules.environ as mod_environ
        return mod_environ.setenv(environ, false_unsets, clear_all)


Instruction:
Explain what the following Python 3 code does
def _pre_tune(self):
        '''
        Set the minion running flag and issue the appropriate warnings if
        the minion cannot be started or is already running
        '''
        if self._running is None:
            self._running = True
        elif self._running is False:
            log.error(
                'This %s was scheduled to stop. Not running %s.tune_in()',
                self.__class__.__name__, self.__class__.__name__
            )
            return
        elif self._running is True:
            log.error(
                'This %s is already running. Not running %s.tune_in()',
                self.__class__.__name__, self.__class__.__name__
            )
            return

        try:
            log.info(
                '%s is starting as user \'%s\'',
                self.__class__.__name__, salt.utils.user.get_user()
            )
        except Exception as err:
            # Only windows is allowed to fail here. See #3189. Log as debug in
            # that case. Else, error.
            log.log(
                salt.utils.platform.is_windows() and logging.DEBUG or logging.ERROR,
                'Failed to get the user who is starting %s',
                self.__class__.__name__,
                exc_info=err
            )

Response: Check if the minion is running and if so issue the appropriate warnings.


Instruction:
Write a Python 3 function that can
send mine data to the master

Response:
def _mine_send(self, tag, data):
        '''
        Send mine data to the master
        '''
        channel = salt.transport.client.ReqChannel.factory(self.opts)
        data['tok'] = self.tok
        try:
            ret = channel.send(data)
            return ret
        except SaltReqTimeoutError:
            log.warning('Unable to send mine data to master.')
            return None
        finally:
            channel.close()


Instruction:
Given the following Python 3 function, write the documentation
def _handle_tag_module_refresh(self, tag, data):
        '''
        Handle a module_refresh event
        '''
        self.module_refresh(
            force_refresh=data.get('force_refresh', False),
            notify=data.get('notify', False)
        )

Response: Handle a module_refresh event.


Instruction:
Create a Python 3 function for
handling a pillar_refresh event.

Response:
def _handle_tag_pillar_refresh(self, tag, data):
        '''
        Handle a pillar_refresh event
        '''
        yield self.pillar_refresh(
            force_refresh=data.get('force_refresh', False),
            notify=data.get('notify', False)
        )


Instruction:
Given the following Python 3 function, write the documentation
def _handle_tag_grains_refresh(self, tag, data):
        '''
        Handle a grains_refresh event
        '''
        if (data.get('force_refresh', False) or
                self.grains_cache != self.opts['grains']):
            self.pillar_refresh(force_refresh=True)
            self.grains_cache = self.opts['grains']

Response: Handle a grains_refresh event


Instruction:
Write a Python 3 function for
handling a fire_master event.

Response:
def _handle_tag_fire_master(self, tag, data):
        '''
        Handle a fire_master event
        '''
        if self.connected:
            log.debug('Forwarding master event tag=%s', data['tag'])
            self._fire_master(data['data'], data['tag'], data['events'], data['pretag'])


Instruction:
Here you have a function in Python 3, explain what it does
def _handle_tag_master_disconnected_failback(self, tag, data):
        '''
        Handle a master_disconnected_failback event
        '''
        # if the master disconnect event is for a different master, raise an exception
        if tag.startswith(master_event(type='disconnected')) and data['master'] != self.opts['master']:
            # not mine master, ignore
            return
        if tag.startswith(master_event(type='failback')):
            # if the master failback event is not for the top master, raise an exception
            if data['master'] != self.opts['master_list'][0]:
                raise SaltException('Bad master \'{0}\' when mine failback is \'{1}\''.format(
                    data['master'], self.opts['master']))
            # if the master failback event is for the current master, raise an exception
            elif data['master'] == self.opts['master'][0]:
                raise SaltException('Already connected to \'{0}\''.format(data['master']))

        if self.connected:
            # we are not connected anymore
            self.connected = False
            log.info('Connection to master %s lost', self.opts['master'])

            # we can't use the config default here because the default '0' value is overloaded
            # to mean 'if 0 disable the job', but when salt detects a timeout it also sets up
            # these jobs
            master_alive_interval = self.opts['master_alive_interval'] or 60

            if self.opts['master_type'] != 'failover':
                # modify the scheduled job to fire on reconnect
                if self.opts['transport'] != 'tcp':
                    schedule = {
                       'function': 'status.master',
                       'seconds': master_alive_interval,
                       'jid_include': True,
                       'maxrunning': 1,
                       'return_job': False,
                       'kwargs': {'master': self.opts['master'],
                                   'connected': False}
                    }
                    self.schedule.modify_job(name=master_event(type='alive', master=self.opts['master']),
                                             schedule=schedule)
            else:
                # delete the scheduled job to don't interfere with the failover process
                if self.opts['transport'] != 'tcp':
                    self.schedule.delete_job(name=master_event(type='alive', master=self.opts['master']),
                                             persist=True)

                log.info('Trying to tune in to next master from master-list')

                if hasattr(self, 'pub_channel'):
                    self.pub_channel.on_recv(None)
                    if hasattr(self.pub_channel, 'auth'):
                        self.pub_channel.auth.invalidate()
                    if hasattr(self.pub_channel, 'close'):
                        self.pub_channel.close()
                    del self.pub_channel

                # if eval_master finds a new master for us, self.connected
                # will be True again on successful master authentication
                try:
                    master, self.pub_channel = yield self.eval_master(
                                                        opts=self.opts,
                                                        failed=True,
                                                        failback=tag.startswith(master_event(type='failback')))
                except SaltClientError:
                    pass

                if self.connected:
                    self.opts['master'] = master

                    # re-init the subsystems to work with the new master
                    log.info(
                        'Re-initialising subsystems for new master %s',
                        self.opts['master']
                    )
                    # put the current schedule into the new loaders
                    self.opts['schedule'] = self.schedule.option('schedule')
                    self.functions, self.returners, self.function_errors, self.executors = self._load_modules()
                    # make the schedule to use the new 'functions' loader
                    self.schedule.functions = self.functions
                    self.pub_channel.on_recv(self._handle_payload)
                    self._fire_master_minion_start()
                    log.info('Minion is ready to receive requests!')

                    # update scheduled job to run with the new master addr
                    if self.opts['transport'] != 'tcp':
                        schedule = {
                           'function': 'status.master',
                           'seconds': master_alive_interval,
                           'jid_include': True,
                           'maxrunning': 1,
                           'return_job': False,
                           'kwargs': {'master': self.opts['master'],
                                       'connected': True}
                        }
                        self.schedule.modify_job(name=master_event(type='alive', master=self.opts['master']),
                                                 schedule=schedule)

                        if self.opts['master_failback'] and 'master_list' in self.opts:
                            if self.opts['master'] != self.opts['master_list'][0]:
                                schedule = {
                                   'function': 'status.ping_master',
                                   'seconds': self.opts['master_failback_interval'],
                                   'jid_include': True,
                                   'maxrunning': 1,
                                   'return_job': False,
                                   'kwargs': {'master': self.opts['master_list'][0]}
                                }
                                self.schedule.modify_job(name=master_event(type='failback'),
                                                         schedule=schedule)
                            else:
                                self.schedule.delete_job(name=master_event(type='failback'), persist=True)
                else:
                    self.restart = True
                    self.io_loop.stop()

Response: Handle a master_disconnected_failback event.


Instruction:
Can you tell what is the following Python 3 function doing
def _handle_tag_master_connected(self, tag, data):
        '''
        Handle a master_connected event
        '''
        # handle this event only once. otherwise it will pollute the log
        # also if master type is failover all the reconnection work is done
        # by `disconnected` event handler and this event must never happen,
        # anyway check it to be sure
        if not self.connected and self.opts['master_type'] != 'failover':
            log.info('Connection to master %s re-established', self.opts['master'])
            self.connected = True
            # modify the __master_alive job to only fire,
            # if the connection is lost again
            if self.opts['transport'] != 'tcp':
                if self.opts['master_alive_interval'] > 0:
                    schedule = {
                       'function': 'status.master',
                       'seconds': self.opts['master_alive_interval'],
                       'jid_include': True,
                       'maxrunning': 1,
                       'return_job': False,
                       'kwargs': {'master': self.opts['master'],
                                   'connected': True}
                    }

                    self.schedule.modify_job(name=master_event(type='alive', master=self.opts['master']),
                                             schedule=schedule)
                else:
                    self.schedule.delete_job(name=master_event(type='alive', master=self.opts['master']), persist=True)

Response: Handle a master_connected event.


Instruction:
Make a summary of the following Python 3 code
def _handle_tag_schedule_return(self, tag, data):
        '''
        Handle a _schedule_return event
        '''
        # reporting current connection with master
        if data['schedule'].startswith(master_event(type='alive', master='')):
            if data['return']:
                log.debug(
                    'Connected to master %s',
                    data['schedule'].split(master_event(type='alive', master=''))[1]
                )
        self._return_pub(data, ret_cmd='_return', sync=False)

Response: Handle a _schedule_return event.


Instruction:
Implement a function in Python 3 to
handle a _salt_error event.

Response:
def _handle_tag_salt_error(self, tag, data):
        '''
        Handle a _salt_error event
        '''
        if self.connected:
            log.debug('Forwarding salt error event tag=%s', tag)
            self._fire_master(data, tag)


Instruction:
Write a Python 3 function that can
handle a salt_auth_creds event.

Response:
def _handle_tag_salt_auth_creds(self, tag, data):
        '''
        Handle a salt_auth_creds event
        '''
        key = tuple(data['key'])
        log.debug(
            'Updating auth data for %s: %s -> %s',
            key, salt.crypt.AsyncAuth.creds_map.get(key), data['creds']
        )
        salt.crypt.AsyncAuth.creds_map[tuple(data['key'])] = data['creds']


Instruction:
Can you generate the documentation for the following Python 3 function
def handle_event(self, package):
        '''
        Handle an event from the epull_sock (all local minion events)
        '''
        if not self.ready:
            raise tornado.gen.Return()
        tag, data = salt.utils.event.SaltEvent.unpack(package)
        log.debug(
            'Minion of \'%s\' is handling event tag \'%s\'',
            self.opts['master'], tag
        )
        tag_functions = {
                         'beacons_refresh': self._handle_tag_beacons_refresh,
                         'environ_setenv': self._handle_tag_environ_setenv,
                         'fire_master': self._handle_tag_fire_master,
                         'grains_refresh': self._handle_tag_grains_refresh,
                         'matchers_refresh': self._handle_tag_matchers_refresh,
                         'manage_schedule': self._handle_tag_manage_schedule,
                         'manage_beacons': self._handle_tag_manage_beacons,
                         '_minion_mine': self._handle_tag_minion_mine,
                         'module_refresh': self._handle_tag_module_refresh,
                         'pillar_refresh': self._handle_tag_pillar_refresh,
                         'salt/auth/creds': self._handle_tag_salt_auth_creds,
                         '_salt_error': self._handle_tag_salt_error,
                         '__schedule_return': self._handle_tag_schedule_return,
                         master_event(type='disconnected'): self._handle_tag_master_disconnected_failback,
                         master_event(type='failback'): self._handle_tag_master_disconnected_failback,
                         master_event(type='connected'): self._handle_tag_master_connected,
                         }

        # Run the appropriate function
        for tag_function in tag_functions:
            if tag.startswith(tag_function):
                tag_functions[tag_function](tag, data)

Response: Handle an event from the epull_sock


Instruction:
Can you generate a brief explanation for the following Python 3 code
def _setup_core(self):
        '''
        Set up the core minion attributes.
        This is safe to call multiple times.
        '''
        if not self.ready:
            # First call. Initialize.
            self.functions, self.returners, self.function_errors, self.executors = self._load_modules()
            self.serial = salt.payload.Serial(self.opts)
            self.mod_opts = self._prep_mod_opts()
#            self.matcher = Matcher(self.opts, self.functions)
            self.matchers = salt.loader.matchers(self.opts)
            self.beacons = salt.beacons.Beacon(self.opts, self.functions)
            uid = salt.utils.user.get_uid(user=self.opts.get('user', None))
            self.proc_dir = get_proc_dir(self.opts['cachedir'], uid=uid)
            self.grains_cache = self.opts['grains']
            self.ready = True

Response: Setup the core minion attributes.


Instruction:
Can you tell what is the following Python 3 function doing
def setup_beacons(self, before_connect=False):
        '''
        Set up the beacons.
        This is safe to call multiple times.
        '''
        self._setup_core()

        loop_interval = self.opts['loop_interval']
        new_periodic_callbacks = {}

        if 'beacons' not in self.periodic_callbacks:
            self.beacons = salt.beacons.Beacon(self.opts, self.functions)

            def handle_beacons():
                # Process Beacons
                beacons = None
                try:
                    beacons = self.process_beacons(self.functions)
                except Exception:
                    log.critical('The beacon errored: ', exc_info=True)
                if beacons and self.connected:
                    self._fire_master(events=beacons)

            new_periodic_callbacks['beacons'] = tornado.ioloop.PeriodicCallback(
                    handle_beacons, loop_interval * 1000)
            if before_connect:
                # Make sure there is a chance for one iteration to occur before connect
                handle_beacons()

        if 'cleanup' not in self.periodic_callbacks:
            new_periodic_callbacks['cleanup'] = tornado.ioloop.PeriodicCallback(
                    self._fallback_cleanups, loop_interval * 1000)

        # start all the other callbacks
        for periodic_cb in six.itervalues(new_periodic_callbacks):
            periodic_cb.start()

        self.periodic_callbacks.update(new_periodic_callbacks)

Response:
Set up the beacons.
        This is safe to call multiple times.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def setup_scheduler(self, before_connect=False):
        '''
        Set up the scheduler.
        This is safe to call multiple times.
        '''
        self._setup_core()

        loop_interval = self.opts['loop_interval']
        new_periodic_callbacks = {}

        if 'schedule' not in self.periodic_callbacks:
            if 'schedule' not in self.opts:
                self.opts['schedule'] = {}
            if not hasattr(self, 'schedule'):
                self.schedule = salt.utils.schedule.Schedule(
                    self.opts,
                    self.functions,
                    self.returners,
                    utils=self.utils,
                    cleanup=[master_event(type='alive')])

            try:
                if self.opts['grains_refresh_every']:  # In minutes, not seconds!
                    log.debug(
                        'Enabling the grains refresher. Will run every %d minute(s).',
                        self.opts['grains_refresh_every']
                    )
                    self._refresh_grains_watcher(abs(self.opts['grains_refresh_every']))
            except Exception as exc:
                log.error(
                    'Exception occurred in attempt to initialize grain refresh '
                    'routine during minion tune-in: %s', exc
                )

            # TODO: actually listen to the return and change period
            def handle_schedule():
                self.process_schedule(self, loop_interval)
            new_periodic_callbacks['schedule'] = tornado.ioloop.PeriodicCallback(handle_schedule, 1000)

            if before_connect:
                # Make sure there is a chance for one iteration to occur before connect
                handle_schedule()

        if 'cleanup' not in self.periodic_callbacks:
            new_periodic_callbacks['cleanup'] = tornado.ioloop.PeriodicCallback(
                    self._fallback_cleanups, loop_interval * 1000)

        # start all the other callbacks
        for periodic_cb in six.itervalues(new_periodic_callbacks):
            periodic_cb.start()

        self.periodic_callbacks.update(new_periodic_callbacks)

Response: Setup the scheduler for the current minion.


Instruction:
How would you explain what the following Python 3 function does
def tune_in(self, start=True):
        '''
        Lock onto the publisher. This is the main event loop for the minion
        :rtype : None
        '''
        self._pre_tune()

        log.debug('Minion \'%s\' trying to tune in', self.opts['id'])

        if start:
            if self.opts.get('beacons_before_connect', False):
                self.setup_beacons(before_connect=True)
            if self.opts.get('scheduler_before_connect', False):
                self.setup_scheduler(before_connect=True)
            self.sync_connect_master()
        if self.connected:
            self._fire_master_minion_start()
            log.info('Minion is ready to receive requests!')

        # Make sure to gracefully handle SIGUSR1
        enable_sigusr1_handler()

        # Make sure to gracefully handle CTRL_LOGOFF_EVENT
        if HAS_WIN_FUNCTIONS:
            salt.utils.win_functions.enable_ctrl_logoff_handler()

        # On first startup execute a state run if configured to do so
        self._state_run()

        self.setup_beacons()
        self.setup_scheduler()

        # schedule the stuff that runs every interval
        ping_interval = self.opts.get('ping_interval', 0) * 60
        if ping_interval > 0 and self.connected:
            def ping_master():
                try:
                    def ping_timeout_handler(*_):
                        if self.opts.get('auth_safemode', False):
                            log.error('** Master Ping failed. Attempting to restart minion**')
                            delay = self.opts.get('random_reauth_delay', 5)
                            log.info('delaying random_reauth_delay %ss', delay)
                            try:
                                self.functions['service.restart'](service_name())
                            except KeyError:
                                # Probably no init system (running in docker?)
                                log.warning(
                                    'ping_interval reached without response '
                                    'from the master, but service.restart '
                                    'could not be run to restart the minion '
                                    'daemon. ping_interval requires that the '
                                    'minion is running under an init system.'
                                )

                    self._fire_master('ping', 'minion_ping', sync=False, timeout_handler=ping_timeout_handler)
                except Exception:
                    log.warning('Attempt to ping master failed.', exc_on_loglevel=logging.DEBUG)
            self.periodic_callbacks['ping'] = tornado.ioloop.PeriodicCallback(ping_master, ping_interval * 1000)
            self.periodic_callbacks['ping'].start()

        # add handler to subscriber
        if hasattr(self, 'pub_channel') and self.pub_channel is not None:
            self.pub_channel.on_recv(self._handle_payload)
        elif self.opts.get('master_type') != 'disable':
            log.error('No connection to master found. Scheduled jobs will not run.')

        if start:
            try:
                self.io_loop.start()
                if self.restart:
                    self.destroy()
            except (KeyboardInterrupt, RuntimeError):  # A RuntimeError can be re-raised by Tornado on shutdown
                self.destroy()

Response: Start the minion tuning in.


Instruction:
How would you code a function in Python 3 to
tear down the minion

Response:
def destroy(self):
        '''
        Tear down the minion
        '''
        if self._running is False:
            return

        self._running = False
        if hasattr(self, 'schedule'):
            del self.schedule
        if hasattr(self, 'pub_channel') and self.pub_channel is not None:
            self.pub_channel.on_recv(None)
            if hasattr(self.pub_channel, 'close'):
                self.pub_channel.close()
            del self.pub_channel
        if hasattr(self, 'periodic_callbacks'):
            for cb in six.itervalues(self.periodic_callbacks):
                cb.stop()


Instruction:
Explain what the following Python 3 code does
def _handle_decoded_payload(self, data):
        '''
        Override this method if you wish to handle the decoded data
        differently.
        '''
        # TODO: even do this??
        data['to'] = int(data.get('to', self.opts['timeout'])) - 1
        # Only forward the command if it didn't originate from ourselves
        if data.get('master_id', 0) != self.opts.get('master_id', 1):
            self.syndic_cmd(data)

Response: Handle the decoded payload.


Instruction:
Create a Python 3 function to
forward the load and forward it on to the client cmd Take the now clear load and forward it on to the client cmd Set up default tgt_type if not set

Response:
def syndic_cmd(self, data):
        '''
        Take the now clear load and forward it on to the client cmd
        '''
        # Set up default tgt_type
        if 'tgt_type' not in data:
            data['tgt_type'] = 'glob'
        kwargs = {}

        # optionally add a few fields to the publish data
        for field in ('master_id',  # which master the job came from
                      'user',  # which user ran the job
                      ):
            if field in data:
                kwargs[field] = data[field]

        def timeout_handler(*args):
            log.warning('Unable to forward pub data: %s', args[1])
            return True

        with tornado.stack_context.ExceptionStackContext(timeout_handler):
            self.local.pub_async(data['tgt'],
                                 data['fun'],
                                 data['arg'],
                                 data['tgt_type'],
                                 data['ret'],
                                 data['jid'],
                                 data['to'],
                                 io_loop=self.io_loop,
                                 callback=lambda _: None,
                                 **kwargs)


Instruction:
Can you implement a function in Python 3 that
executes the tune_in sequence but omits extra logging and the management of the event bus assuming that these are handled outside the tune_in sequence

Response:
def tune_in_no_block(self):
        '''
        Executes the tune_in sequence but omits extra logging and the
        management of the event bus assuming that these are handled outside
        the tune_in sequence
        '''
        # Instantiate the local client
        self.local = salt.client.get_local_client(
                self.opts['_minion_conf_file'], io_loop=self.io_loop)

        # add handler to subscriber
        self.pub_channel.on_recv(self._process_cmd_socket)


Instruction:
Implement a Python 3 function for
tearing down the syndic minion

Response:
def destroy(self):
        '''
        Tear down the syndic minion
        '''
        # We borrowed the local clients poller so give it back before
        # it's destroyed. Reset the local poller reference.
        super(Syndic, self).destroy()
        if hasattr(self, 'local'):
            del self.local

        if hasattr(self, 'forward_events'):
            self.forward_events.stop()


Instruction:
How would you code a function in Python 3 to
spawn all the coroutines which will sign in the syndics

Response:
def _spawn_syndics(self):
        '''
        Spawn all the coroutines which will sign in the syndics
        '''
        self._syndics = OrderedDict()  # mapping of opts['master'] -> syndic
        masters = self.opts['master']
        if not isinstance(masters, list):
            masters = [masters]
        for master in masters:
            s_opts = copy.copy(self.opts)
            s_opts['master'] = master
            self._syndics[master] = self._connect_syndic(s_opts)


Instruction:
Can you generate a brief explanation for the following Python 3 code
def _connect_syndic(self, opts):
        '''
        Create a syndic, and asynchronously connect it to a master
        '''
        auth_wait = opts['acceptance_wait_time']
        failed = False
        while True:
            if failed:
                if auth_wait < self.max_auth_wait:
                    auth_wait += self.auth_wait
                log.debug(
                    "sleeping before reconnect attempt to %s [%d/%d]",
                    opts['master'],
                    auth_wait,
                    self.max_auth_wait,
                )
                yield tornado.gen.sleep(auth_wait)  # TODO: log?
            log.debug(
                'Syndic attempting to connect to %s',
                opts['master']
            )
            try:
                syndic = Syndic(opts,
                                timeout=self.SYNDIC_CONNECT_TIMEOUT,
                                safe=False,
                                io_loop=self.io_loop,
                                )
                yield syndic.connect_master(failed=failed)
                # set up the syndic to handle publishes (specifically not event forwarding)
                syndic.tune_in_no_block()

                # Send an event to the master that the minion is live
                syndic.fire_master_syndic_start()

                log.info(
                    'Syndic successfully connected to %s',
                    opts['master']
                )
                break
            except SaltClientError as exc:
                failed = True
                log.error(
                    'Error while bringing up syndic for multi-syndic. Is the '
                    'master at %s responding?', opts['master']
                )
            except (KeyboardInterrupt, SystemExit):
                raise
            except Exception:
                failed = True
                log.critical(
                    'Unexpected error while connecting to %s',
                    opts['master'], exc_info=True
                )

        raise tornado.gen.Return(syndic)

Response: Connect to a master and wait for it to finish.


Instruction:
Implement a function in Python 3 to
mark a master as dead. This will start the sign - in routine .

Response:
def _mark_master_dead(self, master):
        '''
        Mark a master as dead. This will start the sign-in routine
        '''
        # if its connected, mark it dead
        if self._syndics[master].done():
            syndic = self._syndics[master].result()  # pylint: disable=no-member
            self._syndics[master] = syndic.reconnect()
        else:
            # TODO: debug?
            log.info(
                'Attempting to mark %s as dead, although it is already '
                'marked dead', master
            )


Instruction:
Here you have a function in Python 3, explain what it does
def _call_syndic(self, func, args=(), kwargs=None, master_id=None):
        '''
        Wrapper to call a given func on a syndic, best effort to get the one you asked for
        '''
        if kwargs is None:
            kwargs = {}
        successful = False
        # Call for each master
        for master, syndic_future in self.iter_master_options(master_id):
            if not syndic_future.done() or syndic_future.exception():
                log.error(
                    'Unable to call %s on %s, that syndic is not connected',
                    func, master
                )
                continue

            try:
                getattr(syndic_future.result(), func)(*args, **kwargs)
                successful = True
            except SaltClientError:
                log.error(
                    'Unable to call %s on %s, trying another...',
                    func, master
                )
                self._mark_master_dead(master)
        if not successful:
            log.critical('Unable to call %s on any masters!', func)

Response: Wrapper to call a given function on a syndic


Instruction:
Here you have a function in Python 3, explain what it does
def _return_pub_syndic(self, values, master_id=None):
        '''
        Wrapper to call the '_return_pub_multi' a syndic, best effort to get the one you asked for
        '''
        func = '_return_pub_multi'
        for master, syndic_future in self.iter_master_options(master_id):
            if not syndic_future.done() or syndic_future.exception():
                log.error(
                    'Unable to call %s on %s, that syndic is not connected',
                    func, master
                )
                continue

            future, data = self.pub_futures.get(master, (None, None))
            if future is not None:
                if not future.done():
                    if master == master_id:
                        # Targeted master previous send not done yet, call again later
                        return False
                    else:
                        # Fallback master is busy, try the next one
                        continue
                elif future.exception():
                    # Previous execution on this master returned an error
                    log.error(
                        'Unable to call %s on %s, trying another...',
                        func, master
                    )
                    self._mark_master_dead(master)
                    del self.pub_futures[master]
                    # Add not sent data to the delayed list and try the next master
                    self.delayed.extend(data)
                    continue
            future = getattr(syndic_future.result(), func)(values,
                                                           '_syndic_return',
                                                           timeout=self._return_retry_timer(),
                                                           sync=False)
            self.pub_futures[master] = (future, values)
            return True
        # Loop done and didn't exit: wasn't sent, try again later
        return False

Response: Wrapper to call _return_pub_multi and return the master_id of the first available pub_id


Instruction:
Can you tell what is the following Python 3 function doing
def iter_master_options(self, master_id=None):
        '''
        Iterate (in order) over your options for master
        '''
        masters = list(self._syndics.keys())
        if self.opts['syndic_failover'] == 'random':
            shuffle(masters)
        if master_id not in self._syndics:
            master_id = masters.pop(0)
        else:
            masters.remove(master_id)

        while True:
            yield master_id, self._syndics[master_id]
            if not masters:
                break
            master_id = masters.pop(0)

Response: Iterate over the options for master_id.


Instruction:
Can you write a function in Python 3 where it
tunes in the syndic.

Response:
def tune_in(self):
        '''
        Lock onto the publisher. This is the main event loop for the syndic
        '''
        self._spawn_syndics()
        # Instantiate the local client
        self.local = salt.client.get_local_client(
            self.opts['_minion_conf_file'], io_loop=self.io_loop)
        self.local.event.subscribe('')

        log.debug('SyndicManager \'%s\' trying to tune in', self.opts['id'])

        # register the event sub to the poller
        self.job_rets = {}
        self.raw_events = []
        self._reset_event_aggregation()
        future = self.local.event.set_event_handler(self._process_event)
        self.io_loop.add_future(future, self.reconnect_event_bus)

        # forward events every syndic_event_forward_timeout
        self.forward_events = tornado.ioloop.PeriodicCallback(self._forward_events,
                                                              self.opts['syndic_event_forward_timeout'] * 1000,
                                                              )
        self.forward_events.start()

        # Make sure to gracefully handle SIGUSR1
        enable_sigusr1_handler()

        self.io_loop.start()


Instruction:
Create a Python 3 function for
functioning to finish init after connecting to a master

Response:
def _post_master_init(self, master):
        '''
        Function to finish init after connecting to a master

        This is primarily loading modules, pillars, etc. (since they need
        to know which master they connected to)

        If this function is changed, please check Minion._post_master_init
        to see if those changes need to be propagated.

        ProxyMinions need a significantly different post master setup,
        which is why the differences are not factored out into separate helper
        functions.
        '''
        mp_call = _metaproxy_call(self.opts, 'post_master_init')
        return mp_call(self, master)


Instruction:
Explain what the following Python 3 code does
def _target_load(self, load):
        '''
        Verify that the publication is valid and applies to this minion
        '''
        mp_call = _metaproxy_call(self.opts, 'target_load')
        return mp_call(self, load)

Response: Return the target load for this minion


Instruction:
Write a Python 3 script to
generate the modules for the current minion

Response:
def gen_modules(self, initial_load=False):
        '''
        Tell the minion to reload the execution modules

        CLI Example:

        .. code-block:: bash

            salt '*' sys.reload_modules
        '''
        self.opts['grains'] = salt.loader.grains(self.opts)
        self.opts['pillar'] = salt.pillar.get_pillar(
            self.opts,
            self.opts['grains'],
            self.opts['id'],
            saltenv=self.opts['saltenv'],
            pillarenv=self.opts.get('pillarenv'),
        ).compile_pillar()

        if 'proxy' not in self.opts['pillar'] and 'proxy' not in self.opts:
            errmsg = (
                'No "proxy" configuration key found in pillar or opts '
                'dictionaries for id {id}. Check your pillar/options '
                'configuration and contents. Salt-proxy aborted.'
            ).format(id=self.opts['id'])
            log.error(errmsg)
            self._running = False
            raise SaltSystemExit(code=salt.defaults.exitcodes.EX_GENERIC, msg=errmsg)

        if 'proxy' not in self.opts:
            self.opts['proxy'] = self.opts['pillar']['proxy']

        # Then load the proxy module
        self.proxy = salt.loader.proxy(self.opts)

        self.utils = salt.loader.utils(self.opts, proxy=self.proxy)

        self.functions = salt.loader.minion_mods(self.opts, utils=self.utils, notify=False, proxy=self.proxy)
        self.returners = salt.loader.returners(self.opts, self.functions, proxy=self.proxy)
        self.matchers = salt.loader.matchers(self.opts)
        self.functions['sys.reload_modules'] = self.gen_modules
        self.executors = salt.loader.executors(self.opts, self.functions, proxy=self.proxy)

        fq_proxyname = self.opts['proxy']['proxytype']

        # we can then sync any proxymodules down from the master
        # we do a sync_all here in case proxy code was installed by
        # SPM or was manually placed in /srv/salt/_modules etc.
        self.functions['saltutil.sync_all'](saltenv=self.opts['saltenv'])

        self.functions.pack['__proxy__'] = self.proxy
        self.proxy.pack['__salt__'] = self.functions
        self.proxy.pack['__ret__'] = self.returners
        self.proxy.pack['__pillar__'] = self.opts['pillar']

        # Reload utils as well (chicken and egg, __utils__ needs __proxy__ and __proxy__ needs __utils__
        self.utils = salt.loader.utils(self.opts, proxy=self.proxy)
        self.proxy.pack['__utils__'] = self.utils

        # Reload all modules so all dunder variables are injected
        self.proxy.reload_modules()

        if ('{0}.init'.format(fq_proxyname) not in self.proxy
                or '{0}.shutdown'.format(fq_proxyname) not in self.proxy):
            errmsg = 'Proxymodule {0} is missing an init() or a shutdown() or both. '.format(fq_proxyname) + \
                     'Check your proxymodule.  Salt-proxy aborted.'
            log.error(errmsg)
            self._running = False
            raise SaltSystemExit(code=salt.defaults.exitcodes.EX_GENERIC, msg=errmsg)

        self.module_executors = self.proxy.get('{0}.module_executors'.format(fq_proxyname), lambda: [])()
        proxy_init_fn = self.proxy[fq_proxyname + '.init']
        proxy_init_fn(self.opts)

        self.opts['grains'] = salt.loader.grains(self.opts, proxy=self.proxy)

        #  Sync the grains here so the proxy can communicate them to the master
        self.functions['saltutil.sync_grains'](saltenv='base')
        self.grains_cache = self.opts['grains']
        self.ready = True


Instruction:
Create a Python 3 function to
return a tuple containing the comparison operator and the version of the no .

Response:
def _get_comparison_spec(pkgver):
    '''
    Return a tuple containing the comparison operator and the version. If no
    comparison operator was passed, the comparison is assumed to be an "equals"
    comparison, and "==" will be the operator returned.
    '''
    oper, verstr = salt.utils.pkg.split_comparison(pkgver.strip())
    if oper in ('=', ''):
        oper = '=='
    return oper, verstr


Instruction:
Explain what the following Python 3 code does
def _parse_version_string(version_conditions_string):
    '''
    Returns a list of two-tuples containing (operator, version).
    '''
    result = []
    version_conditions_string = version_conditions_string.strip()
    if not version_conditions_string:
        return result
    for version_condition in version_conditions_string.split(','):
        operator_and_version = _get_comparison_spec(version_condition)
        result.append(operator_and_version)
    return result

Response: Returns a list of two - tuples containing operator and version.


Instruction:
How would you code a function in Python 3 to
return True if any of the installed versions match the specified version conditions string.

Response:
def _fulfills_version_string(installed_versions, version_conditions_string, ignore_epoch=False, allow_updates=False):
    '''
    Returns True if any of the installed versions match the specified version conditions,
    otherwise returns False.

    installed_versions
        The installed versions

    version_conditions_string
        The string containing all version conditions. E.G.
        1.2.3-4
        >=1.2.3-4
        >=1.2.3-4, <2.3.4-5
        >=1.2.3-4, <2.3.4-5, !=1.2.4-1

    ignore_epoch : False
        When a package version contains an non-zero epoch (e.g.
        ``1:3.14.159-2.el7``, and a specific version of a package is desired,
        set this option to ``True`` to ignore the epoch when comparing
        versions.

    allow_updates : False
        Allow the package to be updated outside Salt's control (e.g. auto updates on Windows).
        This means a package on the Minion can have a newer version than the latest available in
        the repository without enforcing a re-installation of the package.
        (Only applicable if only one strict version condition is specified E.G. version: 2.0.6~ubuntu3)
    '''
    version_conditions = _parse_version_string(version_conditions_string)
    for installed_version in installed_versions:
        fullfills_all = True
        for operator, version_string in version_conditions:
            if allow_updates and len(version_conditions) == 1 and operator == '==':
                operator = '>='
            fullfills_all = fullfills_all and _fulfills_version_spec([installed_version], operator, version_string, ignore_epoch=ignore_epoch)
        if fullfills_all:
            return True
    return False


Instruction:
Given the following Python 3 function, write the documentation
def _fulfills_version_spec(versions, oper, desired_version,
                           ignore_epoch=False):
    '''
    Returns True if any of the installed versions match the specified version,
    otherwise returns False
    '''
    cmp_func = __salt__.get('pkg.version_cmp')
    # stripping "with_origin" dict wrapper
    if salt.utils.platform.is_freebsd():
        if isinstance(versions, dict) and 'version' in versions:
            versions = versions['version']
    for ver in versions:
        if (oper == '==' and fnmatch.fnmatch(ver, desired_version)) \
                or salt.utils.versions.compare(ver1=ver,
                                               oper=oper,
                                               ver2=desired_version,
                                               cmp_func=cmp_func,
                                               ignore_epoch=ignore_epoch):
            return True
    return False

Response: Returns True if any of the installed versions match the specified version otherwise returns False


Instruction:
Can you tell what is the following Python 3 function doing
def _find_unpurge_targets(desired, **kwargs):
    '''
    Find packages which are marked to be purged but can't yet be removed
    because they are dependencies for other installed packages. These are the
    packages which will need to be 'unpurged' because they are part of
    pkg.installed states. This really just applies to Debian-based Linuxes.
    '''
    return [
        x for x in desired
        if x in __salt__['pkg.list_pkgs'](purge_desired=True, **kwargs)
    ]

Response: Find packages which can t be purged but can t yet be removed.


Instruction:
Can you generate the documentation for the following Python 3 function
def _find_download_targets(name=None,
                           version=None,
                           pkgs=None,
                           normalize=True,
                           skip_suggestions=False,
                           ignore_epoch=False,
                           **kwargs):
    '''
    Inspect the arguments to pkg.downloaded and discover what packages need to
    be downloaded. Return a dict of packages to download.
    '''
    cur_pkgs = __salt__['pkg.list_downloaded'](**kwargs)
    if pkgs:
        to_download = _repack_pkgs(pkgs, normalize=normalize)

        if not to_download:
            # Badly-formatted SLS
            return {'name': name,
                    'changes': {},
                    'result': False,
                    'comment': 'Invalidly formatted pkgs parameter. See '
                               'minion log.'}
    else:
        if normalize:
            _normalize_name = \
                __salt__.get('pkg.normalize_name', lambda pkgname: pkgname)
            to_download = {_normalize_name(name): version}
        else:
            to_download = {name: version}

        cver = cur_pkgs.get(name, {})
        if name in to_download:
            # Package already downloaded, no need to download again
            if cver and version in cver:
                return {'name': name,
                        'changes': {},
                        'result': True,
                        'comment': 'Version {0} of package \'{1}\' is already '
                                   'downloaded'.format(version, name)}

            # if cver is not an empty string, the package is already downloaded
            elif cver and version is None:
                # The package is downloaded
                return {'name': name,
                        'changes': {},
                        'result': True,
                        'comment': 'Package {0} is already '
                                   'downloaded'.format(name)}

    version_spec = False
    if not skip_suggestions:
        try:
            problems = _preflight_check(to_download, **kwargs)
        except CommandExecutionError:
            pass
        else:
            comments = []
            if problems.get('no_suggest'):
                comments.append(
                    'The following package(s) were not found, and no '
                    'possible matches were found in the package db: '
                    '{0}'.format(
                ', '.join(sorted(problems['no_suggest']))
                    )
                )
            if problems.get('suggest'):
                for pkgname, suggestions in \
                        six.iteritems(problems['suggest']):
                    comments.append(
                        'Package \'{0}\' not found (possible matches: '
                        '{1})'.format(pkgname, ', '.join(suggestions))
                    )
            if comments:
                if len(comments) > 1:
                    comments.append('')
                return {'name': name,
                        'changes': {},
                        'result': False,
                        'comment': '. '.join(comments).rstrip()}

    # Find out which packages will be targeted in the call to pkg.download
    # Check current downloaded versions against specified versions
    targets = {}
    problems = []
    for pkgname, pkgver in six.iteritems(to_download):
        cver = cur_pkgs.get(pkgname, {})
        # Package not yet downloaded, so add to targets
        if not cver:
            targets[pkgname] = pkgver
            continue
        # No version specified but package is already downloaded
        elif cver and not pkgver:
            continue

        version_spec = True
        try:
            if not _fulfills_version_string(cver.keys(), pkgver, ignore_epoch=ignore_epoch):
                targets[pkgname] = pkgver
        except CommandExecutionError as exc:
            problems.append(exc.strerror)
            continue

    if problems:
        return {'name': name,
                'changes': {},
                'result': False,
                'comment': ' '.join(problems)}

    if not targets:
        # All specified packages are already downloaded
        msg = (
            'All specified packages{0} are already downloaded'
            .format(' (matching specified versions)' if version_spec else '')
        )
        return {'name': name,
                'changes': {},
                'result': True,
                'comment': msg}

    return targets

Response: Return a dict of packages to download.


Instruction:
Explain what the following Python 3 code does
def _find_advisory_targets(name=None,
                           advisory_ids=None,
                           **kwargs):
    '''
    Inspect the arguments to pkg.patch_installed and discover what advisory
    patches need to be installed. Return a dict of advisory patches to install.
    '''
    cur_patches = __salt__['pkg.list_installed_patches'](**kwargs)
    if advisory_ids:
        to_download = advisory_ids
    else:
        to_download = [name]
        if cur_patches.get(name, {}):
            # Advisory patch already installed, no need to install it again
            return {'name': name,
                    'changes': {},
                    'result': True,
                    'comment': 'Advisory patch {0} is already '
                               'installed'.format(name)}

    # Find out which advisory patches will be targeted in the call to pkg.install
    targets = []
    for patch_name in to_download:
        cver = cur_patches.get(patch_name, {})
        # Advisory patch not yet installed, so add to targets
        if not cver:
            targets.append(patch_name)
            continue

    if not targets:
        # All specified packages are already downloaded
        msg = ('All specified advisory patches are already installed')
        return {'name': name,
                'changes': {},
                'result': True,
                'comment': msg}

    return targets

Response: Find the advisory patches that need to be installed.


Instruction:
How would you explain what the following Python 3 function does
def _find_remove_targets(name=None,
                         version=None,
                         pkgs=None,
                         normalize=True,
                         ignore_epoch=False,
                         **kwargs):
    '''
    Inspect the arguments to pkg.removed and discover what packages need to
    be removed. Return a dict of packages to remove.
    '''
    if __grains__['os'] == 'FreeBSD':
        kwargs['with_origin'] = True
    cur_pkgs = __salt__['pkg.list_pkgs'](versions_as_list=True, **kwargs)
    if pkgs:
        to_remove = _repack_pkgs(pkgs, normalize=normalize)

        if not to_remove:
            # Badly-formatted SLS
            return {'name': name,
                    'changes': {},
                    'result': False,
                    'comment': 'Invalidly formatted pkgs parameter. See '
                               'minion log.'}
    else:
        _normalize_name = \
            __salt__.get('pkg.normalize_name', lambda pkgname: pkgname)
        to_remove = {_normalize_name(name): version}

    version_spec = False
    # Find out which packages will be targeted in the call to pkg.remove
    # Check current versions against specified versions
    targets = []
    problems = []
    for pkgname, pkgver in six.iteritems(to_remove):
        # FreeBSD pkg supports `openjdk` and `java/openjdk7` package names
        origin = bool(re.search('/', pkgname))

        if __grains__['os'] == 'FreeBSD' and origin:
            cver = [k for k, v in six.iteritems(cur_pkgs) if v['origin'] == pkgname]
        else:
            cver = cur_pkgs.get(pkgname, [])

        # Package not installed, no need to remove
        if not cver:
            continue
        # No version specified and pkg is installed
        elif __salt__['pkg_resource.version_clean'](pkgver) is None:
            targets.append(pkgname)
            continue
        version_spec = True
        try:
            if _fulfills_version_string(cver, pkgver, ignore_epoch=ignore_epoch):
                targets.append(pkgname)
            else:
                log.debug(
                    'Current version (%s) did not match desired version '
                    'specification (%s), will not remove', cver, pkgver
                )
        except CommandExecutionError as exc:
            problems.append(exc.strerror)
            continue

    if problems:
        return {'name': name,
                'changes': {},
                'result': False,
                'comment': ' '.join(problems)}

    if not targets:
        # All specified packages are already absent
        msg = 'All specified packages{0} are already absent'.format(
            ' (matching specified versions)' if version_spec else ''
        )
        return {'name': name,
                'changes': {},
                'result': True,
                'comment': msg}

    return targets

Response: Find packages that need to be removed from the current version of the current version.


Instruction:
Here you have a function in Python 3, explain what it does
def _find_install_targets(name=None,
                          version=None,
                          pkgs=None,
                          sources=None,
                          skip_suggestions=False,
                          pkg_verify=False,
                          normalize=True,
                          ignore_epoch=False,
                          reinstall=False,
                          refresh=False,
                          **kwargs):
    '''
    Inspect the arguments to pkg.installed and discover what packages need to
    be installed. Return a dict of desired packages
    '''
    was_refreshed = False

    if all((pkgs, sources)):
        return {'name': name,
                'changes': {},
                'result': False,
                'comment': 'Only one of "pkgs" and "sources" is permitted.'}

    # dict for packages that fail pkg.verify and their altered files
    altered_files = {}
    # Get the ignore_types list if any from the pkg_verify argument
    if isinstance(pkg_verify, list) \
            and any(x.get('ignore_types') is not None
                    for x in pkg_verify
                    if isinstance(x, _OrderedDict)
                    and 'ignore_types' in x):
        ignore_types = next(x.get('ignore_types')
                            for x in pkg_verify
                            if 'ignore_types' in x)
    else:
        ignore_types = []

    # Get the verify_options list if any from the pkg_verify argument
    if isinstance(pkg_verify, list) \
            and any(x.get('verify_options') is not None
                    for x in pkg_verify
                    if isinstance(x, _OrderedDict)
                    and 'verify_options' in x):
        verify_options = next(x.get('verify_options')
                            for x in pkg_verify
                            if 'verify_options' in x)
    else:
        verify_options = []

    if __grains__['os'] == 'FreeBSD':
        kwargs['with_origin'] = True

    if salt.utils.platform.is_windows():
        # Windows requires a refresh to establish a pkg db if refresh=True, so
        # add it to the kwargs.
        kwargs['refresh'] = refresh

    resolve_capabilities = kwargs.get('resolve_capabilities', False) and 'pkg.list_provides' in __salt__
    try:
        cur_pkgs = __salt__['pkg.list_pkgs'](versions_as_list=True, **kwargs)
        cur_prov = resolve_capabilities and __salt__['pkg.list_provides'](**kwargs) or dict()
    except CommandExecutionError as exc:
        return {'name': name,
                'changes': {},
                'result': False,
                'comment': exc.strerror}

    if salt.utils.platform.is_windows() and kwargs.pop('refresh', False):
        # We already refreshed when we called pkg.list_pkgs
        was_refreshed = True
        refresh = False

    if any((pkgs, sources)):
        if pkgs:
            desired = _repack_pkgs(pkgs, normalize=normalize)
        elif sources:
            desired = __salt__['pkg_resource.pack_sources'](
                sources,
                normalize=normalize,
            )

        if not desired:
            # Badly-formatted SLS
            return {'name': name,
                    'changes': {},
                    'result': False,
                    'comment': 'Invalidly formatted \'{0}\' parameter. See '
                               'minion log.'.format('pkgs' if pkgs
                                                    else 'sources')}

        to_unpurge = _find_unpurge_targets(desired, **kwargs)
    else:
        if salt.utils.platform.is_windows():
            pkginfo = _get_package_info(name, saltenv=kwargs['saltenv'])
            if not pkginfo:
                return {'name': name,
                        'changes': {},
                        'result': False,
                        'comment': 'Package {0} not found in the '
                                   'repository.'.format(name)}
            if version is None:
                version = _get_latest_pkg_version(pkginfo)

        if normalize:
            _normalize_name = \
                __salt__.get('pkg.normalize_name', lambda pkgname: pkgname)
            desired = {_normalize_name(name): version}
        else:
            desired = {name: version}

        to_unpurge = _find_unpurge_targets(desired, **kwargs)

        # FreeBSD pkg supports `openjdk` and `java/openjdk7` package names
        origin = bool(re.search('/', name))

        if __grains__['os'] == 'FreeBSD' and origin:
            cver = [k for k, v in six.iteritems(cur_pkgs)
                    if v['origin'] == name]
        else:
            cver = cur_pkgs.get(name, [])

        if name not in to_unpurge:
            if version and version in cver \
                    and not reinstall \
                    and not pkg_verify:
                # The package is installed and is the correct version
                return {'name': name,
                        'changes': {},
                        'result': True,
                        'comment': 'Version {0} of package \'{1}\' is already '
                                   'installed'.format(version, name)}

            # if cver is not an empty string, the package is already installed
            elif cver and version is None \
                    and not reinstall \
                    and not pkg_verify:
                # The package is installed
                return {'name': name,
                        'changes': {},
                        'result': True,
                        'comment': 'Package {0} is already '
                                   'installed'.format(name)}

    version_spec = False
    if not sources:
        # Check for alternate package names if strict processing is not
        # enforced. Takes extra time. Disable for improved performance
        if not skip_suggestions:
            # Perform platform-specific pre-flight checks
            not_installed = dict([
                (name, version)
                for name, version in desired.items()
                if not (name in cur_pkgs and (version is None or _fulfills_version_string(cur_pkgs[name], version)))
            ])
            if not_installed:
                try:
                    problems = _preflight_check(not_installed, **kwargs)
                except CommandExecutionError:
                    pass
                else:
                    comments = []
                    if problems.get('no_suggest'):
                        comments.append(
                            'The following package(s) were not found, and no '
                            'possible matches were found in the package db: '
                            '{0}'.format(
                                ', '.join(sorted(problems['no_suggest']))
                            )
                        )
                    if problems.get('suggest'):
                        for pkgname, suggestions in \
                                six.iteritems(problems['suggest']):
                            comments.append(
                                'Package \'{0}\' not found (possible matches: '
                                '{1})'.format(pkgname, ', '.join(suggestions))
                            )
                    if comments:
                        if len(comments) > 1:
                            comments.append('')
                        return {'name': name,
                                'changes': {},
                                'result': False,
                                'comment': '. '.join(comments).rstrip()}

    # Resolve the latest package version for any packages with "latest" in the
    # package version
    wants_latest = [] \
        if sources \
        else [x for x, y in six.iteritems(desired) if y == 'latest']
    if wants_latest:
        resolved_latest = __salt__['pkg.latest_version'](*wants_latest,
                                                         refresh=refresh,
                                                         **kwargs)
        if len(wants_latest) == 1:
            resolved_latest = {wants_latest[0]: resolved_latest}
        if refresh:
            was_refreshed = True
            refresh = False

        # pkg.latest_version returns an empty string when the package is
        # up-to-date. So check the currently-installed packages. If found, the
        # resolved latest version will be the currently installed one from
        # cur_pkgs. If not found, then the package doesn't exist and the
        # resolved latest version will be None.
        for key in resolved_latest:
            if not resolved_latest[key]:
                if key in cur_pkgs:
                    resolved_latest[key] = cur_pkgs[key][-1]
                else:
                    resolved_latest[key] = None
        # Update the desired versions with the ones we resolved
        desired.update(resolved_latest)

    # Find out which packages will be targeted in the call to pkg.install
    targets = {}
    to_reinstall = {}
    problems = []
    warnings = []
    failed_verify = False
    for package_name, version_string in six.iteritems(desired):
        cver = cur_pkgs.get(package_name, [])
        if resolve_capabilities and not cver and package_name in cur_prov:
            cver = cur_pkgs.get(cur_prov.get(package_name)[0], [])

        # Package not yet installed, so add to targets
        if not cver:
            targets[package_name] = version_string
            continue
        if sources:
            if reinstall:
                to_reinstall[package_name] = version_string
                continue
            elif 'lowpkg.bin_pkg_info' not in __salt__:
                continue
            # Metadata parser is available, cache the file and derive the
            # package's name and version
            err = 'Unable to cache {0}: {1}'
            try:
                cached_path = __salt__['cp.cache_file'](version_string, saltenv=kwargs['saltenv'])
            except CommandExecutionError as exc:
                problems.append(err.format(version_string, exc))
                continue
            if not cached_path:
                problems.append(err.format(version_string, 'file not found'))
                continue
            elif not os.path.exists(cached_path):
                problems.append('{0} does not exist on minion'.format(version_string))
                continue
            source_info = __salt__['lowpkg.bin_pkg_info'](cached_path)
            if source_info is None:
                warnings.append('Failed to parse metadata for {0}'.format(version_string))
                continue
            else:
                verstr = source_info['version']
        else:
            verstr = version_string
            if reinstall:
                to_reinstall[package_name] = version_string
                continue
            if not __salt__['pkg_resource.check_extra_requirements'](package_name, version_string):
                targets[package_name] = version_string
                continue
            # No version specified and pkg is installed
            elif __salt__['pkg_resource.version_clean'](version_string) is None:
                if (not reinstall) and pkg_verify:
                    try:
                        verify_result = __salt__['pkg.verify'](
                            package_name,
                            ignore_types=ignore_types,
                            verify_options=verify_options,
                            **kwargs
                        )
                    except (CommandExecutionError, SaltInvocationError) as exc:
                        failed_verify = exc.strerror
                        continue
                    if verify_result:
                        to_reinstall[package_name] = version_string
                        altered_files[package_name] = verify_result
                continue
        version_fulfilled = False
        allow_updates = bool(not sources and kwargs.get('allow_updates'))
        try:
            version_fulfilled = _fulfills_version_string(cver, verstr, ignore_epoch=ignore_epoch, allow_updates=allow_updates)
        except CommandExecutionError as exc:
            problems.append(exc.strerror)
            continue

        # Compare desired version against installed version.
        version_spec = True
        if not version_fulfilled:
            if reinstall:
                to_reinstall[package_name] = version_string
            else:
                version_conditions = _parse_version_string(version_string)
                if pkg_verify and any(oper == '==' for oper, version in version_conditions):
                    try:
                        verify_result = __salt__['pkg.verify'](
                            package_name,
                            ignore_types=ignore_types,
                            verify_options=verify_options,
                            **kwargs
                        )
                    except (CommandExecutionError, SaltInvocationError) as exc:
                        failed_verify = exc.strerror
                        continue
                    if verify_result:
                        to_reinstall[package_name] = version_string
                        altered_files[package_name] = verify_result
                else:
                    log.debug(
                        'Current version (%s) did not match desired version '
                        'specification (%s), adding to installation targets',
                        cver, version_string
                    )
                    targets[package_name] = version_string

    if failed_verify:
        problems.append(failed_verify)

    if problems:
        return {'name': name,
                'changes': {},
                'result': False,
                'comment': ' '.join(problems)}

    if not any((targets, to_unpurge, to_reinstall)):
        # All specified packages are installed
        msg = 'All specified packages are already installed{0}'
        msg = msg.format(
            ' and are at the desired version' if version_spec and not sources
            else ''
        )
        ret = {'name': name,
               'changes': {},
               'result': True,
               'comment': msg}
        if warnings:
            ret.setdefault('warnings', []).extend(warnings)
        return ret

    return (desired, targets, to_unpurge, to_reinstall, altered_files,
            warnings, was_refreshed)

Response: Find the packages that need to be installed and install them.


Instruction:
Can you tell what is the following Python 3 function doing
def _verify_install(desired, new_pkgs, ignore_epoch=False, new_caps=None):
    '''
    Determine whether or not the installed packages match what was requested in
    the SLS file.
    '''
    ok = []
    failed = []
    if not new_caps:
        new_caps = dict()
    for pkgname, pkgver in desired.items():
        # FreeBSD pkg supports `openjdk` and `java/openjdk7` package names.
        # Homebrew for Mac OSX does something similar with tap names
        # prefixing package names, separated with a slash.
        has_origin = '/' in pkgname

        if __grains__['os'] == 'FreeBSD' and has_origin:
            cver = [k for k, v in six.iteritems(new_pkgs) if v['origin'] == pkgname]
        elif __grains__['os'] == 'MacOS' and has_origin:
            cver = new_pkgs.get(pkgname, new_pkgs.get(pkgname.split('/')[-1]))
        elif __grains__['os'] == 'OpenBSD':
            cver = new_pkgs.get(pkgname.split('%')[0])
        elif __grains__['os_family'] == 'Debian':
            cver = new_pkgs.get(pkgname.split('=')[0])
        else:
            cver = new_pkgs.get(pkgname)
            if not cver and pkgname in new_caps:
                cver = new_pkgs.get(new_caps.get(pkgname)[0])

        if not cver:
            failed.append(pkgname)
            continue
        elif pkgver == 'latest':
            ok.append(pkgname)
            continue
        elif not __salt__['pkg_resource.version_clean'](pkgver):
            ok.append(pkgname)
            continue
        elif pkgver.endswith("*") and cver[0].startswith(pkgver[:-1]):
            ok.append(pkgname)
            continue
        if _fulfills_version_string(cver, pkgver, ignore_epoch=ignore_epoch):
            ok.append(pkgname)
        else:
            failed.append(pkgname)
    return ok, failed

Response: Verify that the installed packages match what was requested in the SLS file.


Instruction:
Make a summary of the following Python 3 code
def _get_desired_pkg(name, desired):
    '''
    Helper function that retrieves and nicely formats the desired pkg (and
    version if specified) so that helpful information can be printed in the
    comment for the state.
    '''
    if not desired[name] or desired[name].startswith(('<', '>', '=')):
        oper = ''
    else:
        oper = '='
    return '{0}{1}{2}'.format(name, oper,
                              '' if not desired[name] else desired[name])

Response: Helper function that retrieves and nicely formats the desired pkg


Instruction:
Write a Python 3 script for
performing platform - specific checks on desired packages

Response:
def _preflight_check(desired, fromrepo, **kwargs):
    '''
    Perform platform-specific checks on desired packages
    '''
    if 'pkg.check_db' not in __salt__:
        return {}
    ret = {'suggest': {}, 'no_suggest': []}
    pkginfo = __salt__['pkg.check_db'](
        *list(desired.keys()), fromrepo=fromrepo, **kwargs
    )
    for pkgname in pkginfo:
        if pkginfo[pkgname]['found'] is False:
            if pkginfo[pkgname]['suggestions']:
                ret['suggest'][pkgname] = pkginfo[pkgname]['suggestions']
            else:
                ret['no_suggest'].append(pkgname)
    return ret


Instruction:
Can you generate a brief explanation for the following Python 3 code
def _nested_output(obj):
    '''
    Serialize obj and format for output
    '''
    nested.__opts__ = __opts__
    ret = nested.output(obj).rstrip()
    return ret

Response: Serialize obj and format for output


Instruction:
How would you explain what the following Python 3 function does
def _resolve_capabilities(pkgs, refresh=False, **kwargs):
    '''
    Resolve capabilities in ``pkgs`` and exchange them with real package
    names, when the result is distinct.
    This feature can be turned on while setting the paramter
    ``resolve_capabilities`` to True.

    Return the input dictionary with replaced capability names and as
    second return value a bool which say if a refresh need to be run.

    In case of ``resolve_capabilities`` is False (disabled) or not
    supported by the implementation the input is returned unchanged.
    '''
    if not pkgs or 'pkg.resolve_capabilities' not in __salt__:
        return pkgs, refresh

    ret = __salt__['pkg.resolve_capabilities'](pkgs, refresh=refresh, **kwargs)
    return ret, False

Response:
Resolve capabilities in pkgs and exchange them with real package
    names.