Instruction:
Write a Python 3 function that can
spawn the receiver loop.

Response:
def _spawn_receiver_loop(self):
        """Spawns the reader loop.  This is called internall by
        socketio_manage().
        """
        job = gevent.spawn(self._receiver_loop)
        self.jobs.append(job)
        return job


Instruction:
Write a Python 3 script for
watching out if we ve been disconnected and kill all the jobs.

Response:
def _watcher(self):
        """Watch out if we've been disconnected, in that case, kill
        all the jobs.

        """
        while True:
            gevent.sleep(1.0)
            if not self.connected:
                for ns_name, ns in list(six.iteritems(self.active_ns)):
                    ns.recv_disconnect()
                # Killing Socket-level jobs
                gevent.killall(self.jobs)
                break


Instruction:
Here you have a function in Python 3, explain what it does
def _heartbeat(self):
        interval = self.config['heartbeat_interval']
        while self.connected:
            gevent.sleep(interval)
            # TODO: this process could use a timeout object like the disconnect
            #       timeout thing, and ONLY send packets when none are sent!
            #       We would do that by calling timeout.set() for a "sending"
            #       timeout.  If we're sending 100 messages a second, there is
            #       no need to push some heartbeats in there also.
            self.put_client_msg("2::")

Response: Start the heartbeat Greenlet to check connection health.


Instruction:
Given the following Python 3 function, write the documentation
def encode(data, json_dumps=default_json_dumps):
    payload = ''
    msg = str(MSG_TYPES[data['type']])

    if msg in ['0', '1']:
        # '1::' [path] [query]
        msg += '::' + data['endpoint']
        if 'qs' in data and data['qs'] != '':
            msg += ':' + data['qs']

    elif msg == '2':
        # heartbeat
        msg += '::'

    elif msg in ['3', '4', '5']:
        # '3:' [id ('+')] ':' [endpoint] ':' [data]
        # '4:' [id ('+')] ':' [endpoint] ':' [json]
        # '5:' [id ('+')] ':' [endpoint] ':' [json encoded event]
        # The message id is an incremental integer, required for ACKs.
        # If the message id is followed by a +, the ACK is not handled by
        # socket.io, but by the user instead.
        if msg == '3':
            payload = data['data']
        if msg == '4':
            payload = json_dumps(data['data'])
        if msg == '5':
            d = {}
            d['name'] = data['name']
            if 'args' in data and data['args'] != []:
                d['args'] = data['args']
            payload = json_dumps(d)
        if 'id' in data:
            msg += ':' + str(data['id'])
            if data['ack'] == 'data':
                msg += '+'
            msg += ':'
        else:
            msg += '::'
        if 'endpoint' not in data:
            data['endpoint'] = ''
        if payload != '':
            msg += data['endpoint'] + ':' + payload
        else:
            msg += data['endpoint']

    elif msg == '6':
        # '6:::' [id] '+' [data]
        msg += '::' + data.get('endpoint', '') + ':' + str(data['ackId'])
        if 'args' in data and data['args'] != []:
            msg += '+' + json_dumps(data['args'])

    elif msg == '7':
        # '7::' [endpoint] ':' [reason] '+' [advice]
        msg += ':::'
        if 'reason' in data and data['reason'] != '':
            msg += str(ERROR_REASONS[data['reason']])
        if 'advice' in data and data['advice'] != '':
            msg += '+' + str(ERROR_ADVICES[data['advice']])
        msg += data['endpoint']

    # NoOp, used to close a poll after the polling duration time
    elif msg == '8':
        msg += '::'

    return msg

Response: Encode an attribute dict into a byte string.


Instruction:
Can you tell what is the following Python 3 function doing
def decode(rawstr, json_loads=default_json_loads):
    decoded_msg = {}
    try:
        # Handle decoding in Python<3.
        rawstr = rawstr.decode('utf-8')
    except AttributeError:
        pass
    split_data = rawstr.split(":", 3)
    msg_type = split_data[0]
    msg_id = split_data[1]
    endpoint = split_data[2]

    data = ''

    if msg_id != '':
        if "+" in msg_id:
            msg_id = msg_id.split('+')[0]
            decoded_msg['id'] = int(msg_id)
            decoded_msg['ack'] = 'data'
        else:
            decoded_msg['id'] = int(msg_id)
            decoded_msg['ack'] = True

    # common to every message
    msg_type_id = int(msg_type)
    if msg_type_id in MSG_VALUES:
        decoded_msg['type'] = MSG_VALUES[int(msg_type)]
    else:
        raise Exception("Unknown message type: %s" % msg_type)

    decoded_msg['endpoint'] = endpoint

    if len(split_data) > 3:
        data = split_data[3]

    if msg_type == "0":  # disconnect
        pass

    elif msg_type == "1":  # connect
        decoded_msg['qs'] = data

    elif msg_type == "2":  # heartbeat
        pass

    elif msg_type == "3":  # message
        decoded_msg['data'] = data

    elif msg_type == "4":  # json msg
        decoded_msg['data'] = json_loads(data)

    elif msg_type == "5":  # event
        try:
            data = json_loads(data)
        except ValueError:
            print("Invalid JSON event message", data)
            decoded_msg['args'] = []
        else:
            decoded_msg['name'] = data.pop('name')
            if 'args' in data:
                decoded_msg['args'] = data['args']
            else:
                decoded_msg['args'] = []

    elif msg_type == "6":  # ack
        if '+' in data:
            ackId, data = data.split('+')
            decoded_msg['ackId'] = int(ackId)
            decoded_msg['args'] = json_loads(data)
        else:
            decoded_msg['ackId'] = int(data)
            decoded_msg['args'] = []

    elif msg_type == "7":  # error
        if '+' in data:
            reason, advice = data.split('+')
            decoded_msg['reason'] = REASONS_VALUES[int(reason)]
            decoded_msg['advice'] = ADVICES_VALUES[int(advice)]
        else:
            decoded_msg['advice'] = ''
            if data != '':
                decoded_msg['reason'] = REASONS_VALUES[int(data)]
            else:
                decoded_msg['reason'] = ''

    elif msg_type == "8":  # noop
        pass

    return decoded_msg

Response: Decode a rawstr packet arriving from the socket into a dict.


Instruction:
How would you explain what the following Python 3 function does
def add_acl_method(self, method_name):

        if isinstance(self.allowed_methods, set):
            self.allowed_methods.add(method_name)
        else:
            self.allowed_methods = set([method_name])

Response: Add a method to the list of allowed methods


Instruction:
Can you generate the documentation for the following Python 3 function
def del_acl_method(self, method_name):
        if self.allowed_methods is None:
            raise ValueError(
                "Trying to delete an ACL method, but none were"
                + " defined yet! Or: No ACL restrictions yet, why would you"
                + " delete one?"
            )

        self.allowed_methods.remove(method_name)

Response: Delete an ACL method from the ACL system.


Instruction:
Given the following Python 3 function, write the documentation
def process_packet(self, packet):
        packet_type = packet['type']

        if packet_type == 'event':
            return self.process_event(packet)
        elif packet_type == 'message':
            return self.call_method_with_acl('recv_message', packet,
                                             packet['data'])
        elif packet_type == 'json':
            return self.call_method_with_acl('recv_json', packet,
                                             packet['data'])
        elif packet_type == 'connect':
            self.socket.send_packet(packet)
            return self.call_method_with_acl('recv_connect', packet)
        elif packet_type == 'error':
            return self.call_method_with_acl('recv_error', packet)
        elif packet_type == 'ack':
            callback = self.socket._pop_ack_callback(packet['ackId'])
            if not callback:
                print("ERROR: No such callback for ackId %s" % packet['ackId'])
                return
            return callback(*(packet['args']))
        elif packet_type == 'disconnect':
            # Force a disconnect on the namespace.
            return self.call_method_with_acl('recv_disconnect', packet)
        else:
            print("Unprocessed packet", packet)

Response: This method processes a single packet and calls the appropriate method.


Instruction:
Here you have a function in Python 3, explain what it does
def call_method_with_acl(self, method_name, packet, *args):
        if not self.is_method_allowed(method_name):
            self.error('method_access_denied',
                       'You do not have access to method "%s"' % method_name)
            return

        return self.call_method(method_name, packet, *args)

Response: Calls the method with ACLs


Instruction:
How would you explain what the following Python 3 function does
def call_method(self, method_name, packet, *args):
        method = getattr(self, method_name, None)
        if method is None:
            self.error('no_such_method',
                       'The method "%s" was not found' % method_name)
            return

        specs = inspect.getargspec(method)
        func_args = specs.args
        if not len(func_args) or func_args[0] != 'self':
            self.error("invalid_method_args",
                "The server-side method is invalid, as it doesn't "
                "have 'self' as its first argument")
            return

        # Check if we need to decorate to handle exceptions
        if hasattr(self, 'exception_handler_decorator'):
            method = self.exception_handler_decorator(method)

        if len(func_args) == 2 and func_args[1] == 'packet':
            return method(packet)
        else:
            return method(*args)

Response:
This function is used to implement the two behaviors on dispatched
        on_* and recv_* methods.


Instruction:
Write a Python 3 function for
using this to send an error message to your application.

Response:
def error(self, error_name, error_message, msg_id=None, quiet=False):
        """Use this to use the configured ``error_handler`` yield an
        error message to your application.

        :param error_name: is a short string, to associate messages to recovery
                           methods
        :param error_message: is some human-readable text, describing the error
        :param msg_id: is used to associate with a request
        :param quiet: specific to error_handlers. The default doesn't send a
                      message to the user, but shows a debug message on the
                      developer console.
        """
        self.socket.error(error_name, error_message, endpoint=self.ns_name,
                          msg_id=msg_id, quiet=quiet)


Instruction:
Make a summary of the following Python 3 code
def send(self, message, json=False, callback=None):
        pkt = dict(type="message", data=message, endpoint=self.ns_name)
        if json:
            pkt['type'] = "json"

        if callback:
            # By passing ack=True, we use the old behavior of being returned
            # an 'ack' packet, automatically triggered by the client-side
            # with no user-code being run.  The emit() version of the
            # callback is more useful I think :)  So migrate your code.
            pkt['ack'] = True
            pkt['id'] = msgid = self.socket._get_next_msgid()
            self.socket._save_ack_callback(msgid, callback)

        self.socket.send_packet(pkt)

Response: Use send to send a simple string message.


Instruction:
How would you implement a function in Python 3 that
sends an event to the remote end.

