Instruction:
Given the following Python 3 function, write the documentation
def get_ip_scope_hosts( scopeId, auth, url):
    get_ip_scope_url = "/imcrs/res/access/assignedIpScope/ip?size=10000&ipScopeId="+str(scopeId)
    f_url = url + get_ip_scope_url
    r = requests.get(f_url, auth=auth, headers=HEADERS)  # creates the URL using the payload variable as the contents
    try:
        if r.status_code == 200:
            ipscopelist = (json.loads(r.text))
            if ipscopelist == {}:
                return ipscopelist
            else: ipscopelist = ipscopelist['assignedIpInfo']
            if type(ipscopelist) is dict:
                ipscope = []
                ipscope.append(ipscopelist)
                return ipscope
            return ipscopelist
    except requests.exceptions.RequestException as e:
            return "Error:\n" + str(e) + " get_ip_scope: An Error has occured"

Response: Function returns list of allocated IP address for the specified scope


Instruction:
Explain what the following Python 3 code does
def add_host_to_segment(ipaddress, name, description, network_address, auth, url):
    ''' Function to abstract existing add_scope_ip_function. Allows for use of network address rather than forcing human
    to learn the scope_id
    :param ipaddress:

    :param name: name of the owner of this host

    :param description: Description of the host

    :param: network_address: network address of the target scope in format x.x.x.x/yy  where x.x.x.x representents the
    network address and yy represents the length of the subnet mask.  Example:  10.50.0.0 255.255.255.0 would be written
    as 10.50.0.0/24

    :param auth: requests auth object #usually auth.creds from auth pyhpeimc.auth.class

    :param url: base url of IMC RS interface #usually auth.url from pyhpeimc.auth.authclass

    :return:

    :rtype:

    '''
    scope_id = get_scope_id(network_address, auth, url)
    add_scope_ip(ipaddress, name, description, scope_id, auth,url)

Response:
Function to abstract existing add_scope_ip_function. Allows for use of network address rather than forcing human
    to learn the scope_id


Instruction:
Can you tell what is the following Python 3 function doing
def delete_host_from_segment(ipaddress, networkaddress, auth, url):
    '''Function to abstract

    '''
    host_id = get_host_id(ipaddress, networkaddress, auth, url)
    remove_scope_ip(host_id, auth.creds, auth.url)

Response:
Function to abstract
    remove host from segment


Instruction:
Here you have a function in Python 3, explain what it does
def generate_signature(method, version, endpoint,
                       date, rel_url, content_type, content,
                       access_key, secret_key, hash_type):
    '''
    Generates the API request signature from the given parameters.
    '''
    hash_type = hash_type
    hostname = endpoint._val.netloc  # FIXME: migrate to public API
    if version >= 'v4.20181215':
        content = b''
    else:
        if content_type.startswith('multipart/'):
            content = b''
    body_hash = hashlib.new(hash_type, content).hexdigest()

    sign_str = '{}\n{}\n{}\nhost:{}\ncontent-type:{}\nx-backendai-version:{}\n{}'.format(  # noqa
        method.upper(),
        rel_url,
        date.isoformat(),
        hostname,
        content_type.lower(),
        version,
        body_hash
    )
    sign_bytes = sign_str.encode()

    sign_key = hmac.new(secret_key.encode(),
                        date.strftime('%Y%m%d').encode(), hash_type).digest()
    sign_key = hmac.new(sign_key, hostname.encode(), hash_type).digest()

    signature = hmac.new(sign_key, sign_bytes, hash_type).hexdigest()
    headers = {
        'Authorization': 'BackendAI signMethod=HMAC-{}, credential={}:{}'.format(
            hash_type.upper(),
            access_key,
            signature
        ),
    }
    return headers, signature

Response: Generates the API request signature from the given parameters.


Instruction:
Write a Python 3 script to
fetch the list of agents with the given status with limit and offset for pagination.

Response:
async def list_with_limit(cls,
                              limit,
                              offset,
                              status: str = 'ALIVE',
                              fields: Iterable[str] = None) -> Sequence[dict]:
        '''
        Fetches the list of agents with the given status with limit and offset for
        pagination.

        :param limit: number of agents to get
        :param offset: offset index of agents to get
        :param status: An upper-cased string constant representing agent
            status (one of ``'ALIVE'``, ``'TERMINATED'``, ``'LOST'``,
            etc.)
        :param fields: Additional per-agent query fields to fetch.
        '''
        if fields is None:
            fields = (
                'id',
                'addr',
                'status',
                'first_contact',
                'mem_slots',
                'cpu_slots',
                'gpu_slots',
            )
        q = 'query($limit: Int!, $offset: Int!, $status: String) {' \
            '  agent_list(limit: $limit, offset: $offset, status: $status) {' \
            '   items { $fields }' \
            '   total_count' \
            '  }' \
            '}'
        q = q.replace('$fields', ' '.join(fields))
        variables = {
            'limit': limit,
            'offset': offset,
            'status': status,
        }
        rqst = Request(cls.session, 'POST', '/admin/graphql')
        rqst.set_json({
            'query': q,
            'variables': variables,
        })
        async with rqst.fetch() as resp:
            data = await resp.json()
            return data['agent_list']


Instruction:
Given the following Python 3 function, write the documentation
def set_content(self, value: RequestContent, *,
                    content_type: str = None):
        '''
        Sets the content of the request.
        '''
        assert self._attached_files is None, \
               'cannot set content because you already attached files.'
        guessed_content_type = 'application/octet-stream'
        if value is None:
            guessed_content_type = 'text/plain'
            self._content = b''
        elif isinstance(value, str):
            guessed_content_type = 'text/plain'
            self._content = value.encode('utf-8')
        else:
            guessed_content_type = 'application/octet-stream'
            self._content = value
        self.content_type = (content_type if content_type is not None
                             else guessed_content_type)

Response: Sets the content of the request.


Instruction:
Implement a function in Python 3 to
attach a list of files represented as AttachedFile.

Response:
def attach_files(self, files: Sequence[AttachedFile]):
        '''
        Attach a list of files represented as AttachedFile.
        '''
        assert not self._content, 'content must be empty to attach files.'
        self.content_type = 'multipart/form-data'
        self._attached_files = files


Instruction:
Create a Python 3 function to
calculate the signature of the request and adds it to the headers.

Response:
def _sign(self, rel_url, access_key=None, secret_key=None, hash_type=None):
        '''
        Calculates the signature of the given request and adds the
        Authorization HTTP header.
        It should be called at the very end of request preparation and before
        sending the request to the server.
        '''
        if access_key is None:
            access_key = self.config.access_key
        if secret_key is None:
            secret_key = self.config.secret_key
        if hash_type is None:
            hash_type = self.config.hash_type
        hdrs, _ = generate_signature(
            self.method, self.config.version, self.config.endpoint,
            self.date, str(rel_url), self.content_type, self._content,
            access_key, secret_key, hash_type)
        self.headers.update(hdrs)


Instruction:
Create a Python 3 function to
send a request to the server and reads the response.

Response:
def fetch(self, **kwargs) -> 'FetchContextManager':
        '''
        Sends the request to the server and reads the response.

        You may use this method either with plain synchronous Session or
        AsyncSession.  Both the followings patterns are valid:

        .. code-block:: python3

          from ai.backend.client.request import Request
          from ai.backend.client.session import Session

          with Session() as sess:
            rqst = Request(sess, 'GET', ...)
            with rqst.fetch() as resp:
              print(resp.text())

        .. code-block:: python3

          from ai.backend.client.request import Request
          from ai.backend.client.session import AsyncSession

          async with AsyncSession() as sess:
            rqst = Request(sess, 'GET', ...)
            async with rqst.fetch() as resp:
              print(await resp.text())
        '''
        assert self.method in self._allowed_methods, \
               'Disallowed HTTP method: {}'.format(self.method)
        self.date = datetime.now(tzutc())
        self.headers['Date'] = self.date.isoformat()
        if self.content_type is not None:
            self.headers['Content-Type'] = self.content_type
        full_url = self._build_url()
        self._sign(full_url.relative())
        rqst_ctx = self.session.aiohttp_session.request(
            self.method,
            str(full_url),
            data=self._pack_content(),
            timeout=_default_request_timeout,
            headers=self.headers)
        return FetchContextManager(self.session, rqst_ctx, **kwargs)


Instruction:
Here you have a function in Python 3, explain what it does
def connect_websocket(self, **kwargs) -> 'WebSocketContextManager':
        '''
        Creates a WebSocket connection.

        .. warning::

          This method only works with
          :class:`~ai.backend.client.session.AsyncSession`.
        '''
        assert isinstance(self.session, AsyncSession), \
               'Cannot use websockets with sessions in the synchronous mode'
        assert self.method == 'GET', 'Invalid websocket method'
        self.date = datetime.now(tzutc())
        self.headers['Date'] = self.date.isoformat()
        # websocket is always a "binary" stream.
        self.content_type = 'application/octet-stream'
        full_url = self._build_url()
        self._sign(full_url.relative())
        ws_ctx = self.session.aiohttp_session.ws_connect(
            str(full_url),
            autoping=True, heartbeat=30.0,
            headers=self.headers)
        return WebSocketContextManager(self.session, ws_ctx, **kwargs)

Response: Creates a WebSocket connection.


Instruction:
Can you tell what is the following Python 3 function doing
def add_perf_task(task, auth, url):
    add_perf_task_url = "/imcrs/perf/task"
    f_url = url + add_perf_task_url
    payload = json.dumps(task)
    response = requests.post(f_url, data=payload, auth=auth, headers=HEADERS)
    try:
        return response.status_code
    except requests.exceptions.RequestException as error:
        return "Error:\n" + str(error) + ' add_perf_task: An Error has occured'

Response: function adds a performance task to the device


Instruction:
Write a Python 3 script to
function takes a str object containing the name of an existing performance task and issues a RESTFUL call to the IMC REST service to get the performance task information.

