Instruction:
Write a Python 3 function that can
get the bandwidth of an Opus packet.

Response:
def packet_get_bandwidth(data):
    """Gets the bandwidth of an Opus packet."""

    data_pointer = ctypes.c_char_p(data)

    result = _packet_get_bandwidth(data_pointer)
    if result < 0:
        raise OpusError(result)

    return result


Instruction:
Can you write a function in Python 3 where it
gets the number of channels from an Opus packet

Response:
def packet_get_nb_channels(data):
    """Gets the number of channels from an Opus packet"""

    data_pointer = ctypes.c_char_p(data)

    result = _packet_get_nb_channels(data_pointer)
    if result < 0:
        raise OpusError(result)

    return result


Instruction:
Write a Python 3 script to
get the number of frames in an Opus packet

Response:
def packet_get_nb_frames(data, length=None):
    """Gets the number of frames in an Opus packet"""

    data_pointer = ctypes.c_char_p(data)
    if length is None:
        length = len(data)

    result = _packet_get_nb_frames(data_pointer, ctypes.c_int(length))
    if result < 0:
        raise OpusError(result)

    return result


Instruction:
Make a summary of the following Python 3 code
def packet_get_samples_per_frame(data, fs):

    data_pointer = ctypes.c_char_p(data)

    result = _packet_get_nb_frames(data_pointer, ctypes.c_int(fs))
    if result < 0:
        raise OpusError(result)

    return result

Response: Gets the number of samples per frame from an Opus packet


Instruction:
Write a Python 3 script to
decode an Opus frame

Response:
def decode(decoder, data, length, frame_size, decode_fec, channels=2):
    """Decode an Opus frame

    Unlike the `opus_decode` function , this function takes an additional parameter `channels`,
    which indicates the number of channels in the frame
    """

    pcm_size = frame_size * channels * ctypes.sizeof(ctypes.c_int16)
    pcm = (ctypes.c_int16 * pcm_size)()
    pcm_pointer = ctypes.cast(pcm, c_int16_pointer)

    # Converting from a boolean to int
    decode_fec = int(bool(decode_fec))

    result = _decode(decoder, data, length, pcm_pointer, frame_size, decode_fec)
    if result < 0:
        raise OpusError(result)

    return array.array('h', pcm).tostring()


Instruction:
Write a Python 3 script to
parse a comma separated list of tag = value pairs from a string

Response:
def label_list_parser(self, url):
        """
        Extracts comma separate tag=value pairs from a string
        Assumes all characters other than / and , are valid
        """
        labels = re.findall('([^/,]+=[^/,]+)', url)
        slabels = set(labels)
        if '' in slabels:
            slabels.remove('')
        return slabels


Instruction:
Can you generate a brief explanation for the following Python 3 code
def init(app, register_blueprint=True, url_prefix='/fm', access_control_function=None,
         custom_config_json_path=None, custom_init_js_path=None):
    """
    :param app: The Flask app
    :param register_blueprint: Override to False to stop the blueprint from automatically being registered to the
                               app
    :param url_prefix: The URL prefix for the blueprint, defaults to /fm
    :param access_control_function: Pass in a function here to implement access control.  The function will
                                    be called any time someone tries to access the filemanager, and a 404
                                    will be returned if this function returns False
    :param custom_config_json_path: Set this to the full path of you filemanager.config.json file if you want
                                    to use a custom config. Example:
                                    os.path.join(app.root_path, 'static/filemanager.config.json')
    :param custom_init_js_path: Set this to the full path of you filemanager.init.js file if you want
                                to use a custom init.js. Example:
                                os.path.join(app.root_path, 'static/filemanager.init.js')
    """

    global _initialised, _FILE_PATH, _URL_PREFIX

    if _initialised:
        raise Exception('Flask Filemanager can only be registered once!')

    _initialised = True

    _FILE_PATH = app.config.get('FLASKFILEMANAGER_FILE_PATH')
    if not _FILE_PATH:
        raise Exception('No FLASKFILEMANAGER_FILE_PATH value in config')

    log.info('File Manager Using file path: {}'.format(_FILE_PATH))
    util.ensure_dir(_FILE_PATH)

    if access_control_function:
        set_access_control_function(access_control_function)

    if custom_config_json_path:
        set_custom_config_json_path(custom_config_json_path)
        log.info('File Manager using custom config.json path: {}'.format(custom_config_json_path))

    if custom_init_js_path:
        set_custom_init_js_path(custom_init_js_path)
        log.info('File Manager using custom init.js path: {}'.format(custom_init_js_path))

    if register_blueprint:
        log.info('Registering filemanager blueprint to {}'.format(url_prefix))
        app.register_blueprint(filemanager_blueprint, url_prefix=url_prefix)

Response:
:param app: The Flask app
    :param register_blueprint: Override to False to stop the blueprint from automatically being registered to the
                               app
    :param url_prefix: The URL prefix for the blueprint, defaults to /fm
    :param access_control_function: Pass in a function here to implement access control.  The function will
                                    be called any time someone tries to access the filemanager, and a 404
                                    will be returned if this function returns False
    :param custom_config_json_path: Set this to the full path of you filemanager.config.json file if you want
                                    to use a custom config. Example:
                                    os.path.join(app.root_path, 'static/filemanager.config.json')
    :param custom_init_js_path: Set this to the full path of you filemanager.init.js file if you want
                                to use a custom init.js. Example:
                                os.path.join(app.root_path, 'static/filemanager.init.js')


Instruction:
Can you write a function in Python 3 where it
gets file from path or content.

Response:
def get_file(path=None, content=None):
    """
    :param path: relative path, or None to get from request
    :param content: file content, output in data. Used for editfile
    """
    if path is None:
        path = request.args.get('path')

    if path is None:
        return error('No path in request')

    filename = os.path.split(path.rstrip('/'))[-1]
    extension = filename.rsplit('.', 1)[-1]
    os_file_path = web_path_to_os_path(path)

    if os.path.isdir(os_file_path):
        file_type = 'folder'
        # Ensure trailing slash
        if path[-1] != '/':
            path += '/'
    else:
        file_type = 'file'

    ctime = int(os.path.getctime(os_file_path))
    mtime = int(os.path.getmtime(os_file_path))

    height = 0
    width = 0
    if extension in ['gif', 'jpg', 'jpeg', 'png']:
        try:
            im = PIL.Image.open(os_file_path)
            height, width = im.size
        except OSError:
            log.exception('Error loading image "{}" to get width and height'.format(os_file_path))

    attributes = {
        'name': filename,
        'path': get_url_path(path),
        'readable': 1 if os.access(os_file_path, os.R_OK) else 0,
        'writeable': 1 if os.access(os_file_path, os.W_OK) else 0,
        'created': datetime.datetime.fromtimestamp(ctime).ctime(),
        'modified': datetime.datetime.fromtimestamp(mtime).ctime(),
        'timestamp': mtime,
        'width': width,
        'height': height,
        'size': os.path.getsize(os_file_path)
    }

    if content:
        attributes['content'] = content

    return {
        'id': path,
        'type': file_type,
        'attributes': attributes
    }


Instruction:
Here you have a function in Python 3, explain what it does
def __get_charset(self):
        '''Return the character encoding (charset) used internally by MeCab.

        Charset is that of the system dictionary used by MeCab. Will defer to
        the user-specified MECAB_CHARSET environment variable, if set.

        Defaults to shift-jis on Windows.
        Defaults to utf-8 on Mac OS.
        Defaults to euc-jp, as per MeCab documentation, when all else fails.

        Returns:
            Character encoding (charset) used by MeCab.
        '''
        cset = os.getenv(self.MECAB_CHARSET)
        if cset:
            logger.debug(self._DEBUG_CSET_DEFAULT.format(cset))
            return cset
        else:
            try:
                res = Popen(['mecab', '-D'], stdout=PIPE).communicate()
                lines = res[0].decode()
                if not lines.startswith('unrecognized'):
                    dicinfo = lines.split(os.linesep)
                    t = [t for t in dicinfo if t.startswith('charset')]
                    if len(t) > 0:
                        cset = t[0].split()[1].lower()
                        logger.debug(self._DEBUG_CSET_DEFAULT.format(cset))
                        return cset
                    else:
                        logger.error('{}\n'.format(self._ERROR_NODIC))
                        raise EnvironmentError(self._ERROR_NODIC)
                else:
                    logger.error('{}\n'.format(self._ERROR_NOCMD))
                    raise EnvironmentError(self._ERROR_NOCMD)
            except OSError:
                cset = 'euc-jp'
                if sys.platform == 'win32':
                    cset = 'shift-jis'
                elif sys.platform == 'darwin':
                    cset = 'utf8'
                logger.debug(self._DEBUG_CSET_DEFAULT.format(cset))
                return cset

Response: Returns the character encoding used internally by MeCab.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def __get_libpath(self):
        '''Return the absolute path to the MeCab library.

        On Windows, the path to the system dictionary is used to deduce the
        path to libmecab.dll.

        Otherwise, mecab-config is used find the libmecab shared object or
        dynamic library (*NIX or Mac OS, respectively).

        Will defer to the user-specified MECAB_PATH environment variable, if
        set.

        Returns:
            The absolute path to the MeCab library.

        Raises:
            EnvironmentError: A problem was encountered in trying to locate the
                MeCab library.
        '''
        libp = os.getenv(self.MECAB_PATH)
        if libp:
            return os.path.abspath(libp)
        else:
            plat = sys.platform
            if plat == 'win32':
                lib = self._LIBMECAB.format(self._WINLIB_EXT)

                try:
                    v = self.__regkey_value(self._WINHKEY, self._WINVALUE)
                    ldir = v.split('etc')[0]
                    libp = os.path.join(ldir, 'bin', lib)
                except EnvironmentError as err:
                    logger.error('{}\n'.format(err))
                    logger.error('{}\n'.format(sys.exc_info()[0]))
                    raise EnvironmentError(
                        self._ERROR_WINREG.format(self._WINVALUE,
                                                  self._WINHKEY))
            else:
                # UNIX-y OS?
                if plat == 'darwin':
                    lib = self._LIBMECAB.format(self._MACLIB_EXT)
                else:
                    lib = self._LIBMECAB.format(self._UNIXLIB_EXT)

                try:
                    cmd = ['mecab-config', '--libs-only-L']
                    res = Popen(cmd, stdout=PIPE).communicate()
                    lines = res[0].decode()
                    if not lines.startswith('unrecognized'):
                        linfo = lines.strip()
                        libp = os.path.join(linfo, lib)
                    else:
                        raise EnvironmentError(
                            self._ERROR_MECABCONFIG.format(lib))
                except EnvironmentError as err:
                    logger.error('{}\n'.format(err))
                    logger.error('{}\n'.format(sys.exc_info()[0]))
                    raise EnvironmentError(self._ERROR_NOLIB.format(lib))

            if libp and os.path.exists(libp):
                libp = os.path.abspath(libp)
                os.environ[self.MECAB_PATH] = libp
                return libp
            else:
                raise EnvironmentError(self._ERROR_NOLIB.format(libp))

Response: Return the absolute path to the MeCab library.


