Instruction:
Create a Python 3 function to
check whether the ADB connection is intact.

Response:
def available(self):
        """Check whether the ADB connection is intact."""
        if not self.adb_server_ip:
            # python-adb
            return bool(self._adb)

        # pure-python-adb
        try:
            # make sure the server is available
            adb_devices = self._adb_client.devices()

            # make sure the device is available
            try:
                # case 1: the device is currently available
                if any([self.host in dev.get_serial_no() for dev in adb_devices]):
                    if not self._available:
                        self._available = True
                    return True

                # case 2: the device is not currently available
                if self._available:
                    logging.error('ADB server is not connected to the device.')
                    self._available = False
                return False

            except RuntimeError:
                if self._available:
                    logging.error('ADB device is unavailable; encountered an error when searching for device.')
                    self._available = False
                return False

        except RuntimeError:
            if self._available:
                logging.error('ADB server is unavailable.')
                self._available = False
            return False


Instruction:
How would you explain what the following Python 3 function does
def running_apps(self):
        ps = self.adb_shell(RUNNING_APPS_CMD)
        if ps:
            return [line.strip().rsplit(' ', 1)[-1] for line in ps.splitlines() if line.strip()]
        return []

Response: Return a list of running user applications.


Instruction:
Create a Python 3 function to
return the current app.

Response:
def current_app(self):
        """Return the current app."""
        current_focus = self.adb_shell(CURRENT_APP_CMD)
        if current_focus is None:
            return None

        current_focus = current_focus.replace("\r", "")
        matches = WINDOW_REGEX.search(current_focus)

        # case 1: current app was successfully found
        if matches:
            (pkg, activity) = matches.group("package", "activity")
            return {"package": pkg, "activity": activity}

        # case 2: current app could not be found
        logging.warning("Couldn't get current app, reply was %s", current_focus)
        return None


Instruction:
Can you generate a brief explanation for the following Python 3 code
def wake_lock_size(self):
        output = self.adb_shell(WAKE_LOCK_SIZE_CMD)
        if not output:
            return None
        return int(output.split("=")[1].strip())

Response: Get the size of the current wake lock.


Instruction:
Can you generate the documentation for the following Python 3 function
def get_properties(self, get_running_apps=True, lazy=False):
        if get_running_apps:
            output = self.adb_shell(SCREEN_ON_CMD + (SUCCESS1 if lazy else SUCCESS1_FAILURE0) + " && " +
                                    AWAKE_CMD + (SUCCESS1 if lazy else SUCCESS1_FAILURE0) + " && " +
                                    WAKE_LOCK_SIZE_CMD + " && " +
                                    CURRENT_APP_CMD + " && " +
                                    RUNNING_APPS_CMD)
        else:
            output = self.adb_shell(SCREEN_ON_CMD + (SUCCESS1 if lazy else SUCCESS1_FAILURE0) + " && " +
                                    AWAKE_CMD + (SUCCESS1 if lazy else SUCCESS1_FAILURE0) + " && " +
                                    WAKE_LOCK_SIZE_CMD + " && " +
                                    CURRENT_APP_CMD)

        # ADB command was unsuccessful
        if output is None:
            return None, None, None, None, None

        # `screen_on` property
        if not output:
            return False, False, -1, None, None
        screen_on = output[0] == '1'

        # `awake` property
        if len(output) < 2:
            return screen_on, False, -1, None, None
        awake = output[1] == '1'

        lines = output.strip().splitlines()

        # `wake_lock_size` property
        if len(lines[0]) < 3:
            return screen_on, awake, -1, None, None
        wake_lock_size = int(lines[0].split("=")[1].strip())

        # `current_app` property
        if len(lines) < 2:
            return screen_on, awake, wake_lock_size, None, None

        matches = WINDOW_REGEX.search(lines[1])
        if matches:
            # case 1: current app was successfully found
            (pkg, activity) = matches.group("package", "activity")
            current_app = {"package": pkg, "activity": activity}
        else:
            # case 2: current app could not be found
            current_app = None

        # `running_apps` property
        if not get_running_apps or len(lines) < 3:
            return screen_on, awake, wake_lock_size, current_app, None

        running_apps = [line.strip().rsplit(' ', 1)[-1] for line in lines[2:] if line.strip()]

        return screen_on, awake, wake_lock_size, current_app, running_apps

Response: Get the screen_on awake current_app and running_apps properties.


Instruction:
Write a Python 3 script to
check if device identifier is valid.

Response:
def is_valid_device_id(device_id):
    """ Check if device identifier is valid.

    A valid device identifier contains only ascii word characters or dashes.

    :param device_id: Device identifier
    :returns: Valid or not.
    """
    valid = valid_device_id.match(device_id)
    if not valid:
        logging.error("A valid device identifier contains "
                      "only ascii word characters or dashes. "
                      "Device '%s' not added.", device_id)
    return valid


Instruction:
How would you code a function in Python 3 to
add a device to the list of FireTV devices.

Response:
def add(device_id, host, adbkey='', adb_server_ip='', adb_server_port=5037):
    """ Add a device.

    Creates FireTV instance associated with device identifier.

    :param device_id: Device identifier.
    :param host: Host in <address>:<port> format.
    :param adbkey: The path to the "adbkey" file
    :param adb_server_ip: the IP address for the ADB server
    :param adb_server_port: the port for the ADB server
    :returns: Added successfully or not.
    """
    valid = is_valid_device_id(device_id) and is_valid_host(host)
    if valid:
        devices[device_id] = FireTV(str(host), str(adbkey), str(adb_server_ip), str(adb_server_port))
    return valid


Instruction:
Here you have a function in Python 3, explain what it does
def add_device():
    req = request.get_json()
    success = False
    if 'device_id' in req and 'host' in req:
        success = add(req['device_id'], req['host'], req.get('adbkey', ''), req.get('adb_server_ip', ''), req.get('adb_server_port', 5037))
    return jsonify(success=success)

Response: Add a device via HTTP POST.


Instruction:
Can you tell what is the following Python 3 function doing
def list_devices():
    output = {}
    for device_id, device in devices.items():
        output[device_id] = {
            'host': device.host,
            'state': device.state
        }
    return jsonify(devices=output)

Response: List all devices in a node.


Instruction:
Make a summary of the following Python 3 code
def device_state(device_id):
    if device_id not in devices:
        return jsonify(success=False)
    return jsonify(state=devices[device_id].state)

Response: Get device state via HTTP GET.


Instruction:
Write a Python 3 script for
getting currently running app.

Response:
def current_app(device_id):
    """ Get currently running app. """
    if not is_valid_device_id(device_id):
        abort(403)
    if device_id not in devices:
        abort(404)

    current = devices[device_id].current_app
    if current is None:
        abort(404)

    return jsonify(current_app=current)


Instruction:
Create a Python 3 function to
get running apps via HTTP GET.

Response:
def running_apps(device_id):
    """ Get running apps via HTTP GET. """
    if not is_valid_device_id(device_id):
        abort(403)
    if device_id not in devices:
        abort(404)
    return jsonify(running_apps=devices[device_id].running_apps)


Instruction:
Make a summary of the following Python 3 code
def get_app_state(device_id, app_id):
    if not is_valid_app_id(app_id):
        abort(403)
    if not is_valid_device_id(device_id):
        abort(403)
    if device_id not in devices:
        abort(404)
    app_state = devices[device_id].app_state(app_id)
    return jsonify(state=app_state, status=app_state)

Response: Get the state of the requested app


Instruction:
Write a Python 3 script to
initiate device action via HTTP GET.

Response:
def device_action(device_id, action_id):
    """ Initiate device action via HTTP GET. """
    success = False
    if device_id in devices:
        input_cmd = getattr(devices[device_id], action_id, None)
        if callable(input_cmd):
            input_cmd()
            success = True
    return jsonify(success=success)


Instruction:
Can you create a Python 3 function that
starts an app with corresponding package name

Response:
def app_start(device_id, app_id):
    """ Starts an app with corresponding package name"""
    if not is_valid_app_id(app_id):
        abort(403)
    if not is_valid_device_id(device_id):
        abort(403)
    if device_id not in devices:
        abort(404)

    success = devices[device_id].launch_app(app_id)
    return jsonify(success=success)


Instruction:
Create a Python 3 function for
stopping an app with corresponding package name

Response:
def app_stop(device_id, app_id):
    """ stops an app with corresponding package name"""
    if not is_valid_app_id(app_id):
        abort(403)
    if not is_valid_device_id(device_id):
        abort(403)
    if device_id not in devices:
        abort(404)

    success = devices[device_id].stop_app(app_id)
    return jsonify(success=success)


Instruction:
Can you write a function in Python 3 where it
forces a connection attempt via HTTP GET.

Response:
def device_connect(device_id):
    """ Force a connection attempt via HTTP GET. """
    success = False
    if device_id in devices:
        devices[device_id].connect()
        success = True
    return jsonify(success=success)


Instruction:
Make a summary of the following Python 3 code
def _parse_config(config_file_path):
    config_file = open(config_file_path, 'r')
    config = yaml.load(config_file)
    config_file.close()
    return config

Response: Parse Config File from yaml file.


Instruction:
Here you have a function in Python 3, explain what it does
def _add_devices_from_config(args):
    config = _parse_config(args.config)
    for device in config['devices']:
        if args.default:
            if device == "default":
                raise ValueError('devicename "default" in config is not allowed if default param is set')
            if config['devices'][device]['host'] == args.default:
                raise ValueError('host set in default param must not be defined in config')
        add(device, config['devices'][device]['host'], config['devices'][device].get('adbkey', ''),
            config['devices'][device].get('adb_server_ip', ''), config['devices'][device].get('adb_server_port', 5037))

Response: Add devices from config.


Instruction:
Write a Python 3 script to
set up the server.

Response:
def main():
    """ Set up the server. """
    parser = argparse.ArgumentParser(description='AFTV Server')
    parser.add_argument('-p', '--port', type=int, help='listen port', default=5556)
    parser.add_argument('-d', '--default', help='default Amazon Fire TV host', nargs='?')
    parser.add_argument('-c', '--config', type=str, help='Path to config file')
    args = parser.parse_args()

    if args.config:
        _add_devices_from_config(args)

    if args.default and not add('default', args.default):
        exit('invalid hostname')
    app.run(host='0.0.0.0', port=args.port)


Instruction:
How would you explain what the following Python 3 function does
def _load_words(self):
        with open(self._words_file, 'r') as f:
            self._censor_list = [line.strip() for line in f.readlines()]

Response: Loads the list of profane words from file.