Response:
def emit(self, event, *args, **kwargs):
        """Use this to send a structured event, with a name and arguments, to
        the client.

        By default, it uses this namespace's endpoint. You can send messages on
        other endpoints with something like:

            ``self.socket['/other_endpoint'].emit()``.

        However, it is possible that the ``'/other_endpoint'`` was not
        initialized yet, and that would yield a ``KeyError``.

        The only supported ``kwargs`` is ``callback``.  All other parameters
        must be passed positionally.

        :param event: The name of the event to trigger on the other end.
        :param callback: Pass in the callback keyword argument to define a
                         call-back that will be called when the client acks.

                         This callback is slightly different from the one from
                         ``send()``, as this callback will receive parameters
                         from the explicit call of the ``ack()`` function
                         passed to the listener on the client side.

                         The remote listener will need to explicitly ack (by
                         calling its last argument, a function which is
                         usually called 'ack') with some parameters indicating
                         success or error.  The 'ack' packet coming back here
                         will then trigger the callback function with the
                         returned values.
        :type callback: callable
        """
        callback = kwargs.pop('callback', None)

        if kwargs:
            raise ValueError(
                "emit() only supports positional argument, to stay "
                "compatible with the Socket.IO protocol. You can "
                "however pass in a dictionary as the first argument")
        pkt = dict(type="event", name=event, args=args,
                   endpoint=self.ns_name)

        if callback:
            # By passing 'data', we indicate that we *want* an explicit ack
            # by the client code, not an automatic as with send().
            pkt['ack'] = 'data'
            pkt['id'] = msgid = self.socket._get_next_msgid()
            self.socket._save_ack_callback(msgid, callback)

        self.socket.send_packet(pkt)


Instruction:
Make a summary of the following Python 3 code
def spawn(self, fn, *args, **kwargs):
        # self.log.debug("Spawning sub-Namespace Greenlet: %s" % fn.__name__)
        if hasattr(self, 'exception_handler_decorator'):
            fn = self.exception_handler_decorator(fn)
        new = gevent.spawn(fn, *args, **kwargs)
        self.jobs.append(new)
        return new

Response: Spawn a new process attached to this namespace.


Instruction:
Create a Python 3 function for
sending a disconnect packet to the server and remove the local jobs from the Socket.

Response:
def disconnect(self, silent=False):
        """Send a 'disconnect' packet, so that the user knows it has been
        disconnected (booted actually).  This will trigger an onDisconnect()
        call on the client side.

        Over here, we will kill all ``spawn``ed processes and remove the
        namespace from the Socket object.

        :param silent: do not actually send the packet (if they asked for a
                       disconnect for example), but just kill all jobs spawned
                       by this Namespace, and remove it from the Socket.
        """
        if not silent:
            packet = {"type": "disconnect",
                      "endpoint": self.ns_name}
            self.socket.send_packet(packet)
        # remove_namespace might throw GreenletExit so
        # kill_local_jobs must be in finally
        try:
            self.socket.remove_namespace(self.ns_name)
        finally:
            self.kill_local_jobs()


Instruction:
Write a Python 3 function for
returning an existing or new client Socket.

Response:
def get_socket(self, sessid=''):
        """Return an existing or new client Socket."""

        socket = self.sockets.get(sessid)

        if sessid and not socket:
            return None  # you ask for a session that doesn't exist!
        if socket is None:
            socket = Socket(self, self.config)
            self.sockets[socket.sessid] = socket
        else:
            socket.incr_hits()

        return socket


Instruction:
Can you tell what is the following Python 3 function doing
def create():
    name = request.form.get("name")
    if name:
        room, created = get_or_create(ChatRoom, name=name)
        return redirect(url_for('room', slug=room.slug))
    return redirect(url_for('rooms'))

Response: Handles the Create room form on the homepage and generates a new room.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def autodiscover():
    global LOADING_SOCKETIO
    if LOADING_SOCKETIO:
        return
    LOADING_SOCKETIO = True

    import imp
    from django.conf import settings

    for app in settings.INSTALLED_APPS:

        try:
            app_path = import_module(app).__path__
        except AttributeError:
            continue

        try:
            imp.find_module('sockets', app_path)
        except ImportError:
            continue

        import_module("%s.sockets" % app)

    LOADING_SOCKETIO = False

Response: Auto - discover INSTALLED_APPS sockets. py modules and fail silently when there is no socketio module.


Instruction:
Create a Python 3 function for
encoding a list of messages to be unicode.

Response:
def encode_payload(self, messages):
        """Encode list of messages. Expects messages to be unicode.

        ``messages`` - List of raw messages to encode, if necessary

        """
        if not messages or messages[0] is None:
            return ''

        if len(messages) == 1:
            return messages[0].encode('utf-8')

        payload = u''.join([(u'\ufffd%d\ufffd%s' % (len(p), p))
                            for p in messages if p is not None])
        # FIXME: why is it so that we must filter None from here ?  How
        #        is it even possible that a None gets in there ?

        return payload.encode('utf-8')


Instruction:
Given the following Python 3 function, write the documentation
def broadcast_event(self, event, *args):
        pkt = dict(type="event",
                   name=event,
                   args=args,
                   endpoint=self.ns_name)

        for sessid, socket in six.iteritems(self.socket.server.sockets):
            socket.send_packet(pkt)

Response: Broadcasts an event to all the sockets in this particular Namespace.


Instruction:
Implement a Python 3 function for
adding a parent to this role and add itself to the parent s children set.

Response:
def add_parent(self, parent):
        """Add a parent to this role,
        and add role itself to the parent's children set.
        you should override this function if neccessary.

        Example::

            logged_user = RoleMixin('logged_user')
            student = RoleMixin('student')
            student.add_parent(logged_user)

        :param parent: Parent role to add in.
        """
        parent.children.add(self)
        self.parents.add(parent)


Instruction:
Can you implement a function in Python 3 that
adds allowing rules. :param role: Role of this rule. :param method: Method to allow in rule, include GET, POST, PUT etc. :param resource: Resource also view function. :param with_children: Allow role's children in rule as well if with_children is `True`

Response:
def allow(self, role, method, resource, with_children=True):
        """Add allowing rules.

        :param role: Role of this rule.
        :param method: Method to allow in rule, include GET, POST, PUT etc.
        :param resource: Resource also view function.
        :param with_children: Allow role's children in rule as well
                              if with_children is `True`
        """
        if with_children:
            for r in role.get_children():
                permission = (r.get_name(), method, resource)
                if permission not in self._allowed:
                    self._allowed.append(permission)
        if role == 'anonymous':
            permission = (role, method, resource)
        else:
            permission = (role.get_name(), method, resource)
        if permission not in self._allowed:
            self._allowed.append(permission)


Instruction:
Make a summary of the following Python 3 code
def deny(self, role, method, resource, with_children=False):
        if with_children:
            for r in role.get_children():
                permission = (r.get_name(), method, resource)
                if permission not in self._denied:
                    self._denied.append(permission)
        permission = (role.get_name(), method, resource)
        if permission not in self._denied:
            self._denied.append(permission)

Response:
Add denying rules.

        :param role: Role of this rule.
        :param method: Method to deny in rule, include GET, POST, PUT etc.
        :param resource: Resource also view function.
        :param with_children: Deny role's children in rule as well
                              if with_children is `True`


Instruction:
How would you explain what the following Python 3 function does
def exempt(self, resource):
        if resource not in self._exempt:
            self._exempt.append(resource)

Response: Exempt a view function from being checked permission


Instruction:
Make a summary of the following Python 3 code
def is_allowed(self, role, method, resource):
        return (role, method, resource) in self._allowed

Response: Check whether role is allowed to access resource


Instruction:
Can you tell what is the following Python 3 function doing
def is_denied(self, role, method, resource):
        return (role, method, resource) in self._denied

Response: Check wherther role is denied to access resource


Instruction:
Here you have a function in Python 3, explain what it does
def init_app(self, app):

        app.config.setdefault('RBAC_USE_WHITE', False)
        self.use_white = app.config['RBAC_USE_WHITE']

        if not hasattr(app, 'extensions'):
            app.extensions = {}
        app.extensions['rbac'] = _RBACState(self, app)

        self.acl.allow(anonymous, 'GET', 'static')
        app.before_first_request(self._setup_acl)

        app.before_request(self._authenticate)

Response: Initialize application in Flask - RBAC.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def has_permission(self, method, endpoint, user=None):
        app = self.get_app()
        _user = user or self._user_loader()
        if not hasattr(_user, 'get_roles'):
            roles = [anonymous]
        else:
            roles = _user.get_roles()
        return self._check_permission(roles, method, endpoint)

Response: Return True if the current user can access the resource.


Instruction:
Can you write a function in Python 3 where it
removes all binary files in the adslib directory.

Response:
def remove_binaries():
    """Remove all binary files in the adslib directory."""
    patterns = (
        "adslib/*.a",
        "adslib/*.o",
        "adslib/obj/*.o",
        "adslib/*.bin",
        "adslib/*.so",
    )

    for f in functools.reduce(operator.iconcat, [glob.glob(p) for p in patterns]):
        os.remove(f)


Instruction:
Make a summary of the following Python 3 code
def router_function(fn):
    # type: (Callable) -> Callable
    """Raise a runtime error if on Win32 systems.

    Decorator.

    Decorator for functions that interact with the router for the Linux
    implementation of the ADS library.

    Unlike the Windows implementation which uses a separate router daemon,
    the Linux library manages AMS routing in-process. As such, routing must be
    configured programatically via. the provided API. These endpoints are
    invalid on Win32 systems, so an exception will be raised.

    """

    @wraps(fn)
    def wrapper(*args, **kwargs):
        # type: (Any, Any) -> Callable
        if platform_is_windows():  # pragma: no cover, skipt Windows test
            raise RuntimeError(
                "Router interface is not available on Win32 systems.\n"
                "Configure AMS routes using the TwinCAT router service."
            )
        return fn(*args, **kwargs)

    return wrapper

Response: Decorator for TwinCAT router functions.


Instruction:
Make a summary of the following Python 3 code
def adsAddRoute(net_id, ip_address):
    # type: (SAmsNetId, str) -> None
    """Establish a new route in the AMS Router.

    :param pyads.structs.SAmsNetId net_id: net id of routing endpoint
    :param str ip_address: ip address of the routing endpoint

    """
    add_route = _adsDLL.AdsAddRoute
    add_route.restype = ctypes.c_long

    # Convert ip address to bytes (PY3) and get pointer.
    ip_address_p = ctypes.c_char_p(ip_address.encode("utf-8"))

    error_code = add_route(net_id, ip_address_p)

    if error_code:
        raise ADSError(error_code)

Response: Establish a new route in the AMS Router.


Instruction:
Can you implement a function in Python 3 that
connects to the TwinCAT message router.

Response:
def adsPortOpenEx():
    # type: () -> int
    """Connect to the TwinCAT message router.

    :rtype: int
    :return: port number

    """
    port_open_ex = _adsDLL.AdsPortOpenEx
    port_open_ex.restype = ctypes.c_long
    port = port_open_ex()

    if port == 0:
        raise RuntimeError("Failed to open port on AMS router.")

    return port


Instruction:
How would you implement a function in Python 3 that
closes the connection to the TwinCAT message router.

Response:
def adsPortCloseEx(port):
    # type: (int) -> None
    """Close the connection to the TwinCAT message router."""
    port_close_ex = _adsDLL.AdsPortCloseEx
    port_close_ex.restype = ctypes.c_long
    error_code = port_close_ex(port)

    if error_code:
        raise ADSError(error_code)