Instruction:
Here you have a function in Python 3, explain what it does
def __regkey_value(self, path, name='', start_key=None):
        r'''Return the data of value mecabrc at MeCab HKEY node.

        On Windows, the path to the mecabrc as set in the Windows Registry is
        used to deduce the path to libmecab.dll.

        Returns:
            The full path to the mecabrc on Windows.

        Raises:
            WindowsError: A problem was encountered in trying to locate the
                value mecabrc at HKEY_CURRENT_USER\Software\MeCab.
        '''
        if sys.version < '3':
            import _winreg as reg
        else:
            import winreg as reg

        def _fn(path, name='', start_key=None):
            if isinstance(path, str):
                path = path.split('\\')
            if start_key is None:
                start_key = getattr(reg, path[0])
                return _fn(path[1:], name, start_key)
            else:
                subkey = path.pop(0)
            with reg.OpenKey(start_key, subkey) as handle:
                if path:
                    return _fn(path, name, handle)
                else:
                    desc, i = None, 0
                    while not desc or desc[0] != name:
                        desc = reg.EnumValue(handle, i)
                        i += 1
                    return desc[1]
        return _fn(path, name, start_key)

Response: r Returns the data of value mecabrc at the given path at the given name on Windows


Instruction:
Make a summary of the following Python 3 code
def diff(old_html, new_html, cutoff=0.0, plaintext=False, pretty=False):
    if plaintext:
        old_dom = parse_text(old_html)
        new_dom = parse_text(new_html)
    else:
        old_dom = parse_minidom(old_html)
        new_dom = parse_minidom(new_html)

    # If the two documents are not similar enough, don't show the changes.
    if not check_text_similarity(old_dom, new_dom, cutoff):
        return '
The differences from the previous version are too large to show concisely.
'

    dom = dom_diff(old_dom, new_dom)

    # HTML-specific cleanup.
    if not plaintext:
        fix_lists(dom)
        fix_tables(dom)

    # Only return html for the document body contents.
    body_elements = dom.getElementsByTagName('body')
    if len(body_elements) == 1:
        dom = body_elements[0]

    return minidom_tostring(dom, pretty=pretty)

Response: Show the differences between two html documents as html.


Instruction:
How would you explain what the following Python 3 function does
def adjusted_ops(opcodes):
    while opcodes:
        op = opcodes.pop(0)
        tag, i1, i2, j1, j2 = op
        shift = 0
        if tag == 'equal':
            continue
        if tag == 'replace':
            # change the single replace op into a delete then insert
            # pay careful attention to the variables here, there's no typo
            opcodes = [
                ('delete', i1, i2, j1, j1),
                ('insert', i2, i2, j1, j2),
            ] + opcodes
            continue
        yield op
        if tag == 'delete':
            shift = -(i2 - i1)
        elif tag == 'insert':
            shift = +(j2 - j1)
        new_opcodes = []
        for tag, i1, i2, j1, j2 in opcodes:
            new_opcodes.append((
                tag,
                i1 + shift,
                i2 + shift,
                j1,
                j2,
            ))
        opcodes = new_opcodes

Response: Iterate through opcodes and yield all the adjusted operations.


Instruction:
How would you code a function in Python 3 to
yield index tuples for each place in the match.

Response:
def match_indices(match):
    """Yield index tuples (old_index, new_index) for each place in the match."""
    a, b, size = match
    for i in range(size):
        yield a + i, b + i


Instruction:
Can you implement a function in Python 3 that
uses difflib to get the opcodes for a set of matching blocks.

Response:
def get_opcodes(matching_blocks):
    """Use difflib to get the opcodes for a set of matching blocks."""
    sm = difflib.SequenceMatcher(a=[], b=[])
    sm.matching_blocks = matching_blocks
    return sm.get_opcodes()


Instruction:
How would you explain what the following Python 3 function does
def match_blocks(hash_func, old_children, new_children):
    sm = difflib.SequenceMatcher(
        _is_junk,
        a=[hash_func(c) for c in old_children],
        b=[hash_func(c) for c in new_children],
    )
    return sm

Response: Use difflib to find matching blocks.


Instruction:
Given the following Python 3 function, write the documentation
def get_nonmatching_blocks(matching_blocks):
    i = j = 0
    for match in matching_blocks:
        a, b, size = match
        yield (i, a, j, b)
        i = a + size
        j = b + size

Response: Given a list of matching blocks output the gaps between them.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def merge_blocks(a_blocks, b_blocks):
    # Check sentinels for sequence length.
    assert a_blocks[-1][2] == b_blocks[-1][2] == 0 # sentinel size is 0
    assert a_blocks[-1] == b_blocks[-1]
    combined_blocks = sorted(list(set(a_blocks + b_blocks)))
    # Check for overlaps.
    i = j = 0
    for a, b, size in combined_blocks:
        assert i <= a
        assert j <= b
        i = a + size
        j = b + size
    return combined_blocks

Response: Given two lists of blocks combine them in the proper order.


Instruction:
Can you create a Python 3 function that
removes comments from the xml string.

Response:
def remove_comments(xml):
    """
    Remove comments, as they can break the xml parser.

    See html5lib issue #122 ( http://code.google.com/p/html5lib/issues/detail?id=122 ).

    >>> remove_comments('')
    ''
    >>> remove_comments('')
    ''
    >>> remove_comments('
stuffstuff
')
    '
stuffstuff
'
    """
    regex = re.compile(r'', re.DOTALL)
    return regex.sub('', xml)


Instruction:
Write a Python 3 script to
remove text nodes that are not inside the dom.

Response:
def remove_insignificant_text_nodes(dom):
    """
    For html elements that should not have text nodes inside them, remove all
    whitespace. For elements that may have text, collapse multiple spaces to a
    single space.
    """
    nodes_to_remove = []
    for node in walk_dom(dom):
        if is_text(node):
            text = node.nodeValue
            if node.parentNode.tagName in _non_text_node_tags:
                nodes_to_remove.append(node)
            else:
                node.nodeValue = re.sub(r'\s+', ' ', text)
    for node in nodes_to_remove:
        remove_node(node)


Instruction:
Create a Python 3 function for
getting the child at the given index.

Response:
def get_child(parent, child_index):
    """
    Get the child at the given index, or return None if it doesn't exist.
    """
    if child_index < 0 or child_index >= len(parent.childNodes):
        return None
    return parent.childNodes[child_index]


Instruction:
Can you tell what is the following Python 3 function doing
def get_location(dom, location):
    node = dom.documentElement
    for i in location:
        node = get_child(node, i)
        if not node:
            raise ValueError('Node at location %s does not exist.' % location) #TODO: line not covered
    return node

Response: Get the node at the specified location in the specified dom.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def check_text_similarity(a_dom, b_dom, cutoff):
    a_words = list(tree_words(a_dom))
    b_words = list(tree_words(b_dom))

    sm = WordMatcher(a=a_words, b=b_words)
    if sm.text_ratio() >= cutoff:
        return True
    return False

Response: Check whether two dom trees have similar text or not.


Instruction:
Write a Python 3 script for
returning all the significant text below the given node as a list of words.

Response:
def tree_words(node):
    """Return all the significant text below the given node as a list of words.
    >>> list(tree_words(parse_minidom('
one
 two
threefour
')))
    ['one', 'two', 'three', 'four']
    """
    for word in split_text(tree_text(node)):
        word = word.strip()
        if word:
            yield word


Instruction:
Explain what the following Python 3 code does
def tree_text(node):
    text = []
    for descendant in walk_dom(node):
        if is_text(descendant):
            text.append(descendant.nodeValue)
    return ' '.join(text)

Response: Return the text of a node in a tree.


Instruction:
Can you implement a function in Python 3 that
inserts the node before next_sibling.

Response:
def insert_or_append(parent, node, next_sibling):
    """
    Insert the node before next_sibling. If next_sibling is None, append the node last instead.
    """
    # simple insert
    if next_sibling:
        parent.insertBefore(node, next_sibling)
    else:
        parent.appendChild(node)


Instruction:
Can you tell what is the following Python 3 function doing
def wrap(node, tag):
    wrap_node = node.ownerDocument.createElement(tag)
    parent = node.parentNode
    if parent:
        parent.replaceChild(wrap_node, node)
    wrap_node.appendChild(node)
    return wrap_node

Response: Wrap the given tag around a node.


Instruction:
How would you implement a function in Python 3 that
wraps the given tag around the contents of a node.

Response:
def wrap_inner(node, tag):
    """Wrap the given tag around the contents of a node."""
    children = list(node.childNodes)
    wrap_node = node.ownerDocument.createElement(tag)
    for c in children:
        wrap_node.appendChild(c)
    node.appendChild(wrap_node)


Instruction:
Explain what the following Python 3 code does
def unwrap(node):
    for child in list(node.childNodes):
        node.parentNode.insertBefore(child, node)
    remove_node(node)

Response: Removes a node replacing it with its children.


Instruction:
How would you code a function in Python 3 to
split the text by the regex and keep all parts.

Response:
def full_split(text, regex):
    """
    Split the text by the regex, keeping all parts.
    The parts should re-join back into the original text.

    >>> list(full_split('word', re.compile('&.*?')))
    ['word']
    """
    while text:
        m = regex.search(text)
        if not m:
            yield text
            break
        left = text[:m.start()]
        middle = text[m.start():m.end()]
        right = text[m.end():]
        if left:
            yield left
        if middle:
            yield middle
        text = right


Instruction:
Can you implement a function in Python 3 that
splits the given text into pieces by the given regexes.

Response:
def multi_split(text, regexes):
    """
    Split the text by the given regexes, in priority order.

    Make sure that the regex is parenthesized so that matches are returned in
    re.split().

    Splitting on a single regex works like normal split.
    >>> '|'.join(multi_split('one two three', [r'\w+']))
    'one| |two| |three'

    Splitting on digits first separates the digits from their word
    >>> '|'.join(multi_split('one234five 678', [r'\d+', r'\w+']))
    'one|234|five| |678'

    Splitting on words first keeps the word with digits intact.
    >>> '|'.join(multi_split('one234five 678', [r'\w+', r'\d+']))
    'one234five| |678'
    """
    def make_regex(s):
        return re.compile(s) if isinstance(s, basestring) else s
    regexes = [make_regex(r) for r in regexes]

    # Run the list of pieces through the regex split, splitting it into more
    # pieces. Once a piece has been matched, add it to finished_pieces and
    # don't split it again. The pieces should always join back together to form
    # the original text.
    piece_list = [text]
    finished_pieces = set()
    def apply_re(regex, piece_list):
        for piece in piece_list:
            if piece in finished_pieces:
                yield piece
                continue
            for s in full_split(piece, regex):
                if regex.match(s):
                    finished_pieces.add(s)
                if s:
                    yield s

    for regex in regexes:
        piece_list = list(apply_re(regex, piece_list))
        assert ''.join(piece_list) == text
    return piece_list


Instruction:
Can you generate a brief explanation for the following Python 3 code
def text_ratio(self):
        return _calculate_ratio(
            self.match_length(),
            self._text_length(self.a) + self._text_length(self.b),
        )

Response: Return a measure of the sequences s word similarity.


Instruction:
How would you explain what the following Python 3 function does
def match_length(self):
        length = 0
        for match in self.get_matching_blocks():
            a, b, size = match
            length += self._text_length(self.a[a:a+size])
        return length

Response: Find the total length of all words that match between the two sequences.


Instruction:
Create a Python 3 function to
run an xml edit script and return the new html produced.