Response:
def get_perf_task(task_name, auth, url):
    """
        function takes the a str object containing the name of an existing performance tasks and
        issues a RESTFUL call to the IMC REST service. It will return a list

        :param task_name: str containing the name of the performance task

        :param auth: requests auth object #usually auth.creds from auth pyhpeimc.auth.class

        :param url: base url of IMC RS interface #usually auth.url from pyhpeimc.auth.authclass

        :return: 204

        :rtype: dict

        >>> from pyhpeimc.auth import *

        >>> from pyhpeimc.plat.perf import *

        >>> auth = IMCAuth("http://", "10.101.0.203", "8080", "admin", "admin")

        >>> selected_task = get_perf_task('Cisco_Temperature', auth.creds, auth.url)

        >>> assert type(selected_task) is dict

        >>> assert 'taskName' in selected_task
        """
    get_perf_task_url = "/imcrs/perf/task?name=" + task_name + "&orderBy=taskId&desc=false"
    f_url = url + get_perf_task_url
    response = requests.get(f_url, auth=auth, headers=HEADERS)
    try:
        if response.status_code == 200:
            perf_task_info = (json.loads(response.text))
            if 'task' in perf_task_info:
                perf_task_info = (json.loads(response.text))['task']
            else:
                perf_task_info = "Task Doesn't Exist"
            return perf_task_info
    except requests.exceptions.RequestException as error:
        return "Error:\n" + str(error) + ' get_perf_task: An Error has occured'


Instruction:
Can you implement a function in Python 3 that
functions to delete a Perf Task from the IMC RS.

Response:
def delete_perf_task(task_name, auth, url):
    """
    Function takes a str of the target task_name to be deleted and retrieves task_id using
    the get_perf_task function. Once the task_id has been successfully retrieved it is
    populated into the task_id variable and an DELETE call is made against the HPE IMC REST
    interface to delete the target task.
    :param task_name: str of task name
    :param auth: requests auth object #usually auth.creds from auth pyhpeimc.auth.class

    :param url: base url of IMC RS interface #usually auth.url from pyhpeimc.auth.authclass

    :return: int of 204 if successful, str of "Perf Task doesn't exist" i

    :rtype: int

    """
    task_id = get_perf_task(task_name, auth, url)
    if isinstance(task_id, str):
        print("Perf task doesn't exist")
        return 403
    task_id = task_id['taskId']
    get_perf_task_url = "/imcrs/perf/task/delete/" + str(task_id)
    f_url = url + get_perf_task_url
    response = requests.delete(f_url, auth=auth, headers=HEADERS)
    try:
        if response.status_code == 204:
            print("Perf Task successfully delete")
            return response.status_code
    except requests.exceptions.RequestException as error:
        return "Error:\n" + str(error) + ' delete_perf_task: An Error has occured'


Instruction:
Can you implement a function in Python 3 that
processes a response from the API.

Response:
def process_json_response(self, response):
        """For a json response, check if there was any error and throw exception.
        Otherwise, create a housecanary.response.Response."""

        response_json = response.json()

        # handle errors
        code_key = "code"
        if code_key in response_json and response_json[code_key] != constants.HTTP_CODE_OK:
            code = response_json[code_key]

            message = response_json
            if "message" in response_json:
                message = response_json["message"]
            elif "code_description" in response_json:
                message = response_json["code_description"]

            if code == constants.HTTP_FORBIDDEN:
                raise housecanary.exceptions.UnauthorizedException(code, message)
            if code == constants.HTTP_TOO_MANY_REQUESTS:
                raise housecanary.exceptions.RateLimitException(code, message, response)
            else:
                raise housecanary.exceptions.RequestException(code, message)

        request_url = response.request.url

        endpoint_name = self._parse_endpoint_name_from_url(request_url)

        return Response.create(endpoint_name, response_json, response)


Instruction:
Explain what the following Python 3 code does
def start_watcher_thread(self):
        # Create watcher thread
        watcher_thread = threading.Thread(target=self.run_watcher)

        # If the reload mode is `spawn_wait`
        if self._reload_mode == self.RELOAD_MODE_V_SPAWN_WAIT:
            # Use non-daemon thread
            daemon = False

        # If the reload mode is not `spawn_wait`
        else:
            # Use daemon thread
            daemon = True

        # Set whether the thread is daemon
        watcher_thread.setDaemon(daemon)

        # Start watcher thread
        watcher_thread.start()

        # Return watcher thread
        return watcher_thread

Response: Start the watcher thread.


Instruction:
Make a summary of the following Python 3 code
def _find_watch_paths(self):
        # Add directory paths in `sys.path` to watch paths
        watch_path_s = set(os.path.abspath(x) for x in sys.path)

        # For each extra path
        for extra_path in self._extra_paths or ():
            # Get the extra path's directory path
            extra_dir_path = os.path.dirname(os.path.abspath(extra_path))

            # Add to watch paths
            watch_path_s.add(extra_dir_path)

        # For each module in `sys.modules`
        for module in list(sys.modules.values()):
            # Get module file path
            module_path = getattr(module, '__file__', None)

            # If have module file path
            if module_path is not None:
                # Get module directory path
                module_dir_path = os.path.dirname(os.path.abspath(module_path))

                # Add to watch paths
                watch_path_s.add(module_dir_path)

        # Find short paths of these watch paths.
        # E.g. if both `/home` and `/home/aoik` exist, only keep `/home`.
        watch_path_s = self._find_short_paths(watch_path_s)

        # Return the watch paths
        return watch_path_s

Response: Find paths to watch.


Instruction:
Explain what the following Python 3 code does
def _find_short_paths(self, paths):
        # Split each path to parts.
        # E.g. '/home/aoik' to ['', 'home', 'aoik']
        path_parts_s = [path.split(os.path.sep) for path in paths]

        # Root node
        root_node = {}

        # Sort these path parts by length, with the longest being the first.
        #
        # Longer paths appear first so that their extra parts are discarded
        # when a shorter path is found at 5TQ8L.
        #
        # Then for each path's parts.
        for parts in sorted(path_parts_s, key=len, reverse=True):
            # Start from the root node
            node = root_node

            # For each part of the path
            for part in parts:
                # Create node of the path
                node = node.setdefault(part, {})

            # 5TQ8L
            # Clear the last path part's node's child nodes.
            #
            # This aims to keep only the shortest path that needs be watched.
            #
            node.clear()

        # Short paths
        short_path_s = set()

        # Collect leaf paths
        self._collect_leaf_paths(
            node=root_node,
            path_parts=(),
            leaf_paths=short_path_s,
        )

        # Return short paths
        return short_path_s

Response: Find short paths of given paths.


Instruction:
Can you write a function in Python 3 where it
collects paths of leaf nodes. :param node: Starting node. Type is dict. Key is child node's path part. Value is child node. :param path_parts: The starting node's path parts. Type is tuple. :param leaf_paths: Leaf path list. :return: None.

Response:
def _collect_leaf_paths(self, node, path_parts, leaf_paths):
        """
        Collect paths of leaf nodes.

        :param node:
            Starting node. Type is dict.

            Key is child node's path part. Value is child node.

        :param path_parts:
            The starting node's path parts. Type is tuple.

        :param leaf_paths:
            Leaf path list.

        :return:
            None.
        """
        # If the node is leaf node
        if not node:
            # Get node path
            node_path = '/'.join(path_parts)

            # Add to list
            leaf_paths.add(node_path)

        # If the node is not leaf node
        else:
            # For each child node
            for child_path_part, child_node in node.items():
                # Get the child node's path parts
                child_path_part_s = path_parts + (child_path_part,)

                # Visit the child node
                self._collect_leaf_paths(
                    node=child_node,
                    path_parts=child_path_part_s,
                    leaf_paths=leaf_paths,
                )


Instruction:
Given the following Python 3 function, write the documentation
def dispatch(self, event):
        # Get file path
        file_path = event.src_path

        # If the file path is in extra paths
        if file_path in self._extra_paths:
            # Call `reload`
            self.reload()

        # If the file path ends with `.pyc` or `.pyo`
        if file_path.endswith(('.pyc', '.pyo')):
            # Get `.py` file path
            file_path = file_path[:-1]

        # If the file path ends with `.py`
        if file_path.endswith('.py'):
            # Get the file's directory path
            file_dir = os.path.dirname(file_path)

            # If the file's directory path starts with any of the watch paths
            if file_dir.startswith(tuple(self._watch_paths)):
                # Call `reload`
                self.reload()

Response: Dispatches the event object.


Instruction:
Can you tell what is the following Python 3 function doing
def reload(self):
        # Get reload mode
        reload_mode = self._reload_mode

        # If reload mode is `exec`
        if self._reload_mode == self.RELOAD_MODE_V_EXEC:
            # Call `reload_using_exec`
            self.reload_using_exec()

        # If reload mode is `spawn_exit`
        elif self._reload_mode == self.RELOAD_MODE_V_SPAWN_EXIT:
            # Call `reload_using_spawn_exit`
            self.reload_using_spawn_exit()

        # If reload mode is `spawn_wait`
        elif self._reload_mode == self.RELOAD_MODE_V_SPAWN_WAIT:
            # Call `reload_using_spawn_wait`
            self.reload_using_spawn_wait()

        # If reload mode is none of above
        else:
            # Get error message
            error_msg = 'Invalid reload mode: {}.'.format(repr(reload_mode))

            # Raise error
            raise ValueError(error_msg)

Response:
Reload the program.

        :return:
            None.


Instruction:
Implement a Python 3 function for
reloading the program process using the executable.

Response:
def reload_using_exec(self):
        """
        Reload the program process.

        :return:
            None.
        """
        # Create command parts
        cmd_parts = [sys.executable] + sys.argv

        # Get env dict copy
        env_copy = os.environ.copy()

        # Reload the program process
        os.execvpe(
            # Program file path
            sys.executable,
            # Command parts
            cmd_parts,
            # Env dict
            env_copy,
        )


Instruction:
Can you create a Python 3 function that
spawns a subprocess and exit the current process.

Response:
def reload_using_spawn_exit(self):
        """
        Spawn a subprocess and exit the current process.

        :return:
            None.
        """
        # Create command parts
        cmd_parts = [sys.executable] + sys.argv

        # Get env dict copy
        env_copy = os.environ.copy()

        # Spawn subprocess
        subprocess.Popen(cmd_parts, env=env_copy, close_fds=True)

        # If need force exit
        if self._force_exit:
            # Force exit
            os._exit(0)  # pylint: disable=protected-access

        # If not need force exit
        else:
            # Send interrupt to main thread
            interrupt_main()

        # Set the flag
        self._watcher_to_stop = True

        # Exit the watcher thread
        sys.exit(0)


Instruction:
Can you create a Python 3 function that
spawns a subprocess and wait until it finishes.