Instruction:
How would you explain what the following Python 3 function does
def adsGetLocalAddressEx(port):
    # type: (int) -> AmsAddr
    """Return the local AMS-address and the port number.

    :rtype: pyads.structs.AmsAddr
    :return: AMS-address

    """
    get_local_address_ex = _adsDLL.AdsGetLocalAddressEx
    ams_address_struct = SAmsAddr()
    error_code = get_local_address_ex(port, ctypes.pointer(ams_address_struct))

    if error_code:
        raise ADSError(error_code)

    local_ams_address = AmsAddr()
    local_ams_address._ams_addr = ams_address_struct

    return local_ams_address

Response: Returns the local AMS - address and the port number.


Instruction:
Write a Python 3 script for
reading the current ADS-state and the machine-state. Read the current ADS-state and the machine-state from the ADS-server. :param pyads.structs.AmsAddr address: local or remote AmsAddr :rtype: (int, int) :return: ads_state, device_state

Response:
def adsSyncReadStateReqEx(port, address):
    # type: (int, AmsAddr) -> Tuple[int, int]
    """Read the current ADS-state and the machine-state.

    Read the current ADS-state and the machine-state from the
    ADS-server.

    :param pyads.structs.AmsAddr address: local or remote AmsAddr
    :rtype: (int, int)
    :return: ads_state, device_state

    """
    sync_read_state_request = _adsDLL.AdsSyncReadStateReqEx

    # C pointer to ams address struct
    ams_address_pointer = ctypes.pointer(address.amsAddrStruct())

    # Current ADS status and corresponding pointer
    ads_state = ctypes.c_int()
    ads_state_pointer = ctypes.pointer(ads_state)

    # Current device status and corresponding pointer
    device_state = ctypes.c_int()
    device_state_pointer = ctypes.pointer(device_state)

    error_code = sync_read_state_request(
        port, ams_address_pointer, ads_state_pointer, device_state_pointer
    )

    if error_code:
        raise ADSError(error_code)

    return (ads_state.value, device_state.value)


Instruction:
How would you implement a function in Python 3 that
reads the name and version number of the ADS - server.

Response:
def adsSyncReadDeviceInfoReqEx(port, address):
    # type: (int, AmsAddr) -> Tuple[str, AdsVersion]
    """Read the name and the version number of the ADS-server.

    :param int port: local AMS port as returned by adsPortOpenEx()
    :param pyads.structs.AmsAddr address: local or remote AmsAddr
    :rtype: string, AdsVersion
    :return: device name, version

    """
    sync_read_device_info_request = _adsDLL.AdsSyncReadDeviceInfoReqEx

    # Get pointer to the target AMS address
    ams_address_pointer = ctypes.pointer(address.amsAddrStruct())

    # Create buffer to be filled with device name, get pointer to said buffer
    device_name_buffer = ctypes.create_string_buffer(20)
    device_name_pointer = ctypes.pointer(device_name_buffer)

    # Create ADS Version struct and get pointer.
    ads_version = SAdsVersion()
    ads_version_pointer = ctypes.pointer(ads_version)

    error_code = sync_read_device_info_request(
        port, ams_address_pointer, device_name_pointer, ads_version_pointer
    )

    if error_code:
        raise ADSError(error_code)

    return (device_name_buffer.value.decode(), AdsVersion(ads_version))


Instruction:
Write a Python 3 function for
changing the state of the ADS - server and the machine - state of the ADS - server.

Response:
def adsSyncWriteControlReqEx(
    port, address, ads_state, device_state, data, plc_data_type
):
    # type: (int, AmsAddr, int, int, Any, Type) -> None
    """Change the ADS state and the machine-state of the ADS-server.

    :param int port: local AMS port as returned by adsPortOpenEx()
    :param pyads.structs.AmsAddr adr: local or remote AmsAddr
    :param int ads_state: new ADS-state, according to ADSTATE constants
    :param int device_state: new machine-state
    :param data: additional data
    :param int plc_data_type: plc datatype, according to PLCTYPE constants

    """
    sync_write_control_request = _adsDLL.AdsSyncWriteControlReqEx

    ams_address_pointer = ctypes.pointer(address.amsAddrStruct())
    ads_state_c = ctypes.c_ulong(ads_state)
    device_state_c = ctypes.c_ulong(device_state)

    if plc_data_type == PLCTYPE_STRING:
        data = ctypes.c_char_p(data.encode("utf-8"))
        data_pointer = data
        data_length = len(data_pointer.value) + 1
    else:
        data = plc_data_type(data)
        data_pointer = ctypes.pointer(data)
        data_length = ctypes.sizeof(data)

    error_code = sync_write_control_request(
        port,
        ams_address_pointer,
        ads_state_c,
        device_state_c,
        data_length,
        data_pointer,
    )

    if error_code:
        raise ADSError(error_code)


Instruction:
Write a Python 3 function for
sending data synchronous to an AMS - device.

Response:
def adsSyncWriteReqEx(port, address, index_group, index_offset, value, plc_data_type):
    # type: (int, AmsAddr, int, int, Any, Type) -> None
    """Send data synchronous to an ADS-device.

    :param int port: local AMS port as returned by adsPortOpenEx()
    :param pyads.structs.AmsAddr address: local or remote AmsAddr
    :param int indexGroup: PLC storage area, according to the INDEXGROUP
        constants
    :param int index_offset: PLC storage address
    :param value: value to write to the storage address of the PLC
    :param int plc_data_type: type of the data given to the PLC,
        according to PLCTYPE constants

    """
    sync_write_request = _adsDLL.AdsSyncWriteReqEx

    ams_address_pointer = ctypes.pointer(address.amsAddrStruct())
    index_group_c = ctypes.c_ulong(index_group)
    index_offset_c = ctypes.c_ulong(index_offset)

    if plc_data_type == PLCTYPE_STRING:
        data = ctypes.c_char_p(value.encode("utf-8"))
        data_pointer = data  # type: Union[ctypes.c_char_p, ctypes.pointer]
        data_length = len(data_pointer.value) + 1  # type: ignore

    else:
        if type(plc_data_type).__name__ == "PyCArrayType":
            data = plc_data_type(*value)
        else:
            data = plc_data_type(value)

        data_pointer = ctypes.pointer(data)
        data_length = ctypes.sizeof(data)

    error_code = sync_write_request(
        port,
        ams_address_pointer,
        index_group_c,
        index_offset_c,
        data_length,
        data_pointer,
    )

    if error_code:
        raise ADSError(error_code)


Instruction:
Can you implement a function in Python 3 that
reads and write data synchronous from/to an ADS-device. :param int port: local AMS port as returned by adsPortOpenEx() :param pyads.structs.AmsAddr address: local or remote AmsAddr :param int index_group: PLC storage area, according to the INDEXGROUP constants :param int index_offset: PLC storage address :param Type read_data_type: type of the data given to the PLC to respond to, according to PLCTYPE constants :param value: value to write to the storage address of the PLC :param Type write_data_type: type of the data given to the PLC, according to PLCTYPE constants :param bool return_ctypes: return ctypes instead of python types if True (default: False) :rtype: read_data_type :return: value: value read from PLC

Response:
def adsSyncReadWriteReqEx2(
    port,
    address,
    index_group,
    index_offset,
    read_data_type,
    value,
    write_data_type,
    return_ctypes=False,
):
    # type: (int, AmsAddr, int, int, Type, Any, Type, bool) -> Any
    """Read and write data synchronous from/to an ADS-device.

    :param int port: local AMS port as returned by adsPortOpenEx()
    :param pyads.structs.AmsAddr address: local or remote AmsAddr
    :param int index_group: PLC storage area, according to the INDEXGROUP
        constants
    :param int index_offset: PLC storage address
    :param Type read_data_type: type of the data given to the PLC to respond to,
        according to PLCTYPE constants
    :param value: value to write to the storage address of the PLC
    :param Type write_data_type: type of the data given to the PLC, according to
        PLCTYPE constants
    :param bool return_ctypes: return ctypes instead of python types if True
        (default: False)
    :rtype: read_data_type
    :return: value: value read from PLC

    """
    sync_read_write_request = _adsDLL.AdsSyncReadWriteReqEx2

    ams_address_pointer = ctypes.pointer(address.amsAddrStruct())
    index_group_c = ctypes.c_ulong(index_group)
    index_offset_c = ctypes.c_ulong(index_offset)

    if read_data_type == PLCTYPE_STRING:
        read_data = (STRING_BUFFER * PLCTYPE_STRING)()
    else:
        read_data = read_data_type()

    read_data_pointer = ctypes.pointer(read_data)
    read_length = ctypes.c_ulong(ctypes.sizeof(read_data))

    bytes_read = ctypes.c_ulong()
    bytes_read_pointer = ctypes.pointer(bytes_read)

    if write_data_type == PLCTYPE_STRING:
        # Get pointer to string
        write_data_pointer = ctypes.c_char_p(
            value.encode("utf-8")
        )  # type: Union[ctypes.c_char_p, ctypes.pointer]  # noqa: E501
        # Add an extra byte to the data length for the null terminator
        write_length = len(value) + 1
    else:
        if type(write_data_type).__name__ == "PyCArrayType":
            write_data = write_data_type(*value)
        else:
            write_data = write_data_type(value)
        write_data_pointer = ctypes.pointer(write_data)
        write_length = ctypes.sizeof(write_data)

    err_code = sync_read_write_request(
        port,
        ams_address_pointer,
        index_group_c,
        index_offset_c,
        read_length,
        read_data_pointer,
        write_length,
        write_data_pointer,
        bytes_read_pointer,
    )

    if err_code:
        raise ADSError(err_code)

    # If we're reading a value of predetermined size (anything but a string),
    # validate that the correct number of bytes were read
    if read_data_type != PLCTYPE_STRING and bytes_read.value != read_length.value:
        raise RuntimeError(
            "Insufficient data (expected {0} bytes, {1} were read).".format(
                read_length.value, bytes_read.value
            )
        )

    if return_ctypes:
        return read_data

    if read_data_type == PLCTYPE_STRING:
        return read_data.value.decode("utf-8")

    if type(read_data_type).__name__ == "PyCArrayType":
        return [i for i in read_data]

    if hasattr(read_data, "value"):
        return read_data.value

    return read_data