Response:
def run_edit_script(self):
        """
        Run an xml edit script, and return the new html produced.
        """
        for action, location, properties in self.edit_script:
            if action == 'delete':
                node = get_location(self.dom, location)
                self.action_delete(node)
            elif action == 'insert':
                parent = get_location(self.dom, location[:-1])
                child_index = location[-1]
                self.action_insert(parent, child_index, **properties)
        return self.dom


Instruction:
Make a summary of the following Python 3 code
def add_changes_markup(dom, ins_nodes, del_nodes):
    # add markup for inserted and deleted sections
    for node in reversed(del_nodes):
        # diff algorithm deletes nodes in reverse order, so un-reverse the
        # order for this iteration
        insert_or_append(node.orig_parent, node, node.orig_next_sibling)
        wrap(node, 'del')
    for node in ins_nodes:
        wrap(node, 'ins')
    # Perform post-processing and cleanup.
    remove_nesting(dom, 'del')
    remove_nesting(dom, 'ins')
    sort_del_before_ins(dom)
    merge_adjacent(dom, 'del')
    merge_adjacent(dom, 'ins')

Response: Add markup for inserted and deleted sections to the dom to show changes.


Instruction:
Explain what the following Python 3 code does
def remove_nesting(dom, tag_name):
    for node in dom.getElementsByTagName(tag_name):
        for ancestor in ancestors(node):
            if ancestor is node:
                continue
            if ancestor is dom.documentElement:
                break
            if ancestor.tagName == tag_name:
                unwrap(node)
                break

Response: Unwrap items in the node list that have no ancestors with the same tag.


Instruction:
How would you code a function in Python 3 to
sort the nodes of the dom in - place based on a comparison function.

Response:
def sort_nodes(dom, cmp_func):
    """
    Sort the nodes of the dom in-place, based on a comparison function.
    """
    dom.normalize()
    for node in list(walk_dom(dom, elements_only=True)):
        prev_sib = node.previousSibling
        while prev_sib and cmp_func(prev_sib, node) == 1:
            node.parentNode.insertBefore(node, prev_sib)
            prev_sib = node.previousSibling


Instruction:
How would you implement a function in Python 3 that
merges all adjacent tags with the specified tag name.

Response:
def merge_adjacent(dom, tag_name):
    """
    Merge all adjacent tags with the specified tag name.
    Return the number of merges performed.
    """
    for node in dom.getElementsByTagName(tag_name):
        prev_sib = node.previousSibling
        if prev_sib and prev_sib.nodeName == node.tagName:
            for child in list(node.childNodes):
                prev_sib.appendChild(child)
            remove_node(node)


Instruction:
Can you implement a function in Python 3 that
distributes the given element to its children.

Response:
def distribute(node):
    """
    Wrap a copy of the given element around the contents of each of its
    children, removing the node in the process.
    """
    children = list(c for c in node.childNodes if is_element(c))
    unwrap(node)
    tag_name = node.tagName
    for c in children:
        wrap_inner(c, tag_name)


Instruction:
Explain what the following Python 3 code does
def save(self, *args, **kwargs):
        self.__class__.objects.exclude(id=self.id).delete()
        super(SingletonModel, self).save(*args, **kwargs)

Response: Save the object to the database.


Instruction:
Write a Python 3 script for
getting the mappings from MAGICC to OpenSCM regions.

Response:
def get_magicc_region_to_openscm_region_mapping(inverse=False):
    """Get the mappings from MAGICC to OpenSCM regions.

    This is not a pure inverse of the other way around. For example, we never provide
    "GLOBAL" as a MAGICC return value because it's unnecesarily confusing when we also
    have "World". Fortunately MAGICC doesn't ever read the name "GLOBAL" so this
    shouldn't matter.

    Parameters
    ----------
    inverse : bool
        If True, return the inverse mappings i.e. MAGICC to OpenSCM mappings
    Returns
    -------
    dict
        Dictionary of mappings
    """

    def get_openscm_replacement(in_region):
        world = "World"
        if in_region in ("WORLD", "GLOBAL"):
            return world
        if in_region in ("BUNKERS"):
            return DATA_HIERARCHY_SEPARATOR.join([world, "Bunkers"])
        elif in_region.startswith(("NH", "SH")):
            in_region = in_region.replace("-", "")
            hem = "Northern Hemisphere" if "NH" in in_region else "Southern Hemisphere"
            if in_region in ("NH", "SH"):
                return DATA_HIERARCHY_SEPARATOR.join([world, hem])

            land_ocean = "Land" if "LAND" in in_region else "Ocean"
            return DATA_HIERARCHY_SEPARATOR.join([world, hem, land_ocean])
        else:
            return DATA_HIERARCHY_SEPARATOR.join([world, in_region])

    # we generate the mapping dynamically, the first name in the list
    # is the one which will be used for inverse mappings
    _magicc_regions = [
        "WORLD",
        "GLOBAL",
        "OECD90",
        "ALM",
        "REF",
        "ASIA",
        "R5ASIA",
        "R5OECD",
        "R5REF",
        "R5MAF",
        "R5LAM",
        "R6OECD90",
        "R6REF",
        "R6LAM",
        "R6MAF",
        "R6ASIA",
        "NHOCEAN",
        "SHOCEAN",
        "NHLAND",
        "SHLAND",
        "NH-OCEAN",
        "SH-OCEAN",
        "NH-LAND",
        "SH-LAND",
        "SH",
        "NH",
        "BUNKERS",
    ]

    replacements = {}
    for magicc_region in _magicc_regions:
        openscm_region = get_openscm_replacement(magicc_region)
        # i.e. if we've already got a value for the inverse, we don't want to overwrite
        if (openscm_region in replacements.values()) and inverse:
            continue
        replacements[magicc_region] = openscm_region

    if inverse:
        return {v: k for k, v in replacements.items()}
    else:
        return replacements


Instruction:
Implement a function in Python 3 to
convert MAGICC regions to OpenSCM regions

Response:
def convert_magicc_to_openscm_regions(regions, inverse=False):
    """
    Convert MAGICC regions to OpenSCM regions

    Parameters
    ----------
    regions : list_like, str
        Regions to convert

    inverse : bool
        If True, convert the other way i.e. convert OpenSCM regions to MAGICC7
        regions

    Returns
    -------
    ``type(regions)``
        Set of converted regions
    """
    if isinstance(regions, (list, pd.Index)):
        return [_apply_convert_magicc_to_openscm_regions(r, inverse) for r in regions]
    else:
        return _apply_convert_magicc_to_openscm_regions(regions, inverse)


Instruction:
How would you explain what the following Python 3 function does
def get_magicc7_to_openscm_variable_mapping(inverse=False):

    def get_openscm_replacement(in_var):
        if in_var.endswith("_INVERSE_EMIS"):
            prefix = "Inverse Emissions"
        elif in_var.endswith("_EMIS"):
            prefix = "Emissions"
        elif in_var.endswith("_CONC"):
            prefix = "Atmospheric Concentrations"
        elif in_var.endswith("_RF"):
            prefix = "Radiative Forcing"
        elif in_var.endswith("_OT"):
            prefix = "Optical Thickness"
        else:
            raise ValueError("This shouldn't happen")

        variable = in_var.split("_")[0]
        # I hate edge cases
        if variable.endswith("EQ"):
            variable = variable.replace("EQ", " Equivalent")

        if "GHG" in variable:
            variable = variable.replace("GHG", "Greenhouse Gases")

        if "BIOMASSAER" in variable:
            variable = variable.replace("BIOMASSAER", "Aerosols|MAGICC AFOLU")

        if "CO2CH4N2O" in variable:
            variable = variable.replace("CO2CH4N2O", "CO2, CH4 and N2O")

        aggregate_indicators = {
            "KYOTO": "Kyoto Gases",
            "FGASSUM": "F Gases",
            "MHALOSUM": "Montreal Protocol Halogen Gases",
        }
        for agg_indicator, long_name in aggregate_indicators.items():
            if variable.startswith(agg_indicator):
                stripped_var = variable.replace(agg_indicator, "")
                if stripped_var:
                    variable = DATA_HIERARCHY_SEPARATOR.join([stripped_var, long_name])
                else:
                    variable = long_name

        edge_case_B = variable.upper() in ("HCFC141B", "HCFC142B")
        if variable.endswith("I"):
            variable = DATA_HIERARCHY_SEPARATOR.join(
                [variable[:-1], "MAGICC Fossil and Industrial"]
            )
        elif variable.endswith("B") and not edge_case_B:
            variable = DATA_HIERARCHY_SEPARATOR.join([variable[:-1], "MAGICC AFOLU"])

        case_adjustments = {
            "SOX": "SOx",
            "NOX": "NOx",
            "HFC134A": "HFC134a",
            "HFC143A": "HFC143a",
            "HFC152A": "HFC152a",
            "HFC227EA": "HFC227ea",
            "HFC236FA": "HFC236fa",
            "HFC245FA": "HFC245fa",
            "HFC365MFC": "HFC365mfc",
            "HCFC141B": "HCFC141b",
            "HCFC142B": "HCFC142b",
            "CH3CCL3": "CH3CCl3",
            "CCL4": "CCl4",
            "CH3CL": "CH3Cl",
            "CH2CL2": "CH2Cl2",
            "CHCL3": "CHCl3",
            "CH3BR": "CH3Br",
            "HALON1211": "Halon1211",
            "HALON1301": "Halon1301",
            "HALON2402": "Halon2402",
            "HALON1202": "Halon1202",
            "SOLAR": "Solar",
            "VOLCANIC": "Volcanic",
            "EXTRA": "Extra",
        }
        variable = apply_string_substitutions(variable, case_adjustments)

        return DATA_HIERARCHY_SEPARATOR.join([prefix, variable])

    magicc7_suffixes = ["_EMIS", "_CONC", "_RF", "_OT", "_INVERSE_EMIS"]
    magicc7_base_vars = MAGICC7_EMISSIONS_UNITS.magicc_variable.tolist() + [
        "SOLAR",
        "VOLCANIC",
        "CO2EQ",
        "KYOTOCO2EQ",
        "FGASSUMHFC134AEQ",
        "MHALOSUMCFC12EQ",
        "GHG",
        "KYOTOGHG",
        "FGASSUM",
        "MHALOSUM",
        "BIOMASSAER",
        "CO2CH4N2O",
        "EXTRA",
    ]
    magicc7_vars = [
        base_var + suffix
        for base_var in magicc7_base_vars
        for suffix in magicc7_suffixes
    ]

    replacements = {m7v: get_openscm_replacement(m7v) for m7v in magicc7_vars}

    replacements.update(
        {
            "SURFACE_TEMP": "Surface Temperature",
            "TOTAL_INCLVOLCANIC_RF": "Radiative Forcing",
            "VOLCANIC_ANNUAL_RF": "Radiative Forcing|Volcanic",
            "TOTAL_ANTHRO_RF": "Radiative Forcing|Anthropogenic",
            "TOTAER_DIR_RF": "Radiative Forcing|Aerosols|Direct Effect",
            "CLOUD_TOT_RF": "Radiative Forcing|Aerosols|Indirect Effect",
            "MINERALDUST_RF": "Radiative Forcing|Mineral Dust",
            "STRATOZ_RF": "Radiative Forcing|Stratospheric Ozone",
            "TROPOZ_RF": "Radiative Forcing|Tropospheric Ozone",
            "CH4OXSTRATH2O_RF": "Radiative Forcing|CH4 Oxidation Stratospheric H2O",  # what is this
            "LANDUSE_RF": "Radiative Forcing|Land-use Change",
            "BCSNOW_RF": "Radiative Forcing|Black Carbon on Snow",
            "CO2PF_EMIS": "Land to Air Flux|CO2|MAGICC Permafrost",
            # "CH4PF_EMIS": "Land to Air Flux|CH4|MAGICC Permafrost",  # TODO: test and then add when needed
        }
    )

    agg_ocean_heat_top = "Aggregated Ocean Heat Content"
    heat_content_aggreg_depths = {
        "HEATCONTENT_AGGREG_DEPTH{}".format(i): "{}{}Depth {}".format(
            agg_ocean_heat_top, DATA_HIERARCHY_SEPARATOR, i
        )
        for i in range(1, 4)
    }
    replacements.update(heat_content_aggreg_depths)
    replacements.update({"HEATCONTENT_AGGREG_TOTAL": agg_ocean_heat_top})

    ocean_temp_layer = {
        "OCEAN_TEMP_LAYER_{0:03d}".format(i): "Ocean Temperature{}Layer {}".format(
            DATA_HIERARCHY_SEPARATOR, i
        )
        for i in range(1, 999)
    }
    replacements.update(ocean_temp_layer)

    if inverse:
        return {v: k for k, v in replacements.items()}
    else:
        return replacements