Response:
def reload_using_spawn_wait(self):
        """
        Spawn a subprocess and wait until it finishes.

        :return:
            None.
        """
        # Create command parts
        cmd_parts = [sys.executable] + sys.argv

        # Get env dict copy
        env_copy = os.environ.copy()

        # Send interrupt to main thread
        interrupt_main()

        # Spawn subprocess and wait until it finishes
        subprocess.call(cmd_parts, env=env_copy, close_fds=True)

        # Exit the watcher thread
        sys.exit(0)


Instruction:
Make a summary of the following Python 3 code
def agent(agent_id):
    '''
    Show the information about the given agent.
    '''
    fields = [
        ('ID', 'id'),
        ('Status', 'status'),
        ('Region', 'region'),
        ('First Contact', 'first_contact'),
        ('CPU Usage (%)', 'cpu_cur_pct'),
        ('Used Memory (MiB)', 'mem_cur_bytes'),
        ('Total slots', 'available_slots'),
        ('Occupied slots', 'occupied_slots'),
    ]
    if is_legacy_server():
        del fields[9]
        del fields[6]
    q = 'query($agent_id:String!) {' \
        '  agent(agent_id:$agent_id) { $fields }' \
        '}'
    q = q.replace('$fields', ' '.join(item[1] for item in fields))
    v = {'agent_id': agent_id}
    with Session() as session:
        try:
            resp = session.Admin.query(q, v)
        except Exception as e:
            print_error(e)
            sys.exit(1)
        info = resp['agent']
        rows = []
        for name, key in fields:
            if key == 'mem_cur_bytes' and info[key] is not None:
                info[key] = round(info[key] / 2 ** 20, 1)
            if key in info:
                rows.append((name, info[key]))
        print(tabulate(rows, headers=('Field', 'Value')))

Response: Show the information about the given agent.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def agents(status, all):
    '''
    List and manage agents.
    (admin privilege required)
    '''
    fields = [
        ('ID', 'id'),
        ('Status', 'status'),
        ('Region', 'region'),
        ('First Contact', 'first_contact'),
        ('CPU Usage (%)', 'cpu_cur_pct'),
        ('Used Memory (MiB)', 'mem_cur_bytes'),
        ('Total slots', 'available_slots'),
        ('Occupied slots', 'occupied_slots'),
    ]
    if is_legacy_server():
        del fields[9]
        del fields[6]

    def execute_paginated_query(limit, offset):
        try:
            resp_agents = session.Agent.list_with_limit(
                limit, offset, status, fields=(item[1] for item in fields))
        except Exception as e:
            print_error(e)
            sys.exit(1)
        return resp_agents

    def round_mem(results):
        for item in results:
            if 'mem_cur_bytes' in item and item['mem_cur_bytes'] is not None:
                item['mem_cur_bytes'] = round(item['mem_cur_bytes'] / 2 ** 20, 1)
        return results

    def _generate_paginated_results(interval):
        offset = 0
        is_first = True
        total_count = -1
        while True:
            limit = (interval if is_first else
                    min(interval, total_count - offset))
            try:
                result = execute_paginated_query(limit, offset)
            except Exception as e:
                print_error(e)
                sys.exit(1)
            offset += interval
            total_count = result['total_count']
            items = result['items']
            items = round_mem(items)
            table = tabulate((item.values() for item in items),
                                headers=(item[0] for item in fields))
            if is_first:
                is_first = False
            else:
                table_rows = table.split('\n')
                table = '\n'.join(table_rows[2:])
            yield table + '\n'

            if not offset < total_count:
                break

    with Session() as session:
        paginating_interval = 10
        if all:
            click.echo_via_pager(_generate_paginated_results(paginating_interval))
        else:
            result = execute_paginated_query(paginating_interval, offset=0)
            total_count = result['total_count']
            if total_count == 0:
                print('There are no matching agents.')
                return
            items = result['items']
            items = round_mem(items)
            fields = [field for field in fields if field[1] in items[0]]
            print(tabulate((item.values() for item in items),
                            headers=(item[0] for item in fields)))
            if total_count > paginating_interval:
                print("More agents can be displayed by using --all option.")

Response: Return a list of agents with the given status and all if all is True.


Instruction:
How would you code a function in Python 3 to
show details about a keypair resource policy.

Response:
def resource_policy(name):
    """
    Show details about a keypair resource policy. When `name` option is omitted, the
    resource policy for the current access_key will be returned.
    """
    fields = [
        ('Name', 'name'),
        ('Created At', 'created_at'),
        ('Default for Unspecified', 'default_for_unspecified'),
        ('Total Resource Slot', 'total_resource_slots'),
        ('Max Concurrent Sessions', 'max_concurrent_sessions'),
        ('Max Containers per Session', 'max_containers_per_session'),
        ('Max vFolder Count', 'max_vfolder_count'),
        ('Max vFolder Size', 'max_vfolder_size'),
        ('Idle Timeeout', 'idle_timeout'),
        ('Allowed vFolder Hosts', 'allowed_vfolder_hosts'),
    ]
    with Session() as session:
        try:
            rp = session.ResourcePolicy(session.config.access_key)
            info = rp.info(name, fields=(item[1] for item in fields))
        except Exception as e:
            print_error(e)
            sys.exit(1)
        rows = []
        if info is None:
            print('No such resource policy.')
            sys.exit(1)
        for name, key in fields:
            rows.append((name, info[key]))
        print(tabulate(rows, headers=('Field', 'Value')))


Instruction:
Can you tell what is the following Python 3 function doing
def resource_policies(ctx):
    '''
    List and manage resource policies.
    (admin privilege required)
    '''
    if ctx.invoked_subcommand is not None:
        return
    fields = [
        ('Name', 'name'),
        ('Created At', 'created_at'),
        ('Default for Unspecified', 'default_for_unspecified'),
        ('Total Resource Slot', 'total_resource_slots'),
        ('Max Concurrent Sessions', 'max_concurrent_sessions'),
        ('Max Containers per Session', 'max_containers_per_session'),
        ('Max vFolder Count', 'max_vfolder_count'),
        ('Max vFolder Size', 'max_vfolder_size'),
        ('Idle Timeeout', 'idle_timeout'),
        ('Allowed vFolder Hosts', 'allowed_vfolder_hosts'),
    ]
    with Session() as session:
        try:
            items = session.ResourcePolicy.list(fields=(item[1] for item in fields))
        except Exception as e:
            print_error(e)
            sys.exit(1)
        if len(items) == 0:
            print('There are no keypair resource policies.')
            return
        print(tabulate((item.values() for item in items),
                       headers=(item[0] for item in fields)))

Response: List and manage resource policies.


Instruction:
Create a Python 3 function to
add a new keypair resource policy.

Response:
def add(name, default_for_unspecified, total_resource_slots, max_concurrent_sessions,
        max_containers_per_session, max_vfolder_count, max_vfolder_size,
        idle_timeout, allowed_vfolder_hosts):
    '''
    Add a new keypair resource policy.

    NAME: NAME of a new keypair resource policy.
    '''
    with Session() as session:
        try:
            data = session.ResourcePolicy.create(
                name,
                default_for_unspecified=default_for_unspecified,
                total_resource_slots=total_resource_slots,
                max_concurrent_sessions=max_concurrent_sessions,
                max_containers_per_session=max_containers_per_session,
                max_vfolder_count=max_vfolder_count,
                max_vfolder_size=max_vfolder_size,
                idle_timeout=idle_timeout,
                allowed_vfolder_hosts=allowed_vfolder_hosts,
            )
        except Exception as e:
            print_error(e)
            sys.exit(1)
        if not data['ok']:
            print_fail('KeyPair Resource Policy creation has failed: {0}'
                       .format(data['msg']))
            sys.exit(1)
        item = data['resource_policy']
        print('Keypair resource policy ' + item['name'] + ' is created.')


Instruction:
Create a Python 3 function to
delete a keypair resource policy.

Response:
def delete(name):
    """
    Delete a keypair resource policy.

    NAME: NAME of a keypair resource policy to delete.
    """
    with Session() as session:
        if input('Are you sure? (y/n): ').lower().strip()[:1] != 'y':
            print('Canceled.')
            sys.exit(1)
        try:
            data = session.ResourcePolicy.delete(name)
        except Exception as e:
            print_error(e)
            sys.exit(1)
        if not data['ok']:
            print_fail('KeyPair Resource Policy deletion has failed: {0}'
                       .format(data['msg']))
            sys.exit(1)
        print('Resource policy ' + name + ' is deleted.')


Instruction:
Write a Python 3 script to
run a local proxy to a service provided by Backend.AI compute sessions. The type of proxy depends on the app definition: plain TCP or HTTP. \b SESSID: The compute session ID. APP: The name of service provided by the given session.

Response:
def app(session_id, app, bind, port):
    """
    Run a local proxy to a service provided by Backend.AI compute sessions.

    The type of proxy depends on the app definition: plain TCP or HTTP.

    \b
    SESSID: The compute session ID.
    APP: The name of service provided by the given session.
    """
    api_session = None
    runner = None

    async def app_setup():
        nonlocal api_session, runner
        loop = current_loop()
        api_session = AsyncSession()
        # TODO: generalize protocol using service ports metadata
        protocol = 'http'
        runner = ProxyRunner(api_session, session_id, app,
                             protocol, bind, port,
                             loop=loop)
        await runner.ready()
        print_info(
            "A local proxy to the application \"{0}\" ".format(app) +
            "provided by the session \"{0}\" ".format(session_id) +
            "is available at: {0}://{1}:{2}"
            .format(protocol, bind, port)
        )

    async def app_shutdown():
        nonlocal api_session, runner
        print_info("Shutting down....")
        await runner.close()
        await api_session.close()
        print_info("The local proxy to \"{}\" has terminated."
                   .format(app))

    asyncio_run_forever(app_setup(), app_shutdown(),
                        stop_signals={signal.SIGINT, signal.SIGTERM})


Instruction:
Write a Python 3 function that can
retrieve a configuration value from the environment variables.

Response:
def get_env(key: str,
            default: Any = None,
            clean: Callable[[str], Any] = lambda v: v):
    '''
    Retrieves a configuration value from the environment variables.
    The given *key* is uppercased and prefixed by ``"BACKEND_"`` and then
    ``"SORNA_"`` if the former does not exist.

    :param key: The key name.
    :param default: The default value returned when there is no corresponding
        environment variable.
    :param clean: A single-argument function that is applied to the result of lookup
        (in both successes and the default value for failures).
        The default is returning the value as-is.

    :returns: The value processed by the *clean* function.
    '''
    key = key.upper()
    v = os.environ.get('BACKEND_' + key)
    if v is None:
        v = os.environ.get('SORNA_' + key)
    if v is None:
        if default is None:
            raise KeyError(key)
        v = default
    return clean(v)


