Instruction:
How would you implement a function in Python 3 that
sets up the initial relations between this element and other elements.

Response:
def setup(self, parent=None, previous=None):
        """Sets up the initial relations between this element and
        other elements."""
        self.parent = parent
        self.previous = previous
        self.next = None
        self.previousSibling = None
        self.nextSibling = None
        if self.parent and self.parent.contents:
            self.previousSibling = self.parent.contents[-1]
            self.previousSibling.nextSibling = self


Instruction:
Given the following Python 3 function, write the documentation
def extract(self):
        if self.parent:
            try:
                self.parent.contents.remove(self)
            except ValueError:
                pass

        #Find the two elements that would be next to each other if
        #this element (and any children) hadn't been parsed. Connect
        #the two.
        lastChild = self._lastRecursiveChild()
        nextElement = lastChild.next

        if self.previous:
            self.previous.next = nextElement
        if nextElement:
            nextElement.previous = self.previous
        self.previous = None
        lastChild.next = None

        self.parent = None
        if self.previousSibling:
            self.previousSibling.nextSibling = self.nextSibling
        if self.nextSibling:
            self.nextSibling.previousSibling = self.previousSibling
        self.previousSibling = self.nextSibling = None
        return self

Response: Destructively rips this element out of the tree.


Instruction:
Can you implement a function in Python 3 that
finds the last element beneath this object to be parsed.

Response:
def _lastRecursiveChild(self):
        "Finds the last element beneath this object to be parsed."
        lastChild = self
        while hasattr(lastChild, 'contents') and lastChild.contents:
            lastChild = lastChild.contents[-1]
        return lastChild


Instruction:
Implement a function in Python 3 to
return the first item that matches the given criteria and appears after this Tag in the document.

Response:
def findNext(self, name=None, attrs={}, text=None, **kwargs):
        """Returns the first item that matches the given criteria and
        appears after this Tag in the document."""
        return self._findOne(self.findAllNext, name, attrs, text, **kwargs)


Instruction:
Here you have a function in Python 3, explain what it does
def findAllNext(self, name=None, attrs={}, text=None, limit=None,
                    **kwargs):
        """Returns all items that match the given criteria and appear
        after this Tag in the document."""
        return self._findAll(name, attrs, text, limit, self.nextGenerator,
                             **kwargs)

Response:
Returns all items that match the given criteria and appear
        after this Tag in the document.


Instruction:
Can you write a function in Python 3 where it
returns the closest sibling to this Tag that matches the given criteria and appears after this Tag in the document.

Response:
def findNextSibling(self, name=None, attrs={}, text=None, **kwargs):
        """Returns the closest sibling to this Tag that matches the
        given criteria and appears after this Tag in the document."""
        return self._findOne(self.findNextSiblings, name, attrs, text,
                             **kwargs)


Instruction:
Can you write a function in Python 3 where it
returns the next siblings of this Tag that match the given criteria and appear after this Tag in the document.

Response:
def findNextSiblings(self, name=None, attrs={}, text=None, limit=None,
                         **kwargs):
        """Returns the siblings of this Tag that match the given
        criteria and appear after this Tag in the document."""
        return self._findAll(name, attrs, text, limit,
                             self.nextSiblingGenerator, **kwargs)


Instruction:
Implement a function in Python 3 to
return the first item that matches the given criteria and appears before this Tag in the document.

Response:
def findPrevious(self, name=None, attrs={}, text=None, **kwargs):
        """Returns the first item that matches the given criteria and
        appears before this Tag in the document."""
        return self._findOne(self.findAllPrevious, name, attrs, text, **kwargs)


Instruction:
Make a summary of the following Python 3 code
def findAllPrevious(self, name=None, attrs={}, text=None, limit=None,
                        **kwargs):
        """Returns all items that match the given criteria and appear
        before this Tag in the document."""
        return self._findAll(name, attrs, text, limit, self.previousGenerator,
                           **kwargs)

Response:
Returns all items that match the given criteria and appear
        before this Tag in the document.


Instruction:
Make a summary of the following Python 3 code
def findPreviousSibling(self, name=None, attrs={}, text=None, **kwargs):
        return self._findOne(self.findPreviousSiblings, name, attrs, text,
                             **kwargs)

Response:
Returns the closest sibling to this Tag that matches the
        given criteria and appears before this Tag in the document.


Instruction:
Write a Python 3 script to
return the siblings of this Tag that match the given criteria and appear before this Tag in the document.

Response:
def findPreviousSiblings(self, name=None, attrs={}, text=None,
                             limit=None, **kwargs):
        """Returns the siblings of this Tag that match the given
        criteria and appear before this Tag in the document."""
        return self._findAll(name, attrs, text, limit,
                             self.previousSiblingGenerator, **kwargs)


Instruction:
Implement a Python 3 function for
returning the closest parent of this Tag that matches the given criteria.

Response:
def findParent(self, name=None, attrs={}, **kwargs):
        """Returns the closest parent of this Tag that matches the given
        criteria."""
        # NOTE: We can't use _findOne because findParents takes a different
        # set of arguments.
        r = None
        l = self.findParents(name, attrs, 1)
        if l:
            r = l[0]
        return r


Instruction:
Implement a function in Python 3 to
return the parents of this Tag that match the given criteria.

Response:
def findParents(self, name=None, attrs={}, limit=None, **kwargs):
        """Returns the parents of this Tag that match the given
        criteria."""

        return self._findAll(name, attrs, None, limit, self.parentGenerator,
                             **kwargs)


Instruction:
Write a Python 3 function for
iterating over a generator looking for things that match.

Response:
def _findAll(self, name, attrs, text, limit, generator, **kwargs):
        "Iterates over a generator looking for things that match."

        if isinstance(name, SoupStrainer):
            strainer = name
        else:
            # Build a SoupStrainer
            strainer = SoupStrainer(name, attrs, text, **kwargs)
        results = ResultSet(strainer)
        g = generator()
        while True:
            try:
                i = g.next()
            except StopIteration:
                break
            if i:
                found = strainer.search(i)
                if found:
                    results.append(found)
                    if limit and len(results) >= limit:
                        break
        return results


Instruction:
Given the following Python 3 function, write the documentation
def toEncoding(self, s, encoding=None):
        if isinstance(s, unicode):
            if encoding:
                s = s.encode(encoding)
        elif isinstance(s, str):
            if encoding:
                s = s.encode(encoding)
            else:
                s = unicode(s)
        else:
            if encoding:
                s  = self.toEncoding(str(s), encoding)
            else:
                s = unicode(s)
        return s

Response: Encodes an object to a string in some encoding or to Unicode.


Instruction:
Can you tell what is the following Python 3 function doing
def _invert(h):
        "Cheap function to invert a hash."
        i = {}
        for k,v in h.items():
            i[v] = k
        return i

Response: Cheap function to invert a hash.


Instruction:
Write a Python 3 function that can
use in a call to re. sub to replace HTML XML and numericISO - 164 entities with the appropriate Unicode characters.

Response:
def _convertEntities(self, match):
        """Used in a call to re.sub to replace HTML, XML, and numeric
        entities with the appropriate Unicode characters. If HTML
        entities are being converted, any unrecognized entities are
        escaped."""
        x = match.group(1)
        if self.convertHTMLEntities and x in name2codepoint:
            return unichr(name2codepoint[x])
        elif x in self.XML_ENTITIES_TO_SPECIAL_CHARS:
            if self.convertXMLEntities:
                return self.XML_ENTITIES_TO_SPECIAL_CHARS[x]
            else:
                return u'&%s;' % x
        elif len(x) > 0 and x[0] == '#':
            # Handle numeric entities
            if len(x) > 1 and x[1] == 'x':
                return unichr(int(x[2:], 16))
            else:
                return unichr(int(x[1:]))

        elif self.escapeUnrecognizedEntities:
            return u'&%s;' % x
        else:
            return u'&%s;' % x


Instruction:
Can you tell what is the following Python 3 function doing
def decompose(self):
        contents = [i for i in self.contents]
        for i in contents:
            if isinstance(i, Tag):
                i.decompose()
            else:
                i.extract()
        self.extract()

Response: Recursively destroys the contents of this tree.


Instruction:
Write a Python 3 script to
render the contents of this tag as a Unicode string in the given encoding.

Response:
def renderContents(self, encoding=DEFAULT_OUTPUT_ENCODING,
                       prettyPrint=False, indentLevel=0):
        """Renders the contents of this tag as a string in the given
        encoding. If encoding is None, returns a Unicode string.."""
        s=[]
        for c in self:
            text = None
            if isinstance(c, NavigableString):
                text = c.__str__(encoding)
            elif isinstance(c, Tag):
                s.append(c.__str__(encoding, prettyPrint, indentLevel))
            if text and prettyPrint:
                text = text.strip()
            if text:
                if prettyPrint:
                    s.append(" " * (indentLevel-1))
                s.append(text)
                if prettyPrint:
                    s.append("\n")
        return ''.join(s)


Instruction:
Create a Python 3 function for
returning only the first child of this Tag matching the given criteria.

Response:
def find(self, name=None, attrs={}, recursive=True, text=None,
             **kwargs):
        """Return only the first child of this Tag matching the given
        criteria."""
        r = None
        l = self.findAll(name, attrs, recursive, text, 1, **kwargs)
        if l:
            r = l[0]
        return r


Instruction:
How would you explain what the following Python 3 function does
def findAll(self, name=None, attrs={}, recursive=True, text=None,
                limit=None, **kwargs):
        """Extracts a list of Tag objects that match the given
        criteria.  You can specify the name of the Tag and any
        attributes you want the Tag to have.

        The value of a key-value pair in the 'attrs' map can be a
        string, a list of strings, a regular expression object, or a
        callable that takes a string and returns whether or not the
        string matches for some custom definition of 'matches'. The
        same is true of the tag name."""
        generator = self.recursiveChildGenerator
        if not recursive:
            generator = self.childGenerator
        return self._findAll(name, attrs, text, limit, generator, **kwargs)

Response: Returns a list of Tag objects that match the given criteria.


Instruction:
Can you implement a function in Python 3 that
initializes a map representation of this tag s attributes and the tag s class ID.

Response:
def _getAttrMap(self):
        """Initializes a map representation of this tag's attributes,
        if not already initialized."""
        if not getattr(self, 'attrMap'):
            self.attrMap = {}
            for (key, value) in self.attrs:
                self.attrMap[key] = value
        return self.attrMap


Instruction:
Make a summary of the following Python 3 code
def convert_charref(self, name):
        try:
            n = int(name)
        except ValueError:
            return
        if not 0 <= n <= 127 : # ASCII ends at 127, not 255
            return
        return self.convert_codepoint(n)

Response: This method converts a character reference to a string.


Instruction:
Write a Python 3 script to
return true iff the given string is the name of a self - closing tag according to this parser.

Response:
def isSelfClosingTag(self, name):
        """Returns true iff the given string is the name of a
        self-closing tag according to this parser."""
        return self.SELF_CLOSING_TAGS.has_key(name) \
               or self.instanceSelfClosingTags.has_key(name)