Response: Get the mappings from MAGICC7 to OpenSCM variables.


Instruction:
Make a summary of the following Python 3 code
def convert_magicc7_to_openscm_variables(variables, inverse=False):
    if isinstance(variables, (list, pd.Index)):
        return [
            _apply_convert_magicc7_to_openscm_variables(v, inverse) for v in variables
        ]
    else:
        return _apply_convert_magicc7_to_openscm_variables(variables, inverse)

Response: Convert MAGICC7 variables to OpenSCM variables.


Instruction:
Can you generate the documentation for the following Python 3 function
def get_magicc6_to_magicc7_variable_mapping(inverse=False):
    # we generate the mapping dynamically, the first name in the list
    # is the one which will be used for inverse mappings
    magicc6_simple_mapping_vars = [
        "KYOTO-CO2EQ",
        "CO2I",
        "CO2B",
        "CH4",
        "N2O",
        "BC",
        "OC",
        "SOx",
        "NOx",
        "NMVOC",
        "CO",
        "SF6",
        "NH3",
        "CF4",
        "C2F6",
        "HFC4310",
        "HFC43-10",
        "HFC-43-10",
        "HFC4310",
        "HFC134a",
        "HFC143a",
        "HFC227ea",
        "CCl4",
        "CH3CCl3",
        "HFC245fa",
        "Halon 1211",
        "Halon 1202",
        "Halon 1301",
        "Halon 2402",
        "Halon1211",
        "Halon1202",
        "Halon1301",
        "Halon2402",
        "CH3Br",
        "CH3Cl",
        "C6F14",
    ]

    magicc6_sometimes_hyphen_vars = [
        "CFC-11",
        "CFC-12",
        "CFC-113",
        "CFC-114",
        "CFC-115",
        "HCFC-22",
        "HFC-23",
        "HFC-32",
        "HFC-125",
        "HFC-134a",
        "HFC-143a",
        "HCFC-141b",
        "HCFC-142b",
        "HFC-227ea",
        "HFC-245fa",
    ]
    magicc6_sometimes_hyphen_vars = [
        v.replace("-", "") for v in magicc6_sometimes_hyphen_vars
    ] + magicc6_sometimes_hyphen_vars

    magicc6_sometimes_underscore_vars = [
        "HFC43_10",
        "CFC_11",
        "CFC_12",
        "CFC_113",
        "CFC_114",
        "CFC_115",
        "HCFC_22",
        "HCFC_141b",
        "HCFC_142b",
    ]
    magicc6_sometimes_underscore_replacements = {
        v: v.replace("_", "") for v in magicc6_sometimes_underscore_vars
    }

    special_case_replacements = {
        "FossilCO2": "CO2I",
        "OtherCO2": "CO2B",
        "MCF": "CH3CCL3",
        "CARB_TET": "CCL4",
        "MHALOSUMCFC12EQ": "MHALOSUMCFC12EQ",  # special case to avoid confusion with MCF
    }

    one_way_replacements = {"HFC-245ca": "HFC245FA", "HFC245ca": "HFC245FA"}

    all_possible_magicc6_vars = (
        magicc6_simple_mapping_vars
        + magicc6_sometimes_hyphen_vars
        + magicc6_sometimes_underscore_vars
        + list(special_case_replacements.keys())
        + list(one_way_replacements.keys())
    )
    replacements = {}
    for m6v in all_possible_magicc6_vars:
        if m6v in special_case_replacements:
            replacements[m6v] = special_case_replacements[m6v]
        elif (
            m6v in magicc6_sometimes_underscore_vars and not inverse
        ):  # underscores one way
            replacements[m6v] = magicc6_sometimes_underscore_replacements[m6v]
        elif (m6v in one_way_replacements) and not inverse:
            replacements[m6v] = one_way_replacements[m6v]
        else:
            m7v = m6v.replace("-", "").replace(" ", "").upper()
            # i.e. if we've already got a value for the inverse, we don't
            # want to overwrite it
            if (m7v in replacements.values()) and inverse:
                continue
            replacements[m6v] = m7v

    if inverse:
        return {v: k for k, v in replacements.items()}
    else:
        return replacements

Response: Get the mappings from MAGICC6 to MAGICC7 variables.


Instruction:
Can you generate the documentation for the following Python 3 function
def convert_magicc6_to_magicc7_variables(variables, inverse=False):
    if isinstance(variables, (list, pd.Index)):
        return [
            _apply_convert_magicc6_to_magicc7_variables(v, inverse) for v in variables
        ]
    else:
        return _apply_convert_magicc6_to_magicc7_variables(variables, inverse)

Response: Convert MAGICC6 variables to MAGICC7 variables.


Instruction:
Implement a Python 3 function for
returning a dictionary mapping from Pint to Fortran safe units.

Response:
def get_pint_to_fortran_safe_units_mapping(inverse=False):
    """Get the mappings from Pint to Fortran safe units.

    Fortran can't handle special characters like "^" or "/" in names, but we need
    these in Pint. Conversely, Pint stores variables with spaces by default e.g. "Mt
    CO2 / yr" but we don't want these in the input files as Fortran is likely to think
    the whitespace is a delimiter.

    Parameters
    ----------
    inverse : bool
        If True, return the inverse mappings i.e. Fortran safe to Pint mappings

    Returns
    -------
    dict
        Dictionary of mappings
    """
    replacements = {"^": "super", "/": "per", " ": ""}
    if inverse:
        replacements = {v: k for k, v in replacements.items()}
        # mapping nothing to something is obviously not going to work in the inverse
        # hence remove
        replacements.pop("")

    return replacements


Instruction:
Can you implement a function in Python 3 that
converts Pint units to Fortran safe units.

Response:
def convert_pint_to_fortran_safe_units(units, inverse=False):
    """
    Convert Pint units to Fortran safe units

    Parameters
    ----------
    units : list_like, str
        Units to convert

    inverse : bool
        If True, convert the other way i.e. convert Fortran safe units to Pint units

    Returns
    -------
    ``type(units)``
        Set of converted units
    """
    if inverse:
        return apply_string_substitutions(units, FORTRAN_SAFE_TO_PINT_UNITS_MAPPING)
    else:
        return apply_string_substitutions(units, PINT_TO_FORTRAN_SAFE_UNITS_MAPPING)


Instruction:
Can you tell what is the following Python 3 function doing
def run_evaluate(self) -> None:
        result = None
        self.eval_error = False
        if self._needs_evaluation:
            result = self._schema.value.evaluate(self._evaluation_context)

        self.eval_error = result is None
        if self.eval_error:
            return

        # Only set the value if it conforms to the field type
        if not self._schema.is_type_of(result):
            try:
                result = self._schema.type_object(result)
            except Exception as err:
                logging.debug('{} in casting {} to {} for field {}. Error: {}'.format(
                    type(err).__name__, result, self._schema.type,
                    self._schema.fully_qualified_name, err))
                self.eval_error = True
                return

        try:
            result = self._schema.sanitize_object(result)
        except Exception as err:
            logging.debug('{} in sanitizing {} of type {} for field {}. Error: {}'.format(
                type(err).__name__, result, self._schema.type, self._schema.fully_qualified_name,
                err))
            self.eval_error = True
            return

        self.value = result

Response: Runs the base evaluation of the value and the schema.


Instruction:
How would you explain what the following Python 3 function does
def set(self, key: Any, value: Any) -> None:
        if key is not None:
            self[key] = value

Response: Sets the value of a key to a supplied value.


Instruction:
Make a summary of the following Python 3 code
def increment(self, key: Any, by: int = 1) -> None:
        if key is not None:
            self[key] = self.get(key, 0) + by

Response: Increments the value of a key.


Instruction:
Explain what the following Python 3 code does
def insert(self, index: int, obj: Any) -> None:
        if obj is not None:
            super().insert(index, obj)

Response: Inserts an item into the list as long as it is not None.


Instruction:
Write a Python 3 script to
get the THISFILE_DATTYPE and THISFILE_REGIONMODE flags for a given list of regions.

Response:
def get_dattype_regionmode(regions, scen7=False):
    """
    Get the THISFILE_DATTYPE and THISFILE_REGIONMODE flags for a given region set.

    In all MAGICC input files, there are two flags: THISFILE_DATTYPE and
    THISFILE_REGIONMODE. These tell MAGICC how to read in a given input file. This
    function maps the regions which are in a given file to the value of these flags
    expected by MAGICC.

    Parameters
    ----------
    regions : list_like
        The regions to get THISFILE_DATTYPE and THISFILE_REGIONMODE flags for.

    scen7 : bool, optional
        Whether the file we are getting the flags for is a SCEN7 file or not.

    Returns
    -------
    dict
        Dictionary where the flags are the keys and the values are the value they
        should be set to for the given inputs.
    """
    dattype_flag = "THISFILE_DATTYPE"
    regionmode_flag = "THISFILE_REGIONMODE"
    region_dattype_row = _get_dattype_regionmode_regions_row(regions, scen7=scen7)

    dattype = DATTYPE_REGIONMODE_REGIONS[dattype_flag.lower()][region_dattype_row].iloc[
        0
    ]
    regionmode = DATTYPE_REGIONMODE_REGIONS[regionmode_flag.lower()][
        region_dattype_row
    ].iloc[0]

    return {dattype_flag: dattype, regionmode_flag: regionmode}


Instruction:
Can you create a Python 3 function that
gets the region order expected by MAGICC.

Response:
def get_region_order(regions, scen7=False):
    """
    Get the region order expected by MAGICC.

    Parameters
    ----------
    regions : list_like
        The regions to get THISFILE_DATTYPE and THISFILE_REGIONMODE flags for.

    scen7 : bool, optional
        Whether the file we are getting the flags for is a SCEN7 file or not.

    Returns
    -------
    list
        Region order expected by MAGICC for the given region set.
    """
    region_dattype_row = _get_dattype_regionmode_regions_row(regions, scen7=scen7)
    region_order = DATTYPE_REGIONMODE_REGIONS["regions"][region_dattype_row].iloc[0]

    return region_order