Instruction:
Write a Python 3 script for
showing the output logs of a running container.

Response:
def logs(sess_id_or_alias):
    '''
    Shows the output logs of a running container.

    \b
    SESSID: Session ID or its alias given when creating the session.
    '''
    with Session() as session:
        try:
            print_wait('Retrieving container logs...')
            kernel = session.Kernel(sess_id_or_alias)
            result = kernel.get_logs().get('result')
            logs = result.get('logs') if 'logs' in result else ''
            print(logs)
            print_done('End of logs.')
        except Exception as e:
            print_error(e)
            sys.exit(1)


Instruction:
Write a Python 3 script to
wrap the key from the function input.

Response:
def _wrap_key(function, args, kws):
	'''
	get the key from the function input.
	'''
	return hashlib.md5(pickle.dumps((_from_file(function) + function.__name__, args, kws))).hexdigest()


Instruction:
Can you generate a brief explanation for the following Python 3 code
def get(key, adapter = MemoryAdapter):
	'''
	get the cache value
	'''
	try:
		return pickle.loads(adapter().get(key))
	except CacheExpiredException:
		return None

Response: get the cache value


Instruction:
Can you generate the documentation for the following Python 3 function
def set(key, value, timeout = -1, adapter = MemoryAdapter):
	'''
	set cache by code, must set timeout length
	'''
	if adapter(timeout = timeout).set(key, pickle.dumps(value)):
		return value
	else:
		return None

Response: set a value in the cache by code


Instruction:
Can you tell what is the following Python 3 function doing
def wrapcache(timeout = -1, adapter = MemoryAdapter):
	'''
	the Decorator to cache Function.
	'''
	def _wrapcache(function):
		@wraps(function)
		def __wrapcache(*args, **kws):
			hash_key = _wrap_key(function, args, kws)
			try:
				adapter_instance = adapter()
				return pickle.loads(adapter_instance.get(hash_key))
			except CacheExpiredException:
				#timeout
				value = function(*args, **kws)
				set(hash_key, value, timeout, adapter)
				return value
		return __wrapcache
	return _wrapcache

Response: Decorator to cache a function.


Instruction:
Create a Python 3 function to
create an Excel file containing data returned by the Analytics API and saves it to a file.

Response:
def export_analytics_data_to_excel(data, output_file_name, result_info_key, identifier_keys):
    """Creates an Excel file containing data returned by the Analytics API

    Args:
        data: Analytics API data as a list of dicts
        output_file_name: File name for output Excel file (use .xlsx extension).

    """
    workbook = create_excel_workbook(data, result_info_key, identifier_keys)
    workbook.save(output_file_name)
    print('Saved Excel file to {}'.format(output_file_name))


Instruction:
Can you generate the documentation for the following Python 3 function
def export_analytics_data_to_csv(data, output_folder, result_info_key, identifier_keys):
    workbook = create_excel_workbook(data, result_info_key, identifier_keys)

    suffix = '.csv'

    if not os.path.exists(output_folder):
        os.makedirs(output_folder)

    for worksheet in workbook.worksheets:
        file_name = utilities.convert_title_to_snake_case(worksheet.title)

        file_path = os.path.join(output_folder, file_name + suffix)

        mode = 'w'
        if sys.version_info[0] < 3:
            mode = 'wb'
        with io.open(file_path, mode) as output_file:
            csv_writer = csv.writer(output_file)
            for row in worksheet.rows:
                csv_writer.writerow([cell.value for cell in row])

    print('Saved CSV files to {}'.format(output_folder))

Response: Creates a CSV file containing data returned by the Analytics API and saves it into the specified output_folder.


Instruction:
Create a Python 3 function to
create an Excel file made up of combining the Value Report or Rental Report Excel output for the provided addresses. Args: addresses: A list of (address, zipcode) tuples output_file_name: A file name for the Excel output endpoint: One of 'value_report' or 'rental_report' report_type: One of 'full' or 'summary' retry: optional boolean to retry if rate limit is reached api_key: optional API Key api_secret: optional API Secret files_path: Path to save individual files. If None, don't save files

Response:
def concat_excel_reports(addresses, output_file_name, endpoint, report_type,
                         retry, api_key, api_secret, files_path):
    """Creates an Excel file made up of combining the Value Report or Rental Report Excel
       output for the provided addresses.

    Args:
        addresses: A list of (address, zipcode) tuples
        output_file_name: A file name for the Excel output
        endpoint: One of 'value_report' or 'rental_report'
        report_type: One of 'full' or 'summary'
        retry: optional boolean to retry if rate limit is reached
        api_key: optional API Key
        api_secret: optional API Secret
        files_path: Path to save individual files. If None, don't save files
    """
    # create the master workbook to output
    master_workbook = openpyxl.Workbook()

    if api_key is not None and api_secret is not None:
        client = ApiClient(api_key, api_secret)
    else:
        client = ApiClient()

    errors = []

    # for each address, call the API and load the xlsx content in a workbook.
    for index, addr in enumerate(addresses):
        print('Processing {}'.format(addr[0]))
        result = _get_excel_report(
            client, endpoint, addr[0], addr[1], report_type, retry)

        if not result['success']:
            print('Error retrieving report for {}'.format(addr[0]))
            print(result['content'])
            errors.append({'address': addr[0], 'message': result['content']})
            continue

        orig_wb = openpyxl.load_workbook(filename=io.BytesIO(result['content']))

        _save_individual_file(orig_wb, files_path, addr[0])

        # for each worksheet for this address
        for sheet_name in orig_wb.get_sheet_names():
            # if worksheet doesn't exist in master workbook, create it
            if sheet_name in master_workbook.get_sheet_names():
                master_ws = master_workbook.get_sheet_by_name(sheet_name)
            else:
                master_ws = master_workbook.create_sheet(sheet_name)

            # get all the rows in the address worksheet
            orig_rows = orig_wb.get_sheet_by_name(sheet_name).rows

            if sheet_name == 'Summary' or sheet_name == 'Chart Data':
                _process_non_standard_sheet(master_ws, orig_rows, addr, index)
                continue

            _process_standard_sheet(master_ws, orig_rows, addr, index)

    # remove the first sheet which will be empty
    master_workbook.remove(master_workbook.worksheets[0])

    # if any errors occurred, write them to an "Errors" worksheet
    if len(errors) > 0:
        errors_sheet = master_workbook.create_sheet('Errors')
        for error_idx, error in enumerate(errors):
            errors_sheet.cell(row=error_idx+1, column=1, value=error['address'])
            errors_sheet.cell(row=error_idx+1, column=2, value=error['message'])

    # save the master workbook to output_file_name
    adjust_column_width_workbook(master_workbook)
    output_file_path = os.path.join(files_path, output_file_name)
    master_workbook.save(output_file_path)
    print('Saved output to {}'.format(output_file_path))


Instruction:
Can you generate a brief explanation for the following Python 3 code
def create_excel_workbook(data, result_info_key, identifier_keys):
    workbook = analytics_data_excel.get_excel_workbook(data, result_info_key, identifier_keys)
    adjust_column_width_workbook(workbook)
    return workbook

Response: Creates the Excel Workbook


Instruction:
Can you create a Python 3 function that
adjusts column width in the specified worksheet.

Response:
def adjust_column_width(worksheet):
    """Adjust column width in worksheet.

    Args:
        worksheet: worksheet to be adjusted
    """
    dims = {}
    padding = 1
    for row in worksheet.rows:
        for cell in row:
            if not cell.value:
                continue
            dims[cell.column] = max(
                dims.get(cell.column, 0),
                len(str(cell.value))
            )
    for col, value in list(dims.items()):
        worksheet.column_dimensions[col].width = value + padding


Instruction:
How would you explain what the following Python 3 function does
def get_ap_info(ipaddress, auth, url):
    get_ap_info_url = "/imcrs/wlan/apInfo/queryApBasicInfoByCondition?ipAddress=" + str(ipaddress)
    f_url = url + get_ap_info_url
    payload = None
    r = requests.get(f_url, auth=auth,
                     headers=HEADERS)  # creates the URL using the payload variable as the contents
    # print(r.status_code)
    try:
        if r.status_code == 200:
            if len(r.text) > 0:
                return json.loads(r.text)['apBasicInfo']
    except requests.exceptions.RequestException as e:
            return "Error:\n" + str(e) + " get_ap_info_all: An Error has occured"

Response: This function returns the details of the target access point at time of query.


Instruction:
Write a Python 3 script for
returning a list of compute sessions.