Instruction:
Given the following Python 3 function, write the documentation
def adsSyncReadReqEx2(
    port, address, index_group, index_offset, data_type, return_ctypes=False
):
    # type: (int, AmsAddr, int, int, Type, bool) -> Any
    """Read data synchronous from an ADS-device.

    :param int port: local AMS port as returned by adsPortOpenEx()
    :param pyads.structs.AmsAddr address: local or remote AmsAddr
    :param int index_group: PLC storage area, according to the INDEXGROUP
        constants
    :param int index_offset: PLC storage address
    :param Type data_type: type of the data given to the PLC, according to
        PLCTYPE constants
    :param bool return_ctypes: return ctypes instead of python types if True
        (default: False)
    :rtype: data_type
    :return: value: **value**

    """
    sync_read_request = _adsDLL.AdsSyncReadReqEx2

    ams_address_pointer = ctypes.pointer(address.amsAddrStruct())
    index_group_c = ctypes.c_ulong(index_group)
    index_offset_c = ctypes.c_ulong(index_offset)

    if data_type == PLCTYPE_STRING:
        data = (STRING_BUFFER * PLCTYPE_STRING)()
    else:
        data = data_type()

    data_pointer = ctypes.pointer(data)
    data_length = ctypes.c_ulong(ctypes.sizeof(data))

    bytes_read = ctypes.c_ulong()
    bytes_read_pointer = ctypes.pointer(bytes_read)

    error_code = sync_read_request(
        port,
        ams_address_pointer,
        index_group_c,
        index_offset_c,
        data_length,
        data_pointer,
        bytes_read_pointer,
    )

    if error_code:
        raise ADSError(error_code)

    # If we're reading a value of predetermined size (anything but a string),
    # validate that the correct number of bytes were read
    if data_type != PLCTYPE_STRING and bytes_read.value != data_length.value:
        raise RuntimeError(
            "Insufficient data (expected {0} bytes, {1} were read).".format(
                data_length.value, bytes_read.value
            )
        )

    if return_ctypes:
        return data

    if data_type == PLCTYPE_STRING:
        return data.value.decode("utf-8")

    if type(data_type).__name__ == "PyCArrayType":
        return [i for i in data]

    if hasattr(data, "value"):
        return data.value

    return data

Response: Reads data from an AMS - device and returns the result as a Python object.


Instruction:
Make a summary of the following Python 3 code
def adsSyncReadByNameEx(port, address, data_name, data_type, return_ctypes=False):
    # type: (int, AmsAddr, str, Type, bool) -> Any
    """Read data synchronous from an ADS-device from data name.

    :param int port: local AMS port as returned by adsPortOpenEx()
    :param pyads.structs.AmsAddr address: local or remote AmsAddr
    :param string data_name: data name
    :param Type data_type: type of the data given to the PLC, according to
        PLCTYPE constants
    :param bool return_ctypes: return ctypes instead of python types if True
        (default: False)
    :rtype: data_type
    :return: value: **value**

    """
    # Get the handle of the PLC-variable
    handle = adsSyncReadWriteReqEx2(
        port,
        address,
        ADSIGRP_SYM_HNDBYNAME,
        0x0,
        PLCTYPE_UDINT,
        data_name,
        PLCTYPE_STRING,
    )

    # Read the value of a PLC-variable, via handle
    value = adsSyncReadReqEx2(
        port, address, ADSIGRP_SYM_VALBYHND, handle, data_type, return_ctypes
    )

    # Release the handle of the PLC-variable
    adsSyncWriteReqEx(port, address, ADSIGRP_SYM_RELEASEHND, 0, handle, PLCTYPE_UDINT)

    return value

Response: Reads data from an ADS - device from data name.


Instruction:
Can you tell what is the following Python 3 function doing
def adsSyncWriteByNameEx(port, address, data_name, value, data_type):
    # type: (int, AmsAddr, str, Any, Type) -> None
    """Send data synchronous to an ADS-device from data name.

    :param int port: local AMS port as returned by adsPortOpenEx()
    :param pyads.structs.AmsAddr address: local or remote AmsAddr
    :param string data_name: PLC storage address
    :param value: value to write to the storage address of the PLC
    :param Type data_type: type of the data given to the PLC,
        according to PLCTYPE constants

    """
    # Get the handle of the PLC-variable
    handle = adsSyncReadWriteReqEx2(
        port,
        address,
        ADSIGRP_SYM_HNDBYNAME,
        0x0,
        PLCTYPE_UDINT,
        data_name,
        PLCTYPE_STRING,
    )

    # Write the value of a PLC-variable, via handle
    adsSyncWriteReqEx(port, address, ADSIGRP_SYM_VALBYHND, handle, value, data_type)

    # Release the handle of the PLC-variable
    adsSyncWriteReqEx(port, address, ADSIGRP_SYM_RELEASEHND, 0, handle, PLCTYPE_UDINT)

Response: Send data synchronous to an AMS - device from data name.


Instruction:
How would you code a function in Python 3 to
add a device notification to the AMS.

Response:
def adsSyncAddDeviceNotificationReqEx(
    port, adr, data_name, pNoteAttrib, callback, user_handle=None
):
    # type: (int, AmsAddr, str, NotificationAttrib, Callable, int) -> Tuple[int, int]
    """Add a device notification.

    :param int port: local AMS port as returned by adsPortOpenEx()
    :param pyads.structs.AmsAddr adr: local or remote AmsAddr
    :param string data_name: PLC storage address
    :param pyads.structs.NotificationAttrib pNoteAttrib: notification attributes
    :param callback: Callback function to handle notification
    :param user_handle: User Handle
    :rtype: (int, int)
    :returns: notification handle, user handle

    """
    global callback_store

    if NOTEFUNC is None:
        raise TypeError("Callback function type can't be None")

    adsSyncAddDeviceNotificationReqFct = _adsDLL.AdsSyncAddDeviceNotificationReqEx

    pAmsAddr = ctypes.pointer(adr.amsAddrStruct())
    hnl = adsSyncReadWriteReqEx2(
        port, adr, ADSIGRP_SYM_HNDBYNAME, 0x0, PLCTYPE_UDINT, data_name, PLCTYPE_STRING
    )

    nIndexGroup = ctypes.c_ulong(ADSIGRP_SYM_VALBYHND)
    nIndexOffset = ctypes.c_ulong(hnl)
    attrib = pNoteAttrib.notificationAttribStruct()
    pNotification = ctypes.c_ulong()

    nHUser = ctypes.c_ulong(hnl)
    if user_handle is not None:
        nHUser = ctypes.c_ulong(user_handle)

    adsSyncAddDeviceNotificationReqFct.argtypes = [
        ctypes.c_ulong,
        ctypes.POINTER(SAmsAddr),
        ctypes.c_ulong,
        ctypes.c_ulong,
        ctypes.POINTER(SAdsNotificationAttrib),
        NOTEFUNC,
        ctypes.c_ulong,
        ctypes.POINTER(ctypes.c_ulong),
    ]
    adsSyncAddDeviceNotificationReqFct.restype = ctypes.c_long

    def wrapper(addr, notification, user):
        # type: (AmsAddr, SAdsNotificationHeader, int) -> Callable[[SAdsNotificationHeader, str], None]
        return callback(notification, data_name)

    c_callback = NOTEFUNC(wrapper)
    err_code = adsSyncAddDeviceNotificationReqFct(
        port,
        pAmsAddr,
        nIndexGroup,
        nIndexOffset,
        ctypes.byref(attrib),
        c_callback,
        nHUser,
        ctypes.byref(pNotification),
    )

    if err_code:
        raise ADSError(err_code)
    callback_store[pNotification.value] = c_callback
    return (pNotification.value, hnl)


Instruction:
Write a Python 3 function for
removing a device notification.

Response:
def adsSyncDelDeviceNotificationReqEx(port, adr, notification_handle, user_handle):
    # type: (int, AmsAddr, int, int) -> None
    """Remove a device notification.

    :param int port: local AMS port as returned by adsPortOpenEx()
    :param pyads.structs.AmsAddr adr: local or remote AmsAddr
    :param int notification_handle: Notification Handle
    :param int user_handle: User Handle

    """
    adsSyncDelDeviceNotificationReqFct = _adsDLL.AdsSyncDelDeviceNotificationReqEx

    pAmsAddr = ctypes.pointer(adr.amsAddrStruct())
    nHNotification = ctypes.c_ulong(notification_handle)
    err_code = adsSyncDelDeviceNotificationReqFct(port, pAmsAddr, nHNotification)
    callback_store.pop(notification_handle, None)
    if err_code:
        raise ADSError(err_code)

    adsSyncWriteReqEx(port, adr, ADSIGRP_SYM_RELEASEHND, 0, user_handle, PLCTYPE_UDINT)


Instruction:
How would you explain what the following Python 3 function does
def adsSyncSetTimeoutEx(port, nMs):
    # type: (int, int) -> None
    """Set Timeout.

    :param int port: local AMS port as returned by adsPortOpenEx()
    :param int nMs: timeout in ms

    """
    adsSyncSetTimeoutFct = _adsDLL.AdsSyncSetTimeoutEx
    cms = ctypes.c_long(nMs)
    err_code = adsSyncSetTimeoutFct(port, cms)
    if err_code:
        raise ADSError(err_code)

Response: Sets the ADS server to timeout in ms.


Instruction:
Explain what the following Python 3 code does
def _parse_ams_netid(ams_netid):
    # type: (str) -> SAmsNetId
    """Parse an AmsNetId from *str* to *SAmsNetId*.

    :param str ams_netid: NetId as a string
    :rtype: SAmsNetId
    :return: NetId as a struct

    """
    try:
        id_numbers = list(map(int, ams_netid.split(".")))
    except ValueError:
        raise ValueError("no valid netid")

    if len(id_numbers) != 6:
        raise ValueError("no valid netid")

    # Fill the netId struct with data
    ams_netid_st = SAmsNetId()
    ams_netid_st.b = (c_ubyte * 6)(*id_numbers)
    return ams_netid_st

Response: Parse an AmsNetId from a string to a SAmsNetId.


Instruction:
Can you tell what is the following Python 3 function doing
def set_local_address(ams_netid):
    # type: (Union[str, SAmsNetId]) -> None
    """Set the local NetID (**Linux only**).

    :param str: new AmsNetID
    :rtype: None

    **Usage:**

        >>> import pyads
        >>> pyads.open_port()
        >>> pyads.set_local_address('0.0.0.0.1.1')

    """
    if isinstance(ams_netid, str):
        ams_netid_st = _parse_ams_netid(ams_netid)
    else:
        ams_netid_st = ams_netid

    assert isinstance(ams_netid_st, SAmsNetId)

    if linux:
        return adsSetLocalAddress(ams_netid_st)
    else:
        raise ADSError(
            text="SetLocalAddress is not supported for Windows clients."
        )

Response: Set the local address of the given AMS NetID.


Instruction:
Make a summary of the following Python 3 code
def write_control(adr, ads_state, device_state, data, plc_datatype):
    # type: (AmsAddr, int, int, Any, Type) -> None
    """Change the ADS state and the machine-state of the ADS-server.

    :param AmsAddr adr: local or remote AmsAddr
    :param int ads_state: new ADS-state, according to ADSTATE constants
    :param int device_state: new machine-state
    :param data: additional data
    :param int plc_datatype: datatype, according to PLCTYPE constants

    :note: Despite changing the ADS-state and the machine-state it is possible
           to send additional data to the ADS-server. For current ADS-devices
           additional data is not progressed.
           Every ADS-device is able to communicate its current state to other
           devices.
           There is a difference between the device-state and the state of the
           ADS-interface (AdsState). The possible states of an ADS-interface
           are defined in the ADS-specification.

    """
    if port is not None:
        return adsSyncWriteControlReqEx(
            port, adr, ads_state, device_state, data, plc_datatype
        )

