Instruction:
Can you implement a function in Python 3 that
executes a command and read the output as YAML and return the result as a dictionary.

Response:
def ext_pillar(minion_id,
               pillar,  # pylint: disable=W0613
               use_grain=False,
               minion_ids=None,
               tag_match_key=None,
               tag_match_value='asis',
               tag_list_key=None,
               tag_list_sep=';'):
    '''
    Execute a command and read the output as YAML
    '''
    valid_tag_match_value = ['uqdn', 'asis']

    # meta-data:instance-id
    grain_instance_id = __grains__.get('meta-data', {}).get('instance-id', None)
    if not grain_instance_id:
        # dynamic:instance-identity:document:instanceId
        grain_instance_id = \
            __grains__.get('dynamic', {}).get('instance-identity', {}).get('document', {}).get('instance-id', None)
    if grain_instance_id and re.search(r'^i-([0-9a-z]{17}|[0-9a-z]{8})$', grain_instance_id) is None:
        log.error('External pillar %s, instance-id \'%s\' is not valid for '
                  '\'%s\'', __name__, grain_instance_id, minion_id)
        grain_instance_id = None  # invalid instance id found, remove it from use.

    # Check AWS Tag restrictions .i.e. letters, spaces, and numbers and + - = . _ : / @
    if tag_match_key and re.match(r'[\w=.:/@-]+$', tag_match_key) is None:
        log.error('External pillar %s, tag_match_key \'%s\' is not valid ',
                  __name__, tag_match_key if isinstance(tag_match_key, six.text_type) else 'non-string')
        return {}

    if tag_match_key and tag_match_value not in valid_tag_match_value:
        log.error('External pillar %s, tag_value \'%s\' is not valid must be one '
                  'of %s', __name__, tag_match_value, ' '.join(valid_tag_match_value))
        return {}

    if not tag_match_key:
        base_msg = ('External pillar %s, querying EC2 tags for minion id \'%s\' '
                    'against instance-id', __name__, minion_id)
    else:
        base_msg = ('External pillar %s, querying EC2 tags for minion id \'%s\' '
                    'against instance-id or \'%s\' against \'%s\'', __name__, minion_id, tag_match_key, tag_match_value)

    log.debug(base_msg)
    find_filter = None
    find_id = None

    if re.search(r'^i-([0-9a-z]{17}|[0-9a-z]{8})$', minion_id) is not None:
        find_filter = None
        find_id = minion_id
    elif tag_match_key:
        if tag_match_value == 'uqdn':
            find_filter = {'tag:{0}'.format(tag_match_key): minion_id.split('.', 1)[0]}
        else:
            find_filter = {'tag:{0}'.format(tag_match_key): minion_id}
        if grain_instance_id:
            # we have an untrusted grain_instance_id, use it to narrow the search
            # even more. Combination will be unique even if uqdn is set.
            find_filter.update({'instance-id': grain_instance_id})
        # Add this if running state is not dependant on EC2Config
        # find_filter.update('instance-state-name': 'running')

    # no minion-id is instance-id and no suitable filter, try use_grain if enabled
    if not find_filter and not find_id and use_grain:
        if not grain_instance_id:
            log.debug('Minion-id is not in AWS instance-id formation, and there '
                      'is no instance-id grain for minion %s', minion_id)
            return {}
        if minion_ids is not None and minion_id not in minion_ids:
            log.debug('Minion-id is not in AWS instance ID format, and minion_ids '
                      'is set in the ec2_pillar configuration, but minion %s is '
                      'not in the list of allowed minions %s', minion_id, minion_ids)
            return {}
        find_id = grain_instance_id

    if not (find_filter or find_id):
        log.debug('External pillar %s, querying EC2 tags for minion id \'%s\' against '
                  'instance-id or \'%s\' against \'%s\' noughthing to match against',
                  __name__, minion_id, tag_match_key, tag_match_value)
        return {}

    myself = boto.utils.get_instance_metadata(timeout=0.1, num_retries=1)
    if not myself:
        log.info("%s: salt master not an EC2 instance, skipping", __name__)
        return {}

    # Get the Master's instance info, primarily the region
    (_, region) = _get_instance_info()

    # If the Minion's region is available, use it instead
    if use_grain:
        region = __grains__.get('ec2', {}).get('region', region)

    try:
        conn = boto.ec2.connect_to_region(region)
    except boto.exception.AWSConnectionError as exc:
        log.error('%s: invalid AWS credentials, %s', __name__, exc)
        return {}

    if conn is None:
        log.error('%s: Could not connect to region %s', __name__, region)
        return {}

    try:
        if find_id:
            instance_data = conn.get_only_instances(instance_ids=[find_id], dry_run=False)
        else:
            # filters and max_results can not be used togther.
            instance_data = conn.get_only_instances(filters=find_filter, dry_run=False)

    except boto.exception.EC2ResponseError as exc:
        log.error('%s failed with \'%s\'', base_msg, exc)
        return {}

    if not instance_data:
        log.debug('%s no match using \'%s\'', base_msg, find_id if find_id else find_filter)
        return {}

    # Find a active instance, i.e. ignore terminated and stopped instances
    active_inst = []
    for inst in range(0, len(instance_data)):
        if instance_data[inst].state not in ['terminated', 'stopped']:
            active_inst.append(inst)

    valid_inst = len(active_inst)
    if not valid_inst:
        log.debug('%s match found but not active \'%s\'', base_msg, find_id if find_id else find_filter)
        return {}

    if valid_inst > 1:
        log.error('%s multiple matches, ignored, using \'%s\'', base_msg, find_id if find_id else find_filter)
        return {}

    instance = instance_data[active_inst[0]]
    if instance.tags:
        ec2_tags = instance.tags
        ec2_tags_list = {}
        log.debug('External pillar %s, for minion id \'%s\', tags: %s', __name__, minion_id, instance.tags)
        if tag_list_key and isinstance(tag_list_key, list):
            for item in tag_list_key:
                if item in ec2_tags:
                    ec2_tags_list[item] = ec2_tags[item].split(tag_list_sep)
                    del ec2_tags[item]  # make sure its only in ec2_tags_list
                else:
                    ec2_tags_list[item] = []  # always return a result

        return {'ec2_tags': ec2_tags, 'ec2_tags_list': ec2_tags_list}
    return {}


Instruction:
Can you generate the documentation for the following Python 3 function
def ext_pillar(minion_id, pillar, conf):
    '''
    Return an existing set of certificates
    '''
    cache = salt.cache.Cache(__opts__, syspaths.CACHE_DIR)

    ret = {}
    dns_names = cache.fetch('venafi/minions', minion_id)
    for dns_name in dns_names:
        data = cache.fetch('venafi/domains', dns_name)
        ret[dns_name] = data
        del ret[dns_name]['csr']
    return {'venafi': ret}

Response: Return an existing set of certificates


Instruction:
Write a Python 3 function for
returning the status of a service via s6

Response:
def status(name, sig=None):
    '''
    Return the status for a service via s6, return pid if running

    CLI Example:

    .. code-block:: bash

        salt '*' s6.status <service name>
    '''
    cmd = 's6-svstat {0}'.format(_service_path(name))
    out = __salt__['cmd.run_stdout'](cmd)
    try:
        pid = re.search(r'up \(pid (\d+)\)', out).group(1)
    except AttributeError:
        pid = ''
    return pid


Instruction:
Can you write a function in Python 3 where it
returns a list of all available services

Response:
def get_all():
    '''
    Return a list of all available services

    CLI Example:

    .. code-block:: bash

        salt '*' s6.get_all
    '''
    if not SERVICE_DIR:
        raise CommandExecutionError("Could not find service directory.")
    service_list = [dirname for dirname
                            in os.listdir(SERVICE_DIR)
                            if not dirname.startswith('.')]
    return sorted(service_list)


Instruction:
Can you tell what is the following Python 3 function doing
def add_host(mac, name=None, ip=None, ddns=False, group=None,
        supersede_host=False):
    '''
    Add a host object for the given mac.

    CLI Example:

    .. code-block:: bash

        salt dhcp-server omapi.add_host ab:ab:ab:ab:ab:ab name=host1

    Add ddns-hostname and a fixed-ip statements:

    .. code-block:: bash

        salt dhcp-server omapi.add_host ab:ab:ab:ab:ab:ab name=host1 ip=10.1.1.1 ddns=true
    '''
    statements = ''
    o = _conn()
    msg = omapi.OmapiMessage.open(b'host')
    msg.message.append((b'create', struct.pack(b'!I', 1)))
    msg.message.append((b'exclusive', struct.pack(b'!I', 1)))
    msg.obj.append((b'hardware-address', omapi.pack_mac(mac)))
    msg.obj.append((b'hardware-type', struct.pack(b'!I', 1)))
    if ip:
        msg.obj.append((b'ip-address', omapi.pack_ip(ip)))
    if name:
        msg.obj.append((b'name', salt.utils.stringutils.to_bytes(name)))
    if group:
        msg.obj.append((b'group', salt.utils.stringutils.to_bytes(group)))
    if supersede_host:
        statements += 'option host-name "{0}"; '.format(name)
    if ddns and name:
        statements += 'ddns-hostname "{0}"; '.format(name)
    if statements:
        msg.obj.append((b'statements', salt.utils.stringutils.to_bytes(statements)))
    response = o.query_server(msg)
    if response.opcode != omapi.OMAPI_OP_UPDATE:
        return False
    return True

Response: Adds a host object for the given mac.


Instruction:
How would you code a function in Python 3 to
delete the host with the given mac or name.

Response:
def delete_host(mac=None, name=None):
    '''
    Delete the host with the given mac or name.

    CLI Examples:

    .. code-block:: bash

        salt dhcp-server omapi.delete_host name=host1
        salt dhcp-server omapi.delete_host mac=ab:ab:ab:ab:ab:ab
    '''
    if not (mac or name):
        raise TypeError('At least one argument is required')
    o = _conn()
    msg = omapi.OmapiMessage.open(b'host')
    if mac:
        msg.obj.append((b'hardware-address', omapi.pack_mac(mac)))
        msg.obj.append((b'hardware-type', struct.pack(b'!I', 1)))
    if name:
        msg.obj.append((b'name', salt.utils.stringutils.to_bytes(name)))
    response = o.query_server(msg)
    if response.opcode != omapi.OMAPI_OP_UPDATE:
        return None
    if response.handle == 0:
        return False
    response = o.query_server(omapi.OmapiMessage.delete(response.handle))
    if response.opcode != omapi.OMAPI_OP_STATUS:
        return False
    return True


Instruction:
Create a Python 3 function for
returning the auth object

Response:
def _auth():
    '''
    Return the auth object
    '''
    if 'auth' not in __context__:
        try:
            __context__['auth'] = salt.crypt.SAuth(__opts__)
        except SaltClientError:
            log.error('Could not authenticate with master.'
                      'Mine data will not be transmitted.')
    return __context__['auth']


Instruction:
Create a Python 3 function for
executing the configured functions and send the data back up to the master.