Instruction:
How would you code a function in Python 3 to
replace the original censor character '*' with character.

Response:
def set_censor(self, character):
        """Replaces the original censor character '*' with ``character``."""
        # TODO: what if character isn't str()-able?
        if isinstance(character, int):
            character = str(character)
        self._censor_char = character


Instruction:
Can you generate a brief explanation for the following Python 3 code
def get_profane_words(self):
        profane_words = []

        if self._custom_censor_list:
            profane_words = [w for w in self._custom_censor_list]  # Previous versions of Python don't have list.copy()
        else:
            profane_words = [w for w in self._censor_list]

        profane_words.extend(self._extra_censor_list)
        profane_words.extend([inflection.pluralize(word) for word in profane_words])
        profane_words = list(set(profane_words))

        # We sort the list based on decreasing word length so that words like
        # 'fu' aren't substituted before 'fuck' if no_word_boundaries = true
        profane_words.sort(key=len)
        profane_words.reverse()

        return profane_words

Response: Returns all profane words currently in use.


Instruction:
Can you generate the documentation for the following Python 3 function
def censor(self, input_text):
        bad_words = self.get_profane_words()
        res = input_text

        for word in bad_words:
            # Apply word boundaries to the bad word
            regex_string = r'{0}' if self._no_word_boundaries else r'\b{0}\b'
            regex_string = regex_string.format(word)
            regex = re.compile(regex_string, re.IGNORECASE)
            res = regex.sub(self._censor_char * len(word), res)

        return res

Response: Returns input_text with any profane words censored.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def unpack_multiple(data):
        chunks = []
        while data:
            info = SMB2NetworkInterfaceInfo()
            data = info.unpack(data)
            chunks.append(info)

        return chunks

Response: Unpacks a list of SMB2NetworkInterfaceInfo messages from the byte value passed in.


Instruction:
Make a summary of the following Python 3 code
def get_response_structure(name):
        return {
            CreateContextName.SMB2_CREATE_DURABLE_HANDLE_REQUEST:
                SMB2CreateDurableHandleResponse(),
            CreateContextName.SMB2_CREATE_DURABLE_HANDLE_RECONNECT:
                SMB2CreateDurableHandleReconnect(),
            CreateContextName.SMB2_CREATE_QUERY_MAXIMAL_ACCESS_REQUEST:
                SMB2CreateQueryMaximalAccessResponse(),
            CreateContextName.SMB2_CREATE_REQUEST_LEASE:
                SMB2CreateResponseLease(),
            CreateContextName.SMB2_CREATE_QUERY_ON_DISK_ID:
                SMB2CreateQueryOnDiskIDResponse(),
            CreateContextName.SMB2_CREATE_REQUEST_LEASE_V2:
                SMB2CreateResponseLeaseV2(),
            CreateContextName.SMB2_CREATE_DURABLE_HANDLE_REQUEST_V2:
                SMB2CreateDurableHandleResponseV2(),
            CreateContextName.SMB2_CREATE_DURABLE_HANDLE_RECONNECT_V2:
                SMB2CreateDurableHandleReconnectV2,
            CreateContextName.SMB2_CREATE_APP_INSTANCE_ID:
                SMB2CreateAppInstanceId(),
            CreateContextName.SMB2_CREATE_APP_INSTANCE_VERSION:
                SMB2CreateAppInstanceVersion()

        }.get(name, None)

Response: Returns the response structure for a specific create context.


Instruction:
Can you create a Python 3 function that
gets the buffer_data value of a context response and try to convert it to the relevant structure based on the buffer_name used.

Response:
def get_context_data(self):
        """
        Get the buffer_data value of a context response and try to convert it
        to the relevant structure based on the buffer_name used. If it is an
        unknown structure then the raw bytes are returned.

        :return: relevant Structure of buffer_data or bytes if unknown name
        """
        buffer_name = self['buffer_name'].get_value()
        structure = CreateContextName.get_response_structure(buffer_name)
        if structure:
            structure.unpack(self['buffer_data'].get_value())
            return structure
        else:
            # unknown structure, just return the raw bytes
            return self['buffer_data'].get_value()


Instruction:
Create a Python 3 function for
converting a list of SMB2CreateEABuffer structures and packs them as a bytes object that is used when setting to the SMB2CreateContextRequest buffer_data field. This function is used to pack the contents of the SMB2CreateContextRequest buffer_data field.

Response:
def pack_multiple(messages):
        """
        Converts a list of SMB2CreateEABuffer structures and packs them as a
        bytes object used when setting to the SMB2CreateContextRequest
        buffer_data field. This should be used as it would calculate the
        correct next_entry_offset field value for each buffer entry.

        :param messages: List of SMB2CreateEABuffer structures
        :return: bytes object that is set on the SMB2CreateContextRequest
            buffer_data field.
        """
        data = b""
        msg_count = len(messages)
        for i, msg in enumerate(messages):
            if i == msg_count - 1:
                msg['next_entry_offset'] = 0
            else:
                # because the end padding val won't be populated if the entry
                # offset is 0, we set to 1 so the len calc is correct
                msg['next_entry_offset'] = 1
                msg['next_entry_offset'] = len(msg)
            data += msg.pack()

        return data


Instruction:
How would you code a function in Python 3 to
set the print name and length of the message with the values passed in.

Response:
def set_name(self, print_name, substitute_name):
        """
        Set's the path_buffer and print/substitute name length of the message
        with the values passed in. These values should be a string and not a
        byte string as it is encoded in this function.

        :param print_name: The print name string to set
        :param substitute_name: The substitute name string to set
        """
        print_bytes = print_name.encode('utf-16-le')
        sub_bytes = substitute_name.encode('utf-16-le')
        path_buffer = print_bytes + sub_bytes

        self['print_name_offset'].set_value(0)
        self['print_name_length'].set_value(len(print_bytes))
        self['substitute_name_offset'].set_value(len(print_bytes))
        self['substitute_name_length'].set_value(len(sub_bytes))
        self['path_buffer'].set_value(path_buffer)


Instruction:
Write a Python 3 script to
connect to the tree share.

Response:
def connect(self, require_secure_negotiate=True):
        """
        Connect to the share.

        :param require_secure_negotiate: For Dialects 3.0 and 3.0.2, will
            verify the negotiation parameters with the server to prevent
            SMB downgrade attacks
        """
        log.info("Session: %s - Creating connection to share %s"
                 % (self.session.username, self.share_name))
        utf_share_name = self.share_name.encode('utf-16-le')
        connect = SMB2TreeConnectRequest()
        connect['buffer'] = utf_share_name

        log.info("Session: %s - Sending Tree Connect message"
                 % self.session.username)
        log.debug(str(connect))
        request = self.session.connection.send(connect,
                                               sid=self.session.session_id)

        log.info("Session: %s - Receiving Tree Connect response"
                 % self.session.username)
        response = self.session.connection.receive(request)
        tree_response = SMB2TreeConnectResponse()
        tree_response.unpack(response['data'].get_value())
        log.debug(str(tree_response))

        # https://msdn.microsoft.com/en-us/library/cc246687.aspx
        self.tree_connect_id = response['tree_id'].get_value()
        log.info("Session: %s - Created tree connection with ID %d"
                 % (self.session.username, self.tree_connect_id))
        self._connected = True
        self.session.tree_connect_table[self.tree_connect_id] = self

        capabilities = tree_response['capabilities']
        self.is_dfs_share = capabilities.has_flag(
            ShareCapabilities.SMB2_SHARE_CAP_DFS)
        self.is_ca_share = capabilities.has_flag(
            ShareCapabilities.SMB2_SHARE_CAP_CONTINUOUS_AVAILABILITY)

        dialect = self.session.connection.dialect
        if dialect >= Dialects.SMB_3_0_0 and \
                self.session.connection.supports_encryption:
            self.encrypt_data = tree_response['share_flags'].has_flag(
                ShareFlags.SMB2_SHAREFLAG_ENCRYPT_DATA)

            self.is_scaleout_share = capabilities.has_flag(
                ShareCapabilities.SMB2_SHARE_CAP_SCALEOUT)

            # secure negotiate is only valid for SMB 3 dialects before 3.1.1
            if dialect < Dialects.SMB_3_1_1 and require_secure_negotiate:
                self._verify_dialect_negotiate()


Instruction:
Write a Python 3 function for
disconnecting the tree connection from the tree connection.

Response:
def disconnect(self):
        """
        Disconnects the tree connection.
        """
        if not self._connected:
            return

        log.info("Session: %s, Tree: %s - Disconnecting from Tree Connect"
                 % (self.session.username, self.share_name))

        req = SMB2TreeDisconnect()
        log.info("Session: %s, Tree: %s - Sending Tree Disconnect message"
                 % (self.session.username, self.share_name))
        log.debug(str(req))
        request = self.session.connection.send(req,
                                               sid=self.session.session_id,
                                               tid=self.tree_connect_id)

        log.info("Session: %s, Tree: %s - Receiving Tree Disconnect response"
                 % (self.session.username, self.share_name))
        res = self.session.connection.receive(request)
        res_disconnect = SMB2TreeDisconnect()
        res_disconnect.unpack(res['data'].get_value())
        log.debug(str(res_disconnect))
        self._connected = False
        del self.session.tree_connect_table[self.tree_connect_id]


