Instruction:
Can you tell what is the following Python 3 function doing
def _discover_toc(zf, opf_xmldoc, opf_filepath):
    '''
    Returns a list of objects: {title: str, src: str, level: int, index: int}
    '''
    toc = None

    # ePub 3.x
    tag = find_tag(opf_xmldoc, 'item', 'properties', 'nav')
    if tag and 'href' in tag.attributes.keys():
        filepath = unquote(tag.attributes['href'].value)
        # The xhtml file path is relative to the OPF file
        base_dir = os.path.dirname(opf_filepath)
        # print('- Reading Nav file: {}/{}'.format(base_dir, filepath))
        npath = os.path.normpath(os.path.join(base_dir, filepath))
        nav_content = zf.read(npath)
        toc_xmldoc = minidom.parseString(nav_content)

        _toc = []

        for n in toc_xmldoc.getElementsByTagName('a'):
            if n.firstChild and ('href' in n.attributes.keys()):
                href = unquote(n.attributes['href'].value)
                # Discarding CFI links
                if '.html' in href or '.xhtml' in href:
                    title = n.firstChild.nodeValue
                    # try the second node too (maybe the first child is an empty span)
                    if not title and n.firstChild.firstChild:
                        title = n.firstChild.firstChild.nodeValue

                    title = title.strip() if title else None

                    if title:
                        level = -1
                        parentNode = n.parentNode
                        avoid_infinite_loop = 0 # simple security issue to avoid infinite loop for bad epub files
                        while parentNode and parentNode.nodeName != 'nav' and avoid_infinite_loop < 50:
                            if parentNode.nodeName == 'ol': # count the depth of the a link related to ol items
                                level += 1
                            parentNode = parentNode.parentNode
                            avoid_infinite_loop += 1
                        level = max(level, 0) # root level is 0, not -1

                        _toc.append({'title': title, 'src': href, 'level': level})
        if _toc:
            toc = _toc

    if not toc:
        # ePub 2.x
        tag = find_tag(opf_xmldoc, 'item', 'id', 'ncx')
        if not tag:
            tag = find_tag(opf_xmldoc, 'item', 'id', 'ncxtoc')
        if tag and 'href' in tag.attributes.keys():
            filepath = unquote(tag.attributes['href'].value)
            # The ncx file path is relative to the OPF file
            base_dir = os.path.dirname(opf_filepath)
            # print('- Reading NCX file: {}/{}'.format(base_dir, filepath))
            npath = os.path.normpath(os.path.join(base_dir, filepath))
            ncx_content = zf.read(npath)

            toc_xmldoc = minidom.parseString(ncx_content)

            def read_nav_point(nav_point_node, level = 0):
                items = []
                item = {'title': None, 'src': None, 'level': level}
                children_points = []
                for item_node in nav_point_node.childNodes:
                    if item_node.nodeName in ('navLabel', 'ncx:navLabel'):
                        try:
                            text = item_node.getElementsByTagName('text')[0].firstChild
                        except IndexError:
                            try:
                                text = item_node.getElementsByTagName('ncx:text')[0].firstChild
                            except IndexError:
                                text = None

                        item['title'] = text.nodeValue.strip() if text and text.nodeValue else None
                    elif item_node.nodeName in ('content', 'ncx:content'):
                        if item_node.hasAttribute('src'):
                            item['src'] = item_node.attributes['src'].value
                    elif item_node.nodeName in ('navPoint', 'ncx:navPoint'):
                        children_points.append(item_node)

                if item['title']:
                    items.append(item)
                    for child_node in children_points:
                        subitems = read_nav_point(child_node, level=level + 1)
                        items.extend(subitems)
                return items

            def read_nav_map(toc_xmldoc, level=0):
                items = []
                try:
                    nav_map_node = toc_xmldoc.getElementsByTagName('navMap')[0]
                except IndexError:
                    # Some ebooks use the ncx: namespace so try that too
                    try:
                        nav_map_node = toc_xmldoc.getElementsByTagName('ncx:navMap')[0]
                    except IndexError:
                        print('Failed reading TOC')
                        return items

                for nav_point in nav_map_node.childNodes:
                    if nav_point.nodeName in ('navPoint', 'ncx:navPoint'):
                        subitems = read_nav_point(nav_point, level=level)
                        items.extend(subitems)
                return items

            toc = read_nav_map(toc_xmldoc)

    # add indexes
    if toc:
        for i, t in enumerate(toc):
            t['index'] = i

    return toc

Response: Discovers the contents of the OPF file and returns a list of objects.


Instruction:
Here you have a function in Python 3, explain what it does
def get_epub_metadata(filepath, read_cover_image=True, read_toc=True):
    '''
    References: http://idpf.org/epub/201 and http://idpf.org/epub/301
    1. Parse META-INF/container.xml file and find the .OPF file path.
    2. In the .OPF file, find the metadata
    '''
    if not zipfile.is_zipfile(filepath):
        raise EPubException('Unknown file')

    # print('Reading ePub file: {}'.format(filepath))
    zf = zipfile.ZipFile(filepath, 'r', compression=zipfile.ZIP_DEFLATED, allowZip64=True)
    container = zf.read('META-INF/container.xml')
    container_xmldoc = minidom.parseString(container)
    # e.g.: <rootfile full-path="content.opf" media-type="application/oebps-package+xml"/>
    opf_filepath = container_xmldoc.getElementsByTagName('rootfile')[0].attributes['full-path'].value

    opf = zf.read(os.path.normpath(opf_filepath))
    opf_xmldoc = minidom.parseString(opf)

    # This file is specific to the authors if it exists.
    authors_html = None
    try:
        authors_html = minidom.parseString(zf.read('OEBPS/pr02.html'))
    except KeyError:
        # Most books store authors using epub tags, so no worries.
        pass

    # This file is specific to the publish date if it exists.
    publish_date_html = None
    try:
        publish_date_html = minidom.parseString(zf.read('OEBPS/pr01.html'))
    except KeyError:
        # Most books store authors using epub tags, so no worries.
        pass

    file_size_in_bytes = os.path.getsize(filepath)

    data = odict({
        'epub_version': _discover_epub_version(opf_xmldoc),
        'title': _discover_title(opf_xmldoc),
        'language': _discover_language(opf_xmldoc),
        'description': _discover_description(opf_xmldoc),
        'authors': _discover_authors(opf_xmldoc, authors_html=authors_html),
        'publisher': _discover_publisher(opf_xmldoc),
        'publication_date': _discover_publication_date(opf_xmldoc,
                                                       date_html=publish_date_html),
        'identifiers': _discover_identifiers(opf_xmldoc),
        'subject': _discover_subject(opf_xmldoc),
        'file_size_in_bytes': file_size_in_bytes,
    })

    if read_cover_image:
        cover_image_content, cover_image_extension = _discover_cover_image(zf, opf_xmldoc, opf_filepath)
        data.cover_image_content = cover_image_content
        data.cover_image_extension = cover_image_extension

    if read_toc:
        data.toc = _discover_toc(zf, opf_xmldoc, opf_filepath)

    return data

Response: Read the metadata from an ePub file.


Instruction:
Write a Python 3 function for
returning the file. OPF contents of the ePub file

Response:
def get_epub_opf_xml(filepath):
    '''
    Returns the file.OPF contents of the ePub file
    '''
    if not zipfile.is_zipfile(filepath):
        raise EPubException('Unknown file')

    # print('Reading ePub file: {}'.format(filepath))
    zf = zipfile.ZipFile(filepath, 'r', compression=zipfile.ZIP_DEFLATED, allowZip64=True)
    container = zf.read('META-INF/container.xml')
    container_xmldoc = minidom.parseString(container)
    # e.g.: <rootfile full-path="content.opf" media-type="application/oebps-package+xml"/>
    opf_filepath = container_xmldoc.getElementsByTagName('rootfile')[0].attributes['full-path'].value
    return zf.read(opf_filepath)


Instruction:
Can you generate the documentation for the following Python 3 function
def firstname(self, value, case, gender=None):
        if not value:
            raise ValueError('Firstname cannot be empty.')

        return self.__inflect(value, case, 'firstname', gender)

Response: Падеж для склонение имение класса Case gender Падеж для склонение к


Instruction:
Can you generate the documentation for the following Python 3 function
def lastname(self, value, case, gender=None):
        if not value:
            raise ValueError('Lastname cannot be empty.')

        return self.__inflect(value, case, 'lastname', gender)

Response: Падеж для класса Case Lastname


Instruction:
Can you generate the documentation for the following Python 3 function
def middlename(self, value, case, gender=None):
        if not value:
            raise ValueError('Middlename cannot be empty.')

        return self.__inflect(value, case, 'middlename', gender)

Response: Падеж для класса Case для класса Case


Instruction:
Write a Python 3 script for
expanding a reference expression to individual spans.

Response:
def expand(expression):
    """
    Expand a reference expression to individual spans.
    Also works on space-separated ID lists, although a sequence of space
    characters will be considered a delimiter.

    >>> expand('a1')
    'a1'
    >>> expand('a1[3:5]')
    'a1[3:5]'
    >>> expand('a1[3:5+6:7]')
    'a1[3:5]+a1[6:7]'
    >>> expand('a1 a2  a3')
    'a1 a2  a3'

    """
    tokens = []
    for (pre, _id, _range) in robust_ref_re.findall(expression):
        if not _range:
            tokens.append('{}{}'.format(pre, _id))
        else:
            tokens.append(pre)
            tokens.extend(
                '{}{}[{}:{}]'.format(delim, _id, start, end)
                for delim, start, end in span_re.findall(_range)
            )
    return ''.join(tokens)


Instruction:
Write a Python 3 script to
compress a reference expression to group spans on the same id.

Response:
def compress(expression):
    """
    Compress a reference expression to group spans on the same id.
    Also works on space-separated ID lists, although a sequence of space
    characters will be considered a delimiter.

    >>> compress('a1')
    'a1'
    >>> compress('a1[3:5]')
    'a1[3:5]'
    >>> compress('a1[3:5+6:7]')
    'a1[3:5+6:7]'
    >>> compress('a1[3:5]+a1[6:7]')
    'a1[3:5+6:7]'
    >>> compress('a1 a2  a3')
    'a1 a2  a3'

    """
    tokens = []
    selection = []
    last_id = None
    for (pre, _id, _range) in robust_ref_re.findall(expression):
        if _range and _id == last_id:
            selection.extend([pre, _range])
            continue
        if selection:
            tokens.extend(selection + [']'])
            selection = []
        tokens.extend([pre, _id])
        if _range:
            selection = ['[', _range]
            last_id = _id
        else:
            last_id = None
    if selection:
        tokens.extend(selection + [']'])
    return ''.join(tokens)