Response:
def update(clear=False, mine_functions=None):
    '''
    Execute the configured functions and send the data back up to the master.
    The functions to be executed are merged from the master config, pillar and
    minion config under the option `mine_functions`:

    .. code-block:: yaml

        mine_functions:
          network.ip_addrs:
            - eth0
          disk.usage: []

    This function accepts the following arguments:

    clear: False
        Boolean flag specifying whether updating will clear the existing
        mines, or will update. Default: `False` (update).

    mine_functions
        Update the mine data on certain functions only.
        This feature can be used when updating the mine for functions
        that require refresh at different intervals than the rest of
        the functions specified under `mine_functions` in the
        minion/master config or pillar.
        A potential use would be together with the `scheduler`, for example:

        .. code-block:: yaml

            schedule:
              lldp_mine_update:
                function: mine.update
                kwargs:
                    mine_functions:
                      net.lldp: []
                hours: 12

        In the example above, the mine for `net.lldp` would be refreshed
        every 12 hours, while  `network.ip_addrs` would continue to be updated
        as specified in `mine_interval`.

    The function cache will be populated with information from executing these
    functions

    CLI Example:

    .. code-block:: bash

        salt '*' mine.update
    '''
    m_data = {}
    if not mine_functions:
        m_data = __salt__['config.merge']('mine_functions', {})
        # If we don't have any mine functions configured, then we should just bail out
        if not m_data:
            return
    elif mine_functions and isinstance(mine_functions, list):
        m_data = dict((fun, {}) for fun in mine_functions)
    elif mine_functions and isinstance(mine_functions, dict):
        m_data = mine_functions
    else:
        return

    data = {}
    for func in m_data:
        try:
            if m_data[func] and isinstance(m_data[func], dict):
                mine_func = m_data[func].pop('mine_function', func)
                if not _mine_function_available(mine_func):
                    continue
                data[func] = __salt__[mine_func](**m_data[func])
            elif m_data[func] and isinstance(m_data[func], list):
                mine_func = func
                if isinstance(m_data[func][0], dict) and 'mine_function' in m_data[func][0]:
                    mine_func = m_data[func][0]['mine_function']
                    m_data[func].pop(0)

                if not _mine_function_available(mine_func):
                    continue
                data[func] = __salt__[mine_func](*m_data[func])
            else:
                if not _mine_function_available(func):
                    continue
                data[func] = __salt__[func]()
        except Exception:
            trace = traceback.format_exc()
            log.error('Function %s in mine_functions failed to execute', func)
            log.debug('Error: %s', trace)
            continue
    if __opts__['file_client'] == 'local':
        if not clear:
            old = __salt__['data.get']('mine_cache')
            if isinstance(old, dict):
                old.update(data)
                data = old
        return __salt__['data.update']('mine_cache', data)
    load = {
            'cmd': '_mine',
            'data': data,
            'id': __opts__['id'],
            'clear': clear,
    }
    return _mine_send(load, __opts__)


Instruction:
Can you tell what is the following Python 3 function doing
def send(func, *args, **kwargs):
    '''
    Send a specific function to the mine.

    CLI Example:

    .. code-block:: bash

        salt '*' mine.send network.ip_addrs eth0
        salt '*' mine.send eth0_ip_addrs mine_function=network.ip_addrs eth0
    '''
    kwargs = salt.utils.args.clean_kwargs(**kwargs)
    mine_func = kwargs.pop('mine_function', func)
    if mine_func not in __salt__:
        return False
    data = {}
    arg_data = salt.utils.args.arg_lookup(__salt__[mine_func])
    func_data = copy.deepcopy(kwargs)
    for ind, _ in enumerate(arg_data.get('args', [])):
        try:
            func_data[arg_data['args'][ind]] = args[ind]
        except IndexError:
            # Safe error, arg may be in kwargs
            pass
    f_call = salt.utils.args.format_call(
        __salt__[mine_func],
        func_data,
        expected_extra_kws=MINE_INTERNAL_KEYWORDS)
    for arg in args:
        if arg not in f_call['args']:
            f_call['args'].append(arg)
    try:
        if 'kwargs' in f_call:
            data[func] = __salt__[mine_func](*f_call['args'], **f_call['kwargs'])
        else:
            data[func] = __salt__[mine_func](*f_call['args'])
    except Exception as exc:
        log.error('Function %s in mine.send failed to execute: %s',
                  mine_func, exc)
        return False
    if __opts__['file_client'] == 'local':
        old = __salt__['data.get']('mine_cache')
        if isinstance(old, dict):
            old.update(data)
            data = old
        return __salt__['data.update']('mine_cache', data)
    load = {
            'cmd': '_mine',
            'data': data,
            'id': __opts__['id'],
    }
    return _mine_send(load, __opts__)

Response: Send a specific function to the mine.


Instruction:
How would you explain what the following Python 3 function does
def get(tgt,
        fun,
        tgt_type='glob',
        exclude_minion=False):
    '''
    Get data from the mine based on the target, function and tgt_type

    Targets can be matched based on any standard matching system that can be
    matched on the master via these keywords:

    - glob
    - pcre
    - grain
    - grain_pcre
    - compound
    - pillar
    - pillar_pcre

    Note that all pillar matches, whether using the compound matching system or
    the pillar matching system, will be exact matches, with globbing disabled.

    exclude_minion
        Excludes the current minion from the result set

    CLI Example:

    .. code-block:: bash

        salt '*' mine.get '*' network.interfaces
        salt '*' mine.get '*' network.interfaces,network.ipaddrs
        salt '*' mine.get '*' '["network.interfaces", "network.ipaddrs"]'
        salt '*' mine.get 'os:Fedora' network.interfaces grain
        salt '*' mine.get 'G@os:Fedora and S@192.168.5.0/24' network.ipaddrs compound

    .. seealso:: Retrieving Mine data from Pillar and Orchestrate

        This execution module is intended to be executed on minions.
        Master-side operations such as Pillar or Orchestrate that require Mine
        data should use the :py:mod:`Mine Runner module <salt.runners.mine>`
        instead; it can be invoked from a Pillar SLS file using the
        :py:func:`saltutil.runner <salt.modules.saltutil.runner>` module. For
        example:

        .. code-block:: jinja

            {% set minion_ips = salt.saltutil.runner('mine.get',
                tgt='*',
                fun='network.ip_addrs',
                tgt_type='glob') %}
    '''
    if __opts__['file_client'] == 'local':
        ret = {}
        is_target = {'glob': __salt__['match.glob'],
                     'pcre': __salt__['match.pcre'],
                     'list': __salt__['match.list'],
                     'grain': __salt__['match.grain'],
                     'grain_pcre': __salt__['match.grain_pcre'],
                     'ipcidr': __salt__['match.ipcidr'],
                     'compound': __salt__['match.compound'],
                     'pillar': __salt__['match.pillar'],
                     'pillar_pcre': __salt__['match.pillar_pcre'],
                     }[tgt_type](tgt)
        if is_target:
            data = __salt__['data.get']('mine_cache')

            if isinstance(data, dict):
                if isinstance(fun, six.string_types):
                    functions = list(set(fun.split(',')))
                    _ret_dict = len(functions) > 1
                elif isinstance(fun, list):
                    functions = fun
                    _ret_dict = True
                else:
                    return {}

                if not _ret_dict and functions and functions[0] in data:
                    ret[__opts__['id']] = data.get(functions)
                elif _ret_dict:
                    for fun in functions:
                        if fun in data:
                            ret.setdefault(fun, {})[__opts__['id']] = data.get(fun)

        return ret
    load = {
            'cmd': '_mine_get',
            'id': __opts__['id'],
            'tgt': tgt,
            'fun': fun,
            'tgt_type': tgt_type,
    }
    ret = _mine_get(load, __opts__)
    if exclude_minion:
        if __opts__['id'] in ret:
            del ret[__opts__['id']]
    return ret

Response: Return the data from the master based on the target function and tgt_type


Instruction:
Can you implement a function in Python 3 that
removes specific function contents of minion. Returns True on success.

Response:
def delete(fun):
    '''
    Remove specific function contents of minion. Returns True on success.

    CLI Example:

    .. code-block:: bash

        salt '*' mine.delete 'network.interfaces'
    '''
    if __opts__['file_client'] == 'local':
        data = __salt__['data.get']('mine_cache')
        if isinstance(data, dict) and fun in data:
            del data[fun]
        return __salt__['data.update']('mine_cache', data)
    load = {
            'cmd': '_mine_delete',
            'id': __opts__['id'],
            'fun': fun,
    }
    return _mine_send(load, __opts__)


Instruction:
Can you create a Python 3 function that
gets all docker info for a given set of network interfaces and subnet addresses.

Response:
def get_docker(interfaces=None, cidrs=None, with_container_id=False):
    '''
    .. versionchanged:: 2017.7.8,2018.3.3
        When :conf_minion:`docker.update_mine` is set to ``False`` for a given
        minion, no mine data will be populated for that minion, and thus none
        will be returned for it.
    .. versionchanged:: 2019.2.0
        :conf_minion:`docker.update_mine` now defaults to ``False``

    Get all mine data for :py:func:`docker.ps <salt.modules.dockermod.ps_>` and
    run an aggregation routine. The ``interfaces`` parameter allows for
    specifying the network interfaces from which to select IP addresses. The
    ``cidrs`` parameter allows for specifying a list of subnets which the IP
    address must match.

    with_container_id
        Boolean, to expose container_id in the list of results

        .. versionadded:: 2015.8.2

    CLI Example:

    .. code-block:: bash

        salt '*' mine.get_docker
        salt '*' mine.get_docker interfaces='eth0'
        salt '*' mine.get_docker interfaces='["eth0", "eth1"]'
        salt '*' mine.get_docker cidrs='107.170.147.0/24'
        salt '*' mine.get_docker cidrs='["107.170.147.0/24", "172.17.42.0/24"]'
        salt '*' mine.get_docker interfaces='["eth0", "eth1"]' cidrs='["107.170.147.0/24", "172.17.42.0/24"]'
    '''
    # Enforce that interface and cidr are lists
    if interfaces:
        interface_ = []
        interface_.extend(interfaces if isinstance(interfaces, list) else [interfaces])
        interfaces = interface_
    if cidrs:
        cidr_ = []
        cidr_.extend(cidrs if isinstance(cidrs, list) else [cidrs])
        cidrs = cidr_

    # Get docker info
    cmd = 'docker.ps'
    docker_hosts = get('*', cmd)

    proxy_lists = {}

    # Process docker info
    for containers in six.itervalues(docker_hosts):
        host = containers.pop('host')
        host_ips = []

        # Prepare host_ips list
        if not interfaces:
            for info in six.itervalues(host['interfaces']):
                if 'inet' in info:
                    for ip_ in info['inet']:
                        host_ips.append(ip_['address'])
        else:
            for interface in interfaces:
                if interface in host['interfaces']:
                    if 'inet' in host['interfaces'][interface]:
                        for item in host['interfaces'][interface]['inet']:
                            host_ips.append(item['address'])
        host_ips = list(set(host_ips))

        # Filter out ips from host_ips with cidrs
        if cidrs:
            good_ips = []
            for cidr in cidrs:
                for ip_ in host_ips:
                    if salt.utils.network.in_subnet(cidr, [ip_]):
                        good_ips.append(ip_)
            host_ips = list(set(good_ips))

        # Process each container
        for container in six.itervalues(containers):
            container_id = container['Info']['Id']
            if container['Image'] not in proxy_lists:
                proxy_lists[container['Image']] = {}
            for dock_port in container['Ports']:
                # IP exists only if port is exposed
                ip_address = dock_port.get('IP')
                # If port is 0.0.0.0, then we must get the docker host IP
                if ip_address == '0.0.0.0':
                    for ip_ in host_ips:
                        containers = proxy_lists[container['Image']].setdefault('ipv4', {}).setdefault(dock_port['PrivatePort'], [])
                        container_network_footprint = '{0}:{1}'.format(ip_, dock_port['PublicPort'])
                        if with_container_id:
                            value = (container_network_footprint, container_id)
                        else:
                            value = container_network_footprint
                        if value not in containers:
                            containers.append(value)
                elif ip_address:
                    containers = proxy_lists[container['Image']].setdefault('ipv4', {}).setdefault(dock_port['PrivatePort'], [])
                    container_network_footprint = '{0}:{1}'.format(dock_port['IP'], dock_port['PublicPort'])
                    if with_container_id:
                        value = (container_network_footprint, container_id)
                    else:
                        value = container_network_footprint
                    if value not in containers:
                        containers.append(value)

    return proxy_lists


