Instruction:
How would you implement a function in Python 3 that
strings representation of the object.

Response:
def to_string(self, hdr, other):
        """String representation with additional information"""
        result = "%s[%s,%s" % (
                hdr, self.get_type(self.type), self.get_clazz(self.clazz))
        if self.unique:
            result += "-unique,"
        else:
            result += ","
        result += self.name
        if other is not None:
            result += ",%s]" % (other)
        else:
            result += "]"
        return result


Instruction:
Write a Python 3 script to
return true if the question is answered by the record

Response:
def answered_by(self, rec):
        """Returns true if the question is answered by the record"""
        return self.clazz == rec.clazz and \
                (self.type == rec.type or self.type == _TYPE_ANY) and \
                self.name == rec.name


Instruction:
Can you generate the documentation for the following Python 3 function
def reset_ttl(self, other):
        self.created = other.created
        self.ttl = other.ttl

Response:
Sets this record s TTL and created time to that of
        other record.


Instruction:
Can you implement a function in Python 3 that
strings representation of the record with addtional information

Response:
def to_string(self, other):
        """String representation with addtional information"""
        arg = "%s/%s,%s" % (
                self.ttl, self.get_remaining_ttl(current_time_millis()), other)
        return DNSEntry.to_string(self, "record", arg)


Instruction:
Implement a function in Python 3 to
write the packet to the output stream.

Response:
def write(self, out):
        """Used in constructing an outgoing packet"""
        out.write_string(self.address, len(self.address))


Instruction:
Explain what the following Python 3 code does
def write(self, out):
        out.write_string(self.cpu, len(self.cpu))
        out.write_string(self.os, len(self.os))

Response: Write the CPU and OS information to the packet out.


Instruction:
Can you tell what is the following Python 3 function doing
def write(self, out):
        out.write_string(self.text, len(self.text))

Response: Write the text to the packet out.


Instruction:
Make a summary of the following Python 3 code
def set_property(self, key, value):
        self.properties[key] = value
        self.sync_properties()

Response: Set a property in the dict


Instruction:
How would you explain what the following Python 3 function does
def write(self, out):
        out.write_short(self.priority)
        out.write_short(self.weight)
        out.write_short(self.port)
        out.write_name(self.server)

Response: Write the attributes of this object to the packet out.


Instruction:
How would you explain what the following Python 3 function does
def read_header(self):
        format = '!HHHHHH'
        length = struct.calcsize(format)
        info = struct.unpack(format,
                self.data[self.offset:self.offset + length])
        self.offset += length

        self.id = info[0]
        self.flags = info[1]
        self.num_questions = info[2]
        self.num_answers = info[3]
        self.num_authorities = info[4]
        self.num_additionals = info[5]

Response: Reads the header portion of the packet


Instruction:
Given the following Python 3 function, write the documentation
def read_questions(self):
        format = '!HH'
        length = struct.calcsize(format)
        for i in range(0, self.num_questions):
            name = self.read_name()
            info = struct.unpack(format,
                    self.data[self.offset:self.offset + length])
            self.offset += length

            question = DNSQuestion(name, info[0], info[1])
            self.questions.append(question)

Response: Reads questions section of packet


Instruction:
Can you tell what is the following Python 3 function doing
def read_int(self):
        format = '!I'
        length = struct.calcsize(format)
        info = struct.unpack(format,
                self.data[self.offset:self.offset + length])
        self.offset += length
        return info[0]

Response: Reads an integer from the packet


Instruction:
Implement a function in Python 3 to
read a character string from the packet

Response:
def read_character_string(self):
        """Reads a character string from the packet"""
        length = ord(self.data[self.offset])
        self.offset += 1
        return self.read_string(length)


Instruction:
Write a Python 3 function for
reading a string from the packet

Response:
def read_string(self, len):
        """Reads a string of a given length from the packet"""
        format = '!' + str(len) + 's'
        length = struct.calcsize(format)
        info = struct.unpack(format,
                self.data[self.offset:self.offset + length])
        self.offset += length
        return info[0]


Instruction:
Given the following Python 3 function, write the documentation
def read_others(self):
        format = '!HHiH'
        length = struct.calcsize(format)
        n = self.num_answers + self.num_authorities + self.num_additionals
        for i in range(0, n):
            domain = self.read_name()
            info = struct.unpack(format,
                    self.data[self.offset:self.offset + length])
            self.offset += length

            rec = None
            if info[0] == _TYPE_A:
                rec = DNSAddress(domain,
                        info[0], info[1], info[2],
                        self.read_string(4))
            elif info[0] == _TYPE_CNAME or info[0] == _TYPE_PTR:
                rec = DNSPointer(domain,
                        info[0], info[1], info[2],
                        self.read_name())
            elif info[0] == _TYPE_TXT:
                rec = DNSText(domain,
                        info[0], info[1], info[2],
                        self.read_string(info[3]))
            elif info[0] == _TYPE_SRV:
                rec = DNSService(domain,
                        info[0], info[1], info[2],
                        self.read_unsigned_short(),
                        self.read_unsigned_short(),
                        self.read_unsigned_short(),
                        self.read_name())
            elif info[0] == _TYPE_HINFO:
                rec = DNSHinfo(domain,
                        info[0], info[1], info[2],
                        self.read_character_string(),
                        self.read_character_string())
            elif info[0] == _TYPE_RRSIG:
                rec = DNSSignatureI(domain,
                        info[0], info[1], info[2],
                        self.read_string(18),
                        self.read_name(),
                        self.read_character_string())
            elif info[0] == _TYPE_AAAA:
                rec = DNSAddress(domain,
                        info[0], info[1], info[2],
                        self.read_string(16))
            else:
                # Try to ignore types we don't know about
                # this may mean the rest of the name is
                # unable to be parsed, and may show errors
                # so this is left for debugging.  New types
                # encountered need to be parsed properly.
                #
                #print "UNKNOWN TYPE = " + str(info[0])
                #raise BadTypeInNameException
                pass

            if rec is not None:
                self.answers.append(rec)

Response: Reads the answers authorities and additionals section of the packet


Instruction:
Write a Python 3 function that can
read a UTF - 8 string of a given length from the packet

Response:
def read_utf(self, offset, len):
        """Reads a UTF-8 string of a given length from the packet"""
        try:
            result = self.data[offset:offset + len].decode('utf-8')
        except UnicodeDecodeError:
            result = str('')
        return result


Instruction:
Write a Python 3 script to
read a domain name from the packet.

Response:
def read_name(self):
        """Reads a domain name from the packet"""
        result = ''
        off = self.offset
        next = -1
        first = off

        while 1:
            len = ord(self.data[off])
            off += 1
            if len == 0:
                break
            t = len & 0xC0
            if t == 0x00:
                result = ''.join((result, self.read_utf(off, len) + '.'))
                off += len
            elif t == 0xC0:
                if next < 0:
                    next = off + 1
                off = ((len & 0x3F) << 8) | ord(self.data[off])
                if off >= first:
                    raise Exception(
                            "Bad domain name (circular) at " + str(off))
                first = off
            else:
                raise Exception("Bad domain name at " + str(off))

        if next >= 0:
            self.offset = next
        else:
            self.offset = off

        return result


Instruction:
Explain what the following Python 3 code does
def add_answer(self, inp, record):
        if not record.suppressed_by(inp):
            self.add_answer_at_time(record, 0)

Response: Adds an answer to the list of answer records.


Instruction:
Here you have a function in Python 3, explain what it does
def add_answer_at_time(self, record, now):
        if record is not None:
            if now == 0 or not record.is_expired(now):
                self.answers.append((record, now))
                if record.rrsig is not None:
                    self.answers.append((record.rrsig, now))

Response: Adds an answer if does not expire by a certain time


Instruction:
How would you explain what the following Python 3 function does
def write_byte(self, value):
        format = '!B'
        self.data.append(struct.pack(format, value))
        self.size += 1

Response: Writes a single byte to the packet


Instruction:
How would you code a function in Python 3 to
insert an unsigned short in a certain position in the packet

Response:
def insert_short(self, index, value):
        """Inserts an unsigned short in a certain position in the packet"""
        format = '!H'
        self.data.insert(index, struct.pack(format, value))
        self.size += 2


Instruction:
Can you generate a brief explanation for the following Python 3 code
def write_int(self, value):
        format = '!I'
        self.data.append(struct.pack(format, int(value)))
        self.size += 4

Response: Writes an unsigned integer to the packet


Instruction:
Explain what the following Python 3 code does
def write_string(self, value, length):
        format = '!' + str(length) + 's'
        self.data.append(struct.pack(format, value))
        self.size += length

Response: Writes a string to the packet


Instruction:
Can you generate the documentation for the following Python 3 function
def write_utf(self, s):
        utfstr = s.encode('utf-8')
        length = len(utfstr)
        if length > 64:
            raise NamePartTooLongException
        self.write_byte(length)
        self.write_string(utfstr, length)

Response: Writes a UTF - 8 string to the packet


Instruction:
Can you write a function in Python 3 where it
writes a domain name to the packet

Response:
def write_name(self, name):
        """Writes a domain name to the packet"""

        try:
            # Find existing instance of this name in packet
            #
            index = self.names[name]
        except KeyError:
            # No record of this name already, so write it
            # out as normal, recording the location of the name
            # for future pointers to it.
            #
            self.names[name] = self.size
            parts = name.split('.')
            if parts[-1] == '':
                parts = parts[:-1]
            for part in parts:
                self.write_utf(part)
            self.write_byte(0)
            return

        # An index was found, so write a pointer to it
        #
        self.write_byte((index >> 8) | 0xC0)
        self.write_byte(index)


Instruction:
Here you have a function in Python 3, explain what it does
def write_question(self, question):
        self.write_name(question.name)
        self.write_short(question.type)
        self.write_short(question.clazz)

Response: Writes a question to the packet


Instruction:
Create a Python 3 function to
write a record to the packet