Instruction:
Can you generate the documentation for the following Python 3 function
def get_special_scen_code(regions, emissions):
    if sorted(set(PART_OF_SCENFILE_WITH_EMISSIONS_CODE_0)) == sorted(set(emissions)):
        scenfile_emissions_code = 0
    elif sorted(set(PART_OF_SCENFILE_WITH_EMISSIONS_CODE_1)) == sorted(set(emissions)):
        scenfile_emissions_code = 1
    else:
        msg = "Could not determine scen special code for emissions {}".format(emissions)
        raise ValueError(msg)

    if set(regions) == set(["WORLD"]):
        scenfile_region_code = 1
    elif set(regions) == set(["WORLD", "OECD90", "REF", "ASIA", "ALM"]):
        scenfile_region_code = 2
    elif set(regions) == set(["WORLD", "R5OECD", "R5REF", "R5ASIA", "R5MAF", "R5LAM"]):
        scenfile_region_code = 3
    elif set(regions) == set(
        ["WORLD", "R5OECD", "R5REF", "R5ASIA", "R5MAF", "R5LAM", "BUNKERS"]
    ):
        scenfile_region_code = 4
    try:
        return scenfile_region_code * 10 + scenfile_emissions_code
    except NameError:
        msg = "Could not determine scen special code for regions {}".format(regions)
        raise ValueError(msg)

Response: Get the special code for the given set of regions and emissions.


Instruction:
Explain what the following Python 3 code does
def determine_tool(filepath, tool_to_get):
    file_regexp_reader_writer = {
        "SCEN": {"regexp": r"^.*\.SCEN$", "reader": _ScenReader, "writer": _ScenWriter},
        "SCEN7": {
            "regexp": r"^.*\.SCEN7$",
            "reader": _Scen7Reader,
            "writer": _Scen7Writer,
        },
        "prn": {"regexp": r"^.*\.prn$", "reader": _PrnReader, "writer": _PrnWriter},
        # "Sector": {"regexp": r".*\.SECTOR$", "reader": _Scen7Reader, "writer": _Scen7Writer},
        "EmisIn": {
            "regexp": r"^.*\_EMIS.*\.IN$",
            "reader": _HistEmisInReader,
            "writer": _HistEmisInWriter,
        },
        "ConcIn": {
            "regexp": r"^.*\_CONC.*\.IN$",
            "reader": _ConcInReader,
            "writer": _ConcInWriter,
        },
        "OpticalThicknessIn": {
            "regexp": r"^.*\_OT\.IN$",
            "reader": _OpticalThicknessInReader,
            "writer": _OpticalThicknessInWriter,
        },
        "RadiativeForcingIn": {
            "regexp": r"^.*\_RF\.(IN|MON)$",
            "reader": _RadiativeForcingInReader,
            "writer": _RadiativeForcingInWriter,
        },
        "SurfaceTemperatureIn": {
            "regexp": r"^.*SURFACE\_TEMP\.(IN|MON)$",
            "reader": _SurfaceTemperatureInReader,
            "writer": _SurfaceTemperatureInWriter,
        },
        "Out": {
            "regexp": r"^DAT\_.*(?<!EMIS)\.OUT$",
            "reader": _OutReader,
            "writer": None,
        },
        "EmisOut": {
            "regexp": r"^DAT\_.*EMIS\.OUT$",
            "reader": _EmisOutReader,
            "writer": None,
        },
        "InverseEmis": {
            "regexp": r"^INVERSEEMIS\.OUT$",
            "reader": _InverseEmisReader,
            "writer": None,
        },
        "TempOceanLayersOut": {
            "regexp": r"^TEMP\_OCEANLAYERS.*\.OUT$",
            "reader": _TempOceanLayersOutReader,
            "writer": None,
        },
        "BinOut": {
            "regexp": r"^DAT\_.*\.BINOUT$",
            "reader": _BinaryOutReader,
            "writer": None,
        },
        "RCPData": {"regexp": r"^.*\.DAT", "reader": _RCPDatReader, "writer": None}
        # "InverseEmisOut": {"regexp": r"^INVERSEEMIS\_.*\.OUT$", "reader": _Scen7Reader, "writer": _Scen7Writer},
    }

    fbase = basename(filepath)
    if _unsupported_file(fbase):
        raise NoReaderWriterError(
            "{} is in an odd format for which we will never provide a reader/writer.".format(
                filepath
            )
        )

    for file_type, file_tools in file_regexp_reader_writer.items():
        if re.match(file_tools["regexp"], fbase):
            try:
                return file_tools[tool_to_get]
            except KeyError:
                valid_tools = [k for k in file_tools.keys() if k != "regexp"]
                error_msg = (
                    "MAGICCData does not know how to get a {}, "
                    "valid options are: {}".format(tool_to_get, valid_tools)
                )
                raise KeyError(error_msg)

    para_file = "PARAMETERS.OUT"
    if (filepath.endswith(".CFG")) and (tool_to_get == "reader"):
        error_msg = (
            "MAGCCInput cannot read .CFG files like {}, please use "
            "pymagicc.io.read_cfg_file".format(filepath)
        )

    elif (filepath.endswith(para_file)) and (tool_to_get == "reader"):
        error_msg = (
            "MAGCCInput cannot read PARAMETERS.OUT as it is a config "
            "style file, please use pymagicc.io.read_cfg_file"
        )

    else:
        regexp_list_str = "\n".join(
            [
                "{}: {}".format(k, v["regexp"])
                for k, v in file_regexp_reader_writer.items()
            ]
        )
        error_msg = (
            "Couldn't find appropriate {} for {}.\nThe file must be one "
            "of the following types and the filepath must match its "
            "corresponding regular "
            "expression:\n{}".format(tool_to_get, fbase, regexp_list_str)
        )

    raise NoReaderWriterError(error_msg)

Response: This function determines the tool to use for reading or writing.


Instruction:
How would you implement a function in Python 3 that
pulls out a single config set from a parameters_out namelist. This function returns a single file with the config that needs to be passed to MAGICC in order to do the same run as is represented by the values in ``parameters_out``. Parameters ---------- parameters_out : dict, f90nml.Namelist The parameters to dump namelist_to_read : str The namelist to read from the file. Returns ------- :obj:`f90nml.Namelist` An f90nml object with the cleaned, read out config. Examples -------- >>> cfg = pull_cfg_from_parameters_out(magicc.metadata["parameters"]) >>> cfg.write("/somewhere/else/ANOTHERNAME.cfg")

Response:
def pull_cfg_from_parameters_out(parameters_out, namelist_to_read="nml_allcfgs"):
    """Pull out a single config set from a parameters_out namelist.

    This function returns a single file with the config that needs to be passed to
    MAGICC in order to do the same run as is represented by the values in
    ``parameters_out``.

    Parameters
    ----------
    parameters_out : dict, f90nml.Namelist
        The parameters to dump

    namelist_to_read : str
        The namelist to read from the file.

    Returns
    -------
    :obj:`f90nml.Namelist`
        An f90nml object with the cleaned, read out config.

    Examples
    --------
    >>> cfg = pull_cfg_from_parameters_out(magicc.metadata["parameters"])
    >>> cfg.write("/somewhere/else/ANOTHERNAME.cfg")
    """
    single_cfg = Namelist({namelist_to_read: {}})
    for key, value in parameters_out[namelist_to_read].items():
        if "file_tuning" in key:
            single_cfg[namelist_to_read][key] = ""
        else:
            try:
                if isinstance(value, str):
                    single_cfg[namelist_to_read][key] = value.strip(" \t\n\r").replace(
                        "\x00", ""
                    )
                elif isinstance(value, list):
                    clean_list = [v.strip(" \t\n\r").replace("\x00", "") for v in value]
                    single_cfg[namelist_to_read][key] = [v for v in clean_list if v]
                else:
                    assert isinstance(value, Number)
                    single_cfg[namelist_to_read][key] = value
            except AttributeError:
                if isinstance(value, list):
                    assert all([isinstance(v, Number) for v in value])
                    single_cfg[namelist_to_read][key] = value
                else:
                    raise AssertionError(
                        "Unexpected cause in out parameters conversion"
                    )

    return single_cfg


Instruction:
Implement a Python 3 function for
pulling out a single config set from a MAGICC PARAMETERS. OUT file.

Response:
def pull_cfg_from_parameters_out_file(
    parameters_out_file, namelist_to_read="nml_allcfgs"
):
    """Pull out a single config set from a MAGICC ``PARAMETERS.OUT`` file.

    This function reads in the ``PARAMETERS.OUT`` file and returns a single file with
    the config that needs to be passed to MAGICC in order to do the same run as is
    represented by the values in ``PARAMETERS.OUT``.

    Parameters
    ----------
    parameters_out_file : str
        The ``PARAMETERS.OUT`` file to read

    namelist_to_read : str
        The namelist to read from the file.

    Returns
    -------
    :obj:`f90nml.Namelist`
        An f90nml object with the cleaned, read out config.

    Examples
    --------
    >>> cfg = pull_cfg_from_parameters_out_file("PARAMETERS.OUT")
    >>> cfg.write("/somewhere/else/ANOTHERNAME.cfg")
    """
    parameters_out = read_cfg_file(parameters_out_file)
    return pull_cfg_from_parameters_out(
        parameters_out, namelist_to_read=namelist_to_read
    )


Instruction:
Can you generate the documentation for the following Python 3 function
def get_generic_rcp_name(inname):
    # TODO: move into OpenSCM
    mapping = {
        "rcp26": "rcp26",
        "rcp3pd": "rcp26",
        "rcp45": "rcp45",
        "rcp6": "rcp60",
        "rcp60": "rcp60",
        "rcp85": "rcp85",
    }
    try:
        return mapping[inname.lower()]
    except KeyError:
        error_msg = "No generic name for input: {}".format(inname)
        raise ValueError(error_msg)

Response: Convert an RCP name into the generic Pymagicc RCP name.


Instruction:
Write a Python 3 function for
joining two sets of time series into a single time series.

Response:
def join_timeseries(base, overwrite, join_linear=None):
    """Join two sets of timeseries

    Parameters
    ----------
    base : :obj:`MAGICCData`, :obj:`pd.DataFrame`, filepath
        Base timeseries to use. If a filepath, the data will first be loaded from disk.

    overwrite : :obj:`MAGICCData`, :obj:`pd.DataFrame`, filepath
        Timeseries to join onto base. Any points which are in both `base` and
        `overwrite` will be taken from `overwrite`. If a filepath, the data will first
        be loaded from disk.

    join_linear : tuple of len(2)
        A list/array which specifies the period over which the two timeseries should
        be joined. The first element is the start time of the join period, the second
        element is the end time of the join period. In the join period (excluding the
        start and end times), output data will be a linear interpolation between (the
        annually interpolated) `base` and `overwrite` data. If None, no linear join
        will be done and any points in (the annually interpolated) `overwrite` data
        will simply overwrite any points in `base`.

    Returns
    -------
    :obj:`MAGICCData`
        The joint timeseries. The resulting data is linearly interpolated onto annual steps
    """
    if join_linear is not None:
        if len(join_linear) != 2:
            raise ValueError("join_linear must have a length of 2")

    if isinstance(base, str):
        base = MAGICCData(base)
    elif isinstance(base, MAGICCData):
        base = deepcopy(base)

    if isinstance(overwrite, str):
        overwrite = MAGICCData(overwrite)
    elif isinstance(overwrite, MAGICCData):
        overwrite = deepcopy(overwrite)

    result = _join_timeseries_mdata(base, overwrite, join_linear)

    return MAGICCData(result)