Instruction:
Can you generate a brief explanation for the following Python 3 code
def connect(self, dialect=None, timeout=60):
        log.info("Setting up transport connection")
        self.transport.connect()

        log.info("Starting negotiation with SMB server")
        smb_response = self._send_smb2_negotiate(dialect, timeout)
        log.info("Negotiated dialect: %s"
                 % str(smb_response['dialect_revision']))
        self.dialect = smb_response['dialect_revision'].get_value()
        self.max_transact_size = smb_response['max_transact_size'].get_value()
        self.max_read_size = smb_response['max_read_size'].get_value()
        self.max_write_size = smb_response['max_write_size'].get_value()
        self.server_guid = smb_response['server_guid'].get_value()
        self.gss_negotiate_token = smb_response['buffer'].get_value()

        if not self.require_signing and \
                smb_response['security_mode'].has_flag(
                    SecurityMode.SMB2_NEGOTIATE_SIGNING_REQUIRED):
            self.require_signing = True
        log.info("Connection require signing: %s" % self.require_signing)
        capabilities = smb_response['capabilities']

        # SMB 2.1
        if self.dialect >= Dialects.SMB_2_1_0:
            self.supports_file_leasing = \
                capabilities.has_flag(Capabilities.SMB2_GLOBAL_CAP_LEASING)
            self.supports_multi_credit = \
                capabilities.has_flag(Capabilities.SMB2_GLOBAL_CAP_LARGE_MTU)

        # SMB 3.x
        if self.dialect >= Dialects.SMB_3_0_0:
            self.supports_directory_leasing = capabilities.has_flag(
                Capabilities.SMB2_GLOBAL_CAP_DIRECTORY_LEASING)
            self.supports_multi_channel = capabilities.has_flag(
                Capabilities.SMB2_GLOBAL_CAP_MULTI_CHANNEL)

            # TODO: SMB2_GLOBAL_CAP_PERSISTENT_HANDLES
            self.supports_persistent_handles = False
            self.supports_encryption = capabilities.has_flag(
                Capabilities.SMB2_GLOBAL_CAP_ENCRYPTION) \
                and self.dialect < Dialects.SMB_3_1_1
            self.server_capabilities = capabilities
            self.server_security_mode = \
                smb_response['security_mode'].get_value()

            # TODO: Check/add server to server_list in Client Page 203

        # SMB 3.1
        if self.dialect >= Dialects.SMB_3_1_1:
            for context in smb_response['negotiate_context_list']:
                if context['context_type'].get_value() == \
                        NegotiateContextType.SMB2_ENCRYPTION_CAPABILITIES:
                    cipher_id = context['data']['ciphers'][0]
                    self.cipher_id = Ciphers.get_cipher(cipher_id)
                    self.supports_encryption = self.cipher_id != 0
                else:
                    hash_id = context['data']['hash_algorithms'][0]
                    self.preauth_integrity_hash_id = \
                        HashAlgorithms.get_algorithm(hash_id)

Response: Connects to the server and negotiates the capabilities of the current server.


Instruction:
Can you tell what is the following Python 3 function doing
def disconnect(self, close=True):
        if close:
            for session in list(self.session_table.values()):
                session.disconnect(True)

        log.info("Disconnecting transport connection")
        self.transport.disconnect()

Response: Disconnects the connection to the transport and all the active session tables.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def send_compound(self, messages, sid, tid, related=False):
        send_data = b""
        session = self.session_table[sid]
        tree = session.tree_connect_table[tid]
        requests = []

        total_requests = len(messages)
        for i, message in enumerate(messages):
            if i == total_requests - 1:
                next_command = 0
                padding = b""
            else:
                msg_length = 64 + len(message)

                # each compound message must start at the 8-byte boundary
                mod = msg_length % 8
                padding_length = 8 - mod if mod > 0 else 0
                padding = b"\x00" * padding_length
                next_command = msg_length + padding_length

            header = self._generate_packet_header(message, sid, tid, None)
            header['next_command'] = next_command
            if i != 0 and related:
                header['session_id'] = b"\xff" * 8
                header['tree_id'] = b"\xff" * 4
                header['flags'].set_flag(
                    Smb2Flags.SMB2_FLAGS_RELATED_OPERATIONS
                )

            if session.signing_required and session.signing_key:
                self._sign(header, session, padding=padding)
            send_data += header.pack() + padding

            request = Request(header)
            requests.append(request)
            self.outstanding_requests[header['message_id'].get_value()] = \
                request

        if session.encrypt_data or tree.encrypt_data:
            send_data = self._encrypt(send_data, session)

        self.transport.send(send_data)

        return requests

Response: Sends multiple messages within one TCP request.


Instruction:
Write a Python 3 script for
polling the message buffer of the TCP connection and waits until a valid message is received based on the message_id passed in. :param request: The Request object to wait get the response for :param wait: Wait for the final response in the case of a STATUS_PENDING response, the pending response is returned in the case of wait=False :param timeout: Set a timeout used while waiting for a response from the server :return: SMB2HeaderResponse of the received message

Response:
def receive(self, request, wait=True, timeout=None):
        """
        Polls the message buffer of the TCP connection and waits until a valid
        message is received based on the message_id passed in.

        :param request: The Request object to wait get the response for
        :param wait: Wait for the final response in the case of a
            STATUS_PENDING response, the pending response is returned in the
            case of wait=False
        :param timeout: Set a timeout used while waiting for a response from
            the server
        :return: SMB2HeaderResponse of the received message
        """
        start_time = time.time()

        # check if we have received a response
        while True:
            self._flush_message_buffer()
            status = request.response['status'].get_value() if \
                request.response else None
            if status is not None and (wait and
                                       status != NtStatus.STATUS_PENDING):
                break
            current_time = time.time() - start_time
            if timeout and (current_time > timeout):
                error_msg = "Connection timeout of %d seconds exceeded while" \
                            " waiting for a response from the server" \
                            % timeout
                raise smbprotocol.exceptions.SMBException(error_msg)

        response = request.response
        status = response['status'].get_value()
        if status not in [NtStatus.STATUS_SUCCESS, NtStatus.STATUS_PENDING]:
            raise smbprotocol.exceptions.SMBResponseException(response, status)

        # now we have a retrieval request for the response, we can delete
        # the request from the outstanding requests
        message_id = request.message['message_id'].get_value()
        del self.outstanding_requests[message_id]

        return response


Instruction:
Write a Python 3 function that can
send an SMB2 Echo request to the server and return the number of credits that were granted by the server.

Response:
def echo(self, sid=0, timeout=60, credit_request=1):
        """
        Sends an SMB2 Echo request to the server. This can be used to request
        more credits from the server with the credit_request param.

        On a Samba server, the sid can be 0 but for a Windows SMB Server, the
        sid of an authenticated session must be passed into this function or
        else the socket will close.

        :param sid: When talking to a Windows host this must be populated with
            a valid session_id from a negotiated session
        :param timeout: The timeout in seconds to wait for the Echo Response
        :param credit_request: The number of credits to request
        :return: the credits that were granted by the server
        """
        log.info("Sending Echo request with a timeout of %d and credit "
                 "request of %d" % (timeout, credit_request))

        echo_msg = SMB2Echo()
        log.debug(str(echo_msg))
        req = self.send(echo_msg, sid=sid, credit_request=credit_request)

        log.info("Receiving Echo response")
        response = self.receive(req, timeout=timeout)
        log.info("Credits granted from the server echo response: %d"
                 % response['credit_response'].get_value())
        echo_resp = SMB2Echo()
        echo_resp.unpack(response['data'].get_value())
        log.debug(str(echo_resp))

        return response['credit_response'].get_value()


Instruction:
Write a Python 3 function that can
loop through the transport message_buffer until there are no messages left in the queue. Each response is assigned to the Request object based on the message_id which are then available in self.outstanding_requests

Response:
def _flush_message_buffer(self):
        """
        Loops through the transport message_buffer until there are no messages
        left in the queue. Each response is assigned to the Request object
        based on the message_id which are then available in
        self.outstanding_requests
        """
        while True:
            message_bytes = self.transport.receive()

            # there were no messages receives, so break from the loop
            if message_bytes is None:
                break

            # check if the message is encrypted and decrypt if necessary
            if message_bytes[:4] == b"\xfdSMB":
                message = SMB2TransformHeader()
                message.unpack(message_bytes)
                message_bytes = self._decrypt(message)

            # now retrieve message(s) from response
            is_last = False
            session_id = None
            while not is_last:
                next_command = struct.unpack("<L", message_bytes[20:24])[0]
                header_length = \
                    next_command if next_command != 0 else len(message_bytes)
                header_bytes = message_bytes[:header_length]
                message = SMB2HeaderResponse()
                message.unpack(header_bytes)

                flags = message['flags']
                if not flags.has_flag(Smb2Flags.SMB2_FLAGS_RELATED_OPERATIONS):
                    session_id = message['session_id'].get_value()

                self._verify(message, session_id)
                message_id = message['message_id'].get_value()
                request = self.outstanding_requests.get(message_id, None)
                if not request:
                    error_msg = "Received response with an unknown message " \
                                "ID: %d" % message_id
                    raise smbprotocol.exceptions.SMBException(error_msg)

                # add the upper credit limit based on the credits granted by
                # the server
                credit_response = message['credit_response'].get_value()
                self.sequence_window['high'] += \
                    credit_response if credit_response > 0 else 1

                request.response = message
                self.outstanding_requests[message_id] = request

                message_bytes = message_bytes[header_length:]
                is_last = next_command == 0


Instruction:
How would you implement a function in Python 3 that
calculates the credit charge for a request based on the command.

Response:
def _calculate_credit_charge(self, message):
        """
        Calculates the credit charge for a request based on the command. If
        connection.supports_multi_credit is not True then the credit charge
        isn't valid so it returns 0.

        The credit charge is the number of credits that are required for
        sending/receiving data over 64 kilobytes, in the existing messages only
        the Read, Write, Query Directory or IOCTL commands will end in this
        scenario and each require their own calculation to get the proper
        value. The generic formula for calculating the credit charge is

        https://msdn.microsoft.com/en-us/library/dn529312.aspx
        (max(SendPayloadSize, Expected ResponsePayloadSize) - 1) / 65536 + 1

        :param message: The message being sent
        :return: The credit charge to set on the header
        """
        credit_size = 65536

        if not self.supports_multi_credit:
            credit_charge = 0
        elif message.COMMAND == Commands.SMB2_READ:
            max_size = message['length'].get_value() + \
                       message['read_channel_info_length'].get_value() - 1
            credit_charge = math.ceil(max_size / credit_size)
        elif message.COMMAND == Commands.SMB2_WRITE:
            max_size = message['length'].get_value() + \
                       message['write_channel_info_length'].get_value() - 1
            credit_charge = math.ceil(max_size / credit_size)
        elif message.COMMAND == Commands.SMB2_IOCTL:
            max_in_size = len(message['buffer'])
            max_out_size = message['max_output_response'].get_value()
            max_size = max(max_in_size, max_out_size) - 1
            credit_charge = math.ceil(max_size / credit_size)
        elif message.COMMAND == Commands.SMB2_QUERY_DIRECTORY:
            max_in_size = len(message['buffer'])
            max_out_size = message['output_buffer_length'].get_value()
            max_size = max(max_in_size, max_out_size) - 1
            credit_charge = math.ceil(max_size / credit_size)
        else:
            credit_charge = 1

        # python 2 returns a float where we need an integer
        return int(credit_charge)