Instruction:
Create a Python 3 function to
split the expression into individual selection expressions.

Response:
def selections(expression, keep_delimiters=True):
    """
    Split the expression into individual selection expressions. The
    delimiters will be kept as separate items if keep_delimters=True.
    Also works on space-separated ID lists, although a sequence of space
    characters will be considered a delimiter.

    >>> selections('a1')
    ['a1']
    >>> selections('a1[3:5]')
    ['a1[3:5]']
    >>> selections('a1[3:5+6:7]')
    ['a1[3:5+6:7]']
    >>> selections('a1[3:5+6:7]+a2[1:4]')
    ['a1[3:5+6:7]', '+', 'a2[1:4]']
    >>> selections('a1[3:5+6:7]+a2[1:4]', keep_delimiters=False)
    ['a1[3:5+6:7]', 'a2[1:4]']
    >>> selections('a1 a2  a3')
    ['a1', ' ', 'a2', '  ', 'a3']

    """
    tokens = []
    for (pre, _id, _range) in robust_ref_re.findall(expression):
        if keep_delimiters and pre:
            tokens.append(pre)
        if _id:
            if _range:
                tokens.append('{}[{}]'.format(_id, _range))
            else:
                tokens.append(_id)
    return tokens


Instruction:
How would you implement a function in Python 3 that
returns the string that is the resolution of the alignment expression expression which selects ids from container.

Response:
def resolve(container, expression):
    """
    Return the string that is the resolution of the alignment expression
    `expression`, which selects ids from `container`.
    """
    itemgetter = getattr(container, 'get_item', container.get)
    tokens = []
    expression = expression.strip()
    for sel_delim, _id, _range in selection_re.findall(expression):
        tokens.append(delimiters.get(sel_delim, ''))
        item = itemgetter(_id)
        if item is None:
            raise XigtStructureError(
                'Referred Item (id: {}) from reference "{}" does not '
                'exist in the given container.'
                .format(_id, expression)
            )
        # treat None values as empty strings for resolution
        value = item.value() or ''
        if _range:
            for spn_delim, start, end in span_re.findall(_range):
                start = int(start) if start else None
                end = int(end) if end else None
                tokens.extend([
                    delimiters.get(spn_delim, ''),
                    value[start:end]
                ])
        else:
            tokens.append(value)
    return ''.join(tokens)


Instruction:
Can you create a Python 3 function that
returns a list of ids denoting objects in igt that are referred by id.

Response:
def referents(igt, id, refattrs=None):
    """
    Return a list of ids denoting objects (tiers or items) in `igt` that
    are referred by the object denoted by `id` using a reference
    attribute in `refattrs`. If `refattrs` is None, then consider all
    known reference attributes for the type of object denoted by _id_.
    In other words, if 'b1' refers to 'a1' using 'alignment', then
    `referents(igt, 'b1', ['alignment'])` returns `['a1']`.
    """
    obj = igt.get_any(id)
    if obj is None:
        raise XigtLookupError(id)
    if refattrs is None:
        refattrs = obj.allowed_reference_attributes()
    return {ra: ids(obj.attributes.get(ra, '')) for ra in refattrs}


Instruction:
Here you have a function in Python 3, explain what it does
def referrers(igt, id, refattrs=None):
    if refattrs is None:
        result = {}
    else:
        result = {ra: [] for ra in refattrs}

    # if the id is a tier, only look at tiers; otherwise only look at items
    try:
        obj = igt[id]
        others = igt.tiers
    except KeyError:
        obj = igt.get_item(id)
        others = [i for t in igt.tiers for i in t.items]

    if obj is None:
        raise XigtLookupError(id)

    for other in others:
        if other.id is None:
            continue  # raise a warning?

        _refattrs = refattrs
        if _refattrs is None:
            _refattrs = other.allowed_reference_attributes()

        attrget = other.attributes.get  # just loop optimization
        for ra in _refattrs:
            result.setdefault(ra, [])
            if id in ids(attrget(ra, '')):
                result[ra].append(other.id)
    return result

Response: Return a list of ids denoting objects in igt that refer to the given id.


Instruction:
Here you have a function in Python 3, explain what it does
def ancestors(obj, refattrs=(ALIGNMENT, SEGMENTATION)):
    if hasattr(obj, 'tier'):
        tier = obj.tier
        items = [obj]
    else:
        tier = obj
        items = tier.items
    # a tier may be visited twice (e.g. A > B > A), but then it stops;
    # this is to avoid cycles
    visited = set([tier.id])
    while True:
        # get the first specified attribute
        refattr = next((ra for ra in refattrs if ra in tier.attributes), None)
        if not refattr:
            break
        reftier = ref.dereference(tier, refattr)
        ids = set(chain.from_iterable(
            ref.ids(item.attributes.get(refattr, '')) for item in items
        ))
        refitems = [item for item in reftier.items if item.id in ids]
        yield (tier, refattr, reftier, refitems)
        # cycle detection; break if we've now encountered something twice
        if reftier.id in visited:
            break
        visited.update(reftier.id)
        tier = reftier
        items = refitems

Response: get ancestors of an item


Instruction:
How would you implement a function in Python 3 that
gets the list of descendants of an item

Response:
def descendants(obj, refattrs=(SEGMENTATION, ALIGNMENT), follow='first'):
    """
    >>> for des in query.descendants(igt.get_item('p1'), refattrs=(SEGMENTATION, ALIGNMENT)):
    ...     print(des)
    (<Tier object (id: p type: phrases) at ...>, 'segmentation', <Tier object (id: w type: words) at ...>, [<Item object (id: w1) at ...>])
    (<Tier object (id: p type: phrases) at ...>, 'alignment', <Tier object (id: t type: translations) at ...>, [<Item object (id: t1) at ...>])
    (<Tier object (id: w type: words) at ...>, 'segmentation', <Tier object (id: m type: morphemes) at ...>, [<Item object (id: m1) at ...>])
    (<Tier object (id: m type: morphemes) at ...>, 'alignment', <Tier object (id: g type: glosses) at ...>, [<Item object (id: g1) at ...>])
    """

    if hasattr(obj, 'tier'):
        tier = obj.tier
        items = [obj]
    else:
        tier = obj
        items = tier.items
    igt = tier.igt
    visited = set()
    agenda = deque([(tier, items)])
    while agenda:
        tier, items = agenda.popleft()
        tier_refs = tier.referrers(refattrs)
        item_ids = set(item.id for item in items)
        # get followable refattrs with something on the referrers list
        ras = [ra for ra in refattrs if tier_refs[ra]]
        if follow == 'first' and ras:
            ras = [ras[0]]
        if not ras:
            continue
        # unlike ancestors, descendants for a refattr may have 1+ tiers
        for refattr in ras:
            # try to avoid cycles
            if (tier.id, refattr) in visited:
                continue
            else:
                visited.add((tier.id, refattr))
            for reftier_id in tier_refs[refattr]:
                reftier = igt[reftier_id]
                refitems = [
                    item for item in reftier.items
                    if set(ref.ids(item.attributes.get(refattr,'')))
                       .intersection(item_ids)
                ]
                yield (tier, refattr, reftier, refitems)
                agenda.append((reftier, refitems))


Instruction:
Create a Python 3 function to
decode a XigtCorpus element.

Response:
def default_decode(events, mode='full'):
    """Decode a XigtCorpus element."""
    event, elem = next(events)
    root = elem  # store root for later instantiation
    while (event, elem.tag) not in [('start', 'igt'), ('end', 'xigt-corpus')]:
        event, elem = next(events)
    igts = None
    if event == 'start' and elem.tag == 'igt':
        igts = (
            decode_igt(e)
            for e in iter_elements(
                'igt', events, root, break_on=[('end', 'xigt-corpus')]
            )
        )
    xc = decode_xigtcorpus(root, igts=igts, mode=mode)
    return xc


Instruction:
Here you have a function in Python 3, explain what it does
def _get_file_content(source):
    filepath = os.path.join('siglists', source + '.txt')

    lines = []
    with resource_stream(__name__, filepath) as f:
        for i, line in enumerate(f):
            line = line.decode('utf-8', 'strict').strip()
            if not line or line.startswith('#'):
                continue

            try:
                re.compile(line)
            except Exception as ex:
                raise BadRegularExpressionLineError(
                    'Regex error: {} in file {} at line {}'.format(
                        str(ex),
                        filepath,
                        i
                    )
                )

            lines.append(line)

    if source in _SPECIAL_EXTENDED_VALUES:
        lines = lines + _SPECIAL_EXTENDED_VALUES[source]

    return tuple(lines)

Response: Return a tuple each value being a line of the source file.


Instruction:
Can you create a Python 3 function that
checks quickly whether file is rar archive.

Response:
def _get_rar_version(xfile):
    """Check quickly whether file is rar archive.
    """
    buf = xfile.read(len(RAR5_ID))
    if buf.startswith(RAR_ID):
        return 3
    elif buf.startswith(RAR5_ID):
        xfile.read(1)
        return 5
    return 0


Instruction:
Can you write a function in Python 3 where it
proceeds to next volume.

Response:
def _open_next(self):
        """Proceed to next volume."""

        # is the file split over archives?
        if (self._cur.flags & rarfile.RAR_FILE_SPLIT_AFTER) == 0:
            return False

        if self._fd:
            self._fd.close()
            self._fd = None

        # open next part
        self._volfile = self._parser._next_volname(self._volfile)
        fd = rarfile.XFile(self._volfile)
        self._fd = fd
        sig = fd.read(len(self._parser._expect_sig))
        if sig != self._parser._expect_sig:
            raise rarfile.BadRarFile("Invalid signature")

        # loop until first file header
        while 1:
            cur = self._parser._parse_header(fd)
            if not cur:
                raise rarfile.BadRarFile("Unexpected EOF")
            if cur.type in (rarfile.RAR_BLOCK_MARK, rarfile.RAR_BLOCK_MAIN):
                if cur.add_size:
                    fd.seek(cur.add_size, 1)
                continue
            if cur.orig_filename != self._inf.orig_filename:
                raise rarfile.BadRarFile("Did not found file entry")
            self._cur = cur
            self._cur_avail = cur.add_size
            return True


Instruction:
Can you generate the documentation for the following Python 3 function
def _check(self): # TODO: fix?
        if self._returncode:
            rarfile.check_returncode(self, '')
        if self._remain != 0:
            raise rarfile.BadRarFile("Failed the read enough data")

Response: Check CRC and return code.


Instruction:
Can you create a Python 3 function that
returns a matrix that contains RGB channels and colors scaled by 0 to 255

Response:
def to_24bit_gray(mat: np.ndarray):
    """returns a matrix that contains RGB channels, and colors scaled
    from 0 to 255"""
    return np.repeat(np.expand_dims(_normalize(mat), axis=2), 3, axis=2)