Instruction:
Can you generate a brief explanation for the following Python 3 code
def valid():
    '''
    List valid entries in mine configuration.

    CLI Example:

    .. code-block:: bash

        salt '*' mine.valid
    '''
    m_data = __salt__['config.merge']('mine_functions', {})
    # If we don't have any mine functions configured, then we should just bail out
    if not m_data:
        return

    data = {}
    for func in m_data:
        if m_data[func] and isinstance(m_data[func], dict):
            mine_func = m_data[func].pop('mine_function', func)
            if not _mine_function_available(mine_func):
                continue
            data[func] = {mine_func: m_data[func]}
        elif m_data[func] and isinstance(m_data[func], list):
            mine_func = func
            if isinstance(m_data[func][0], dict) and 'mine_function' in m_data[func][0]:
                mine_func = m_data[func][0]['mine_function']
                m_data[func].pop(0)

            if not _mine_function_available(mine_func):
                continue
            data[func] = {mine_func: m_data[func]}
        else:
            if not _mine_function_available(func):
                continue
            data[func] = m_data[func]

    return data

Response: List valid entries in mine configuration.


Instruction:
Can you tell what is the following Python 3 function doing
def returner(ret):
    '''
    Return data to a Pg server
    '''
    try:
        with _get_serv(ret, commit=True) as cur:
            sql = '''INSERT INTO salt_returns
                    (fun, jid, return, id, success, full_ret, alter_time)
                    VALUES (%s, %s, %s, %s, %s, %s, to_timestamp(%s))'''

            cur.execute(sql, (ret['fun'], ret['jid'],
                              psycopg2.extras.Json(ret['return']),
                              ret['id'],
                              ret.get('success', False),
                              psycopg2.extras.Json(ret),
                              time.time()))
    except salt.exceptions.SaltMasterError:
        log.critical('Could not store return with pgjsonb returner. PostgreSQL server unavailable.')

Response:
Return data to a Pg server
 ArcGIS server


Instruction:
How would you explain what the following Python 3 function does
def event_return(events):
    '''
    Return event to Pg server

    Requires that configuration be enabled via 'event_return'
    option in master config.
    '''
    with _get_serv(events, commit=True) as cur:
        for event in events:
            tag = event.get('tag', '')
            data = event.get('data', '')
            sql = '''INSERT INTO salt_events (tag, data, master_id, alter_time)
                     VALUES (%s, %s, %s, to_timestamp(%s))'''
            cur.execute(sql, (tag, psycopg2.extras.Json(data),
                              __opts__['id'], time.time()))

Response: Return event to Pg server


Instruction:
Can you generate the documentation for the following Python 3 function
def save_load(jid, load, minions=None):
    '''
    Save the load to the specified jid id
    '''
    with _get_serv(commit=True) as cur:
        try:
            cur.execute(PG_SAVE_LOAD_SQL,
                        {'jid': jid, 'load': psycopg2.extras.Json(load)})
        except psycopg2.IntegrityError:
            # https://github.com/saltstack/salt/issues/22171
            # Without this try/except we get tons of duplicate entry errors
            # which result in job returns not being stored properly
            pass

Response: Save the load to the specified jid id


Instruction:
Can you generate the documentation for the following Python 3 function
def get_load(jid):
    '''
    Return the load data that marks a specified jid
    '''
    with _get_serv(ret=None, commit=True) as cur:

        sql = '''SELECT load FROM jids WHERE jid = %s;'''
        cur.execute(sql, (jid,))
        data = cur.fetchone()
        if data:
            return data[0]
        return {}

Response:
Return the load data that marks a specified jid
    Return the load data that marks a specified jid
    Return the load data that marks a specified jid
    Return the load data that marks a specified jid
    Return the empty dict if no load data is found


Instruction:
Explain what the following Python 3 code does
def get_fun(fun):
    '''
    Return a dict of the last function called for all minions
    '''
    with _get_serv(ret=None, commit=True) as cur:

        sql = '''SELECT s.id,s.jid, s.full_ret
                FROM salt_returns s
                JOIN ( SELECT MAX(`jid`) as jid
                    from salt_returns GROUP BY fun, id) max
                ON s.jid = max.jid
                WHERE s.fun = %s
                '''

        cur.execute(sql, (fun,))
        data = cur.fetchall()

        ret = {}
        if data:
            for minion, _, full_ret in data:
                ret[minion] = full_ret
        return ret

Response: Return a dict of the last function called for all minions


Instruction:
Create a Python 3 function to
purge jobs older than this date.

Response:
def _purge_jobs(timestamp):
    '''
    Purge records from the returner tables.
    :param job_age_in_seconds:  Purge jobs older than this
    :return:
    '''
    with _get_serv() as cursor:
        try:
            sql = 'delete from jids where jid in (select distinct jid from salt_returns where alter_time < %s)'
            cursor.execute(sql, (timestamp,))
            cursor.execute('COMMIT')
        except psycopg2.DatabaseError as err:
            error = err.args
            sys.stderr.write(six.text_type(error))
            cursor.execute("ROLLBACK")
            raise err

        try:
            sql = 'delete from salt_returns where alter_time < %s'
            cursor.execute(sql, (timestamp,))
            cursor.execute('COMMIT')
        except psycopg2.DatabaseError as err:
            error = err.args
            sys.stderr.write(six.text_type(error))
            cursor.execute("ROLLBACK")
            raise err

        try:
            sql = 'delete from salt_events where alter_time < %s'
            cursor.execute(sql, (timestamp,))
            cursor.execute('COMMIT')
        except psycopg2.DatabaseError as err:
            error = err.args
            sys.stderr.write(six.text_type(error))
            cursor.execute("ROLLBACK")
            raise err

    return True


Instruction:
Write a Python 3 function that can
archive jobs from the backup tables.

Response:
def _archive_jobs(timestamp):
    '''
    Copy rows to a set of backup tables, then purge rows.
    :param timestamp: Archive rows older than this timestamp
    :return:
    '''
    source_tables = ['jids',
                     'salt_returns',
                     'salt_events']

    with _get_serv() as cursor:
        target_tables = {}
        for table_name in source_tables:
            try:
                tmp_table_name = table_name + '_archive'
                sql = 'create table IF NOT exists {0} (LIKE {1})'.format(tmp_table_name, table_name)
                cursor.execute(sql)
                cursor.execute('COMMIT')
                target_tables[table_name] = tmp_table_name
            except psycopg2.DatabaseError as err:
                error = err.args
                sys.stderr.write(six.text_type(error))
                cursor.execute("ROLLBACK")
                raise err

        try:
            sql = 'insert into {0} select * from {1} where jid in (select distinct jid from salt_returns where alter_time < %s)'.format(target_tables['jids'], 'jids')
            cursor.execute(sql, (timestamp,))
            cursor.execute('COMMIT')
        except psycopg2.DatabaseError as err:
            error = err.args
            sys.stderr.write(six.text_type(error))
            cursor.execute("ROLLBACK")
            raise err
        except Exception as e:
            log.error(e)
            raise

        try:
            sql = 'insert into {0} select * from {1} where alter_time < %s'.format(target_tables['salt_returns'], 'salt_returns')
            cursor.execute(sql, (timestamp,))
            cursor.execute('COMMIT')
        except psycopg2.DatabaseError as err:
            error = err.args
            sys.stderr.write(six.text_type(error))
            cursor.execute("ROLLBACK")
            raise err

        try:
            sql = 'insert into {0} select * from {1} where alter_time < %s'.format(target_tables['salt_events'], 'salt_events')
            cursor.execute(sql, (timestamp,))
            cursor.execute('COMMIT')
        except psycopg2.DatabaseError as err:
            error = err.args
            sys.stderr.write(six.text_type(error))
            cursor.execute("ROLLBACK")
            raise err

    return _purge_jobs(timestamp)


Instruction:
Write a Python 3 script to
call in the master s event loop every loop_interval.

Response:
def clean_old_jobs():
    '''
    Called in the master's event loop every loop_interval.  Archives and/or
    deletes the events and job details from the database.
    :return:
    '''
    if __opts__.get('keep_jobs', False) and int(__opts__.get('keep_jobs', 0)) > 0:
        try:
            with _get_serv() as cur:
                sql = "select (NOW() -  interval '{0}' hour) as stamp;".format(__opts__['keep_jobs'])
                cur.execute(sql)
                rows = cur.fetchall()
                stamp = rows[0][0]

            if __opts__.get('archive_jobs', False):
                _archive_jobs(stamp)
            else:
                _purge_jobs(stamp)
        except Exception as e:
            log.error(e)


Instruction:
Create a Python 3 function to
return information about the CPU.

Response:
def cpustats():
    '''
    Return information about the CPU.

    Returns
        dict: A dictionary containing information about the CPU stats

    CLI Example:

    .. code-block:: bash

        salt * status.cpustats
    '''
    # Tries to gather information similar to that returned by a Linux machine
    # Avoid using WMI as there's a lot of overhead

    # Time related info
    user, system, idle, interrupt, dpc = psutil.cpu_times()
    cpu = {'user': user,
           'system': system,
           'idle': idle,
           'irq': interrupt,
           'dpc': dpc}
    # Count related info
    ctx_switches, interrupts, soft_interrupts, sys_calls = psutil.cpu_stats()
    intr = {'irqs': {'irqs': [],
                     'total': interrupts}}
    soft_irq = {'softirqs': [],
               'total': soft_interrupts}
    return {'btime': psutil.boot_time(),
            'cpu': cpu,
            'ctxt': ctx_switches,
            'intr': intr,
            'processes': len(psutil.pids()),
            'softirq': soft_irq,
            'syscalls': sys_calls}


Instruction:
Can you generate the documentation for the following Python 3 function
def meminfo():
    '''
    Return information about physical and virtual memory on the system

    Returns:
        dict: A dictionary of information about memory on the system

    CLI Example:

    .. code-block:: bash

        salt * status.meminfo
    '''
    # Get physical memory
    vm_total, vm_available, vm_percent, vm_used, vm_free = psutil.virtual_memory()
    # Get swap memory
    swp_total, swp_used, swp_free, swp_percent, _, _ = psutil.swap_memory()

    def get_unit_value(memory):
        symbols = ('K', 'M', 'G', 'T', 'P', 'E', 'Z', 'Y')
        prefix = {}
        for i, s in enumerate(symbols):
            prefix[s] = 1 << (i + 1) * 10
        for s in reversed(symbols):
            if memory >= prefix[s]:
                value = float(memory) / prefix[s]
                return {'unit': s,
                        'value': value}
        return {'unit': 'B',
                'value': memory}

    return {'VmallocTotal': get_unit_value(vm_total),
            'VmallocUsed': get_unit_value(vm_used),
            'VmallocFree': get_unit_value(vm_free),
            'VmallocAvail': get_unit_value(vm_available),
            'SwapTotal': get_unit_value(swp_total),
            'SwapUsed': get_unit_value(swp_used),
            'SwapFree': get_unit_value(swp_free)}