Instruction:
Can you generate a brief explanation for the following Python 3 code
def _popToTag(self, name, inclusivePop=True):
        #print "Popping to %s" % name
        if name == self.ROOT_TAG_NAME:
            return

        numPops = 0
        mostRecentTag = None
        for i in range(len(self.tagStack)-1, 0, -1):
            if name == self.tagStack[i].name:
                numPops = len(self.tagStack)-i
                break
        if not inclusivePop:
            numPops = numPops - 1

        for i in range(0, numPops):
            mostRecentTag = self.popTag()
        return mostRecentTag

Response: Pops the tag stack up to and including the most recent instance of the given tag.


Instruction:
Make a summary of the following Python 3 code
def _toStringSubclass(self, text, subclass):
        self.endData()
        self.handle_data(text)
        self.endData(subclass)

Response:
Adds a certain piece of text to the tree as a NavigableString
        subclass.


Instruction:
Write a Python 3 function for
handling a processing instruction as a ProcessingInstruction object possibly one with a %SOUP - ENCODING% slot into which an analyzed entry will be plugged later.

Response:
def handle_pi(self, text):
        """Handle a processing instruction as a ProcessingInstruction
        object, possibly one with a %SOUP-ENCODING% slot into which an
        encoding will be plugged later."""
        if text[:3] == "xml":
            text = u"xml version='1.0' encoding='%SOUP-ENCODING%'"
        self._toStringSubclass(text, ProcessingInstruction)


Instruction:
Implement a function in Python 3 to
handle character references as data.

Response:
def handle_charref(self, ref):
        "Handle character references as data."
        if self.convertEntities:
            data = unichr(int(ref))
        else:
            data = '&#%s;' % ref
        self.handle_data(data)


Instruction:
Here you have a function in Python 3, explain what it does
def handle_entityref(self, ref):
        data = None
        if self.convertHTMLEntities:
            try:
                data = unichr(name2codepoint[ref])
            except KeyError:
                pass

        if not data and self.convertXMLEntities:
                data = self.XML_ENTITIES_TO_SPECIAL_CHARS.get(ref)

        if not data and self.convertHTMLEntities and \
            not self.XML_ENTITIES_TO_SPECIAL_CHARS.get(ref):
                # TODO: We've got a problem here. We're told this is
                # an entity reference, but it's not an XML entity
                # reference or an HTML entity reference. Nonetheless,
                # the logical thing to do is to pass it through as an
                # unrecognized entity reference.
                #
                # Except: when the input is "&carol;" this function
                # will be called with input "carol". When the input is
                # "AT&T", this function will be called with input
                # "T". We have no way of knowing whether a semicolon
                # was present originally, so we don't know whether
                # this is an unknown entity or just a misplaced
                # ampersand.
                #
                # The more common case is a misplaced ampersand, so I
                # escape the ampersand and omit the trailing semicolon.
                data = "&%s" % ref
        if not data:
            # This case is different from the one above, because we
            # haven't already gone through a supposedly comprehensive
            # mapping of entities to Unicode characters. We might not
            # have gone through any mapping at all. So the chances are
            # very high that this is a real entity, and not a
            # misplaced ampersand.
            data = "&%s;" % ref
        self.handle_data(data)

Response: Handle entity references as data possibly converting known unicode and XML entity references to the corresponding Unicode unicode characters.


Instruction:
Make a summary of the following Python 3 code
def parse_declaration(self, i):
        j = None
        if self.rawdata[i:i+9] == '<![CDATA[':
             k = self.rawdata.find(']]>', i)
             if k == -1:
                 k = len(self.rawdata)
             data = self.rawdata[i+9:k]
             j = k+3
             self._toStringSubclass(data, CData)
        else:
            try:
                j = SGMLParser.parse_declaration(self, i)
            except SGMLParseError:
                toHandle = self.rawdata[i:]
                self.handle_data(toHandle)
                j = i + len(toHandle)
        return j

Response:
Treat a bogus SGML declaration as raw data. Treat a CDATA
        declaration as a CData object.


Instruction:
Can you tell what is the following Python 3 function doing
def _subMSChar(self, orig):
        sub = self.MS_CHARS.get(orig)
        if type(sub) == types.TupleType:
            if self.smartQuotesTo == 'xml':
                sub = '&#x%s;' % sub[1]
            else:
                sub = '&%s;' % sub[0]
        return sub

Response: Changes a MS smart quote character to an XML or HTML object.


Instruction:
Create a Python 3 function to
give a string and its encoding decodes the string into Unicode.

Response:
def _toUnicode(self, data, encoding):
        '''Given a string and its encoding, decodes the string into Unicode.
        %encoding is a string recognized by encodings.aliases'''

        # strip Byte Order Mark (if present)
        if (len(data) >= 4) and (data[:2] == '\xfe\xff') \
               and (data[2:4] != '\x00\x00'):
            encoding = 'utf-16be'
            data = data[2:]
        elif (len(data) >= 4) and (data[:2] == '\xff\xfe') \
                 and (data[2:4] != '\x00\x00'):
            encoding = 'utf-16le'
            data = data[2:]
        elif data[:3] == '\xef\xbb\xbf':
            encoding = 'utf-8'
            data = data[3:]
        elif data[:4] == '\x00\x00\xfe\xff':
            encoding = 'utf-32be'
            data = data[4:]
        elif data[:4] == '\xff\xfe\x00\x00':
            encoding = 'utf-32le'
            data = data[4:]
        newdata = unicode(data, encoding)
        return newdata


Instruction:
Here you have a function in Python 3, explain what it does
def _detectEncoding(self, xml_data, isHTML=False):
        xml_encoding = sniffed_xml_encoding = None
        try:
            if xml_data[:4] == '\x4c\x6f\xa7\x94':
                # EBCDIC
                xml_data = self._ebcdic_to_ascii(xml_data)
            elif xml_data[:4] == '\x00\x3c\x00\x3f':
                # UTF-16BE
                sniffed_xml_encoding = 'utf-16be'
                xml_data = unicode(xml_data, 'utf-16be').encode('utf-8')
            elif (len(xml_data) >= 4) and (xml_data[:2] == '\xfe\xff') \
                     and (xml_data[2:4] != '\x00\x00'):
                # UTF-16BE with BOM
                sniffed_xml_encoding = 'utf-16be'
                xml_data = unicode(xml_data[2:], 'utf-16be').encode('utf-8')
            elif xml_data[:4] == '\x3c\x00\x3f\x00':
                # UTF-16LE
                sniffed_xml_encoding = 'utf-16le'
                xml_data = unicode(xml_data, 'utf-16le').encode('utf-8')
            elif (len(xml_data) >= 4) and (xml_data[:2] == '\xff\xfe') and \
                     (xml_data[2:4] != '\x00\x00'):
                # UTF-16LE with BOM
                sniffed_xml_encoding = 'utf-16le'
                xml_data = unicode(xml_data[2:], 'utf-16le').encode('utf-8')
            elif xml_data[:4] == '\x00\x00\x00\x3c':
                # UTF-32BE
                sniffed_xml_encoding = 'utf-32be'
                xml_data = unicode(xml_data, 'utf-32be').encode('utf-8')
            elif xml_data[:4] == '\x3c\x00\x00\x00':
                # UTF-32LE
                sniffed_xml_encoding = 'utf-32le'
                xml_data = unicode(xml_data, 'utf-32le').encode('utf-8')
            elif xml_data[:4] == '\x00\x00\xfe\xff':
                # UTF-32BE with BOM
                sniffed_xml_encoding = 'utf-32be'
                xml_data = unicode(xml_data[4:], 'utf-32be').encode('utf-8')
            elif xml_data[:4] == '\xff\xfe\x00\x00':
                # UTF-32LE with BOM
                sniffed_xml_encoding = 'utf-32le'
                xml_data = unicode(xml_data[4:], 'utf-32le').encode('utf-8')
            elif xml_data[:3] == '\xef\xbb\xbf':
                # UTF-8 with BOM
                sniffed_xml_encoding = 'utf-8'
                xml_data = unicode(xml_data[3:], 'utf-8').encode('utf-8')
            else:
                sniffed_xml_encoding = 'ascii'
                pass
        except:
            xml_encoding_match = None
        xml_encoding_match = re.compile(
            '^<\?.*encoding=[\'"](.*?)[\'"].*\?>').match(xml_data)
        if not xml_encoding_match and isHTML:
            regexp = re.compile('<\s*meta[^>]+charset=([^>]*?)[;\'">]', re.I)
            xml_encoding_match = regexp.search(xml_data)
        if xml_encoding_match is not None:
            xml_encoding = xml_encoding_match.groups()[0].lower()
            if isHTML:
                self.declaredHTMLEncoding = xml_encoding
            if sniffed_xml_encoding and \
               (xml_encoding in ('iso-10646-ucs-2', 'ucs-2', 'csunicode',
                                 'iso-10646-ucs-4', 'ucs-4', 'csucs4',
                                 'utf-16', 'utf-32', 'utf_16', 'utf_32',
                                 'utf16', 'u16')):
                xml_encoding = sniffed_xml_encoding
        return xml_data, xml_encoding, sniffed_xml_encoding

Response: Detects the XML encoding of a document.


Instruction:
Can you generate the documentation for the following Python 3 function
def shoebot_example(**shoebot_kwargs):

    def decorator(f):
        def run():
            from shoebot import ShoebotInstallError  # https://github.com/shoebot/shoebot/issues/206
            print("    Shoebot - %s:" % f.__name__.replace("_", " "))
            try:
                import shoebot
                outputfile = "/tmp/shoebot-%s.png" % f.__name__
                bot = shoebot.create_bot(outputfile=outputfile)
                f(bot)
                bot.finish()
                print('        [passed] : %s' % outputfile)
                print('')
            except ShoebotInstallError as e:
                print('        [failed]', e.args[0])
                print('')
            except Exception:
                print('        [failed] - traceback:')
                for line in traceback.format_exc().splitlines():
                    print('    %s' % line)
                print('')

        return run

    return decorator

Response: Decorator to run some code in a single bot instance.


Instruction:
How would you code a function in Python 3 to
return the center point of the path disregarding transforms.

Response:
def _get_center(self):
        '''Returns the center point of the path, disregarding transforms.
        '''
        x = (self.x + self.width / 2)
        y = (self.y + self.height / 2)
        return (x, y)


Instruction:
How would you code a function in Python 3 to
scale the context based on difference between bot size and widget size and widget size.

Response:
def scale_context_and_center(self, cr):
        """
        Scale context based on difference between bot size and widget
        """
        bot_width, bot_height = self.bot_size
        if self.width != bot_width or self.height != bot_height:
            # Scale up by largest dimension
            if self.width < self.height:
                scale_x = float(self.width) / float(bot_width)
                scale_y = scale_x
                cr.translate(0, (self.height - (bot_height * scale_y)) / 2.0)
            elif self.width > self.height:
                scale_y = float(self.height) / float(bot_height)
                scale_x = scale_y
                cr.translate((self.width - (bot_width * scale_x)) / 2.0, 0)
            else:
                scale_x = 1.0
                scale_y = 1.0
            cr.scale(scale_x, scale_y)
            self.input_device.scale_x = scale_y
            self.input_device.scale_y = scale_y