Response:
def sessions(status, access_key, id_only, all):
    '''
    List and manage compute sessions.
    '''
    fields = [
        ('Session ID', 'sess_id'),
    ]
    with Session() as session:
        if is_admin(session):
            fields.append(('Owner', 'access_key'))
    if not id_only:
        fields.extend([
            ('Image', 'image'),
            ('Tag', 'tag'),
            ('Created At', 'created_at',),
            ('Terminated At', 'terminated_at'),
            ('Status', 'status'),
            ('Occupied Resource', 'occupied_slots'),
            ('Used Memory (MiB)', 'mem_cur_bytes'),
            ('Max Used Memory (MiB)', 'mem_max_bytes'),
            ('CPU Using (%)', 'cpu_using'),
        ])
        if is_legacy_server():
            del fields[2]

    def execute_paginated_query(limit, offset):
        q = '''
        query($limit:Int!, $offset:Int!, $ak:String, $status:String) {
          compute_session_list(
              limit:$limit, offset:$offset, access_key:$ak, status:$status) {
            items { $fields }
            total_count
          }
        }'''
        q = textwrap.dedent(q).strip()
        q = q.replace('$fields', ' '.join(item[1] for item in fields))
        v = {
            'limit': limit,
            'offset': offset,
            'status': status if status != 'ALL' else None,
            'ak': access_key,
        }
        try:
            resp = session.Admin.query(q, v)
        except Exception as e:
            print_error(e)
            sys.exit(1)
        return resp['compute_session_list']

    def round_mem(items):
        for item in items:
            if 'mem_cur_bytes' in item:
                item['mem_cur_bytes'] = round(item['mem_cur_bytes'] / 2 ** 20, 1)
            if 'mem_max_bytes' in item:
                item['mem_max_bytes'] = round(item['mem_max_bytes'] / 2 ** 20, 1)
        return items

    def _generate_paginated_results(interval):
        offset = 0
        is_first = True
        total_count = -1
        while True:
            limit = (interval if is_first else
                    min(interval, total_count - offset))
            try:
                result = execute_paginated_query(limit, offset)
            except Exception as e:
                print_error(e)
                sys.exit(1)
            offset += interval
            total_count = result['total_count']
            items = result['items']
            items = round_mem(items)

            if id_only:
                yield '\n'.join([item['sess_id'] for item in items]) + '\n'
            else:
                table = tabulate([item.values() for item in items],
                                    headers=(item[0] for item in fields))
                if not is_first:
                    table_rows = table.split('\n')
                    table = '\n'.join(table_rows[2:])
                yield table + '\n'

            if is_first:
                is_first = False
            if not offset < total_count:
                break

    with Session() as session:
        paginating_interval = 10
        if all:
            click.echo_via_pager(_generate_paginated_results(paginating_interval))
        else:
            result = execute_paginated_query(paginating_interval, offset=0)
            total_count = result['total_count']
            if total_count == 0:
                print('There are no compute sessions currently {0}.'
                      .format(status.lower()))
                return
            items = result['items']
            items = round_mem(items)
            if id_only:
                for item in items:
                    print(item['sess_id'])
            else:
                print(tabulate([item.values() for item in items],
                                headers=(item[0] for item in fields)))
            if total_count > paginating_interval:
                print("More sessions can be displayed by using --all option.")


Instruction:
Write a Python 3 function that can
show detailed information for a running compute session.

Response:
def session(sess_id_or_alias):
    '''
    Show detailed information for a running compute session.

    SESSID: Session id or its alias.
    '''
    fields = [
        ('Session ID', 'sess_id'),
        ('Role', 'role'),
        ('Image', 'image'),
        ('Tag', 'tag'),
        ('Created At', 'created_at'),
        ('Terminated At', 'terminated_at'),
        ('Agent', 'agent'),
        ('Status', 'status'),
        ('Status Info', 'status_info'),
        ('Occupied Resources', 'occupied_slots'),
        ('CPU Used (ms)', 'cpu_used'),
        ('Used Memory (MiB)', 'mem_cur_bytes'),
        ('Max Used Memory (MiB)', 'mem_max_bytes'),
        ('Number of Queries', 'num_queries'),
        ('Network RX Bytes', 'net_rx_bytes'),
        ('Network TX Bytes', 'net_tx_bytes'),
        ('IO Read Bytes', 'io_read_bytes'),
        ('IO Write Bytes', 'io_write_bytes'),
        ('IO Max Scratch Size', 'io_max_scratch_size'),
        ('IO Current Scratch Size', 'io_cur_scratch_size'),
        ('CPU Using (%)', 'cpu_using'),
    ]
    if is_legacy_server():
        del fields[3]
    q = 'query($sess_id:String) {' \
        '  compute_session(sess_id:$sess_id) { $fields }' \
        '}'
    q = q.replace('$fields', ' '.join(item[1] for item in fields))
    v = {'sess_id': sess_id_or_alias}
    with Session() as session:
        try:
            resp = session.Admin.query(q, v)
        except Exception as e:
            print_error(e)
            sys.exit(1)
        if resp['compute_session']['sess_id'] is None:
            print('There is no such running compute session.')
            return
        print('Session detail:\n---------------')
        for i, value in enumerate(resp['compute_session'].values()):
            if fields[i][1] in ['mem_cur_bytes', 'mem_max_bytes']:
                value = round(value / 2 ** 20, 1)
            print(fields[i][0] + ': ' + str(value))


Instruction:
Can you create a Python 3 function that
returns a new instance of the correct type of Response based on the data.

Response:
def create(cls, endpoint_name, json_body, original_response):
        """Factory for creating the correct type of Response based on the data.
        Args:
            endpoint_name (str) - The endpoint of the request, such as "property/value"
            json_body - The response body in json format.
            original_response (response object) - server response returned from an http request.
        """

        if endpoint_name == "property/value_report":
            return ValueReportResponse(endpoint_name, json_body, original_response)

        if endpoint_name == "property/rental_report":
            return RentalReportResponse(endpoint_name, json_body, original_response)

        prefix = endpoint_name.split("/")[0]

        if prefix == "block":
            return BlockResponse(endpoint_name, json_body, original_response)

        if prefix == "zip":
            return ZipCodeResponse(endpoint_name, json_body, original_response)

        if prefix == "msa":
            return MsaResponse(endpoint_name, json_body, original_response)

        return PropertyResponse(endpoint_name, json_body, original_response)


Instruction:
How would you code a function in Python 3 to
get a list of business error messages strings for each of the requested objects that had a business error. Returns an empty list if there was no error.

Response:
def get_object_errors(self):
        """Gets a list of business error message strings
        for each of the requested objects that had a business error.
        If there was no error, returns an empty list

        Returns:
            List of strings
        """
        if self._object_errors is None:
            self._object_errors = [{str(o): o.get_errors()}
                                   for o in self.objects()
                                   if o.has_error()]

        return self._object_errors


Instruction:
Write a Python 3 script for
returning true if any requested object had a business logic error code.

Response:
def has_object_error(self):
        """Returns true if any requested object had a business logic error,
        otherwise returns false

        Returns:
            boolean
        """
        if self._has_object_error is None:
            # scan the objects for any business error codes
            self._has_object_error = next(
                (True for o in self.objects()
                 if o.has_error()),
                False)
        return self._has_object_error


Instruction:
Write a Python 3 function for
returning a list of rate limit details.

Response:
def rate_limits(self):
        """Returns a list of rate limit details."""
        if not self._rate_limits:
            self._rate_limits = utilities.get_rate_limits(self.response)

        return self._rate_limits


Instruction:
Can you generate a brief explanation for the following Python 3 code
def check_imc_creds(auth, url):
    test_url = '/imcrs'
    f_url = url + test_url
    try:
        response = requests.get(f_url, auth=auth, headers=HEADERS, verify=False)
        return bool(response.status_code == 200)
    except requests.exceptions.RequestException as error:
        return "Error:\n" + str(error) + " test_imc_creds: An Error has occured"

Response:
Function takes input of auth class object auth object and URL and returns a BOOL of TRUE
     if the authentication was successful.


Instruction:
Given the following Python 3 function, write the documentation
def print_to_file(object_name):
    with open('pyoutput.txt', 'w') as filehandler:
        output = None
        if isinstance(object_name, list):
            output = json.dumps(object, indent=4)
        if isinstance(object_name, dict):
            output = json.dumps(object, indent=4)
        if isinstance(object_name, str):
            output = object_name
        filehandler.write(output)

Response: Function prints out to file handler and saves to current working directory as pyoutput. txt


Instruction:
Make a summary of the following Python 3 code
def get_auth(self):
        url = self.h_url + self.server + ":" + self.port
        auth = requests.auth.HTTPDigestAuth(self.username, self.password)
        f_url = url + "/imcrs"
        try:
            response = requests.get(f_url, auth=auth, headers=HEADERS, verify=False)
            if response.status_code != 200:  # checks for valid IMC credentials
                print("Error:\n" + "Error: \n You're credentials are invalid. Please try again\n\n")
                set_imc_creds()
            return response.status_code
        except requests.exceptions.RequestException as error:
            return "Error:\n" + str(error) + 'The IMC server address is invalid. Please try again'

Response: This method requests an authentication object from the HPE IMC NMS and returns an HTTPDigest Auth Object containing the ID of the object.


Instruction:
Can you tell what is the following Python 3 function doing
def print_title(title, is_end=False):
    # If is end title
    if is_end:
        # Use `=`
        sep = '====='

    # If is not end title
    else:
        # Use `-`
        sep = '-----'

    # If is not end title
    if not is_end:
        # Print an empty line for visual comfort
        print_text()

    # Print the title, e.g. `----- {title} -----`
    print_text('# {sep} {title} {sep}'.format(title=title, sep=sep))

Response: Print a title in a sequence of words.


Instruction:
Given the following Python 3 function, write the documentation
def get_full_python_version():
    # Get version part, e.g. `3.5.1.final.0`
    version_part = '.'.join(str(x) for x in sys.version_info)

    # Get integer width, e.g. 32 or 64
    int_width = struct.calcsize('P') * 8

    # Get integer width part, e.g. `64bit` or `32bit`
    int_width_part = str(int_width) + 'bit'

    # Return full Python version
    return version_part + '.' + int_width_part

Response: Get full Python version.


Instruction:
Write a Python 3 function for
getting given virtual environment s python program path.

Response:
def get_python_path(venv_path):
    """
    Get given virtual environment's `python` program path.

    :param venv_path: Virtual environment directory path.

    :return: `python` program path.
    """
    # Get `bin` directory path
    bin_path = get_bin_path(venv_path)

    # Get `python` program path
    program_path = os.path.join(bin_path, 'python')

    # If the platform is Windows
    if sys.platform.startswith('win'):
        # Add `.exe` suffix to the `python` program path
        program_path = program_path + '.exe'

    # Return the `python` program path
    return program_path


Instruction:
How would you explain what the following Python 3 function does
def add_options(ctx):
    # Add option
    ctx.add_option(
        '--always',
        action='store_true',
        default=False,
        dest='always',
        help='whether always run tasks.',
    )

    # Add option
    ctx.add_option(
        '--check-import',
        action='store_true',
        default=False,
        dest='check_import',
        help='whether import module for dirty checking.',
    )

    # Add option
    ctx.add_option(
        '--venv',
        dest='venv',
        help=(
            'virtual environment directory relative path relative to top'
            ' directory.'
        ),
    )

    # Add option
    ctx.add_option(
        '--venv-add-version',
        default='1',
        dest='venv_add_version',
        # Convert to int so that the value can be used as boolean
        type=int,
        metavar='0|1',
        help=(
            'whether add full Python version to virtual environment directory'
            ' name. E.g. `.py3.5.1.final.0.64bit`. Default is add.'
        ),
    )

    # Add option
    ctx.add_option(
        '--req',
        default=None,
        dest='req_path',
        help='requirements file relative path relative to top directory.',
    )

Response: Add command line options.