Response:
Return information about physical and virtual memory on the system
otope


Instruction:
How would you explain what the following Python 3 function does
def vmstats():
    '''
    Return information about the virtual memory on the machine

    Returns:
        dict: A dictionary of virtual memory stats

    CLI Example:

    .. code-block:: bash

        salt * status.vmstats
    '''
    # Setup the SPI Structure
    spi = SYSTEM_PERFORMANCE_INFORMATION()
    retlen = ctypes.c_ulong()

    # 2 means to query System Performance Information and return it in a
    # SYSTEM_PERFORMANCE_INFORMATION Structure
    ctypes.windll.ntdll.NtQuerySystemInformation(
        2, ctypes.byref(spi), ctypes.sizeof(spi), ctypes.byref(retlen))

    # Return each defined field in a dict
    ret = {}
    for field in spi._fields_:
        ret.update({field[0]: getattr(spi, field[0])})

    return ret

Response: Return information about the virtual memory on the machine


Instruction:
Create a Python 3 function to
return the disk usage for this minion

Response:
def diskusage(human_readable=False, path=None):
    '''
    .. versionadded:: 2015.8.0

    Return the disk usage for this minion

    human_readable : False
        If ``True``, usage will be in KB/MB/GB etc.

    CLI Example:

    .. code-block:: bash

        salt '*' status.diskusage path=c:/salt
    '''
    if not path:
        path = 'c:/'

    disk_stats = psutil.disk_usage(path)

    total_val = disk_stats.total
    used_val = disk_stats.used
    free_val = disk_stats.free
    percent = disk_stats.percent

    if human_readable:
        total_val = _byte_calc(total_val)
        used_val = _byte_calc(used_val)
        free_val = _byte_calc(free_val)

    return {'total': total_val,
            'used': used_val,
            'free': free_val,
            'percent': percent}


Instruction:
Implement a function in Python 3 to
return the process data for all processes in the system

Response:
def procs(count=False):
    '''
    Return the process data

    count : False
        If ``True``, this function will simply return the number of processes.

        .. versionadded:: 2015.8.0

    CLI Example:

    .. code-block:: bash

        salt '*' status.procs
        salt '*' status.procs count
    '''
    with salt.utils.winapi.Com():
        wmi_obj = wmi.WMI()
        processes = wmi_obj.win32_process()

    #this short circuit's the function to get a short simple proc count.
    if count:
        return len(processes)

    #a propper run of the function, creating a nonsensically long out put.
    process_info = {}
    for proc in processes:
        process_info[proc.ProcessId] = _get_process_info(proc)

    return process_info


Instruction:
Can you tell what is the following Python 3 function doing
def saltmem(human_readable=False):
    '''
    .. versionadded:: 2015.8.0

    Returns the amount of memory that salt is using

    human_readable : False
        return the value in a nicely formatted number

    CLI Example:

    .. code-block:: bash

        salt '*' status.saltmem
        salt '*' status.saltmem human_readable=True
    '''
    # psutil.Process defaults to current process (`os.getpid()`)
    p = psutil.Process()

    # Use oneshot to get a snapshot
    with p.oneshot():
        mem = p.memory_info().rss

    if human_readable:
        return _byte_calc(mem)

    return mem

Response: Return the amount of memory that salt is using


Instruction:
Can you generate a brief explanation for the following Python 3 code
def uptime(human_readable=False):
    '''
    .. versionadded:: 2015.8.0

    Return the system uptime for the machine

    Args:

        human_readable (bool):
            Return uptime in human readable format if ``True``, otherwise
            return seconds. Default is ``False``

            .. note::
                Human readable format is ``days, hours:min:sec``. Days will only
                be displayed if more than 0

    Returns:
        str:
            The uptime in seconds or human readable format depending on the
            value of ``human_readable``

    CLI Example:

    .. code-block:: bash

        salt '*' status.uptime
        salt '*' status.uptime human_readable=True
    '''
    # Get startup time
    startup_time = datetime.datetime.fromtimestamp(psutil.boot_time())

    # Subtract startup time from current time to get the uptime of the system
    uptime = datetime.datetime.now() - startup_time

    return six.text_type(uptime) if human_readable else uptime.total_seconds()

Response: Return the system uptime for the specified resource.


Instruction:
Write a Python 3 script for
returning process information as a dict

Response:
def _get_process_info(proc):
    '''
    Return  process information
    '''
    cmd = salt.utils.stringutils.to_unicode(proc.CommandLine or '')
    name = salt.utils.stringutils.to_unicode(proc.Name)
    info = dict(
        cmd=cmd,
        name=name,
        **_get_process_owner(proc)
    )
    return info


Instruction:
How would you code a function in Python 3 to
return a new master entry for the current state of the master.

Response:
def master(master=None, connected=True):
    '''
    .. versionadded:: 2015.5.0

    Fire an event if the minion gets disconnected from its master. This
    function is meant to be run via a scheduled job from the minion. If
    master_ip is an FQDN/Hostname, is must be resolvable to a valid IPv4
    address.

    CLI Example:

    .. code-block:: bash

        salt '*' status.master
    '''

    def _win_remotes_on(port):
        '''
        Windows specific helper function.
        Returns set of ipv4 host addresses of remote established connections
        on local or remote tcp port.

        Parses output of shell 'netstat' to get connections

        PS C:> netstat -n -p TCP

        Active Connections

          Proto  Local Address          Foreign Address        State
          TCP    10.1.1.26:3389         10.1.1.1:4505          ESTABLISHED
          TCP    10.1.1.26:56862        10.1.1.10:49155        TIME_WAIT
          TCP    10.1.1.26:56868        169.254.169.254:80     CLOSE_WAIT
          TCP    127.0.0.1:49197        127.0.0.1:49198        ESTABLISHED
          TCP    127.0.0.1:49198        127.0.0.1:49197        ESTABLISHED
        '''
        remotes = set()
        try:
            data = subprocess.check_output(['netstat', '-n', '-p', 'TCP'])  # pylint: disable=minimum-python-version
        except subprocess.CalledProcessError:
            log.error('Failed netstat')
            raise

        lines = salt.utils.stringutils.to_unicode(data).split('\n')
        for line in lines:
            if 'ESTABLISHED' not in line:
                continue
            chunks = line.split()
            remote_host, remote_port = chunks[2].rsplit(':', 1)
            if int(remote_port) != port:
                continue
            remotes.add(remote_host)
        return remotes

    # the default publishing port
    port = 4505
    master_ips = None

    if master:
        master_ips = _host_to_ips(master)

    if not master_ips:
        return

    if __salt__['config.get']('publish_port') != '':
        port = int(__salt__['config.get']('publish_port'))

    master_connection_status = False
    connected_ips = _win_remotes_on(port)

    # Get connection status for master
    for master_ip in master_ips:
        if master_ip in connected_ips:
            master_connection_status = True
            break

    # Connection to master is not as expected
    if master_connection_status is not connected:
        event = salt.utils.event.get_event('minion', opts=__opts__, listen=False)
        if master_connection_status:
            event.fire_event({'master': master}, salt.minion.master_event(type='connected'))
        else:
            event.fire_event({'master': master}, salt.minion.master_event(type='disconnected'))

    return master_connection_status


Instruction:
Here you have a function in Python 3, explain what it does
def _check_config_exists(config_file=None):
    '''
    Verify the config file is present
    '''
    if config_file is None:
        config_file = _config_file()
    if not os.path.isfile(config_file):
        return False
    return True

Response: Verify the config file is present and is a valid resource.


Instruction:
Can you generate the documentation for the following Python 3 function
def is_jail(name):
    '''
    Return True if jail exists False if not

    CLI Example:

    .. code-block:: bash

        salt '*' poudriere.is_jail <jail name>
    '''
    jails = list_jails()
    for jail in jails:
        if jail.split()[0] == name:
            return True
    return False

Response: Check if a jail exists


Instruction:
How would you code a function in Python 3 to
make pkgng aware version of the current hierarchy

Response:
def make_pkgng_aware(jname):
    '''
    Make jail ``jname`` pkgng aware

    CLI Example:

    .. code-block:: bash

        salt '*' poudriere.make_pkgng_aware <jail name>
    '''
    ret = {'changes': {}}
    cdir = _config_dir()
    # ensure cdir is there
    if not os.path.isdir(cdir):
        os.makedirs(cdir)
        if os.path.isdir(cdir):
            ret['changes'] = 'Created poudriere make file dir {0}'.format(cdir)
        else:
            return 'Could not create or find required directory {0}'.format(
                    cdir)

    # Added args to file
    __salt__['file.write']('{0}-make.conf'.format(os.path.join(cdir, jname)), 'WITH_PKGNG=yes')

    if os.path.isfile(os.path.join(cdir, jname) + '-make.conf'):
        ret['changes'] = 'Created {0}'.format(
                os.path.join(cdir, '{0}-make.conf'.format(jname))
                )
        return ret
    else:
        return 'Looks like file {0} could not be created'.format(
                os.path.join(cdir, jname + '-make.conf')
                )


Instruction:
Make a summary of the following Python 3 code
def parse_config(config_file=None):
    '''
    Returns a dict of poudriere main configuration definitions

    CLI Example:

    .. code-block:: bash

        salt '*' poudriere.parse_config
    '''
    if config_file is None:
        config_file = _config_file()
    ret = {}
    if _check_config_exists(config_file):
        with salt.utils.files.fopen(config_file) as ifile:
            for line in ifile:
                key, val = salt.utils.stringutils.to_unicode(line).split('=')
                ret[key] = val
        return ret

    return 'Could not find {0} on file system'.format(config_file)

Response: Parses the poudriere main configuration file


Instruction:
Create a Python 3 function for
creating a new poudriere jail

Response:
def create_jail(name, arch, version="9.0-RELEASE"):
    '''
    Creates a new poudriere jail if one does not exist

    *NOTE* creating a new jail will take some time the master is not hanging

    CLI Example:

    .. code-block:: bash

        salt '*' poudriere.create_jail 90amd64 amd64
    '''
    # Config file must be on system to create a poudriere jail
    _check_config_exists()

    # Check if the jail is there
    if is_jail(name):
        return '{0} already exists'.format(name)

    cmd = 'poudriere jails -c -j {0} -v {1} -a {2}'.format(name, version, arch)
    __salt__['cmd.run'](cmd)

    # Make jail pkgng aware
    make_pkgng_aware(name)

    # Make sure the jail was created
    if is_jail(name):
        return 'Created jail {0}'.format(name)

    return 'Issue creating jail {0}'.format(name)


Instruction:
Here you have a function in Python 3, explain what it does
def update_jail(name):
    '''
    Run freebsd-update on `name` poudriere jail

    CLI Example:

    .. code-block:: bash

        salt '*' poudriere.update_jail freebsd:10:x86:64
    '''
    if is_jail(name):
        cmd = 'poudriere jail -u -j {0}'.format(name)
        ret = __salt__['cmd.run'](cmd)
        return ret
    else:
        return 'Could not find jail {0}'.format(name)