Response: Write the control to the ADS server.


Instruction:
Make a summary of the following Python 3 code
def write(adr, index_group, index_offset, value, plc_datatype):
    # type: (AmsAddr, int, int, Any, Type) -> None
    """Send data synchronous to an ADS-device.

    :param AmsAddr adr: local or remote AmsAddr
    :param int index_group: PLC storage area, according to the INDEXGROUP
        constants
    :param int index_offset: PLC storage address
    :param value: value to write to the storage address of the PLC
    :param Type plc_datatype: type of the data given to the PLC,
        according to PLCTYPE constants

    """
    if port is not None:
        return adsSyncWriteReqEx(
            port, adr, index_group, index_offset, value, plc_datatype
        )

Response: Send data synchronous to an ADS - device.


Instruction:
How would you code a function in Python 3 to
read and writes data synchronous from an ADS - device.

Response:
def read_write(
    adr,
    index_group,
    index_offset,
    plc_read_datatype,
    value,
    plc_write_datatype,
    return_ctypes=False,
):
    # type: (AmsAddr, int, int, Type, Any, Type, bool) -> Any
    """Read and write data synchronous from/to an ADS-device.

    :param AmsAddr adr: local or remote AmsAddr
    :param int index_group: PLC storage area, according to the INDEXGROUP
        constants
    :param int index_offset: PLC storage address
    :param Type plc_read_datatype: type of the data given to the PLC to respond
            to, according to PLCTYPE constants
        :param value: value to write to the storage address of the PLC
    :param Type plc_write_datatype: type of the data given to the PLC, according to
        PLCTYPE constants
    :param bool return_ctypes: return ctypes instead of python types if True
        (default: False)
    :rtype: PLCTYPE
    :return: value: **value**

    """
    if port is not None:
        return adsSyncReadWriteReqEx2(
            port,
            adr,
            index_group,
            index_offset,
            plc_read_datatype,
            value,
            plc_write_datatype,
            return_ctypes,
        )

    return None


Instruction:
Can you generate the documentation for the following Python 3 function
def read(adr, index_group, index_offset, plc_datatype, return_ctypes=False):
    # type: (AmsAddr, int, int, Type, bool) -> Any
    """Read data synchronous from an ADS-device.

        :param AmsAddr adr: local or remote AmsAddr
    :param int index_group: PLC storage area, according to the INDEXGROUP
        constants
    :param int index_offset: PLC storage address
    :param int plc_datatype: type of the data given to the PLC, according to
        PLCTYPE constants
    :param bool return_ctypes: return ctypes instead of python types if True
        (default: False)
    :return: value: **value**

    """
    if port is not None:
        return adsSyncReadReqEx2(
            port, adr, index_group, index_offset, plc_datatype, return_ctypes
        )

    return None

Response: Read data synchronous from an ADS - device.


Instruction:
Make a summary of the following Python 3 code
def read_by_name(adr, data_name, plc_datatype, return_ctypes=False):
    # type: (AmsAddr, str, Type, bool) -> Any
    """Read data synchronous from an ADS-device from data name.

    :param AmsAddr adr: local or remote AmsAddr
    :param string data_name: data name
    :param int plc_datatype: type of the data given to the PLC, according to
        PLCTYPE constants
    :param bool return_ctypes: return ctypes instead of python types if True
        (default: False)
    :return: value: **value**

    """
    if port is not None:
        return adsSyncReadByNameEx(port, adr, data_name, plc_datatype, return_ctypes)

    return None

Response: Reads data from an ADS - device from a data name.


Instruction:
How would you implement a function in Python 3 that
sends data synchronous to an ADS - device from data name.

Response:
def write_by_name(adr, data_name, value, plc_datatype):
    # type: (AmsAddr, str, Any, Type) -> None
    """Send data synchronous to an ADS-device from data name.

    :param AmsAddr adr: local or remote AmsAddr
    :param string data_name: PLC storage address
    :param value: value to write to the storage address of the PLC
    :param int plc_datatype: type of the data given to the PLC,
        according to PLCTYPE constants

    """
    if port is not None:
        return adsSyncWriteByNameEx(port, adr, data_name, value, plc_datatype)


Instruction:
Can you generate a brief explanation for the following Python 3 code
def add_device_notification(adr, data_name, attr, callback, user_handle=None):
    # type: (AmsAddr, str, NotificationAttrib, Callable, int) -> Optional[Tuple[int, int]]  # noqa: E501
    """Add a device notification.

    :param pyads.structs.AmsAddr adr: AMS Address associated with the routing
        entry which is to be removed from the router.
    :param str data_name: PLC storage address
    :param pyads.structs.NotificationAttrib attr: object that contains
        all the attributes for the definition of a notification
    :param callback: callback function that gets executed on in the event
        of a notification

    :rtype: (int, int)
    :returns: notification handle, user handle

    Save the notification handle and the user handle on creating a
    notification if you want to be able to remove the notification
    later in your code.

    """
    if port is not None:
        return adsSyncAddDeviceNotificationReqEx(
            port, adr, data_name, attr, callback, user_handle
        )

    return None

Response: Add a device notification.


Instruction:
Implement a Python 3 function for
removing a device notification from the routing table.

Response:
def del_device_notification(adr, notification_handle, user_handle):
    # type: (AmsAddr, int, int) -> None
    """Remove a device notification.

    :param pyads.structs.AmsAddr adr: AMS Address associated with the routing
        entry which is to be removed from the router.
    :param notification_handle: address of the variable that contains
        the handle of the notification
    :param user_handle: user handle

    """
    if port is not None:
        return adsSyncDelDeviceNotificationReqEx(
            port, adr, notification_handle, user_handle
        )


Instruction:
Can you generate the documentation for the following Python 3 function
def open(self):
        # type: () -> None
        """Connect to the TwinCAT message router."""
        if self._open:
            return

        self._port = adsPortOpenEx()

        if linux:
            adsAddRoute(self._adr.netIdStruct(), self.ip_address)

        self._open = True

Response: Connect to the TwinCAT message router.


Instruction:
Create a Python 3 function for
closing the connection to the TwinCAT message router.

Response:
def close(self):
        # type: () -> None
        """:summary: Close the connection to the TwinCAT message router."""
        if not self._open:
            return

        if linux:
            adsDelRoute(self._adr.netIdStruct())

        if self._port is not None:
            adsPortCloseEx(self._port)
            self._port = None

        self._open = False


Instruction:
How would you explain what the following Python 3 function does
def write_control(self, ads_state, device_state, data, plc_datatype):
        # type: (int, int, Any, Type) -> None
        """Change the ADS state and the machine-state of the ADS-server.

        :param int ads_state: new ADS-state, according to ADSTATE constants
        :param int device_state: new machine-state
        :param data: additional data
        :param int plc_datatype: datatype, according to PLCTYPE constants

        :note: Despite changing the ADS-state and the machine-state it is
            possible to send additional data to the ADS-server. For current
            ADS-devices additional data is not progressed.
            Every ADS-device is able to communicate its current state to other
            devices. There is a difference between the device-state and the
            state of the ADS-interface (AdsState). The possible states of an
            ADS-interface are defined in the ADS-specification.

        """
        if self._port is not None:
            return adsSyncWriteControlReqEx(
                self._port, self._adr, ads_state, device_state, data, plc_datatype
            )

Response: Write the control of an ADS - server.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def write(self, index_group, index_offset, value, plc_datatype):
        # type: (int, int, Any, Type) -> None
        """Send data synchronous to an ADS-device.

        :param int index_group: PLC storage area, according to the INDEXGROUP
            constants
        :param int index_offset: PLC storage address
        :param value: value to write to the storage address of the PLC
        :param int plc_datatype: type of the data given to the PLC,
            according to PLCTYPE constants

        """
        if self._port is not None:
            return adsSyncWriteReqEx(
                self._port, self._adr, index_group, index_offset, value, plc_datatype
            )

Response: Send data synchronous to an ADS - device.


Instruction:
Can you create a Python 3 function that
reads and writes the specified value from an ADS - device and returns the result.

Response:
def read_write(
        self,
        index_group,
        index_offset,
        plc_read_datatype,
        value,
        plc_write_datatype,
        return_ctypes=False,
    ):
        # type: (int, int, Type, Any, Type, bool) -> Any
        """Read and write data synchronous from/to an ADS-device.

        :param int index_group: PLC storage area, according to the INDEXGROUP
            constants
        :param int index_offset: PLC storage address
        :param int plc_read_datatype: type of the data given to the PLC to
            respond to, according to PLCTYPE constants
        :param value: value to write to the storage address of the PLC
        :param plc_write_datatype: type of the data given to the PLC,
            according to PLCTYPE constants
            :rtype: PLCTYPE
    :param bool return_ctypes: return ctypes instead of python types if True
        (default: False)
        :return: value: **value**

        """
        if self._port is not None:
            return adsSyncReadWriteReqEx2(
                self._port,
                self._adr,
                index_group,
                index_offset,
                plc_read_datatype,
                value,
                plc_write_datatype,
                return_ctypes,
            )

        return None


Instruction:
Create a Python 3 function for
reading data synchronous from an ADS - device.

Response:
def read(self, index_group, index_offset, plc_datatype, return_ctypes=False):
        # type: (int, int, Type, bool) -> Any
        """Read data synchronous from an ADS-device.

        :param int index_group: PLC storage area, according to the INDEXGROUP
            constants
        :param int index_offset: PLC storage address
        :param int plc_datatype: type of the data given to the PLC, according
            to PLCTYPE constants
            :return: value: **value**
        :param bool return_ctypes: return ctypes instead of python types if True
            (default: False)

        """
        if self._port is not None:
            return adsSyncReadReqEx2(
                self._port, self._adr, index_group, index_offset, plc_datatype, return_ctypes
            )

        return None


Instruction:
Given the following Python 3 function, write the documentation
def read_by_name(self, data_name, plc_datatype, return_ctypes=False):
        # type: (str, Type, bool) -> Any
        """Read data synchronous from an ADS-device from data name.

        :param string data_name: data name
        :param int plc_datatype: type of the data given to the PLC, according
            to PLCTYPE constants
            :return: value: **value**
        :param bool return_ctypes: return ctypes instead of python types if True
            (default: False)

        """
        if self._port:
            return adsSyncReadByNameEx(self._port, self._adr, data_name, plc_datatype, return_ctypes)

        return None

Response: Reads data from an ADS - device from a data name.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def write_by_name(self, data_name, value, plc_datatype):
        # type: (str, Any, Type) -> None
        """Send data synchronous to an ADS-device from data name.

        :param string data_name: PLC storage address
        :param value: value to write to the storage address of the PLC
        :param int plc_datatype: type of the data given to the PLC,
            according to PLCTYPE constants

        """
        if self._port:
            return adsSyncWriteByNameEx(
                self._port, self._adr, data_name, value, plc_datatype
            )