Instruction:
Can you write a function in Python 3 where it
adds given path to PYTHONPATH environment variable.

Response:
def add_pythonpath(path):
    """
    Prepend given path to environment variable PYTHONPATH.

    :param path: Path to add to PYTHONPATH.

    :return: New PYTHONPATH value.
    """
    # Get PYTHONPATH value. Default is empty string.
    pythonpath = os.environ.setdefault('PYTHONPATH', '')

    # If given path is not in PYTHONPATH
    if path not in pythonpath.split(os.pathsep):
        # Prepend given path to PYTHONPATH
        pythonpath = os.environ['PYTHONPATH'] = \
            (path + os.pathsep + pythonpath) if pythonpath else path

    # Return new PYTHONPATH value
    return pythonpath


Instruction:
Explain what the following Python 3 code does
def mark_path(path):
    # If given path is not string,
    # or given path is absolute path.
    if not isinstance(path, str) or os.path.isabs(path):
        # Get error message
        msg = 'Error (2D9ZA): Given path is not relative path: {0}.'.format(
            path
        )

        # Raise error
        raise ValueError(msg)

    # If given path is string,
    # and given path is not absolute path.

    # Wrap given path
    return _ItemWrapper(type='path', item=path)

Response: Wrap given path as relative path relative to top directory.


Instruction:
Write a Python 3 function that can
wrap given item as input or output target that should be added to task.

Response:
def _mark_target(type, item):
    """
    Wrap given item as input or output target that should be added to task.

    Wrapper object will be handled specially in \
    :paramref:`create_cmd_task.parts`.

    :param type: Target type.

        Allowed values:
            - 'input'
            - 'output'

    :param item: Item to mark as input or output target.

        Allowed values:
            - Relative path relative to top directory.
            - Node object.
            - List of these.

    :return: Wrapper object.
    """
    # If given type is not valid
    if type not in ('input', 'output'):
        # Get error message
        msg = 'Error (7D74X): Type is not valid: {0}'.format(type)

        # Raise error
        raise ValueError(msg)

    # If given type is valid.

    # Store given item
    orig_item = item

    # If given path is list
    if isinstance(item, list):
        # Use it as items list
        item_s = item

    # If given path is not list
    else:
        # Create items list containing given path
        item_s = [item]

    # For the items list's each item
    for item in item_s:
        # If the item is string,
        # and the item is absolute path.
        if isinstance(item, str) and os.path.isabs(item):
            # Get error message
            msg = (
                'Error (5VWOZ): Given path is not relative path: {0}.'
            ).format(item)

            # Raise error
            raise ValueError(msg)

    # Wrap given item
    return _ItemWrapper(type=type, item=orig_item)


Instruction:
Here you have a function in Python 3, explain what it does
def create_node(ctx, path):
    # Ensure given context object is BuildContext object
    _ensure_build_context(ctx)

    # Get top directory's relative path relative to `wscript` directory
    top_dir_relpath = os.path.relpath(
        # Top directory's absolute path
        ctx.top_dir,
        # `wscript` directory's absolute path
        ctx.run_dir,
    )

    # Convert given relative path to be relative to `wscript` directory
    node_path = os.path.join(top_dir_relpath, path)

    # Create node using the relative path relative to `wscript` directory
    node = ctx.path.make_node(node_path)

    # Return the created node
    return node

Response: Create a node for given relative path relative to the top directory.


Instruction:
Can you tell what is the following Python 3 function doing
def _normalize_items(
    ctx,
    items,
    str_to_node=False,
    node_to_str=False,
    allow_task=False,
):
    """
    Normalize given items.

    Do several things:
        - Ignore None.
        - Flatten list.
        - Unwrap wrapped item in `_ItemWrapper`.

    :param ctx: BuildContext object.

    :param items: Items list to normalize.

    :param str_to_node: Convert string to node.

    :param node_to_str: Convert node to absolute path.

    :param allow_task: Whether allow task item.

    :return: Normalized tuples list.

        Tuple format is:
        ::

            (
                normalized_item,        # Normalized item.
                wrapper_type,           # Original `_ItemWrapper` type.
            )
    """
    # Ensure given context object is BuildContext object
    _ensure_build_context(ctx)

    # Normalized tuples list
    norm_tuple_s = []

    # If given items list is empty
    if not items:
        # Return empty list
        return norm_tuple_s

    # If given items list is not empty.

    # For given items list's each item
    for item in items:
        # If the item is item wrapper
        if isinstance(item, _ItemWrapper):
            # Get wrapper type
            wrapper_type = item.type()

            # Get real item
            item = item.item()

        # If the item is not item wrapper
        else:
            # Set wrapper type be None
            wrapper_type = None

            # Use the item as real item
            item = item

        # If the real item is list
        if isinstance(item, list):
            # Use the real item as real items list
            real_item_s = item

        # If the real item is not list
        else:
            # Create real items list containing the real item
            real_item_s = [item]

        # For each real item
        for real_item in real_item_s:
            # If the real item is None
            if real_item is None:
                # Ignore None
                continue

            # If the real item is not None.

            # If the real item is string
            elif isinstance(real_item, str):
                # If need convert string to node
                if (wrapper_type is not None) or str_to_node:
                    # If the path string is absolute path
                    if os.path.isabs(real_item):
                        # Get error message
                        msg = (
                            'Error (7MWU9): Given path is not relative path:'
                            ' {0}.'
                        ).format(real_item)

                        # Raise error
                        raise ValueError(msg)

                    # If the path string is not absolute path.

                    # Create node as normalized item
                    norm_item = create_node(ctx, real_item)

                    # If need convert node to absolute path
                    if node_to_str:
                        # Convert the node to absolute path
                        norm_item = norm_item.abspath()

                # If not need convert string to node
                else:
                    # Use the string as normalized item
                    norm_item = real_item

                # Create normalized tuple
                norm_tuple = (norm_item, wrapper_type)

            # If the real item is not string.

            # If the real item is node
            elif isinstance(real_item, Node):
                # If need convert node to absolute path
                if node_to_str:
                    # Convert the node to absolute path
                    real_item = real_item.abspath()

                # Create normalized tuple
                norm_tuple = (real_item, wrapper_type)

            # If the real item is not node.

            # If the real item is task
            elif isinstance(real_item, Task):
                # If allow task item
                if allow_task:
                    # Create normalized tuple
                    norm_tuple = (real_item, wrapper_type)

                # If not allow task item
                else:
                    # Get error message
                    msg = 'Error (6PVMG): Item type is not valid: {0}.'.format(
                        real_item
                    )

                    # Raise error
                    raise ValueError(msg)

            # If the real item is not task.

            # If the real item is not None, string, node, or task
            else:
                # Get error message
                msg = 'Error (63KUG): Item type is not valid: {0}.'.format(
                    real_item
                )

                # Raise error
                raise ValueError(msg)

            # Add the normalized tuple to list
            norm_tuple_s.append(norm_tuple)

    # Return the normalized tuples list
    return norm_tuple_s

Response: Normalizes given items list.


Instruction:
Write a Python 3 function for
updating the touch file at given path.

Response:
def update_touch_file(
    ctx,
    path,
    check_import=False,
    check_import_module=None,
    check_import_python=None,
    always=False,
):
    """
    Update touch file at given path.

    Do two things:
        - Create touch file if it not exists.
        - Update touch file if import checking fails.

    The returned touch file node is used as task's output target for dirty
    checking. Task will run if the touch file changes.

    :param ctx: BuildContext instance.

    :param path: Touch file relative path relative to top directory.

    :param check_import: Whether import module for dirty checking.

    :param check_import_module: Module name to import for dirty checking.

    :param check_import_python: Python program to use for dirty checking.

    :param always: Whether always run.

    :return: A two-item tuple.

        Tuple format is:
        ::

            (
                touch_file_node,        # Touch file node.
                task_needs_run,         # Whether task needs run.
            )
    """
    # Ensure given context object is BuildContext object
    _ensure_build_context(ctx)

    # Print title
    print_title('Update touch file: {}'.format(path))

    # Create touch node
    touch_node = create_node(ctx, path)

    # Whether task needs run
    need_run = False

    # If the touch file not exists,
    # or `always` flag is on.
    if not touch_node.exists() or always:
        # Set `need_run` flag on
        need_run = True

    # If the touch file exists,
    # and `always` flag is off.
    else:
        # If need import module for dirty checking,
        # and module name to import is given.
        if check_import and check_import_module:
            # Get import statement.
            # Notice `from` import ensures the imported module is not imported
            # as `__main__` module. And `__name__` exists in any module.
            import_stmt = 'from {} import __name__'.format(check_import_module)

            # Print info
            print_text('Check import: {}'.format(import_stmt))

            # If Python program to check import is not given
            if check_import_python is None:
                # Get error message
                msg = (
                    'Error (3BKFW): Python program to check import is not'
                    ' given.'
                )

                # Raise error
                raise ValueError(msg)

            # If Python program to check import is given.

            # Normalize given Python program path
            check_import_python, _ = _normalize_items(
                ctx=ctx,
                items=[check_import_python],
                # Convert node to absolute path
                node_to_str=True,
            )[0]

            # If the Python program path is not string
            if not isinstance(check_import_python, str):
                # Get error message
                msg = (
                    'Error (39FQE): Given Python program to check import is'
                    ' not string or node: {0}.'
                ).format(check_import_python)

                # Raise error
                raise ValueError(msg)

            # If the Python program path is string.

            # If the Python program path is not absolute path
            if not os.path.isabs(check_import_python):
                # Convert the Python program path to absolute path
                check_import_python = \
                    create_node(ctx, check_import_python).abspath()

            # The Python program path is absolute path now.

            # Get command parts
            cmd_part_s = [
                # Python program absolute path
                check_import_python,

                # Run code
                '-c',

                # Code to run
                import_stmt
            ]

            # Print the command in multi-line format
            print_text(_format_multi_line_command(cmd_part_s))

            #
            try:
                # Run the command
                subprocess.check_output(cmd_part_s)

                # If not have error,
                # it means the module can be imported.
                #     Set `need_run` flag off.
                need_run = False

            # If have error,
            # it means the module can not be imported.
            #
            # Notice the program may not exist. So catch general exception.
            except Exception:  # pylint: disable=W0703
                # Set `need_run` flag on
                need_run = True

    # If task needs run
    if need_run:
        # If the touch file's parent directory not exists
        if not touch_node.parent.exists():
            # Create the touch file's parent directory
            touch_node.parent.mkdir()

        # Write current time to the touch file to force content change.
        # This will fail dirty-checking and cause task to run.
        touch_node.write('{0}\n'.format(datetime.utcnow()))

        # Print info
        print_text('Updated.')

    # If task not needs run
    else:
        # Print info
        print_text('Skipped.')

    # Print end title
    print_title('Update touch file: {}'.format(path), is_end=True)

    # Return a two-item tuple
    return touch_node, need_run