Instruction:
Can you generate the documentation for the following Python 3 function
def draw(self, widget, cr):
        '''
        Draw just the exposed part of the backing store, scaled to fit
        '''
        if self.bot_size is None:
            # No bot to draw yet.
            self.draw_default_image(cr)
            return

        cr = driver.ensure_pycairo_context(cr)

        surface = self.backing_store.surface
        cr.set_source_surface(surface)
        cr.paint()

Response: Draw just the exposed part of the backing store scaled to fit


Instruction:
Can you generate a brief explanation for the following Python 3 code
def create_rcontext(self, size, frame):
        '''
        Creates a recording surface for the bot to draw on

        :param size: The width and height of bot
        '''
        self.frame = frame
        width, height = size
        meta_surface = cairo.RecordingSurface(cairo.CONTENT_COLOR_ALPHA, (0, 0, width, height))

        ctx = cairo.Context(meta_surface)
        return ctx

Response: Creates a recording surface for the bot to draw on


Instruction:
Can you create a Python 3 function that
updates the backing store from a cairo context and schedule a redraw (expose event) :param size: width, height in pixels of bot :param frame: frame # thar was drawn :param cairo_ctx: cairo context the bot was drawn on

Response:
def do_drawing(self, size, frame, cairo_ctx):
        '''
        Update the backing store from a cairo context and
        schedule a redraw (expose event)

        :param size: width, height in pixels of bot
        :param frame: frame # thar was drawn
        :param cairo_ctx: cairo context the bot was drawn on
        '''
        if self.get_window() and not self.bot_size:
            # Get initial size for window
            self.set_size_request(*size)

        self.bot_size = size
        self.backing_store = BackingStore.get_backingstore(self.width, self.height)

        cr = pycairo.Context(self.backing_store.surface)
        if self.scale_fit:
            self.scale_context_and_center(cr)

        cairo_ctx = driver.ensure_pycairo_context(cairo_ctx)
        cr.set_source_surface(cairo_ctx.get_target())
        # Create the cairo context
        cr.set_operator(cairo.OPERATOR_SOURCE)
        cr.paint()

        self.queue_draw()

        while Gtk.events_pending():
            Gtk.main_iteration_do(False)


Instruction:
Implement a Python 3 function for
returning a JSON string representation of a Python data structure.

Response:
def encode(self, o):
        """
        Return a JSON string representation of a Python data structure.

        >>> JSONEncoder().encode({"foo": ["bar", "baz"]})
        '{"foo": ["bar", "baz"]}'
        """
        # This is for extremely simple cases and benchmarks.
        if isinstance(o, basestring):
            if isinstance(o, str):
                _encoding = self.encoding
                if (_encoding is not None
                        and not (_encoding == 'utf-8')):
                    o = o.decode(_encoding)
            if self.ensure_ascii:
                return encode_basestring_ascii(o)
            else:
                return encode_basestring(o)
        # This doesn't pass the iterator directly to ''.join() because the
        # exceptions aren't as detailed.  The list call should be roughly
        # equivalent to the PySequence_Fast that ''.join() would do.
        chunks = list(self.iterencode(o))
        return ''.join(chunks)


Instruction:
Write a Python 3 script to
encode the given object and yield each string representation as available.

Response:
def iterencode(self, o):
        """
        Encode the given object and yield each string
        representation as available.

        For example::

            for chunk in JSONEncoder().iterencode(bigobject):
                mysocket.write(chunk)
        """
        if self.check_circular:
            markers = {}
        else:
            markers = None
        return self._iterencode(o, markers)


Instruction:
Here you have a function in Python 3, explain what it does
def get_key_map(self):
        '''
        Return a dict in the form of

        SHOEBOT_KEY_NAME, GTK_VALUE

        Shoebot key names look like KEY_LEFT, whereas Gdk uses KEY_Left
        - Shoebot key names are derived from Nodebox 1, which was a mac
          app.
        '''
        kdict = {}
        for gdk_name in dir(Gdk):
            nb_name = gdk_name.upper()
            kdict[nb_name] = getattr(Gdk, gdk_name)
        return kdict

Response: Return a dict of the key names and values of the Shoebot application.


Instruction:
Write a Python 3 function for
outputting a filename along with multifile filename along with multifile filename along with multifile filename along with multifile filename along with multifile numbered filenames will be used.

Response:
def _output_file(self, frame):
        """
        If filename was used output a filename, along with multifile
        numbered filenames will be used.

        If buff was specified it is returned.

        :return: Output buff or filename.
        """
        if self.buff:
            return self.buff
        elif self.multifile:
            return self.file_root + "_%03d" % frame + self.file_ext
        else:
            return self.filename


Instruction:
Explain what the following Python 3 code does
def create_rcontext(self, size, frame):
        if self.format == 'pdf':
            surface = cairo.PDFSurface(self._output_file(frame), *size)
        elif self.format in ('ps', 'eps'):
            surface = cairo.PSSurface(self._output_file(frame), *size)
        elif self.format == 'svg':
            surface = cairo.SVGSurface(self._output_file(frame), *size)
        elif self.format == 'surface':
            surface = self.target
        else:
            surface = cairo.ImageSurface(cairo.FORMAT_ARGB32, *size)
        return cairo.Context(surface)

Response: Create a new context object for the current image.


Instruction:
Here you have a function in Python 3, explain what it does
def rendering_finished(self, size, frame, cairo_ctx):
        surface = cairo_ctx.get_target()
        if self.format == 'png':
            surface.write_to_png(self._output_file(frame))
        surface.finish()
        surface.flush()

Response: Called when the CairoCanvas has rendered a bot


Instruction:
Can you generate a brief explanation for the following Python 3 code
def output_closure(self, target, file_number=None):
        '''
        Function to output to a cairo surface

        target is a cairo Context or filename
        if file_number is set, then files will be numbered
        (this is usually set to the current frame number)
        '''
        def output_context(ctx):
            target_ctx = target
            target_ctx.set_source_surface(ctx.get_target())
            target_ctx.paint()
            return target_ctx

        def output_surface(ctx):
            target_ctx = cairo.Context(target)
            target_ctx.set_source_surface(ctx.get_target())
            target_ctx.paint()
            return target_ctx

        def output_file(ctx):
            root, extension = os.path.splitext(target)
            if file_number:
                filename = '%s_%04d%s' % (root, file_number, extension)
            else:
                filename = target

            extension = extension.lower()
            if extension == '.png':
                surface = ctx.get_target()
                surface.write_to_png(target)
            elif extension == '.pdf':
                target_ctx = cairo.Context(cairo.PDFSurface(filename, *self.size_or_default()))
                target_ctx.set_source_surface(ctx.get_target())
                target_ctx.paint()
            elif extension in ('.ps', '.eps'):
                target_ctx = cairo.Context(cairo.PSSurface(filename, *self.size_or_default()))
                if extension == '.eps':
                    target_ctx.set_eps(extension='.eps')
                target_ctx.set_source_surface(ctx.get_target())
                target_ctx.paint()
            elif extension == '.svg':
                target_ctx = cairo.Context(cairo.SVGSurface(filename, *self.size_or_default()))
                target_ctx.set_source_surface(ctx.get_target())
                target_ctx.paint()
            return filename

        if isinstance(target, cairo.Context):
            return output_context
        elif isinstance(target, cairo.Surface):
            return output_surface
        else:
            return output_file

Response:
Function to output to a cairo surface
            target is a string or a path to a cairo surface containing the current frame number.


Instruction:
Can you create a Python 3 function that
parses the resource class definition and returns a list of all the links in a resource class properties.

Response:
def _parse(self):

        """ Strips links from the definition and gathers them in a links property.
        """

        p1 = "\[.*?\](.*?)\[\/.*?\]"
        p2 = "\[(.*?)\]"
        self.links = []
        for p in (p1,p2):
            for link in re.findall(p, self.description):
                self.links.append(link)
            self.description = re.sub(p, "\\1", self.description)

        self.description = self.description.strip()


Instruction:
Write a Python 3 function that can
create a CairoCanvas and CairoImageSink for an attachment to a bot.

Response:
def create_canvas(src, format=None, outputfile=None, multifile=False, buff=None, window=False, title=None,
                  fullscreen=None, show_vars=False):
    """
    Create canvas and sink for attachment to a bot

    canvas is what draws images, 'sink' is the final consumer of the images

    :param src: Defaults for title or outputfile if not specified.

    :param format: CairoImageSink image format, if using buff instead of outputfile
    :param buff: CairoImageSink buffer object to send output to

    :param outputfile: CairoImageSink output filename e.g. "hello.svg"
    :param multifile: CairoImageSink if True,

    :param title: ShoebotWindow - set window title
    :param fullscreen: ShoebotWindow - set window title
    :param show_vars: ShoebotWindow - display variable window

    Two kinds of sink are provided: CairoImageSink and ShoebotWindow

    ShoebotWindow

    Displays a window to draw shoebot inside.

    CairoImageSink

    Output to a filename (or files if multifile is set), or a buffer object.
    """
    from core import CairoCanvas, CairoImageSink # https://github.com/shoebot/shoebot/issues/206

    if outputfile:
        sink = CairoImageSink(outputfile, format, multifile, buff)
    elif window or show_vars:
        from gui import ShoebotWindow
        if not title:
            if src and os.path.isfile(src):
                title = os.path.splitext(os.path.basename(src))[0] + ' - Shoebot'
            else:
                title = 'Untitled - Shoebot'
        sink = ShoebotWindow(title, show_vars, fullscreen=fullscreen)
    else:
        if src and isinstance(src, cairo.Surface):
            outputfile = src
            format = 'surface'
        elif src and os.path.isfile(src):
            outputfile = os.path.splitext(os.path.basename(src))[0] + '.' + (format or 'svg')
        else:
            outputfile = 'output.svg'
        sink = CairoImageSink(outputfile, format, multifile, buff)
    canvas = CairoCanvas(sink)

    return canvas


Instruction:
Can you create a Python 3 function that
creates a bot with the same canvas attached to it

Response:
def create_bot(src=None, grammar=NODEBOX, format=None, outputfile=None, iterations=1, buff=None, window=False,
               title=None, fullscreen=None, server=False, port=7777, show_vars=False, vars=None, namespace=None):
    """
    Create a canvas and a bot with the same canvas attached to it

    bot parameters
    :param grammar: DRAWBOT or NODEBOX - decides what kind of bot is created
    :param vars: preset dictionary of vars from the called

    canvas parameters:
    ... everything else ...

    See create_canvas for details on those parameters.

    """
    canvas = create_canvas(src, format, outputfile, iterations > 1, buff, window, title, fullscreen=fullscreen,
                           show_vars=show_vars)

    if grammar == DRAWBOT:
        from shoebot.grammar import DrawBot
        bot = DrawBot(canvas, namespace=namespace, vars=vars)
    else:
        from shoebot.grammar import NodeBot
        bot = NodeBot(canvas, namespace=namespace, vars=vars)

    if server:
        from shoebot.sbio import SocketServer
        socket_server = SocketServer(bot, "", port=port)
    return bot