Response:
def write_record(self, record, now):
        """Writes a record (answer, authoritative answer, additional) to
        the packet"""
        self.write_name(record.name)
        self.write_short(record.type)
        if record.unique and self.multicast:
            self.write_short(record.clazz | _CLASS_UNIQUE)
        else:
            self.write_short(record.clazz)
        if now == 0:
            self.write_int(record.ttl)
        else:
            self.write_int(record.get_remaining_ttl(now))
        index = len(self.data)
        # Adjust size for the short we will write before this record
        #
        self.size += 2
        record.write(self)
        self.size -= 2

        length = len(b''.join(self.data[index:]))
        self.insert_short(index, length)


Instruction:
Can you generate a brief explanation for the following Python 3 code
def packet(self):
        if not self.finished:
            self.finished = 1
            for question in self.questions:
                self.write_question(question)
            for answer, time in self.answers:
                self.write_record(answer, time)
            for authority in self.authorities:
                self.write_record(authority, 0)
            for additional in self.additionals:
                self.write_record(additional, 0)

            self.insert_short(0, len(self.additionals))
            self.insert_short(0, len(self.authorities))
            self.insert_short(0, len(self.answers))
            self.insert_short(0, len(self.questions))
            self.insert_short(0, self.flags)
            if self.multicast:
                self.insert_short(0, 0)
            else:
                self.insert_short(0, self.id)
        return b''.join(self.data)

Response:
Returns a string containing the packet s bytes
           .


Instruction:
Explain what the following Python 3 code does
def add(self, entry):
        if self.get(entry) is not None:
            return
        try:
            list = self.cache[entry.key]
        except:
            list = self.cache[entry.key] = []
        list.append(entry)

Response: Adds an entry to the cache


Instruction:
How would you explain what the following Python 3 function does
def sign(self, entry, signer=None):
        if (self.get(entry) is not None):
            return
        if (entry.rrsig is None) and (self.private is not None):
            entry.rrsig = DNSSignatureS(entry.name,
                    _TYPE_RRSIG, _CLASS_IN, entry, self.private, signer)
        self.add(entry)
        if (self.private is not None):
            self.add(entry.rrsig)

Response: Adds and sign an entry


Instruction:
How would you implement a function in Python 3 that
removes an entry from the cache

Response:
def remove(self, entry):
        """Removes an entry"""
        try:
            list = self.cache[entry.key]
            list.remove(entry)
        except:
            pass


Instruction:
Can you create a Python 3 function that
gets an entry by key. Will return None if there is no matching entry.

Response:
def get(self, entry):
        """Gets an entry by key.  Will return None if there is no
        matching entry."""
        try:
            list = self.cache[entry.key]
            return list[list.index(entry)]
        except:
            return None


Instruction:
Can you tell what is the following Python 3 function doing
def get_by_details(self, name, type, clazz):
        entry = DNSEntry(name, type, clazz)
        return self.get(entry)

Response: Gets an entry by details. Will return None if there is no matching entry.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def entries(self):
        def add(x, y):
            return x + y
        try:
            return reduce(add, list(self.cache.values()))
        except:
            return []

Response: Returns a list of all entries


Instruction:
Here you have a function in Python 3, explain what it does
def update_record(self, zeroconf, now, record):
        if record.type == _TYPE_PTR and record.name == self.type:
            expired = record.is_expired(now)
            try:
                oldrecord = self.services[record.alias.lower()]
                if not expired:
                    oldrecord.reset_ttl(record)
                else:
                    del(self.services[record.alias.lower()])
                    callback = lambda x: self.listener.remove_service(x,
                            self.type, record.alias)
                    self.list.append(callback)
                    return
            except:
                if not expired:
                    self.services[record.alias.lower()] = record
                    callback = lambda x: self.listener.add_service(x,
                            self.type, record.alias)
                    self.list.append(callback)

            expires = record.get_expiration_time(75)
            if expires < self.next_time:
                self.next_time = expires

Response: Callback invoked by Zeroconf when new information arrives.


Instruction:
Can you generate the documentation for the following Python 3 function
def set_properties(self, properties):
        if isinstance(properties, dict):
            self.properties = properties
            self.sync_properties()
        else:
            self.text = properties

Response: Sets properties and text of this info from a dictionary


Instruction:
Given the following Python 3 function, write the documentation
def set_text(self, text):
        self.text = text
        try:
            self.properties = text_to_dict(text)
        except:
            traceback.print_exc()
            self.properties = None

Response: Sets properties and text given a text field


Instruction:
How would you code a function in Python 3 to
name accessor for the class name.

Response:
def get_name(self):
        """Name accessor"""
        if self.type is not None and self.name.endswith("." + self.type):
            return self.name[:len(self.name) - len(self.type) - 1]
        return self.name


Instruction:
Can you generate the documentation for the following Python 3 function
def update_record(self, zeroconf, now, record):
        if record is not None and not record.is_expired(now):
            if record.type == _TYPE_A:
                if record.name == self.name:
                    if not record.address in self.address:
                        self.address.append(record.address)
            elif record.type == _TYPE_SRV:
                if record.name == self.name:
                    self.server = record.server
                    self.port = record.port
                    self.weight = record.weight
                    self.priority = record.priority
                    self.address = []
                    self.update_record(zeroconf, now,
                            zeroconf.cache.get_by_details(self.server,
                                _TYPE_A, _CLASS_IN))
            elif record.type == _TYPE_TXT:
                if record.name == self.name:
                    self.set_text(record.text)

Response: Updates service information from a DNS record.


Instruction:
Can you generate the documentation for the following Python 3 function
def request(self, zeroconf, timeout):
        now = current_time_millis()
        delay = _LISTENER_TIME
        next = now + delay
        last = now + timeout
        result = 0
        try:
            zeroconf.add_listener(self,
                    DNSQuestion(self.name, _TYPE_ANY, _CLASS_IN))
            while self.server is None or \
                    len(self.address) == 0 or \
                    self.text is None:
                if last <= now:
                    return 0
                if next <= now:
                    out = DNSOutgoing(_FLAGS_QR_QUERY)
                    out.add_question(DNSQuestion(self.name,
                        _TYPE_SRV, _CLASS_IN))
                    out.add_answer_at_time(
                            zeroconf.cache.get_by_details(self.name,
                                _TYPE_SRV, _CLASS_IN), now)
                    out.add_question(
                            DNSQuestion(self.name, _TYPE_TXT, _CLASS_IN))
                    out.add_answer_at_time(
                            zeroconf.cache.get_by_details(self.name,
                                _TYPE_TXT, _CLASS_IN), now)
                    if self.server is not None:
                        out.add_question(
                                DNSQuestion(self.server, _TYPE_A, _CLASS_IN))
                        out.add_answer_at_time(
                                zeroconf.cache.get_by_details(self.server,
                                    _TYPE_A, _CLASS_IN), now)
                    zeroconf.send(out)
                    next = now + delay
                    delay = delay * 2

                zeroconf.wait(min(next, last) - now)
                now = current_time_millis()
            result = 1
        finally:
            zeroconf.remove_listener(self)

        return result

Response: Returns true if the service could be discovered on the zeroconf network and updates this object with details discovered.