Response: Update the freebsd - update on the specified jail


Instruction:
Can you generate the documentation for the following Python 3 function
def delete_jail(name):
    '''
    Deletes poudriere jail with `name`

    CLI Example:

    .. code-block:: bash

        salt '*' poudriere.delete_jail 90amd64
    '''
    if is_jail(name):
        cmd = 'poudriere jail -d -j {0}'.format(name)
        __salt__['cmd.run'](cmd)

        # Make sure jail is gone
        if is_jail(name):
            return 'Looks like there was an issue deleteing jail \
            {0}'.format(name)
    else:
        # Could not find jail.
        return 'Looks like jail {0} has not been created'.format(name)

    # clean up pkgng make info in config dir
    make_file = os.path.join(_config_dir(), '{0}-make.conf'.format(name))
    if os.path.isfile(make_file):
        try:
            os.remove(make_file)
        except (IOError, OSError):
            return ('Deleted jail "{0}" but was unable to remove jail make '
                    'file').format(name)
        __salt__['file.remove'](make_file)

    return 'Deleted jail {0}'.format(name)

Response: Deletes poudriere jail with name


Instruction:
Write a Python 3 function for
updating the ports tree either the default or the ports_tree specified

Response:
def update_ports_tree(ports_tree):
    '''
    Updates the ports tree, either the default or the `ports_tree` specified

    CLI Example:

    .. code-block:: bash

        salt '*' poudriere.update_ports_tree staging
    '''
    _check_config_exists()
    if ports_tree:
        cmd = 'poudriere ports -u -p {0}'.format(ports_tree)
    else:
        cmd = 'poudriere ports -u'
    ret = __salt__['cmd.run'](cmd)
    return ret


Instruction:
Explain what the following Python 3 code does
def bulk_build(jail, pkg_file, keep=False):
    '''
    Run bulk build on poudriere server.

    Return number of pkg builds, failures, and errors, on error dump to CLI

    CLI Example:

    .. code-block:: bash

        salt -N buildbox_group poudriere.bulk_build 90amd64 /root/pkg_list

    '''
    # make sure `pkg file` and jail is on file system
    if not os.path.isfile(pkg_file):
        return 'Could not find file {0} on filesystem'.format(pkg_file)
    if not is_jail(jail):
        return 'Could not find jail {0}'.format(jail)

    # Generate command
    if keep:
        cmd = 'poudriere bulk -k -f {0} -j {1}'.format(pkg_file, jail)
    else:
        cmd = 'poudriere bulk -f {0} -j {1}'.format(pkg_file, jail)

    # Bulk build this can take some time, depending on pkg_file ... hours
    res = __salt__['cmd.run'](cmd)
    lines = res.splitlines()
    for line in lines:
        if "packages built" in line:
            return line
    return ('There may have been an issue building packages dumping output: '
            '{0}').format(res)

Response: Run bulk build on poudriere server.


Instruction:
Explain what the following Python 3 code does
def _update_nilrt_restart_state():
    '''
    NILRT systems determine whether to reboot after various package operations
    including but not limited to kernel module installs/removals by checking
    specific file md5sums & timestamps. These files are touched/modified by
    the post-install/post-remove functions of their respective packages.

    The opkg module uses this function to store/update those file timestamps
    and checksums to be used later by the restartcheck module.

    '''
    __salt__['cmd.shell']('stat -c %Y /lib/modules/$(uname -r)/modules.dep >{0}/modules.dep.timestamp'
                          .format(NILRT_RESTARTCHECK_STATE_PATH))
    __salt__['cmd.shell']('md5sum /lib/modules/$(uname -r)/modules.dep >{0}/modules.dep.md5sum'
                          .format(NILRT_RESTARTCHECK_STATE_PATH))

    # We can't assume nisysapi.ini always exists like modules.dep
    nisysapi_path = '/usr/local/natinst/share/nisysapi.ini'
    if os.path.exists(nisysapi_path):
        __salt__['cmd.shell']('stat -c %Y {0} >{1}/nisysapi.ini.timestamp'
                              .format(nisysapi_path, NILRT_RESTARTCHECK_STATE_PATH))
        __salt__['cmd.shell']('md5sum {0} >{1}/nisysapi.ini.md5sum'
                              .format(nisysapi_path, NILRT_RESTARTCHECK_STATE_PATH))

    # Expert plugin files get added to a conf.d dir, so keep track of the total
    # no. of files, their timestamps and content hashes
    nisysapi_conf_d_path = "/usr/lib/{0}/nisysapi/conf.d/experts/".format(
        'arm-linux-gnueabi' if 'arm' in __grains__.get('cpuarch') else 'x86_64-linux-gnu'
    )

    if os.path.exists(nisysapi_conf_d_path):
        with salt.utils.files.fopen('{0}/sysapi.conf.d.count'.format(
                NILRT_RESTARTCHECK_STATE_PATH), 'w') as fcount:
            fcount.write(str(len(os.listdir(nisysapi_conf_d_path))))

        for fexpert in os.listdir(nisysapi_conf_d_path):
            __salt__['cmd.shell']('stat -c %Y {0}/{1} >{2}/{1}.timestamp'
                                  .format(nisysapi_conf_d_path,
                                          fexpert,
                                          NILRT_RESTARTCHECK_STATE_PATH))
            __salt__['cmd.shell']('md5sum {0}/{1} >{2}/{1}.md5sum'
                                  .format(nisysapi_conf_d_path,
                                          fexpert,
                                          NILRT_RESTARTCHECK_STATE_PATH))

Response: Update the state of the NILRT restartcheck module.


Instruction:
Make a summary of the following Python 3 code
def _get_restartcheck_result(errors):
    '''
    Return restartcheck result and append errors (if any) to ``errors``
    '''
    rs_result = __salt__['restartcheck.restartcheck'](verbose=False)
    if isinstance(rs_result, dict) and 'comment' in rs_result:
        errors.append(rs_result['comment'])
    return rs_result

Response: Return restartcheck result and append errors to errors


Instruction:
Write a Python 3 script for
processing restartcheck output to see if system restarts were requested and take appropriate action.

Response:
def _process_restartcheck_result(rs_result, **kwargs):
    '''
    Check restartcheck output to see if system/service restarts were requested
    and take appropriate action.
    '''
    if 'No packages seem to need to be restarted' in rs_result:
        return
    reboot_required = False
    for rstr in rs_result:
        if 'System restart required' in rstr:
            _update_nilrt_restart_state()
            __salt__['system.set_reboot_required_witnessed']()
            reboot_required = True
    if kwargs.get('always_restart_services', True) or not reboot_required:
        for rstr in rs_result:
            if 'System restart required' not in rstr:
                service = os.path.join('/etc/init.d', rstr)
                if os.path.exists(service):
                    __salt__['cmd.run']([service, 'restart'])


Instruction:
Implement a function in Python 3 to
update the opkg database to latest packages based upon repositories

Response:
def refresh_db(failhard=False, **kwargs):  # pylint: disable=unused-argument
    '''
    Updates the opkg database to latest packages based upon repositories

    Returns a dict, with the keys being package databases and the values being
    the result of the update attempt. Values can be one of the following:

    - ``True``: Database updated successfully
    - ``False``: Problem updating database

    failhard
        If False, return results of failed lines as ``False`` for the package
        database that encountered the error.
        If True, raise an error with a list of the package databases that
        encountered errors.

        .. versionadded:: 2018.3.0

    CLI Example:

    .. code-block:: bash

        salt '*' pkg.refresh_db
    '''
    # Remove rtag file to keep multiple refreshes from happening in pkg states
    salt.utils.pkg.clear_rtag(__opts__)
    ret = {}
    error_repos = []
    cmd = ['opkg', 'update']
    # opkg returns a non-zero retcode when there is a failure to refresh
    # from one or more repos. Due to this, ignore the retcode.
    call = __salt__['cmd.run_all'](cmd,
                                   output_loglevel='trace',
                                   python_shell=False,
                                   ignore_retcode=True,
                                   redirect_stderr=True)

    out = call['stdout']
    prev_line = ''
    for line in salt.utils.itertools.split(out, '\n'):
        if 'Inflating' in line:
            key = line.strip().split()[1][:-1]
            ret[key] = True
        elif 'Updated source' in line:
            # Use the previous line.
            key = prev_line.strip().split()[1][:-1]
            ret[key] = True
        elif 'Failed to download' in line:
            key = line.strip().split()[5].split(',')[0]
            ret[key] = False
            error_repos.append(key)
        prev_line = line

    if failhard and error_repos:
        raise CommandExecutionError(
            'Error getting repos: {0}'.format(', '.join(error_repos))
        )

    # On a non-zero exit code where no failed repos were found, raise an
    # exception because this appears to be a different kind of error.
    if call['retcode'] != 0 and not error_repos:
        raise CommandExecutionError(out)

    return ret


Instruction:
Can you generate a brief explanation for the following Python 3 code
def _build_install_command_list(cmd_prefix, to_install, to_downgrade, to_reinstall):
    '''
    Builds a list of install commands to be executed in sequence in order to process
    each of the to_install, to_downgrade, and to_reinstall lists.
    '''
    cmds = []
    if to_install:
        cmd = copy.deepcopy(cmd_prefix)
        cmd.extend(to_install)
        cmds.append(cmd)
    if to_downgrade:
        cmd = copy.deepcopy(cmd_prefix)
        cmd.append('--force-downgrade')
        cmd.extend(to_downgrade)
        cmds.append(cmd)
    if to_reinstall:
        cmd = copy.deepcopy(cmd_prefix)
        cmd.append('--force-reinstall')
        cmd.extend(to_reinstall)
        cmds.append(cmd)

    return cmds

Response:
Builds a list of install commands to be executed in sequence in order to process
    each of the to_install to_downgrade and to_reinstall lists.


Instruction:
Explain what the following Python 3 code does
def _parse_reported_packages_from_install_output(output):
    '''
    Parses the output of "opkg install" to determine what packages would have been
    installed by an operation run with the --noaction flag.

    We are looking for lines like:
        Installing <package> (<version>) on <target>
    or
        Upgrading <package> from <oldVersion> to <version> on root
    '''
    reported_pkgs = {}
    install_pattern = re.compile(r'Installing\s(?P<package>.*?)\s\((?P<version>.*?)\)\son\s(?P<target>.*?)')
    upgrade_pattern = re.compile(r'Upgrading\s(?P<package>.*?)\sfrom\s(?P<oldVersion>.*?)\sto\s(?P<version>.*?)\son\s(?P<target>.*?)')
    for line in salt.utils.itertools.split(output, '\n'):
        match = install_pattern.match(line)
        if match is None:
            match = upgrade_pattern.match(line)
        if match:
            reported_pkgs[match.group('package')] = match.group('version')

    return reported_pkgs

Response:
Parses the output of opkg install to determine what packages would have been installed on the root
   .