Instruction:
Explain what the following Python 3 code does
def run(src,
        grammar=NODEBOX,
        format=None,
        outputfile=None,
        iterations=1,
        buff=None,
        window=True,
        title=None,
        fullscreen=None,
        close_window=False,
        server=False,
        port=7777,
        show_vars=False,
        vars=None,
        namespace=None,
        run_shell=False,
        args=[],
        verbose=False,
        background_thread=True):
    """
    Create and run a bot, the arguments all correspond to sanitized
    commandline options.

    :param background_thread: If True then use a background thread.

    Other args are split into create_args and run_args

    See create_bot for details on create_args

    run_args are passed to bot.run - see Nodebot.run or Drawbot.run

    Background thread:

    readline in python is blocking, running the app in a background
    thread opens up the main thread for IO on stdin/stdout, which
    can be used for communication with shoebot when livecoding is
    enabled.

    See shoebot.io for implementation of the shell, and the gedit
    plugin for an example of using livecoding.
    """
    # Munge shoebogt sys.argv
    sys.argv = [sys.argv[
                    0]] + args  # Remove shoebot parameters so sbot can be used in place of the python interpreter (e.g. for sphinx).

    # arguments for create_bot
    create_args = [src,
                   grammar,
                   format,
                   outputfile,
                   iterations,
                   buff,
                   window,
                   title,
                   fullscreen,
                   server,
                   port,
                   show_vars]
    create_kwargs = dict(vars=vars, namespace=namespace)
    run_args = [src]
    run_kwargs = dict(
        iterations=iterations,
        frame_limiter=window,
        verbose=verbose,
        # run forever except 1. windowed mode is off 2. if --close-window was specified and
        # 3. if an output file was indicated
        run_forever=window and not (close_window or bool(outputfile)),
    )

    # Run shoebot in a background thread so we can run a cmdline shell in the current thread
    if background_thread:
        sbot_thread = ShoebotThread(
            create_args=create_args,
            create_kwargs=create_kwargs,
            run_args=run_args,
            run_kwargs=run_kwargs,
            send_sigint=run_shell
        )
        sbot_thread.start()
        sbot = sbot_thread.sbot
    else:
        print('background thread disabled')
        # This is a debug option, things should always work using the
        # background thread (crosses fingers)
        if run_shell:
            # python readline is blocking, so ui must run in a seperate
            # thread
            raise ValueError('UI Must run in a separate thread to shell and shell needs main thread')

        sbot_thread = None
        sbot = create_bot(*create_args, **create_kwargs)
        sbot.run(*run_args, **run_kwargs)

    if run_shell:
        import shoebot.sbio.shell
        shell = shoebot.sbio.shell.ShoebotCmd(sbot, trusted=True)
        try:
            shell.cmdloop()
        except KeyboardInterrupt as e:
            publish_event(QUIT_EVENT)  # Handle Ctrl-C
            # KeyboardInterrupt is generated by os.kill from the other thread
            if verbose:
                raise
            else:
                return
    elif background_thread:
        try:
            while sbot_thread.is_alive():
                sleep(1)
        except KeyboardInterrupt:
            publish_event(QUIT_EVENT)

    if all((background_thread, sbot_thread)):
        sbot_thread.join()

    return sbot

Response: Create and run a nodebot from a source string.


Instruction:
Given the following Python 3 function, write the documentation
def save_as(self):
        chooser = ShoebotFileChooserDialog(_('Save File'), None, Gtk.FileChooserAction.SAVE,
                                           (Gtk.STOCK_SAVE, Gtk.ResponseType.ACCEPT,
                                            Gtk.STOCK_CANCEL, Gtk.ResponseType.CANCEL))
        chooser.set_do_overwrite_confirmation(True)
        chooser.set_transient_for(self)
        saved = chooser.run() == Gtk.ResponseType.ACCEPT
        if saved:
            old_filename = self.filename
            self.source_buffer.filename = chooser.get_filename()
            if not self.save():
                self.filename = old_filename
        chooser.destroy()
        return saved

Response: Save the buffer as.


Instruction:
Given the following Python 3 function, write the documentation
def add_variables(self):
        for k, v in self.bot._vars.items():
            if not hasattr(v, 'type'):
                raise AttributeError(
                    '%s is not a Shoebot Variable - see https://shoebot.readthedocs.io/en/latest/commands.html#dynamic-variables' % k)
            self.add_variable(v)

Response: Add all variables to the specified vbox


Instruction:
Write a Python 3 function that can
update the value of a variable in the current object

Response:
def update_var(self, name, value):
        """
        :return: success, err_msg_if_failed
        """
        widget = self.widgets.get(name)
        if widget is None:
            return False, 'No widget found matching, {}'.format(name)

        try:
            if isinstance(widget, Gtk.CheckButton):
                widget.set_active(value)
                return True, widget.get_active()
            elif isinstance(widget, Gtk.Entry):
                widget.set_text(value)
                return True, widget.get_text()
            else:
                widget.set_value(value)
                return True, widget.get_value()
        except Exception as e:
            return False, str(e)


Instruction:
Write a Python 3 function that can
call when a slider is changed.

Response:
def widget_changed(self, widget, v):
        ''' Called when a slider is adjusted. '''
        # set the appropriate bot var
        if v.type is NUMBER:
            self.bot._namespace[v.name] = widget.get_value()
            self.bot._vars[v.name].value = widget.get_value()  ## Not sure if this is how to do this - stu
            publish_event(VARIABLE_UPDATED_EVENT, v)  # pretty dumb for now
        elif v.type is BOOLEAN:
            self.bot._namespace[v.name] = widget.get_active()
            self.bot._vars[v.name].value = widget.get_active()  ## Not sure if this is how to do this - stu
            publish_event(VARIABLE_UPDATED_EVENT, v)  # pretty dumb for now
        elif v.type is TEXT:
            self.bot._namespace[v.name] = widget.get_text()
            self.bot._vars[v.name].value = widget.get_text()  ## Not sure if this is how to do this - stu
            publish_event(VARIABLE_UPDATED_EVENT, v)


Instruction:
How would you explain what the following Python 3 function does
def var_added(self, v):
        self.add_variable(v)

        self.window.set_size_request(400, 35 * len(self.widgets.keys()))
        self.window.show_all()

Response: Called when a new variable was added in the bot while it ran


Instruction:
Make a summary of the following Python 3 code
def var_deleted(self, v):
        widget = self.widgets[v.name]

        # widgets are all in a single container ..
        parent = widget.get_parent()
        self.container.remove(parent)
        del self.widgets[v.name]

        self.window.set_size_request(400, 35 * len(self.widgets.keys()))
        self.window.show_all()

Response: Called when a var was deleted in the bot


Instruction:
How would you code a function in Python 3 to
parse a SVG string into a list of paths.

Response:
def parse(svg, cached=False, _copy=True):

    """ Returns cached copies unless otherwise specified.
    """

    if not cached:
        dom = parser.parseString(svg)
        paths = parse_node(dom, [])
    else:
        id = _cache.id(svg)
        if not _cache.has_key(id):
            dom = parser.parseString(svg)
            _cache.save(id, parse_node(dom, []))
        paths = _cache.load(id, _copy)

    return paths


Instruction:
Can you write a function in Python 3 where it
returns the attribute of the XML element.

Response:
def get_attribute(element, attribute, default=0):

    """ Returns XML element's attribute, or default if none.
    """

    a = element.getAttribute(attribute)
    if a == "":
        return default
    return a


Instruction:
Can you tell what is the following Python 3 function doing
def parse_transform(e, path):

    """ Transform the path according to a defined matrix.

    Attempts to extract a transform="matrix()|translate()" attribute.
    Transforms the path accordingly.

    """

    t = get_attribute(e, "transform", default="")

    for mode in ("matrix", "translate"):
        if t.startswith(mode):
            v = t.replace(mode, "").lstrip("(").rstrip(")")
            v = v.replace(", ", ",").replace(" ", ",")
            v = [float(x) for x in v.split(",")]
            from nodebox.graphics import Transform
            t = Transform()
            if mode == "matrix":
                t._set_matrix(v)
            elif mode == "translate":
                t.translate(*v)
            path = t.transformBezierPath(path)
            break

    # Transformations can also be defined as <g transform="matrix()"><path /><g>
    # instead of <g><path transform="matrix() /></g>.
    e = e.parentNode
    if e and e.tagName == "g":
        path = parse_transform(e, path)

    return path

Response: Parses the transform attribute of the element e and returns the path.


Instruction:
Make a summary of the following Python 3 code
def add_color_info(e, path):

    """ Expand the path with color information.

    Attempts to extract fill and stroke colors
    from the element and adds it to path attributes.

    """

    _ctx.colormode(RGB, 1.0)

    def _color(hex, alpha=1.0):
        if hex == "none": return None
        n = int(hex[1:],16)
        r = (n>>16)&0xff
        g = (n>>8)&0xff
        b = n&0xff
        return _ctx.color(r/255.0, g/255.0, b/255.0, alpha)

    path.fill = (0,0,0,0)
    path.stroke = (0,0,0,0)
    path.strokewidth = 0

    # See if we can find an opacity attribute,
    # which is the color's alpha.
    alpha = get_attribute(e, "opacity", default="")
    if alpha == "":
        alpha = 1.0
    else:
        alpha = float(alpha)

    # Colors stored as fill="" or stroke="" attributes.
    try: path.fill = _color(get_attribute(e, "fill", default="#00000"), alpha)
    except:
        pass
    try: path.stroke = _color(get_attribute(e, "stroke", default="none"), alpha)
    except:
        pass
    try: path.strokewidth = float(get_attribute(e, "stroke-width", default="1"))
    except:
        pass

    # Colors stored as a CSS style attribute, for example:
    # style="fill:#ff6600;stroke:#ffe600;stroke-width:0.06742057"
    style = get_attribute(e, "style", default="").split(";")
    for s in style:
        try:
            if s.startswith("fill:"):
                path.fill = _color(s.replace("fill:", ""))
            elif s.startswith("stroke:"):
                path.stroke = _color(s.replace("stroke:", ""))
            elif s.startswith("stroke-width:"):
                path.strokewidth = float(s.replace("stroke-width:", ""))
        except:
            pass

    # A path with beginning and ending coordinate
    # at the same location is considered closed.
    # Unless it contains a MOVETO somewhere in the middle.
    path.closed = False
    if path[0].x == path[len(path)-1].x and \
       path[0].y == path[len(path)-1].y:
        path.closed = True
    for i in range(1,-1):
        if path[i].cmd == MOVETO:
            path.closed = False

    return path

Response: Adds color information to the path attributes of the current node.