Instruction:
How would you explain what the following Python 3 function does
def wait(self, timeout):
        self.condition.acquire()
        self.condition.wait(timeout // 1000)
        self.condition.release()

Response:
Calling thread waits for a given number of milliseconds or
        until notified.


Instruction:
Can you write a function in Python 3 where it
notifies all waiting threads

Response:
def notify_all(self):
        """Notifies all waiting threads"""
        self.condition.acquire()
        # python 3.x
        try:
            self.condition.notify_all()
        except:
            self.condition.notifyAll()
        self.condition.release()


Instruction:
How would you code a function in Python 3 to
return the service information for a particular name and type.

Response:
def get_service_info(self, type, name, timeout=3000):
        """Returns network's service information for a particular
        name and type, or None if no service matches by the timeout,
        which defaults to 3 seconds."""
        info = ServiceInfo(type, name)
        if info.request(self, timeout):
            return info
        return None


Instruction:
Can you generate the documentation for the following Python 3 function
def add_serviceListener(self, type, listener):
        self.remove_service_listener(listener)
        self.browsers.append(ServiceBrowser(self, type, listener))

Response: Adds a listener for a particular service type.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def remove_service_listener(self, listener):
        for browser in self.browsers:
            if browser.listener == listener:
                browser.cancel()
                del(browser)

Response: Removes a listener from the set that is currently listening.


Instruction:
Here you have a function in Python 3, explain what it does
def register_service(self, info):
        self.check_service(info)
        self.services[info.name.lower()] = info

        # zone transfer
        self.transfer_zone(info.type)
        self.announce_service(info.name)

Response:
Registers a service with a default TTL
        of 60 seconds.


Instruction:
How would you code a function in Python 3 to
check the network for a unique service name modifying the the passed in if it is not unique.

Response:
def check_service(self, info):
        """Checks the network for a unique service name, modifying the
        ServiceInfo passed in if it is not unique."""
        now = current_time_millis()
        next_time = now
        i = 0
        while i < 3:
            for record in self.cache.entries_with_name(info.type):
                if record.type == _TYPE_PTR and \
                        not record.is_expired(now) and \
                        record.alias == info.name:
                    if (info.name.find('.') < 0):
                        info.name = info.name + ".[" + \
                                info.address + \
                                ":" + info.port + \
                                "]." + info.type
                        self.check_service(info)
                        return
                    raise NonUniqueNameException
            if now < next_time:
                self.wait(next_time - now)
                now = current_time_millis()
                continue
            out = DNSOutgoing(_FLAGS_QR_QUERY | _FLAGS_AA)
            self.debug = out
            out.add_question(
                    DNSQuestion(info.type, _TYPE_PTR, _CLASS_IN))
            out.add_authorative_answer(
                    DNSPointer(info.type,
                        _TYPE_PTR, _CLASS_IN, info.ttl, info.name))
            self.send(out)
            i += 1
            next_time += _CHECK_TIME


Instruction:
Write a Python 3 script for
adding a listener to the list of listeners that have been added to the cache.

Response:
def add_listener(self, listener, question):
        """Adds a listener for a given question.  The listener will have
        its update_record method called when information is available to
        answer the question."""
        now = current_time_millis()
        self.listeners.append(listener)
        if question is not None:
            for record in self.cache.entries_with_name(question.name):
                if question.answered_by(record) and not record.is_expired(now):
                    listener.update_record(self, now, record)
        self.notify_all()


Instruction:
Can you implement a function in Python 3 that
uses to notify listeners of new information that has updated a record.

Response:
def update_record(self, now, rec):
        """Used to notify listeners of new information that has updated
        a record."""
        for listener in self.listeners:
            listener.update_record(self, now, rec)
        self.notify_all()


Instruction:
Write a Python 3 script for
dealing with incoming response packets.

Response:
def handle_response(self, msg, address):
        """Deal with incoming response packets.  All answers
        are held in the cache, and listeners are notified."""
        now = current_time_millis()

        sigs = []
        precache = []

        for record in msg.answers:
            if isinstance(record, DNSSignature):
                sigs.append(record)
            else:
                precache.append(record)

            for e in precache:
                for s in sigs:
                    if self.verify(e, s):
                        # print "DNS: %s verified with %s" % (e,s)

                        if self.adaptive and e.type == _TYPE_A:
                            if e.address == '\x00\x00\x00\x00':
                                e.address = socket.inet_aton(address)

                        if e in self.cache.entries():
                            if e.is_expired(now):
                                for i in self.hooks:
                                    try:
                                        i.remove(e)
                                    except:
                                        pass
                                self.cache.remove(e)
                                self.cache.remove(s)
                            else:
                                entry = self.cache.get(e)
                                sig = self.cache.get(s)
                                if (entry is not None) and (sig is not None):
                                    for i in self.hooks:
                                        try:
                                            i.update(e)
                                        except:
                                            pass
                                    entry.reset_ttl(e)
                                    sig.reset_ttl(s)
                        else:
                            e.rrsig = s
                            self.cache.add(e)
                            self.cache.add(s)
                            for i in self.hooks:
                                try:
                                    i.add(e)
                                except:
                                    pass

                        precache.remove(e)
                        sigs.remove(s)
                        self.update_record(now, record)

        if self.bypass:
            for e in precache:
                if e in self.cache.entries():
                    if e.is_expired(now):
                        for i in self.hooks:
                            try:
                                i.remove(e)
                            except:
                                pass
                        self.cache.remove(e)
                    else:
                        entry = self.cache.get(e)
                        if (entry is not None):
                            for i in self.hooks:
                                try:
                                    i.update(e)
                                except:
                                    pass
                            entry.reset_ttl(e)
                else:
                    self.cache.add(e)
                    for i in self.hooks:
                        try:
                            i.add(e)
                        except:
                            pass

                self.update_record(now, record)


Instruction:
Write a Python 3 function that can
deal with incoming query packets.

Response:
def handle_query(self, msg, addr, port, orig):
        """
        Deal with incoming query packets.  Provides a response if
        possible.

        msg    - message to process
        addr    - dst addr
        port    - dst port
        orig    - originating address (for adaptive records)
        """
        out = None

        # Support unicast client responses
        #
        if port != _MDNS_PORT:
            out = DNSOutgoing(_FLAGS_QR_RESPONSE | _FLAGS_AA, 0)
            for question in msg.questions:
                out.add_question(question)
        for question in msg.questions:
            if question.type == _TYPE_PTR:
                for service in self.services.values():
                    if question.name == service.type:
                        # FIXME: sometimes we just not in time filling cache
                        answer = self.cache.get(
                                DNSPointer(service.type,
                                    _TYPE_PTR, _CLASS_IN,
                                    service.ttl, service.name))
                        if out is None and answer is not None:
                            out = DNSOutgoing(_FLAGS_QR_RESPONSE | _FLAGS_AA)
                        if answer:
                            out.add_answer(msg, answer)
            if question.type == _TYPE_AXFR:
                if question.name in list(self.zones.keys()):
                    if out is None:
                        out = DNSOutgoing(_FLAGS_QR_RESPONSE | _FLAGS_AA)
                    for i in self.zones[question.name].services.values():
                        out.add_answer(msg, i)
            else:
                try:
                    if out is None:
                        out = DNSOutgoing(_FLAGS_QR_RESPONSE | _FLAGS_AA)

                    service = self.services.get(question.name.lower(), None)
                    try:
                        rs = service.records
                    except:
                        rs = []

                    # Answer A record queries for any service addresses we know
                    if (question.type == _TYPE_A or \
                            question.type == _TYPE_ANY) \
                            and (_TYPE_A in rs):
                        for service in self.services.values():
                            if service.server == question.name.lower():
                                for i in service.address:
                                    out.add_answer(msg, self.cache.get(
                                        DNSAddress(question.name,
                                            _TYPE_A, _CLASS_IN | _CLASS_UNIQUE,
                                            service.ttl, i)))

                    if not service:
                        continue

                    if (question.type == _TYPE_SRV or \
                            question.type == _TYPE_ANY) and (_TYPE_SRV in rs):
                        out.add_answer(msg, self.cache.get(
                            DNSService(question.name,
                                _TYPE_SRV, _CLASS_IN | _CLASS_UNIQUE,
                                service.ttl, service.priority, service.weight,
                                service.port, service.server)))
                    if (question.type == _TYPE_TXT or \
                            question.type == _TYPE_ANY) and \
                            (_TYPE_TXT in rs):
                        out.add_answer(msg, self.cache.get(
                            DNSText(question.name,
                                _TYPE_TXT, _CLASS_IN | _CLASS_UNIQUE,
                                service.ttl, service.text)))
                    if (question.type == _TYPE_SRV) and (_TYPE_SRV in rs):
                        for i in service.address:
                            out.add_additional_answer(self.cache.get(
                                DNSAddress(service.server,
                                    _TYPE_A, _CLASS_IN | _CLASS_UNIQUE,
                                    service.ttl, i)))
                except:
                    traceback.print_exc()

        if out is not None and out.answers:
            out.id = msg.id
            self.send(out, addr, port)


Instruction:
How would you explain what the following Python 3 function does
def send(self, out, addr=_MDNS_ADDR, port=_MDNS_PORT):
        # This is a quick test to see if we can parse the packets we generate
        #temp = DNSIncoming(out.packet())
        for i in self.intf.values():
            try:
                return i.sendto(out.packet(), 0, (addr, port))
            except:
                traceback.print_exc()
                # Ignore this, it may be a temporary loss of network connection
                return -1

Response: Sends an outgoing packet.


Instruction:
How would you explain what the following Python 3 function does
def close(self):
        if globals()['_GLOBAL_DONE'] == 0:
            globals()['_GLOBAL_DONE'] = 1
            self.notify_all()
            self.engine.notify()
            self.unregister_all_services()
            for i in self.intf.values():
                try:
                    # there are cases, when we start mDNS without network
                    i.setsockopt(socket.SOL_IP, socket.IP_DROP_MEMBERSHIP,
                            socket.inet_aton(_MDNS_ADDR) + \
                                    socket.inet_aton('0.0.0.0'))
                except:
                    pass
                i.close()

Response: Ends the background threads and prevent this instance from servicing further queries.


Instruction:
Write a Python 3 function that can
execute Blurr BTS with the given records.

Response:
def execute(self, identity_records: 'RDD', old_state_rdd: Optional['RDD'] = None) -> 'RDD':
        """
        Executes Blurr BTS with the given records. old_state_rdd can be provided to load an older
        state from a previous run.

        :param identity_records: RDD of the form Tuple[Identity, List[TimeAndRecord]]
        :param old_state_rdd: A previous streaming BTS state RDD as Tuple[Identity, Streaming BTS
            State]
        :return: RDD[Identity, Tuple[Streaming BTS State, List of Window BTS output]]
        """
        identity_records_with_state = identity_records
        if old_state_rdd:
            identity_records_with_state = identity_records.fullOuterJoin(old_state_rdd)
        return identity_records_with_state.map(lambda x: self._execute_per_identity_records(x))


Instruction:
How would you implement a function in Python 3 that
reads the data from the given json_files path and converts them into the Record s format for the given object.

Response:
def get_record_rdd_from_json_files(self,
                                       json_files: List[str],
                                       data_processor: DataProcessor = SimpleJsonDataProcessor(),
                                       spark_session: Optional['SparkSession'] = None) -> 'RDD':
        """
        Reads the data from the given json_files path and converts them into the `Record`s format for
        processing. `data_processor` is used to process the per event data in those files to convert
        them into `Record`.

        :param json_files: List of json file paths. Regular Spark path wildcards are accepted.
        :param data_processor: `DataProcessor` to process each event in the json files.
        :param spark_session: `SparkSession` to use for execution. If None is provided then a basic
            `SparkSession` is created.
        :return: RDD containing Tuple[Identity, List[TimeAndRecord]] which can be used in
            `execute()`
        """
        spark_context = get_spark_session(spark_session).sparkContext
        raw_records: 'RDD' = spark_context.union(
            [spark_context.textFile(file) for file in json_files])
        return raw_records.mapPartitions(
            lambda x: self.get_per_identity_records(x, data_processor)).groupByKey().mapValues(list)


Instruction:
Write a Python 3 script to
convert an RDD of raw events into the Record s format for processing.

Response:
def get_record_rdd_from_rdd(
            self,
            rdd: 'RDD',
            data_processor: DataProcessor = SimpleDictionaryDataProcessor(),
    ) -> 'RDD':
        """
        Converts a RDD of raw events into the `Record`s format for processing. `data_processor` is
        used to process the per row data to convert them into `Record`.

        :param rdd: RDD containing the raw events.
        :param data_processor: `DataProcessor` to process each row in the given `rdd`.
        :return: RDD containing Tuple[Identity, List[TimeAndRecord]] which can be used in
            `execute()`
        """
        return rdd.mapPartitions(
            lambda x: self.get_per_identity_records(x, data_processor)).groupByKey().mapValues(list)


Instruction:
Write a Python 3 function that can
write the data to disk.

Response:
def write_output_file(self,
                          path: str,
                          per_identity_data: 'RDD',
                          spark_session: Optional['SparkSession'] = None) -> None:
        """
        Basic helper function to persist data to disk.

        If window BTS was provided then the window BTS output to written in csv format, otherwise,
        the streaming BTS output is written in JSON format to the `path` provided

        :param path: Path where the output should be written.
        :param per_identity_data: Output of the `execute()` call.
        :param spark_session: `SparkSession` to use for execution. If None is provided then a basic
            `SparkSession` is created.
        :return:
        """
        _spark_session_ = get_spark_session(spark_session)
        if not self._window_bts:
            per_identity_data.flatMap(
                lambda x: [json.dumps(data, cls=BlurrJSONEncoder) for data in x[1][0].items()]
            ).saveAsTextFile(path)
        else:
            # Convert to a DataFrame first so that the data can be saved as a CSV
            _spark_session_.createDataFrame(per_identity_data.flatMap(lambda x: x[1][1])).write.csv(
                path, header=True)


Instruction:
How would you explain what the following Python 3 function does
def print_output(self, per_identity_data: 'RDD') -> None:
        if not self._window_bts:
            data = per_identity_data.flatMap(
                lambda x: [json.dumps(data, cls=BlurrJSONEncoder) for data in x[1][0].items()])
        else:
            # Convert to a DataFrame first so that the data can be saved as a CSV
            data = per_identity_data.map(
                lambda x: json.dumps((x[0], x[1][1]), cls=BlurrJSONEncoder))
        for row in data.collect():
            print(row)

Response: Basic helper function to write data to stdout.


Instruction:
Write a Python 3 function that can
find an executable in the path.

Response:
def find_executable(executable, path=None):
    """
    As distutils.spawn.find_executable, but on Windows, look up
    every extension declared in PATHEXT instead of just `.exe`
    """
    if sys.platform != 'win32':
        return distutils.spawn.find_executable(executable, path)

    if path is None:
        path = os.environ['PATH']

    paths = path.split(os.pathsep)
    extensions = os.environ.get('PATHEXT', '.exe').split(os.pathsep)
    base, ext = os.path.splitext(executable)

    if not os.path.isfile(executable):
        for p in paths:
            for ext in extensions:
                f = os.path.join(p, base + ext)
                if os.path.isfile(f):
                    return f
        return None
    else:
        return executable


Instruction:
Can you generate a brief explanation for the following Python 3 code
def create_environment_dict(overrides):
    result = os.environ.copy()
    result.update(overrides or {})
    return result

Response: Create and return a copy of os. environ with the specified overrides


Instruction:
Given the following Python 3 function, write the documentation
def get(self, server):
        if not isinstance(server, six.binary_type):
            server = server.encode('utf-8')
        data = self._execute('get', server)
        result = json.loads(data.decode('utf-8'))

        # docker-credential-pass will return an object for inexistent servers
        # whereas other helpers will exit with returncode != 0. For
        # consistency, if no significant data is returned,
        # raise CredentialsNotFound
        if result['Username'] == '' and result['Secret'] == '':
            raise errors.CredentialsNotFound(
                'No matching credentials in {}'.format(self.program)
            )

        return result

Response: Retrieve credentials for server.


Instruction:
Create a Python 3 function to
store credentials for server. Raises a StoreError if an error occurs.

Response:
def store(self, server, username, secret):
        """ Store credentials for `server`. Raises a `StoreError` if an error
            occurs.
        """
        data_input = json.dumps({
            'ServerURL': server,
            'Username': username,
            'Secret': secret
        }).encode('utf-8')
        return self._execute('store', data_input)


Instruction:
Explain what the following Python 3 code does
def erase(self, server):
        if not isinstance(server, six.binary_type):
            server = server.encode('utf-8')
        self._execute('erase', server)

Response: Erase the credentials for the specified server. Raises a StoreError if an error occurs.


Instruction:
Can you write a function in Python 3 where it
evaluates and returns the identity as specified in the schema.

Response:
def get_identity(self, record: Record) -> str:
        """
        Evaluates and returns the identity as specified in the schema.
        :param record: Record which is used to determine the identity.
        :return: The evaluated identity
        :raises: IdentityError if identity cannot be determined.
        """
        context = self.schema_context.context
        context.add_record(record)
        identity = self.identity.evaluate(context)
        if not identity:
            raise IdentityError('Could not determine identity using {}. Record is {}'.format(
                self.identity.code_string, record))
        context.remove_record()
        return identity


Instruction:
Create a Python 3 function for
evaluating and updates data in the StreamingTransformer.

Response:
def run_evaluate(self, record: Record):
        """
        Evaluates and updates data in the StreamingTransformer.
        :param record: The 'source' record used for the update.
        :raises: IdentityError if identity is different from the one used during
        initialization.
        """
        record_identity = self._schema.get_identity(record)
        if self._identity != record_identity:
            raise IdentityError(
                'Identity in transformer ({}) and new record ({}) do not match'.format(
                    self._identity, record_identity))

        # Add source record and time to the global context
        self._evaluation_context.add_record(record)
        self._evaluation_context.global_add(
            'time',
            DateTimeFieldSchema.sanitize_object(
                self._schema.time.evaluate(self._evaluation_context)))
        super().run_evaluate()

        # Cleanup source and time form the context
        self._evaluation_context.remove_record()
        self._evaluation_context.global_remove('time')


Instruction:
Write a Python 3 function that can
extend the schema spec with the identity field.

Response:
def extend_schema_spec(self) -> None:
        """ Injects the identity field """
        super().extend_schema_spec()

        identity_field = {
            'Name': '_identity',
            'Type': BtsType.STRING,
            'Value': 'identity',
            ATTRIBUTE_INTERNAL: True
        }

        if self.ATTRIBUTE_FIELDS in self._spec:
            self._spec[self.ATTRIBUTE_FIELDS].insert(0, identity_field)
            self.schema_loader.add_schema_spec(identity_field, self.fully_qualified_name)


Instruction:
Explain what the following Python 3 code does
def _persist(self) -> None:
        if self._store:
            self._store.save(self._key, self._snapshot)

Response: Persist the current data to the persistent store.


Instruction:
Here you have a function in Python 3, explain what it does
def add_schema_spec(self, spec: Dict[str, Any],
                        fully_qualified_parent_name: str = None) -> Optional[str]:
        """
        Add a schema dictionary to the schema loader. The given schema is stored
        against fully_qualified_parent_name + ITEM_SEPARATOR('.') + schema.name.
        :param spec: Schema specification.
        :param fully_qualified_parent_name: Full qualified name of the parent.
        If None is passed then the schema is stored against the schema name.
        :return: The fully qualified name against which the spec is stored.
        None is returned if the given spec is not a dictionary or the spec does not
        contain a 'name' key.
        """
        if not isinstance(spec, dict) or ATTRIBUTE_NAME not in spec:
            return None

        name = spec[ATTRIBUTE_NAME]
        fully_qualified_name = name if fully_qualified_parent_name is None else self.get_fully_qualified_name(
            fully_qualified_parent_name, name)

        # Ensure that basic validation for each spec part is done before it is added to spec cache
        if isinstance(spec, dict):
            self._error_cache.add(
                validate_required_attributes(fully_qualified_name, spec, ATTRIBUTE_NAME,
                                             ATTRIBUTE_TYPE))
            if ATTRIBUTE_TYPE in spec and not Type.contains(spec[ATTRIBUTE_TYPE]):
                self._error_cache.add(
                    InvalidTypeError(fully_qualified_name, spec, ATTRIBUTE_TYPE,
                                     InvalidTypeError.Reason.TYPE_NOT_DEFINED))

        self._spec_cache[fully_qualified_name] = spec
        for key, val in spec.items():
            if isinstance(val, list):
                for item in val:
                    self.add_schema_spec(item, fully_qualified_name)
            self.add_schema_spec(val, fully_qualified_name)

        return spec[ATTRIBUTE_NAME]

Response: Adds a schema dictionary to the schema loader.


Instruction:
Make a summary of the following Python 3 code
def add_errors(self, *errors: Union[BaseSchemaError, SchemaErrorCollection]) -> None:
        for error in errors:
            self._error_cache.add(error)

Response: Adds errors to the error store for the schema.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def get_schema_object(self, fully_qualified_name: str) -> 'BaseSchema':

        if fully_qualified_name not in self._schema_cache:
            spec = self.get_schema_spec(fully_qualified_name)

            if spec:
                try:
                    self._schema_cache[fully_qualified_name] = TypeLoader.load_schema(
                        spec.get(ATTRIBUTE_TYPE, None))(fully_qualified_name, self)
                except TypeLoaderError as err:
                    self.add_errors(
                        InvalidTypeError(fully_qualified_name, spec, ATTRIBUTE_TYPE,
                                         InvalidTypeError.Reason.TYPE_NOT_LOADED,
                                         err.type_class_name))

        return self._schema_cache.get(fully_qualified_name, None)

Response: Returns an initialized schema object for the given fully_qualified_name.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def get_store(self, fully_qualified_name: str) -> Optional['Store']:

        if fully_qualified_name not in self._store_cache:
            schema = self.get_schema_object(fully_qualified_name)
            if not schema:
                return None

            if Type.is_store_type(schema.type):
                self._store_cache[fully_qualified_name] = TypeLoader.load_item(schema.type)(schema)
            else:
                self.add_errors(
                    InvalidTypeError(fully_qualified_name, {}, ATTRIBUTE_TYPE,
                                     InvalidTypeError.Reason.INCORRECT_BASE, schema.type,
                                     InvalidTypeError.BaseTypes.STORE))

        return self._store_cache.get(fully_qualified_name, None)

Response: Returns an initialized store object for the given fully qualified name.


Instruction:
Write a Python 3 function for
using to generate a schema object from the given fully qualified parent name and the given nested item name.

Response:
def get_nested_schema_object(self, fully_qualified_parent_name: str,
                                 nested_item_name: str) -> Optional['BaseSchema']:
        """
        Used to generate a schema object from the given fully_qualified_parent_name
        and the nested_item_name.
        :param fully_qualified_parent_name: The fully qualified name of the parent.
        :param nested_item_name: The nested item name.
        :return: An initialized schema object of the nested item.
        """
        return self.get_schema_object(
            self.get_fully_qualified_name(fully_qualified_parent_name, nested_item_name))


Instruction:
Can you create a Python 3 function that
returns the fully qualified name of the nested item.

Response:
def get_fully_qualified_name(fully_qualified_parent_name: str, nested_item_name: str) -> str:
        """
        Returns the fully qualified name by combining the fully_qualified_parent_name
        and nested_item_name.
        :param fully_qualified_parent_name: The fully qualified name of the parent.
        :param nested_item_name: The nested item name.
        :return: The fully qualified name of the nested item.
        """
        return fully_qualified_parent_name + SchemaLoader.ITEM_SEPARATOR + nested_item_name


Instruction:
Can you generate a brief explanation for the following Python 3 code
def get_schema_spec(self, fully_qualified_name: str) -> Dict[str, Any]:

        if fully_qualified_name not in self._spec_cache:
            self.add_errors(SpecNotFoundError(fully_qualified_name, {}))

        return self._spec_cache.get(fully_qualified_name, None)

Response: Used to retrieve the specifications of the given schema from the given fully_qualified_name of the schema.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def get_schema_specs_of_type(self, *schema_types: Type) -> Dict[str, Dict[str, Any]]:

        return {
            fq_name: schema
            for fq_name, schema in self._spec_cache.items()
            if Type.is_type_in(schema.get(ATTRIBUTE_TYPE, ''), list(schema_types))
        }

Response: Returns a list of fully qualified names and schema dictionary tuples for the given schema types.


Instruction:
Make a summary of the following Python 3 code
def global_add(self, key: str, value: Any) -> None:
        self.global_context[key] = value

Response: Adds a key and value to the global dictionary.


Instruction:
Create a Python 3 function to
merge the provided evaluation context to the current evaluation context.

Response:
def merge(self, evaluation_context: 'EvaluationContext') -> None:
        """
        Merges the provided evaluation context to the current evaluation context.
        :param evaluation_context: Evaluation context to merge.
        """
        self.global_context.merge(evaluation_context.global_context)
        self.local_context.merge(evaluation_context.local_context)


Instruction:
How would you code a function in Python 3 to
evaluate the expression with the context provided.

Response:
def evaluate(self, evaluation_context: EvaluationContext) -> Any:
        """
        Evaluates the expression with the context provided.  If the execution
        results in failure, an ExpressionEvaluationException encapsulating the
        underlying exception is raised.
        :param evaluation_context: Global and local context dictionary to be passed for evaluation
        """
        try:

            if self.type == ExpressionType.EVAL:
                return eval(self.code_object, evaluation_context.global_context,
                            evaluation_context.local_context)

            elif self.type == ExpressionType.EXEC:
                return exec(self.code_object, evaluation_context.global_context,
                            evaluation_context.local_context)

        except Exception as err:
            # Evaluation exceptions are expected because of missing fields in the source 'Record'.
            logging.debug('{} in evaluating expression {}. Error: {}'.format(
                type(err).__name__, self.code_string, err))
            # These should result in an exception being raised:
            # NameError - Exceptions thrown because of using names in the expression which are not
            #   present in EvaluationContext. A common cause for this is typos in the BTS.
            # MissingAttributeError - Exception thrown when a BTS nested item is used which does not
            #   exist. Should only happen for erroneous BTSs.
            # ImportError - Thrown when there is a failure in importing other modules.
            if isinstance(err, (NameError, MissingAttributeError, ImportError)):
                raise err
            return None


Instruction:
Create a Python 3 function for
copying all the files in source directory to target.

Response:
def _copy_files(source, target):
    """
    Copy all the files in source directory to target.

    Ignores subdirectories.
    """
    source_files = listdir(source)
    if not exists(target):
        makedirs(target)
    for filename in source_files:
        full_filename = join(source, filename)
        if isfile(full_filename):
            shutil.copy(full_filename, target)


Instruction:
Here you have a function in Python 3, explain what it does
def create_copy(self):
        if self.executable is None or not isfile(self.executable):
            raise FileNotFoundError(
                "Could not find MAGICC{} executable: {}".format(
                    self.version, self.executable
                )
            )
        if self.is_temp:
            assert (
                self.root_dir is None
            ), "A temp copy for this instance has already been created"
            self.root_dir = mkdtemp(prefix="pymagicc-")

        if exists(self.run_dir):
            raise Exception("A copy of MAGICC has already been created.")
        if not exists(self.root_dir):
            makedirs(self.root_dir)

        exec_dir = basename(self.original_dir)

        # Copy a subset of folders from the MAGICC `original_dir`
        # Also copy anything which is in the root of the MAGICC distribution
        # Assumes that the MAGICC binary is in a folder one level below the root
        # of the MAGICC distribution. i.e. /run/magicc.exe or /bin/magicc
        dirs_to_copy = [".", "bin", "run"]
        # Check that the executable is in a valid sub directory
        assert exec_dir in dirs_to_copy, "binary must be in bin/ or run/ directory"

        for d in dirs_to_copy:
            source_dir = abspath(join(self.original_dir, "..", d))
            if exists(source_dir):
                _copy_files(source_dir, join(self.root_dir, d))

        # Create an empty out dir
        # MAGICC assumes that the 'out' directory already exists
        makedirs(join(self.root_dir, "out"))

        # Create basic configuration files so magicc can run
        self.set_years()
        self.set_config()

Response: Creates a temporary directory structure and copy of MAGICC configuration files and binary.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def run(self, scenario=None, only=None, **kwargs):
        if not exists(self.root_dir):
            raise FileNotFoundError(self.root_dir)

        if self.executable is None:
            raise ValueError(
                "MAGICC executable not found, try setting an environment variable `MAGICC_EXECUTABLE_{}=/path/to/binary`".format(
                    self.version
                )
            )

        if scenario is not None:
            kwargs = self.set_emission_scenario_setup(scenario, kwargs)

        yr_config = {}
        if "startyear" in kwargs:
            yr_config["startyear"] = kwargs.pop("startyear")
        if "endyear" in kwargs:
            yr_config["endyear"] = kwargs.pop("endyear")
        if yr_config:
            self.set_years(**yr_config)

        # should be able to do some other nice metadata stuff re how magicc was run
        # etc. here
        kwargs.setdefault("rundate", get_date_time_string())

        self.update_config(**kwargs)

        self.check_config()

        exec_dir = basename(self.original_dir)
        command = [join(self.root_dir, exec_dir, self.binary_name)]

        if not IS_WINDOWS and self.binary_name.endswith(".exe"):  # pragma: no cover
            command.insert(0, "wine")

        # On Windows shell=True is required.
        subprocess.check_call(command, cwd=self.run_dir, shell=IS_WINDOWS)

        outfiles = self._get_output_filenames()

        read_cols = {"climate_model": ["MAGICC{}".format(self.version)]}
        if scenario is not None:
            read_cols["model"] = scenario["model"].unique().tolist()
            read_cols["scenario"] = scenario["scenario"].unique().tolist()
        else:
            read_cols.setdefault("model", ["unspecified"])
            read_cols.setdefault("scenario", ["unspecified"])

        mdata = None
        for filepath in outfiles:
            try:
                openscm_var = _get_openscm_var_from_filepath(filepath)
                if only is None or openscm_var in only:
                    tempdata = MAGICCData(
                        join(self.out_dir, filepath), columns=deepcopy(read_cols)
                    )
                    mdata = mdata.append(tempdata) if mdata is not None else tempdata

            except (NoReaderWriterError, InvalidTemporalResError):
                continue

        if mdata is None:
            error_msg = "No output found for only={}".format(only)
            raise ValueError(error_msg)

        try:
            run_paras = self.read_parameters()
            self.config = run_paras
            mdata.metadata["parameters"] = run_paras
        except FileNotFoundError:
            pass

        return mdata

Response: Run MAGICC and parse the output.


Instruction:
Can you implement a function in Python 3 that
checks that our MAGICC. CFG files are set to safely work with Pymagicc.

Response:
def check_config(self):
        """Check that our MAGICC ``.CFG`` files are set to safely work with PYMAGICC

        For further detail about why this is required, please see :ref:`MAGICC flags`.

        Raises
        ------
        ValueError
            If we are not certain that the config written by PYMAGICC will overwrite
            all other config i.e. that there will be no unexpected behaviour. A
            ValueError will also be raised if the user tries to use more than one
            scenario file.
        """
        cfg_error_msg = (
            "PYMAGICC is not the only tuning model that will be used by "
            "`MAGCFG_USER.CFG`: your run is likely to fail/do odd things"
        )
        emisscen_error_msg = (
            "You have more than one `FILE_EMISSCEN_X` flag set. Using more than "
            "one emissions scenario is hard to debug and unnecessary with "
            "Pymagicc's dataframe scenario input. Please combine all your "
            "scenarios into one dataframe with Pymagicc and pandas, then feed "
            "this single Dataframe into Pymagicc's run API."
        )

        nml_to_check = "nml_allcfgs"
        usr_cfg = read_cfg_file(join(self.run_dir, "MAGCFG_USER.CFG"))
        for k in usr_cfg[nml_to_check]:
            if k.startswith("file_tuningmodel"):
                first_tuningmodel = k in ["file_tuningmodel", "file_tuningmodel_1"]
                if first_tuningmodel:
                    if usr_cfg[nml_to_check][k] != "PYMAGICC":
                        raise ValueError(cfg_error_msg)
                elif usr_cfg[nml_to_check][k] not in ["USER", ""]:
                    raise ValueError(cfg_error_msg)

            elif k.startswith("file_emisscen_"):
                if usr_cfg[nml_to_check][k] not in ["NONE", ""]:
                    raise ValueError(emisscen_error_msg)


Instruction:
Write a Python 3 function for
writing an input file to disk

Response:
def write(self, mdata, name):
        """Write an input file to disk

        Parameters
        ----------
        mdata : :obj:`pymagicc.io.MAGICCData`
            A MAGICCData instance with the data to write

        name : str
            The name of the file to write. The file will be written to the MAGICC
            instance's run directory i.e. ``self.run_dir``
        """
        mdata.write(join(self.run_dir, name), self.version)


Instruction:
Can you tell what is the following Python 3 function doing
def read_parameters(self):
        param_fname = join(self.out_dir, "PARAMETERS.OUT")

        if not exists(param_fname):
            raise FileNotFoundError("No PARAMETERS.OUT found")

        with open(param_fname) as nml_file:
            parameters = dict(f90nml.read(nml_file))
            for group in ["nml_years", "nml_allcfgs", "nml_outputcfgs"]:
                parameters[group] = dict(parameters[group])
                for k, v in parameters[group].items():
                    parameters[group][k] = _clean_value(v)
                parameters[group.replace("nml_", "")] = parameters.pop(group)
            self.config = parameters
        return parameters

Response: Read a parameters. out file and return a dictionary containing all the configuration used by MAGICC


Instruction:
Can you tell what is the following Python 3 function doing
def remove_temp_copy(self):
        if self.is_temp and self.root_dir is not None:
            shutil.rmtree(self.root_dir)
            self.root_dir = None

Response: Removes a temporary copy of the MAGICC version shipped with Pymagicc.


Instruction:
Write a Python 3 function that can
create a configuration file for the current version of the MAGICC.

Response:
def set_config(
        self, filename="MAGTUNE_PYMAGICC.CFG", top_level_key="nml_allcfgs", **kwargs
    ):
        """
        Create a configuration file for MAGICC.

        Writes a fortran namelist in run_dir.

        Parameters
        ----------
        filename : str
            Name of configuration file to write

        top_level_key : str
            Name of namelist to be written in the
            configuration file

        kwargs
            Other parameters to pass to the configuration file. No
            validation on the parameters is performed.

        Returns
        -------
        dict
            The contents of the namelist which was written to file
        """
        kwargs = self._format_config(kwargs)

        fname = join(self.run_dir, filename)
        conf = {top_level_key: kwargs}
        f90nml.write(conf, fname, force=True)

        return conf


Instruction:
Write a Python 3 script to
update a configuration file for MAGICC and returns the contents of the file.

Response:
def update_config(
        self, filename="MAGTUNE_PYMAGICC.CFG", top_level_key="nml_allcfgs", **kwargs
    ):
        """Updates a configuration file for MAGICC

        Updates the contents of a fortran namelist in the run directory,
        creating a new namelist if none exists.

        Parameters
        ----------
        filename : str
            Name of configuration file to write

        top_level_key : str
            Name of namelist to be written in the
            configuration file

        kwargs
            Other parameters to pass to the configuration file. No
            validation on the parameters is performed.

        Returns
        -------
        dict
            The contents of the namelist which was written to file
        """
        kwargs = self._format_config(kwargs)
        fname = join(self.run_dir, filename)

        if exists(fname):
            conf = f90nml.read(fname)
        else:
            conf = {top_level_key: {}}

        conf[top_level_key].update(kwargs)
        f90nml.write(conf, fname, force=True)

        return conf


Instruction:
Explain what the following Python 3 code does
def set_zero_config(self):
        # zero_emissions is imported from scenarios module
        zero_emissions.write(join(self.run_dir, self._scen_file_name), self.version)

        time = zero_emissions.filter(variable="Emissions|CH4", region="World")[
            "time"
        ].values
        no_timesteps = len(time)
        # value doesn't actually matter as calculations are done from difference but
        # chose sensible value nonetheless
        ch4_conc_pi = 722
        ch4_conc = ch4_conc_pi * np.ones(no_timesteps)
        ch4_conc_df = pd.DataFrame(
            {
                "time": time,
                "scenario": "idealised",
                "model": "unspecified",
                "climate_model": "unspecified",
                "variable": "Atmospheric Concentrations|CH4",
                "unit": "ppb",
                "todo": "SET",
                "region": "World",
                "value": ch4_conc,
            }
        )
        ch4_conc_writer = MAGICCData(ch4_conc_df)
        ch4_conc_filename = "HIST_CONSTANT_CH4_CONC.IN"
        ch4_conc_writer.metadata = {
            "header": "Constant pre-industrial CH4 concentrations"
        }
        ch4_conc_writer.write(join(self.run_dir, ch4_conc_filename), self.version)

        fgas_conc_pi = 0
        fgas_conc = fgas_conc_pi * np.ones(no_timesteps)
        # MAGICC6 doesn't read this so not a problem, for MAGICC7 we might have to
        # write each file separately
        varname = "FGAS_CONC"
        fgas_conc_df = pd.DataFrame(
            {
                "time": time,
                "scenario": "idealised",
                "model": "unspecified",
                "climate_model": "unspecified",
                "variable": varname,
                "unit": "ppt",
                "todo": "SET",
                "region": "World",
                "value": fgas_conc,
            }
        )
        fgas_conc_writer = MAGICCData(fgas_conc_df)
        fgas_conc_filename = "HIST_ZERO_{}.IN".format(varname)
        fgas_conc_writer.metadata = {"header": "Zero concentrations"}
        fgas_conc_writer.write(join(self.run_dir, fgas_conc_filename), self.version)

        emis_config = self._fix_any_backwards_emissions_scen_key_in_config(
            {"file_emissionscenario": self._scen_file_name}
        )
        self.set_config(
            **emis_config,
            rf_initialization_method="ZEROSTARTSHIFT",
            rf_total_constantafteryr=10000,
            file_co2i_emis="",
            file_co2b_emis="",
            co2_switchfromconc2emis_year=1750,
            file_ch4i_emis="",
            file_ch4b_emis="",
            file_ch4n_emis="",
            file_ch4_conc=ch4_conc_filename,
            ch4_switchfromconc2emis_year=10000,
            file_n2oi_emis="",
            file_n2ob_emis="",
            file_n2on_emis="",
            file_n2o_conc="",
            n2o_switchfromconc2emis_year=1750,
            file_noxi_emis="",
            file_noxb_emis="",
            file_noxi_ot="",
            file_noxb_ot="",
            file_noxt_rf="",
            file_soxnb_ot="",
            file_soxi_ot="",
            file_soxt_rf="",
            file_soxi_emis="",
            file_soxb_emis="",
            file_soxn_emis="",
            file_oci_emis="",
            file_ocb_emis="",
            file_oci_ot="",
            file_ocb_ot="",
            file_oci_rf="",
            file_ocb_rf="",
            file_bci_emis="",
            file_bcb_emis="",
            file_bci_ot="",
            file_bcb_ot="",
            file_bci_rf="",
            file_bcb_rf="",
            bcoc_switchfromrf2emis_year=1750,
            file_nh3i_emis="",
            file_nh3b_emis="",
            file_nmvoci_emis="",
            file_nmvocb_emis="",
            file_coi_emis="",
            file_cob_emis="",
            file_mineraldust_rf="",
            file_landuse_rf="",
            file_bcsnow_rf="",
            # rf_fgassum_scale=0,  # this appears to do nothing, hence the next two lines
            file_fgas_conc=[fgas_conc_filename] * 12,
            fgas_switchfromconc2emis_year=10000,
            rf_mhalosum_scale=0,
            mhalo_switch_conc2emis_yr=1750,
            stratoz_o3scale=0,
            rf_volcanic_scale=0,
            rf_solar_scale=0,
        )

Response: Set the config such that radiative forcing and temperature output will be zero.


Instruction:
Create a Python 3 function for
setting the start and end dates of the simulations.

Response:
def set_years(self, startyear=1765, endyear=2100):
        """
        Set the start and end dates of the simulations.

        Parameters
        ----------
        startyear : int
            Start year of the simulation

        endyear : int
            End year of the simulation

        Returns
        -------
        dict
            The contents of the namelist
        """
        # TODO: test altering stepsperyear, I think 1, 2 and 24 should all work
        return self.set_config(
            "MAGCFG_NMLYEARS.CFG",
            "nml_years",
            endyear=endyear,
            startyear=startyear,
            stepsperyear=12,
        )


Instruction:
Here you have a function in Python 3, explain what it does
def set_output_variables(self, write_ascii=True, write_binary=False, **kwargs):

        assert (
            write_ascii or write_binary
        ), "write_binary and/or write_ascii must be configured"
        if write_binary and write_ascii:
            ascii_binary = "BOTH"
        elif write_ascii:
            ascii_binary = "ASCII"
        else:
            ascii_binary = "BINARY"

        # defaults
        outconfig = {
            "out_emissions": 0,
            "out_gwpemissions": 0,
            "out_sum_gwpemissions": 0,
            "out_concentrations": 0,
            "out_carboncycle": 0,
            "out_forcing": 0,
            "out_surfaceforcing": 0,
            "out_permafrost": 0,
            "out_temperature": 0,
            "out_sealevel": 0,
            "out_parameters": 0,
            "out_misc": 0,
            "out_timeseriesmix": 0,
            "out_rcpdata": 0,
            "out_summaryidx": 0,
            "out_inverseemis": 0,
            "out_tempoceanlayers": 0,
            "out_heatuptake": 0,
            "out_ascii_binary": ascii_binary,
            "out_warnings": 0,
            "out_precipinput": 0,
            "out_aogcmtuning": 0,
            "out_ccycletuning": 0,
            "out_observationaltuning": 0,
            "out_keydata_1": 0,
            "out_keydata_2": 0,
        }
        if self.version == 7:
            outconfig["out_oceanarea"] = 0
            outconfig["out_lifetimes"] = 0

        for kw in kwargs:
            val = 1 if kwargs[kw] else 0  # convert values to 0/1 instead of booleans
            outconfig["out_" + kw.lower()] = val

        self.update_config(**outconfig)

Response: Set the output configuration minimising output as much as possible.


Instruction:
How would you explain what the following Python 3 function does
def diagnose_tcr_ecs(self, **kwargs):
        if self.version == 7:
            raise NotImplementedError("MAGICC7 cannot yet diagnose ECS and TCR")
        self._diagnose_tcr_ecs_config_setup(**kwargs)
        timeseries = self.run(
            scenario=None,
            only=[
                "Atmospheric Concentrations|CO2",
                "Radiative Forcing",
                "Surface Temperature",
            ],
        )
        tcr, ecs = self._get_tcr_ecs_from_diagnosis_results(timeseries)
        return {"tcr": tcr, "ecs": ecs, "timeseries": timeseries}

Response: Diagnose TCR and ECS and return a dictionary of the relevant model input and output times.


Instruction:
Write a Python 3 script to
set the emissions flags correctly.

Response:
def set_emission_scenario_setup(self, scenario, config_dict):
        """Set the emissions flags correctly.

        Parameters
        ----------
        scenario : :obj:`pymagicc.io.MAGICCData`
            Scenario to run.

        config_dict : dict
            Dictionary with current input configurations which is to be validated and
            updated where necessary.

        Returns
        -------
        dict
            Updated configuration
        """
        self.write(scenario, self._scen_file_name)
        # can be lazy in this line as fix backwards key handles errors for us
        config_dict["file_emissionscenario"] = self._scen_file_name
        config_dict = self._fix_any_backwards_emissions_scen_key_in_config(config_dict)

        return config_dict


Instruction:
Can you create a Python 3 function that
checks if a type is defined

Response:
def contains(value: Union[str, 'Type']) -> bool:
        """ Checks if a type is defined """
        if isinstance(value, str):
            return any(value.lower() == i.value for i in Type)

        return any(value == i for i in Type)


Instruction:
Here you have a function in Python 3, explain what it does
def xml_replace(filename, **replacements):
    keywords = set(replacements.keys())
    templatename = f'{filename}.xmlt'
    targetname = f'{filename}.xml'
    print(f'template file: {templatename}')
    print(f'target file: {targetname}')
    print('replacements:')
    with open(templatename) as templatefile:
        templatebody = templatefile.read()
    parts = templatebody.replace('<!--|', '|-->').split('|-->')
    defaults = {}
    for idx, part in enumerate(parts):
        if idx % 2:
            subparts = part.partition('=')
            if subparts[2]:
                parts[idx] = subparts[0]
                if subparts[0] not in replacements:
                    if ((subparts[0] in defaults) and
                            (defaults[subparts[0]] != str(subparts[2]))):
                        raise RuntimeError(
                            f'Template file `{templatename}` defines '
                            f'different default values for marker '
                            f'`{subparts[0]}`.')
                    defaults[subparts[0]] = str(subparts[2])
    markers = parts[1::2]
    try:
        unused_keywords = keywords.copy()
        for idx, part in enumerate(parts):
            if idx % 2:
                argument_info = 'given argument'
                newpart = replacements.get(part)
                if newpart is None:
                    argument_info = 'default argument'
                    newpart = defaults.get(part)
                if newpart is None:
                    raise RuntimeError(
                        f'Marker `{part}` cannot be replaced.')
                print(f'  {part} --> {newpart} ({argument_info})')
                parts[idx] = str(newpart)
                unused_keywords.discard(part)
        targetbody = ''.join(parts)
        if unused_keywords:
            raise RuntimeError(
                f'Keyword(s) `{objecttools.enumeration(unused_keywords)}` '
                f'cannot be used.')
        with open(targetname, 'w') as targetfile:
            targetfile.write(targetbody)
    except BaseException:
        objecttools.augment_excmessage(
            f'While trying to replace the markers '
            f'`{objecttools.enumeration(sorted(set(markers)))}` of the '
            f'XML template file `{templatename}` with the available '
            f'keywords `{objecttools.enumeration(sorted(keywords))}`')

Response: Read the content of an XML template file and apply the given replacements to the given XML file.


Instruction:
Implement a function in Python 3 to
return the required indexes based on the given lambda function and the Timegrids object handled by module hydpy. pub.

Response:
def _calcidxs(func):
        """Return the required indexes based on the given lambda function
        and the |Timegrids| object handled by module |pub|.  Raise a
        |RuntimeError| if the latter is not available.
        """
        timegrids = hydpy.pub.get('timegrids')
        if timegrids is None:
            raise RuntimeError(
                'An Indexer object has been asked for an %s array.  Such an '
                'array has neither been determined yet nor can it be '
                'determined automatically at the moment.   Either define an '
                '%s array manually and pass it to the Indexer object, or make '
                'a proper Timegrids object available within the pub module.  '
                'In usual HydPy applications, the latter is done '
                'automatically.'
                % (func.__name__, func.__name__))
        idxs = numpy.empty(len(timegrids.init), dtype=int)
        for jdx, date in enumerate(hydpy.pub.timegrids.init):
            idxs[jdx] = func(date)
        return idxs


Instruction:
Explain what the following Python 3 code does
def dayofyear(self):
        def _dayofyear(date):
            return (date.dayofyear-1 +
                    ((date.month > 2) and (not date.leapyear)))
        return _dayofyear

Response: Return the day of the year index.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def timeofyear(self):
        refgrid = timetools.Timegrid(
            timetools.Date('2000.01.01'),
            timetools.Date('2001.01.01'),
            hydpy.pub.timegrids.stepsize)

        def _timeofyear(date):
            date = copy.deepcopy(date)
            date.year = 2000
            return refgrid[date]

        return _timeofyear

Response: Return a function that returns the time of the year index for the current year.


Instruction:
Can you write a function in Python 3 where it
assigns the given docstring to the property instance and if possible to the module of its owner class.

Response:
def set_doc(self, doc: str):
        """Assign the given docstring to the property instance and, if
        possible, to the `__test__` dictionary of the module of its
        owner class."""
        self.__doc__ = doc
        if hasattr(self, 'module'):
            ref = f'{self.objtype.__name__}.{self.name}'
            self.module.__dict__['__test__'][ref] = doc


Instruction:
Explain what the following Python 3 code does
def getter_(self, fget) -> 'BaseProperty':
        self.fget = fget
        self.set_doc(fget.__doc__)
        return self

Response:
Add the given getter function and its docstring to the
         property and return it.


Instruction:
Write a Python 3 function for
returning |True| or |False| to indicate if the protected property is ready for the given object.

Response:
def isready(self, obj) -> bool:
        """Return |True| or |False| to indicate if the protected
        property is ready for the given object.  If the object is
        unknow, |ProtectedProperty| returns |False|."""
        return vars(obj).get(self.name, False)


Instruction:
Given the following Python 3 function, write the documentation
def allready(self, obj) -> bool:
        for prop in self.__properties:
            if not prop.isready(obj):
                return False
        return True

Response:
Return |True| or |False| to indicate whether all protected
        properties are ready or not.


Instruction:
Make a summary of the following Python 3 code
def call_fget(self, obj) -> Any:
        custom = vars(obj).get(self.name)
        if custom is None:
            return self.fget(obj)
        return custom

Response: Return the predefined custom value when available otherwise return the value defined by the getter function.


Instruction:
Here you have a function in Python 3, explain what it does
def call_fset(self, obj, value) -> None:
        vars(obj)[self.name] = self.fset(obj, value)

Response: Store the given custom value and call the setter function.


Instruction:
How would you explain what the following Python 3 function does
def call_fdel(self, obj) -> None:
        self.fdel(obj)
        try:
            del vars(obj)[self.name]
        except KeyError:
            pass

Response: Remove the predefined custom value and call the delete function.


Instruction:
Can you tell what is the following Python 3 function doing
def trim(self, lower=None, upper=None):
        if lower is None:
            lower = getattr(self.subpars.relwb, 'value', None)
        lland_parameters.ParameterSoil.trim(self, lower, upper)

Response: Trim upper values in accordance with RelWB \\ leq RelWZ.


Instruction:
Can you write a function in Python 3 where it
trims upper values in accordance with RelWB \\ leq RelWZ.

Response:
def trim(self, lower=None, upper=None):
        """Trim upper values in accordance with :math:`RelWB \\leq RelWZ`.

        >>> from hydpy.models.lland import *
        >>> parameterstep('1d')
        >>> nhru(3)
        >>> lnk(ACKER)
        >>> relwz.values = 0.5
        >>> relwb(0.2, 0.5, 0.8)
        >>> relwb
        relwb(0.2, 0.5, 0.5)
        """
        if upper is None:
            upper = getattr(self.subpars.relwz, 'value', None)
        lland_parameters.ParameterSoil.trim(self, lower, upper)


Instruction:
Can you tell what is the following Python 3 function doing
def trim(self, lower=None, upper=None):
        if lower is None:
            lower = getattr(self.subpars.eqi1, 'value', None)
        super().trim(lower, upper)

Response: Trim lower values in accordance with : math : EQI1 \\ leq EQB.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def trim(self, lower=None, upper=None):
        if lower is None:
            lower = getattr(self.subpars.eqi2, 'value', None)
        if upper is None:
            upper = getattr(self.subpars.eqb, 'value', None)
        super().trim(lower, upper)

Response:
Trim lower values in accordance with
       .


Instruction:
Write a Python 3 script for
returning a list of digital time choices every half hour from 00 to 23 to 30.

Response:
def time_choices():
    """Return digital time choices every half hour from 00:00 to 23:30."""
    hours = list(range(0, 24))
    times = []
    for h in hours:
        hour = str(h).zfill(2)
        times.append(hour+':00')
        times.append(hour+':30')
    return list(zip(times, times))


Instruction:
Make a summary of the following Python 3 code
def _add_lines(specification, module):
    caption = _all_spec2capt.get(specification, 'dummy')
    if caption.split()[-1] in ('parameters', 'sequences', 'Masks'):
        exists_collectionclass = True
        name_collectionclass = caption.title().replace(' ', '')
    else:
        exists_collectionclass = False
    lines = []
    if specification == 'model':
        lines += [f'',
                  f'.. autoclass:: {module.__name__}.Model',
                  f'    :members:',
                  f'    :show-inheritance:',
                  f'    :exclude-members: {", ".join(EXCLUDE_MEMBERS)}']
    elif exists_collectionclass:
        lines += [f'',
                  f'.. autoclass:: {module.__name__}.{name_collectionclass}',
                  f'    :members:',
                  f'    :show-inheritance:',
                  f'    :exclude-members: {", ".join(EXCLUDE_MEMBERS)}']
    lines += ['',
              '.. automodule:: ' + module.__name__,
              '    :members:',
              '    :show-inheritance:']
    if specification == 'model':
        lines += ['    :exclude-members: Model']
    elif exists_collectionclass:
        lines += ['    :exclude-members: ' + name_collectionclass]
    return lines

Response: Return a list of autodoc commands for a basemodels docstring.


Instruction:
Make a summary of the following Python 3 code
def autodoc_basemodel(module):
    autodoc_tuple2doc(module)
    namespace = module.__dict__
    doc = namespace.get('__doc__')
    if doc is None:
        doc = ''
    basemodulename = namespace['__name__'].split('.')[-1]
    modules = {key: value for key, value in namespace.items()
               if (isinstance(value, types.ModuleType) and
                   key.startswith(basemodulename+'_'))}
    substituter = Substituter(hydpy.substituter)
    lines = []
    specification = 'model'
    modulename = basemodulename+'_'+specification
    if modulename in modules:
        module = modules[modulename]
        lines += _add_title('Model features', '-')
        lines += _add_lines(specification, module)
        substituter.add_module(module)
    for (title, spec2capt) in (('Parameter features', _PAR_SPEC2CAPT),
                               ('Sequence features', _SEQ_SPEC2CAPT),
                               ('Auxiliary features', _AUX_SPEC2CAPT)):
        found_module = False
        new_lines = _add_title(title, '-')
        for (specification, caption) in spec2capt.items():
            modulename = basemodulename+'_'+specification
            module = modules.get(modulename)
            if module:
                found_module = True
                new_lines += _add_title(caption, '.')
                new_lines += _add_lines(specification, module)
                substituter.add_module(module)
        if found_module:
            lines += new_lines
    doc += '\n'.join(lines)
    namespace['__doc__'] = doc
    basemodule = importlib.import_module(namespace['__name__'])
    substituter.add_module(basemodule)
    substituter.update_masters()
    namespace['substituter'] = substituter

Response: Add an exhaustive docstring to the given module of a basemodel.


Instruction:
How would you explain what the following Python 3 function does
def autodoc_applicationmodel(module):
    autodoc_tuple2doc(module)
    name_applicationmodel = module.__name__
    name_basemodel = name_applicationmodel.split('_')[0]
    module_basemodel = importlib.import_module(name_basemodel)
    substituter = Substituter(module_basemodel.substituter)
    substituter.add_module(module)
    substituter.update_masters()
    module.substituter = substituter

Response:
Improves the docstrings of application models when called
    at the bottom of the respective module.


Instruction:
Write a Python 3 script for
preparing and return a |Substituter| object for the main __init__ object of HydPy *.

Response:
def prepare_mainsubstituter():
    """Prepare and return a |Substituter| object for the main `__init__`
    file of *HydPy*."""
    substituter = Substituter()
    for module in (builtins, numpy, datetime, unittest, doctest, inspect, io,
                   os, sys, time, collections, itertools, subprocess, scipy,
                   typing):
        substituter.add_module(module)
    for subpackage in (auxs, core, cythons, exe):
        for dummy, name, dummy in pkgutil.walk_packages(subpackage.__path__):
            full_name = subpackage.__name__ + '.' + name
            substituter.add_module(importlib.import_module(full_name))
    substituter.add_modules(models)
    for cymodule in (annutils, smoothutils, pointerutils):
        substituter.add_module(cymodule, cython=True)
    substituter._short2long['|pub|'] = ':mod:`~hydpy.pub`'
    substituter._short2long['|config|'] = ':mod:`~hydpy.config`'
    return substituter


Instruction:
Can you generate the documentation for the following Python 3 function
def _number_of_line(member_tuple):
    member = member_tuple[1]
    try:
        return member.__code__.co_firstlineno
    except AttributeError:
        pass
    try:
        return inspect.findsource(member)[1]
    except BaseException:
        pass
    for value in vars(member).values():
        try:
            return value.__code__.co_firstlineno
        except AttributeError:
            pass
    return 0

Response:
Try to return the number of the first line of the definition of a
    member of a module.


Instruction:
Can you tell what is the following Python 3 function doing
def autodoc_module(module):
    doc = getattr(module, '__doc__')
    if doc is None:
        doc = ''
    members = []
    for name, member in inspect.getmembers(module):
        if ((not name.startswith('_')) and
                (inspect.getmodule(member) is module)):
            members.append((name, member))
    members = sorted(members, key=_number_of_line)
    if members:
        lines = ['\n\nModule :mod:`~%s` implements the following members:\n'
                 % module.__name__]
        for (name, member) in members:
            if inspect.isfunction(member):
                type_ = 'func'
            elif inspect.isclass(member):
                type_ = 'class'
            else:
                type_ = 'obj'
            lines.append('      * :%s:`~%s` %s'
                         % (type_, name, objecttools.description(member)))
        doc = doc + '\n\n' + '\n'.join(lines) + '\n\n' + 80*'_'
        module.__doc__ = doc

Response: Add a short summary of all implemented members to a modules docstring.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def autodoc_tuple2doc(module):
    modulename = module.__name__
    for membername, member in inspect.getmembers(module):
        for tuplename, descr in _name2descr.items():
            tuple_ = getattr(member, tuplename, None)
            if tuple_:
                logstring = f'{modulename}.{membername}.{tuplename}'
                if logstring not in _loggedtuples:
                    _loggedtuples.add(logstring)
                    lst = [f'\n\n\n    {descr}:']
                    if tuplename == 'CLASSES':
                        type_ = 'func'
                    else:
                        type_ = 'class'
                    for cls in tuple_:
                        lst.append(
                            f'      * '
                            f':{type_}:`{cls.__module__}.{cls.__name__}`'
                            f' {objecttools.description(cls)}')
                    doc = getattr(member, '__doc__')
                    if doc is None:
                        doc = ''
                    member.__doc__ = doc + '\n'.join(l for l in lst)

Response: Include tuples as CLASS of ControlParameters and RUN_METHODS of Models into the respective docstring.


Instruction:
Given the following Python 3 function, write the documentation
def consider_member(name_member, member, module, class_=None):
        if name_member.startswith('_'):
            return False
        if inspect.ismodule(member):
            return False
        real_module = getattr(member, '__module__', None)
        if not real_module:
            return True
        if real_module != module.__name__:
            if class_ and hasattr(member, '__get__'):
                return True
            if 'hydpy' in real_module:
                return False
            if module.__name__ not in real_module:
                return False
        return True

Response:
Return |True| if the given member should be added to the
        substitutions. If not return |False|.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def get_role(member, cython=False):
        if inspect.isroutine(member) or isinstance(member, numpy.ufunc):
            return 'func'
        elif inspect.isclass(member):
            return 'class'
        elif cython:
            return 'func'
        return 'const'

Response: Return the reStructuredText role func class or const for the given member.


Instruction:
Given the following Python 3 function, write the documentation
def add_substitution(self, short, medium, long, module):
        name = module.__name__
        if 'builtin' in name:
            self._short2long[short] = long.split('~')[0] + long.split('.')[-1]
        else:
            if ('hydpy' in name) and (short not in self._blacklist):
                if short in self._short2long:
                    if self._short2long[short] != long:
                        self._blacklist.add(short)
                        del self._short2long[short]
                else:
                    self._short2long[short] = long
            self._medium2long[medium] = long

Response: Add the given substitutions both as a short2long mapping and a medium2long mapping.


Instruction:
Create a Python 3 function to
add the given module to the internal dictionary.

Response:
def add_module(self, module, cython=False):
        """Add the given module, its members, and their submembers.

        The first examples are based on the site-package |numpy|: which
        is passed to method |Substituter.add_module|:

        >>> from hydpy.core.autodoctools import Substituter
        >>> substituter = Substituter()
        >>> import numpy
        >>> substituter.add_module(numpy)

        Firstly, the module itself is added:

        >>> substituter.find('|numpy|')
        |numpy| :mod:`~numpy`

        Secondly, constants like |numpy.nan| are added:

        >>> substituter.find('|numpy.nan|')
        |numpy.nan| :const:`~numpy.nan`

        Thirdly, functions like |numpy.clip| are added:

        >>> substituter.find('|numpy.clip|')
        |numpy.clip| :func:`~numpy.clip`

        Fourthly, clases line |numpy.ndarray| are added:

        >>> substituter.find('|numpy.ndarray|')
        |numpy.ndarray| :class:`~numpy.ndarray`

        When adding Cython modules, the `cython` flag should be set |True|:

        >>> from hydpy.cythons import pointerutils
        >>> substituter.add_module(pointerutils, cython=True)
        >>> substituter.find('set_pointer')
        |PPDouble.set_pointer| \
:func:`~hydpy.cythons.autogen.pointerutils.PPDouble.set_pointer`
        |pointerutils.PPDouble.set_pointer| \
:func:`~hydpy.cythons.autogen.pointerutils.PPDouble.set_pointer`
        """
        name_module = module.__name__.split('.')[-1]
        short = ('|%s|'
                 % name_module)
        long = (':mod:`~%s`'
                % module.__name__)
        self._short2long[short] = long
        for (name_member, member) in vars(module).items():
            if self.consider_member(
                    name_member, member, module):
                role = self.get_role(member, cython)
                short = ('|%s|'
                         % name_member)
                medium = ('|%s.%s|'
                          % (name_module,
                             name_member))
                long = (':%s:`~%s.%s`'
                        % (role,
                           module.__name__,
                           name_member))
                self.add_substitution(short, medium, long, module)
                if inspect.isclass(member):
                    for name_submember, submember in vars(member).items():
                        if self.consider_member(
                                name_submember, submember, module, member):
                            role = self.get_role(submember, cython)
                            short = ('|%s.%s|'
                                     % (name_member,
                                        name_submember))
                            medium = ('|%s.%s.%s|'
                                      % (name_module,
                                         name_member,
                                         name_submember))
                            long = (':%s:`~%s.%s.%s`'
                                    % (role,
                                       module.__name__,
                                       name_member,
                                       name_submember))
                            self.add_substitution(short, medium, long, module)


Instruction:
Can you tell what is the following Python 3 function doing
def add_modules(self, package):
        for name in os.listdir(package.__path__[0]):
            if name.startswith('_'):
                continue
            name = name.split('.')[0]
            short = '|%s|' % name
            long = ':mod:`~%s.%s`' % (package.__package__, name)
            self._short2long[short] = long

Response: Add the modules of the given package without their members.