Instruction:
How would you explain what the following Python 3 function does
def apply_color_map(name: str, mat: np.ndarray = None):
    def apply_map(mat):
        return (cm.get_cmap(name)(_normalize(mat))[:, :, :3] * 255).astype(np.uint8)

    return apply_map if mat is None else apply_map(mat)

Response: returns an RGB matrix scaled by a matplotlib color map


Instruction:
How would you implement a function in Python 3 that
converts a 2d numpy array to a pygame. Surface

Response:
def mat_to_surface(mat: np.ndarray, transformer=to_24bit_gray):
    """Can be used to create a pygame.Surface from a 2d numpy array.

    By default a grey image with scaled colors is returned, but using the
    transformer argument any transformation can be used.

    :param mat: the matrix to create the surface of.
    :type mat: np.ndarray

    :param transformer: function that transforms the matrix to a valid color
        matrix, i.e. it must have 3dimension, were the 3rd dimension are the color
        channels. For each channel a value between 0 and 255 is allowed
    :type transformer: Callable[np.ndarray[np.ndarray]]"""

    return pygame.pixelcopy.make_surface(transformer(mat.transpose())
        if transformer is not None else mat.transpose())


Instruction:
Make a summary of the following Python 3 code
def random_id(length=16, charset=alphanum_chars, first_charset=alpha_chars, sep='', group=0):
    t = []

    first_chars = list(set(charset).intersection(first_charset))
    if len(first_chars) == 0:
        first_chars = charset

    t.append(first_chars[random.randrange(len(first_chars))])

    for i in range(len(t), length):
        if (group > 0) and (i % group == 0) and (i < length):
            t.append(sep)
        t.append(charset[random.randrange(len(charset))])

    return ''.join(t)

Response: Creates a random id with the given length and charset.


Instruction:
Can you implement a function in Python 3 that
merges any number of dictionaries with the given ones.

Response:
def merge_dict(data, *args):
    """Merge any number of dictionaries
    """
    results = {}
    for current in (data,) + args:
        results.update(current)
    return results


Instruction:
Write a Python 3 function that can
join individual URL strings together and returns a single string.

Response:
def make_url(url, *paths):
    """Joins individual URL strings together, and returns a single string.
    """
    for path in paths:
        url = re.sub(r'/?$', re.sub(r'^/?', '/', path), url)
    return url


Instruction:
Can you implement a function in Python 3 that
aggregates result for all servers.

Response:
def aggregate_result(self, return_code, output, service_description='', specific_servers=None):
        '''
        aggregate result
        '''
        if specific_servers == None:
            specific_servers = self.servers
        else:
            specific_servers = set(self.servers).intersection(specific_servers)

        for server in specific_servers:
            if not self.servers[server]['send_errors_only'] or return_code > 0:
                self.servers[server]['results'].append({'return_code': return_code,
                           'output': output,
                           'service_description': service_description,
                           'return_status': STATUSES[return_code][0],
                           'custom_fqdn': self.servers[server]['custom_fqdn']})
                LOG.info("[email][%s][%s]: Aggregate result: %r", service_description, server, self.servers[server]['results'][-1])


Instruction:
Write a Python 3 script for
sending results to all servers

Response:
def send_results(self):
        '''
        send results
        '''

        for server in self.servers:
            if self.servers[server]['results']:
                if len(self.servers[server]['results']) == 1:
                    msg = MIMEText('')
                    msg['Subject'] = '[%(custom_fqdn)s] [%(service_description)s] %(return_status)s: %(output)s' % self.servers[server]['results'][0]
                else:
                    txt = ''
                    summary = [0, 0, 0, 0]
                    for results in self.servers[server]['results']:
                        txt += '[%(service_description)s] %(return_status)s: %(output)s\n' % results
                        summary[results['return_code']] += 1
                    msg = MIMEText(txt)
                    subject = '[%(custom_fqdn)s]' % self.servers[server]['results'][0]
                    for i, status in enumerate(STATUSES):
                        subject += ' %s:%s' % (status[0], summary[i])
                    msg['Subject'] = subject

                msg['From'] = self.servers[server]['from']
                msg['To'] = ', '.join(self.servers[server]['to'])
                if self.servers[server]['tls']:
                    smtp_server = smtplib.SMTP_SSL(self.servers[server]['host'], self.servers[server]['port'])
                else:
                    smtp_server = smtplib.SMTP(self.servers[server]['host'], self.servers[server]['port'])

                if self.servers[server]['login'] and len(self.servers[server]['login']) > 0:
                    smtp_server.login(self.servers[server]['login'], self.servers[server]['password'])
                smtp_server.sendmail(self.servers[server]['from'], self.servers[server]['to'], msg.as_string())
                smtp_server.quit()
                LOG.info("[email][%s]: e-mail sent from: %s to: %s", server, self.servers[server]['from'], self.servers[server]['to'])


Instruction:
Can you generate the documentation for the following Python 3 function
def main():
    config = {
        "api": {
            "services": [
                {
                    "name": "my_api",
                    "testkey": "testval",
                },
            ],
            "calls": {
                "hello_world": {
                    "delay": 5,
                    "priority": 1,
                    "arguments": None,
                },
                "marco": {
                    "delay": 1,
                    "priority": 1,
                },
                "pollo": {
                    "delay": 1,
                    "priority": 1,
                },
            }
        }
    }
    app = AppBuilder([MyAPI], Strategy(Print()), AppConf(config))
    app.run()

Response: Main function for the main function of the main function.


Instruction:
How would you code a function in Python 3 to
make a request from the incoming data

Response:
def make_request(self, data):
        """Parse the outgoing schema"""
        sch = MockItemSchema()
        return Request(**{
            "callname": self.context.get("callname"),
            "payload": sch.dump(data),
        })


Instruction:
How would you code a function in Python 3 to
populate the result with the data from the incoming data.

Response:
def populate_data(self, data):
        """Parse the outgoing schema"""
        sch = MockItemSchema()
        return Result(**{
            "callname": self.context.get("callname"),
            "result": sch.dump(data),
        })


Instruction:
Can you generate the documentation for the following Python 3 function
def key_press(keys):
        return lambda e: e.key if e.type == pygame.KEYDOWN \
            and e.key in keys else EventConsumerInfo.DONT_CARE

Response: returns a handler that can be used with EventListener. listen()


Instruction:
Here you have a function in Python 3, explain what it does
def unicode_char(ignored_chars=None):
        return lambda e: e.unicode if e.type == pygame.KEYDOWN \
            and ((ignored_chars is None)
                  or (e.unicode not in ignored_chars))\
            else EventConsumerInfo.DONT_CARE

Response: returns a handler that listens for unicode characters


Instruction:
Here you have a function in Python 3, explain what it does
def mouse_area(self, handler, group=0, ident=None):
        key = ident or id(handler)
        if key not in self.mouse_proxies[group]:
            self.mouse_proxies[group][key] = MouseProxy(handler, ident)
        return self.mouse_proxies[group][key]

Response:
Adds a new MouseProxy for the given group to the
        EventListener. mouse_proxies dict.


Instruction:
Write a Python 3 script for
calling listen repeatedly until listen returns something else than None. Then returns None.

Response:
def listen_until_return(self, *temporary_handlers, timeout=0):
        """Calls listen repeatedly until listen returns something else than None.
        Then returns listen's result. If timeout is not zero listen_until_return
        stops after timeout seconds and returns None."""
        start = time.time()
        while timeout == 0 or time.time() - start < timeout:
            res = self.listen(*temporary_handlers)
            if res is not None:
                return res


Instruction:
Write a Python 3 script to
wait till one key was pressed n times.

Response:
def wait_for_n_keypresses(self, key, n=1):
        """Waits till one key was pressed n times.

        :param key: the key to be pressed as defined by pygame. E.g.
            pygame.K_LEFT for the left arrow key
        :type key: int
        :param n: number of repetitions till the function returns
        :type n: int
        """
        my_const = "key_consumed"
        counter = 0

        def keypress_listener(e): return my_const \
            if e.type == pygame.KEYDOWN and e.key == key \
            else EventConsumerInfo.DONT_CARE

        while counter < n:
            if self.listen(keypress_listener) == my_const:
                counter += 1


Instruction:
Can you generate the documentation for the following Python 3 function
def wait_for_keys(self, *keys, timeout=0):
        if len(keys) == 1 and _is_iterable(keys[0]):
            keys = keys[0]

        return self.listen_until_return(Handler.key_press(keys), timeout=timeout)

Response:
Waits until one of the specified keys was pressed and returns
        which key was pressed.


Instruction:
How would you implement a function in Python 3 that
waits until a single character is pressed in the specified list of ignored_chars.

Response:
def wait_for_unicode_char(self, ignored_chars=None, timeout=0):
        """Returns a str that contains the single character that was pressed.
        This already respects modifier keys and keyboard layouts. If timeout is
        not none and no key is pressed within the specified timeout, None is
        returned. If a key is ingnored_chars it will be ignored. As argument for
        irgnored_chars any object that has a __contains__ method can be used,
        e.g. a string, a set, a list, etc"""
        return  self.listen_until_return(Handler.unicode_char(ignored_chars),
                                        timeout=timeout)


Instruction:
Can you generate a brief explanation for the following Python 3 code
def _find_all_first_files(self, item):
        for listed_item in item.list():
            new_style = re.findall(r'(?i)\.part(\d+)\.rar^', listed_item.id)
            if new_style:
                if int(new_style[0]) == 1:
                    yield 'new', listed_item
            elif listed_item.id.lower().endswith('.rar'):
                yield 'old', listed_item

Response: Yields all the first files in the item.


Instruction:
Implement a function in Python 3 to
find all matching data files in search_path

Response:
def find_datafile(name, search_path, codecs=get_codecs()):
    """
    find all matching data files in search_path
    search_path: path of directories to load from
    codecs: allow to override from list of installed
    returns array of tuples (codec_object, filename)
    """
    return munge.find_datafile(name, search_path, codecs)


Instruction:
Here you have a function in Python 3, explain what it does
def load_datafile(name, search_path, codecs=get_codecs(), **kwargs):
    return munge.load_datafile(name, search_path, codecs, **kwargs)

Response: load datafile from codec