Instruction:
Explain what the following Python 3 code does
def disconnect(self, close=True):
        if not self._connected:
            # already disconnected so let's return
            return

        if close:
            for open in list(self.open_table.values()):
                open.close(False)

            for tree in list(self.tree_connect_table.values()):
                tree.disconnect()

        log.info("Session: %s - Logging off of SMB Session" % self.username)
        logoff = SMB2Logoff()
        log.info("Session: %s - Sending Logoff message" % self.username)
        log.debug(str(logoff))
        request = self.connection.send(logoff, sid=self.session_id)

        log.info("Session: %s - Receiving Logoff response" % self.username)
        res = self.connection.receive(request)
        res_logoff = SMB2Logoff()
        res_logoff.unpack(res['data'].get_value())
        log.debug(str(res_logoff))
        self._connected = False
        del self.connection.session_table[self.session_id]

Response: Logs off the session and closes all open and tree - connect tables.


Instruction:
Make a summary of the following Python 3 code
def _smb3kdf(self, ki, label, context):
        kdf = KBKDFHMAC(
            algorithm=hashes.SHA256(),
            mode=Mode.CounterMode,
            length=16,
            rlen=4,
            llen=4,
            location=CounterLocation.BeforeFixed,
            label=label,
            context=context,
            fixed=None,
            backend=default_backend()
        )
        return kdf.derive(ki)

Response: Derive the session key from the SMB 3. x key derivation function


Instruction:
Write a Python 3 script for
packing the value into a byte string so it can be sent to the server.

Response:
def pack(self):
        """
        Packs the field value into a byte string so it can be sent to the
        server.

        :param structure: The message structure class object
        :return: A byte string of the packed field's value
        """
        value = self._get_calculated_value(self.value)
        packed_value = self._pack_value(value)
        size = self._get_calculated_size(self.size, packed_value)
        if len(packed_value) != size:
            raise ValueError("Invalid packed data length for field %s of %d "
                             "does not fit field size of %d"
                             % (self.name, len(packed_value), size))

        return packed_value


Instruction:
Create a Python 3 function to
parse and sets the value attribute for the field.

Response:
def set_value(self, value):
        """
        Parses, and sets the value attribute for the field.

        :param value: The value to be parsed and set, the allowed input types
            vary depending on the Field used
        """
        parsed_value = self._parse_value(value)
        self.value = parsed_value


Instruction:
Can you write a function in Python 3 where it
takes in a byte string and sets the value based on the field s definition.

Response:
def unpack(self, data):
        """
        Takes in a byte string and set's the field value based on field
        definition.

        :param structure: The message structure class object
        :param data: The byte string of the data to unpack
        :return: The remaining data for subsequent fields
        """
        size = self._get_calculated_size(self.size, data)
        self.set_value(data[0:size])
        return data[len(self):]


Instruction:
Write a Python 3 function that can
get the final value of the field and runs the lambda functions recursively until a final value is derived.

Response:
def _get_calculated_value(self, value):
        """
        Get's the final value of the field and runs the lambda functions
        recursively until a final value is derived.

        :param value: The value to calculate/expand
        :return: The final value
        """
        if isinstance(value, types.LambdaType):
            expanded_value = value(self.structure)
            return self._get_calculated_value(expanded_value)
        else:
            # perform one final parsing of the value in case lambda value
            # returned a different type
            return self._parse_value(value)


Instruction:
Can you generate the documentation for the following Python 3 function
def _get_calculated_size(self, size, data):
        # if the size is derived from a lambda function, run it now; otherwise
        # return the value we passed in or the length of the data if the size
        # is None (last field value)
        if size is None:
            return len(data)
        elif isinstance(size, types.LambdaType):
            expanded_size = size(self.structure)
            return self._get_calculated_size(expanded_size, data)
        else:
            return size

Response:
Get the final size of the field and runs the lambda functions
        recursively until a final size is found.


Instruction:
Can you tell what is the following Python 3 function doing
def _get_struct_format(self, size):
        if isinstance(size, types.LambdaType):
            size = size(self.structure)

        struct_format = {
            1: 'B',
            2: 'H',
            4: 'L',
            8: 'Q'
        }
        if size not in struct_format.keys():
            raise InvalidFieldDefinition("Cannot struct format of size %s"
                                         % size)
        return struct_format[size]

Response: Get s the format specifier for use in struct.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def unpack_response(file_information_class, buffer):
        structs = smbprotocol.query_info
        resp_structure = {
            FileInformationClass.FILE_DIRECTORY_INFORMATION:
                structs.FileDirectoryInformation,
            FileInformationClass.FILE_NAMES_INFORMATION:
                structs.FileNamesInformation,
            FileInformationClass.FILE_BOTH_DIRECTORY_INFORMATION:
                structs.FileBothDirectoryInformation,
            FileInformationClass.FILE_ID_BOTH_DIRECTORY_INFORMATION:
                structs.FileIdBothDirectoryInformation,
            FileInformationClass.FILE_FULL_DIRECTORY_INFORMATION:
                structs.FileFullDirectoryInformation,
            FileInformationClass.FILE_ID_FULL_DIRECTORY_INFORMATION:
                structs.FileIdFullDirectoryInformation,
        }[file_information_class]
        query_results = []

        current_offset = 0
        is_next = True
        while is_next:
            result = resp_structure()
            result.unpack(buffer[current_offset:])
            query_results.append(result)
            current_offset += result['next_entry_offset'].get_value()
            is_next = result['next_entry_offset'].get_value() != 0

        return query_results

Response: Unpacks the SMB2QueryDirectoryResponse object into a list of query_info. structures.


Instruction:
Make a summary of the following Python 3 code
def create(self, impersonation_level, desired_access, file_attributes,
               share_access, create_disposition, create_options,
               create_contexts=None, send=True):
        """
        This will open the file based on the input parameters supplied. Any
        file open should also be called with Open.close() when it is finished.

        More details on how each option affects the open process can be found
        here https://msdn.microsoft.com/en-us/library/cc246502.aspx.

        Supports out of band send function, call this function with send=False
        to return a tuple of (SMB2CreateRequest, receive_func) instead of
        sending the the request and waiting for the response. The receive_func
        can be used to get the response from the server by passing in the
        Request that was used to sent it out of band.

        :param impersonation_level: (ImpersonationLevel) The type of
            impersonation level that is issuing the create request.
        :param desired_access: The level of access that is required of the
            open. FilePipePrinterAccessMask or DirectoryAccessMask should be
            used depending on the type of file being opened.
        :param file_attributes: (FileAttributes) attributes to set on the file
            being opened, this usually is for opens that creates a file.
        :param share_access: (ShareAccess) Specifies the sharing mode for the
            open.
        :param create_disposition: (CreateDisposition) Defines the action the
            server MUST take if the file already exists.
        :param create_options: (CreateOptions) Specifies the options to be
            applied when creating or opening the file.
        :param create_contexts: (List<SMB2CreateContextRequest>) List of
            context request values to be applied to the create.

        Create Contexts are used to encode additional flags and attributes when
        opening files. More details on create context request values can be
        found here https://msdn.microsoft.com/en-us/library/cc246504.aspx.

        :param send: Whether to send the request in the same call or return the
            message to the caller and the unpack function

        :return: List of context response values or None if there are no
            context response values. If the context response value is not known
            to smbprotocol then the list value would be raw bytes otherwise
            it is a Structure defined in create_contexts.py
        """
        create = SMB2CreateRequest()
        create['impersonation_level'] = impersonation_level
        create['desired_access'] = desired_access
        create['file_attributes'] = file_attributes
        create['share_access'] = share_access
        create['create_disposition'] = create_disposition
        create['create_options'] = create_options
        if self.file_name == "":
            create['buffer_path'] = b"\x00\x00"
        else:
            create['buffer_path'] = self.file_name.encode('utf-16-le')
        if create_contexts:
            create['buffer_contexts'] = smbprotocol.create_contexts.\
                SMB2CreateContextRequest.pack_multiple(create_contexts)

        if self.connection.dialect >= Dialects.SMB_3_0_0:
            self.desired_access = desired_access
            self.share_mode = share_access
            self.create_options = create_options
            self.file_attributes = file_attributes
            self.create_disposition = create_disposition

        if not send:
            return create, self._create_response

        log.info("Session: %s, Tree Connect: %s - sending SMB2 Create Request "
                 "for file %s" % (self.tree_connect.session.username,
                                  self.tree_connect.share_name,
                                  self.file_name))

        log.debug(str(create))
        request = self.connection.send(create,
                                       self.tree_connect.session.session_id,
                                       self.tree_connect.tree_connect_id)
        return self._create_response(request)

Response: This method creates an Any ArcGIS file and returns a tuple of SMB2CreateRequest and SMB2CreateResponse.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def read(self, offset, length, min_length=0, unbuffered=False, wait=True,
             send=True):
        """
        Reads from an opened file or pipe

        Supports out of band send function, call this function with send=False
        to return a tuple of (SMB2ReadRequest, receive_func) instead of
        sending the the request and waiting for the response. The receive_func
        can be used to get the response from the server by passing in the
        Request that was used to sent it out of band.

        :param offset: The offset to start the read of the file.
        :param length: The number of bytes to read from the offset.
        :param min_length: The minimum number of bytes to be read for a
            successful operation.
        :param unbuffered: Whether to the server should cache the read data at
            intermediate layers, only value for SMB 3.0.2 or newer
        :param wait: If send=True, whether to wait for a response if
            STATUS_PENDING was received from the server or fail.
        :param send: Whether to send the request in the same call or return the
            message to the caller and the unpack function
        :return: A byte string of the bytes read
        """
        if length > self.connection.max_read_size:
            raise SMBException("The requested read length %d is greater than "
                               "the maximum negotiated read size %d"
                               % (length, self.connection.max_read_size))

        read = SMB2ReadRequest()
        read['length'] = length
        read['offset'] = offset
        read['minimum_count'] = min_length
        read['file_id'] = self.file_id
        read['padding'] = b"\x50"

        if unbuffered:
            if self.connection.dialect < Dialects.SMB_3_0_2:
                raise SMBUnsupportedFeature(self.connection.dialect,
                                            Dialects.SMB_3_0_2,
                                            "SMB2_READFLAG_READ_UNBUFFERED",
                                            True)
            read['flags'].set_flag(ReadFlags.SMB2_READFLAG_READ_UNBUFFERED)

        if not send:
            return read, self._read_response

        log.info("Session: %s, Tree Connect ID: %s - sending SMB2 Read "
                 "Request for file %s" % (self.tree_connect.session.username,
                                          self.tree_connect.share_name,
                                          self.file_name))
        log.debug(str(read))
        request = self.connection.send(read,
                                       self.tree_connect.session.session_id,
                                       self.tree_connect.tree_connect_id)
        return self._read_response(request, wait)

Response: Reads from an opened file or pipe and returns a byte string containing the read data.