Instruction:
Can you generate the documentation for the following Python 3 function
def download(self, size=SIZE_LARGE, thumbnail=False, wait=60, asynchronous=False):

        """ Downloads this image to cache.

        Calling the download() method instantiates an asynchronous URLAccumulator.
        Once it is done downloading, this image will have its path property
        set to an image file in the cache.

        """

        if thumbnail == True: size = SIZE_THUMBNAIL # backwards compatibility
        self._size = disambiguate_size(size)
        if self._size == SIZE_THUMBNAIL:
            url = self.url.replace("/preview/", "/med/")
        else:
            url = self.url

        cache = "morguefile"
        extension = os.path.splitext(url)[1]
        URLAccumulator.__init__(self, url, wait, asynchronous, cache, extension, 2)

        if not asynchronous:
            return self.path

Response: Downloads this image to the cache.


Instruction:
Write a Python 3 function for
returning a copy of the event handler remembering the last node clicked.

Response:
def copy(self, graph):

        """ Returns a copy of the event handler, remembering the last node clicked.
        """

        e = events(graph, self._ctx)
        e.clicked = self.clicked
        return e


Instruction:
Can you generate a brief explanation for the following Python 3 code
def update(self):

        """ Interacts with the graph by clicking or dragging nodes.
        Hovering a node fires the callback function events.hover().
        Clicking a node fires the callback function events.click().
        """

        if self.mousedown:

            # When not pressing or dragging, check each node.
            if not self.pressed and not self.dragged:
                for n in self.graph.nodes:
                    if self.mouse in n:
                        self.pressed = n
                        break

            # If a node is pressed, check if a drag is started.
            elif self.pressed and not self.mouse in self.pressed:
                self.dragged = self.pressed
                self.pressed = None

            # Drag the node (right now only for springgraphs).
            elif self.dragged and self.graph.layout.type == "spring":
                self.drag(self.dragged)
                self.graph.layout.i = min(100, max(2, self.graph.layout.n-100))

        # Mouse is clicked on a node, fire callback.
        elif self.pressed and self.mouse in self.pressed:
            self.clicked = self.pressed
            self.pressed = None
            self.graph.layout.i = 2
            self.click(self.clicked)

        # Mouse up.
        else:
            self.hovered = None
            self.pressed = None
            self.dragged = None

            # Hovering over a node?
            for n in self.graph.nodes:
                if self.mouse in n:
                    self.hovered = n
                    self.hover(n)
                    break

Response: Updates the mouse state of the node.


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

        """ Drags given node to mouse location.
        """

        dx = self.mouse.x - self.graph.x
        dy = self.mouse.y - self.graph.y

        # A dashed line indicates the drag vector.
        s = self.graph.styles.default
        self._ctx.nofill()
        self._ctx.nostroke()
        if s.stroke:
            self._ctx.strokewidth(s.strokewidth)
            self._ctx.stroke(
                s.stroke.r,
                s.stroke.g,
                s.stroke.g,
                0.75
            )
        p = self._ctx.line(node.x, node.y, dx, dy, draw=False)
        try: p._nsBezierPath.setLineDash_count_phase_([2,4], 2, 50)
        except:
            pass
        self._ctx.drawpath(p)
        r = node.__class__(None).r * 0.75
        self._ctx.oval(dx-r/2, dy-r/2, r, r)

        node.vx = dx / self.graph.d
        node.vy = dy / self.graph.d

Response: Drags given node to mouse location.


Instruction:
Make a summary of the following Python 3 code
def hover(self, node):

        """ Displays a popup when hovering over a node.
        """

        if self.popup == False: return
        if self.popup == True or self.popup.node != node:
            if self.popup_text.has_key(node.id):
                texts = self.popup_text[node.id]
            else:
                texts = None
            self.popup = popup(self._ctx, node, texts)
        self.popup.draw()

Response: Displays a popup when hovering over a node.


Instruction:
Write a Python 3 script for
returning a cached textpath of the given text in queue.

Response:
def textpath(self, i):

        """ Returns a cached textpath of the given text in queue.
        """

        if len(self._textpaths) == i:
            self._ctx.font(self.font, self.fontsize)
            txt = self.q[i]
            if len(self.q) > 1:
                # Indicate current text (e.g. 5/13).
                txt += " ("+str(i+1)+"/" + str(len(self.q))+")"
            p = self._ctx.textpath(txt, 0, 0, width=self._w)
            h = self._ctx.textheight(txt, width=self._w)
            self._textpaths.append((p, h))

        return self._textpaths[i]


Instruction:
Explain what the following Python 3 code does
def update(self):

        """ Rotates the queued texts and determines display time.
        """

        if self.delay > 0:
            # It takes a while for the popup to appear.
            self.delay -= 1; return

        if self.fi == 0:
            # Only one text in queue, displayed infinitely.
            if len(self.q) == 1:
                self.fn = float("inf")
            # Else, display time depends on text length.
            else:
                self.fn = len(self.q[self.i]) / self.speed
                self.fn = max(self.fn, self.mf)

        self.fi += 1
        if self.fi > self.fn:
            # Rotate to the next text in queue.
            self.fi = 0
            self.i = (self.i+1) % len(self.q)

Response: Updates the internal state of the internal state of the object.


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

        """ Draws a popup rectangle with a rotating text queue.
        """

        if len(self.q) > 0:
            self.update()

            if self.delay == 0:

                # Rounded rectangle in the given background color.
                p, h = self.textpath(self.i)
                f = self.fontsize
                self._ctx.fill(self.background)
                self._ctx.rect(
                    self.node.x + f*1.0,
                    self.node.y + f*0.5,
                    self._w + f,
                    h + f*1.5,
                    roundness=0.2
                )

                # Fade in/out the current text.
                alpha = 1.0
                if self.fi < 5:
                    alpha = 0.2 * self.fi
                if self.fn-self.fi < 5:
                    alpha = 0.2 * (self.fn-self.fi)
                self._ctx.fill(
                    self.text.r,
                    self.text.g,
                    self.text.b,
                    self.text.a * alpha
                )

                self._ctx.translate(self.node.x + f*2.0, self.node.y + f*2.5)
                self._ctx.drawpath(p)

Response: Draws a popup rectangle with a rotating text queue.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def write_main(argv):
    if len(argv) != 1:
        print("Please provide the name of a file to write.")
        return 1

    filename = argv[0]
    resource_name = "files/" + filename
    tweaks_name = amend_filename(filename, "_tweaks")

    if not pkg_resources.resource_exists("edx_lint", resource_name):
        print(u"Don't have file %r to write." % filename)
        return 2

    if os.path.exists(filename):
        print(u"Checking existing copy of %s" % filename)
        tef = TamperEvidentFile(filename)
        if not tef.validate():
            bak_name = amend_filename(filename, "_backup")
            print(u"Your copy of %s seems to have been edited, renaming it to %s" % (filename, bak_name))
            if os.path.exists(bak_name):
                print(u"A previous %s exists, deleting it" % bak_name)
                os.remove(bak_name)
            os.rename(filename, bak_name)

    print(u"Reading edx_lint/files/%s" % filename)
    cfg = configparser.RawConfigParser()
    resource_string = pkg_resources.resource_string("edx_lint", resource_name).decode("utf8")

    # pkg_resources always reads binary data (in both python2 and python3).
    # ConfigParser.read_string only exists in python3, so we have to wrap the string
    # from pkg_resources in a cStringIO so that we can pass it into ConfigParser.readfp.
    if six.PY2:
        cfg.readfp(cStringIO(resource_string), resource_name)
    else:
        cfg.read_string(resource_string, resource_name)     # pylint: disable=no-member

    if os.path.exists(tweaks_name):
        print(u"Applying local tweaks from %s" % tweaks_name)
        cfg_tweaks = configparser.RawConfigParser()
        cfg_tweaks.read([tweaks_name])

        merge_configs(cfg, cfg_tweaks)

    print(u"Writing %s" % filename)
    output_text = cStringIO()
    output_text.write(WARNING_HEADER.format(filename=filename, tweaks_name=tweaks_name))
    cfg.write(output_text)

    out_tef = TamperEvidentFile(filename)
    if six.PY2:
        output_bytes = output_text.getvalue()
    else:
        output_bytes = output_text.getvalue().encode("utf8")
    out_tef.write(output_bytes)

    return 0

Response: Write a local copy of FILENAME using FILENAME_tweaks for local tweaks.


Instruction:
Can you tell what is the following Python 3 function doing
def amend_filename(filename, amend):
    base, ext = os.path.splitext(filename)
    amended_name = base + amend + ext
    return amended_name

Response: Amends a filename with a suffix.


Instruction:
Can you tell what is the following Python 3 function doing
def check_main(argv):
    if len(argv) != 1:
        print("Please provide the name of a file to check.")
        return 1

    filename = argv[0]

    if os.path.exists(filename):
        print(u"Checking existing copy of %s" % filename)
        tef = TamperEvidentFile(filename)
        if tef.validate():
            print(u"Your copy of %s is good" % filename)
        else:
            print(u"Your copy of %s seems to have been edited" % filename)
    else:
        print(u"You don't have a copy of %s" % filename)

    return 0

Response: Check that FILENAME has not been edited since writing.


Instruction:
Explain what the following Python 3 code does
def merge_configs(main, tweaks):
    for section in tweaks.sections():
        for option in tweaks.options(section):
            value = tweaks.get(section, option)
            if option.endswith("+"):
                option = option[:-1]
                value = main.get(section, option) + value
            main.set(section, option, value)

Response: Merge tweaks into a main config file.


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

        with open(self.filename, "rb") as f:
            text = f.read()

        start_last_line = text.rfind(b"\n", 0, -1)
        if start_last_line == -1:
            return False

        original_text = text[:start_last_line+1]
        last_line = text[start_last_line+1:]

        expected_hash = hashlib.sha1(original_text).hexdigest().encode('utf8')
        match = re.search(b"[0-9a-f]{40}", last_line)
        if not match:
            return False
        actual_hash = match.group(0)
        return actual_hash == expected_hash

Response: Check if the file still has its original contents.


Instruction:
Write a Python 3 script for
checking that a checker s visitors are correctly named.

Response:
def check_visitors(cls):
    """Check that a checker's visitors are correctly named.

    A checker has methods named visit_NODETYPE, but it's easy to mis-name
    a visit method, and it will never be called.  This decorator checks
    the class to see that all of its visitors are named after an existing
    node class.
    """
    for name in dir(cls):
        if name.startswith("visit_"):
            if name[6:] not in CLASS_NAMES:
                raise Exception(u"Method {} doesn't correspond to a node class".format(name))
    return cls


Instruction:
Here you have a function in Python 3, explain what it does
def usable_class_name(node):
    name = node.qname()
    for prefix in ["__builtin__.", "builtins.", "."]:
        if name.startswith(prefix):
            name = name[len(prefix):]
    return name

Response: Make a reasonable class name for a class node.