Instruction:
Make a summary of the following Python 3 code
def cred_init(
            self,
            *,
            secrets_dir: str,
            log: Logger,
            bot_name: str,
    ) -> None:
        """
        Initialize what requires credentials/secret files.

        :param secrets_dir: dir to expect credentials in and store logs/history in.
        :param log: logger to use for log output.
        :param bot_name: name of this bot,
            used for various kinds of labelling.
        :returns: none.
        """
        super().__init__(secrets_dir=secrets_dir, log=log, bot_name=bot_name)

        self.ldebug("Retrieving CONSUMER_KEY...")
        with open(path.join(self.secrets_dir, "CONSUMER_KEY")) as f:
            CONSUMER_KEY = f.read().strip()

        self.ldebug("Retrieving CONSUMER_SECRET...")
        with open(path.join(self.secrets_dir, "CONSUMER_SECRET")) as f:
            CONSUMER_SECRET = f.read().strip()

        self.ldebug("Retrieving ACCESS_TOKEN...")
        with open(path.join(self.secrets_dir, "ACCESS_TOKEN")) as f:
            ACCESS_TOKEN = f.read().strip()

        self.ldebug("Retrieving ACCESS_SECRET...")
        with open(path.join(self.secrets_dir, "ACCESS_SECRET")) as f:
            ACCESS_SECRET = f.read().strip()

        self.ldebug("Looking for OWNER_HANDLE...")
        owner_handle_path = path.join(self.secrets_dir, "OWNER_HANDLE")
        if path.isfile(owner_handle_path):
            with open(owner_handle_path) as f:
                self.owner_handle = f.read().strip()
        else:
            self.ldebug("Couldn't find OWNER_HANDLE, unable to DM...")
            self.owner_handle = ""

        self.auth = tweepy.OAuthHandler(CONSUMER_KEY, CONSUMER_SECRET)
        self.auth.set_access_token(ACCESS_TOKEN, ACCESS_SECRET)

        self.api = tweepy.API(self.auth)

Response: Initialize what requires credentials and secret files.


Instruction:
Explain what the following Python 3 code does
def send(
            self,
            *,
            text: str,
    ) -> List[OutputRecord]:
        """
        Send birdsite message.

        :param text: text to send in post.
        :returns: list of output records,
            each corresponding to either a single post,
            or an error.
        """
        try:
            status = self.api.update_status(text)
            self.ldebug(f"Status object from tweet: {status}.")
            return [TweetRecord(record_data={"tweet_id": status._json["id"], "text": text})]

        except tweepy.TweepError as e:
            return [self.handle_error(
                message=(f"Bot {self.bot_name} encountered an error when "
                 f"sending post {text} without media:\n{e}\n"),
                error=e)]

Response: Send a message to a specific birdsite.


Instruction:
Make a summary of the following Python 3 code
def send_with_media(
            self,
            *,
            text: str,
            files: List[str],
            captions: List[str]=[]
    ) -> List[OutputRecord]:
        """
        Upload media to birdsite,
        and send status and media,
        and captions if present.

        :param text: tweet text.
        :param files: list of files to upload with post.
        :param captions: list of captions to include as alt-text with files.
        :returns: list of output records,
            each corresponding to either a single post,
            or an error.
        """

        # upload media
        media_ids = None
        try:
            self.ldebug(f"Uploading files {files}.")
            media_ids = [self.api.media_upload(file).media_id_string for file in files]
        except tweepy.TweepError as e:
            return [self.handle_error(
                message=f"Bot {self.bot_name} encountered an error when uploading {files}:\n{e}\n",
                error=e)]

        # apply captions, if present
        self._handle_caption_upload(media_ids=media_ids, captions=captions)

        # send status
        try:
            status = self.api.update_status(status=text, media_ids=media_ids)
            self.ldebug(f"Status object from tweet: {status}.")
            return [TweetRecord(record_data={
                "tweet_id": status._json["id"],
                "text": text,
                "media_ids": media_ids,
                "captions": captions,
                "files": files
            })]

        except tweepy.TweepError as e:
            return [self.handle_error(
                message=(f"Bot {self.bot_name} encountered an error when "
                 f"sending post {text} with media ids {media_ids}:\n{e}\n"),
                error=e)]

Response: Uploads media to birdsite and sends status and media and captions to post.


Instruction:
How would you code a function in Python 3 to
perform a batch reply on the target account.

Response:
def perform_batch_reply(
            self,
            *,
            callback: Callable[..., str],
            lookback_limit: int,
            target_handle: str,
    ) -> List[OutputRecord]:
        """
        Performs batch reply on target account.
        Looks up the recent messages of the target user,
        applies the callback,
        and replies with
        what the callback generates.

        :param callback: a callback taking a message id,
            message contents,
            and optional extra keys,
            and returning a message string.
        :param target: the id of the target account.
        :param lookback_limit: a lookback limit of how many messages to consider.
        :returns: list of output records,
            each corresponding to either a single post,
            or an error.
        """
        self.log.info(f"Attempting to batch reply to birdsite user {target_handle}")

        if "@" in target_handle:
            base_target_handle = target_handle[1:]
        else:
            base_target_handle = target_handle

        records: List[OutputRecord] = []
        statuses = self.api.user_timeline(screen_name=base_target_handle, count=lookback_limit)
        self.log.debug(f"Retrieved {len(statuses)} statuses.")
        for i, status in enumerate(statuses):
            self.log.debug(f"Processing status {i} of {len(statuses)}")
            status_id = status.id

            # find possible replies we've made.
            # the 10 * lookback_limit is a guess,
            # might not be enough and I'm not sure we can guarantee it is.
            our_statuses = self.api.user_timeline(since_id=status_id,
                                                  count=lookback_limit * 10)
            in_reply_to_ids = list(map(lambda x: x.in_reply_to_status_id, our_statuses))

            if status_id not in in_reply_to_ids:
                # the twitter API and tweepy will attempt to give us the truncated text of the
                # message if we don't do this roundabout thing.
                encoded_status_text = self.api.get_status(status_id,
                                                  tweet_mode="extended")._json["full_text"]

                status_text = html.unescape(encoded_status_text)
                message = callback(message_id=status_id, message=status_text, extra_keys={})

                full_message = f"@{base_target_handle} {message}"
                self.log.info(f"Trying to reply with {message} to status {status_id} "
                              f"from {target_handle}.")
                try:
                    new_status = self.api.update_status(status=full_message,
                                                        in_reply_to_status_id=status_id)

                    records.append(TweetRecord(record_data={
                        "tweet_id": new_status.id,
                        "in_reply_to": f"@{base_target_handle}",
                        "in_reply_to_id": status_id,
                        "text": full_message,
                    }))

                except tweepy.TweepError as e:
                    records.append(self.handle_error(
                        message=(f"Bot {self.bot_name} encountered an error when "
                         f"trying to reply to {status_id} with {message}:\n{e}\n"),
                        error=e))
            else:
                self.log.info(f"Not replying to status {status_id} from {target_handle} "
                              f"- we already replied.")

        return records


Instruction:
Implement a function in Python 3 to
send DM to owner if something happens.

Response:
def send_dm_sos(self, message: str) -> None:
        """
        Send DM to owner if something happens.

        :param message: message to send to owner.
        :returns: None.
        """
        if self.owner_handle:
            try:
                # twitter changed the DM API and tweepy (as of 2019-03-08)
                # has not adapted.
                # fixing with
                # https://github.com/tweepy/tweepy/issues/1081#issuecomment-423486837
                owner_id = self.api.get_user(screen_name=self.owner_handle).id
                event = {
                    "event": {
                        "type": "message_create",
                        "message_create": {
                            "target": {
                                "recipient_id": f"{owner_id}",
                            },
                            "message_data": {
                                "text": message
                            }
                        }
                    }
                }

                self._send_direct_message_new(event)

            except tweepy.TweepError as de:
                self.lerror(f"Error trying to send DM about error!: {de}")

        else:
            self.lerror("Can't send DM SOS, no owner handle.")


Instruction:
Can you generate the documentation for the following Python 3 function
def handle_error(
            self,
            *,
            message: str,
            error: tweepy.TweepError,
    ) -> OutputRecord:
        """
        Handle error while trying to do something.

        :param message: message to send in DM regarding error.
        :param e: tweepy error object.
        :returns: OutputRecord containing an error.
        """
        self.lerror(f"Got an error! {error}")

        # Handle errors if we know how.
        try:
            code = error[0]["code"]
            if code in self.handled_errors:
                self.handled_errors[code]
            else:
                self.send_dm_sos(message)

        except Exception:
            self.send_dm_sos(message)

        return TweetRecord(error=error)

Response: Handle an error while trying to do something.


Instruction:
How would you explain what the following Python 3 function does
def _handle_caption_upload(
            self,
            *,
            media_ids: List[str],
            captions: Optional[List[str]],
    ) -> None:
        """
        Handle uploading all captions.

        :param media_ids: media ids of uploads to attach captions to.
        :param captions: captions to be attached to those media ids.
        :returns: None.
        """
        if captions is None:
            captions = []

        if len(media_ids) > len(captions):
            captions.extend([self.default_caption_message] * (len(media_ids) - len(captions)))

        for i, media_id in enumerate(media_ids):
            caption = captions[i]
            self._upload_caption(media_id=media_id, caption=caption)

Response:
Handle uploading all captions.

        :param media_ids: media ids of uploads to attach captions to.
        :param captions: captions to be attached to those media ids.
        :returns: None.


Instruction:
Implement a Python 3 function for
sending a new message to the direct message queue.

Response:
def _send_direct_message_new(self, messageobject: Dict[str, Dict]) -> Any:
        """
        :reference: https://developer.twitter.com/en/docs/direct-messages/sending-and-receiving/api-reference/new-event.html
        """
        headers, post_data = _buildmessageobject(messageobject)
        newdm_path = "/direct_messages/events/new.json"

        return tweepy.binder.bind_api(
            api=self.api,
            path=newdm_path,
            method="POST",
            require_auth=True,
        )(post_data=post_data, headers=headers)


Instruction:
Can you tell what is the following Python 3 function doing
def main():
    parser = argparse.ArgumentParser(description=DESCRIPTION)
    parser.add_argument(
        '-v', '--verbose', help='increase output verbosity', action='store_true'
    )
    args = parser.parse_args()

    generator = SignatureGenerator(debug=args.verbose)

    crash_data = json.loads(sys.stdin.read())

    ret = generator.generate(crash_data)

    print(json.dumps(ret, indent=2))

Response: Takes crash data via stdin and generates a Socorro signature