Instruction:
How would you explain what the following Python 3 function does
def _execute_install_command(cmd, parse_output, errors, parsed_packages):
    '''
    Executes a command for the install operation.
    If the command fails, its error output will be appended to the errors list.
    If the command succeeds and parse_output is true, updated packages will be appended
    to the parsed_packages dictionary.
    '''
    out = __salt__['cmd.run_all'](
        cmd,
        output_loglevel='trace',
        python_shell=False
    )
    if out['retcode'] != 0:
        if out['stderr']:
            errors.append(out['stderr'])
        else:
            errors.append(out['stdout'])
    elif parse_output:
        parsed_packages.update(_parse_reported_packages_from_install_output(out['stdout']))

Response: Executes a command for the install operation.


Instruction:
Write a Python 3 script for
installing the passed package from the IPK database.

Response:
def install(name=None,
            refresh=False,
            pkgs=None,
            sources=None,
            reinstall=False,
            **kwargs):
    '''
    Install the passed package, add refresh=True to update the opkg database.

    name
        The name of the package to be installed. Note that this parameter is
        ignored if either "pkgs" or "sources" is passed. Additionally, please
        note that this option can only be used to install packages from a
        software repository. To install a package file manually, use the
        "sources" option.

        CLI Example:

        .. code-block:: bash

            salt '*' pkg.install <package name>

    refresh
        Whether or not to refresh the package database before installing.

    version
        Install a specific version of the package, e.g. 1.2.3~0ubuntu0. Ignored
        if "pkgs" or "sources" is passed.

        .. versionadded:: 2017.7.0

    reinstall : False
        Specifying reinstall=True will use ``opkg install --force-reinstall``
        rather than simply ``opkg install`` for requested packages that are
        already installed.

        If a version is specified with the requested package, then ``opkg
        install --force-reinstall`` will only be used if the installed version
        matches the requested version.

        .. versionadded:: 2017.7.0

    Multiple Package Installation Options:

    pkgs
        A list of packages to install from a software repository. Must be
        passed as a python list.

        CLI Example:

        .. code-block:: bash

            salt '*' pkg.install pkgs='["foo", "bar"]'
            salt '*' pkg.install pkgs='["foo", {"bar": "1.2.3-0ubuntu0"}]'

    sources
        A list of IPK packages to install. Must be passed as a list of dicts,
        with the keys being package names, and the values being the source URI
        or local path to the package.  Dependencies are automatically resolved
        and marked as auto-installed.

        CLI Example:

        .. code-block:: bash

            salt '*' pkg.install sources='[{"foo": "salt://foo.deb"},{"bar": "salt://bar.deb"}]'

    install_recommends
        Whether to install the packages marked as recommended. Default is True.

    only_upgrade
        Only upgrade the packages (disallow downgrades), if they are already
        installed. Default is False.

        .. versionadded:: 2017.7.0

    always_restart_services
        Whether to restart services even if a reboot is required. Default is True.

    Returns a dict containing the new package names and versions::

        {'<package>': {'old': '<old-version>',
                       'new': '<new-version>'}}
    '''
    refreshdb = salt.utils.data.is_true(refresh)

    try:
        pkg_params, pkg_type = __salt__['pkg_resource.parse_targets'](
            name, pkgs, sources, **kwargs
        )
    except MinionError as exc:
        raise CommandExecutionError(exc)

    old = list_pkgs()
    cmd_prefix = ['opkg', 'install']
    to_install = []
    to_reinstall = []
    to_downgrade = []

    _append_noaction_if_testmode(cmd_prefix, **kwargs)
    if not pkg_params:
        return {}
    elif pkg_type == 'file':
        if reinstall:
            cmd_prefix.append('--force-reinstall')
        if not kwargs.get('only_upgrade', False):
            cmd_prefix.append('--force-downgrade')
        to_install.extend(pkg_params)
    elif pkg_type == 'repository':
        if not kwargs.get('install_recommends', True):
            cmd_prefix.append('--no-install-recommends')
        for pkgname, pkgversion in six.iteritems(pkg_params):
            if (name and pkgs is None and kwargs.get('version') and
                    len(pkg_params) == 1):
                # Only use the 'version' param if 'name' was not specified as a
                # comma-separated list
                version_num = kwargs['version']
            else:
                version_num = pkgversion

            if version_num is None:
                # Don't allow downgrades if the version
                # number is not specified.
                if reinstall and pkgname in old:
                    to_reinstall.append(pkgname)
                else:
                    to_install.append(pkgname)
            else:
                pkgstr = '{0}={1}'.format(pkgname, version_num)
                cver = old.get(pkgname, '')
                if reinstall and cver and salt.utils.versions.compare(
                        ver1=version_num,
                        oper='==',
                        ver2=cver,
                        cmp_func=version_cmp):
                    to_reinstall.append(pkgstr)
                elif not cver or salt.utils.versions.compare(
                        ver1=version_num,
                        oper='>=',
                        ver2=cver,
                        cmp_func=version_cmp):
                    to_install.append(pkgstr)
                else:
                    if not kwargs.get('only_upgrade', False):
                        to_downgrade.append(pkgstr)
                    else:
                        # This should cause the command to fail.
                        to_install.append(pkgstr)

    cmds = _build_install_command_list(cmd_prefix, to_install, to_downgrade, to_reinstall)

    if not cmds:
        return {}

    if refreshdb:
        refresh_db()

    errors = []
    is_testmode = _is_testmode(**kwargs)
    test_packages = {}
    for cmd in cmds:
        _execute_install_command(cmd, is_testmode, errors, test_packages)

    __context__.pop('pkg.list_pkgs', None)
    new = list_pkgs()
    if is_testmode:
        new = copy.deepcopy(new)
        new.update(test_packages)

    ret = salt.utils.data.compare_dicts(old, new)

    if pkg_type == 'file' and reinstall:
        # For file-based packages, prepare 'to_reinstall' to have a list
        # of all the package names that may have been reinstalled.
        # This way, we could include reinstalled packages in 'ret'.
        for pkgfile in to_install:
            # Convert from file name to package name.
            cmd = ['opkg', 'info', pkgfile]
            out = __salt__['cmd.run_all'](
                cmd,
                output_loglevel='trace',
                python_shell=False
            )
            if out['retcode'] == 0:
                # Just need the package name.
                pkginfo_dict = _process_info_installed_output(
                    out['stdout'], []
                )
                if pkginfo_dict:
                    to_reinstall.append(list(pkginfo_dict.keys())[0])

    for pkgname in to_reinstall:
        if pkgname not in ret or pkgname in old:
            ret.update({pkgname: {'old': old.get(pkgname, ''),
                                  'new': new.get(pkgname, '')}})

    rs_result = _get_restartcheck_result(errors)

    if errors:
        raise CommandExecutionError(
            'Problem encountered installing package(s)',
            info={'errors': errors, 'changes': ret}
        )

    _process_restartcheck_result(rs_result, **kwargs)

    return ret


Instruction:
Given the following Python 3 function, write the documentation
def _parse_reported_packages_from_remove_output(output):
    '''
    Parses the output of "opkg remove" to determine what packages would have been
    removed by an operation run with the --noaction flag.

    We are looking for lines like
        Removing <package> (<version>) from <Target>...
    '''
    reported_pkgs = {}
    remove_pattern = re.compile(r'Removing\s(?P<package>.*?)\s\((?P<version>.*?)\)\sfrom\s(?P<target>.*?)...')
    for line in salt.utils.itertools.split(output, '\n'):
        match = remove_pattern.match(line)
        if match:
            reported_pkgs[match.group('package')] = ''

    return reported_pkgs

Response: Parses the output of opkg remove to determine what packages would have been removed from the target.


Instruction:
Write a Python 3 function for
removing packages using opkg remove.

Response:
def remove(name=None, pkgs=None, **kwargs):  # pylint: disable=unused-argument
    '''
    Remove packages using ``opkg remove``.

    name
        The name of the package to be deleted.

    Multiple Package Options:

    pkgs
        A list of packages to delete. Must be passed as a python list. The
        ``name`` parameter will be ignored if this option is passed.

    remove_dependencies
        Remove package and all dependencies

        .. versionadded:: 2019.2.0

    auto_remove_deps
        Remove packages that were installed automatically to satisfy dependencies

        .. versionadded:: 2019.2.0

    Returns a dict containing the changes.

    CLI Example:

    .. code-block:: bash

        salt '*' pkg.remove <package name>
        salt '*' pkg.remove <package1>,<package2>,<package3>
        salt '*' pkg.remove pkgs='["foo", "bar"]'
        salt '*' pkg.remove pkgs='["foo", "bar"]' remove_dependencies=True auto_remove_deps=True
    '''
    try:
        pkg_params = __salt__['pkg_resource.parse_targets'](name, pkgs)[0]
    except MinionError as exc:
        raise CommandExecutionError(exc)

    old = list_pkgs()
    targets = [x for x in pkg_params if x in old]
    if not targets:
        return {}
    cmd = ['opkg', 'remove']
    _append_noaction_if_testmode(cmd, **kwargs)
    if kwargs.get('remove_dependencies', False):
        cmd.append('--force-removal-of-dependent-packages')
    if kwargs.get('auto_remove_deps', False):
        cmd.append('--autoremove')
    cmd.extend(targets)

    out = __salt__['cmd.run_all'](
        cmd,
        output_loglevel='trace',
        python_shell=False
    )
    if out['retcode'] != 0:
        if out['stderr']:
            errors = [out['stderr']]
        else:
            errors = [out['stdout']]
    else:
        errors = []

    __context__.pop('pkg.list_pkgs', None)
    new = list_pkgs()
    if _is_testmode(**kwargs):
        reportedPkgs = _parse_reported_packages_from_remove_output(out['stdout'])
        new = {k: v for k, v in new.items() if k not in reportedPkgs}
    ret = salt.utils.data.compare_dicts(old, new)

    rs_result = _get_restartcheck_result(errors)

    if errors:
        raise CommandExecutionError(
            'Problem encountered removing package(s)',
            info={'errors': errors, 'changes': ret}
        )

    _process_restartcheck_result(rs_result, **kwargs)

    return ret


Instruction:
Write a Python 3 script for
upgrading all packages via opkg upgrade

Response:
def upgrade(refresh=True, **kwargs):  # pylint: disable=unused-argument
    '''
    Upgrades all packages via ``opkg upgrade``

    Returns a dictionary containing the changes:

    .. code-block:: python

        {'<package>':  {'old': '<old-version>',
                        'new': '<new-version>'}}

    CLI Example:

    .. code-block:: bash

        salt '*' pkg.upgrade
    '''
    ret = {'changes': {},
           'result': True,
           'comment': '',
           }

    errors = []

    if salt.utils.data.is_true(refresh):
        refresh_db()

    old = list_pkgs()

    cmd = ['opkg', 'upgrade']
    result = __salt__['cmd.run_all'](cmd,
                                     output_loglevel='trace',
                                     python_shell=False)
    __context__.pop('pkg.list_pkgs', None)
    new = list_pkgs()
    ret = salt.utils.data.compare_dicts(old, new)

    if result['retcode'] != 0:
        errors.append(result)

    rs_result = _get_restartcheck_result(errors)

    if errors:
        raise CommandExecutionError(
            'Problem encountered upgrading packages',
            info={'errors': errors, 'changes': ret}
        )

    _process_restartcheck_result(rs_result, **kwargs)

    return ret