Instruction:
Can you tell what is the following Python 3 function doing
def parse_pylint_output(pylint_output):
    for line in pylint_output:
        if not line.strip():
            continue

        if line[0:5] in ("-"*5, "*"*5):
            continue

        parsed = PYLINT_PARSEABLE_REGEX.search(line)
        if parsed is None:
            LOG.warning(
                u"Unable to parse %r. If this is a lint failure, please re-run pylint with the "
                u"--output-format=parseable option, otherwise, you can ignore this message.",
                line
            )
            continue

        parsed_dict = parsed.groupdict()
        parsed_dict['linenum'] = int(parsed_dict['linenum'])
        yield PylintError(**parsed_dict)

Response: Parse the pylint output into PylintError tuples.


Instruction:
Here you have a function in Python 3, explain what it does
def format_pylint_disables(error_names, tag=True):
    tag_str = "lint-amnesty, " if tag else ""
    if error_names:
        return u"  # {tag}pylint: disable={disabled}".format(
            disabled=", ".join(sorted(error_names)),
            tag=tag_str,
        )
    else:
        return ""

Response: Format a list of error_names into a pylint disable line.


Instruction:
How would you explain what the following Python 3 function does
def fix_pylint(line, errors):
    if not errors:
        yield line
        return

    current = PYLINT_EXCEPTION_REGEX.search(line)
    if current:
        original_errors = {disable.strip() for disable in current.group('disables').split(',')}
    else:
        original_errors = set()

    disabled_errors = set(original_errors)

    for error in errors:
        if error.error_name == 'useless-suppression':
            parsed = re.search("""Useless suppression of '(?P<error_name>[^']+)'""", error.error_msg)
            disabled_errors.discard(parsed.group('error_name'))
        elif error.error_name == 'missing-docstring' and error.error_msg == 'Missing module docstring':
            yield format_pylint_disables({error.error_name}).strip() + '\n'
        else:
            disabled_errors.add(error.error_name)

    disable_string = format_pylint_disables(disabled_errors, not disabled_errors <= original_errors)

    if current:
        yield PYLINT_EXCEPTION_REGEX.sub(disable_string, line)
    else:
        yield re.sub(r'($\s*)', disable_string + r'\1', line, count=1)

Response: Yield any modified versions of line needed to address the errors in errors.


Instruction:
Implement a function in Python 3 to
add ``# pylint: disable`` clauses to add exceptions to all existing pylint errors in a codebase.

Response:
def pylint_amnesty(pylint_output):
    """
    Add ``# pylint: disable`` clauses to add exceptions to all existing pylint errors in a codebase.
    """
    errors = defaultdict(lambda: defaultdict(set))
    for pylint_error in parse_pylint_output(pylint_output):
        errors[pylint_error.filename][pylint_error.linenum].add(pylint_error)

    for file_with_errors in sorted(errors):
        try:
            opened_file = open(file_with_errors)
        except IOError:
            LOG.warning(u"Unable to open %s for edits", file_with_errors, exc_info=True)
        else:
            with opened_file as input_file:
                output_lines = []
                for line_num, line in enumerate(input_file, start=1):
                    output_lines.extend(
                        fix_pylint(
                            line,
                            errors[file_with_errors][line_num]
                        )
                    )

            with open(file_with_errors, 'w') as output_file:
                output_file.writelines(output_lines)


Instruction:
Can you write a function in Python 3 where it
prints the help string for the edx_lint command.

Response:
def show_help():
    """Print the help string for the edx_lint command."""
    print("""\
Manage local config files from masters in edx_lint.

Commands:
""")
    for cmd in [write_main, check_main, list_main]:
        print(cmd.__doc__.lstrip("\n"))


Instruction:
Can you create a Python 3 function that
parses an HTML JSON form submission as per the W3C Draft spec.

Response:
def parse_json_form(dictionary, prefix=''):
    """
    Parse an HTML JSON form submission as per the W3C Draft spec
    An implementation of "The application/json encoding algorithm"
    http://www.w3.org/TR/html-json-forms/
    """
    # Step 1: Initialize output object
    output = {}
    for name, value in get_all_items(dictionary):
        # TODO: implement is_file flag

        # Step 2: Compute steps array
        steps = parse_json_path(name)

        # Step 3: Initialize context
        context = output

        # Step 4: Iterate through steps
        for step in steps:
            # Step 4.1 Retrieve current value from context
            current_value = get_value(context, step.key, Undefined())

            # Steps 4.2, 4.3: Set JSON value on context
            context = set_json_value(
                context=context,
                step=step,
                current_value=current_value,
                entry_value=value,
                is_file=False,
            )
    # Convert any remaining Undefined array entries to None
    output = clean_undefined(output)
    output = clean_empty_string(output)

    # Account for DRF prefix (not part of JSON form spec)
    result = get_value(output, prefix, Undefined())
    if isinstance(result, Undefined):
        return output
    else:
        return result


Instruction:
How would you explain what the following Python 3 function does
def parse_json_path(path):

    # Steps 1, 2, 3
    original_path = path
    steps = []

    # Step 11 (Failure)
    failed = [
        JsonStep(
            type="object",
            key=original_path,
            last=True,
            failed=True,
        )
    ]

    # Other variables for later use
    digit_re = re.compile(r'^\[([0-9]+)\]')
    key_re = re.compile(r'^\[([^\]]+)\]')

    # Step 4 - Find characters before first [ (if any)
    parts = path.split("[")
    first_key = parts[0]
    if parts[1:]:
        path = "[" + "[".join(parts[1:])
    else:
        path = ""

    # Step 5 - According to spec, keys cannot start with [
    # NOTE: This was allowed in older DRF versions, so disabling rule for now
    # if not first_key:
    #     return failed

    # Step 6 - Save initial step
    steps.append(JsonStep(
        type="object",
        key=first_key,
    ))

    # Step 7 - Simple single-step case (no [ found)
    if not path:
        steps[-1].last = True
        return steps

    # Step 8 - Loop
    while path:
        # Step 8.1 - Check for single-item array
        if path[:2] == "[]":
            path = path[2:]
            steps.append(JsonStep(
                type="array",
                key=0,
            ))
            continue

        # Step 8.2 - Check for array[index]
        digit_match = digit_re.match(path)
        if digit_match:
            path = digit_re.sub("", path)
            steps.append(JsonStep(
                type="array",
                key=int(digit_match.group(1)),
            ))
            continue

        # Step 8.3 - Check for object[key]
        key_match = key_re.match(path)
        if key_match:
            path = key_re.sub("", path)
            steps.append(JsonStep(
                type="object",
                key=key_match.group(1),
            ))
            continue

        # Step 8.4 - Invalid key format
        return failed

    # Step 9
    next_step = None
    for step in reversed(steps):
        if next_step:
            step.next_type = next_step.type
        else:
            step.last = True
        next_step = step

    return steps

Response: Parses a string as a JSON encoding path


Instruction:
Explain what the following Python 3 code does
def set_json_value(context, step, current_value, entry_value, is_file):

    # TODO: handle is_file

    # Add empty values to array so indexing works like JavaScript
    if isinstance(context, list) and isinstance(step.key, int):
        undefined_count = step.key - len(context) + 1
        if undefined_count > 1000:
            raise ParseException("Too many consecutive empty values!")
        elif undefined_count > 0:
            context += [Undefined()] * undefined_count

    # Step 7: Handle last step
    if step.last:
        if isinstance(current_value, Undefined):
            # Step 7.1: No existing value
            key = step.key
            if isinstance(context, dict) and isinstance(key, int):
                key = str(key)
            if step.append:
                context[key] = [entry_value]
            else:
                context[key] = entry_value
        elif isinstance(current_value, list):
            # Step 7.2: Existing value is an Array, assume multi-valued field
            # and add entry to end.

            # FIXME: What if the other items in the array had explicit keys and
            # this one is supposed to be the "" value?
            # (See step 8.4 and Example 7)
            context[step.key].append(entry_value)

        elif isinstance(current_value, dict) and not is_file:
            # Step 7.3: Existing value is an Object
            return set_json_value(
                context=current_value,
                step=JsonStep(type="object", key="", last=True),
                current_value=current_value.get("", Undefined()),
                entry_value=entry_value,
                is_file=is_file,
            )
        else:
            # Step 7.4: Existing value is a scalar; preserve both values
            context[step.key] = [current_value, entry_value]

        # Step 7.5
        return context

    # Step 8: Handle intermediate steps
    if isinstance(current_value, Undefined):
        # 8.1: No existing value
        if step.next_type == "array":
            context[step.key] = []
        else:
            context[step.key] = {}
        return context[step.key]
    elif isinstance(current_value, dict):
        # Step 8.2: Existing value is an Object
        return get_value(context, step.key, Undefined())
    elif isinstance(current_value, list):
        # Step 8.3: Existing value is an Array
        if step.next_type == "array":
            return current_value
        # Convert array to object to facilitate mixed keys
        obj = {}
        for i, item in enumerate(current_value):
            if not isinstance(item, Undefined):
                obj[str(i)] = item
        context[step.key] = obj
        return obj
    else:
        # 8.4: Existing value is a scalar; convert to Object, preserving
        # current value via an empty key
        obj = {'': current_value}
        context[step.key] = obj
        return obj

Response: Apply a JSON value to a context object object


Instruction:
Write a Python 3 function that can
mimic JavaScript Object / Array behavior by allowing access to nonexistent RSVs and VISA objects.

Response:
def get_value(obj, key, default=None):
    """
    Mimic JavaScript Object/Array behavior by allowing access to nonexistent
    indexes.
    """
    if isinstance(obj, dict):
        return obj.get(key, default)
    elif isinstance(obj, list):
        try:
            return obj[key]
        except IndexError:
            return default


Instruction:
Given the following Python 3 function, write the documentation
def clean_undefined(obj):
    if isinstance(obj, list):
        return [
            None if isinstance(item, Undefined) else item
            for item in obj
        ]
    if isinstance(obj, dict):
        for key in obj:
            obj[key] = clean_undefined(obj[key])
    return obj