Instruction:
How would you explain what the following Python 3 function does
def add_config(self, config):
        for attr in self.__fixed_attrs:
            if attr in config:
                raise Exception("cannot set '%s' outside of init", attr)

        # pre checkout

        stages = config.get('stages', None)
        if stages:
            self.stages = stages

        # maybe pre checkout

        # validate options
        self.__dry_run = config.get('dry_run', False)

        self.system = str.lower(platform.system())

        self.__start = config.get('start', None)
        self.__end = config.get('end', None)
        self.__only = config.get('only', None)

        self.__build_docs = config.get('build_docs', False)
        self.__chatty = config.get('chatty', False)
        self.__clean = config.get('clean', False)
        self.__devel = config.get('devel', False)
        self.__debug = config.get('debug', False)
        self.__skip_libcheck = config.get('skip_libcheck', False)
        self.__debuginfo = config.get('debuginfo', False)
        self.__release = config.get('release', False)
        self.__skip_unit = config.get('skip_unit', False)
        self.__static = config.get('static', False)
        self.__make_dash_j = int(config.get('j', 0))
        self.__target_only = config.get('target_only', None)

        bits = config.get('bits', None)
        if bits:
            self.bits = int(bits)
        else:
            self.bits = self.sys_bits

        self.compiler = config.get('compiler', None)
        self.test_config = config.get('test_config', '-')
        if not self.test_config:
            self.test_config = '-'
        self.use_ccache = config.get('use_ccache', False)
        self.tmpl_engine = config.get('tmpl_engine', 'jinja2')
        self.__write_codec = config.get('write_codec', None)
        self.__codec = None

        # TODO move out of init
        if not config.get('skip_env_check', False):
            if "LD_LIBRARY_PATH" in os.environ:
                raise Exception("environment variable LD_LIBRARY_PATH is set")

        self.check_config()

Response: Add a configuration dict to the internal configuration dict.


Instruction:
Can you generate the documentation for the following Python 3 function
def check_config(self):

        # sanity checks - no config access past here
        if not getattr(self, 'stages', None):
            raise NotImplementedError("member variable 'stages' must be defined")
        # start at stage
        if self.__start:
            self.__stage_start = self.find_stage(self.__start)
        else:
            self.__stage_start = 0
        # end at stage
        if self.__end:
            self.__stage_end = self.find_stage(self.__end) + 1
            self.opt_end = self.__end
        else:
            self.__stage_end = len(self.stages)
        # only stage
        if self.__only:
            if self.__start or self.__end:
                raise Exception(
                    "stage option 'only' cannot be used with start or end")
            self.__stage_start = self.find_stage(self.__only)
            self.__stage_end = self.__stage_start + 1

        if self.__devel:
            self.__devel = True
            # force deploy skip
            if self.__stage_end >= len(self.stages):
                self.status_msg("removing deploy stage for development build")
# XXX                self.__stage_end = self.__stage_end - 1

        if self.stage_start >= self.stage_end:
            raise Exception("start and end produce no stages")

        if self.bits not in [32, 64]:
            raise Exception(
                "can't do a %d bit build: unknown build process" % self.bits)

        if self.bits == 64 and not self.is_64b:
            raise Exception(
                "this machine is not 64 bit, cannot perform 64 bit build")

        if self.system == 'windows':
            self.compilertag = 'vc10'
        elif self.system == 'linux':
            self.compilertag = 'gcc44'
        else:
            raise RuntimeError("can't decide compilertag on " + self.system)

        self.build_suffix = ''
        if not self.is_unixy:
            if self.__static:
                runtime = 'MT'
            else:
                runtime = 'MD'
            if self.__release:
                self.configuration_name = 'Release'
            else:
                runtime += 'd'
                self.configuration_name = 'Debug'

            self.build_suffix = '-' + runtime
            self.runtime = runtime
        else:
            self.configuration_name = 'CFNAME_INVALID_ON_LINUX'
            self.runtime = 'RUNTIME_INVALID_ON_LINUX'

        if self.test_config != '-':
            self.test_config = os.path.abspath(self.test_config)

        # split version
        if self.version:
            ver = self.version.split('.')
            self.version_major = int(ver[0])
            self.version_minor = int(ver[1])
            self.version_patch = int(ver[2])
            if(len(ver) == 4):
                self.version_build = int(ver[3])

Response: check the config for sanity checks


Instruction:
Can you implement a function in Python 3 that
checks if the definition of a class is valid

Response:
def check_definition(self):
        """
        called after Defintion was loaded to sanity check
        raises on error
        """
        if not self.write_codec:
            self.__write_codec = self.defined.data_ext

        # TODO need to add back a class scope target limited for subprojects with sub target sets
        targets = self.get_defined_targets()
        if self.__target_only:
            if self.__target_only not in targets:
                raise RuntimeError("invalid target '%s'" % self.__target_only)

            self.targets = [self.__target_only]
        else:
            self.targets = targets


Instruction:
How would you implement a function in Python 3 that
finds all matching data files in search_path returns array of tuples

Response:
def find_datafile(self, name, search_path=None):
        """
        find all matching data files in search_path
        returns array of tuples (codec_object, filename)
        """
        if not search_path:
            search_path = self.define_dir

        return codec.find_datafile(name, search_path)


Instruction:
Write a Python 3 script to
load a datafile from the codec

Response:
def load_datafile(self, name, search_path=None, **kwargs):
        """
        find datafile and load them from codec
        """
        if not search_path:
            search_path = self.define_dir

        self.debug_msg('loading datafile %s from %s' % (name, str(search_path)))
        return codec.load_datafile(name, search_path, **kwargs)


Instruction:
How would you implement a function in Python 3 that
runs all configured stages

Response:
def run(self):
        """ run all configured stages """

        self.sanity_check()

# TODO - check for devel
#        if not self.version:
#            raise Exception("no version")
# XXX check attr exist
        if not self.release_environment:
            raise Exception("no instance name")

        time_start = time.time()

        cwd = os.getcwd()

        who = getpass.getuser()
        self._make_outdirs()

        append_notices = ""
        if hasattr(self, 'opt_end'):
            append_notices = ". shortened push, only to %s stage" % self.opt_end
        if self.is_devel:
            append_notices += ". devel build"
        if hasattr(self, 'append_notices'):
            append_notices += self.append_notices

        line = "%s %s %s by %s%s" % (
            sys.argv[0], self.version, self.release_environment, who, append_notices)
        b = 'deploy begin %s' % line
        e = 'deploy done %s' % line

        if self.chatty:
            self.alact(b)

        ok = False
        stage_passed = None
        try:
            for stage in self.stages[self.stage_start:self.stage_end]:
                self.debug_msg("stage %s starting" % (stage,))
                getattr(self, stage)()
                self.chdir(cwd)
                stage_passed = stage
                self.debug_msg("stage %s complete" % (stage,))
            ok = True
        finally:
            if not ok:
                if self.chatty:
                    if not stage_passed:
                        self.alact(
                            'deploy failed %s. completed no stages' % line)
                    else:
                        self.alact('deploy failed %s. completed %s' %
                                   (line, stage_passed))
        self.status_msg('[OK]')
        if self.chatty:
            self.alact('%s in %0.3f sec' % (e, time.time() - time_start))

        return 0


Instruction:
Given the following Python 3 function, write the documentation
def timestamp(dt):
	if dt.tzinfo is None:
		return time.mktime((
			dt.year, dt.month, dt.day,
			dt.hour, dt.minute, dt.second,
			-1, -1, -1)) + dt.microsecond / 1e6
	else:
		return (dt - _EPOCH).total_seconds()

Response: Return POSIX timestamp as float.


Instruction:
Can you implement a function in Python 3 that
rates limit a function.

Response:
def rate_limited(max_per_hour: int, *args: Any) -> Callable[..., Any]:
    """Rate limit a function."""
    return util.rate_limited(max_per_hour, *args)


Instruction:
Write a Python 3 script to
repair a corrupted IterationRecord with a specific known issue.

Response:
def _repair(record: Dict[str, Any]) -> Dict[str, Any]:
    """Repair a corrupted IterationRecord with a specific known issue."""
    output_records = record.get("output_records")
    if record.get("_type", None) == "IterationRecord" and output_records is not None:
        birdsite_record = output_records.get("birdsite")

        # check for the bug
        if isinstance(birdsite_record, dict) and birdsite_record.get("_type") == "IterationRecord":

            # get to the bottom of the corrupted record
            failed = False
            while birdsite_record.get("_type") == "IterationRecord":
                sub_record = birdsite_record.get("output_records")
                if sub_record is None:
                    failed = True
                    break

                birdsite_record = sub_record.get("birdsite")
                if birdsite_record is None:
                    failed = True
                    break

            if failed:
                return record

            # add type
            birdsite_record["_type"] = TweetRecord.__name__

            # lift extra keys, just in case
            if "extra_keys" in birdsite_record:
                record_extra_values = record.get("extra_keys", {})
                for key, value in birdsite_record["extra_keys"].items():
                    if key not in record_extra_values:
                        record_extra_values[key] = value

                record["extra_keys"] = record_extra_values

                del birdsite_record["extra_keys"]

            output_records["birdsite"] = birdsite_record

        # pull that correct record up to the top level, fixing corruption
        record["output_records"] = output_records

    return record


Instruction:
Make a summary of the following Python 3 code
def from_dict(cls, obj_dict: Dict[str, Any]) -> "IterationRecord":
        obj = cls()
        for key, item in obj_dict.items():
            obj.__dict__[key] = item

        return obj

Response: Get object back from dict.


Instruction:
Explain what the following Python 3 code does
def send(
            self,
            *args: str,
            text: str=None,
    ) -> IterationRecord:
        """
        Post text-only to all outputs.

        :param args: positional arguments.
            expected: text to send as message in post.
            keyword text argument is preferred over this.
        :param text: text to send as message in post.
        :returns: new record of iteration
        """
        if text is not None:
            final_text = text
        else:
            if len(args) == 0:
                raise BotSkeletonException(("Please provide text either as a positional arg or "
                                            "as a keyword arg (text=TEXT)"))
            else:
                final_text = args[0]

        # TODO there could be some annotation stuff here.
        record = IterationRecord(extra_keys=self.extra_keys)
        for key, output in self.outputs.items():
            if output["active"]:
                self.log.info(f"Output {key} is active, calling send on it.")
                entry: Any = output["obj"]
                output_result = entry.send(text=final_text)
                record.output_records[key] = output_result

            else:
                self.log.info(f"Output {key} is inactive. Not sending.")

        self.history.append(record)
        self.update_history()

        return record

Response: Send a message to all outputs.