Instruction:
Can you tell what is the following Python 3 function doing
def write(self, data, offset=0, write_through=False, unbuffered=False,
              wait=True, send=True):
        """
        Writes data to an opened file.

        Supports out of band send function, call this function with send=False
        to return a tuple of (SMBWriteRequest, receive_func) instead of
        sending the the request and waiting for the response. The receive_func
        can be used to get the response from the server by passing in the
        Request that was used to sent it out of band.

        :param data: The bytes data to write.
        :param offset: The offset in the file to write the bytes at
        :param write_through: Whether written data is persisted to the
            underlying storage, not valid for SMB 2.0.2.
        :param unbuffered: Whether to the server should cache the write data at
            intermediate layers, only value for SMB 3.0.2 or newer
        :param wait: If send=True, whether to wait for a response if
            STATUS_PENDING was received from the server or fail.
        :param send: Whether to send the request in the same call or return the
            message to the caller and the unpack function
        :return: The number of bytes written
        """
        data_len = len(data)
        if data_len > self.connection.max_write_size:
            raise SMBException("The requested write length %d is greater than "
                               "the maximum negotiated write size %d"
                               % (data_len, self.connection.max_write_size))

        write = SMB2WriteRequest()
        write['length'] = len(data)
        write['offset'] = offset
        write['file_id'] = self.file_id
        write['buffer'] = data

        if write_through:
            if self.connection.dialect < Dialects.SMB_2_1_0:
                raise SMBUnsupportedFeature(self.connection.dialect,
                                            Dialects.SMB_2_1_0,
                                            "SMB2_WRITEFLAG_WRITE_THROUGH",
                                            True)
            write['flags'].set_flag(WriteFlags.SMB2_WRITEFLAG_WRITE_THROUGH)

        if unbuffered:
            if self.connection.dialect < Dialects.SMB_3_0_2:
                raise SMBUnsupportedFeature(self.connection.dialect,
                                            Dialects.SMB_3_0_2,
                                            "SMB2_WRITEFLAG_WRITE_UNBUFFERED",
                                            True)
            write['flags'].set_flag(WriteFlags.SMB2_WRITEFLAG_WRITE_UNBUFFERED)

        if not send:
            return write, self._write_response

        log.info("Session: %s, Tree Connect: %s - sending SMB2 Write Request "
                 "for file %s" % (self.tree_connect.session.username,
                                  self.tree_connect.share_name,
                                  self.file_name))
        log.debug(str(write))
        request = self.connection.send(write,
                                       self.tree_connect.session.session_id,
                                       self.tree_connect.tree_connect_id)
        return self._write_response(request, wait)

Response: Writes data to an opened file.


Instruction:
How would you code a function in Python 3 to
send a SMB2FlushRequest to the server to flush all cached file information for the opened file.

Response:
def flush(self, send=True):
        """
        A command sent by the client to request that a server flush all cached
        file information for the opened file.

        Supports out of band send function, call this function with send=False
        to return a tuple of (SMB2FlushRequest, receive_func) instead of
        sending the the request and waiting for the response. The receive_func
        can be used to get the response from the server by passing in the
        Request that was used to sent it out of band.

        :param send: Whether to send the request in the same call or return the
            message to the caller and the unpack function
        :return: The SMB2FlushResponse received from the server
        """
        flush = SMB2FlushRequest()
        flush['file_id'] = self.file_id

        if not send:
            return flush, self._flush_response

        log.info("Session: %s, Tree Connect: %s - sending SMB2 Flush Request "
                 "for file %s" % (self.tree_connect.session.username,
                                  self.tree_connect.share_name,
                                  self.file_name))
        log.debug(str(flush))
        request = self.connection.send(flush,
                                       self.tree_connect.session.session_id,
                                       self.tree_connect.tree_connect_id)
        return self._flush_response(request)


Instruction:
Write a Python 3 function for
closing an opened file.

Response:
def close(self, get_attributes=False, send=True):
        """
        Closes an opened file.

        Supports out of band send function, call this function with send=False
        to return a tuple of (SMB2CloseRequest, receive_func) instead of
        sending the the request and waiting for the response. The receive_func
        can be used to get the response from the server by passing in the
        Request that was used to sent it out of band.

        :param get_attributes: (Bool) whether to get the latest attributes on
            the close and set them on the Open object
        :param send: Whether to send the request in the same call or return the
            message to the caller and the unpack function
        :return: SMB2CloseResponse message received from the server
        """
        # it is already closed and this isn't for an out of band request
        if not self._connected and send:
            return

        close = SMB2CloseRequest()

        close['file_id'] = self.file_id
        if get_attributes:
            close['flags'] = CloseFlags.SMB2_CLOSE_FLAG_POSTQUERY_ATTRIB

        if not send:
            return close, self._close_response

        log.info("Session: %s, Tree Connect: %s - sending SMB2 Close Request "
                 "for file %s" % (self.tree_connect.session.username,
                                  self.tree_connect.share_name,
                                  self.file_name))
        log.debug(str(close))
        request = self.connection.send(close,
                                       self.tree_connect.session.session_id,
                                       self.tree_connect.tree_connect_id)
        return self._close_response(request)


Instruction:
Write a Python 3 function for
using to set the structure parameters based on the input string :param sid_string: String of the sid in S-x-x-x-x form

Response:
def from_string(self, sid_string):
        """
        Used to set the structure parameters based on the input string

        :param sid_string: String of the sid in S-x-x-x-x form
        """
        if not sid_string.startswith("S-"):
            raise ValueError("A SID string must start with S-")

        sid_entries = sid_string.split("-")
        if len(sid_entries) < 3:
            raise ValueError("A SID string must start with S and contain a "
                             "revision and identifier authority, e.g. S-1-0")

        revision = int(sid_entries[1])
        id_authority = int(sid_entries[2])
        sub_authorities = [int(i) for i in sid_entries[3:]]

        self['revision'].set_value(revision)
        self['identifier_authority'].set_value(id_authority)
        self['sub_authorities'] = sub_authorities


Instruction:
Here you have a function in Python 3, explain what it does
def poll(self):
        if not self.status["done"]:
            r = Request("get", self.url + ".json", {"token": self.payload["token"]})
            for param, when in MessageRequest.params.iteritems():
                self.status[param] = bool(r.answer[param])
                self.status[when] = int(r.answer[when])
            for param in ["acknowledged_by", "acknowledged_by_device"]:
                self.status[param] = r.answer[param]
            self.status["last_delivered_at"] = int(r.answer["last_delivered_at"])
            if any(self.status[param] for param in MessageRequest.params):
                self.status["done"] = True
        return self.status["done"]

Response: This method is used to poll the status of the current message.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def sounds(self):
        if not Pushover._SOUNDS:
            request = Request("get", SOUND_URL, {"token": self.token})
            Pushover._SOUNDS = request.answer["sounds"]
        return Pushover._SOUNDS

Response:
Return a dictionary of sounds recognized by Pushover and that can be
        used in a notification message.


Instruction:
Can you create a Python 3 function that
sends a message to the user specified by user.

Response:
def message(self, user, message, **kwargs):
        """Send `message` to the user specified by `user`. It is possible
        to specify additional properties of the message by passing keyword
        arguments. The list of valid keywords is ``title, priority, sound,
        callback, timestamp, url, url_title, device, retry, expire and html``
        which are described in the Pushover API documentation.

        For convenience, you can simply set ``timestamp=True`` to set the
        timestamp to the current timestamp.

        An image can be attached to a message by passing a file-like object
        to the `attachment` keyword argument.

        This method returns a :class:`MessageRequest` object.
        """

        payload = {"message": message, "user": user, "token": self.token}
        for key, value in kwargs.iteritems():
            if key not in Pushover.message_keywords:
                raise ValueError("{0}: invalid message parameter".format(key))
            elif key == "timestamp" and value is True:
                payload[key] = int(time.time())
            elif key == "sound" and value not in self.sounds:
                raise ValueError("{0}: invalid sound".format(value))
            else:
                payload[key] = value

        return MessageRequest(payload)


Instruction:
How would you code a function in Python 3 to
send a glance to the user.

Response:
def glance(self, user, **kwargs):
        """Send a glance to the user. The default property is ``text``, as this
        is used on most glances, however a valid glance does not need to
        require text and can be constructed using any combination of valid
        keyword properties. The list of valid keywords is ``title, text,
        subtext, count, percent and device`` which are  described in the
        Pushover Glance API documentation.

        This method returns a :class:`GlanceRequest` object.
        """
        payload = {"user": user, "token": self.token}

        for key, value in kwargs.iteritems():
            if key not in Pushover.glance_keywords:
                raise ValueError("{0}: invalid glance parameter".format(key))
            else:
                payload[key] = value

        return Request("post", GLANCE_URL, payload)


Instruction:
Here you have a function in Python 3, explain what it does
def mswe(w, v):
    # Ensure inputs are numpy arrays
    w = np.array(w)
    v = np.array(v)
    # Check dimensions
    if(len(w.shape) != 2):
        raise TypeError('Estimated coefficients must be in NxM matrix')
    if(len(v.shape) != 1):
        raise TypeError('Real coefficients must be in 1d array')
    # Ensure equal length between estimated and real coeffs
    N, M = w.shape
    L = v.size
    if(M < L):
        v = v[:-(L-M)]
    elif(M > L):
        v = np.concatenate((v, np.zeros(M-L)))

    # Calculate and return MSWE
    mswe = np.mean((w - v)**2, axis=1)
    return mswe

Response: Calculates the mean squared weight error between estimated and true filter coefficients in respect to iterations.