Response: Send data synchronous to an ADS - device from data name.


Instruction:
Write a Python 3 script to
add a new device notification.

Response:
def add_device_notification(self, data_name, attr, callback, user_handle=None):
        # type: (str, NotificationAttrib, Callable, int) -> Optional[Tuple[int, int]]
        """Add a device notification.

        :param str data_name: PLC storage address
        :param pyads.structs.NotificationAttrib attr: object that contains
            all the attributes for the definition of a notification
        :param callback: callback function that gets executed on in the event
            of a notification

        :rtype: (int, int)
        :returns: notification handle, user handle

        Save the notification handle and the user handle on creating a
        notification if you want to be able to remove the notification
        later in your code.

        **Usage**:

            >>> import pyads
            >>> from ctypes import size_of
            >>>
            >>> # Connect to the local TwinCAT PLC
            >>> plc = pyads.Connection('127.0.0.1.1.1', 851)
            >>>
            >>> # Create callback function that prints the value
            >>> def mycallback(adr, notification, user):
            >>>     contents = notification.contents
            >>>     value = next(
            >>>         map(int,
            >>>             bytearray(contents.data)[0:contents.cbSampleSize])
            >>>     )
            >>>     print(value)
            >>>
            >>> with plc:
            >>>     # Add notification with default settings
            >>>     attr = pyads.NotificationAttrib(size_of(pyads.PLCTYPE_INT))
            >>>
            >>>     hnotification, huser = plc.add_device_notification(
            >>>         adr, attr, mycallback)
            >>>
            >>>     # Remove notification
            >>>     plc.del_device_notification(hnotification, huser)

        """
        if self._port is not None:
            notification_handle, user_handle = adsSyncAddDeviceNotificationReqEx(
                self._port, self._adr, data_name, attr, callback, user_handle
            )
            return notification_handle, user_handle

        return None


Instruction:
Can you tell what is the following Python 3 function doing
def del_device_notification(self, notification_handle, user_handle):
        # type: (int, int) -> None
        """Remove a device notification.

        :param notification_handle: address of the variable that contains
            the handle of the notification
        :param user_handle: user handle

        """
        if self._port is not None:
            adsSyncDelDeviceNotificationReqEx(
                self._port, self._adr, notification_handle, user_handle
            )

Response: Remove a device notification.


Instruction:
Can you tell what is the following Python 3 function doing
def notification(self, plc_datatype=None):
        # type: (Optional[Type[Any]]) -> Callable
        """Decorate a callback function.

        **Decorator**.

        A decorator that can be used for callback functions in order to
        convert the data of the NotificationHeader into the fitting
        Python type.

        :param plc_datatype: The PLC datatype that needs to be converted. This can
        be any basic PLC datatype or a `ctypes.Structure`.

        The callback functions need to be of the following type:

        >>> def callback(handle, name, timestamp, value)

        * `handle`: the notification handle
        * `name`: the variable name
        * `timestamp`: the timestamp as datetime value
        * `value`: the converted value of the variable

        **Usage**:

            >>> import pyads
            >>>
            >>> plc = pyads.Connection('172.18.3.25.1.1', 851)
            >>>
            >>>
            >>> @plc.notification(pyads.PLCTYPE_STRING)
            >>> def callback(handle, name, timestamp, value):
            >>>     print(handle, name, timestamp, value)
            >>>
            >>>
            >>> with plc:
            >>>    attr = pyads.NotificationAttrib(20,
            >>>                                    pyads.ADSTRANS_SERVERCYCLE)
            >>>    handles = plc.add_device_notification('GVL.test', attr,
            >>>                                          callback)
            >>>    while True:
            >>>        pass

        """

        def notification_decorator(func):
            # type: (Callable[[int, str, datetime, Any], None]) -> Callable[[Any, str], None] # noqa: E501

            def func_wrapper(notification, data_name):
                # type: (Any, str) -> None
                contents = notification.contents
                data = contents.data
                data_size = contents.cbSampleSize

                datatype_map = {
                    PLCTYPE_BOOL: "<?",
                    PLCTYPE_BYTE: "<c",
                    PLCTYPE_DINT: "<i",
                    PLCTYPE_DWORD: "<I",
                    PLCTYPE_INT: "<h",
                    PLCTYPE_LREAL: "<d",
                    PLCTYPE_REAL: "<f",
                    PLCTYPE_SINT: "<b",
                    PLCTYPE_UDINT: "<L",
                    PLCTYPE_UINT: "<H",
                    PLCTYPE_USINT: "<B",
                    PLCTYPE_WORD: "<H",
                }  # type: Dict[Type, str]

                if plc_datatype == PLCTYPE_STRING:
                    dest = (c_ubyte * data_size)()
                    memmove(addressof(dest), addressof(data), data_size)
                    # read only until null-termination character
                    value = bytearray(dest).split(b"\0", 1)[0].decode("utf-8")

                elif issubclass(plc_datatype, Structure):
                    value = plc_datatype()
                    fit_size = min(data_size, sizeof(value))
                    memmove(addressof(value), addressof(data), fit_size)

                elif plc_datatype not in datatype_map:
                    value = data

                else:
                    value = struct.unpack(
                        datatype_map[plc_datatype], bytearray(data)[:data_size]
                    )[0]

                dt = filetime_to_dt(contents.nTimeStamp)

                return func(contents.hNotification, data_name, dt, value)

            return func_wrapper

        return notification_decorator

Response: Returns a function that can be used to create a new notification.


Instruction:
Create a Python 3 function to
extract the text from the node that has the xpath xpath

Response:
def xml_extract_text(node, xpath):
    """
    :param node: the node to be queried
    :param xpath: the path to fetch the child node that has the wanted text
    """
    text = node.find(xpath).text
    if text is not None:
        text = text.strip()
    return text


Instruction:
Can you write a function in Python 3 where it
returns the datetime object that corresponds to the date of the node

Response:
def xml_extract_date(node, xpath, date_format='%d/%m/%Y'):
    """
    :param node: the node to be queried
    :param xpath: the path to fetch the child node that has the wanted date
    """
    return datetime.strptime(xml_extract_text(node, xpath), date_format)


Instruction:
Can you generate a brief explanation for the following Python 3 code
def xml_extract_datetime(node, xpath, datetime_format='%d/%m/%Y %H:%M:%S'):
    return datetime.strptime(xml_extract_text(node, xpath), datetime_format)

Response: returns the datetime that the node has the wanted datetime


Instruction:
How would you implement a function in Python 3 that
translates a column in the sequence of strings in the sequence of categories.

Response:
def translate_column(df, column, translations):
    """
    :param df: (pandas.Dataframe) the dataframe to be translated
    :param column: (str) the column to be translated
    :param translations: (dict) a dictionary of the strings to be categorized and translated
    """
    df[column] = df[column].astype('category')
    translations = [translations[cat]
                    for cat in df[column].cat.categories]
    df[column].cat.rename_categories(translations, inplace=True)


Instruction:
Write a Python 3 script to
fetch the list of speeches from the specified date range

Response:
def fetch_speeches(data_dir, range_start, range_end):
    """
    :param data_dir: (str) directory in which the output file will be saved
    :param range_start: (str) date in the format dd/mm/yyyy
    :param range_end: (str) date in the format dd/mm/yyyy
    """
    speeches = SpeechesDataset()
    df = speeches.fetch(range_start, range_end)
    save_to_csv(df, data_dir, "speeches")
    return df


Instruction:
Make a summary of the following Python 3 code
def fetch(self, range_start, range_end):
        range_dates = {'dataIni': range_start, 'dataFim': range_end}
        url = self.URL.format(**range_dates)
        xml = urllib.request.urlopen(url)

        tree = ET.ElementTree(file=xml)
        records = self._parse_speeches(tree.getroot())

        return pd.DataFrame(records, columns=[
            'session_code',
            'session_date',
            'session_num',
            'phase_code',
            'phase_desc',
            'speech_speaker_num',
            'speech_speaker_name',
            'speech_speaker_party',
            'speech_speaker_state',
            'speech_started_at',
            'speech_room_num',
            'speech_insertion_num'
        ])

Response: Fetches the list of speeches from the ListarDiscursosPlenario endpoint of the SessoesReunioes API.


Instruction:
How would you explain what the following Python 3 function does
def fetch_presences(data_dir, deputies, date_start, date_end):
    presences = PresencesDataset()
    df = presences.fetch(deputies, date_start, date_end)
    save_to_csv(df, data_dir, "presences")

    log.info("Presence records:", len(df))
    log.info("Records of deputies present on a session:", len(df[df.presence == 'Present']))
    log.info("Records of deputies absent from a session:", len(df[df.presence == 'Absent']))

    return df

Response: Fetch the presences from the database


Instruction:
Can you write a function in Python 3 where it
fetches data from the given deputies.

Response:
def fetch(self, deputies, start_date, end_date):
        """
        :param deputies: (pandas.DataFrame) a dataframe with deputies data
        :param date_start: (str) date in the format dd/mm/yyyy
        :param date_end: (str) date in the format dd/mm/yyyy
        """
        log.debug("Fetching data for {} deputies from {} -> {}".format(len(deputies), start_date, end_date))

        records = self._all_presences(deputies, start_date, end_date)

        df = pd.DataFrame(records, columns=(
            'term',
            'congressperson_document',
            'congressperson_name',
            'party',
            'state',
            'date',
            'present_on_day',
            'justification',
            'session',
            'presence'
        ))
        return self._translate(df)


Instruction:
Implement a function in Python 3 to
fetch the official Missions from the specified date range.

Response:
def fetch_official_missions(data_dir, start_date, end_date):
    """
    :param data_dir: (str) directory in which the output file will be saved
    :param start_date: (datetime) first date of the range to be scraped
    :param end_date: (datetime) last date of the range to be scraped
    """
    official_missions = OfficialMissionsDataset()
    df = official_missions.fetch(start_date, end_date)
    save_to_csv(df, data_dir, "official-missions")

    return df


Instruction:
Implement a function in Python 3 to
fetch official missions within the given date range

Response:
def fetch(self, start_date, end_date):
        """
        Fetches official missions within the given date range
        """

        records = []
        for two_months_range in self._generate_ranges(start_date, end_date):
            log.debug(two_months_range)
            for record in self._fetch_missions_for_range(two_months_range[0], two_months_range[1]):
                records.append(record)

        df = pd.DataFrame(records, columns=[
            'participant',
            'destination',
            'subject',
            'start',
            'end',
            'canceled',
            'report_status',
            'report_details_link'
        ])

        translate_column(df, 'report_status', {
            'Disponível': 'Available',
            'Pendente': 'Pending',
            'Em análise': 'Analysing',
            'Não se aplica': 'Does not apply'
        })
        translate_column(df, 'canceled', {
            'Não': 'No',
            'Sim': 'Yes'
        })

        return df.drop_duplicates()