Instruction:
Here you have a function in Python 3, explain what it does
def send_with_one_media(
            self,
            *args: str,
            text: str=None,
            file: str=None,
            caption: str=None,
    ) -> IterationRecord:
        """
        Post with one media item to all outputs.
        Provide filename so outputs can handle their own uploads.

        :param args: positional arguments.
            expected:
                text to send as message in post.
                file to be uploaded.
                caption to be paired with file.
            keyword arguments preferred over positional ones.
        :param text: text to send as message in post.
        :param file: file to be uploaded in post.
        :param caption: caption to be uploaded alongside file.
        :returns: new record of iteration
        """
        final_text = text
        if final_text is None:
            if len(args) < 1:
                raise TypeError(("Please provide either positional argument "
                                 "TEXT, or keyword argument text=TEXT"))
            else:
                final_text = args[0]

        final_file = file
        if final_file is None:
            if len(args) < 2:
                raise TypeError(("Please provide either positional argument "
                                            "FILE, or keyword argument file=FILE"))
            else:
                final_file = args[1]

        # this arg is ACTUALLY optional,
        # so the pattern is changed.
        final_caption = caption
        if final_caption is None:
            if len(args) >= 3:
                final_caption = args[2]

        # TODO more error checking like this.
        if final_caption is None or final_caption == "":
            captions:List[str] = []
        else:
            captions = [final_caption]

        record = IterationRecord(extra_keys=self.extra_keys)
        for key, output in self.outputs.items():
            if output["active"]:
                self.log.info(f"Output {key} is active, calling media send on it.")
                entry: Any = output["obj"]
                output_result = entry.send_with_media(text=final_text,
                                                      files=[final_file],
                                                      captions=captions)
                record.output_records[key] = output_result
            else:
                self.log.info(f"Output {key} is inactive. Not sending with media.")

        self.history.append(record)
        self.update_history()

        return record

Response: Post with one media item to all outputs.


Instruction:
Explain what the following Python 3 code does
def send_with_many_media(
            self,
            *args: str,
            text: str=None,
            files: List[str]=None,
            captions: List[str]=[],
    ) -> IterationRecord:
        """
        Post with several media.
        Provide filenames so outputs can handle their own uploads.

        :param args: positional arguments.
            expected:
                text to send as message in post.
                files to be uploaded.
                captions to be paired with files.
            keyword arguments preferred over positional ones.
        :param text: text to send as message in post.
        :param files: files to be uploaded in post.
        :param captions: captions to be uploaded alongside files.
        :returns: new record of iteration
        """
        if text is None:
            if len(args) < 1:
                raise TypeError(("Please provide either required positional argument "
                                 "TEXT, or keyword argument text=TEXT"))
            else:
                final_text = args[0]
        else:
            final_text = text

        if files is None:
            if len(args) < 2:
                raise TypeError(("Please provide either positional argument "
                                 "FILES, or keyword argument files=FILES"))
            else:
                final_files = list(args[1:])
        else:
            final_files = files

        # captions have never been permitted to be provided as positional args
        # (kind of backed myself into that)
        # so they just get defaulted and it's fine.

        record = IterationRecord(extra_keys=self.extra_keys)
        for key, output in self.outputs.items():
            if output["active"]:
                self.log.info(f"Output {key} is active, calling media send on it.")
                entry: Any = output["obj"]
                output_result = entry.send_with_media(text=final_text,
                                                      files=final_files,
                                                      captions=captions)
                record.output_records[key] = output_result
            else:
                self.log.info(f"Output {key} is inactive. Not sending with media.")

        self.history.append(record)
        self.update_history()

        return record

Response: Post with several media.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def perform_batch_reply(
            self,
            *,
            callback: Callable[..., str]=None,
            target_handles: Dict[str, str]=None,
            lookback_limit: int=20,
            per_service_lookback_limit: Dict[str, int]=None,
    ) -> IterationRecord:
        """
        Performs batch reply on target accounts.
        Looks up the recent messages of the target user,
        applies the callback,
        and replies with
        what the callback generates.

        :param callback: a callback taking a message id,
            message contents,
            and optional extra keys,
            and returning a message string.
        :param targets: a dictionary of service names to target handles
            (currently only one per service).
        :param lookback_limit: a lookback limit of how many messages to consider (optional).
        :param per_service_lookback: and a dictionary of service names to per-service
            lookback limits.
            takes preference over lookback_limit (optional).
        :returns: new record of iteration
        :raises BotSkeletonException: raises BotSkeletonException if batch reply fails or cannot be
            performed
        """
        if callback is None:
            raise BotSkeletonException("Callback must be provided.""")

        if target_handles is None:
            raise BotSkeletonException("Targets must be provided.""")

        if lookback_limit > self.lookback_limit:
            raise BotSkeletonException(
                f"Lookback_limit cannot exceed {self.lookback_limit}, " +
                f"but it was {lookback_limit}"
            )

        # use per-service lookback dict for convenience in a moment.
        # if necessary, use lookback_limit to fill it out.
        lookback_dict = per_service_lookback_limit
        if (lookback_dict is None):
            lookback_dict = {}

        record = IterationRecord(extra_keys=self.extra_keys)
        for key, output in self.outputs.items():
            if key not in lookback_dict:
                lookback_dict[key] = lookback_limit

            if target_handles.get(key, None) is None:
                self.log.info(f"No target for output {key}, skipping this output.")

            elif not output.get("active", False):
                self.log.info(f"Output {key} is inactive. Not calling batch reply.")

            elif output["active"]:
                self.log.info(f"Output {key} is active, calling batch reply on it.")
                entry: Any = output["obj"]
                output_result = entry.perform_batch_reply(callback=callback,
                                                          target_handle=target_handles[key],
                                                          lookback_limit=lookback_dict[key],
                                                          )
                record.output_records[key] = output_result

        self.history.append(record)
        self.update_history()

        return record

Response: Performs a batch reply on the target accounts.


Instruction:
Write a Python 3 function for
going to sleep for the duration of self. delay seconds.

Response:
def nap(self) -> None:
        """
        Go to sleep for the duration of self.delay.

        :returns: None
        """
        self.log.info(f"Sleeping for {self.delay} seconds.")
        for _ in progress.bar(range(self.delay)):
            time.sleep(1)


Instruction:
Here you have a function in Python 3, explain what it does
def store_extra_info(self, key: str, value: Any) -> None:
        self.extra_keys[key] = value

Response: Store some extra info in the messaging storage.


Instruction:
Create a Python 3 function to
store several extra keys in the messaging storage.

Response:
def store_extra_keys(self, d: Dict[str, Any]) -> None:
        """
        Store several extra values in the messaging storage.

        :param d: dictionary entry to merge with current self.extra_keys.
        :returns: None
        """
        new_dict = dict(self.extra_keys, **d)
        self.extra_keys = new_dict.copy()


Instruction:
Write a Python 3 function that can
update the history of the current message.

Response:
def update_history(self) -> None:
        """
        Update messaging history on disk.

        :returns: None
        """
        self.log.debug(f"Saving history. History is: \n{self.history}")

        jsons = []
        for item in self.history:
            json_item = item.__dict__

            # Convert sub-entries into JSON as well.
            json_item["output_records"] = self._parse_output_records(item)

            jsons.append(json_item)

        if not path.isfile(self.history_filename):
            open(self.history_filename, "a+").close()

        with open(self.history_filename, "w") as f:
            json.dump(jsons, f, default=lambda x: x.__dict__.copy(), sort_keys=True, indent=4)
            f.write("\n")


Instruction:
How would you explain what the following Python 3 function does
def load_history(self) -> List["IterationRecord"]:
        if path.isfile(self.history_filename):
            with open(self.history_filename, "r") as f:
                try:
                    dicts = json.load(f)

                except json.decoder.JSONDecodeError as e:
                    self.log.error(f"Got error \n{e}\n decoding JSON history, overwriting it.\n"
                                   f"Former history available in {self.history_filename}.bak")
                    copyfile(self.history_filename, f"{self.history_filename}.bak")
                    return []

                history: List[IterationRecord] = []
                for hdict_pre in dicts:

                    if "_type" in hdict_pre and hdict_pre["_type"] == IterationRecord.__name__:
                        # repair any corrupted entries
                        hdict = _repair(hdict_pre)
                        record = IterationRecord.from_dict(hdict)
                        history.append(record)

                    # Be sure to handle legacy tweetrecord-only histories.
                    # Assume anything without our new _type (which should have been there from the
                    # start, whoops) is a legacy history.
                    else:
                        item = IterationRecord()

                        # Lift extra keys up to upper record (if they exist).
                        extra_keys = hdict_pre.pop("extra_keys", {})
                        item.extra_keys = extra_keys

                        hdict_obj = TweetRecord.from_dict(hdict_pre)

                        # Lift timestamp up to upper record.
                        item.timestamp = hdict_obj.timestamp

                        item.output_records["birdsite"] = hdict_obj

                        history.append(item)

                self.log.debug(f"Loaded history:\n {history}")

                return history

        else:
            return []

Response: Load the history from disk to self. history_filename.


Instruction:
Create a Python 3 function to
set up all output methods.

Response:
def _setup_all_outputs(self) -> None:
        """Set up all output methods. Provide them credentials and anything else they need."""

        # The way this is gonna work is that we assume an output should be set up iff it has a
        # credentials_ directory under our secrets dir.
        for key in self.outputs.keys():
            credentials_dir = path.join(self.secrets_dir, f"credentials_{key}")

            # special-case birdsite for historical reasons.
            if key == "birdsite" and not path.isdir(credentials_dir) \
                    and path.isfile(path.join(self.secrets_dir, "CONSUMER_KEY")):
                credentials_dir = self.secrets_dir

            if path.isdir(credentials_dir):
                output_skeleton = self.outputs[key]

                output_skeleton["active"] = True

                obj: Any = output_skeleton["obj"]
                obj.cred_init(secrets_dir=credentials_dir, log=self.log, bot_name=self.bot_name)

                output_skeleton["obj"] = obj

                self.outputs[key] = output_skeleton


Instruction:
Implement a Python 3 function for
parsing the output records into dicts ready for JSON.

Response:
def _parse_output_records(self, item: IterationRecord) -> Dict[str, Any]:
        """Parse output records into dicts ready for JSON."""
        output_records = {}
        for key, sub_item in item.output_records.items():
            if isinstance(sub_item, dict) or isinstance(sub_item, list):
                output_records[key] = sub_item
            else:
                output_records[key] = sub_item.__dict__

        return output_records


Instruction:
Write a Python 3 function that can
create the directory of a fully qualified file name if it does not exist.

Response:
def make_dir(fname):
    """
    Create the directory of a fully qualified file name if it does not exist.

    :param fname: File name
    :type  fname: string

    Equivalent to these Bash shell commands:

    .. code-block:: bash

        $ fname="${HOME}/mydir/myfile.txt"
        $ dir=$(dirname "${fname}")
        $ mkdir -p "${dir}"

    :param fname: Fully qualified file name
    :type  fname: string
    """
    file_path, fname = os.path.split(os.path.abspath(fname))
    if not os.path.exists(file_path):
        os.makedirs(file_path)