Instruction:
Can you generate a brief explanation for the following Python 3 code
def chain_tasks(tasks):
    # If given tasks list is not empty
    if tasks:
        # Previous task
        previous_task = None

        # For given tasks list's each task
        for task in tasks:
            # If the task is not None.
            # Task can be None to allow code like ``task if _PY2 else None``.
            if task is not None:
                # If previous task is not None
                if previous_task is not None:
                    # Set the task to run after the previous task
                    task.set_run_after(previous_task)

                # Set the task as previous task for the next task
                previous_task = task

    # Return given tasks list.
    return tasks

Response: Chain given tasks. Set each task to run after its previous task.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def create_cmd_task(
    ctx,
    parts,
    inputs=None,
    outputs=None,
    env=None,
    cwd=None,
    task_name=None,
    cache_key=None,
    always=False,
    add_to_group=True,
):
    """
    Create task that runs given command.

    :param ctx: BuildContext object.

    :param parts: Command parts list.

        Each part can be:
            - **None**: Will be ignored.
            - **String**: Will be used as-is.
            - **Node object**: Will be converted to absolute path.
            - **List of these**: Will be flattened.
            - **Item wrapper of these**: Will be unwrapped. Item marked as
              input or output target will be added to created task.

    :param inputs: Input items list to add to created task.

        Each item can be:
            - **None**: Will be ignored.
            - **Path**: Relative path relative to top directory. Will be
              converted to node.
            - **Node object**: Will be used as-is.
            - **Task object**: Will set created task to run after the task.
            - **List of these**: Will be flattened.
            - **Item wrapper of these**: Will be unwrapped.

    :param outputs: Outputs items list to add to created task.

        Each item can be:
            - **None**: Will be ignored.
            - **Path**: Relative path relative to top directory. Will be
              converted to node.
            - **Node object**: Will be used as-is.
            - **Task object**: Will set the task to run after created task.
            - **List of these**: Will be flattened.
            - **Item wrapper of these**: Will be unwrapped.

    :param env: Environment dict.

        Default is use given context object's environment dict.

    :param cwd: Working directory in which to run given command.

        Default is top directory.

    :param task_name: Task name for display purpose.

        Default is use the caller function's name.

    :param cache_key: Task cache key.

    :param always: Whether mark created task as always run.

    :param add_to_group: Whether add created task to given context.

    :return: Created task.

    :notes:
        It is recommended to refer to files inside project using relative
        paths. This is even required if the files are used as task's input or
        output targets.

        It is not ideal to make relative paths relative to current working
        directory, or relative to `wscript` file, because neither of the two
        choices guarantee a fixed start directory.

        It is not ideal to let `Waf` resolve relative paths neither, because
        the start directory used for resolving relative paths varies with
        different types of command context (i.e. OptionsContext,
        ConfigurationContext, BuildContext, and Context).

        It is best to make relative paths relative to project's top directory.
        To do so, first use `Waf`'s pre-defined path variable `top` to locate
        project's top directory (Notice path variable `top`'s value is relative
        to `wscript` file.). Then `aoikwafutil`'s functions like
        `create_cmd_task` will use path variable `top`'s value to resolve other
        relative paths.

        `create_cmd_task` handles relative paths using rules below:

            - Relative paths marked by `mark_path`, `mark_input`, or
              `mark_output` are relative to top directory.

            - Relative paths passed to argument `parts` are used as-is. They
              are relative to the working directory in which to run the
              command. However, they can be marked to be relative to top
              directory instead.

            - Relative paths passed to argument `inputs` or `outputs` are
              relative to top directory. They need not be marked.
    """
    # Ensure given context object is BuildContext object
    _ensure_build_context(ctx)

    # If task name is not given
    if not task_name:
        # Get the caller function's name
        task_name = inspect.stack()[1][3]

    # Print title
    print_title('Create task: {}'.format(task_name))

    # If cache key is given
    if cache_key:
        # Find cached task
        cached_task = _TASKS_CACHE.get(cache_key, None)

        # If have found cached task
        if cached_task is not None:
            # Print info
            print_text('Use cached task `{}`.'.format(cache_key))

            # Print end title
            print_title('Create task: {}'.format(task_name), is_end=True)

            # Return the cached task
            return cached_task

        # If have not found cached task.
        #     Continue to create task.

    # If cache key is not given.
    #     Continue to create task.

    # Normalized command parts list
    norm_part_s = []

    # Input nodes list
    input_node_s = []

    # Output nodes list
    output_node_s = []

    # Get the first command part that is program path
    first_part = parts[0]

    # If the first command part is list.
    # Notice the first command part can be list if the value is from `ctx.env`,
    # e.g `ctx.env.PYTHON`.
    if isinstance(first_part, list):
        # Use the first item in the list as the first command part
        parts[0] = first_part[0]

    # For given command parts list's each command part
    for part, wrapper_type in _normalize_items(ctx=ctx, items=parts):
        # If the command part is string
        if isinstance(part, str):
            # Add the string to the normalized list
            norm_part_s.append(part)

        # If the command part is node
        elif isinstance(part, Node):
            # Add the node's absolute path to the normalized list
            norm_part_s.append(part.abspath())

            # If the wrapper type is `input`
            if wrapper_type == 'input':
                # Add the node to the input nodes list
                input_node_s.append(part)

            # If the wrapper type is `output`
            elif wrapper_type == 'output':
                # Add the node to the output nodes list
                output_node_s.append(part)

            # If the wrapper type is not `input` or `output`
            else:
                # Do nothing
                pass

        # If the command part is not string or node
        else:
            # Get error message
            msg = 'Error (2W9YD): Command part is not valid: {0}.'.format(part)

            # Raise error
            raise ValueError(msg)

    # If environment dict is not given
    if env is None:
        # Use given context object's environment dict
        env = ctx.env

    # If working directory path is not given
    if cwd is None:
        # Set working directory path be top directory absolute path
        cwd = ctx.top_dir

    # If the working directory path is not absolute path.
    if not os.path.isabs(cwd):
        # Convert the working directory path to absolute path
        cwd = create_node(ctx, cwd).abspath()

    # Create task that runs command
    task = CmdTask(
        # Context object
        ctx=ctx,

        # Command parts list
        parts=norm_part_s,

        # Environment dict
        env=env,

        # Working directory
        cwd=cwd,

        # Task name
        task_name=task_name,
    )

    # For each input or output item.
    # Notice the code structure for handling input and output items are the
    # same so use the same code with different variables to avoid duplicate
    # code.
    for wrapper_type, item_s, node_s, nodes_set_func in [
        ('input', inputs, input_node_s, task.set_inputs),
        ('output', outputs, output_node_s, task.set_outputs),
    ]:
        # For each normalized item
        for item, _ in _normalize_items(
            # Context
            ctx=ctx,

            # Items to normalize
            items=item_s,

            # Convert string to node
            str_to_node=True,

            # Allow task item
            allow_task=True,
        ):
            # If the item is node
            if isinstance(item, Node):
                # Add the node to the nodes list
                node_s.append(item)

            # If the item is task
            elif isinstance(item, Task):
                # If the wrapper type is `input`
                if wrapper_type == 'input':
                    # Set the created task to run after the task
                    task.set_run_after(item)

                # If the wrapper type is `output`
                elif wrapper_type == 'output':
                    # Set the task to run after the created task
                    item.set_run_after(task)

                # If the wrapper type is not `input` or `output`
                else:
                    # Get error message
                    msg = (
                        'Error (3ZLGJ): Wrapper type is not valid: {0}.'
                    ).format(wrapper_type)

                    # Raise error
                    raise ValueError(msg)

            # If the item is not node or task
            else:
                # Get error message
                msg = 'Error (5H4GC): Item type is not valid: {0}.'.format(
                    item
                )

                # Raise error
                raise ValueError(msg)

        # Add these nodes to the created task as input or output targets
        nodes_set_func(node_s)

    # If need mark the created task as always run
    if always:
        # Mark the created task as always run
        task.always_run = True  # pylint: disable=W0201

    # If need add the created task to given context
    if add_to_group:
        # Add the created task to given context
        ctx.add_to_group(task)

    # If cache key is given
    if cache_key:
        # Add the created task to the cache
        _TASKS_CACHE[cache_key] = task

    # Print end title
    print_title('Create task: {}'.format(task_name), is_end=True)

    # Return the task
    return task

Response: Create a task that runs given command.


Instruction:
Implement a function in Python 3 to
print given context s info.

Response:
def print_ctx(ctx):
    """
    Print given context's info.

    :param ctx: Context object.

    :return: None.
    """
    # Print title
    print_title('ctx attributes')

    # Print context object's attributes
    print_text(dir(ctx))

    # Print end title
    print_title('ctx attributes', is_end=True)

    # Print title
    print_title('ctx.options')

    # Print context options dict
    print_text(pformat(vars(ctx.options), indent=4, width=1))

    # Print end title
    print_title('ctx.options', is_end=True)

    # If the context object has `env` attribute.
    # Notice plain context object not has `env` attribute.
    if hasattr(ctx, 'env'):
        # Print title
        print_title('ctx.env')

        # Print context environment variables dict
        print_text(pformat(dict(ctx.env), indent=4, width=1))

        # Print end title
        print_title('ctx.env', is_end=True)


Instruction:
Create a Python 3 function to
create task that sets up virtualenv.