Response: Convert Undefined array entries to None ( null


Instruction:
Implement a Python 3 function for
removing empty string values from the object and returns a list of empty strings.

Response:
def clean_empty_string(obj):
    """
    Replace empty form values with None, since the is_html_input() check in
    Field won't work after we convert to JSON.
    (FIXME: What about allow_blank=True?)
    """
    if obj == '':
        return None
    if isinstance(obj, list):
        return [
            None if item == '' else item
            for item in obj
        ]
    if isinstance(obj, dict):
        for key in obj:
            obj[key] = clean_empty_string(obj[key])
    return obj


Instruction:
Given the following Python 3 function, write the documentation
def trans_new(name, transform, inverse, breaks=None,
              minor_breaks=None, _format=None,
              domain=(-np.inf, np.inf), doc='', **kwargs):
    """
    Create a transformation class object

    Parameters
    ----------
    name : str
        Name of the transformation
    transform : callable ``f(x)``
        A function (preferably a `ufunc`) that computes
        the transformation.
    inverse : callable ``f(x)``
        A function (preferably a `ufunc`) that computes
        the inverse of the transformation.
    breaks : callable ``f(limits)``
        Function to compute the breaks for this transform.
        If None, then a default good enough for a linear
        domain is used.
    minor_breaks : callable ``f(major, limits)``
        Function to compute the minor breaks for this
        transform. If None, then a default good enough for
        a linear domain is used.
    _format : callable ``f(breaks)``
        Function to format the generated breaks.
    domain : array_like
        Domain over which the transformation is valid.
        It should be of length 2.
    doc : str
        Docstring for the class.
    **kwargs : dict
        Attributes of the transform, e.g if base is passed
        in kwargs, then `t.base` would be a valied attribute.

    Returns
    -------
    out : trans
        Transform class
    """
    def _get(func):
        if isinstance(func, (classmethod, staticmethod, MethodType)):
            return func
        else:
            return staticmethod(func)

    klass_name = '{}_trans'.format(name)

    d = {'transform': _get(transform),
         'inverse': _get(inverse),
         'domain': domain,
         '__doc__': doc,
         **kwargs}

    if breaks:
        d['breaks_'] = _get(breaks)

    if minor_breaks:
        d['minor_breaks'] = _get(minor_breaks)

    if _format:
        d['format'] = _get(_format)

    return type(klass_name, (trans,), d)

Response: Create a new transcription object.


Instruction:
Write a Python 3 script to
create a log transform class for the base.

Response:
def log_trans(base=None, **kwargs):
    """
    Create a log transform class for *base*

    Parameters
    ----------
    base : float
        Base for the logarithm. If None, then
        the natural log is used.
    kwargs : dict
        Keyword arguments passed onto
        :func:`trans_new`. Should not include
        the `transform` or `inverse`.

    Returns
    -------
    out : type
        Log transform class
    """
    # transform function
    if base is None:
        name = 'log'
        base = np.exp(1)
        transform = np.log
    elif base == 10:
        name = 'log10'
        transform = np.log10
    elif base == 2:
        name = 'log2'
        transform = np.log2
    else:
        name = 'log{}'.format(base)

        def transform(x):
            return np.log(x)/np.log(base)

    # inverse function
    def inverse(x):
        try:
            return base ** x
        except TypeError:
            return [base**val for val in x]

    if 'domain' not in kwargs:
        kwargs['domain'] = (sys.float_info.min, np.inf)

    if 'breaks' not in kwargs:
        kwargs['breaks'] = log_breaks(base=base)

    kwargs['base'] = base
    kwargs['_format'] = log_format(base)

    _trans = trans_new(name, transform, inverse, **kwargs)

    if 'minor_breaks' not in kwargs:
        n = int(base) - 2
        _trans.minor_breaks = trans_minor_breaks(_trans, n=n)

    return _trans


Instruction:
Implement a function in Python 3 to
create a exponential transform class for the base of the logarithm.

Response:
def exp_trans(base=None, **kwargs):
    """
    Create a exponential transform class for *base*

    This is inverse of the log transform.

    Parameters
    ----------
    base : float
        Base of the logarithm
    kwargs : dict
        Keyword arguments passed onto
        :func:`trans_new`. Should not include
        the `transform` or `inverse`.

    Returns
    -------
    out : type
        Exponential transform class
    """
    # default to e
    if base is None:
        name = 'power_e'
        base = np.exp(1)
    else:
        name = 'power_{}'.format(base)

    # transform function
    def transform(x):
        return base ** x

    # inverse function
    def inverse(x):
        return np.log(x)/np.log(base)

    kwargs['base'] = base
    return trans_new(name, transform, inverse, **kwargs)


Instruction:
How would you explain what the following Python 3 function does
def boxcox_trans(p, **kwargs):
    if np.abs(p) < 1e-7:
        return log_trans()

    def transform(x):
        return (x**p - 1) / (p * np.sign(x-1))

    def inverse(x):
        return (np.abs(x) * p + np.sign(x)) ** (1 / p)

    kwargs['p'] = p
    kwargs['name'] = kwargs.get('name', 'pow_{}'.format(p))
    kwargs['transform'] = transform
    kwargs['inverse'] = inverse
    return trans_new(**kwargs)

Response: Returns a new Boxcox Transformation object for the given power parameter.


Instruction:
Can you tell what is the following Python 3 function doing
def probability_trans(distribution, *args, **kwargs):
    import scipy.stats as stats
    cdists = {k for k in dir(stats)
              if hasattr(getattr(stats, k), 'cdf')}
    if distribution not in cdists:
        msg = "Unknown distribution '{}'"
        raise ValueError(msg.format(distribution))

    try:
        doc = kwargs.pop('_doc')
    except KeyError:
        doc = ''

    try:
        name = kwargs.pop('_name')
    except KeyError:
        name = 'prob_{}'.format(distribution)

    def transform(x):
        return getattr(stats, distribution).cdf(x, *args, **kwargs)

    def inverse(x):
        return getattr(stats, distribution).ppf(x, *args, **kwargs)

    return trans_new(name,
                     transform, inverse, domain=(0, 1),
                     doc=doc)

Response: Returns a new random - random - random - random - random - random - random - random - random - random - random - random - random - random - random number


Instruction:
Can you generate a brief explanation for the following Python 3 code
def gettrans(t):
    obj = t
    # Make sure trans object is instantiated
    if isinstance(obj, str):
        name = '{}_trans'.format(obj)
        obj = globals()[name]()
    if callable(obj):
        obj = obj()
    if isinstance(obj, type):
        obj = obj()

    if not isinstance(obj, trans):
        raise ValueError("Could not get transform object.")

    return obj

Response: Returns a trans object for the specified name


Instruction:
Here you have a function in Python 3, explain what it does
def breaks(self, limits):
        # clip the breaks to the domain,
        # e.g. probabilities will be in [0, 1] domain
        vmin = np.max([self.domain[0], limits[0]])
        vmax = np.min([self.domain[1], limits[1]])
        breaks = np.asarray(self.breaks_([vmin, vmax]))

        # Some methods(mpl_breaks, extended_breaks) that
        # calculate breaks take the limits as guide posts and
        # not hard limits.
        breaks = breaks.compress((breaks >= self.domain[0]) &
                                 (breaks <= self.domain[1]))
        return breaks

Response:
Calculate breaks in data space and return them
        in transformed space.


Instruction:
Write a Python 3 function that can
transform from date to a numerical format

Response:
def transform(x):
        """
        Transform from date to a numerical format
        """
        try:
            x = date2num(x)
        except AttributeError:
            # numpy datetime64
            # This is not ideal because the operations do not
            # preserve the np.datetime64 type. May be need
            # a datetime64_trans
            x = [pd.Timestamp(item) for item in x]
            x = date2num(x)
        return x


Instruction:
Explain what the following Python 3 code does
def transform(x):
        # microseconds
        try:
            x = np.array([_x.total_seconds()*10**6 for _x in x])
        except TypeError:
            x = x.total_seconds()*10**6
        return x

Response: Transform from Timeddelta to numerical format


Instruction:
Can you tell what is the following Python 3 function doing
def inverse(x):
        try:
            x = [datetime.timedelta(microseconds=i) for i in x]
        except TypeError:
            x = datetime.timedelta(microseconds=x)
        return x

Response: Transform to Timedelta from numerical format


Instruction:
Explain what the following Python 3 code does
def transform(x):
        # nanoseconds
        try:
            x = np.array([_x.value for _x in x])
        except TypeError:
            x = x.value
        return x

Response: Transform from Timeddelta to numerical format


Instruction:
Can you generate the documentation for the following Python 3 function
def inverse(x):
        try:
            x = [pd.Timedelta(int(i)) for i in x]
        except TypeError:
            x = pd.Timedelta(int(x))
        return x

Response: Transform to Timedelta from numerical format


Instruction:
Here you have a function in Python 3, explain what it does
def rescale(x, to=(0, 1), _from=None):
    if _from is None:
        _from = np.min(x), np.max(x)
    return np.interp(x, _from, to)

Response: Rescales numeric vector to have specified minimum and maximum.


Instruction:
How would you explain what the following Python 3 function does
def rescale_mid(x, to=(0, 1), _from=None, mid=0):
    array_like = True

    try:
        len(x)
    except TypeError:
        array_like = False
        x = [x]

    if not hasattr(x, 'dtype'):
        x = np.asarray(x)

    if _from is None:
        _from = np.array([np.min(x), np.max(x)])
    else:
        _from = np.asarray(_from)

    if (zero_range(_from) or zero_range(to)):
        out = np.repeat(np.mean(to), len(x))
    else:
        extent = 2 * np.max(np.abs(_from - mid))
        out = (x - mid) / extent * np.diff(to) + np.mean(to)

    if not array_like:
        out = out[0]
    return out

Response: Rescales numeric vector to have specified minimum midpoint and maximum midpoint and returns array_like | numeric


Instruction:
Can you generate the documentation for the following Python 3 function
def rescale_max(x, to=(0, 1), _from=None):
    array_like = True

    try:
        len(x)
    except TypeError:
        array_like = False
        x = [x]

    if not hasattr(x, 'dtype'):
        x = np.asarray(x)

    if _from is None:
        _from = np.array([np.min(x), np.max(x)])

    out = x/_from[1] * to[1]

    if not array_like:
        out = out[0]
    return out

Response: Rescales numeric vector to have specified maximum.


Instruction:
Can you generate the documentation for the following Python 3 function
def squish_infinite(x, range=(0, 1)):
    xtype = type(x)

    if not hasattr(x, 'dtype'):
        x = np.asarray(x)

    x[x == -np.inf] = range[0]
    x[x == np.inf] = range[1]

    if not isinstance(x, xtype):
        x = xtype(x)
    return x

Response: Truncates infinite values to a range.


Instruction:
Can you generate the documentation for the following Python 3 function
def squish(x, range=(0, 1), only_finite=True):
    xtype = type(x)

    if not hasattr(x, 'dtype'):
        x = np.asarray(x)

    finite = np.isfinite(x) if only_finite else True

    x[np.logical_and(x < range[0], finite)] = range[0]
    x[np.logical_and(x > range[1], finite)] = range[1]

    if not isinstance(x, xtype):
        x = xtype(x)
    return x

Response: Squish values into range.


Instruction:
Create a Python 3 function for
converting any values outside of range to a new array_like object.

Response:
def censor(x, range=(0, 1), only_finite=True):
    """
    Convert any values outside of range to a **NULL** type object.

    Parameters
    ----------
    x : array_like
        Values to manipulate
    range : tuple
        (min, max) giving desired output range
    only_finite : bool
        If True (the default), will only modify
        finite values.

    Returns
    -------
    x : array_like
        Censored array

    Examples
    --------
    >>> a = [1, 2, np.inf, 3, 4, -np.inf, 5]
    >>> censor(a, (0, 10))
    [1, 2, inf, 3, 4, -inf, 5]
    >>> censor(a, (0, 10), False)
    [1, 2, nan, 3, 4, nan, 5]
    >>> censor(a, (2, 4))
    [nan, 2, inf, 3, 4, -inf, nan]

    Notes
    -----
    All values in ``x`` should be of the same type. ``only_finite`` parameter
    is not considered for Datetime and Timedelta types.

    The **NULL** type object depends on the type of values in **x**.

    - :class:`float` - :py:`float('nan')`
    - :class:`int` - :py:`float('nan')`
    - :class:`datetime.datetime` : :py:`np.datetime64(NaT)`
    - :class:`datetime.timedelta` : :py:`np.timedelta64(NaT)`

    """
    if not len(x):
        return x

    py_time_types = (datetime.datetime, datetime.timedelta)
    np_pd_time_types = (pd.Timestamp, pd.Timedelta,
                        np.datetime64, np.timedelta64)
    x0 = first_element(x)

    # Yes, we want type not isinstance
    if type(x0) in py_time_types:
        return _censor_with(x, range, 'NaT')

    if not hasattr(x, 'dtype') and isinstance(x0, np_pd_time_types):
        return _censor_with(x, range, type(x0)('NaT'))

    x_array = np.asarray(x)
    if pdtypes.is_number(x0) and not isinstance(x0, np.timedelta64):
        null = float('nan')
    elif com.is_datetime_arraylike(x_array):
        null = pd.Timestamp('NaT')
    elif pdtypes.is_datetime64_dtype(x_array):
        null = np.datetime64('NaT')
    elif isinstance(x0, pd.Timedelta):
        null = pd.Timedelta('NaT')
    elif pdtypes.is_timedelta64_dtype(x_array):
        null = np.timedelta64('NaT')
    else:
        raise ValueError(
            "Do not know how to censor values of type "
            "{}".format(type(x0)))

    if only_finite:
        try:
            finite = np.isfinite(x)
        except TypeError:
            finite = np.repeat(True, len(x))
    else:
        finite = np.repeat(True, len(x))

    if hasattr(x, 'dtype'):
        outside = (x < range[0]) | (x > range[1])
        bool_idx = finite & outside
        x = x.copy()
        x[bool_idx] = null
    else:
        x = [null if not range[0] <= val <= range[1] and f else val
             for val, f in zip(x, finite)]

    return x


Instruction:
How would you explain what the following Python 3 function does
def _censor_with(x, range, value=None):
    return [val if range[0] <= val <= range[1] else value
            for val in x]

Response: Censor any values outside of range with value


Instruction:
Can you tell what is the following Python 3 function doing
def zero_range(x, tol=np.finfo(float).eps * 100):
    try:
        if len(x) == 1:
            return True
    except TypeError:
        return True

    if len(x) != 2:
        raise ValueError('x must be length 1 or 2')

    # Deals with array_likes that have non-standard indices
    x = tuple(x)

    # datetime - pandas, cpython
    if isinstance(x[0], (pd.Timestamp, datetime.datetime)):
        # date2num include timezone info, .toordinal() does not
        x = date2num(x)
    # datetime - numpy
    elif isinstance(x[0], np.datetime64):
        return x[0] == x[1]
    # timedelta - pandas, cpython
    elif isinstance(x[0], (pd.Timedelta, datetime.timedelta)):
        x = x[0].total_seconds(), x[1].total_seconds()
    # timedelta - numpy
    elif isinstance(x[0], np.timedelta64):
        return x[0] == x[1]
    elif not isinstance(x[0], (float, int, np.number)):
        raise TypeError(
            "zero_range objects cannot work with objects "
            "of type '{}'".format(type(x[0])))

    if any(np.isnan(x)):
        return np.nan

    if x[0] == x[1]:
        return True

    if all(np.isinf(x)):
        return False

    m = np.abs(x).min()
    if m == 0:
        return False

    return np.abs((x[0] - x[1]) / m) < tol

Response: Returns True if the range of vector x is close to zero.


Instruction:
How would you explain what the following Python 3 function does
def expand_range(range, mul=0, add=0, zero_width=1):
    x = range

    # Enforce tuple
    try:
        x[0]
    except TypeError:
        x = (x, x)

    # The expansion cases
    if zero_range(x):
        new = x[0]-zero_width/2, x[0]+zero_width/2
    else:
        dx = (x[1] - x[0]) * mul + add
        new = x[0]-dx, x[1]+dx

    return new

Response: Expand a range of data with a multiplicative or additive constant.


Instruction:
How would you explain what the following Python 3 function does
def expand_range_distinct(range, expand=(0, 0, 0, 0), zero_width=1):

    if len(expand) == 2:
        expand = tuple(expand) * 2

    lower = expand_range(range, expand[0], expand[1], zero_width)[0]
    upper = expand_range(range, expand[2], expand[3], zero_width)[1]
    return (lower, upper)

Response: Expand a range with a multiplicative or additive constants.


Instruction:
Can you generate the documentation for the following Python 3 function
def _extend_breaks(self, major):
        trans = self.trans
        trans = trans if isinstance(trans, type) else trans.__class__
        # so far we are only certain about this extending stuff
        # making sense for log transform
        is_log = trans.__name__.startswith('log')
        diff = np.diff(major)
        step = diff[0]
        if is_log and all(diff == step):
            major = np.hstack([major[0]-step, major, major[-1]+step])
        return major

Response: Extend the major array with 2 extra breaks at either end of major_breaks or the last major_breaks.


Instruction:
Can you generate the documentation for the following Python 3 function
def best_units(self, sequence):
        # Read
        #   [(0.9, 's'),
        #    (9, 'm)]
        # as, break ranges between 0.9 seconds (inclusive)
        # and 9 minutes are represented in seconds. And so on.
        ts_range = self.value(max(sequence)) - self.value(min(sequence))
        package = self.determine_package(sequence[0])
        if package == 'pandas':
            cuts = [
                (0.9, 'us'),
                (0.9, 'ms'),
                (0.9, 's'),
                (9, 'm'),
                (6, 'h'),
                (4, 'd'),
                (4, 'w'),
                (4, 'M'),
                (3, 'y')]
            denomination = NANOSECONDS
            base_units = 'ns'
        else:
            cuts = [
                (0.9, 's'),
                (9, 'm'),
                (6, 'h'),
                (4, 'd'),
                (4, 'w'),
                (4, 'M'),
                (3, 'y')]
            denomination = SECONDS
            base_units = 'ms'

        for size, units in reversed(cuts):
            if ts_range >= size*denomination[units]:
                return units

        return base_units

Response: Determine good units for representing a sequence of timedeltas


Instruction:
Make a summary of the following Python 3 code
def scaled_limits(self):
        _min = self.limits[0]/self.factor
        _max = self.limits[1]/self.factor
        return _min, _max

Response: Returns the minimum and maximum of the set of resources that are scaled by factor.


Instruction:
Make a summary of the following Python 3 code
def numeric_to_timedelta(self, numerics):
        if self.package == 'pandas':
            return [self.type(int(x*self.factor), units='ns')
                    for x in numerics]
        else:
            return [self.type(seconds=x*self.factor)
                    for x in numerics]

Response: Convert sequence of numerics to timedelta


Instruction:
Implement a Python 3 function for
converting timedelta to a number corresponding to the appropriate units.

Response:
def to_numeric(self, td):
        """
        Convert timedelta to a number corresponding to the
        appropriate units. The appropriate units are those
        determined with the object is initialised.
        """
        if self.package == 'pandas':
            return td.value/NANOSECONDS[self.units]
        else:
            return td.total_seconds()/SECONDS[self.units]


Instruction:
Can you generate the documentation for the following Python 3 function
def round_any(x, accuracy, f=np.round):
    if not hasattr(x, 'dtype'):
        x = np.asarray(x)

    return f(x / accuracy) * accuracy

Response: Round to multiple of any number.


Instruction:
Write a Python 3 function for
returning the minimum and maximum of a sequence of items.

Response:
def min_max(x, na_rm=False, finite=True):
    """
    Return the minimum and maximum of x

    Parameters
    ----------
    x : array_like
        Sequence
    na_rm : bool
        Whether to remove ``nan`` values.
    finite : bool
        Whether to consider only finite values.

    Returns
    -------
    out : tuple
        (minimum, maximum) of x
    """
    if not hasattr(x, 'dtype'):
        x = np.asarray(x)

    if na_rm and finite:
        x = x[np.isfinite(x)]
    elif not na_rm and np.any(np.isnan(x)):
        return np.nan, np.nan
    elif na_rm:
        x = x[~np.isnan(x)]
    elif finite:
        x = x[~np.isinf(x)]

    if (len(x)):
        return np.min(x), np.max(x)
    else:
        return float('-inf'), float('inf')


Instruction:
Can you tell what is the following Python 3 function doing
def match(v1, v2, nomatch=-1, incomparables=None, start=0):
    v2_indices = {}
    for i, x in enumerate(v2):
        if x not in v2_indices:
            v2_indices[x] = i

    v1_to_v2_map = [nomatch] * len(v1)
    skip = set(incomparables) if incomparables else set()
    for i, x in enumerate(v1):
        if x in skip:
            continue

        try:
            v1_to_v2_map[i] = v2_indices[x] + start
        except KeyError:
            pass

    return v1_to_v2_map

Response: Returns a vector of the positions of v1 that matches v2.


Instruction:
Make a summary of the following Python 3 code
def precision(x):
    from .bounds import zero_range

    rng = min_max(x, na_rm=True)
    if zero_range(rng):
        span = np.abs(rng[0])
    else:
        span = np.diff(rng)[0]

    if span == 0:
        return 1
    else:
        return 10 ** int(np.floor(np.log10(span)))

Response: Returns the precision of x.


Instruction:
Explain what the following Python 3 code does
def multitype_sort(a):
    types = defaultdict(list)
    numbers = {int, float, complex}

    for x in a:
        t = type(x)
        if t in numbers:
            types['number'].append(x)
        else:
            types[t].append(x)

    for t in types:
        types[t] = np.sort(types[t])

    return list(chain(*(types[t] for t in types)))

Response:
Sort elements of multiple types
    x is assumed to contain elements of different types such that
    plain sort would raise a TypeError.


Instruction:
Can you generate the documentation for the following Python 3 function
def nearest_int(x):
    if x == 0:
        return np.int64(0)
    elif x > 0:
        return np.int64(x + 0.5)
    else:
        return np.int64(x - 0.5)

Response: Return nearest long integer to x


Instruction:
Implement a function in Python 3 to
check if value is close to an integer.

Response:
def is_close_to_int(x):
    """
    Check if value is close to an integer

    Parameters
    ----------
    x : float
        Numeric value to check

    Returns
    -------
    out : bool
    """
    if not np.isfinite(x):
        return False
    return abs(x - nearest_int(x)) < 1e-10


Instruction:
Can you generate a brief explanation for the following Python 3 code
def same_log10_order_of_magnitude(x, delta=0.1):
    dmin = np.log10(np.min(x)*(1-delta))
    dmax = np.log10(np.max(x)*(1+delta))
    return np.floor(dmin) == np.floor(dmax)

Response: Returns True if the given array - like object x is approximately in same order of magnitude as the base 10.