Instruction:
Can you generate the documentation for the following Python 3 function
def _generate_ranges(start_date, end_date):
        range_start = start_date
        while range_start < end_date:
            range_end = range_start + timedelta(days=60)
            yield (
                range_start.strftime("%d/%m/%Y"),
                range_end.strftime("%d/%m/%Y")
            )
            range_start += timedelta(days=30)

Response: Generate a list of 2 month ranges for the requested anracatetime.


Instruction:
Here you have a function in Python 3, explain what it does
def fetch_session_start_times(data_dir, pivot, session_dates):
    session_start_times = SessionStartTimesDataset()
    df = session_start_times.fetch(pivot, session_dates)
    save_to_csv(df, data_dir, "session-start-times")

    log.info("Dates requested:", len(session_dates))
    found = pd.to_datetime(df['date'], format="%Y-%m-%d %H:%M:%S").dt.date.unique()
    log.info("Dates found:", len(found))
    return df

Response: Fetch the start times for a congressperson document.


Instruction:
Can you create a Python 3 function that
fetches the start times for a congressperson document.

Response:
def fetch(self, pivot, session_dates):
        """
        :param pivot: (int) a congressperson document to use as a pivot for scraping the data
        :param session_dates: (list) datetime objects to fetch the start times for
        """

        records = self._all_start_times(pivot, session_dates)
        return pd.DataFrame(records, columns=(
            'date',
            'session',
            'started_at'
        ))


Instruction:
Can you generate a brief explanation for the following Python 3 code
def fetch_deputies(data_dir):
    deputies = DeputiesDataset()
    df = deputies.fetch()
    save_to_csv(df, data_dir, "deputies")

    holders = df.condition == 'Holder'
    substitutes = df.condition == 'Substitute'
    log.info("Total deputies:", len(df))
    log.info("Holder deputies:", len(df[holders]))
    log.info("Substitute deputies:", len(df[substitutes]))
    return df

Response: Fetch the deputies dataset and save it to a CSV file


Instruction:
Here you have a function in Python 3, explain what it does
def fetch(self):
        xml = urllib.request.urlopen(self.URL)

        tree = ET.ElementTree(file=xml)
        records = self._parse_deputies(tree.getroot())

        df = pd.DataFrame(records, columns=(
            'congressperson_id',
            'budget_id',
            'condition',
            'congressperson_document',
            'civil_name',
            'congressperson_name',
            'picture_url',
            'gender',
            'state',
            'party',
            'phone_number',
            'email'
        ))
        return self._translate(df)

Response: Fetches the list of deputies for the current term.


Instruction:
Can you implement a function in Python 3 that
adds a node to the hash ring including a number of replicas.

Response:
def add_node(self, node):
        """Adds a `node` to the hash ring (including a number of replicas).
        """
        self.nodes.append(node)
        for x in xrange(self.replicas):
            ring_key = self.hash_method(b("%s:%d" % (node, x)))
            self.ring[ring_key] = node
            self.sorted_keys.append(ring_key)

        self.sorted_keys.sort()


Instruction:
How would you explain what the following Python 3 function does
def remove_node(self, node):
        self.nodes.remove(node)
        for x in xrange(self.replicas):
            ring_key = self.hash_method(b("%s:%d" % (node, x)))
            self.ring.pop(ring_key)
            self.sorted_keys.remove(ring_key)

Response: Removes a node from the hash ring and its replicas.


Instruction:
How would you explain what the following Python 3 function does
def get_node_pos(self, key):
        if len(self.ring) == 0:
            return [None, None]
        crc = self.hash_method(b(key))
        idx = bisect.bisect(self.sorted_keys, crc)
        # prevents out of range index
        idx = min(idx, (self.replicas * len(self.nodes)) - 1)
        return [self.ring[self.sorted_keys[idx]], idx]

Response: Given a string key returns a tuple of the node and its index in the hash ring along with its position in the ring.


Instruction:
Can you tell what is the following Python 3 function doing
def iter_nodes(self, key):
        if len(self.ring) == 0:
            yield None, None
        node, pos = self.get_node_pos(key)
        for k in self.sorted_keys[pos:]:
            yield k, self.ring[k]

Response: Given a string key it returns the nodes as a generator that can hold the key.


Instruction:
Can you generate the documentation for the following Python 3 function
def format_servers(servers):
    configs = []
    if not isinstance(servers, list):
        raise ValueError("server's config must be list")
    _type = type(servers[0])
    if _type == dict:
        return servers
    if (sys.version_info[0] == 3 and _type in [str, bytes]) \
            or (sys.version_info[0] == 2 and _type in [str, unicode]):
        for config in servers:
            configs.append(parse_url(config))
    else:
        raise ValueError("invalid server config")
    return configs

Response: returns a list of servers in two kinds of format


Instruction:
Create a Python 3 function to
return a list of values ordered identically to keys

Response:
def mget(self, keys, *args):
        """
        Returns a list of values ordered identically to ``keys``
        """
        args = list_or_args(keys, args)
        server_keys = {}
        ret_dict = {}
        for key in args:
            server_name = self.get_server_name(key)
            server_keys[server_name] = server_keys.get(server_name, [])
            server_keys[server_name].append(key)
        for server_name, sub_keys in iteritems(server_keys):
            values = self.connections[server_name].mget(sub_keys)
            ret_dict.update(dict(zip(sub_keys, values)))
        result = []
        for key in args:
            result.append(ret_dict.get(key, None))
        return result


Instruction:
Explain what the following Python 3 code does
def mset(self, mapping):
        servers = {}
        for key, value in mapping.items():
            server_name = self.get_server_name(key)
            servers.setdefault(server_name, [])
            servers[server_name].append((key, value))
        for name, items in servers.items():
            self.connections[name].mset(dict(items))
        return True

Response: Sets each key in the mapping dict to its corresponding value.


Instruction:
Write a Python 3 script to
return a new Lock object using the specified key name.

Response:
def lock(self, name, timeout=None, sleep=0.1):
        """
        Return a new Lock object using key ``name`` that mimics
        the behavior of threading.Lock.

        If specified, ``timeout`` indicates a maximum life for the lock.
        By default, it will remain locked until release() is called.

        ``sleep`` indicates the amount of time to sleep per loop iteration
        when the lock is in blocking mode and another client is currently
        holding the lock.
        """
        return Lock(self, name, timeout=timeout, sleep=sleep)


Instruction:
Can you generate the documentation for the following Python 3 function
def parse_line(line, document=None):
    '''
    Return a language-server diagnostic from a line of the Mypy error report;
    optionally, use the whole document to provide more context on it.
    '''
    result = re.match(line_pattern, line)
    if result:
        _, lineno, offset, severity, msg = result.groups()
        lineno = int(lineno or 1)
        offset = int(offset or 0)
        errno = 2
        if severity == 'error':
            errno = 1
        diag = {
            'source': 'mypy',
            'range': {
                'start': {'line': lineno - 1, 'character': offset},
                # There may be a better solution, but mypy does not provide end
                'end': {'line': lineno - 1, 'character': offset + 1}
            },
            'message': msg,
            'severity': errno
        }
        if document:
            # although mypy does not provide the end of the affected range, we
            # can make a good guess by highlighting the word that Mypy flagged
            word = document.word_at_position(diag['range']['start'])
            if word:
                diag['range']['end']['character'] = (
                    diag['range']['start']['character'] + len(word))

        return diag

Response: Parse a line of the Mypy error report into a dictionary of language - server diagnostic information.


Instruction:
Write a Python 3 script for
establishing a connection to the Lavalink server.

Response:
async def connect(self):
        """ Establishes a connection to the Lavalink server. """
        await self._lavalink.bot.wait_until_ready()

        if self._ws and self._ws.open:
            log.debug('WebSocket still open, closing...')
            await self._ws.close()

        user_id = self._lavalink.bot.user.id
        shard_count = self._lavalink.bot.shard_count or self._shards

        headers = {
            'Authorization': self._password,
            'Num-Shards': shard_count,
            'User-Id': str(user_id)
        }
        log.debug('Preparing to connect to Lavalink')
        log.debug('    with URI: {}'.format(self._uri))
        log.debug('    with headers: {}'.format(str(headers)))
        log.info('Connecting to Lavalink...')

        try:
            self._ws = await websockets.connect(self._uri, loop=self._loop, extra_headers=headers)
        except OSError as error:
            log.exception('Failed to connect to Lavalink: {}'.format(str(error)))
        else:
            log.info('Connected to Lavalink!')
            self._loop.create_task(self.listen())
            version = self._ws.response_headers.get('Lavalink-Major-Version', 2)
            try:
                self._lavalink._server_version = int(version)
            except ValueError:
                self._lavalink._server_version = 2
            log.info('Lavalink server version is {}'.format(version))
            if self._queue:
                log.info('Replaying {} queued events...'.format(len(self._queue)))
                for task in self._queue:
                    await self.send(**task)


Instruction:
Make a summary of the following Python 3 code
async def _attempt_reconnect(self):
        log.info('Connection closed; attempting to reconnect in 30 seconds')
        for a in range(0, self._ws_retry):
            await asyncio.sleep(30)
            log.info('Reconnecting... (Attempt {})'.format(a + 1))
            await self.connect()

            if self._ws.open:
                return True
        return False

Response: Attempts to reconnect to the Lavalink server.


Instruction:
Can you create a Python 3 function that
waits for a message from the Lavalink server and processes it.

Response:
async def listen(self):
        """ Waits to receive a payload from the Lavalink server and processes it. """
        while not self._shutdown:
            try:
                data = json.loads(await self._ws.recv())
            except websockets.ConnectionClosed as error:
                log.warning('Disconnected from Lavalink: {}'.format(str(error)))
                for g in self._lavalink.players._players.copy().keys():
                    ws = self._lavalink.bot._connection._get_websocket(int(g))
                    await ws.voice_state(int(g), None)

                self._lavalink.players.clear()

                if self._shutdown:
                    break

                if await self._attempt_reconnect():
                    return

                log.warning('Unable to reconnect to Lavalink!')
                break

            op = data.get('op', None)
            log.debug('Received WebSocket data {}'.format(str(data)))

            if not op:
                return log.debug('Received WebSocket message without op {}'.format(str(data)))

            if op == 'event':
                log.debug('Received event of type {}'.format(data['type']))
                player = self._lavalink.players[int(data['guildId'])]
                event = None

                if data['type'] == 'TrackEndEvent':
                    event = TrackEndEvent(player, data['track'], data['reason'])
                elif data['type'] == 'TrackExceptionEvent':
                    event = TrackExceptionEvent(player, data['track'], data['error'])
                elif data['type'] == 'TrackStuckEvent':
                    event = TrackStuckEvent(player, data['track'], data['thresholdMs'])

                if event:
                    await self._lavalink.dispatch_event(event)
            elif op == 'playerUpdate':
                await self._lavalink.update_state(data)
            elif op == 'stats':
                self._lavalink.stats._update(data)
                await self._lavalink.dispatch_event(StatsUpdateEvent(self._lavalink.stats))

        log.debug('Closing WebSocket...')
        await self._ws.close()