Instruction:
Write a Python 3 script to
perform normalized least-mean-squares (NLMS) adaptive filtering on u to minimize error given by e=d-y, where y is the output of the adaptive filter. Parameters ---------- u : array-like One-dimensional filter input. d : array-like One-dimensional desired signal, i.e., the output of the unknown FIR system which the adaptive filter should identify. Must have length >= len(u), or N+M-1 if number of iterations are limited (via the N parameter). M : int Desired number of filter taps (desired filter order + 1), must be non-negative. step : float Step size of the algorithm, must be non-negative. Optional Parameters ------------------- eps : float Regularization factor to avoid numerical issues when power of input is close to zero. Defaults to 0.001. Must be non-negative. leak : float Leakage factor, must be equal to or greater than zero and smaller than one. When greater than zero a leaky LMS filter is used. Defaults to 0, i.e., no leakage. initCoeffs : array-like Initial filter coefficients to use. Should match desired number of filter taps, defaults to zeros. N : int Number of iterations to run. Must be less than or equal to len(u)-M+1. Defaults to len(u)-M+1. returnCoeffs : boolean If true, will return all filter coefficients for every iteration in an N x M matrix. Does not include the initial coefficients. If false, only the latest coefficients in a vector of length M is returned. Defaults to false. Returns ------- y : numpy.array Output values of LMS filter, array of length N. e : numpy.array Error signal, i.e, d-y. Array of length N. w : numpy.array Final filter coefficients in array of length M if returnCoeffs is False. NxM array containing all filter coefficients for all iterations otherwise. Raises ------ TypeError If number of filter taps M is not type integer, number of iterations N is not type integer, or leakage leak is not type float/int. ValueError If number of iterations N is greater than len(u)-M, number of filter taps M is negative, or if step-size or leakage is outside specified range. Minimal Working Example ----------------------- >>> import numpy as np >>> >>> np.random.seed(1337) >>> ulen = 2000 >>> coeff = np.concatenate(([4], np.zeros(10), [-11], np.zeros(7), [0.7])) >>> u = np.random.randn(ulen) >>> d = np.convolve(u, coeff) >>> >>> M = 20 # No. of taps >>> step = 1 # Step size >>> y, e, w = nlms(u, d, M, step) >>> print np.allclose(w, coeff) True Extended Example ---------------- >>> import numpy as np >>> >>> np.random.seed(1337) >>> N = 1000 >>> coeffs = np.concatenate(([13], np.zeros(9), [-3], np.zeros(8), [-.2])) >>> u = np.random.randn(20000) # Note len(u) >> N but we limit iterations >>> d = np.convolve(u, coeffs) >>> >>> M = 20 # No. of taps >>> step = 1 # Step size >>> y, e, w = nlms(u, d, M, step, N=N, returnCoeffs=True) >>> y.shape == (N,) True >>> e.shape == (N,) True >>> w.shape == (N, M) True >>> # Calculate mean square weight error >>> mswe = np.mean((w - coeffs)**2, axis=1) >>> # Should never increase so diff should above be > 0 >>> diff = np.diff(mswe) >>> (diff <= 1e-10).all() True

Response:
def nlms(u, d, M, step, eps=0.001, leak=0, initCoeffs=None, N=None,
         returnCoeffs=False):
    """
    Perform normalized least-mean-squares (NLMS) adaptive filtering on u to
    minimize error given by e=d-y, where y is the output of the adaptive
    filter.

    Parameters
    ----------
    u : array-like
        One-dimensional filter input.
    d : array-like
        One-dimensional desired signal, i.e., the output of the unknown FIR
        system which the adaptive filter should identify. Must have length >=
        len(u), or N+M-1 if number of iterations are limited (via the N
        parameter).
    M : int
        Desired number of filter taps (desired filter order + 1), must be
        non-negative.
    step : float
        Step size of the algorithm, must be non-negative.

    Optional Parameters
    -------------------
    eps : float
        Regularization factor to avoid numerical issues when power of input
        is close to zero. Defaults to 0.001. Must be non-negative.
    leak : float
        Leakage factor, must be equal to or greater than zero and smaller than
        one. When greater than zero a leaky LMS filter is used. Defaults to 0,
        i.e., no leakage.
    initCoeffs : array-like
        Initial filter coefficients to use. Should match desired number of
        filter taps, defaults to zeros.
    N : int
        Number of iterations to run. Must be less than or equal to len(u)-M+1.
        Defaults to len(u)-M+1.
    returnCoeffs : boolean
        If true, will return all filter coefficients for every iteration in an
        N x M matrix. Does not include the initial coefficients. If false, only
        the latest coefficients in a vector of length M is returned. Defaults
        to false.

    Returns
    -------
    y : numpy.array
        Output values of LMS filter, array of length N.
    e : numpy.array
        Error signal, i.e, d-y. Array of length N.
    w : numpy.array
        Final filter coefficients in array of length M if returnCoeffs is
        False. NxM array containing all filter coefficients for all iterations
        otherwise.

    Raises
    ------
    TypeError
        If number of filter taps M is not type integer, number of iterations N
        is not type integer, or leakage leak is not type float/int.
    ValueError
        If number of iterations N is greater than len(u)-M, number of filter
        taps M is negative, or if step-size or leakage is outside specified
        range.

    Minimal Working Example
    -----------------------
    >>> import numpy as np
    >>>
    >>> np.random.seed(1337)
    >>> ulen = 2000
    >>> coeff = np.concatenate(([4], np.zeros(10), [-11], np.zeros(7), [0.7]))
    >>> u = np.random.randn(ulen)
    >>> d = np.convolve(u, coeff)
    >>>
    >>> M = 20  # No. of taps
    >>> step = 1  # Step size
    >>> y, e, w = nlms(u, d, M, step)
    >>> print np.allclose(w, coeff)
    True

    Extended Example
    ----------------
    >>> import numpy as np
    >>>
    >>> np.random.seed(1337)
    >>> N = 1000
    >>> coeffs = np.concatenate(([13], np.zeros(9), [-3], np.zeros(8), [-.2]))
    >>> u = np.random.randn(20000)  # Note len(u) >> N but we limit iterations
    >>> d = np.convolve(u, coeffs)
    >>>
    >>> M = 20  # No. of taps
    >>> step = 1  # Step size
    >>> y, e, w = nlms(u, d, M, step, N=N, returnCoeffs=True)
    >>> y.shape == (N,)
    True
    >>> e.shape == (N,)
    True
    >>> w.shape == (N, M)
    True
    >>> # Calculate mean square weight error
    >>> mswe = np.mean((w - coeffs)**2, axis=1)
    >>> # Should never increase so diff should above be > 0
    >>> diff = np.diff(mswe)
    >>> (diff <= 1e-10).all()
    True
    """
    # Check epsilon
    _pchk.checkRegFactor(eps)
    # Num taps check
    _pchk.checkNumTaps(M)
    # Max iteration check
    if N is None:
        N = len(u)-M+1
    _pchk.checkIter(N, len(u)-M+1)
    # Check len(d)
    _pchk.checkDesiredSignal(d, N, M)
    # Step check
    _pchk.checkStep(step)
    # Leakage check
    _pchk.checkLeakage(leak)
    # Init. coeffs check
    if initCoeffs is None:
        initCoeffs = np.zeros(M)
    else:
        _pchk.checkInitCoeffs(initCoeffs, M)

    # Initialization
    y = np.zeros(N)  # Filter output
    e = np.zeros(N)  # Error signal
    w = initCoeffs  # Initial filter coeffs
    leakstep = (1 - step*leak)
    if returnCoeffs:
        W = np.zeros((N, M))  # Matrix to hold coeffs for each iteration

    # Perform filtering
    for n in xrange(N):
        x = np.flipud(u[n:n+M])  # Slice to get view of M latest datapoints
        y[n] = np.dot(x, w)
        e[n] = d[n+M-1] - y[n]

        normFactor = 1./(np.dot(x, x) + eps)
        w = leakstep * w + step * normFactor * x * e[n]
        y[n] = np.dot(x, w)
        if returnCoeffs:
            W[n] = w

    if returnCoeffs:
        w = W

    return y, e, w


Instruction:
Can you generate the documentation for the following Python 3 function
def ap(u, d, M, step, K, eps=0.001, leak=0, initCoeffs=None, N=None,
       returnCoeffs=False):
    """
    Perform affine projection (AP) adaptive filtering on u to minimize error
    given by e=d-y, where y is the output of the adaptive filter.

    Parameters
    ----------
    u : array-like
        One-dimensional filter input.
    d : array-like
        One-dimensional desired signal, i.e., the output of the unknown FIR
        system which the adaptive filter should identify. Must have length >=
        len(u), or N+M-1 if number of iterations are limited (via the N
        parameter).
    M : int
        Desired number of filter taps (desired filter order + 1), must be
        non-negative.
    step : float
        Step size of the algorithm, must be non-negative.
    K : int
        Projection order, must be integer larger than zero.

    Optional Parameters
    -------------------
    eps : float
        Regularization factor to avoid numerical issues when power of input
        is close to zero. Defaults to 0.001. Must be non-negative.
    leak : float
        Leakage factor, must be equal to or greater than zero and smaller than
        one. When greater than zero a leaky LMS filter is used. Defaults to 0,
        i.e., no leakage.
    initCoeffs : array-like
        Initial filter coefficients to use. Should match desired number of
        filter taps, defaults to zeros.
    N : int
        Number of iterations to run. Must be less than or equal to len(u)-M+1.
        Defaults to len(u)-M+1.
    returnCoeffs : boolean
        If true, will return all filter coefficients for every iteration in an
        N x M matrix. Does not include the initial coefficients. If false, only
        the latest coefficients in a vector of length M is returned. Defaults
        to false.

    Returns
    -------
    y : numpy.array
        Output values of LMS filter, array of length N.
    e : numpy.array
        Error signal, i.e, d-y. Array of length N.
    w : numpy.array
        Final filter coefficients in array of length M if returnCoeffs is
        False. NxM array containing all filter coefficients for all iterations
        otherwise.

    Raises
    ------
    TypeError
        If number of filter taps M is not type integer, number of iterations N
        is not type integer, or leakage leak is not type float/int.
    ValueError
        If number of iterations N is greater than len(u)-M, number of filter
        taps M is negative, or if step-size or leakage is outside specified
        range.

    Minimal Working Example
    -----------------------
    >>> import numpy as np
    >>>
    >>> np.random.seed(1337)
    >>> ulen = 2000
    >>> coeff = np.concatenate(([4], np.zeros(10), [-11], np.zeros(7), [0.7]))
    >>> u = np.random.randn(ulen)
    >>> d = np.convolve(u, coeff)
    >>>
    >>> M = 20  # No. of taps
    >>> step = 1  # Step size
    >>> K = 5  # Projection order
    >>> y, e, w = ap(u, d, M, step, K)
    >>> print np.allclose(w, coeff)
    True

    Extended Example
    ----------------
    >>> import numpy as np
    >>>
    >>> np.random.seed(1337)
    >>> N = 1000
    >>> coeffs = np.concatenate(([13], np.zeros(9), [-3], np.zeros(8), [-.2]))
    >>> u = np.random.randn(20000)  # Note: len(u) >> N but we limit iterations
    >>> d = np.convolve(u, coeffs)
    >>>
    >>> M = 20  # No. of taps
    >>> step = 1  # Step size
    >>> K = 5  # Projection order
    >>> y, e, w = ap(u, d, M, step, K, N=N, returnCoeffs=True)
    >>> y.shape == (N,)
    True
    >>> e.shape == (N,)
    True
    >>> w.shape == (N, M)
    True
    >>> # Calculate mean square weight error
    >>> mswe = np.mean((w - coeffs)**2, axis=1)
    >>> # Should never increase so diff should above be > 0
    >>> diff = np.diff(mswe)
    >>> (diff <= 1e-10).all()
    True
    """
    # Check epsilon
    _pchk.checkRegFactor(eps)
    # Check projection order
    _pchk.checkProjectOrder(K)
    # Num taps check
    _pchk.checkNumTaps(M)
    # Max iteration check
    if N is None:
        N = len(u)-M-K+1
    _pchk.checkIter(N, len(u)-M+1)
    # Check len(d)
    _pchk.checkDesiredSignal(d, N, M)
    # Step check
    _pchk.checkStep(step)
    # Leakage check
    _pchk.checkLeakage(leak)
    # Init. coeffs check
    if initCoeffs is None:
        initCoeffs = np.zeros(M)
    else:
        _pchk.checkInitCoeffs(initCoeffs, M)

    # Initialization
    y_out = np.zeros(N)  # Filter output
    e_out = np.zeros(N)  # Error signal
    w = initCoeffs  # Initial filter coeffs
    I = np.identity(K)  # Init. identity matrix for faster loop matrix inv.
    epsI = eps * np.identity(K)  # Init. epsilon identiy matrix
    leakstep = (1 - step*leak)

    if returnCoeffs:
        W = np.zeros((N, M))  # Matrix to hold coeffs for each iteration

    # Perform filtering
    for n in xrange(N):
        # Generate U matrix and D vector with current data
        U = np.zeros((M, K))
        for k in np.arange(K):
            U[:, (K-k-1)] = u[n+k:n+M+k]
        U = np.flipud(U)
        D = np.flipud(d[n+M-1:n+M+K-1])

        # Filter
        y = np.dot(U.T, w)
        e = D - y

        y_out[n] = y[0]
        e_out[n] = e[0]

        # Normalization factor
        normFactor = np.linalg.solve(epsI + np.dot(U.T, U), I)
        # Naive alternative
        # normFactor = np.linalg.inv(epsI + np.dot(U.T, U))

        w = leakstep * w + step * np.dot(U, np.dot(normFactor, e))

        if returnCoeffs:
            W[n] = w

    if returnCoeffs:
        w = W

    return y_out, e_out, w