Instruction:
Write a Python 3 function that can
read a MAGICC. SCEN file and return the data and metadata.

Response:
def read_scen_file(
    filepath,
    columns={
        "model": ["unspecified"],
        "scenario": ["unspecified"],
        "climate_model": ["unspecified"],
    },
    **kwargs
):
    """
    Read a MAGICC .SCEN file.

    Parameters
    ----------
    filepath : str
        Filepath of the .SCEN file to read

    columns : dict
        Passed to ``__init__`` method of MAGICCData. See
        ``MAGICCData.__init__`` for details.

    kwargs
        Passed to ``__init__`` method of MAGICCData. See
        ``MAGICCData.__init__`` for details.

    Returns
    -------
    :obj:`pymagicc.io.MAGICCData`
        ``MAGICCData`` object containing the data and metadata.
    """
    mdata = MAGICCData(filepath, columns=columns, **kwargs)

    return mdata


Instruction:
How would you explain what the following Python 3 function does
def _get_openscm_var_from_filepath(filepath):
    reader = determine_tool(filepath, "reader")(filepath)
    openscm_var = convert_magicc7_to_openscm_variables(
        convert_magicc6_to_magicc7_variables(reader._get_variable_from_filepath())
    )

    return openscm_var

Response: Returns the OpenSCM variable implied by a filepath.


Instruction:
Can you write a function in Python 3 where it
finds the start and end index of the embedded namelist.

Response:
def _find_nml(self):
        """
        Find the start and end of the embedded namelist.

        Returns
        -------
        (int, int)
            start and end index for the namelist
        """
        nml_start = None
        nml_end = None
        for i in range(len(self.lines)):
            if self.lines[i].strip().startswith("&"):
                nml_start = i

            if self.lines[i].strip().startswith("/"):
                nml_end = i
        assert (
            nml_start is not None and nml_end is not None
        ), "Could not find namelist within {}".format(self.filepath)
        return nml_end, nml_start


Instruction:
How would you implement a function in Python 3 that
extracts the tabulated data from the input file and return a pandas. DataFrame and the metadata.

Response:
def process_data(self, stream, metadata):
        """
        Extract the tabulated data from the input file.

        Parameters
        ----------
        stream : Streamlike object
            A Streamlike object (nominally StringIO)
            containing the table to be extracted
        metadata : dict
            Metadata read in from the header and the namelist

        Returns
        -------
        (pandas.DataFrame, dict)
            The first element contains the data, processed to the standard
            MAGICCData format.
            The second element is th updated metadata based on the processing performed.
        """
        ch, metadata = self._get_column_headers_and_update_metadata(stream, metadata)
        df = self._convert_data_block_and_headers_to_df(stream)

        return df, metadata, ch


Instruction:
Write a Python 3 function that can
convert the data block and headers to a Pandas DataFrame.

Response:
def _convert_data_block_and_headers_to_df(self, stream):
        """
        stream : Streamlike object
            A Streamlike object (nominally StringIO) containing the data to be
            extracted

        ch : dict
            Column headers to use for the output pd.DataFrame

        Returns
        -------
        :obj:`pd.DataFrame`
            Dataframe with processed datablock
        """
        df = pd.read_csv(
            stream,
            skip_blank_lines=True,
            delim_whitespace=True,
            header=None,
            index_col=0,
        )

        if isinstance(df.index, pd.core.indexes.numeric.Float64Index):
            df.index = df.index.to_series().round(3)

        # reset the columns to be 0..n instead of starting at 1
        df.columns = list(range(len(df.columns)))

        return df


Instruction:
Can you write a function in Python 3 where it
determines the file variable from the filepath.

Response:
def _get_variable_from_filepath(self):
        """
        Determine the file variable from the filepath.

        Returns
        -------
        str
            Best guess of variable name from the filepath
        """
        try:
            return self.regexp_capture_variable.search(self.filepath).group(1)
        except AttributeError:
            self._raise_cannot_determine_variable_from_filepath_error()


Instruction:
Implement a function in Python 3 to
parse the header for additional metadata.

Response:
def process_header(self, header):
        """
        Parse the header for additional metadata.

        Parameters
        ----------
        header : str
            All the lines in the header.

        Returns
        -------
        dict
            The metadata in the header.
        """
        metadata = {}
        for line in header.split("\n"):
            line = line.strip()
            for tag in self.header_tags:
                tag_text = "{}:".format(tag)
                if line.lower().startswith(tag_text):
                    metadata[tag] = line[len(tag_text) + 1 :].strip()

        return metadata


Instruction:
How would you explain what the following Python 3 function does
def _read_data_header_line(self, stream, expected_header):
        pos = stream.tell()
        expected_header = (
            [expected_header] if isinstance(expected_header, str) else expected_header
        )
        for exp_hd in expected_header:
            tokens = stream.readline().split()
            try:
                assert tokens[0] == exp_hd
                return tokens[1:]
            except AssertionError:
                stream.seek(pos)
                continue

        assertion_msg = "Expected a header token of {}, got {}".format(
            expected_header, tokens[0]
        )
        raise AssertionError(assertion_msg)

Response: Read a data header line and ensure that it starts with the expected header.


Instruction:
Can you generate the documentation for the following Python 3 function
def read_chunk(self, t):
        size = self.data[self.pos : self.pos + 4].cast("i")[0]
        d = self.data[self.pos + 4 : self.pos + 4 + size]

        assert (
            self.data[self.pos + 4 + size : self.pos + 4 + size + 4].cast("i")[0]
            == size
        )
        self.pos = self.pos + 4 + size + 4

        res = np.array(d.cast(t))

        # Return as a scalar or a numpy array if it is an array
        if res.size == 1:
            return res[0]
        return res

Response: Read out the next chunk of memory from the fortran binary stream.


Instruction:
Can you tell what is the following Python 3 function doing
def process_data(self, stream, metadata):
        index = np.arange(metadata["firstyear"], metadata["lastyear"] + 1)

        # The first variable is the global values
        globe = stream.read_chunk("d")

        assert len(globe) == len(index)

        regions = stream.read_chunk("d")
        num_regions = int(len(regions) / len(index))
        regions = regions.reshape((-1, num_regions), order="F")

        data = np.concatenate((globe[:, np.newaxis], regions), axis=1)

        df = pd.DataFrame(data, index=index)

        if isinstance(df.index, pd.core.indexes.numeric.Float64Index):
            df.index = df.index.to_series().round(3)

        df.index.name = "time"

        regions = [
            "World",
            "World|Northern Hemisphere|Ocean",
            "World|Northern Hemisphere|Land",
            "World|Southern Hemisphere|Ocean",
            "World|Southern Hemisphere|Land",
        ]

        variable = convert_magicc6_to_magicc7_variables(
            self._get_variable_from_filepath()
        )
        variable = convert_magicc7_to_openscm_variables(variable)
        column_headers = {
            "variable": [variable] * (num_regions + 1),
            "region": regions,
            "unit": ["unknown"] * len(regions),
            "todo": ["SET"] * len(regions),
        }

        return df, metadata, self._set_column_defaults(column_headers)

Response: Extracts the tabulated data from the input file and returns a Pandas DataFrame containing the data extracted to the standard MAGICCData format.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def process_header(self, data):
        metadata = {
            "datacolumns": data.read_chunk("I"),
            "firstyear": data.read_chunk("I"),
            "lastyear": data.read_chunk("I"),
            "annualsteps": data.read_chunk("I"),
        }
        if metadata["annualsteps"] != 1:
            raise InvalidTemporalResError(
                "{}: Only annual files can currently be processed".format(self.filepath)
            )

        return metadata

Response: Reads the first part of the file to get some essential metadata


Instruction:
Create a Python 3 function for
writing a MAGICC input file from df and metadata

Response:
def write(self, magicc_input, filepath):
        """
        Write a MAGICC input file from df and metadata

        Parameters
        ----------
        magicc_input : :obj:`pymagicc.io.MAGICCData`
            MAGICCData object which holds the data to write

        filepath : str
            Filepath of the file to write to.
        """
        self._filepath = filepath
        # TODO: make copy attribute for MAGICCData
        self.minput = deepcopy(magicc_input)
        self.data_block = self._get_data_block()

        output = StringIO()

        output = self._write_header(output)
        output = self._write_namelist(output)
        output = self._write_datablock(output)

        with open(
            filepath, "w", encoding="utf-8", newline=self._newline_char
        ) as output_file:
            output.seek(0)
            copyfileobj(output, output_file)


Instruction:
Write a Python 3 script for
appending any input which can be converted to MAGICCData to self.

Response:
def append(self, other, inplace=False, **kwargs):
        """
        Append any input which can be converted to MAGICCData to self.

        Parameters
        ----------
        other : MAGICCData, pd.DataFrame, pd.Series, str
            Source of data to append.

        inplace : bool
            If True, append ``other`` inplace, otherwise return a new ``MAGICCData``
            instance.

        **kwargs
            Passed to ``MAGICCData`` constructor (only used if ``MAGICCData`` is not a
            ``MAGICCData`` instance).
        """
        if not isinstance(other, MAGICCData):
            other = MAGICCData(other, **kwargs)

        if inplace:
            super().append(other, inplace=inplace)
            self.metadata.update(other.metadata)
        else:
            res = super().append(other, inplace=inplace)
            res.metadata = deepcopy(self.metadata)
            res.metadata.update(other.metadata)

            return res


Instruction:
How would you code a function in Python 3 to
write an input file to disk.

Response:
def write(self, filepath, magicc_version):
        """
        Write an input file to disk.

        Parameters
        ----------
        filepath : str
            Filepath of the file to write.

        magicc_version : int
            The MAGICC version for which we want to write files. MAGICC7 and MAGICC6
            namelists are incompatible hence we need to know which one we're writing
            for.
        """
        writer = determine_tool(filepath, "writer")(magicc_version=magicc_version)
        writer.write(self, filepath)


Instruction:
Can you generate a brief explanation for the following Python 3 code
def validate_python_identifier_attributes(fully_qualified_name: str, spec: Dict[str, Any],
                                          *attributes: str) -> List[InvalidIdentifierError]:
    """ Validates a set of attributes as identifiers in a spec """
    errors: List[InvalidIdentifierError] = []

    checks: List[Tuple[Callable, InvalidIdentifierError.Reason]] = [
        (lambda x: x.startswith('_'), InvalidIdentifierError.Reason.STARTS_WITH_UNDERSCORE),
        (lambda x: x.startswith('run_'), InvalidIdentifierError.Reason.STARTS_WITH_RUN),
        (lambda x: not x.isidentifier(), InvalidIdentifierError.Reason.INVALID_PYTHON_IDENTIFIER),
    ]

    for attribute in attributes:
        if attribute not in spec or spec.get(ATTRIBUTE_INTERNAL, False):
            continue

        for check in checks:
            if check[0](spec[attribute]):
                errors.append(
                    InvalidIdentifierError(fully_qualified_name, spec, attribute, check[1]))
                break

    return errors