Instruction:
Can you tell what is the following Python 3 function doing
def normalize_windows_fname(fname, _force=False):
    if (platform.system().lower() != "windows") and (not _force):  # pragma: no cover
        return fname
    # Replace unintended escape sequences that could be in
    # the file name, like "C:\appdata"
    rchars = {
        "\x07": r"\\a",
        "\x08": r"\\b",
        "\x0C": r"\\f",
        "\x0A": r"\\n",
        "\x0D": r"\\r",
        "\x09": r"\\t",
        "\x0B": r"\\v",
    }
    ret = ""
    for char in os.path.normpath(fname):
        ret = ret + rchars.get(char, char)
    # Remove superfluous double backslashes
    network_share = False
    tmp = None
    network_share = fname.startswith(r"\\")
    while tmp != ret:
        tmp, ret = ret, ret.replace(r"\\\\", r"\\")
    ret = ret.replace(r"\\\\", r"\\")
    # Put back network share if needed
    if network_share:
        ret = r"\\" + ret.lstrip(r"\\")
    return ret

Response: r Normalize a Windows file name to be compatible with Windows.


Instruction:
Can you write a function in Python 3 where it
enforces line separators to be the right one depending on platform.

Response:
def _homogenize_linesep(line):
    """Enforce line separators to be the right one depending on platform."""
    token = str(uuid.uuid4())
    line = line.replace(os.linesep, token).replace("\n", "").replace("\r", "")
    return line.replace(token, os.linesep)


Instruction:
Create a Python 3 function for
processing line range tokens.

Response:
def _proc_token(spec, mlines):
    """Process line range tokens."""
    spec = spec.strip().replace(" ", "")
    regexp = re.compile(r".*[^0123456789\-,]+.*")
    tokens = spec.split(",")
    cond = any([not item for item in tokens])
    if ("--" in spec) or ("-," in spec) or (",-" in spec) or cond or regexp.match(spec):
        raise RuntimeError("Argument `lrange` is not valid")
    lines = []
    for token in tokens:
        if token.count("-") > 1:
            raise RuntimeError("Argument `lrange` is not valid")
        if "-" in token:
            subtokens = token.split("-")
            lmin, lmax = (
                int(subtokens[0]),
                int(subtokens[1]) if subtokens[1] else mlines,
            )
            for num in range(lmin, lmax + 1):
                lines.append(num)
        else:
            lines.append(int(token))
    if lines != sorted(lines):
        raise RuntimeError("Argument `lrange` is not valid")
    return lines


Instruction:
How would you explain what the following Python 3 function does
def incfile(fname, fpointer, lrange=None, sdir=None):
    # pylint: disable=R0914
    # Read file
    file_dir = (
        sdir
        if sdir
        else os.environ.get("PKG_DOC_DIR", os.path.abspath(os.path.dirname(__file__)))
    )
    fname = os.path.join(file_dir, fname)
    with open(fname, "r") as fobj:
        lines = fobj.readlines()
    # Eliminate spurious carriage returns in Microsoft Windows
    lines = [_homogenize_linesep(line) for line in lines]
    # Parse line specification
    inc_lines = (
        _proc_token(lrange, len(lines)) if lrange else list(range(1, len(lines) + 1))
    )
    # Produce output
    fpointer(".. code-block:: python" + os.linesep)
    fpointer(os.linesep)
    for num, line in enumerate(lines):
        if num + 1 in inc_lines:
            fpointer(
                "    " + line.replace("\t", "    ").rstrip() + os.linesep
                if line.strip()
                else os.linesep
            )
    fpointer(os.linesep)

Response: r Include a file in the current directory.


Instruction:
Implement a Python 3 function for
printing STDOUT of a shell command formatted in reStructuredText.

Response:
def ste(command, nindent, mdir, fpointer, env=None):
    """
    Print STDOUT of a shell command formatted in reStructuredText.

    This is a simplified version of :py:func:`pmisc.term_echo`.

    :param command: Shell command (relative to **mdir** if **env** is not given)
    :type  command: string

    :param nindent: Indentation level
    :type  nindent: integer

    :param mdir: Module directory, used if **env** is not given
    :type  mdir: string

    :param fpointer: Output function pointer. Normally is :code:`cog.out` but
                     :code:`print` or other functions can be used for
                     debugging
    :type  fpointer: function object

    :param env: Environment dictionary. If not provided, the environment
                dictionary is the key "PKG_BIN_DIR" with the value of the
                **mdir**
    :type  env: dictionary

    For example::

        .. This is a reStructuredText file snippet
        .. [[[cog
        .. import os, sys
        .. from docs.support.term_echo import term_echo
        .. file_name = sys.modules['docs.support.term_echo'].__file__
        .. mdir = os.path.realpath(
        ..     os.path.dirname(
        ..         os.path.dirname(os.path.dirname(file_name))
        ..     )
        .. )
        .. [[[cog ste('build_docs.py -h', 0, mdir, cog.out) ]]]

        .. code-block:: console

        $ ${PKG_BIN_DIR}/build_docs.py -h
        usage: build_docs.py [-h] [-d DIRECTORY] [-n NUM_CPUS]
        ...
        $

        .. ]]]

    """
    sdir = LDELIM + "PKG_BIN_DIR" + RDELIM
    command = (
        sdir + ("{sep}{cmd}".format(sep=os.path.sep, cmd=command))
        if env is None
        else command
    )
    env = {"PKG_BIN_DIR": mdir} if env is None else env
    term_echo(command, nindent, env, fpointer)


Instruction:
Can you generate a brief explanation for the following Python 3 code
def term_echo(command, nindent=0, env=None, fpointer=None, cols=60):
    # pylint: disable=R0204
    # Set argparse width so that output does not need horizontal scroll
    # bar in narrow windows or displays
    os.environ["COLUMNS"] = str(cols)
    command_int = command
    if env:
        for var, repl in env.items():
            command_int = command_int.replace('"' + LDELIM + var + RDELIM + '"', repl)
            command_int = command_int.replace(LDELIM + var + RDELIM, repl)
    tokens = command_int.split(" ")
    # Add Python interpreter executable for Python scripts on Windows since
    # the shebang does not work
    if (platform.system().lower() == "windows") and (
        tokens[0].endswith(".py")
    ):  # pragma: no cover
        tokens = [sys.executable] + tokens
    proc = subprocess.Popen(tokens, stdout=subprocess.PIPE, stderr=subprocess.STDOUT)
    stdout = proc.communicate()[0]
    if sys.hexversion >= 0x03000000:  # pragma: no cover
        stdout = stdout.decode("utf-8")
    stdout = stdout.split("\n")
    indent = nindent * " "
    fpointer(os.linesep)
    fpointer("{0}.. code-block:: console{1}".format(indent, os.linesep))
    fpointer(os.linesep)
    fpointer("{0}    $ {1}{2}".format(indent, command, os.linesep))
    for line in stdout:
        line = _homogenize_linesep(line)
        if line.strip():
            fpointer(indent + "    " + line.replace("\t", "    ") + os.linesep)
        else:
            fpointer(os.linesep)

Response: Print a shell command formatted in reStructuredText.


Instruction:
Write a Python 3 script to
return the string given by param formatted with the callers locals.

Response:
def flo(string):
    '''Return the string given by param formatted with the callers locals.'''
    callers_locals = {}
    frame = inspect.currentframe()
    try:
        outerframe = frame.f_back
        callers_locals = outerframe.f_locals
    finally:
        del frame
    return string.format(**callers_locals)


Instruction:
Can you generate a brief explanation for the following Python 3 code
def _wrap_with(color_code):
    '''Color wrapper.

    Example:
        >>> blue = _wrap_with('34')
        >>> print(blue('text'))
        \033[34mtext\033[0m
    '''
    def inner(text, bold=False):
        '''Inner color function.'''
        code = color_code
        if bold:
            code = flo("1;{code}")
        return flo('\033[{code}m{text}\033[0m')
    return inner