Response:
def virtualenv_setup(
    ctx,
    python,
    inputs=None,
    outputs=None,
    touch=None,
    check_import=False,
    pip_setup_file=None,
    pip_setup_touch=None,
    cache_key=None,
    always=False,
):
    """
    Create task that sets up `virtualenv` package.

    :param ctx: BuildContext object.

    :param python: Python program path.

    :param inputs: Input items list to add to created task.

        See :paramref:`create_cmd_task.inputs` for allowed item types.

    :param outputs: Output items list to add to created task.

        See :paramref:`create_cmd_task.outputs` for allowed item types.

    :param touch: Touch file path for dirty checking.

    :param check_import: Whether import module for dirty checking.

    :param pip_setup_file: `get-pip.py` file path for `pip_setup` task.

    :param pip_setup_touch: Touch file path for `pip_setup` task.

    :param cache_key: Task cache key.

    :param always: Whether always run.

    :return: Created task.
    """
    # Ensure given context object is BuildContext object
    _ensure_build_context(ctx)

    # If `get-pip.py` file path is not given
    if pip_setup_file is None:
        # Not create task that sets up `pip`
        pip_setup_task = None

    # If `get-pip.py` file path is given
    else:
        # Create task that sets up `pip`
        pip_setup_task = pip_setup(
            # Context
            ctx=ctx,

            # Python program path
            python=python,

            # `get-pip.py` file path
            setup_file=pip_setup_file,

            # Touch file path
            touch=pip_setup_touch,

            # Whether import module for dirty checking
            check_import=check_import,

            # Whether always run
            always=always,
        )

    # If touch file path is not given
    if touch is None:
        # Not update touch file
        touch_node = None
    else:
        # Update touch file
        touch_node, always = update_touch_file(
            # Context
            ctx=ctx,

            # Touch file path
            path=touch,

            # Whether import module for dirty checking
            check_import=check_import,

            # Module name to import for dirty checking
            check_import_module='virtualenv',

            # Python program path for dirty checking
            check_import_python=python,

            # Whether always run
            always=always,
        )

    # Create task that sets up `virtualenv` package
    task = create_cmd_task(
        # Context
        ctx=ctx,

        # Command parts
        parts=[
            # Python program path
            python,

            # Run module
            '-m',

            # Module name
            'pip',

            # Install package
            'install',

            # Package name
            'virtualenv',
        ],

        # Input items list
        inputs=[
            # Run after the task that sets up `pip`
            pip_setup_task,

            # Given input items list
            inputs,
        ],

        # Output items list
        outputs=[
            # Use the touch node as output target for dirty checking
            touch_node,

            # Given output items list
            outputs,
        ],

        # Whether always run
        always=always,

        # Task cache key
        cache_key=cache_key or (python, 'virtualenv'),
    )

    # Return the created task
    return task


Instruction:
Write a Python 3 function for
creating a virtual environment.

Response:
def create_venv(
    ctx,
    python,
    venv_path,
    inputs=None,
    outputs=None,
    pip_setup_file=None,
    pip_setup_touch=None,
    virtualenv_setup_touch=None,
    task_name=None,
    cache_key=None,
    always=False,
):
    """
    Create task that sets up virtual environment.

    :param ctx: BuildContext object.

    :param python: Python program path.

    :param venv_path: Virtual environment directory relative path relative to
        top directory.

    :param inputs: Input items list to add to created task.

        See :paramref:`create_cmd_task.inputs` for allowed item types.

    :param outputs: Output items list to add to created task.

        See :paramref:`create_cmd_task.outputs` for allowed item types.

    :param pip_setup_file: `get-pip.py` file path for `pip_setup` task.

    :param pip_setup_touch: Touch file path for `pip_setup` task.

    :param virtualenv_setup_touch: Touch file path for `virtualenv_setup` task.

    :param task_name: Task name for display purpose.

    :param cache_key: Task cache key.

    :param always: Whether always run.

    :return: Created task.
    """
    # Ensure given context object is BuildContext object
    _ensure_build_context(ctx)

    # Create task that sets up `virtualenv` package
    virtualenv_setup_task = virtualenv_setup(
        # Context
        ctx=ctx,

        # Python program path
        python=python,

        # Touch file path
        touch=virtualenv_setup_touch,

        # `get-pip.py` file path for `pip_setup` task.
        pip_setup_file=pip_setup_file,

        # Touch file path for `pip_setup` task.
        pip_setup_touch=pip_setup_touch,
    )

    # Get virtual environment directory path node
    venv_path_node, _ = _normalize_items(
        ctx=ctx,
        items=[venv_path],
        # Convert path string to node
        str_to_node=True
    )[0]

    # Create task that sets up virtual environment.
    task = create_cmd_task(
        # Context
        ctx=ctx,

        # Command parts
        parts=[
            # Python program path
            python,

            # Run module
            '-m',

            # Module name
            'virtualenv',

            # Virtual environment directory absolute path
            venv_path_node.abspath(),
        ],

        # Input items list
        inputs=[
            # Run after the task that sets up `virtualenv` package
            virtualenv_setup_task,

            # Given input items list
            inputs,
        ],

        # Output items list
        outputs=[
            # Add the virtual environment's `python` program path as output
            # target for dirty checking
            get_python_path(venv_path),

            # Add the virtual environment's `pip` program path as output target
            # for dirty checking
            get_pip_path(venv_path),

            # Given output items list
            outputs,
        ],

        # Whether always run
        always=always,

        # Task name
        task_name=task_name,

        # Task cache key
        cache_key=cache_key or (python, venv_path),
    )

    # Return the created task
    return task


Instruction:
Implement a Python 3 function for
creating a pip - ins - req task.

Response:
def pip_ins_req(
    ctx,
    python,
    req_path,
    venv_path=None,
    inputs=None,
    outputs=None,
    touch=None,
    check_import=False,
    check_import_module=None,
    pip_setup_file=None,
    pip_setup_touch=None,
    virtualenv_setup_touch=None,
    always=False,
):
    """
    Create task that uses given virtual environment's `pip` to sets up \
    packages listed in given requirements file.

    :param ctx: BuildContext object.

    :param python: Python program path used to set up `pip` and `virtualenv`.

    :param req_path: Requirements file relative path relative to top directory.

    :param venv_path: Virtual environment directory relative path relative to
        top directory.

        If given, will create the virtual environment and set up packages
        listed in given requirements file in the virtual environment.

        If not given, will set up packages listed in given requirements file in
        given Python program's environment.

    :param inputs: Input items list to add to created task.

        See :paramref:`create_cmd_task.inputs` for allowed item types.

    :param outputs: Output items list to add to created task.

        See :paramref:`create_cmd_task.outputs` for allowed item types.

    :param touch: Touch file path for dirty checking.

    :param check_import: Whether import module for dirty checking.

    :param check_import_module: Module name to import for dirty checking.

    :param pip_setup_file: `get-pip.py` file path for `pip_setup` task.

    :param pip_setup_touch: Touch file path for `pip_setup` task.

    :param virtualenv_setup_touch: Touch file path for `virtualenv_setup` task.

    :param always: Whether always run.

    :return: Created task.
    """
    # Ensure given context object is BuildContext object
    _ensure_build_context(ctx)

    # If virtual environment directory path is not given
    if venv_path is None:
        # Use given Python program path
        venv_python = python

    # If virtual environment directory path is given
    else:
        # Get Python program path in the virtual environment
        venv_python = get_python_path(venv_path)

        # Mark the path as input target
        venv_python = mark_input(venv_python)

    # If virtual environment directory path is not given,
    # it means not create virtual environment.
    if venv_path is None:
        # Create task that sets up `pip`
        pip_setup_task = pip_setup(
            # Context
            ctx=ctx,

            # Python program path
            python=python,

            # `get-pip.py` file path
            setup_file=pip_setup_file,

            # Touch file path
            touch=pip_setup_touch,

            # Whether import module for dirty checking
            always=always,
        )

        # Not create virtual environment
        venv_task = None

    # If virtual environment directory path is given
    else:
        # Not create task that sets up `pip` here because `create_venv`
        # function below will do
        pip_setup_task = None

        # Create task that sets up virtual environment
        venv_task = create_venv(
            # Context
            ctx=ctx,

            # Python program path
            python=python,

            # Virtual environment directory path
            venv_path=venv_path,

            # Output items list
            outputs=[
                # Add the virtual environment's `python` program path as output
                # target for dirty checking
                get_python_path(venv_path),

                # Add the virtual environment's `pip` program path as output
                # target for dirty checking
                get_pip_path(venv_path),
            ],

            # Whether always run
            always=always,

            # Task name
            task_name='Create venv `{}`'.format(venv_path),

            # `get-pip.py` file path for `pip_setup` task
            pip_setup_file=pip_setup_file,

            # Touch file path for `pip_setup` task
            pip_setup_touch=pip_setup_touch,

            # Touch file path for `virtualenv_setup` task
            virtualenv_setup_touch=virtualenv_setup_touch,
        )

    # If touch file path is not given
    if not touch:
        # Not update touch file
        touch_node = None

    # If touch file path is given
    else:
        # Update touch file
        touch_node, always = update_touch_file(
            # Context
            ctx=ctx,

            # Touch file path
            path=touch,

            # Whether import module for dirty checking
            check_import=check_import,

            # Module name to import for dirty checking
            check_import_module=check_import_module,

            # Python program path for dirty checking
            check_import_python=venv_python,

            # Whether always run
            always=always,
        )

    # Create task that sets up packages
    task = create_cmd_task(
        # Context
        ctx=ctx,

        # Command parts
        parts=[
            # Python program path
            venv_python,

            # Run module
            '-m',

            # Module name
            'pip',

            # Install package
            'install',

            # Read package names from requirements file
            '-r',

            # Requirements file path. Mark as input target.
            mark_input(req_path),
        ],

        # Input items list
        inputs=inputs,

        # Output items list
        outputs=[
            # Use the touch node as output target for dirty checking
            touch_node,

            # Given output items list
            outputs,
        ],

        # Whether always run
        always=always,
    )

    # Chain these tasks to run one after another
    chain_tasks([
        pip_setup_task,
        venv_task,
        task,
    ])

    # Return the created task
    return task


Instruction:
Can you generate the documentation for the following Python 3 function
def git_clean(ctx):
    # Get command parts
    cmd_part_s = [
        # Program path
        'git',

        # Clean untracked files
        'clean',

        # Remove all untracked files
        '-x',

        # Remove untracked directories too
        '-d',

        # Force to remove
        '-f',

        # Give two `-f` flags to remove sub-repositories too
        '-f',
    ]

    # Print title
    print_title('git_clean')

    # Print the command in multi-line format
    print_text(_format_multi_line_command(cmd_part_s))

    # Create subprocess to run the command in top directory
    proc = subprocess.Popen(cmd_part_s, cwd=ctx.top_dir)

    # Wait the subprocess to finish
    proc.wait()

    # Print end title
    print_title('git_clean', is_end=True)

Response: Delete all untracked files and directories in the current git repository.