Response: This function performs an affine projection on u to minimize error by analytical adaptive filter given by e = d - y.


Instruction:
Write a Python 3 function for
executing a bugreport command on the current page of the adb device and save it to dest_file

Response:
def bugreport(dest_file="default.log"):
    """
    Prints dumpsys, dumpstate, and logcat data to the screen, for the purposes of bug reporting
    :return: result of _exec_command() execution
    """
    adb_full_cmd = [v.ADB_COMMAND_PREFIX, v.ADB_COMMAND_BUGREPORT]
    try:
        dest_file_handler = open(dest_file, "w")
    except IOError:
        print("IOError: Failed to create a log file")

    # We have to check if device is available or not before executing this command
    # as adb bugreport will wait-for-device infinitely and does not come out of
    # loop
    # Execute only if device is available only
    if _isDeviceAvailable():
        result = _exec_command_to_file(adb_full_cmd, dest_file_handler)
        return (result, "Success: Bug report saved to: " + dest_file)
    else:
        return (0, "Device Not Found")


Instruction:
Can you generate the documentation for the following Python 3 function
def push(src, dest):
    adb_full_cmd = [v.ADB_COMMAND_PREFIX, v.ADB_COMMAND_PUSH, src, dest]
    return _exec_command(adb_full_cmd)

Response: Push object from host to target


Instruction:
Can you generate a brief explanation for the following Python 3 code
def pull(src, dest):
    adb_full_cmd = [v.ADB_COMMAND_PREFIX, v.ADB_COMMAND_PULL, src, dest]
    return _exec_command(adb_full_cmd)

Response: Pull object from target to host


Instruction:
Implement a Python 3 function for
getting list of all available devices including emulators

Response:
def devices(opts=[]):
    """
    Get list of all available devices including emulators
    :param opts: list command options (e.g. ["-r", "-a"])
    :return: result of _exec_command() execution
    """
    adb_full_cmd = [v.ADB_COMMAND_PREFIX, v.ADB_COMMAND_DEVICES, _convert_opts(opts)]
    return _exec_command(adb_full_cmd)


Instruction:
How would you implement a function in Python 3 that
executes shell command on target

Response:
def shell(cmd):
    """
    Execute shell command on target
    :param cmd: string shell command to execute
    :return: result of _exec_command() execution
    """
    adb_full_cmd = [v.ADB_COMMAND_PREFIX, v.ADB_COMMAND_SHELL, cmd]
    return _exec_command(adb_full_cmd)


Instruction:
Can you implement a function in Python 3 that
installs a single. apk on the target

Response:
def install(apk, opts=[]):
    """
    Install *.apk on target
    :param apk: string path to apk on host to install
    :param opts: list command options (e.g. ["-r", "-a"])
    :return: result of _exec_command() execution
    """
    adb_full_cmd = [v.ADB_COMMAND_PREFIX, v.ADB_COMMAND_INSTALL, _convert_opts(opts), apk]
    return _exec_command(adb_full_cmd)


Instruction:
Here you have a function in Python 3, explain what it does
def sync():
    adb_full_cmd = [v.ADB_COMMAND_PREFIX, v.ADB_COMMAND_SHELL ,v.ADB_COMMAND_SYNC]
    return _exec_command(adb_full_cmd)

Response: Execute the sync command.


Instruction:
Create a Python 3 function for
executing adb command and return output

Response:
def _exec_command(adb_cmd):
    """
    Format adb command and execute it in shell
    :param adb_cmd: list adb command to execute
    :return: string '0' and shell command output if successful, otherwise
    raise CalledProcessError exception and return error code
    """
    t = tempfile.TemporaryFile()
    final_adb_cmd = []
    for e in adb_cmd:
        if e != '':  # avoid items with empty string...
            final_adb_cmd.append(e)  # ... so that final command doesn't
            # contain extra spaces
    print('\n*** Executing ' + ' '.join(adb_cmd) + ' ' + 'command')

    try:
        output = check_output(final_adb_cmd, stderr=t)
    except CalledProcessError as e:
        t.seek(0)
        result = e.returncode, t.read()
    else:
        result = 0, output
        print('\n' + result[1])

    return result


Instruction:
Can you tell what is the following Python 3 function doing
def _exec_command_to_file(adb_cmd, dest_file_handler):
    t = tempfile.TemporaryFile()
    final_adb_cmd = []
    for e in adb_cmd:
        if e != '':  # avoid items with empty string...
            final_adb_cmd.append(e)  # ... so that final command doesn't
            # contain extra spaces
    print('\n*** Executing ' + ' '.join(adb_cmd) + ' ' + 'command')

    try:
        output = call(final_adb_cmd, stdout=dest_file_handler, stderr=t)
    except CalledProcessError as e:
        t.seek(0)
        result = e.returncode, t.read()
    else:
        result = output
        dest_file_handler.close()

    return result

Response: Execute a list of adb commands and writes the output to a file handler.


Instruction:
Write a Python 3 script to
detect if the data was changed. This is added in 1. 6.

Response:
def has_changed(self, initial, data):
        "Detects if the data was changed. This is added in 1.6."
        if initial is None and data is None:
            return False
        if data and not hasattr(data, '__iter__'):
            data = self.widget.decompress(data)
        initial = self.to_python(initial)
        data = self.to_python(data)
        if hasattr(self, '_coerce'):
            data = self._coerce(data)
        if isinstance(data, Model) and isinstance(initial, Model):
            return model_vars(data) != model_vars(initial)
        else:
            return data != initial


Instruction:
How would you explain what the following Python 3 function does
def results_decorator(func):
    # Wrap function to maintian the original doc string, etc
    @wraps(func)
    def decorator(lookup_cls):
        # Construct a class decorator from the original function
        original = lookup_cls.results
        def inner(self, request):
            # Wrap lookup_cls.results by first calling func and checking the result
            result = func(request)
            if isinstance(result, HttpResponse):
                return result
            return original(self, request)
        # Replace original lookup_cls.results with wrapped version
        lookup_cls.results = inner
        return lookup_cls
    # Return the constructed decorator
    return decorator

Response: A decorator that returns a function which returns a HttpResponse object or a Lookup. results.


Instruction:
Here you have a function in Python 3, explain what it does
def staff_member_required(request):
    "Lookup decorator to require the user is a staff member."
    user = getattr(request, 'user', None)
    if user is None or not user.is_authenticated:
        return HttpResponse(status=401) # Unauthorized
    elif not user.is_staff:
        return HttpResponseForbidden()

Response: Lookup decorator to require the user is a staff member.


Instruction:
Make a summary of the following Python 3 code
def format_item(self, item):
        "Construct result dictionary for the match item."
        result = {
            'id': self.get_item_id(item),
            'value': self.get_item_value(item),
            'label': self.get_item_label(item),
        }
        for key in settings.SELECTABLE_ESCAPED_KEYS:
            if key in result:
                result[key] = conditional_escape(result[key])
        return result

Response: Construct result dictionary for the match item.


Instruction:
Can you generate the documentation for the following Python 3 function
def paginate_results(self, results, options):
        "Return a django.core.paginator.Page of results."
        limit = options.get('limit', settings.SELECTABLE_MAX_LIMIT)
        paginator = Paginator(results, limit)
        page = options.get('page', 1)
        try:
            results = paginator.page(page)
        except (EmptyPage, InvalidPage):
            results = paginator.page(paginator.num_pages)
        return results

Response: Return a django. core. paginator. Page of results.


Instruction:
Make a summary of the following Python 3 code
def results(self, request):
        "Match results to given term and return the serialized HttpResponse."
        results = {}
        form = self.form(request.GET)
        if form.is_valid():
            options = form.cleaned_data
            term = options.get('term', '')
            raw_data = self.get_query(request, term)
            results = self.format_results(raw_data, options)
        return self.response(results)

Response: Match results to given term and return the serialized HttpResponse.


Instruction:
Write a Python 3 script to
return a python structure that later gets serialized. raw_data full list of objects matching the search term full list of objects matching the search term a dictionary of the given options a dictionary of the given options