Response: Validates a set of attributes as identifiers in a resource tree.


Instruction:
Create a Python 3 function for
validating that a set of attributes are present in the resource tree.

Response:
def validate_required_attributes(fully_qualified_name: str, spec: Dict[str, Any],
                                 *attributes: str) -> List[RequiredAttributeError]:
    """ Validates to ensure that a set of attributes are present in spec """
    return [
        RequiredAttributeError(fully_qualified_name, spec, attribute)
        for attribute in attributes
        if attribute not in spec
    ]


Instruction:
Can you generate a brief explanation for the following Python 3 code
def validate_empty_attributes(fully_qualified_name: str, spec: Dict[str, Any],
                              *attributes: str) -> List[EmptyAttributeError]:
    """ Validates to ensure that a set of attributes do not contain empty values """
    return [
        EmptyAttributeError(fully_qualified_name, spec, attribute)
        for attribute in attributes
        if not spec.get(attribute, None)
    ]

Response: Validates that a set of attributes do not contain empty values.


Instruction:
Write a Python 3 script to
validate that the value of the specified attribute is a number of the specified type and lies with the specified range.

Response:
def validate_number_attribute(
        fully_qualified_name: str,
        spec: Dict[str, Any],
        attribute: str,
        value_type: Union[Type[int], Type[float]] = int,
        minimum: Optional[Union[int, float]] = None,
        maximum: Optional[Union[int, float]] = None) -> Optional[InvalidNumberError]:
    """ Validates to ensure that the value is a number of the specified type, and lies with the specified range """

    if attribute not in spec:
        return

    try:
        value = value_type(spec[attribute])
        if (minimum is not None and value < minimum) or (maximum is not None and value > maximum):
            raise None
    except:
        return InvalidNumberError(fully_qualified_name, spec, attribute, value_type, minimum,
                                  maximum)


Instruction:
Write a Python 3 script for
validating that the value of an attribute lies within a set of candidates.

Response:
def validate_enum_attribute(fully_qualified_name: str, spec: Dict[str, Any], attribute: str,
                            candidates: Set[Union[str, int, float]]) -> Optional[InvalidValueError]:
    """ Validates to ensure that the value of an attribute lies within an allowed set of candidates """

    if attribute not in spec:
        return

    if spec[attribute] not in candidates:
        return InvalidValueError(fully_qualified_name, spec, attribute, candidates)


Instruction:
Can you tell what is the following Python 3 function doing
def parse(key_string: str) -> 'Key':
        parts = key_string.split(Key.PARTITION)
        key_type = KeyType.DIMENSION
        if parts[3]:
            key_type = KeyType.TIMESTAMP
        return Key(key_type, parts[0], parts[1], parts[2].split(Key.DIMENSION_PARTITION)
                   if parts[2] else [],
                   parser.parse(parts[3]) if parts[3] else None)

Response: Parses a flat key string and returns a Key object


Instruction:
Can you create a Python 3 function that
parses a flat key string and returns a Key object

Response:
def parse_sort_key(identity: str, sort_key_string: str) -> 'Key':
        """ Parses a flat key string and returns a key """
        parts = sort_key_string.split(Key.PARTITION)
        key_type = KeyType.DIMENSION
        if parts[2]:
            key_type = KeyType.TIMESTAMP
        return Key(key_type, identity, parts[0], parts[1].split(Key.DIMENSION_PARTITION)
                   if parts[1] else [],
                   parser.parse(parts[2]) if parts[2] else None)


Instruction:
Write a Python 3 function for
checking if this key starts with the other key. Returns False if this key starts with other key.

Response:
def starts_with(self, other: 'Key') -> bool:
        """
        Checks if this key starts with the other key provided. Returns False if key_type, identity
        or group are different.
        For `KeyType.TIMESTAMP` returns True.
        For `KeyType.DIMENSION` does prefix match between the two dimensions property.
        """
        if (self.key_type, self.identity, self.group) != (other.key_type, other.identity,
                                                          other.group):
            return False
        if self.key_type == KeyType.TIMESTAMP:
            return True
        if self.key_type == KeyType.DIMENSION:
            if len(self.dimensions) < len(other.dimensions):
                return False
            return self.dimensions[0:len(other.dimensions)] == other.dimensions


Instruction:
Can you tell what is the following Python 3 function doing
def _evaluate_dimension_fields(self) -> bool:
        for _, item in self._dimension_fields.items():
            item.run_evaluate()
            if item.eval_error:
                return False
        return True

Response: Evaluates the dimension fields. Returns True if any of the fields could not be evaluated.


Instruction:
Given the following Python 3 function, write the documentation
def _compare_dimensions_to_fields(self) -> bool:
        for name, item in self._dimension_fields.items():
            if item.value != self._nested_items[name].value:
                return False
        return True

Response: Compares the dimension field values to the value in regular fields.


Instruction:
Write a Python 3 function for
generating the Key object based on dimension fields.

Response:
def _key(self):
        """ Generates the Key object based on dimension fields. """
        return Key(self._schema.key_type, self._identity, self._name,
                   [str(item.value) for item in self._dimension_fields.values()])


Instruction:
Can you generate a brief explanation for the following Python 3 code
def run(scenario, magicc_version=6, **kwargs):
    if magicc_version == 6:
        magicc_cls = MAGICC6
    elif magicc_version == 7:
        magicc_cls = MAGICC7
    else:
        raise ValueError("MAGICC version {} is not available".format(magicc_version))

    with magicc_cls() as magicc:
        results = magicc.run(scenario=scenario, **kwargs)

    return results

Response: Run a MAGICC scenario and return the output data and config parameters.


Instruction:
Given the following Python 3 function, write the documentation
def run_evaluate(self, block: TimeAggregate) -> bool:
        if self._anchor.evaluate_anchor(block, self._evaluation_context):

            try:
                self.run_reset()
                self._evaluation_context.global_add('anchor', block)
                self._evaluate()
                self._anchor.add_condition_met()
                return True
            finally:
                self._evaluation_context.global_remove('anchor')

        return False

Response: Evaluates the anchor condition against the specified block.


Instruction:
How would you explain what the following Python 3 function does
def extend_schema_spec(self) -> None:
        super().extend_schema_spec()

        if self.ATTRIBUTE_FIELDS in self._spec:
            # Add new fields to the schema spec. Since `_identity` is added by the super, new elements are added after
            predefined_field = self._build_time_fields_spec(self._spec[self.ATTRIBUTE_NAME])
            self._spec[self.ATTRIBUTE_FIELDS][1:1] = predefined_field

            # Add new field schema to the schema loader
            for field_schema in predefined_field:
                self.schema_loader.add_schema_spec(field_schema, self.fully_qualified_name)

Response: Extends the schema spec with the block start and end times.


Instruction:
Write a Python 3 script to
construct the spec for predefined fields that are to be included in the master spec prior to schema load

Response:
def _build_time_fields_spec(name_in_context: str) -> List[Dict[str, Any]]:
        """
        Constructs the spec for predefined fields that are to be included in the master spec prior to schema load
        :param name_in_context: Name of the current object in the context
        :return:
        """
        return [
            {
                'Name': '_start_time',
                'Type': Type.DATETIME,
                'Value': ('time if {aggregate}._start_time is None else time '
                          'if time < {aggregate}._start_time else {aggregate}._start_time'
                          ).format(aggregate=name_in_context),
                ATTRIBUTE_INTERNAL: True
            },
            {
                'Name': '_end_time',
                'Type': Type.DATETIME,
                'Value': ('time if {aggregate}._end_time is None else time '
                          'if time > {aggregate}._end_time else {aggregate}._end_time'
                          ).format(aggregate=name_in_context),
                ATTRIBUTE_INTERNAL: True
            },
        ]


Instruction:
Make a summary of the following Python 3 code
def apply_string_substitutions(
    inputs,
    substitutions,
    inverse=False,
    case_insensitive=False,
    unused_substitutions="ignore",
):
    """Apply a number of substitutions to a string(s).

    The substitutions are applied effectively all at once. This means that conflicting
    substitutions don't interact. Where substitutions are conflicting, the one which
    is longer takes precedance. This is confusing so we recommend that you look at
    the examples.

    Parameters
    ----------
    inputs : str, list of str
        The string(s) to which we want to apply the substitutions.

    substitutions : dict
        The substitutions we wish to make. The keys are the strings we wish to
        substitute, the values are the strings which we want to appear in the output
        strings.

    inverse : bool
        If True, do the substitutions the other way around i.e. use the keys as the
        strings we want to appear in the output strings and the values as the strings
        we wish to substitute.

    case_insensitive : bool
        If True, the substitutions will be made in a case insensitive way.

    unused_substitutions : {"ignore", "warn", "raise"}, default ignore
        Behaviour when one or more of the inputs does not have a corresponding
        substitution. If "ignore", nothing happens. If "warn", a warning is issued. If
        "raise", an error is raised. See the examples.

    Returns
    -------
    ``type(input)``
        The input with substitutions performed.

    Examples
    --------
    >>> apply_string_substitutions("Hello JimBob", {"Jim": "Bob"})
    'Hello BobBob'

    >>> apply_string_substitutions("Hello JimBob", {"Jim": "Bob"}, inverse=True)
    'Hello JimJim'

    >>> apply_string_substitutions(["Hello JimBob", "Jim says, 'Hi Bob'"], {"Jim": "Bob"})
    ['Hello BobBob', "Bob says, 'Hi Bob'"]

    >>> apply_string_substitutions(["Hello JimBob", "Jim says, 'Hi Bob'"], {"Jim": "Bob"}, inverse=True)
    ['Hello JimJim', "Jim says, 'Hi Jim'"]

    >>> apply_string_substitutions("Muttons Butter", {"M": "B", "Button": "Zip"})
    'Buttons Butter'
    # Substitutions don't cascade. If they did, Muttons would become Buttons, then the
    # substitutions "Button" --> "Zip" would be applied and we would end up with
    # "Zips Butter".

    >>> apply_string_substitutions("Muttons Butter", {"Mutton": "Gutter", "tt": "zz"})
    'Gutters Buzzer'
    # Longer substitutions take precedent. Hence Mutton becomes Gutter, not Muzzon.

    >>> apply_string_substitutions("Butter", {"buTTer": "Gutter"}, case_insensitive=True)
    'Gutter'

    >>> apply_string_substitutions("Butter", {"teeth": "tooth"})
    'Butter'

    >>> apply_string_substitutions("Butter", {"teeth": "tooth"}, unused_substitutions="ignore")
    'Butter'

    >>> apply_string_substitutions("Butter", {"teeth": "tooth"}, unused_substitutions="warn")
    ...pymagicc/utils.py:50: UserWarning: No substitution available for {'Butter'} warnings.warn(msg)
    'Butter'

    >>> apply_string_substitutions("Butter", {"teeth": "tooth"}, unused_substitutions="raise")
    ValueError: No substitution available for {'Butter'}
    """
    if inverse:
        substitutions = {v: k for k, v in substitutions.items()}

    # only possible to have conflicting substitutions when case insensitive
    if case_insensitive:
        _check_duplicate_substitutions(substitutions)

    if unused_substitutions != "ignore":
        _check_unused_substitutions(
            substitutions, inputs, unused_substitutions, case_insensitive
        )

    compiled_regexp = _compile_replacement_regexp(
        substitutions, case_insensitive=case_insensitive
    )

    inputs_return = deepcopy(inputs)
    if isinstance(inputs_return, str):
        inputs_return = _multiple_replace(inputs_return, substitutions, compiled_regexp)
    else:
        inputs_return = [
            _multiple_replace(v, substitutions, compiled_regexp) for v in inputs_return
        ]

    return inputs_return