Instruction:
Make a summary of the following Python 3 code
def hold(name=None, pkgs=None, sources=None, **kwargs):  # pylint: disable=W0613
    '''
    Set package in 'hold' state, meaning it will not be upgraded.

    name
        The name of the package, e.g., 'tmux'

        CLI Example:

        .. code-block:: bash

            salt '*' pkg.hold <package name>

    pkgs
        A list of packages to hold. Must be passed as a python list.

        CLI Example:

        .. code-block:: bash

            salt '*' pkg.hold pkgs='["foo", "bar"]'
    '''
    if not name and not pkgs and not sources:
        raise SaltInvocationError(
            'One of name, pkgs, or sources must be specified.'
        )
    if pkgs and sources:
        raise SaltInvocationError(
            'Only one of pkgs or sources can be specified.'
        )

    targets = []
    if pkgs:
        targets.extend(pkgs)
    elif sources:
        for source in sources:
            targets.append(next(iter(source)))
    else:
        targets.append(name)

    ret = {}
    for target in targets:
        if isinstance(target, dict):
            target = next(iter(target))

        ret[target] = {'name': target,
                       'changes': {},
                       'result': False,
                       'comment': ''}

        state = _get_state(target)
        if not state:
            ret[target]['comment'] = ('Package {0} not currently held.'
                                      .format(target))
        elif state != 'hold':
            if 'test' in __opts__ and __opts__['test']:
                ret[target].update(result=None)
                ret[target]['comment'] = ('Package {0} is set to be held.'
                                          .format(target))
            else:
                result = _set_state(target, 'hold')
                ret[target].update(changes=result[target], result=True)
                ret[target]['comment'] = ('Package {0} is now being held.'
                                          .format(target))
        else:
            ret[target].update(result=True)
            ret[target]['comment'] = ('Package {0} is already set to be held.'
                                      .format(target))
    return ret

Response: Hold a package in the sequence of packages.


Instruction:
Implement a function in Python 3 to
return the state of the pkg

Response:
def _get_state(pkg):
    '''
    View package state from the opkg database

    Return the state of pkg
    '''
    cmd = ['opkg', 'status']
    cmd.append(pkg)
    out = __salt__['cmd.run'](cmd, python_shell=False)
    state_flag = ''
    for line in salt.utils.itertools.split(out, '\n'):
        if line.startswith('Status'):
            _status, _state_want, state_flag, _state_status = line.split()

    return state_flag


Instruction:
Make a summary of the following Python 3 code
def _set_state(pkg, state):
    '''
    Change package state on the opkg database

    The state can be any of:

     - hold
     - noprune
     - user
     - ok
     - installed
     - unpacked

    This command is commonly used to mark a specific package to be held from
    being upgraded, that is, to be kept at a certain version.

    Returns a dict containing the package name, and the new and old
    versions.
    '''
    ret = {}
    valid_states = ('hold', 'noprune', 'user', 'ok', 'installed', 'unpacked')
    if state not in valid_states:
        raise SaltInvocationError('Invalid state: {0}'.format(state))
    oldstate = _get_state(pkg)
    cmd = ['opkg', 'flag']
    cmd.append(state)
    cmd.append(pkg)
    _out = __salt__['cmd.run'](cmd, python_shell=False)

    # Missing return value check due to opkg issue 160
    ret[pkg] = {'old': oldstate,
                'new': state}
    return ret

Response: Change the state of a specific package on the opkg database


Instruction:
Make a summary of the following Python 3 code
def list_upgrades(refresh=True, **kwargs):  # pylint: disable=unused-argument
    '''
    List all available package upgrades.

    CLI Example:

    .. code-block:: bash

        salt '*' pkg.list_upgrades
    '''
    ret = {}
    if salt.utils.data.is_true(refresh):
        refresh_db()

    cmd = ['opkg', 'list-upgradable']
    call = __salt__['cmd.run_all'](cmd,
                                   output_loglevel='trace',
                                   python_shell=False)

    if call['retcode'] != 0:
        comment = ''
        if 'stderr' in call:
            comment += call['stderr']
        if 'stdout' in call:
            comment += call['stdout']
        raise CommandExecutionError(comment)
    else:
        out = call['stdout']

    for line in out.splitlines():
        name, _oldversion, newversion = line.split(' - ')
        ret[name] = newversion

    return ret

Response: List all available package upgrades.


Instruction:
Can you tell what is the following Python 3 function doing
def _convert_to_standard_attr(attr):
    '''
    Helper function for _process_info_installed_output()

    Converts an opkg attribute name to a standard attribute
    name which is used across 'pkg' modules.
    '''
    ret_attr = ATTR_MAP.get(attr, None)
    if ret_attr is None:
        # All others convert to lowercase
        return attr.lower()
    return ret_attr

Response: Helper function for _process_info_installed_output() converts an opkg attribute name to a standard attribute name which is used across pkg modules.


Instruction:
Explain what the following Python 3 code does
def _process_info_installed_output(out, filter_attrs):
    '''
    Helper function for info_installed()

    Processes stdout output from a single invocation of
    'opkg status'.
    '''
    ret = {}
    name = None
    attrs = {}
    attr = None

    for line in salt.utils.itertools.split(out, '\n'):
        if line and line[0] == ' ':
            # This is a continuation of the last attr
            if filter_attrs is None or attr in filter_attrs:
                line = line.strip()
                if attrs[attr]:
                    # If attr is empty, don't add leading newline
                    attrs[attr] += '\n'
                attrs[attr] += line
            continue
        line = line.strip()
        if not line:
            # Separator between different packages
            if name:
                ret[name] = attrs
            name = None
            attrs = {}
            attr = None
            continue
        key, value = line.split(':', 1)
        value = value.lstrip()
        attr = _convert_to_standard_attr(key)
        if attr == 'name':
            name = value
        elif filter_attrs is None or attr in filter_attrs:
            attrs[attr] = value

    if name:
        ret[name] = attrs
    return ret

Response: Helper function for info_installed() processes the output from a single invocation of info_installed opkg status.


Instruction:
Write a Python 3 script to
return the information of the named packages installed on the system.

Response:
def info_installed(*names, **kwargs):
    '''
    Return the information of the named package(s), installed on the system.

    .. versionadded:: 2017.7.0

    :param names:
        Names of the packages to get information about. If none are specified,
        will return information for all installed packages.

    :param attr:
        Comma-separated package attributes. If no 'attr' is specified, all available attributes returned.

        Valid attributes are:
            arch, conffiles, conflicts, depends, description, filename, group,
            install_date_time_t, md5sum, packager, provides, recommends,
            replaces, size, source, suggests, url, version

    CLI example:

    .. code-block:: bash

        salt '*' pkg.info_installed
        salt '*' pkg.info_installed attr=version,packager
        salt '*' pkg.info_installed <package1>
        salt '*' pkg.info_installed <package1> <package2> <package3> ...
        salt '*' pkg.info_installed <package1> attr=version,packager
        salt '*' pkg.info_installed <package1> <package2> <package3> ... attr=version,packager
    '''
    attr = kwargs.pop('attr', None)
    if attr is None:
        filter_attrs = None
    elif isinstance(attr, six.string_types):
        filter_attrs = set(attr.split(','))
    else:
        filter_attrs = set(attr)

    ret = {}
    if names:
        # Specific list of names of installed packages
        for name in names:
            cmd = ['opkg', 'status', name]
            call = __salt__['cmd.run_all'](cmd,
                                           output_loglevel='trace',
                                           python_shell=False)
            if call['retcode'] != 0:
                comment = ''
                if call['stderr']:
                    comment += call['stderr']
                else:
                    comment += call['stdout']

                raise CommandExecutionError(comment)
            ret.update(_process_info_installed_output(call['stdout'], filter_attrs))
    else:
        # All installed packages
        cmd = ['opkg', 'status']
        call = __salt__['cmd.run_all'](cmd,
                                       output_loglevel='trace',
                                       python_shell=False)
        if call['retcode'] != 0:
            comment = ''
            if call['stderr']:
                comment += call['stderr']
            else:
                comment += call['stdout']

            raise CommandExecutionError(comment)
        ret.update(_process_info_installed_output(call['stdout'], filter_attrs))

    return ret


Instruction:
Write a Python 3 function for
comparing two packages and return the version of the first one.

Response:
def version_cmp(pkg1, pkg2, ignore_epoch=False, **kwargs):  # pylint: disable=unused-argument
    '''
    Do a cmp-style comparison on two packages. Return -1 if pkg1 < pkg2, 0 if
    pkg1 == pkg2, and 1 if pkg1 > pkg2. Return None if there was a problem
    making the comparison.

    ignore_epoch : False
        Set to ``True`` to ignore the epoch when comparing versions

        .. versionadded:: 2016.3.4

    CLI Example:

    .. code-block:: bash

        salt '*' pkg.version_cmp '0.2.4-0' '0.2.4.1-0'
    '''
    normalize = lambda x: six.text_type(x).split(':', 1)[-1] if ignore_epoch else six.text_type(x)
    pkg1 = normalize(pkg1)
    pkg2 = normalize(pkg2)

    output = __salt__['cmd.run_stdout'](['opkg', '--version'],
                                        output_loglevel='trace',
                                        python_shell=False)
    opkg_version = output.split(' ')[2].strip()
    if salt.utils.versions.LooseVersion(opkg_version) >= \
            salt.utils.versions.LooseVersion('0.3.4'):
        cmd_compare = ['opkg', 'compare-versions']
    elif salt.utils.path.which('opkg-compare-versions'):
        cmd_compare = ['opkg-compare-versions']
    else:
        log.warning('Unable to find a compare-versions utility installed. Either upgrade opkg to '
                    'version > 0.3.4 (preferred) or install the older opkg-compare-versions script.')
        return None

    for oper, ret in (("<<", -1), ("=", 0), (">>", 1)):
        cmd = cmd_compare[:]
        cmd.append(_cmd_quote(pkg1))
        cmd.append(oper)
        cmd.append(_cmd_quote(pkg2))
        retcode = __salt__['cmd.retcode'](cmd,
                                          output_loglevel='trace',
                                          ignore_retcode=True,
                                          python_shell=False)
        if retcode == 0:
            return ret
    return None


Instruction:
Can you write a function in Python 3 where it
sets the option to repo

Response:
def _set_repo_option(repo, option):
    '''
    Set the option to repo
    '''
    if not option:
        return
    opt = option.split('=')
    if len(opt) != 2:
        return
    if opt[0] == 'trusted':
        repo['trusted'] = opt[1] == 'yes'
    else:
        repo[opt[0]] = opt[1]


Instruction:
Given the following Python 3 function, write the documentation
def _set_repo_options(repo, options):
    '''
    Set the options to the repo.
    '''
    delimiters = "[", "]"
    pattern = '|'.join(map(re.escape, delimiters))
    for option in options:
        splitted = re.split(pattern, option)
        for opt in splitted:
            _set_repo_option(repo, opt)

Response: Set the options to the repo.


Instruction:
Can you tell what is the following Python 3 function doing
def _create_repo(line, filename):
    '''
    Create repo
    '''
    repo = {}
    if line.startswith('#'):
        repo['enabled'] = False
        line = line[1:]
    else:
        repo['enabled'] = True
    cols = salt.utils.args.shlex_split(line.strip())
    repo['compressed'] = not cols[0] in 'src'
    repo['name'] = cols[1]
    repo['uri'] = cols[2]
    repo['file'] = os.path.join(OPKG_CONFDIR, filename)
    if len(cols) > 3:
        _set_repo_options(repo, cols[3:])
    return repo

Response: Create repo dict from line