Response:
def format_results(self, raw_data, options):
        '''
        Returns a python structure that later gets serialized.
        raw_data
            full list of objects matching the search term
        options
            a dictionary of the given options
        '''
        page_data = self.paginate_results(raw_data, options)
        results = {}
        meta = options.copy()
        meta['more'] = _('Show more results')
        if page_data and page_data.has_next():
            meta['next_page'] = page_data.next_page_number()
        if page_data and page_data.has_previous():
            meta['prev_page'] = page_data.previous_page_number()
        results['data'] = [self.format_item(item) for item in page_data.object_list]
        results['meta'] = meta
        return results


Instruction:
Explain what the following Python 3 code does
def import_lookup_class(lookup_class):
    from selectable.base import LookupBase
    if isinstance(lookup_class, string_types):
        mod_str, cls_str = lookup_class.rsplit('.', 1)
        mod = import_module(mod_str)
        lookup_class = getattr(mod, cls_str)
    if not issubclass(lookup_class, LookupBase):
        raise TypeError('lookup_class must extend from selectable.base.LookupBase')
    return lookup_class

Response: Imports lookup_class as a dotted base and ensure it extends LookupBase


Instruction:
Write a Python 3 function for
ensuring given limit is less than default if defined

Response:
def clean_limit(self):
        "Ensure given limit is less than default if defined"
        limit = self.cleaned_data.get('limit', None)
        if (settings.SELECTABLE_MAX_LIMIT is not None and
            (not limit or limit > settings.SELECTABLE_MAX_LIMIT)):
            limit = settings.SELECTABLE_MAX_LIMIT
        return limit


Instruction:
Can you implement a function in Python 3 that
parses the results from the API.

Response:
async def parseResults(self, api_data):
    """ See CoverSource.parseResults. """
    results = []

    # parse HTML and get results
    parser = lxml.etree.HTMLParser()
    html = lxml.etree.XML(api_data.decode("latin-1"), parser)

    for rank, result in enumerate(__class__.RESULTS_SELECTOR(html), 1):
      # extract url
      metadata_div = result.find("div")
      metadata_json = lxml.etree.tostring(metadata_div, encoding="unicode", method="text")
      metadata_json = json.loads(metadata_json)
      google_url = result.find("a").get("href")
      if google_url is not None:
        query = urllib.parse.urlsplit(google_url).query
      else:
        query = None
      if not query:
        img_url = metadata_json["ou"]
      else:
        query = urllib.parse.parse_qs(query)
        img_url = query["imgurl"][0]
      # extract format
      check_metadata = CoverImageMetadata.NONE
      format = metadata_json["ity"].lower()
      try:
        format = SUPPORTED_IMG_FORMATS[format]
      except KeyError:
        # format could not be identified or is unknown
        format = None
        check_metadata = CoverImageMetadata.FORMAT
      # extract size
      if not query:
        size = metadata_json["ow"], metadata_json["oh"]
      else:
        size = tuple(map(int, (query["w"][0], query["h"][0])))
      # extract thumbnail url
      thumbnail_url = metadata_json["tu"]
      # result
      results.append(GoogleImagesCoverSourceResult(img_url,
                                                   size,
                                                   format,
                                                   thumbnail_url=thumbnail_url,
                                                   source=self,
                                                   rank=rank,
                                                   check_metadata=check_metadata))

    return results


Instruction:
Can you tell what is the following Python 3 function doing
async def waitAccessAsync(self):
    async with self.lock:
      while True:
        last_access_ts = self.__getLastAccess()
        if last_access_ts is not None:
          now = time.time()
          last_access_ts = last_access_ts[0]
          time_since_last_access = now - last_access_ts
          if time_since_last_access < self.min_delay_between_accesses:
            time_to_wait = self.min_delay_between_accesses - time_since_last_access
            if self.jitter_range_ms is not None:
              time_to_wait += random.randint(*self.jitter_range_ms) / 1000
            self.logger.debug("Sleeping for %.2fms because of rate limit for domain %s" % (time_to_wait * 1000,
                                                                                self.domain))
            await asyncio.sleep(time_to_wait)

        access_time = time.time()
        self.__access(access_time)

        # now we should be good... except if another process did the same query at the same time
        # the database serves as an atomic lock, query again to be sure the last row is the one
        # we just inserted
        last_access_ts = self.__getLastAccess()
        if last_access_ts[0] == access_time:
          break

Response: Wait for the request to be granted to the API.


Instruction:
Can you implement a function in Python 3 that
records an API access.

Response:
def __access(self, ts):
    """ Record an API access. """
    with self.connection:
      self.connection.execute("INSERT OR REPLACE INTO access_timestamp (timestamp, domain) VALUES (?, ?)",
                              (ts, self.domain))


Instruction:
Can you tell what is the following Python 3 function doing
def aiohttp_socket_timeout(socket_timeout_s):
  return aiohttp.ClientTimeout(total=None,
                               connect=None,
                               sock_connect=socket_timeout_s,
                               sock_read=socket_timeout_s)

Response: Return a new aiohttp. ClientTimeout object with only socket timeouts set.


Instruction:
How would you explain what the following Python 3 function does
async def query(self, url, *, post_data=None, headers=None, verify=True, cache=None, pre_cache_callback=None):
    async def store_in_cache_callback():
      pass
    if cache is not None:
      # try from cache first
      if post_data is not None:
        if (url, post_data) in cache:
          self.logger.debug("Got data for URL '%s' %s from cache" % (url, dict(post_data)))
          return store_in_cache_callback, cache[(url, post_data)]
      elif url in cache:
        self.logger.debug("Got data for URL '%s' from cache" % (url))
        return store_in_cache_callback, cache[url]

    domain_rate_watcher = rate_watcher.AccessRateWatcher(self.watcher_db_filepath,
                                                         url,
                                                         self.min_delay_between_accesses,
                                                         jitter_range_ms=self.jitter_range_ms,
                                                         logger=self.logger)

    for attempt, time_to_sleep in enumerate(redo.retrier(max_attempts=HTTP_MAX_ATTEMPTS,
                                                         sleeptime=1,
                                                         max_sleeptime=HTTP_MAX_RETRY_SLEEP_S,
                                                         sleepscale=1.5),
                                            1):
      await domain_rate_watcher.waitAccessAsync()

      try:
        if post_data is not None:
          async with self.session.post(url,
                                       data=post_data,
                                       headers=self._buildHeaders(headers),
                                       timeout=HTTP_NORMAL_TIMEOUT,
                                       ssl=verify) as response:
            content = await response.read()
        else:
          async with self.session.get(url,
                                      headers=self._buildHeaders(headers),
                                      timeout=HTTP_NORMAL_TIMEOUT,
                                      ssl=verify) as response:
            content = await response.read()

        if cache is not None:
          async def store_in_cache_callback():
            if pre_cache_callback is not None:
              # process
              try:
                data = await pre_cache_callback(content)
              except Exception:
                data = content
            else:
              data = content

            # add to cache
            if post_data is not None:
              cache[(url, post_data)] = data
            else:
              cache[url] = data

      except (asyncio.TimeoutError, aiohttp.ClientError) as e:
        self.logger.warning("Querying '%s' failed (attempt %u/%u): %s %s" % (url,
                                                                             attempt,
                                                                             HTTP_MAX_ATTEMPTS,
                                                                             e.__class__.__qualname__,
                                                                             e))
        if attempt == HTTP_MAX_ATTEMPTS:
          raise
        else:
          self.logger.debug("Retrying in %.3fs" % (time_to_sleep))
          await asyncio.sleep(time_to_sleep)

      else:
        break  # http retry loop

    response.raise_for_status()

    return store_in_cache_callback, content

Response: Send a GET or POST request to the specified URL.


Instruction:
Can you tell what is the following Python 3 function doing
async def isReachable(self, url, *, headers=None, verify=True, response_headers=None, cache=None):
    if (cache is not None) and (url in cache):
      # try from cache first
      self.logger.debug("Got headers for URL '%s' from cache" % (url))
      resp_ok, response_headers = pickle.loads(cache[url])
      return resp_ok

    domain_rate_watcher = rate_watcher.AccessRateWatcher(self.watcher_db_filepath,
                                                         url,
                                                         self.min_delay_between_accesses,
                                                         jitter_range_ms=self.jitter_range_ms,
                                                         logger=self.logger)
    resp_ok = True
    try:
      for attempt, time_to_sleep in enumerate(redo.retrier(max_attempts=HTTP_MAX_ATTEMPTS,
                                                           sleeptime=0.5,
                                                           max_sleeptime=HTTP_MAX_RETRY_SLEEP_SHORT_S,
                                                           sleepscale=1.5),
                                              1):
        await domain_rate_watcher.waitAccessAsync()

        try:
          async with self.session.head(url,
                                       headers=self._buildHeaders(headers),
                                       timeout=HTTP_SHORT_TIMEOUT,
                                       ssl=verify) as response:
            pass

        except (asyncio.TimeoutError, aiohttp.ClientError) as e:
          self.logger.warning("Probing '%s' failed (attempt %u/%u): %s %s" % (url,
                                                                              attempt,
                                                                              HTTP_MAX_ATTEMPTS,
                                                                              e.__class__.__qualname__,
                                                                              e))
          if attempt == HTTP_MAX_ATTEMPTS:
            resp_ok = False
          else:
            self.logger.debug("Retrying in %.3fs" % (time_to_sleep))
            await asyncio.sleep(time_to_sleep)

        else:
          response.raise_for_status()

          if response_headers is not None:
            response_headers.update(response.headers)

          break  # http retry loop

    except aiohttp.ClientResponseError as e:
      self.logger.debug("Probing '%s' failed: %s %s" % (url, e.__class__.__qualname__, e))
      resp_ok = False

    if cache is not None:
      # store in cache
      cache[url] = pickle.dumps((resp_ok, response_headers))

    return resp_ok

Response: Send a HEAD request to the given URL and return True if the request is successful.


Instruction:
Make a summary of the following Python 3 code
async def fastStreamedQuery(self, url, *, headers=None, verify=True):
    response = await self.session.get(url,
                                      headers=self._buildHeaders(headers),
                                      timeout=HTTP_SHORT_TIMEOUT,
                                      ssl=verify)

    response.raise_for_status()

    return response

Response: Send a GET request with short timeout do not retry and return streamed response.


Instruction:
How would you implement a function in Python 3 that
processes a query string.

Response:
def processQueryString(self, s):
    """ See CoverSource.processQueryString. """
    char_blacklist = set(string.punctuation)
    char_blacklist.remove("'")
    char_blacklist.remove("&")
    char_blacklist = frozenset(char_blacklist)
    return __class__.unpunctuate(s.lower(), char_blacklist=char_blacklist)