Instruction:
Can you tell what is the following Python 3 function doing
def connected_channel(self):
        if not self.channel_id:
            return None

        return self._lavalink.bot.get_channel(int(self.channel_id))

Response: Returns the voice channel that the player is connected to.


Instruction:
Implement a function in Python 3 to
connect to a voice channel.

Response:
async def connect(self, channel_id: int):
        """ Connects to a voice channel. """
        ws = self._lavalink.bot._connection._get_websocket(int(self.guild_id))
        await ws.voice_state(self.guild_id, str(channel_id))


Instruction:
Create a Python 3 function for
disconnecting from the voice channel if any.

Response:
async def disconnect(self):
        """ Disconnects from the voice channel, if any. """
        if not self.is_connected:
            return

        await self.stop()

        ws = self._lavalink.bot._connection._get_websocket(int(self.guild_id))
        await ws.voice_state(self.guild_id, None)


Instruction:
Can you implement a function in Python 3 that
stores custom user data.

Response:
def store(self, key: object, value: object):
        """ Stores custom user data. """
        self._user_data.update({key: value})


Instruction:
How would you explain what the following Python 3 function does
def fetch(self, key: object, default=None):
        return self._user_data.get(key, default)

Response: Retrieves the related value for the given key from the stored user data.


Instruction:
Write a Python 3 script to
add a track to the queue.

Response:
def add(self, requester: int, track: dict):
        """ Adds a track to the queue. """
        self.queue.append(AudioTrack().build(track, requester))


Instruction:
Can you generate a brief explanation for the following Python 3 code
def add_next(self, requester: int, track: dict):
        self.queue.insert(0, AudioTrack().build(track, requester))

Response: Adds a track to the beginning of the queue


Instruction:
Explain what the following Python 3 code does
def add_at(self, index: int, requester: int, track: dict):
        self.queue.insert(min(index, len(self.queue) - 1), AudioTrack().build(track, requester))

Response: Adds a track at a specific index in the queue.


Instruction:
Can you write a function in Python 3 where it
plays the first track in the queue if any or plays a track from the specified index.

Response:
async def play(self, track_index: int = 0, ignore_shuffle: bool = False):
        """ Plays the first track in the queue, if any or plays a track from the specified index in the queue. """
        if self.repeat and self.current:
            self.queue.append(self.current)

        self.previous = self.current
        self.current = None
        self.position = 0
        self.paused = False

        if not self.queue:
            await self.stop()
            await self._lavalink.dispatch_event(QueueEndEvent(self))
        else:
            if self.shuffle and not ignore_shuffle:
                track = self.queue.pop(randrange(len(self.queue)))
            else:
                track = self.queue.pop(min(track_index, len(self.queue) - 1))

            self.current = track
            await self._lavalink.ws.send(op='play', guildId=self.guild_id, track=track.track)
            await self._lavalink.dispatch_event(TrackStartEvent(self, track))


Instruction:
Explain what the following Python 3 code does
async def play_now(self, requester: int, track: dict):
        self.add_next(requester, track)
        await self.play(ignore_shuffle=True)

Response: Add a new track and play it.


Instruction:
Can you generate the documentation for the following Python 3 function
async def play_at(self, index: int):
        self.queue = self.queue[min(index, len(self.queue) - 1):len(self.queue)]
        await self.play(ignore_shuffle=True)

Response: Play the queue from a specific point. Disregards tracks before the index.


Instruction:
Can you implement a function in Python 3 that
plays the previous track if it exists.

Response:
async def play_previous(self):
        """ Plays previous track if it exist, if it doesn't raises a NoPreviousTrack error. """
        if not self.previous:
            raise NoPreviousTrack
        self.queue.insert(0, self.previous)
        await self.play(ignore_shuffle=True)


Instruction:
Make a summary of the following Python 3 code
async def stop(self):
        await self._lavalink.ws.send(op='stop', guildId=self.guild_id)
        self.current = None

Response: Stops the player if playing.


Instruction:
Can you tell what is the following Python 3 function doing
async def set_pause(self, pause: bool):
        await self._lavalink.ws.send(op='pause', guildId=self.guild_id, pause=pause)
        self.paused = pause

Response: Sets the player s paused state.


Instruction:
Given the following Python 3 function, write the documentation
async def set_volume(self, vol: int):
        if self._lavalink._server_version <= 2:
            self.volume = max(min(vol, 150), 0)
        else:
            self.volume = max(min(vol, 1000), 0)
        await self._lavalink.ws.send(op='volume', guildId=self.guild_id, volume=self.volume)

Response: Sets the player s volume.


Instruction:
Can you write a function in Python 3 where it
seeks to a given position in the track.

Response:
async def seek(self, pos: int):
        """ Seeks to a given position in the track. """
        await self._lavalink.ws.send(op='seek', guildId=self.guild_id, position=pos)


Instruction:
How would you explain what the following Python 3 function does
async def handle_event(self, event):
        if isinstance(event, (TrackStuckEvent, TrackExceptionEvent)) or \
                isinstance(event, TrackEndEvent) and event.reason == 'FINISHED':
            await self.play()

Response: Handles an event from the queue.


Instruction:
Can you implement a function in Python 3 that
returns a player object from the cache or creates one if it does not exist.

Response:
def get(self, guild_id):
        """ Returns a player from the cache, or creates one if it does not exist. """
        if guild_id not in self._players:
            p = self._player(lavalink=self.lavalink, guild_id=guild_id)
            self._players[guild_id] = p

        return self._players[guild_id]


Instruction:
How would you code a function in Python 3 to
remove a player from the current players.

Response:
def remove(self, guild_id):
        """ Removes a player from the current players. """
        if guild_id in self._players:
            self._players[guild_id].cleanup()
            del self._players[guild_id]


Instruction:
How would you implement a function in Python 3 that
searches and play a song from a given query.

Response:
async def _play(self, ctx, *, query: str):
        """ Searches and plays a song from a given query. """
        player = self.bot.lavalink.players.get(ctx.guild.id)

        query = query.strip('<>')

        if not url_rx.match(query):
            query = f'ytsearch:{query}'

        tracks = await self.bot.lavalink.get_tracks(query)

        if not tracks:
            return await ctx.send('Nothing found!')

        embed = discord.Embed(color=discord.Color.blurple())

        if 'list' in query and 'ytsearch:' not in query:
            for track in tracks:
                player.add(requester=ctx.author.id, track=track)

            embed.title = 'Playlist enqueued!'
            embed.description = f'Imported {len(tracks)} tracks from the playlist!'
            await ctx.send(embed=embed)
        else:
            track_title = tracks[0]["info"]["title"]
            track_uri = tracks[0]["info"]["uri"]

            embed.title = "Track enqueued!"
            embed.description = f'[{track_title}]({track_uri})'
            player.add(requester=ctx.author.id, track=tracks[0])

        if not player.is_playing:
            await player.play()


Instruction:
Write a Python 3 function that can
seek to a given position in a track.

Response:
async def _seek(self, ctx, *, time: str):
        """ Seeks to a given position in a track. """
        player = self.bot.lavalink.players.get(ctx.guild.id)

        if not player.is_playing:
            return await ctx.send('Not playing.')

        seconds = time_rx.search(time)
        if not seconds:
            return await ctx.send('You need to specify the amount of seconds to skip!')

        seconds = int(seconds.group()) * 1000
        if time.startswith('-'):
            seconds *= -1

        track_time = player.position + seconds
        await player.seek(track_time)

        await ctx.send(f'Moved track to **{lavalink.Utils.format_time(track_time)}**')


Instruction:
Write a Python 3 script to
skip the current track.

Response:
async def _skip(self, ctx):
        """ Skips the current track. """
        player = self.bot.lavalink.players.get(ctx.guild.id)

        if not player.is_playing:
            return await ctx.send('Not playing.')

        await player.skip()
        await ctx.send('⏭ | Skipped.')


Instruction:
Given the following Python 3 function, write the documentation
async def _stop(self, ctx):
        player = self.bot.lavalink.players.get(ctx.guild.id)

        if not player.is_playing:
            return await ctx.send('Not playing.')

        player.queue.clear()
        await player.stop()
        await ctx.send('⏹ | Stopped.')

Response: Stops the player and clears its queue.


Instruction:
Make a summary of the following Python 3 code
async def _now(self, ctx):
        player = self.bot.lavalink.players.get(ctx.guild.id)
        song = 'Nothing'

        if player.current:
            position = lavalink.Utils.format_time(player.position)
            if player.current.stream:
                duration = '🔴 LIVE'
            else:
                duration = lavalink.Utils.format_time(player.current.duration)
            song = f'**[{player.current.title}]({player.current.uri})**\n({position}/{duration})'

        embed = discord.Embed(color=discord.Color.blurple(), title='Now Playing', description=song)
        await ctx.send(embed=embed)

Response: Show some stats about the currently playing song.


Instruction:
How would you implement a function in Python 3 that
shows the player s queue.

Response:
async def _queue(self, ctx, page: int = 1):
        """ Shows the player's queue. """
        player = self.bot.lavalink.players.get(ctx.guild.id)

        if not player.queue:
            return await ctx.send('There\'s nothing in the queue! Why not queue something?')

        items_per_page = 10
        pages = math.ceil(len(player.queue) / items_per_page)

        start = (page - 1) * items_per_page
        end = start + items_per_page

        queue_list = ''
        for index, track in enumerate(player.queue[start:end], start=start):
            queue_list += f'`{index + 1}.` [**{track.title}**]({track.uri})\n'

        embed = discord.Embed(colour=discord.Color.blurple(),
                              description=f'**{len(player.queue)} tracks**\n\n{queue_list}')
        embed.set_footer(text=f'Viewing page {page}/{pages}')
        await ctx.send(embed=embed)


Instruction:
Create a Python 3 function to
pause or resumes the current track.

Response:
async def _pause(self, ctx):
        """ Pauses/Resumes the current track. """
        player = self.bot.lavalink.players.get(ctx.guild.id)

        if not player.is_playing:
            return await ctx.send('Not playing.')

        if player.paused:
            await player.set_pause(False)
            await ctx.send('⏯ | Resumed')
        else:
            await player.set_pause(True)
            await ctx.send('⏯ | Paused')


Instruction:
Make a summary of the following Python 3 code
async def _volume(self, ctx, volume: int = None):
        player = self.bot.lavalink.players.get(ctx.guild.id)

        if not volume:
            return await ctx.send(f'🔈 | {player.volume}%')

        await player.set_volume(volume)
        await ctx.send(f'🔈 | Set to {player.volume}%')

Response: Changes the player s volume.


Instruction:
Here you have a function in Python 3, explain what it does
async def _shuffle(self, ctx):
        player = self.bot.lavalink.players.get(ctx.guild.id)

        if not player.is_playing:
            return await ctx.send('Nothing playing.')

        player.shuffle = not player.shuffle
        await ctx.send('🔀 | Shuffle ' + ('enabled' if player.shuffle else 'disabled'))

Response: Shuffles the player's queue.