Instruction:
Make a summary of the following Python 3 code
def _read_repos(conf_file, repos, filename, regex):
    '''
    Read repos from configuration file
    '''
    for line in conf_file:
        line = salt.utils.stringutils.to_unicode(line)
        if not regex.search(line):
            continue
        repo = _create_repo(line, filename)

        # do not store duplicated uri's
        if repo['uri'] not in repos:
            repos[repo['uri']] = [repo]

Response: Read repos from configuration file


Instruction:
Make a summary of the following Python 3 code
def list_repos(**kwargs):  # pylint: disable=unused-argument
    '''
    Lists all repos on ``/etc/opkg/*.conf``

    CLI Example:

    .. code-block:: bash

       salt '*' pkg.list_repos
    '''
    repos = {}
    regex = re.compile(REPO_REGEXP)
    for filename in os.listdir(OPKG_CONFDIR):
        if not filename.endswith(".conf"):
            continue
        with salt.utils.files.fopen(os.path.join(OPKG_CONFDIR, filename)) as conf_file:
            _read_repos(conf_file, repos, filename, regex)
    return repos

Response: Lists all repos on the OPKG. conf dir


Instruction:
Can you generate the documentation for the following Python 3 function
def get_repo(repo, **kwargs):  # pylint: disable=unused-argument
    '''
    Display a repo from the ``/etc/opkg/*.conf``

    CLI Examples:

    .. code-block:: bash

        salt '*' pkg.get_repo repo
    '''
    repos = list_repos()

    if repos:
        for source in six.itervalues(repos):
            for sub in source:
                if sub['name'] == repo:
                    return sub
    return {}

Response: Display a repo from the system


Instruction:
Can you generate the documentation for the following Python 3 function
def _del_repo_from_file(repo, filepath):
    '''
    Remove a repo from filepath
    '''
    with salt.utils.files.fopen(filepath) as fhandle:
        output = []
        regex = re.compile(REPO_REGEXP)
        for line in fhandle:
            line = salt.utils.stringutils.to_unicode(line)
            if regex.search(line):
                if line.startswith('#'):
                    line = line[1:]
                cols = salt.utils.args.shlex_split(line.strip())
                if repo != cols[1]:
                    output.append(salt.utils.stringutils.to_str(line))
    with salt.utils.files.fopen(filepath, 'w') as fhandle:
        fhandle.writelines(output)

Response: Remove a repo from filepath


Instruction:
Given the following Python 3 function, write the documentation
def _set_trusted_option_if_needed(repostr, trusted):
    '''
    Set trusted option to repo if needed
    '''
    if trusted is True:
        repostr += ' [trusted=yes]'
    elif trusted is False:
        repostr += ' [trusted=no]'
    return repostr

Response: Sets trusted option to repo if needed


Instruction:
How would you explain what the following Python 3 function does
def _add_new_repo(repo, properties):
    '''
    Add a new repo entry
    '''
    repostr = '# ' if not properties.get('enabled') else ''
    repostr += 'src/gz ' if properties.get('compressed') else 'src '
    if ' ' in repo:
        repostr += '"' + repo + '" '
    else:
        repostr += repo + ' '
    repostr += properties.get('uri')
    repostr = _set_trusted_option_if_needed(repostr, properties.get('trusted'))
    repostr += '\n'
    conffile = os.path.join(OPKG_CONFDIR, repo + '.conf')

    with salt.utils.files.fopen(conffile, 'a') as fhandle:
        fhandle.write(salt.utils.stringutils.to_str(repostr))

Response: Add a new repo entry


Instruction:
Here you have a function in Python 3, explain what it does
def _mod_repo_in_file(repo, repostr, filepath):
    '''
    Replace a repo entry in filepath with repostr
    '''
    with salt.utils.files.fopen(filepath) as fhandle:
        output = []
        for line in fhandle:
            cols = salt.utils.args.shlex_split(
                salt.utils.stringutils.to_unicode(line).strip()
            )
            if repo not in cols:
                output.append(line)
            else:
                output.append(salt.utils.stringutils.to_str(repostr + '\n'))
    with salt.utils.files.fopen(filepath, 'w') as fhandle:
        fhandle.writelines(output)

Response: Replace a repo entry in filepath with repostr


Instruction:
Can you generate the documentation for the following Python 3 function
def del_repo(repo, **kwargs):  # pylint: disable=unused-argument
    '''
    Delete a repo from ``/etc/opkg/*.conf``

    If the file does not contain any other repo configuration, the file itself
    will be deleted.

    CLI Examples:

    .. code-block:: bash

        salt '*' pkg.del_repo repo
    '''
    refresh = salt.utils.data.is_true(kwargs.get('refresh', True))
    repos = list_repos()
    if repos:
        deleted_from = dict()
        for repository in repos:
            source = repos[repository][0]
            if source['name'] == repo:
                deleted_from[source['file']] = 0
                _del_repo_from_file(repo, source['file'])

        if deleted_from:
            ret = ''
            for repository in repos:
                source = repos[repository][0]
                if source['file'] in deleted_from:
                    deleted_from[source['file']] += 1
            for repo_file, count in six.iteritems(deleted_from):
                msg = 'Repo \'{0}\' has been removed from {1}.\n'
                if count == 1 and os.path.isfile(repo_file):
                    msg = ('File {1} containing repo \'{0}\' has been '
                           'removed.\n')
                    try:
                        os.remove(repo_file)
                    except OSError:
                        pass
                ret += msg.format(repo, repo_file)
            if refresh:
                refresh_db()
            return ret

    return "Repo {0} doesn't exist in the opkg repo lists".format(repo)

Response: Delete a repo from the opkg repo lists


Instruction:
Explain what the following Python 3 code does
def mod_repo(repo, **kwargs):
    '''
    Modify one or more values for a repo.  If the repo does not exist, it will
    be created, so long as uri is defined.

    The following options are available to modify a repo definition:

    repo
        alias by which opkg refers to the repo.
    uri
        the URI to the repo.
    compressed
        defines (True or False) if the index file is compressed
    enabled
        enable or disable (True or False) repository
        but do not remove if disabled.
    refresh
        enable or disable (True or False) auto-refresh of the repositories

    CLI Examples:

    .. code-block:: bash

        salt '*' pkg.mod_repo repo uri=http://new/uri
        salt '*' pkg.mod_repo repo enabled=False
    '''
    repos = list_repos()
    found = False
    uri = ''
    if 'uri' in kwargs:
        uri = kwargs['uri']

    for repository in repos:
        source = repos[repository][0]
        if source['name'] == repo:
            found = True
            repostr = ''
            if 'enabled' in kwargs and not kwargs['enabled']:
                repostr += '# '
            if 'compressed' in kwargs:
                repostr += 'src/gz ' if kwargs['compressed'] else 'src'
            else:
                repostr += 'src/gz' if source['compressed'] else 'src'
            repo_alias = kwargs['alias'] if 'alias' in kwargs else repo
            if ' ' in repo_alias:
                repostr += ' "{0}"'.format(repo_alias)
            else:
                repostr += ' {0}'.format(repo_alias)
            repostr += ' {0}'.format(kwargs['uri'] if 'uri' in kwargs else source['uri'])
            trusted = kwargs.get('trusted')
            repostr = _set_trusted_option_if_needed(repostr, trusted) if trusted is not None else \
                _set_trusted_option_if_needed(repostr, source.get('trusted'))
            _mod_repo_in_file(repo, repostr, source['file'])
        elif uri and source['uri'] == uri:
            raise CommandExecutionError(
                'Repository \'{0}\' already exists as \'{1}\'.'.format(uri, source['name']))

    if not found:
        # Need to add a new repo
        if 'uri' not in kwargs:
            raise CommandExecutionError(
                'Repository \'{0}\' not found and no URI passed to create one.'.format(repo))
        properties = {'uri': kwargs['uri']}
        # If compressed is not defined, assume True
        properties['compressed'] = kwargs['compressed'] if 'compressed' in kwargs else True
        # If enabled is not defined, assume True
        properties['enabled'] = kwargs['enabled'] if 'enabled' in kwargs else True
        properties['trusted'] = kwargs.get('trusted')
        _add_new_repo(repo, properties)

    if 'refresh' in kwargs:
        refresh_db()

Response: Modify one or more values for a repo.


Instruction:
Can you write a function in Python 3 where it
lists the files that belong to a package. Not specifying any packages will return a list of _every_ file on the system's package database (not generally recommended). CLI Examples: .. code-block:: bash salt '*' pkg.file_list httpd salt '*' pkg.file_list httpd postfix salt '*' pkg.file_list

Response:
def file_list(*packages, **kwargs):  # pylint: disable=unused-argument
    '''
    List the files that belong to a package. Not specifying any packages will
    return a list of _every_ file on the system's package database (not
    generally recommended).

    CLI Examples:

    .. code-block:: bash

        salt '*' pkg.file_list httpd
        salt '*' pkg.file_list httpd postfix
        salt '*' pkg.file_list
    '''
    output = file_dict(*packages)
    files = []
    for package in list(output['packages'].values()):
        files.extend(package)
    return {'errors': output['errors'], 'files': files}


Instruction:
Implement a function in Python 3 to
return a dict of all files in a package.

Response:
def file_dict(*packages, **kwargs):  # pylint: disable=unused-argument
    '''
    List the files that belong to a package, grouped by package. Not
    specifying any packages will return a list of _every_ file on the system's
    package database (not generally recommended).

    CLI Examples:

    .. code-block:: bash

        salt '*' pkg.file_list httpd
        salt '*' pkg.file_list httpd postfix
        salt '*' pkg.file_list
    '''
    errors = []
    ret = {}
    cmd_files = ['opkg', 'files']

    if not packages:
        packages = list(list_pkgs().keys())

    for package in packages:
        files = []
        cmd = cmd_files[:]
        cmd.append(package)
        out = __salt__['cmd.run_all'](cmd,
                                      output_loglevel='trace',
                                      python_shell=False)
        for line in out['stdout'].splitlines():
            if line.startswith('/'):
                files.append(line)
            elif line.startswith(' * '):
                errors.append(line[3:])
                break
            else:
                continue
        if files:
            ret[package] = files

    return {'errors': errors, 'packages': ret}


Instruction:
Write a Python 3 function for
returning the name of the package that owns the file. Multiple file paths can be passed.

Response:
def owner(*paths, **kwargs):  # pylint: disable=unused-argument
    '''
    Return the name of the package that owns the file. Multiple file paths can
    be passed. Like :mod:`pkg.version <salt.modules.opkg.version`, if a single
    path is passed, a string will be returned, and if multiple paths are passed,
    a dictionary of file/package name pairs will be returned.

    If the file is not owned by a package, or is not present on the minion,
    then an empty string will be returned for that path.

    CLI Example:

        salt '*' pkg.owner /usr/bin/apachectl
        salt '*' pkg.owner /usr/bin/apachectl /usr/bin/basename
    '''
    if not paths:
        return ''
    ret = {}
    cmd_search = ['opkg', 'search']
    for path in paths:
        cmd = cmd_search[:]
        cmd.append(path)
        output = __salt__['cmd.run_stdout'](cmd,
                                            output_loglevel='trace',
                                            python_shell=False)
        if output:
            ret[path] = output.split(' - ')[0].strip()
        else:
            ret[path] = ''
    if len(ret) == 1:
        return next(six.itervalues(ret))
    return ret