Response:
Color wrapper.

    Example:
        >>> blue = _wrap_with('34')
        >>> print(blue('text'))
        \033[34mtext\033[0m


Instruction:
Create a Python 3 function to
delete temporary files and directories for packaging and editing.

Response:
def clean(deltox=False):
    '''Delete temporary files not under version control.

    Args:
        deltox: If True, delete virtual environments used by tox
    '''

    basedir = dirname(__file__)

    print(cyan('delete temp files and dirs for packaging'))
    local(flo(
        'rm -rf  '
        '{basedir}/.eggs/  '
        '{basedir}/utlz.egg-info/  '
        '{basedir}/dist  '
        '{basedir}/README  '
        '{basedir}/build/  '
    ))

    print(cyan('\ndelete temp files and dirs for editing'))
    local(flo(
        'rm -rf  '
        '{basedir}/.cache  '
        '{basedir}/.ropeproject  '
    ))

    print(cyan('\ndelete bytecode compiled versions of the python src'))
    # cf. http://stackoverflow.com/a/30659970
    local(flo('find  {basedir}/utlz  {basedir}/tests  ') +
          '\( -name \*pyc -o -name \*.pyo -o -name __pycache__ '
          '-o -name \*.so -o -name \*.o -o -name \*.c \) '
          '-prune '
          '-exec rm -rf {} +')

    if deltox:
        print(cyan('\ndelete tox virual environments'))
        local(flo('cd {basedir}  &&  rm -rf .tox/'))


Instruction:
Write a Python 3 function for
installing latest pythons with pyenv.

Response:
def pythons():
    '''Install latest pythons with pyenv.

    The python version will be activated in the projects base dir.

    Will skip already installed latest python versions.
    '''
    if not _pyenv_exists():
        print('\npyenv is not installed. You can install it with fabsetup '
              '(https://github.com/theno/fabsetup):\n\n    ' +
              cyan('mkdir ~/repos && cd ~/repos\n    '
                   'git clone  https://github.com/theno/fabsetup.git\n    '
                   'cd fabsetup  &&  fab setup.pyenv -H localhost'))
        return 1

    latest_pythons = _determine_latest_pythons()

    print(cyan('\n## install latest python versions'))
    for version in latest_pythons:
        local(flo('pyenv install --skip-existing {version}'))

    print(cyan('\n## activate pythons'))
    basedir = dirname(__file__)
    latest_pythons_str = '  '.join(latest_pythons)
    local(flo('cd {basedir}  &&  pyenv local  system  {latest_pythons_str}'))

    highest_python = latest_pythons[-1]
    print(cyan(flo(
        '\n## prepare Python-{highest_python} for testing and packaging')))
    packages_for_testing = 'pytest  tox'
    packages_for_packaging = 'pypandoc  twine'
    local(flo('~/.pyenv/versions/{highest_python}/bin/pip  install --upgrade  '
              'pip  {packages_for_testing}  {packages_for_packaging}'))


Instruction:
Can you implement a function in Python 3 that
runs tox. Build package and run unit tests against several pythons.

Response:
def tox(args=''):
    '''Run tox.

    Build package and run unit tests against several pythons.

    Args:
        args: Optional arguments passed to tox.
        Example:

            fab tox:'-e py36 -r'
    '''
    basedir = dirname(__file__)

    latest_pythons = _determine_latest_pythons()
    # e.g. highest_minor_python: '3.6'
    highest_minor_python = _highest_minor(latest_pythons)

    _local_needs_pythons(flo('cd {basedir}  &&  '
                             'python{highest_minor_python} -m tox {args}'))


Instruction:
Here you have a function in Python 3, explain what it does
def pypi():
    '''Build package and upload to pypi.'''
    if query_yes_no('version updated in setup.py?'):

        print(cyan('\n## clean-up\n'))
        execute(clean)

        basedir = dirname(__file__)

        latest_pythons = _determine_latest_pythons()
        # e.g. highest_minor: '3.6'
        highest_minor = _highest_minor(latest_pythons)
        python = flo('python{highest_minor}')

        print(cyan('\n## build package'))
        _local_needs_pythons(flo('cd {basedir}  &&  {python}  setup.py  sdist'))

        print(cyan('\n## upload package'))
        local(flo('cd {basedir}  &&  {python} -m twine upload  dist/*'))

Response: Build and upload to pypi.


Instruction:
Write a Python 3 function that can
check that the input column numbers are out of range.

Response:
def chk_col_numbers(line_num, num_cols, tax_id_col, id_col, symbol_col):
    """
    Check that none of the input column numbers is out of range.
    (Instead of defining this function, we could depend on Python's built-in
    IndexError exception for this issue, but the IndexError exception wouldn't
    include line number information, which is helpful for users to find exactly
    which line is the culprit.)
    """

    bad_col = ''
    if tax_id_col >= num_cols:
        bad_col = 'tax_id_col'
    elif id_col >= num_cols:
        bad_col = 'discontinued_id_col'
    elif symbol_col >= num_cols:
        bad_col = 'discontinued_symbol_col'

    if bad_col:
        raise Exception(
            'Input file line #%d: column number of %s is out of range' %
            (line_num, bad_col))


Instruction:
Make a summary of the following Python 3 code
def import_gene_history(file_handle, tax_id, tax_id_col, id_col, symbol_col):

    # Make sure that tax_id is not "" or "  "
    if not tax_id or tax_id.isspace():
        raise Exception("Input tax_id is blank")

    # Make sure that tax_id exists in Organism table in the database.
    try:
        organism = Organism.objects.get(taxonomy_id=tax_id)
    except Organism.DoesNotExist:
        raise Exception('Input tax_id %s does NOT exist in Organism table. '
                        'Please add it into Organism table first.' % tax_id)

    if tax_id_col < 0 or id_col < 0 or symbol_col < 0:
        raise Exception(
            'tax_id_col, id_col and symbol_col must be positive integers')

    for line_index, line in enumerate(file_handle):
        if line.startswith('#'):  # Skip comment lines.
            continue

        fields = line.rstrip().split('\t')
        # Check input column numbers.
        chk_col_numbers(line_index + 1, len(fields), tax_id_col, id_col,
                        symbol_col)

        # Skip lines whose tax_id's do not match input tax_id.
        if tax_id != fields[tax_id_col]:
            continue

        entrez_id = fields[id_col]
        # If the gene already exists in database, set its "obsolete" attribute
        # to True; otherwise create a new obsolete Gene record in database.
        try:
            gene = Gene.objects.get(entrezid=entrez_id)
            if not gene.obsolete:
                gene.obsolete = True
                gene.save()
        except Gene.DoesNotExist:
            Gene.objects.create(entrezid=entrez_id, organism=organism,
                                systematic_name=fields[symbol_col],
                                obsolete=True)

Response: Read the gene history file into the database.


Instruction:
Make a summary of the following Python 3 code
def cred_init(
            self,
            *,
            secrets_dir: str,
            log: Logger,
            bot_name: str="",
    ) -> None:
        """Initialize what requires credentials/secret files."""
        super().__init__(secrets_dir=secrets_dir, log=log, bot_name=bot_name)

        self.ldebug("Retrieving ACCESS_TOKEN ...")
        with open(path.join(self.secrets_dir, "ACCESS_TOKEN")) as f:
            ACCESS_TOKEN = f.read().strip()

        # Instance base url optional.
        self.ldebug("Looking for INSTANCE_BASE_URL ...")
        instance_base_url_path = path.join(self.secrets_dir, "INSTANCE_BASE_URL")
        if path.isfile(instance_base_url_path):
            with open(instance_base_url_path) as f:
                self.instance_base_url = f.read().strip()
        else:
            self.ldebug("Couldn't find INSTANCE_BASE_URL, defaulting to mastodon.social.")
            self.instance_base_url = "https://mastodon.social"

        self.api = mastodon.Mastodon(access_token=ACCESS_TOKEN,
                                     api_base_url=self.instance_base_url)
        self.html_re = re.compile("<.*?>")

Response: Initialize what requires credentials and secret files.


Instruction:
Explain what the following Python 3 code does
def send(
            self,
            *,
            text: str,
    ) -> List[OutputRecord]:
        """
        Send mastodon message.

        :param text: text to send in post.
        :returns: list of output records,
            each corresponding to either a single post,
            or an error.
        """
        try:
            status = self.api.status_post(status=text)

            return [TootRecord(record_data={
                "toot_id": status["id"],
                "text": text
            })]

        except mastodon.MastodonError as e:
            return [self.handle_error((f"Bot {self.bot_name} encountered an error when "
                                      f"sending post {text} without media:\n{e}\n"),
                                     e)]

Response: Send a message to the specified toot.


Instruction:
Can you implement a function in Python 3 that
uploads media to mastodon and sends status and media to the bot.

Response:
def send_with_media(
            self,
            *,
            text: str,
            files: List[str],
            captions: List[str]=[],
    ) -> List[OutputRecord]:
        """
        Upload media to mastodon,
        and send status and media,
        and captions if present.

        :param text: post text.
        :param files: list of files to upload with post.
        :param captions: list of captions to include as alt-text with files.
        :returns: list of output records,
            each corresponding to either a single post,
            or an error.
        """
        try:
            self.ldebug(f"Uploading files {files}.")
            if captions is None:
                captions = []

            if len(files) > len(captions):
                captions.extend([self.default_caption_message] * (len(files) - len(captions)))

            media_dicts = []
            for i, file in enumerate(files):
                caption = captions[i]
                media_dicts.append(self.api.media_post(file, description=caption))

            self.ldebug(f"Media ids {media_dicts}")

        except mastodon.MastodonError as e:
            return [self.handle_error(
                f"Bot {self.bot_name} encountered an error when uploading {files}:\n{e}\n", e
            )]

        try:
            status = self.api.status_post(status=text, media_ids=media_dicts)
            self.ldebug(f"Status object from toot: {status}.")
            return [TootRecord(record_data={
                "toot_id": status["id"],
                "text": text,
                "media_ids": media_dicts,
                "captions": captions
            })]

        except mastodon.MastodonError as e:
            return [self.handle_error((f"Bot {self.bot_name} encountered an error when "
                                      f"sending post {text} with media dicts {media_dicts}:"
                                      f"\n{e}\n"),
                                     e)]


Instruction:
Can you tell what is the following Python 3 function doing
def perform_batch_reply(
            self,
            *,
            callback: Callable[..., str],
            lookback_limit: int,
            target_handle: str,
    ) -> List[OutputRecord]:
        """
        Performs batch reply on target account.
        Looks up the recent messages of the target user,
        applies the callback,
        and replies with
        what the callback generates.

        :param callback: a callback taking a message id,
            message contents,
            and optional extra keys,
            and returning a message string.
        :param target: the id of the target account.
        :param lookback_limit: a lookback limit of how many messages to consider.
        :returns: list of output records,
            each corresponding to either a single post,
            or an error.
        """
        self.log.info(f"Attempting to batch reply to mastodon user {target_handle}")

        # target handle should be able to be provided either as @user or @user@domain
        # note that this produces an empty first chunk
        handle_chunks = target_handle.split("@")
        target_base_handle = handle_chunks[1]

        records: List[OutputRecord] = []
        our_id = self.api.account_verify_credentials()["id"]

        # be careful here - we're using a search to do this,
        # and if we're not careful we'll pull up people just mentioning the target.
        possible_accounts = self.api.account_search(target_handle, following=True)
        their_id = None
        for account in possible_accounts:
            if account["username"] == target_base_handle:
                their_id = account["id"]
                break

        if their_id is None:
            return [self.handle_error(f"Could not find target handle {target_handle}!", None)]

        statuses = self.api.account_statuses(their_id, limit=lookback_limit)
        for status in statuses:

            status_id = status.id

            # find possible replies we've made.
            our_statuses = self.api.account_statuses(our_id, since_id=status_id)
            in_reply_to_ids = list(map(lambda x: x.in_reply_to_id, our_statuses))
            if status_id not in in_reply_to_ids:

                encoded_status_text = re.sub(self.html_re, "", status.content)
                status_text = html.unescape(encoded_status_text)

                message = callback(message_id=status_id, message=status_text, extra_keys={})
                self.log.info(f"Replying {message} to status {status_id} from {target_handle}.")
                try:
                    new_status = self.api.status_post(status=message, in_reply_to_id=status_id)

                    records.append(TootRecord(record_data={
                        "toot_id": new_status.id,
                        "in_reply_to": target_handle,
                        "in_reply_to_id": status_id,
                        "text": message,
                    }))

                except mastodon.MastodonError as e:
                    records.append(
                        self.handle_error((f"Bot {self.bot_name} encountered an error when "
                                           f"sending post {message} during a batch reply "
                                           f":\n{e}\n"),
                                          e))
            else:
                self.log.info(f"Not replying to status {status_id} from {target_handle} "
                              f"- we already replied.")

        return records

Response: Perform a batch reply on the target account.


Instruction:
Given the following Python 3 function, write the documentation
def handle_error(self, message: str, e: mastodon.MastodonError) -> OutputRecord:
        self.lerror(f"Got an error! {e}")

        # Handle errors if we know how.
        try:
            code = e[0]["code"]
            if code in self.handled_errors:
                self.handled_errors[code]
            else:
                pass

        except Exception:
            pass

        return TootRecord(error=e)

Response: Handle an error while trying to do something.


Instruction:
Implement a Python 3 function for
reading the header from the log file.

Response:
def _read_header(self):
        '''
        Little-endian
        |... 4 bytes unsigned int ...|... 4 bytes unsigned int ...|
        |        frames count        |      dimensions count      |
        '''
        self._fh.seek(0)
        buf = self._fh.read(4*2)
        fc, dc = struct.unpack("<II", buf)
        return fc, dc