Response: Apply a number of substitutions to a string.


Instruction:
Write a Python 3 function that can
return the list of items from the store based on the given time range.

Response:
def get_range(self,
                  base_key: Key,
                  start_time: datetime,
                  end_time: datetime = None,
                  count: int = 0) -> List[Tuple[Key, Any]]:
        """
        Returns the list of items from the store based on the given time range or count.
        :param base_key: Items which don't start with the base_key are filtered out.
        :param start_time: Start time to for the range query
        :param end_time: End time of the range query. If None count is used.
        :param count: The number of items to be returned. Used if end_time is not specified.
        """
        if end_time and count:
            raise ValueError('Only one of `end` or `count` can be set')

        if count:
            end_time = datetime.min.replace(
                tzinfo=timezone.utc) if count < 0 else datetime.max.replace(tzinfo=timezone.utc)

        end_time = self._add_timezone_if_required(end_time)
        start_time = self._add_timezone_if_required(start_time)

        if end_time < start_time:
            start_time, end_time = end_time, start_time

        if base_key.key_type == KeyType.TIMESTAMP:
            start_key = Key(KeyType.TIMESTAMP, base_key.identity, base_key.group, [], start_time)
            end_key = Key(KeyType.TIMESTAMP, base_key.identity, base_key.group, [], end_time)
            return self._get_range_timestamp_key(start_key, end_key, count)
        else:
            return self._get_range_dimension_key(base_key, start_time, end_time, count)


Instruction:
Explain what the following Python 3 code does
def _get_range_timestamp_key(self, start: Key, end: Key,
                                 count: int = 0) -> List[Tuple[Key, Any]]:
        """
        Returns the list of items from the store based on the given time range or count.

        This is used when the key being used is a TIMESTAMP key.
        """
        raise NotImplementedError()

Response: Returns the list of items from the store based on the given time range.


Instruction:
Given the following Python 3 function, write the documentation
def _get_range_dimension_key(self,
                                 base_key: Key,
                                 start_time: datetime,
                                 end_time: datetime,
                                 count: int = 0) -> List[Tuple[Key, Any]]:
        """
        Returns the list of items from the store based on the given time range or count.

        This is used when the key being used is a DIMENSION key.
        """
        raise NotImplementedError()

Response: Returns the list of items from the store based on the given time range or count.


Instruction:
Can you tell what is the following Python 3 function doing
def _restrict_items_to_count(items: List[Tuple[Key, Any]], count: int) -> List[Tuple[Key, Any]]:
        if abs(count) > len(items):
            count = Store._sign(count) * len(items)

        if count < 0:
            return items[count:]
        else:
            return items[:count]

Response: Restricts items to count number if the number of items is larger than abs ( count.


Instruction:
Write a Python 3 script to
build an expression object.

Response:
def build_expression(self, attribute: str) -> Optional[Expression]:
        """ Builds an expression object.  Adds an error if expression creation has errors. """

        expression_string = self._spec.get(attribute, None)
        if expression_string:
            try:
                return Expression(str(expression_string))
            except Exception as err:
                self.add_errors(
                    InvalidExpressionError(self.fully_qualified_name, self._spec, attribute, err))

        return None


Instruction:
Can you generate the documentation for the following Python 3 function
def add_errors(self, *errors: Union[BaseSchemaError, List[BaseSchemaError]]) -> None:
        self.schema_loader.add_errors(*errors)

Response: Adds errors to the error repository.


Instruction:
Can you write a function in Python 3 where it
validates that the schema contains a series of required attributes.

Response:
def validate_required_attributes(self, *attributes: str) -> None:
        """ Validates that the schema contains a series of required attributes """
        self.add_errors(
            validate_required_attributes(self.fully_qualified_name, self._spec, *attributes))


Instruction:
How would you implement a function in Python 3 that
validates that the attribute contains a numeric value within boundaries.

Response:
def validate_number_attribute(self,
                                  attribute: str,
                                  value_type: Union[Type[int], Type[float]] = int,
                                  minimum: Optional[Union[int, float]] = None,
                                  maximum: Optional[Union[int, float]] = None) -> None:
        """ Validates that the attribute contains a numeric value within boundaries if specified """
        self.add_errors(
            validate_number_attribute(self.fully_qualified_name, self._spec, attribute, value_type,
                                      minimum, maximum))


Instruction:
Implement a function in Python 3 to
validate that the attribute value is among the candidates.

Response:
def validate_enum_attribute(self, attribute: str,
                                candidates: Set[Union[str, int, float]]) -> None:
        """ Validates that the attribute value is among the candidates """
        self.add_errors(
            validate_enum_attribute(self.fully_qualified_name, self._spec, attribute, candidates))


Instruction:
Can you generate a brief explanation for the following Python 3 code
def validate_schema_spec(self) -> None:
        self.add_errors(
            validate_empty_attributes(self.fully_qualified_name, self._spec, *self._spec.keys()))
        self.add_errors(
            validate_python_identifier_attributes(self.fully_qualified_name, self._spec,
                                                  self.ATTRIBUTE_NAME))

Response: This method is called by the validation routines that are called by the base class to validate the schema specification.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def _needs_evaluation(self) -> bool:
        return self._schema.when is None or self._schema.when.evaluate(self._evaluation_context)

Response: Returns True when the schema needs evaluation


Instruction:
Implement a Python 3 function for
evaluating the current item and returns an evaluation result object containing the result and reasons why the evaluation failed

Response:
def run_evaluate(self, *args, **kwargs) -> None:
        """
        Evaluates the current item
        :returns An evaluation result object containing the result, or reasons why
        evaluation failed
        """
        if self._needs_evaluation:
            for _, item in self._nested_items.items():
                item.run_evaluate()


Instruction:
Explain what the following Python 3 code does
def _snapshot(self) -> Dict[str, Any]:
        try:
            return {name: item._snapshot for name, item in self._nested_items.items()}
        except Exception as e:
            raise SnapshotError('Error while creating snapshot for {}'.format(self._name)) from e

Response: Creates a snapshot of the current item.


Instruction:
Here you have a function in Python 3, explain what it does
def run_restore(self, snapshot: Dict[Union[str, Key], Any]) -> 'BaseItemCollection':
        try:

            for name, snap in snapshot.items():
                if isinstance(name, Key):
                    self._nested_items[name.group].run_restore(snap)
                else:
                    self._nested_items[name].run_restore(snap)
            return self

        except Exception as e:
            raise SnapshotError('Error while restoring snapshot: {}'.format(self._snapshot)) from e

Response: Restores the state of a collection from a snapshot


Instruction:
Create a Python 3 function for
preparing the window for the current window.

Response:
def _prepare_window(self, start_time: datetime) -> None:
        """
        Prepares window if any is specified.
        :param start_time: The anchor block start_time from where the window
        should be generated.
        """
        # evaluate window first which sets the correct window in the store
        store = self._schema.schema_loader.get_store(
            self._schema.source.store_schema.fully_qualified_name)
        if Type.is_type_equal(self._schema.window_type, Type.DAY) or Type.is_type_equal(
                self._schema.window_type, Type.HOUR):
            block_list = self._load_blocks(
                store.get_range(
                    Key(self._schema.source.key_type, self._identity, self._schema.source.name),
                    start_time, self._get_end_time(start_time)))
        else:
            block_list = self._load_blocks(
                store.get_range(
                    Key(self._schema.source.key_type, self._identity, self._schema.source.name),
                    start_time, None, self._schema.window_value))

        self._window_source = _WindowSource(block_list)
        self._validate_view()


Instruction:
Implement a Python 3 function for
generating the end time to be used for the store range query.

Response:
def _get_end_time(self, start_time: datetime) -> datetime:
        """
        Generates the end time to be used for the store range query.
        :param start_time: Start time to use as an offset to calculate the end time
        based on the window type in the schema.
        :return:
        """
        if Type.is_type_equal(self._schema.window_type, Type.DAY):
            return start_time + timedelta(days=self._schema.window_value)
        elif Type.is_type_equal(self._schema.window_type, Type.HOUR):
            return start_time + timedelta(hours=self._schema.window_value)


Instruction:
How would you code a function in Python 3 to
convert [ ( Key block ) to [ BlockAggregate ]

Response:
def _load_blocks(self, blocks: List[Tuple[Key, Any]]) -> List[TimeAggregate]:
        """
        Converts [(Key, block)] to [BlockAggregate]
        :param blocks: List of (Key, block) blocks.
        :return: List of BlockAggregate
        """
        return [
            TypeLoader.load_item(self._schema.source.type)(self._schema.source, self._identity,
                                                           EvaluationContext()).run_restore(block)
            for (_, block) in blocks
        ]


Instruction:
Given the following Python 3 function, write the documentation
def execute_per_identity_records(
            self,
            identity: str,
            records: List[TimeAndRecord],
            old_state: Optional[Dict[Key, Any]] = None) -> Tuple[str, Tuple[Dict, List]]:
        """
        Executes the streaming and window BTS on the given records. An option old state can provided
        which initializes the state for execution. This is useful for batch execution where the
        previous state is written out to storage and can be loaded for the next batch run.

        :param identity: Identity of the records.
        :param records: List of TimeAndRecord to be processed.
        :param old_state: Streaming BTS state dictionary from a previous execution.
        :return: Tuple[Identity, Tuple[Identity, Tuple[Streaming BTS state dictionary,
            List of window BTS output]].
        """
        schema_loader = SchemaLoader()
        if records:
            records.sort(key=lambda x: x[0])
        else:
            records = []

        block_data = self._execute_stream_bts(records, identity, schema_loader, old_state)
        window_data = self._execute_window_bts(identity, schema_loader)

        return identity, (block_data, window_data)

Response: Executes the streaming and window BTS on the given records.


Instruction:
Explain what the following Python 3 code does
def get_per_identity_records(self, events: Iterable, data_processor: DataProcessor
                                 ) -> Generator[Tuple[str, TimeAndRecord], None, None]:
        """
        Uses the given iteratable events and the data processor convert the event into a list of
        Records along with its identity and time.
        :param events: iteratable events.
        :param data_processor: DataProcessor to process each event in events.
        :return: yields Tuple[Identity, TimeAndRecord] for all Records in events,
        """
        schema_loader = SchemaLoader()
        stream_bts_name = schema_loader.add_schema_spec(self._stream_bts)
        stream_transformer_schema: StreamingTransformerSchema = schema_loader.get_schema_object(
            stream_bts_name)
        for event in events:
            try:
                for record in data_processor.process_data(event):
                    try:
                        id = stream_transformer_schema.get_identity(record)
                        time = stream_transformer_schema.get_time(record)
                        yield (id, (time, record))
                    except Exception as err:
                        logging.error('{} in parsing Record {}.'.format(err, record))
            except Exception as err:
                logging.error('{} in parsing Event {}.'.format(err, event))

Response: Returns a generator that yields all Records in the given events and the time and record.