Instruction:
Given the following Python 3 function, write the documentation
def swarm(self, x, y, r=100):
        sc = _ctx.stroke(0, 0, 0, 0)
        sw = _ctx.strokewidth(0)

        _ctx.push()
        _ctx.transform(_ctx.CORNER)
        _ctx.translate(x, y)

        for i in _range(r * 3):
            clr = choice(self).copy()
            clr.alpha -= 0.5 * random()
            _ctx.fill(clr)
            clr = choice(self)
            _ctx.stroke(clr)
            _ctx.strokewidth(10 * random())

            _ctx.rotate(360 * random())

            r2 = r * 0.5 * random()
            _ctx.oval(r * random(), 0, r2, r2)
        _ctx.pop()

        _ctx.strokewidth(sw)
        if sc is None:
            _ctx.nostroke()
        else:
            _ctx.stroke(sc)

Response: Fancy random ovals for all the colors in the list.


Instruction:
Given the following Python 3 function, write the documentation
def _interpolate(self, colors, n=100):

        """ Returns intermediary colors for given list of colors.
        """

        gradient = []
        for i in _range(n):
            l = len(colors) - 1
            x = int(1.0 * i / n * l)
            x = min(x + 0, l)
            y = min(x + 1, l)

            base = 1.0 * n / l * x
            d = (i - base) / (1.0 * n / l)
            r = colors[x].r * (1 - d) + colors[y].r * d
            g = colors[x].g * (1 - d) + colors[y].g * d
            b = colors[x].b * (1 - d) + colors[y].b * d
            a = colors[x].a * (1 - d) + colors[y].a * d

            gradient.append(color(r, g, b, a, mode="rgb"))

        gradient.append(colors[-1])
        return gradient

Response: Interpolates the given list of colors.


Instruction:
Can you generate the documentation for the following Python 3 function
def _cache(self):
        n = self.steps

        # Only one color in base list.
        if len(self._colors) == 1:
            ColorList.__init__(self, [self._colors[0] for i in _range(n)])
            return

        # Expand the base list so we can chop more accurately.
        colors = self._interpolate(self._colors, 40)

        # Chop into left half and right half.
        # Make sure their ending and beginning match colors.
        left = colors[:len(colors) / 2]
        right = colors[len(colors) / 2:]
        left.append(right[0])
        right.insert(0, left[-1])

        # Calculate left and right gradient proportionally to spread.
        gradient = self._interpolate(left, int(n * self.spread))[:-1]
        gradient.extend(
            self._interpolate(right, n - int(n * self.spread))[1:]
        )

        if self.spread > 1: gradient = gradient[:n]
        if self.spread < 0: gradient = gradient[-n:]
        ColorList.__init__(self, gradient)

Response: Generates a list of colors that can be used to generate the log entries for a specific base color.


Instruction:
Here you have a function in Python 3, explain what it does
def copy(self, clr=None, d=0.0):
        cr = ColorRange()
        cr.name = self.name

        cr.h = deepcopy(self.h)
        cr.s = deepcopy(self.s)
        cr.b = deepcopy(self.b)
        cr.a = deepcopy(self.a)

        cr.grayscale = self.grayscale
        if not self.grayscale:
            cr.black = self.black.copy()
            cr.white = self.white.copy()

        if clr != None:
            cr.h, cr.a = clr.h + d * (random() * 2 - 1), clr.a

        return cr

Response: Returns a copy of the range.


Instruction:
Write a Python 3 script to
return a random color from the color range.

Response:
def color(self, clr=None, d=0.035):
        """
        Returns a color with random values in the defined h, s b, a ranges.

        If a color is given, use that color's hue and alpha,
        and generate its saturation and brightness from the shade.
        The hue is varied with the given d.

        In this way you could have a "warm" color range
        that returns all kinds of warm colors.
        When a red color is given as parameter it would generate
        all kinds of warm red colors.
        """
        # Revert to grayscale for black, white and grey hues.
        if clr != None and not isinstance(clr, Color):
            clr = color(clr)
        if clr != None and not self.grayscale:
            if clr.is_black: return self.black.color(clr, d)
            if clr.is_white: return self.white.color(clr, d)
            if clr.is_grey: return choice(
                (self.black.color(clr, d), self.white.color(clr, d))
            )

        h, s, b, a = self.h, self.s, self.b, self.a
        if clr != None:
            h, a = clr.h + d * (random() * 2 - 1), clr.a

        hsba = []
        for v in [h, s, b, a]:
            if isinstance(v, _list):
                min, max = choice(v)
            elif isinstance(v, tuple):
                min, max = v
            else:
                min, max = v, v
            hsba.append(min + (max - min) * random())

        h, s, b, a = hsba
        return color(h, s, b, a, mode="hsb")


Instruction:
Write a Python 3 function that can
return True if the given color is part of this color range.

Response:
def contains(self, clr):
        """
        Returns True if the given color is part of this color range.

        Check whether each h, s, b, a component of the color
        falls within the defined range for that component.

        If the given color is grayscale,
        checks against the definitions for black and white.
        """
        if not isinstance(clr, Color):
            return False

        if not isinstance(clr, _list):
            clr = [clr]

        for clr in clr:

            if clr.is_grey and not self.grayscale:
                return (self.black.contains(clr) or \
                        self.white.contains(clr))

            for r, v in [(self.h, clr.h), (self.s, clr.s), (self.b, clr.brightness), (self.a, clr.a)]:
                if isinstance(r, _list):
                    pass
                elif isinstance(r, tuple):
                    r = [r]
                else:
                    r = [(r, r)]
                for min, max in r:
                    if not (min <= v <= max):
                        return False

        return True


Instruction:
Can you generate the documentation for the following Python 3 function
def _weight_by_hue(self):
        grouped = {}
        weights = []
        for clr, rng, weight in self.ranges:
            h = clr.nearest_hue(primary=False)
            if grouped.has_key(h):
                ranges, total_weight = grouped[h]
                ranges.append((clr, rng, weight))
                total_weight += weight
                grouped[h] = (ranges, total_weight)
            else:
                grouped[h] = ([(clr, rng, weight)], weight)

        # Calculate the normalized (0.0-1.0) weight for each hue,
        # and transform the dictionary to a list.
        s = 1.0 * sum([w for r, w in grouped.values()])
        grouped = [(grouped[h][1], grouped[h][1] / s, h, grouped[h][0]) for h in grouped]
        grouped.sort()
        grouped.reverse()

        return grouped

Response: Returns a list of tuples that are weight per hue.


Instruction:
Given the following Python 3 function, write the documentation
def _xml(self):
        grouped = self._weight_by_hue()

        xml = "<colors query=\"" + self.name + "\" tags=\"" + ", ".join(self.tags) + "\">\n\n"
        for total_weight, normalized_weight, hue, ranges in grouped:
            if hue == self.blue: hue = "blue"
            clr = color(hue)
            xml += "\t<color name=\"" + clr.name + "\" weight=\"" + str(normalized_weight) + "\">\n "
            xml += "\t\t<rgb r=\"" + str(clr.r) + "\" g=\"" + str(clr.g) + "\" "
            xml += "b=\"" + str(clr.b) + "\" a=\"" + str(clr.a) + "\" />\n "
            for clr, rng, wgt in ranges:
                xml += "\t\t<shade name=\"" + str(rng) + "\" weight=\"" + str(wgt / total_weight) + "\" />\n "
            xml = xml.rstrip(" ") + "\t</color>\n\n"
        xml += "</colors>"

        return xml

Response: Returns the color information as XML.


Instruction:
Can you create a Python 3 function that
saves the color information in the cache as XML.

Response:
def _save(self):
        """
        Saves the color information in the cache as XML.
        """
        if not os.path.exists(self.cache):
            os.makedirs(self.cache)

        path = os.path.join(self.cache, self.name + ".xml")
        f = open(path, "w")
        f.write(self.xml)
        f.close()


Instruction:
Create a Python 3 function for
loading a theme from aggregated web data.

Response:
def _load(self, top=5, blue="blue", archive=None, member=None):
        """
        Loads a theme from aggregated web data.

        The data must be old-style Prism XML: <color>s consisting of <shade>s.
        Colors named "blue" will be overridden with the blue parameter.

        archive can be a file like object (e.g. a ZipFile)
        and will be used along with 'member' if specified.
        """
        if archive is None:
            path = os.path.join(self.cache, self.name + ".xml")
            xml = open(path).read()
        else:
            assert member is not None
            xml = archive.read(member)
        dom = parseString(xml).documentElement

        attr = lambda e, a: e.attributes[a].value

        for e in dom.getElementsByTagName("color")[:top]:
            w = float(attr(e, "weight"))
            try:
                rgb = e.getElementsByTagName("rgb")[0]
                clr = color(
                    float(attr(rgb, "r")),
                    float(attr(rgb, "g")),
                    float(attr(rgb, "b")),
                    float(attr(rgb, "a")),
                    mode="rgb"
                )
                try:
                    clr.name = attr(e, "name")
                    if clr.name == "blue": clr = color(blue)
                except:
                    pass
            except:
                name = attr(e, "name")
                if name == "blue": name = blue
                clr = color(name)

            for s in e.getElementsByTagName("shade"):
                self.ranges.append((
                    clr,
                    shade(attr(s, "name")),
                    w * float(attr(s, "weight"))
                ))


Instruction:
Here you have a function in Python 3, explain what it does
def color(self, d=0.035):
        s = sum([w for clr, rng, w in self.ranges])
        r = random()
        for clr, rng, weight in self.ranges:
            if weight / s >= r: break
            r -= weight / s

        return rng(clr, d)

Response: Returns a random color within the theme.


Instruction:
Write a Python 3 function that can
return a number of random colors from the theme.

Response:
def colors(self, n=10, d=0.035):
        """
        Returns a number of random colors from the theme.
        """
        s = sum([w for clr, rng, w in self.ranges])
        colors = colorlist()
        for i in _range(n):
            r = random()
            for clr, rng, weight in self.ranges:
                if weight / s >= r: break
                r -= weight / s
            colors.append(rng(clr, d))

        return colors


Instruction:
Explain what the following Python 3 code does
def swatch(self, x, y, w=35, h=35, padding=4, roundness=0, n=12, d=0.035, grouped=None):
        if grouped is None:  # should be True or False
            grouped = self.group_swatches

        # If we dont't need to make groups,
        # just display an individual column for each weight
        # in the (color, range, weight) tuples.
        if not grouped:
            s = sum([wgt for clr, rng, wgt in self.ranges])
            for clr, rng, wgt in self.ranges:
                cols = max(1, int(wgt / s * n))
                for i in _range(cols):
                    rng.colors(clr, n=n, d=d).swatch(x, y, w, h, padding=padding, roundness=roundness)
                    x += w + padding

            return x, y + n * (h + padding)

        # When grouped, combine hues and display them
        # in batches of rows, then moving on to the next hue.
        grouped = self._weight_by_hue()
        for total_weight, normalized_weight, hue, ranges in grouped:
            dy = y
            rc = 0
            for clr, rng, weight in ranges:
                dx = x
                cols = int(normalized_weight * n)
                cols = max(1, min(cols, n - len(grouped)))
                if clr.name == "black": rng = rng.black
                if clr.name == "white": rng = rng.white
                for i in _range(cols):
                    rows = int(weight / total_weight * n)
                    rows = max(1, rows)
                    # Each column should add up to n rows,
                    # if not due to rounding errors, add a row at the bottom.
                    if (clr, rng, weight) == ranges[-1] and rc + rows < n: rows += 1
                    rng.colors(clr, n=rows, d=d).swatch(dx, dy, w, h, padding=padding, roundness=roundness)
                    dx += w + padding
                dy += (w + padding) * rows  # + padding
                rc = rows
            x += (w + padding) * cols + padding

        return x, dy

Response: Draw a weighted swatch with approximately n columns and rows and padding.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def objs(self):
        for obj in self.objects.itervalues():
            if obj.sessionid in self.sessions:
                yield obj

Response:
Returns a generator of tracked objects which are recognized with
        this profile and are in the current session.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def _append_element(self, render_func, pe):
        '''
        Append a render function and the parameters to pass
        an equivilent PathElement, or the PathElement itself.
        '''
        self._render_funcs.append(render_func)
        self._elements.append(pe)

Response:
Append a render function and the parameters to pass
        an equivilent PathElement.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def _get_bounds(self):
        '''
        Return cached bounds of this Grob.
        If bounds are not cached, render to a meta surface, and
        keep the meta surface and bounds cached.
        '''
        if self._bounds:
            return self._bounds

        record_surface = cairo.RecordingSurface(cairo.CONTENT_COLOR_ALPHA, (-1, -1, 1, 1))
        dummy_ctx = cairo.Context(record_surface)
        self._traverse(dummy_ctx)

        self._bounds = dummy_ctx.path_extents()
        return self._bounds

Response: Get the bounds of this Grob.


Instruction:
Write a Python 3 script to
return True if the grob contains the given point.

Response:
def contains(self, x, y):
        '''
        Return cached bounds of this Grob.
        If bounds are not cached, render to a meta surface, and
        keep the meta surface and bounds cached.
        '''
        if self._bounds:
            return self._bounds

        record_surface = cairo.RecordingSurface(cairo.CONTENT_COLOR_ALPHA, (-1, -1, 1, 1))
        dummy_ctx = cairo.Context(record_surface)
        self._traverse(dummy_ctx)

        in_fill = dummy_ctx.in_fill(x, y)
        return in_fill


Instruction:
Explain what the following Python 3 code does
def _get_center(self):
        '''
        Return cached bounds of this Grob.
        If bounds are not cached, render to a meta surface, and
        keep the meta surface and bounds cached.
        '''
        if self._center:
            return self._center

        # get the center point
        (x1, y1, x2, y2) = self._get_bounds()
        x = (x1 + x2) / 2
        y = (y1 + y2) / 2

        center = self._center = x, y
        # TODO Cache function that draws using the RecordingSurface
        # Save the context or surface (without the bounding box strokecolor)
        # to optimise drawing
        return center

Response: Get the center point of the current grob.


Instruction:
Make a summary of the following Python 3 code
def _render_closure(self):
        '''Use a closure so that draw attributes can be saved'''
        fillcolor = self.fill
        strokecolor = self.stroke
        strokewidth = self.strokewidth

        def _render(cairo_ctx):
            '''
            At the moment this is based on cairo.

            TODO: Need to work out how to move the cairo specific
                  bits somewhere else.
            '''
            # Go to initial point (CORNER or CENTER):
            transform = self._call_transform_mode(self._transform)

            if fillcolor is None and strokecolor is None:
                # Fixes _bug_FillStrokeNofillNostroke.bot
                return

            cairo_ctx.set_matrix(transform)
            # Run the path commands on the cairo context:
            self._traverse(cairo_ctx)
            # Matrix affects stroke, so we need to reset it:
            cairo_ctx.set_matrix(cairo.Matrix())

            if fillcolor is not None and strokecolor is not None:
                if strokecolor[3] < 1:
                    # Draw onto intermediate surface so that stroke
                    # does not overlay fill
                    cairo_ctx.push_group()

                    cairo_ctx.set_source_rgba(*fillcolor)
                    cairo_ctx.fill_preserve()

                    e = cairo_ctx.stroke_extents()
                    cairo_ctx.set_source_rgba(*strokecolor)
                    cairo_ctx.set_operator(cairo.OPERATOR_SOURCE)
                    cairo_ctx.set_line_width(strokewidth)
                    cairo_ctx.stroke()

                    cairo_ctx.pop_group_to_source()
                    cairo_ctx.paint()
                else:
                    # Fast path if no alpha in stroke
                    cairo_ctx.set_source_rgba(*fillcolor)
                    cairo_ctx.fill_preserve()

                    cairo_ctx.set_source_rgba(*strokecolor)
                    cairo_ctx.set_line_width(strokewidth)
                    cairo_ctx.stroke()
            elif fillcolor is not None:
                cairo_ctx.set_source_rgba(*fillcolor)
                cairo_ctx.fill()
            elif strokecolor is not None:
                cairo_ctx.set_source_rgba(*strokecolor)
                cairo_ctx.set_line_width(strokewidth)
                cairo_ctx.stroke()

        return _render

Response: Render the image on the context.


Instruction:
Can you write a function in Python 3 where it
locates t on a specific segment in the path.

Response:
def _locate(self, t, segments=None):
        """ Locates t on a specific segment in the path.
            Returns (index, t, PathElement)
            A path is a combination of lines and curves (segments).
            The returned index indicates the start of the segment that contains point t.
            The returned t is the absolute time on that segment,
            in contrast to the relative t on the whole of the path.
            The returned point is the last MOVETO, any subsequent CLOSETO after i closes to that point.
            When you supply the list of segment lengths yourself, as returned from length(path, segmented=True),
            point() works about thirty times faster in a for-loop since it doesn't need to recalculate
            the length during each iteration.
        """
        # Originally from nodebox-gl
        if segments is None:
            segments = self._segment_lengths(relative=True)
        if len(segments) == 0:
            raise PathError, "The given path is empty"
        for i, el in enumerate(self._get_elements()):
            if i == 0 or el.cmd == MOVETO:
                closeto = Point(el.x, el.y)
            if t <= segments[i] or i == len(segments) - 1:
                break
            else:
                t -= segments[i]
        try:
            t /= segments[i]
        except ZeroDivisionError:
            pass
        if i == len(segments) - 1 and segments[i] == 0:
            i -= 1
        return (i, t, closeto)


Instruction:
How would you explain what the following Python 3 function does
def point(self, t, segments=None):
        # Originally from nodebox-gl
        if len(self._elements) == 0:
            raise PathError("The given path is empty")

        if self._segments is None:
            self._segments = self._get_length(segmented=True, precision=10)

        i, t, closeto = self._locate(t, segments=self._segments)
        x0, y0 = self[i].x, self[i].y
        p1 = self[i + 1]
        if p1.cmd == CLOSE:
            x, y = self._linepoint(t, x0, y0, closeto.x, closeto.y)
            return PathElement(LINETO, x, y)
        elif p1.cmd in (LINETO, MOVETO):
            x1, y1 = p1.x, p1.y
            x, y = self._linepoint(t, x0, y0, x1, y1)
            return PathElement(LINETO, x, y)
        elif p1.cmd == CURVETO:
            # Note: the handles need to be interpreted differenty than in a BezierPath.
            # In a BezierPath, ctrl1 is how the curve started, and ctrl2 how it arrives in this point.
            # Here, ctrl1 is how the curve arrives, and ctrl2 how it continues to the next point.
            x3, y3, x1, y1, x2, y2 = p1.x, p1.y, p1.ctrl1.x, p1.ctrl1.y, p1.ctrl2.x, p1.ctrl2.y
            x, y, c1x, c1y, c2x, c2y = self._curvepoint(t, x0, y0, x1, y1, x2, y2, x3, y3)
            return PathElement(CURVETO, c1x, c1y, c2x, c2y, x, y)
        else:
            raise PathError("Unknown cmd '%s' for p1 %s" % (p1.cmd, p1))

Response: Returns the coordinates for a point on the path.


Instruction:
Here you have a function in Python 3, explain what it does
def points(self, amount=100, start=0.0, end=1.0, segments=None):
        # Originally from nodebox-gl
        if len(self._elements) == 0:
            raise PathError("The given path is empty")
        n = end - start
        d = n
        if amount > 1:
            # The delta value is divided by amount-1, because we also want the last point (t=1.0)
            # If we don't use amount-1, we fall one point short of the end.
            # If amount=4, we want the point at t 0.0, 0.33, 0.66 and 1.0.
            # If amount=2, we want the point at t 0.0 and 1.0.
            d = float(n) / (amount - 1)
        for i in xrange(int(amount)):
            yield self.point(start + d * i, segments)

Response: Returns an iterator with a list of points for the given path.


Instruction:
Here you have a function in Python 3, explain what it does
def _linepoint(self, t, x0, y0, x1, y1):
        # Originally from nodebox-gl
        out_x = x0 + t * (x1 - x0)
        out_y = y0 + t * (y1 - y0)
        return (out_x, out_y)

Response: Returns the coordinates of the line that points at t on the line.


Instruction:
Create a Python 3 function to
return the length of the line.

Response:
def _linelength(self, x0, y0, x1, y1):
        """ Returns the length of the line.
        """
        # Originally from nodebox-gl
        a = pow(abs(x0 - x1), 2)
        b = pow(abs(y0 - y1), 2)
        return sqrt(a + b)


Instruction:
Can you tell what is the following Python 3 function doing
def _curvepoint(self, t, x0, y0, x1, y1, x2, y2, x3, y3, handles=False):
        # Originally from nodebox-gl
        mint = 1 - t
        x01 = x0 * mint + x1 * t
        y01 = y0 * mint + y1 * t
        x12 = x1 * mint + x2 * t
        y12 = y1 * mint + y2 * t
        x23 = x2 * mint + x3 * t
        y23 = y2 * mint + y3 * t
        out_c1x = x01 * mint + x12 * t
        out_c1y = y01 * mint + y12 * t
        out_c2x = x12 * mint + x23 * t
        out_c2y = y12 * mint + y23 * t
        out_x = out_c1x * mint + out_c2x * t
        out_y = out_c1y * mint + out_c2y * t
        if not handles:
            return (out_x, out_y, out_c1x, out_c1y, out_c2x, out_c2y)
        else:
            return (out_x, out_y, out_c1x, out_c1y, out_c2x, out_c2y, x01, y01, x23, y23)

Response: Returns the coordinates of a curve point at t.


Instruction:
Here you have a function in Python 3, explain what it does
def _segment_lengths(self, relative=False, n=20):
        # From nodebox_gl
        lengths = []
        first = True
        for el in self._get_elements():
            if first is True:
                close_x, close_y = el.x, el.y
                first = False
            elif el.cmd == MOVETO:
                close_x, close_y = el.x, el.y
                lengths.append(0.0)
            elif el.cmd == CLOSE:
                lengths.append(self._linelength(x0, y0, close_x, close_y))
            elif el.cmd == LINETO:
                lengths.append(self._linelength(x0, y0, el.x, el.y))
            elif el.cmd == CURVETO:
                x3, y3, x1, y1, x2, y2 = el.x, el.y, el.c1x, el.c1y, el.c2x, el.c2y
                # (el.c1x, el.c1y, el.c2x, el.c2y, el.x, el.y)
                lengths.append(self._curvelength(x0, y0, x1, y1, x2, y2, x3, y3, n))
            if el.cmd != CLOSE:
                x0 = el.x
                y0 = el.y
        if relative:
            length = sum(lengths)
            try:
                # Relative segment lengths' sum is 1.0.
                return map(lambda l: l / length, lengths)
            except ZeroDivisionError:
                # If the length is zero, just return zero for all segments
                return [0.0] * len(lengths)
        else:
            return lengths

Response: Returns a list with the lengths of each segment in the path.


Instruction:
Write a Python 3 script for
returning the length of the path.

Response:
def _get_length(self, segmented=False, precision=10):
        """ Returns the length of the path.
            Calculates the length of each spline in the path, using n as a number of points to measure.
            When segmented is True, returns a list containing the individual length of each spline
            as values between 0.0 and 1.0, defining the relative length of each spline
            in relation to the total path length.
        """
        # Originally from nodebox-gl
        if not segmented:
            return sum(self._segment_lengths(n=precision), 0.0)
        else:
            return self._segment_lengths(relative=True, n=precision)


Instruction:
Given the following Python 3 function, write the documentation
def _get_elements(self):
        '''
        Yields all elements as PathElements
        '''
        for index, el in enumerate(self._elements):
            if isinstance(el, tuple):
                el = PathElement(*el)
                self._elements[index] = el
            yield el

Response: Yields all elements as PathElements


Instruction:
Here you have a function in Python 3, explain what it does
def depth_first_search(root, visit=lambda node: False, traversable=lambda node, edge: True):

    """ Simple, multi-purpose depth-first search.

    Visits all the nodes connected to the root, depth-first.
    The visit function is called on each node.
    Recursion will stop if it returns True, and ubsequently dfs() will return True.
    The traversable function takes the current node and edge,
    and returns True if we are allowed to follow this connection to the next node.
    For example, the traversable for directed edges is follows:
    lambda node, edge: node == edge.node1

    Note: node._visited is expected to be False for all nodes.

    """

    stop = visit(root)
    root._visited = True
    for node in root.links:
        if stop: return True
        if not traversable(root, root.links.edge(node)): continue
        if not node._visited:
            stop = depth_first_search(node, visit, traversable)
    return stop

Response: Simple depth - first search.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def adjacency(graph, directed=False, reversed=False, stochastic=False, heuristic=None):

    """ An edge weight map indexed by node id's.

    A dictionary indexed by node id1's in which each value is a
    dictionary of connected node id2's linking to the edge weight.
    If directed, edges go from id1 to id2, but not the other way.
    If stochastic, all the weights for the neighbors of a given node sum to 1.
    A heuristic can be a function that takes two node id's and returns
    and additional cost for movement between the two nodes.

    """

    v = {}
    for n in graph.nodes:
        v[n.id] = {}

    for e in graph.edges:

        id1 = e.node1.id
        id2 = e.node2.id
        if reversed:
            id1, id2 = id2, id1

        #if not v.has_key(id1): v[id1] = {}
        #if not v.has_key(id2): v[id2] = {}
        v[id1][id2] = 1.0 - e.weight*0.5

        if heuristic:
            v[id1][id2] += heuristic(id1, id2)

        if not directed:
            v[id2][id1] = v[id1][id2]

    if stochastic:
        for id1 in v:
            d = sum(v[id1].values())
            for id2 in v[id1]:
                v[id1][id2] /= d

    return v

Response: Returns a dictionary of adjacency of a graph.


Instruction:
Create a Python 3 function to
return a dictionary of brandes betweenness centrality for nodes in the graph.

Response:
def brandes_betweenness_centrality(graph, normalized=True):

    """ Betweenness centrality for nodes in the graph.

    Betweenness centrality is a measure of the number of shortests paths that pass through a node.
    Nodes in high-density areas will get a good score.

    The algorithm is Brandes' betweenness centrality,
    from NetworkX 0.35.1: Aric Hagberg, Dan Schult and Pieter Swart,
    based on Dijkstra's algorithm for shortest paths modified from Eppstein.
    https://networkx.lanl.gov/wiki

    """

    G = graph.keys()
    W = adjacency(graph)

    betweenness = dict.fromkeys(G, 0.0) # b[v]=0 for v in G
    for s in G:
        S = []
        P = {}
        for v in G: P[v] = []
        sigma = dict.fromkeys(G, 0) # sigma[v]=0 for v in G
        D = {}
        sigma[s] = 1
        seen = { s: 0 }
        Q = [] # use Q as heap with (distance, node id) tuples
        heapq.heappush(Q, (0, s, s))
        while Q:
            (dist, pred, v) = heapq.heappop(Q)
            if v in D: continue # already searched this node
            sigma[v] = sigma[v] + sigma[pred] # count paths
            S.append(v)
            D[v] = seen[v]
            for w in graph[v].links:

                w = w.id
                vw_dist = D[v] + W[v][w]

                if w not in D and (w not in seen or vw_dist < seen[w]):
                    seen[w] = vw_dist
                    heapq.heappush(Q, (vw_dist, v, w))
                    P[w] = [v]
                elif vw_dist == seen[w]: # handle equal paths
                    sigma[w] = sigma[w] + sigma[v]
                    P[w].append(v)

        delta = dict.fromkeys(G,0)
        while S:
            w = S.pop()
            for v in P[w]:
                delta[v] = delta[v] + (float(sigma[v]) / float(sigma[w])) * (1.0 + delta[w])
            if w != s:
                betweenness[w] = betweenness[w] + delta[w]

        #-----------------------------------
        if normalized:
            # Normalize between 0.0 and 1.0.
            m = max(betweenness.values())
            if m == 0: m = 1
        else:
            m = 1

        betweenness = dict([(id, w/m) for id, w in betweenness.iteritems()])
        return betweenness


Instruction:
Can you generate a brief explanation for the following Python 3 code
def eigenvector_centrality(graph, normalized=True, reversed=True, rating={},
                           start=None, iterations=100, tolerance=0.0001):

    """ Eigenvector centrality for nodes in the graph (like Google's PageRank).

    Eigenvector centrality is a measure of the importance of a node in a directed network.
    It rewards nodes with a high potential of (indirectly) connecting to high-scoring nodes.
    Nodes with no incoming connections have a score of zero.
    If you want to measure outgoing connections, reversed should be False.

    The eigenvector calculation is done by the power iteration method.
    It has no guarantee of convergence.
    A starting vector for the power iteration can be given in the start dict.

    You can adjust the importance of a node with the rating dictionary,
    which links node id's to a score.

    The algorithm is adapted from NetworkX, Aric Hagberg (hagberg@lanl.gov):
    https://networkx.lanl.gov/attachment/ticket/119/eigenvector_centrality.py

    """

    G = graph.keys()
    W = adjacency (graph, directed=True, reversed=reversed)

    def _normalize(x):
        s = sum(x.values())
        if s != 0: s = 1.0 / s
        for k in x:
            x[k] *= s

    x = start
    if x is None:
        x = dict([(n, random()) for n in G])
    _normalize(x)

    # Power method: y = Ax multiplication.
    for i in range(iterations):
        x0 = x
        x = dict.fromkeys(x0.keys(), 0)
        for n in x:
            for nbr in W[n]:
                r = 1
                if rating.has_key(n): r = rating[n]
                x[n] += 0.01 + x0[nbr] * W[n][nbr] * r
        _normalize(x)
        e = sum([abs(x[n]-x0[n]) for n in x])
        if e < len(graph.nodes) * tolerance:
            if normalized:
                # Normalize between 0.0 and 1.0.
                m = max(x.values())
                if m == 0: m = 1
                x = dict([(id, w/m) for id, w in x.iteritems()])
            return x

    #raise NoConvergenceError
    warn("node weight is 0 because eigenvector_centrality() did not converge.", Warning)
    return dict([(n, 0) for n in G])

Response: Eigenvector centrality for nodes in a directed network.


Instruction:
Make a summary of the following Python 3 code
def examples_menu(root_dir=None, depth=0):
    # pre 3.12 menus
    examples_dir = ide_utils.get_example_dir()
    if not examples_dir:
        return "", [], []

    root_dir = root_dir or examples_dir

    file_tmpl = '<menuitem name="{name}" action="{action}"/>'
    dir_tmpl = '<menu name="{name}" action="{action}">{menu}</menu>'

    file_actions = []
    submenu_actions = []

    xml = ""

    for fn in sorted(os.listdir(root_dir)):
        path = os.path.join(root_dir, fn)
        rel_path = path[len(examples_dir):]
        if os.path.isdir(path):
            action = 'ShoebotExampleMenu {0}'.format(rel_path)
            label = fn.capitalize()

            sm_xml, sm_file_actions, sm_menu_actions = examples_menu(os.path.join(root_dir, fn), depth+1)

            submenu_actions.extend(sm_menu_actions)
            file_actions.extend(sm_file_actions)
            submenu_actions.append((action, label))
            xml += dir_tmpl.format(name=fn, action=action, menu=sm_xml)
        elif os.path.splitext(path)[1] in ['.bot', '.py'] and not fn.startswith('_'):
            action = 'ShoebotExampleOpen {0}'.format(rel_path)
            label = ide_utils.make_readable_filename(fn)

            xml += file_tmpl.format(name=fn, action=action)
            file_actions.append((action, label))

    return xml, file_actions, submenu_actions

Response: returns xml for menu and sub - menus


Instruction:
Explain what the following Python 3 code does
def mk_examples_menu(text, root_dir=None, depth=0):
    # 3.12+ menus
    examples_dir = ide_utils.get_example_dir()
    if not examples_dir:
        return None, []

    root_dir = root_dir or examples_dir

    file_actions = []

    menu = Gio.Menu.new()
    base_item = Gio.MenuItem.new_submenu(text, menu)

    for fn in sorted(os.listdir(root_dir)):
        path = os.path.join(root_dir, fn)
        rel_path = path[len(examples_dir):]
        if os.path.isdir(path):
            label = fn.capitalize()

            item, sm_file_actions = mk_examples_menu(label, os.path.join(root_dir, fn))
            menu.append_item(item)

            file_actions.extend(sm_file_actions)
        elif os.path.splitext(path)[1] in ['.bot', '.py'] and not fn.startswith('_'):
            label = ide_utils.make_readable_filename(fn)

            # the only way I could work out to attach the data to the menu item is in the name :/
            action_name = "win.open_example__%s" % encode_relpath(rel_path)

            menu.append(label, action_name)
            file_actions.append(rel_path)

    return base_item, file_actions

Response: Create a menu with examples.


Instruction:
How would you explain what the following Python 3 function does
def get_child_by_name(parent, name):
    # http://stackoverflow.com/questions/2072976/access-to-widget-in-gtk
    def iterate_children(widget, name):
        if widget.get_name() == name:
            return widget
        try:
            for w in widget.get_children():
                result = iterate_children(w, name)
                if result is not None:
                    return result
                else:
                    continue
        except AttributeError:
            pass
    return iterate_children(parent, name)

Response: Iterate through a gtk container parent and return the widget with the name name.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def venv_has_script(script):
    def f(venv):
        path=os.path.join(venv, 'bin', script)
        if os.path.isfile(path):
            return True
    return f

Response: returns function that checks if venv has script


Instruction:
How would you implement a function in Python 3 that
checks if a directory is a virtualenv.

Response:
def is_venv(directory, executable='python'):
    """
    :param directory: base directory of python environment
    """
    path=os.path.join(directory, 'bin', executable)
    return os.path.isfile(path)


Instruction:
Here you have a function in Python 3, explain what it does
def vw_envs(filter=None):
    vw_root=os.path.abspath(os.path.expanduser(os.path.expandvars('~/.virtualenvs')))
    venvs=[]
    for directory in os.listdir(vw_root):
        venv=os.path.join(vw_root, directory)
        if os.path.isdir(os.path.join(venv)):
            if filter and not filter(venv):
                continue
            venvs.append(venv)
    return sorted(venvs)

Response: Return a list of python environments in ~. virtualenvs.


Instruction:
Make a summary of the following Python 3 code
def sbot_executable():
    gsettings=load_gsettings()
    venv = gsettings.get_string('current-virtualenv')
    if venv == 'Default':
        sbot = which('sbot')
    elif venv == 'System':
        # find system python
        env_venv = os.environ.get('VIRTUAL_ENV')
        if not env_venv:
            return which('sbot')

        # First sbot in path that is not in current venv
        for p in os.environ['PATH'].split(os.path.pathsep):
            sbot='%s/sbot' % p
            if not p.startswith(env_venv) and os.path.isfile(sbot):
                return sbot
    else:
        sbot = os.path.join(venv, 'bin/sbot')
        if not os.path.isfile(sbot):
            print('Shoebot not found, reverting to System shoebot')
            sbot = which('sbot')
    return os.path.realpath(sbot)

Response: Find the executable of the current SBOT


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

        """ Returns the meta description in the page.
        """

        meta = self.find("meta", {"name":"description"})
        if isinstance(meta, dict) and \
           meta.has_key("content"):
            return meta["content"]
        else:
            return u""

Response: Returns the meta description in the page.


Instruction:
How would you code a function in Python 3 to
return the meta keywords in the page.

Response:
def _keywords(self):

        """ Returns the meta keywords in the page.
        """

        meta = self.find("meta", {"name":"keywords"})
        if isinstance(meta, dict) and \
           meta.has_key("content"):
            keywords = [k.strip() for k in meta["content"].split(",")]
        else:
            keywords = []

        return keywords


Instruction:
Can you generate the documentation for the following Python 3 function
def links(self, external=True):

        """ Retrieves links in the page.

        Returns a list of URL's.
        By default, only external URL's are returned.
        External URL's starts with http:// and point to another
        domain than the domain the page is on.

        """

        domain = URLParser(self.url).domain

        links = []
        for a in self("a"):
            for attribute, value in a.attrs:
                if attribute == "href":
                    if not external \
                    or (value.startswith("http://") and value.find("http://"+domain) < 0):
                        links.append(value)

        return links

Response: Retrieves the links in the page.


Instruction:
Make a summary of the following Python 3 code
def sorted(list, cmp=None, reversed=False):
    list = [x for x in list]
    list.sort(cmp)
    if reversed: list.reverse()
    return list

Response: Returns a sorted copy of the list.


Instruction:
Can you generate the documentation for the following Python 3 function
def unique(list):
    unique = []; [unique.append(x) for x in list if x not in unique]
    return unique

Response: Returns a copy of the list without duplicates.


Instruction:
Can you generate the documentation for the following Python 3 function
def subgraph(graph, id, distance=1):

    """ Creates the subgraph of the flattened node with given id (or list of id's).
    Finds all the edges between the nodes that make up the subgraph.
    """

    g = graph.copy(empty=True)

    if isinstance(id, (FunctionType, LambdaType)):
        # id can also be a lambda or function that returns True or False
        # for each node in the graph. We take the id's of nodes that pass.
        id = [node.id for node in filter(id, graph.nodes)]
    if not isinstance(id, (list, tuple)):
        id = [id]
    for id in id:
        for n in flatten(graph[id], distance):
            g.add_node(n.id, n.r, n.style, n.category, n.label, (n==graph.root), n.__dict__)

    for e in graph.edges:
        if g.has_key(e.node1.id) and \
           g.has_key(e.node2.id):
            g.add_edge(e.node1.id, e.node2.id, e.weight, e.length, e.label, e.__dict__)

    # Should we look for shortest paths between nodes here?

    return g

Response: Creates a subgraph of the flattened node with given id.


Instruction:
Write a Python 3 function that can
return the largest possible clique for the given node with given id.

Response:
def clique(graph, id):

    """ Returns the largest possible clique for the node with given id.
    """

    clique = [id]
    for n in graph.nodes:
        friend = True
        for id in clique:
            if n.id == id or graph.edge(n.id, id) == None:
                friend = False
                break
        if friend:
            clique.append(n.id)

    return clique


Instruction:
How would you explain what the following Python 3 function does
def cliques(graph, threshold=3):

    """ Returns all the cliques in the graph of at least the given size.
    """

    cliques = []
    for n in graph.nodes:
        c = clique(graph, n.id)
        if len(c) >= threshold:
            c.sort()
            if c not in cliques:
                cliques.append(c)

    return cliques

Response: Returns all the cliques in the given graph.


Instruction:
Here you have a function in Python 3, explain what it does
def partition(graph):

    """ Splits unconnected subgraphs.

    For each node in the graph, make a list of its id and all directly connected id's.
    If one of the nodes in this list intersects with a subgraph,
    they are all part of that subgraph.
    Otherwise, this list is part of a new subgraph.
    Return a list of subgraphs sorted by size (biggest-first).

    """

    g = []
    for n in graph.nodes:
        c = [n.id for n in flatten(n)]
        f = False
        for i in range(len(g)):
            if len(intersection(g[i], c)) > 0:
                g[i] = union(g[i], c)
                f = True
                break
        if not f:
            g.append(c)

    # If 1 is directly connected to 2 and 3,
    # and 4 is directly connected to 5 and 6, these are separate subgraphs.
    # If we later find that 7 is directly connected to 3 and 6,
    # it will be attached to [1, 2, 3] yielding
    # [1, 2, 3, 6, 7] and [4, 5, 6].
    # These two subgraphs are connected and need to be merged.
    merged = []
    for i in range(len(g)):
        merged.append(g[i])
        for j in range(i+1, len(g)):
            if len(intersection(g[i], g[j])) > 0:
                merged[-1].extend(g[j])
                g[j] = []

    g = merged
    g = [graph.sub(g, distance=0) for g in g]
    g.sort(lambda a, b: len(b) - len(a))

    return g

Response: Splits unconnected subgraphs into two lists.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def render(self, size, frame, drawqueue):
        '''
        Calls implmentation to get a render context,
        passes it to the drawqueues render function
        then calls self.rendering_finished
        '''
        r_context = self.create_rcontext(size, frame)
        drawqueue.render(r_context)
        self.rendering_finished(size, frame, r_context)
        return r_context

Response: Returns a new render context


Instruction:
Can you create a Python 3 function that
tries to interpret the next 8 bytes of the data as a 64 - bit signed integer.

Response:
def readLong(data):
    """Tries to interpret the next 8 bytes of the data
    as a 64-bit signed integer."""
    high, low = struct.unpack(">ll", data[0:8])
    big = (long(high) << 32) + low
    rest = data[8:]
    return (big, rest)


Instruction:
Can you generate the documentation for the following Python 3 function
def OSCBlob(next):

    if type(next) == type(""):
        length = len(next)
        padded = math.ceil((len(next)) / 4.0) * 4
        binary = struct.pack(">i%ds" % (padded), length, next)
        tag    = 'b'
    else:
        tag    = ''
        binary = ''

    return (tag, binary)

Response:
Convert a string into an OSC Blob and
    returning a ( typetag data ) tuple.


Instruction:
Write a Python 3 script for
converting some Python types to their OSC binary representations returning a ( typetag data ) tuple.

Response:
def OSCArgument(next):
    """Convert some Python types to their
    OSC binary representations, returning a
    (typetag, data) tuple."""

    if type(next) == type(""):
        OSCstringLength = math.ceil((len(next)+1) / 4.0) * 4
        binary  = struct.pack(">%ds" % (OSCstringLength), next)
        tag = "s"
    elif type(next) == type(42.5):
        binary  = struct.pack(">f", next)
        tag = "f"
    elif type(next) == type(13):
        binary  = struct.pack(">i", next)
        tag = "i"
    else:
        binary  = ""
        tag = ""

    return (tag, binary)


Instruction:
Can you tell what is the following Python 3 function doing
def parseArgs(args):
    parsed = []
    for arg in args:
        print arg
        arg = arg.strip()
        interpretation = None
        try:
            interpretation = float(arg)
            if string.find(arg, ".") == -1:
                interpretation = int(interpretation)
        except:
            # Oh - it was a string.
            interpretation = arg
            pass
        parsed.append(interpretation)
    return parsed

Response:
Given a list of strings produces a list
    where those strings have been parsed as floats or integers.


Instruction:
Make a summary of the following Python 3 code
def decodeOSC(data):
    table = {"i":readInt, "f":readFloat, "s":readString, "b":readBlob}
    decoded = []
    address,  rest = readString(data)
    typetags = ""

    if address == "#bundle":
        time, rest = readLong(rest)
#       decoded.append(address)
#       decoded.append(time)
        while len(rest)>0:
            length, rest = readInt(rest)
            decoded.append(decodeOSC(rest[:length]))
            rest = rest[length:]

    elif len(rest) > 0:
        typetags, rest = readString(rest)
        decoded.append(address)
        decoded.append(typetags)
        if typetags[0] == ",":
            for tag in typetags[1:]:
                value, rest = table[tag](rest)
                decoded.append(value)
        else:
            print "Oops, typetag lacks the magic ,"

    return decoded

Response: Converts a typetagged OSC message to a Python list.


Instruction:
Here you have a function in Python 3, explain what it does
def append(self, argument, typehint = None):

        if typehint == 'b':
            binary = OSCBlob(argument)
        else:
            binary = OSCArgument(argument)

        self.typetags = self.typetags + binary[0]
        self.rawAppend(binary[1])

Response: Appends data to the message


Instruction:
Can you generate the documentation for the following Python 3 function
def getBinary(self):
        address  = OSCArgument(self.address)[1]
        typetags = OSCArgument(self.typetags)[1]
        return address + typetags + self.message

Response: Returns the binary message with typetags.


Instruction:
Here you have a function in Python 3, explain what it does
def handle(self, data, source = None):
        decoded = decodeOSC(data)
        self.dispatch(decoded, source)

Response:
Given data tries to call the callback with the
        right address.


Instruction:
How would you explain what the following Python 3 function does
def dispatch(self, message, source = None):
        msgtype = ""
        try:
            if type(message[0]) == str:
                # got a single message
                address = message[0]
                self.callbacks[address](message)
            elif type(message[0]) == list:
                for msg in message:
                    self.dispatch(msg)
        except KeyError, key:
            print 'address %s not found, %s: %s' % (address, key, message)
            pprint.pprint(message)
        except IndexError, e:
            print '%s: %s' % (e, message)
            pass
        except None, e:
            print "Exception in", address, "callback :", e

        return

Response: Sends decoded OSC data to an appropriate calback


Instruction:
Explain what the following Python 3 code does
def add(self, callback, name):
        if callback == None:
            del self.callbacks[name]
        else:
            self.callbacks[name] = callback

Response: Adds a callback to our set of callbacks with name.


Instruction:
Given the following Python 3 function, write the documentation
def find_example_dir():
    # Replace %s with directory to check for shoebot menus.
    code_stub = textwrap.dedent("""
    from pkg_resources import resource_filename, Requirement, DistributionNotFound
    try:
        print(resource_filename(Requirement.parse('shoebot'), '%s'))
    except DistributionNotFound:
        pass

    """)

    # Needs to run in same python env as shoebot (may be different to gedits)
    code = code_stub % 'share/shoebot/examples'
    cmd = ["python", "-c", code]
    p = subprocess.Popen(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
    output, errors = p.communicate()
    if errors:
        print('Shoebot experienced errors searching for install and examples.')
        print('Errors:\n{0}'.format(errors.decode('utf-8')))
        return None
    else:
        examples_dir = output.decode('utf-8').strip()
        if os.path.isdir(examples_dir):
            return examples_dir

        # If user is running 'setup.py develop' then examples could be right here
        #code = "from pkg_resources import resource_filename, Requirement; print resource_filename(Requirement.parse('shoebot'), 'examples/')"
        code = code_stub % 'examples/'
        cmd = ["python", "-c", code]
        p = subprocess.Popen(cmd, stdout=subprocess.PIPE)
        output, errors = p.communicate()
        examples_dir = output.decode('utf-8').strip()
        if os.path.isdir(examples_dir):
            return examples_dir

        if examples_dir:
            print('Shoebot could not find examples at: {0}'.format(examples_dir))
        else:
            print('Shoebot could not find install dir and examples.')

Response: Find examples dir.. a little bit ugly..


Instruction:
Can you generate the documentation for the following Python 3 function
def run(self):
        try:
            for line in iter(self._fd.readline, False):
                if line is not None:
                    if self._althandler:
                        if self._althandler(line):
                            # If the althandler returns True
                            # then don't process this as usual
                            continue
                self._queue.put(line)
                if not line:
                    time.sleep(0.1)
        except ValueError:  # This can happen if we are closed during readline - TODO - better fix.
            if not self._fd.closed:
                raise

Response: Runs the tread thread.


Instruction:
Write a Python 3 script for
checking whether there is no more content to expect.

Response:
def eof(self):
        """
        Check whether there is no more content to expect.
        """
        return (not self.is_alive()) and self._queue.empty() or self._fd.closed


Instruction:
Can you generate the documentation for the following Python 3 function
def live_source_load(self, source):
        source = source.rstrip('\n')
        if source != self.source:
            self.source = source
            b64_source = base64.b64encode(bytes(bytearray(source, "ascii")))
            self.send_command(CMD_LOAD_BASE64, b64_source)

Response: Send new source code to the bot


Instruction:
Write a Python 3 function that can
send command to the remote process.

Response:
def send_command(self, cmd, *args):
        """
        :param cmd:
        :param args:
        :return:
        """
        # Test in python 2 and 3 before modifying (gedit2 + 3)
        if True:
            # Create a CommandResponse using a cookie as a unique id
            cookie = str(uuid.uuid4())
            response = CommandResponse(cmd, cookie, None, info=[])
            self.responses[cookie] = response
            args = list(args) + [b'cookie=' + bytes(cookie, "ascii")]
        if args:
            bytes_args = []
            for arg in args:
                if isinstance(arg, bytes):
                    bytes_args.append(arg)
                else:
                    bytes_args.append(bytearray(arg, "ascii"))
            data = bytearray(cmd, "ascii") + b' ' + b' '.join(bytes_args) + b'\n'
        else:
            data = bytearray(cmd, "ascii") + b'\n'

        self.process.stdin.write(data)
        self.process.stdin.flush()


Instruction:
How would you code a function in Python 3 to
close outputs of process.

Response:
def close(self):
        """
        Close outputs of process.
        """
        self.process.stdout.close()
        self.process.stderr.close()
        self.running = False


Instruction:
Write a Python 3 script to
get responses to commands sent

Response:
def get_command_responses(self):
        """
        Get responses to commands sent
        """
        if not self.response_queue.empty():
            yield None
        while not self.response_queue.empty():
            line = self.response_queue.get()
            if line is not None:
                yield line


Instruction:
Write a Python 3 function that can
sort a list of options by preference

Response:
def sort_by_preference(options, prefer):
    """
    :param options: List of options
    :param prefer: Prefered options
    :return:

    Pass in a list of options, return options in 'prefer' first

    >>> sort_by_preference(["cairo", "cairocffi"], ["cairocffi"])
    ["cairocffi", "cairo"]
    """
    if not prefer:
        return options
    return sorted(options, key=lambda x: (prefer + options).index(x))


Instruction:
Create a Python 3 function to
import the modules in module_names and set the has_... booleans to class set..._impl to first successful import

Response:
def import_libs(self, module_names, impl_name):
        """
        Loop through module_names,
        add has_.... booleans to class
        set ..._impl to first successful import

        :param module_names:  list of module names to try importing
        :param impl_name:  used in error output if no modules succeed
        :return: name, module from first successful implementation
        """
        for name in module_names:
            try:
                module = __import__(name)
                has_module = True
            except ImportError:
                module = None
                has_module = False
            setattr(self, name, module)
            setattr(self, 'has_%s' % name, has_module)

        for name in module_names:
            try:
                return name, __import__(name)
            except ImportError:
                pass
        raise ImportError('No %s Implementation found, tried: %s' % (impl_name, ' '.join(module_names)))


Instruction:
Here you have a function in Python 3, explain what it does
def ensure_pycairo_context(self, ctx):
        if self.cairocffi and isinstance(ctx, self.cairocffi.Context):
            from shoebot.util.cairocffi.cairocffi_to_pycairo import _UNSAFE_cairocffi_context_to_pycairo
            return _UNSAFE_cairocffi_context_to_pycairo(ctx)
        else:
            return ctx

Response: Ensures that the given context is a pycairo context.


Instruction:
Write a Python 3 function that can
create a new context from a Context object.

Response:
def pangocairo_create_context(cr):
    """
    If python-gi-cairo is not installed, using PangoCairo.create_context
    dies with an unhelpful KeyError, check for that and output somethig
    useful.
    """
    # TODO move this to core.backend
    try:
        return PangoCairo.create_context(cr)
    except KeyError as e:
        if e.args == ('could not find foreign type Context',):
            raise ShoebotInstallError("Error creating PangoCairo missing dependency: python-gi-cairo")
        else:
            raise


Instruction:
Make a summary of the following Python 3 code
def _get_center(self):
        '''Returns the center point of the path, disregarding transforms.
        '''
        w, h = self.layout.get_pixel_size()
        x = (self.x + w / 2)
        y = (self.y + h / 2)
        return x, y

Response: Returns the center point of the path disregarding transforms.


Instruction:
Make a summary of the following Python 3 code
def is_list(str):

    """ Determines if an item in a paragraph is a list.

    If all of the lines in the markup start with a "*" or "1."
    this indicates a list as parsed by parse_paragraphs().
    It can be drawn with draw_list().

    """

    for chunk in str.split("\n"):
        chunk = chunk.replace("\t", "")
        if  not chunk.lstrip().startswith("*") \
        and not re.search(r"^([0-9]{1,3}\. )", chunk.lstrip()):
            return False

    return True

Response: Determines if an item in a paragraph is a list.


Instruction:
Can you create a Python 3 function that
determines if an item in a paragraph is a LaTeX math equation.

Response:
def is_math(str):

    """ Determines if an item in a paragraph is a LaTeX math equation.

    Math equations are wrapped in <math></math> tags.
    They can be drawn as an image using draw_math().

    """

    str = str.strip()
    if str.startswith("<math>") and str.endswith("</math>"):
        return True
    else:
        return False


Instruction:
How would you explain what the following Python 3 function does
def draw_math(str, x, y, alpha=1.0):

    """ Uses mimetex to generate a GIF-image from the LaTeX equation.
    """

    try: from web import _ctx
    except: pass

    str = re.sub("</{0,1}math>", "", str.strip())
    img = mimetex.gif(str)
    w, h = _ctx.imagesize(img)
    _ctx.image(img, x, y, alpha=alpha)
    return w, h

Response: Draws a LaTeX math string to the current context.


Instruction:
Can you generate the documentation for the following Python 3 function
def draw_list(markup, x, y, w, padding=5, callback=None):

    """ Draws list markup with indentation in NodeBox.

    Draw list markup at x, y coordinates
    using indented bullets or numbers.
    The callback is a command that takes a str and an int.

    """

    try: from web import _ctx
    except: pass

    i = 1
    for chunk in markup.split("\n"):

        if callback != None:
            callback(chunk, i)

        m = re.search("^([0-9]{1,3}\. )", chunk.lstrip())
        if m:
            indent = re.search("[0-9]", chunk).start()*padding*2
            bullet = m.group(1)
            dx = textwidth("000.")
            chunk = chunk.lstrip(m.group(1)+"\t")

        if chunk.lstrip().startswith("*"):
            indent = chunk.find("*")*padding*2
            bullet = u"•"
            dx = textwidth("*")
            chunk = chunk.lstrip("* \t")

        _ctx.text(bullet, x+indent, y)
        dx += padding + indent
        _ctx.text(chunk, x+dx, y, width=w-dx)
        y += _ctx.textheight(chunk, width=w-dx)
        y += _ctx.textheight(" ") * 0.25
        i += 1

Response: Draw list markup at x y coordinates using indented bullets or numbers.


Instruction:
How would you code a function in Python 3 to
draw a table in the NodeBox.

Response:
def draw_table(table, x, y, w, padding=5):

    """ This is a very poor algorithm to draw Wikipedia tables in NodeBox.
    """

    try: from web import _ctx
    except: pass

    f = _ctx.fill()
    _ctx.stroke(f)
    h = _ctx.textheight(" ") + padding*2

    row_y = y

    if table.title != "":
        _ctx.fill(f)
        _ctx.rect(x, row_y, w, h)
        _ctx.fill(1)
        _ctx.text(table.title, x+padding, row_y+_ctx.fontsize()+ padding)
        row_y += h

    # A table of flags marking how long a cell
    # from a previous row is still spanning in a column.
    rowspans = [1 for i in range(10)]
    previous_cell_w = 0

    for row in table:

        cell_x = x

        # The width of a cell is the total table width
        # evenly divided by the number of cells.
        # Previous rows' cells still spanning will push cells
        # to the right and decrease their width.
        cell_w  = 1.0 * w
        cell_w -= previous_cell_w * len([n for n in rowspans if n > 1])
        cell_w /= len(row)

        # The height of each cell is the highest cell in the row.
        # The height depends on the amount of text in the cell.
        cell_h = 0
        for cell in row:
            this_h = _ctx.textheight(cell, width=cell_w-padding*2) + padding*2
            cell_h = max(cell_h, this_h)

        # Traverse each cell in this row.
        i = 0
        for cell in row:

            # If a previous row's cell is still spanning,
            # push this cell to the right.
            if rowspans[i] > 1:
                rowspans[i] -= 1
                cell_x += previous_cell_w
                i += 1

            # Get the rowspan attribute for this cell.
            m = re.search("rowspan=\"(.*?)\"", cell.properties)
            if m:
                rowspan = int(m.group(1))
                rowspans[i] = rowspan
            else:
                rowspan = 1

            # Padded cell text.
            # Horizontal line above each cell.
            # Vertical line before each cell.
            _ctx.fill(f)
            _ctx.text(cell, cell_x+padding, row_y+_ctx.fontsize()+padding, cell_w-padding*2)
            _ctx.line(cell_x, row_y, cell_x+cell_w, row_y)
            if cell_x > x:
                _ctx.nofill()
                _ctx.line(cell_x, row_y, cell_x, row_y+cell_h)

            cell_x += cell_w
            i += 1

        # Move to next row.
        row_y += cell_h
        previous_cell_w = cell_w

    # Table's bounding rectangle.
    _ctx.nofill()
    _ctx.rect(x, y, w, row_y-y)


Instruction:
Write a Python 3 function for
parsing the markup and sets the attributes of the object.

Response:
def parse(self, light=False):

        """ Parses data from Wikipedia page markup.

        The markup comes from Wikipedia's edit page.
        We parse it here into objects containing plain text.
        The light version parses only links to other articles, it's faster than a full parse.

        """

        markup = self.markup

        self.disambiguation = self.parse_disambiguation(markup)
        self.categories = self.parse_categories(markup)
        self.links = self.parse_links(markup)

        if not light:

            # Conversion of HTML markup to Wikipedia markup.
            markup = self.convert_pre(markup)
            markup = self.convert_li(markup)
            markup = self.convert_table(markup)
            markup = replace_entities(markup)

            # Harvest references from the markup
            # and replace them by footnotes.
            markup = markup.replace("{{Cite", "{{cite")
            markup = re.sub("\{\{ {1,2}cite", "{{cite", markup)
            self.references, markup = self.parse_references(markup)

            # Make sure there are no legend linebreaks in image links.
            # Then harvest images and strip them from the markup.
            markup = re.sub("\n+(\{\{legend)", "\\1", markup)
            self.images, markup = self.parse_images(markup)
            self.images.extend(self.parse_gallery_images(markup))

            self.paragraphs = self.parse_paragraphs(markup)
            self.tables = self.parse_tables(markup)
            self.translations = self.parse_translations(markup)
            self.important = self.parse_important(markup)


Instruction:
Implement a Python 3 function for
stripping Wikipedia markup from given text.

Response:
def plain(self, markup):

        """ Strips Wikipedia markup from given text.

        This creates a "plain" version of the markup,
        stripping images and references and the like.
        Does some commonsense maintenance as well,
        like collapsing multiple spaces.
        If you specified full_strip=False for WikipediaPage instance,
        some markup is preserved as HTML (links, bold, italic).

        """

        # Strip bold and italic.
        if self.full_strip:
            markup = markup.replace("'''", "")
            markup = markup.replace("''", "")
        else:
            markup = re.sub("'''([^']*?)'''", "<b>\\1</b>", markup)
            markup = re.sub("''([^']*?)''", "<i>\\1</i>", markup)

        # Strip image gallery sections.
        markup = re.sub(self.re["gallery"], "", markup)

        # Strip tables.
        markup = re.sub(self.re["table"], "", markup)
        markup = markup.replace("||", "")
        markup = markup.replace("|}", "")

        # Strip links, keeping the display alias.
        # We'll strip the ending ]] later.
        if self.full_strip:
            markup = re.sub(r"\[\[[^\]]*?\|", "", markup)
        else:
            markup = re.sub(r"\[\[([^]|]*|)\]\]", '<a href="\\1">\\1</a>', markup)
            markup = re.sub(r"\[\[([^]|]*|)\|([^]]*)\]\]", '<a href="\\1">\\2</a>', markup)

        # Strip translations, users, etc.
        markup = re.sub(self.re["translation"], "", markup)

        # This math TeX is not supported:
        markup = markup.replace("\displaytyle", "")
        markup = markup.replace("\textstyle", "")
        markup = markup.replace("\scriptstyle", "")
        markup = markup.replace("\scriptscriptstyle", "")

        # Before stripping [ and ] brackets,
        # make sure they are retained inside <math></math> equations.
        markup = re.sub("(<math>.*?)\[(.*?</math>)", "\\1MATH___OPEN\\2", markup)
        markup = re.sub("(<math>.*?)\](.*?</math>)", "\\1MATH___CLOSE\\2", markup)
        markup = markup.replace("[", "")
        markup = markup.replace("]", "")
        markup = markup.replace("MATH___OPEN", "[")
        markup = markup.replace("MATH___CLOSE", "]")

        # a) Strip references.
        # b) Strip <ref></ref> tags.
        # c) Strip <ref name="" /> tags.
        # d) Replace --REF--(12) by [12].
        # e) Remove space between [12] and trailing punctuation .,
        # f) Remove HTML comment <!-- -->
        # g) Keep the Latin Extended-B template: {{latinx| }}
        # h) Strip Middle-Earth references.
        # i) Keep quotes: {{quote| }}
        # j) Remove templates
        markup = re.sub(self.re["reference"], "", markup)                  # a
        markup = re.sub("</{0,1}ref.*?>", "", markup)                      # b
        markup = re.sub("<ref name=\".*?\" {0,1}/>", "", markup)           # c
        markup = re.sub(self.ref+"\(([0-9]*?)\)", "[\\1] ", markup)        # d
        markup = re.sub("\] ([,.\"\?\)])", "]\\1", markup)                 # e
        markup = re.sub(self.re["comment"], "", markup)                    # f
        markup = re.sub("\{\{latinx\|(.*?)\}\}", "\\1", markup)            # g
        markup = re.sub("\{\{ME-ref.*?\}\}", "", markup)                   # h
        markup = re.sub("\{\{quote\|(.*?)\}\}", "\"\\1\"", markup)         # i
        markup = re.sub(re.compile("\{\{.*?\}\}", re.DOTALL), "", markup)  # j
        markup = markup.replace("}}", "")

        # Collapse multiple spaces between words,
        # unless they appear in preformatted text.
        markup = re.sub("<br.*?/{0,1}>", " ", markup)
        markup = markup.split("\n")
        for i in range(len(markup)):
            if not markup[i].startswith(" "):
                markup[i] = re.sub(r"[ ]+", " ", markup[i])
        markup = "\n".join(markup)
        markup = markup.replace(" .", ".")

        # Strip all HTML except <math> tags.
        if self.full_strip:
            markup = strip_tags(markup, exclude=["math"], linebreaks=True)

        markup = markup.strip()
        return markup


Instruction:
Can you implement a function in Python 3 that
converts the markup from pre to wikipedia

Response:
def convert_pre(self, markup):

        """ Substitutes <pre> to Wikipedia markup by adding a space at the start of a line.
        """

        for m in re.findall(self.re["preformatted"], markup):
            markup = markup.replace(m, m.replace("\n", "\n "))
            markup = re.sub("<pre.*?>\n{0,}", "", markup)
            markup = re.sub("\W{0,}</pre>", "", markup)

        return markup


Instruction:
Can you tell what is the following Python 3 function doing
def convert_li(self, markup):

        """ Subtitutes <li> content to Wikipedia markup.
        """

        for li in re.findall("<li;*?>", markup):
            markup = re.sub(li, "\n* ", markup)
        markup = markup.replace("</li>", "")

        return markup

Response: Convert the li content to Wikipedia markup.


Instruction:
Can you write a function in Python 3 where it
converts HTML table content to Wikipedia markup.

Response:
def convert_table(self, markup):

        """ Subtitutes <table> content to Wikipedia markup.
        """

        for table in re.findall(self.re["html-table"], markup):
            wiki = table
            wiki = re.sub(r"<table(.*?)>", "{|\\1", wiki)
            wiki = re.sub(r"<tr(.*?)>", "|-\\1", wiki)
            wiki = re.sub(r"<td(.*?)>", "|\\1|", wiki)
            wiki = wiki.replace("</td>", "\n")
            wiki = wiki.replace("</tr>", "\n")
            wiki = wiki.replace("</table>", "\n|}")
            markup = markup.replace(table, wiki)

        return markup


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

        """ Returns a list of internal Wikipedia links in the markup.

        # A Wikipedia link looks like:
        # [[List of operating systems#Embedded | List of embedded operating systems]]
        # It does not contain a colon, this indicates images, users, languages, etc.

        The return value is a list containing the first part of the link,
        without the anchor.

        """

        links = []
        m = re.findall(self.re["link"], markup)
        for link in m:
            # We don't like [[{{{1|Universe (disambiguation)}}}]]
            if link.find("{") >= 0:
                link = re.sub("\{{1,3}[0-9]{0,2}\|", "", link)
                link = link.replace("{", "")
                link = link.replace("}", "")
            link = link.split("|")
            link[0] = link[0].split("#")
            page = link[0][0].strip()
            #anchor = u""
            #display = u""
            #if len(link[0]) > 1:
            #    anchor = link[0][1].strip()
            #if len(link) > 1:
            #    display = link[1].strip()
            if not page in links:
                links.append(page)
                #links[page] = WikipediaLink(page, anchor, display)

        links.sort()
        return links

Response: Parses the markup and returns a list of internal Wikipedia links.


Instruction:
Write a Python 3 function that can
parse the markup and returns a list of images found in the markup.

Response:
def parse_images(self, markup, treshold=6):

        """ Returns a list of images found in the markup.

        An image has a pathname, a description in plain text
        and a list of properties Wikipedia uses to size and place images.

        # A Wikipedia image looks like:
        # [[Image:Columbia Supercomputer - NASA Advanced Supercomputing Facility.jpg|right|thumb|
        #   The [[NASA]] [[Columbia (supercomputer)|Columbia Supercomputer]].]]
        # Parts are separated by "|".
        # The first part is the image file, the last part can be a description.
        # In between are display properties, like "right" or "thumb".

        """

        images = []
        m = re.findall(self.re["image"], markup)
        for p in m:
            p = self.parse_balanced_image(p)
            img = p.split("|")
            path = img[0].replace("[[Image:", "").strip()
            description = u""
            links = {}
            properties = []
            if len(img) > 1:
                img = "|".join(img[1:])
                links = self.parse_links(img)
                properties = self.plain(img).split("|")
                description = u""
                # Best guess: an image description is normally
                # longer than six characters, properties like
                # "thumb" and "right" are less than six characters.
                if len(properties[-1]) > treshold:
                    description = properties[-1]
                    properties = properties[:-1]
            img = WikipediaImage(path, description, links, properties)
            images.append(img)
            markup = markup.replace(p, "")

        return images, markup.strip()


Instruction:
How would you implement a function in Python 3 that
corrects Wikipedia image markup.

Response:
def parse_balanced_image(self, markup):

        """ Corrects Wikipedia image markup.

        Images have a description inside their link markup that
        can contain link markup itself, make sure the outer "[" and "]" brackets
        delimiting the image are balanced correctly (e.g. no [[ ]] ]]).

        Called from parse_images().

        """

        opened = 0
        closed = 0
        for i in range(len(markup)):
            if markup[i] == "[": opened += 1
            if markup[i] == "]": closed += 1
            if opened == closed:
                return markup[:i+1]

        return markup


Instruction:
Write a Python 3 script for
parsing the gallery images from the markup.

Response:
def parse_gallery_images(self, markup):

        """ Parses images from the <gallery></gallery> section.

        Images inside <gallery> tags do not have outer "[[" brackets.
        Add these and then parse again.

        """

        gallery = re.search(self.re["gallery"], markup)
        if gallery:
            gallery = gallery.group(1)
            gallery = gallery.replace("Image:", "[[Image:")
            gallery = gallery.replace("\n", "]]\n")
            images, markup = self.parse_images(gallery)
            return images

        return []


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

        """ Creates a list from lines of text in a paragraph.

        Each line of text is a new item in the list,
        except lists and preformatted chunks (<li> and <pre>),
        these are kept together as a single chunk.

        Lists are formatted using parse_paragraph_list().

        Empty lines are stripped from the output.
        Indentation (i.e. lines starting with ":") is ignored.

        Called from parse_paragraphs() method.

        """

        s = self.plain(markup)
        # Add an extra linebreak between the last list item
        # and the normal line following after it, so they don't stick together, e.g.
        # **[[Alin Magic]], magic used in the videogame ''[[Rise of Nations: Rise of Legends]]''
        # In '''popular culture''':
        # * [[Magic (film)|''Magic'' (film)]], a 1978 film starring Anthony Hopkins and Ann-Margret
        s = re.sub(re.compile("\n([*#;].*?)\n([^*#?])", re.DOTALL), "\n\\1\n\n\\2", s)
        # This keeps list items with linebreaks
        # between them nicely together.
        s = re.sub("\n{2,3}([*#;])", "\n\\1", s)
        chunks = []
        ch = ""
        i = 1
        for chunk in s.split("\n"):
            if chunk.startswith(":"):
                chunk = chunk.lstrip(":")
            if len(chunk.strip()) > 1:
                # Leave out taxoboxes and infoboxes.
                if not chunk.startswith("|"):
                    ch += chunk + "\n"
            if ch.strip() != "":
                if not re.search("^[ *#;]", chunk):
                    ch = self.parse_paragraph_list(ch)
                    chunks.append(ch.rstrip())
                    ch = ""

        if ch.strip() != "":
            ch = self.parse_paragraph_list(ch)
            chunks.append(ch.strip())

        return chunks

Response: Parses a paragraph into a list of items.


Instruction:
Create a Python 3 function to
parse a list of items from a Wikipedia file.

Response:
def parse_paragraph_list(self, markup, indent="\t"):

        """ Formats bullets and numbering of Wikipedia lists.

        List items are marked by "*", "#" or ";" at the start of a line.
        We treat ";" the same as "*",
        and replace "#" with real numbering (e.g. "2.").
        Sublists (e.g. *** and ###) get indented by tabs.

        Called from parse_paragraphs() method.

        """

        def lastleft(ch, str):
            n = 0
            while n < len(str) and str[n] == ch: n += 1
            return n

        tally = [1 for i in range(10)]
        chunks = markup.split("\n")
        for i in range(len(chunks)):
            if chunks[i].startswith("#"):
                j = min(lastleft("#", chunks[i]), len(tally)-1)
                chunks[i] = indent*(j-1) + str(tally[j])+". " + chunks[i][j:]
                chunks[i] = chunks[i].replace(".  ", ". ")
                tally[j] += 1
                # Reset the numbering of sublists.
                for k in range(j+1, len(tally)):
                    tally[k] = 1
            if chunks[i].startswith(";"):
                chunks[i] = "*" + chunks[i][1:]
            if chunks[i].startswith("*"):
                j = lastleft("*", chunks[i])
                chunks[i] = indent*(j-1) + "* " + chunks[i][j:]
                chunks[i] = chunks[i].replace("*  ", "* ")

        return "\n".join(chunks)


Instruction:
Can you generate a brief explanation for the following Python 3 code
def connect_paragraph(self, paragraph, paragraphs):

        """ Create parent/child links to other paragraphs.

        The paragraphs parameters is a list of all the paragraphs
        parsed up till now.

        The parent is the previous paragraph whose depth is less.
        The parent's children include this paragraph.

        Called from parse_paragraphs() method.

        """

        if paragraph.depth > 0:
            n = range(len(paragraphs))
            n.reverse()
            for i in n:
                if paragraphs[i].depth == paragraph.depth-1:
                    paragraph.parent = paragraphs[i]
                    paragraphs[i].children.append(paragraph)
                    break

        return paragraph

Response: Connect a paragraph to another paragraph.


Instruction:
Create a Python 3 function to
parse the content of a specific paragraph into a list of items and items.

Response:
def parse_paragraph_references(self, markup):

        """ Updates references with content from specific paragraphs.

        The "references", "notes", "external links" paragraphs
        are double-checked for references. Not all items in the list
        might have been referenced inside the article, or the item
        might contain more info than we initially parsed from it.

        Called from parse_paragraphs() method.

        """

        for chunk in markup.split("\n"):
            # We already parsed this, it contains the self.ref mark.
            # See if we can strip more notes from it.
            m = re.search(self.ref+"\(([0-9]*?)\)", chunk)
            if m:
                chunk = chunk.strip("* ")
                chunk = chunk.replace(m.group(0), "")
                chunk = self.plain(chunk)
                i = int(m.group(1))
                if chunk != "":
                    self.references[i-1].note = chunk
            # If it's not a citation we don't have this reference yet.
            elif chunk.strip().startswith("*") \
             and chunk.find("{{cite") < 0:
                chunk = chunk.strip("* ")
                chunk = self.plain(chunk)
                if chunk != "":
                    r = WikipediaReference()
                    r.note = chunk
                    self.references.append(r)


Instruction:
Create a Python 3 function to
parse the markup and returns a list of paragraphs.

Response:
def parse_paragraphs(self, markup):

        """ Returns a list of paragraphs in the markup.

        A paragraph has a title and multiple lines of plain text.
        A paragraph might have parent and child paragraphs,
        denoting subtitles or bigger chapters.

        A paragraph might have links to additional articles.

        Formats numbered lists by replacing # by 1.
        Formats bulleted sublists like ** or *** with indentation.

        """

        # Paragraphs to exclude.
        refs = ["references", "notes", "notes and references", "external links", "further reading"]
        exclude = ["see also", "media", "gallery", "related topics", "lists", "gallery", "images"]
        exclude.extend(refs)

        paragraphs = []
        paragraph = WikipediaParagraph(self.title)
        paragraph_data = ""
        for chunk in markup.split("\n"):

            # Strip each line of whitespace,
            # unless it's a preformatted line (starts with a space).
            if not chunk.startswith(" "):
                chunk = chunk.strip()

            # A title wrapped in "=", "==", "==="...
            # denotes a new paragraphs section.
            if chunk.startswith("="):

                if paragraph.title.lower() in refs \
                or (paragraph.parent and paragraph.parent.title.lower() in refs):
                    self.parse_paragraph_references(paragraph_data)
                paragraph.extend(self.parse_paragraph(paragraph_data))
                paragraphs.append(paragraph)

                # Initialise a new paragraph.
                # Create parent/child links to other paragraphs.
                title = chunk.strip().strip("=")
                title = self.plain(title)
                paragraph = WikipediaParagraph(title)
                paragraph.depth = self.parse_paragraph_heading_depth(chunk)
                if paragraph.title.lower() not in exclude:
                    paragraph = self.connect_paragraph(paragraph, paragraphs)
                paragraph_data = ""

            # Underneath a title might be links to in-depth articles,
            # e.g. Main articles: Computer program and Computer programming
            # which in wiki markup would be {{main|Computer program|Computer programming}}
            # The second line corrects" {{Main|Credit (finance)}} or {{Main|Usury}}".
            elif re.search(re.compile("^{{main", re.I), chunk):
                paragraph.main = [link.strip("} ") for link in chunk.split("|")[1:]]
                paragraph.main = [re.sub(re.compile("}}.*?{{main", re.I), "", link)
                                  for link in paragraph.main]

            # At the bottom might be links to related articles,
            # e.g. See also: Abundance of the chemical elements
            # which in wiki markup would be {{see also|Abundance of the chemical elements}}
            elif re.search(re.compile("^{{see {0,1}also", re.I), chunk):
                paragraph.related = [link.strip("} ") for link in chunk.split("|")[1:]]

            # Accumulate the data in this paragraph,
            # we'll process it once a new paragraph starts.
            else:
                paragraph_data += chunk +"\n"

        # Append the last paragraph.
        if paragraph.title.lower() in refs \
        or (paragraph.parent and paragraph.parent.title.lower() in refs):
            self.parse_paragraph_references(paragraph_data)
        paragraph.extend(self.parse_paragraph(paragraph_data))
        paragraphs.append(paragraph)

        # The "See also" paragraph is an enumeration of links
        # which we already parsed so don't show them.
        # We also did references, and other paragraphs are not that relevant.
        paragraphs_exclude = []
        for paragraph in paragraphs:
            if paragraph.title.lower() not in exclude \
            and not (paragraph.parent and paragraph.parent.title.lower() in exclude):
                paragraphs_exclude.append(paragraph)

        if len(paragraphs_exclude) == 1 and \
           len(paragraphs_exclude[0]) == 0:
            return []

        return paragraphs_exclude


Instruction:
Can you implement a function in Python 3 that
parses a row of cells in a Wikipedia table.

Response:
def parse_table_row(self, markup, row):

        """ Parses a row of cells in a Wikipedia table.

        Cells in the row are separated by "||".
        A "!" indicates a row of heading columns.
        Each cell can contain properties before a "|",
        # e.g. align="right" | Cell 2 (right aligned).

        """

        if row == None:
            row = WikipediaTableRow()

        markup = markup.replace("!!", "||")
        for cell in markup.lstrip("|!").split("||"):
            # The "|" after the properties can't be part of a link.
            i = cell.find("|")
            j = cell.find("[[")
            if i>0 and (j<0 or i<j):
                data = self.plain(cell[i+1:])
                properties = cell[:i].strip()
            else:
                data = self.plain(cell)
                properties = u""
            cell = WikipediaTableCell(data)
            cell.properties = properties
            row.append(cell)

        return row


Instruction:
Write a Python 3 function for
creating a link from the table to paragraph and vice versa.

Response:
def connect_table(self, table, chunk, markup):

        """ Creates a link from the table to paragraph and vice versa.

        Finds the first heading above the table in the markup.
        This is the title of the paragraph the table belongs to.

        """

        k = markup.find(chunk)
        i = markup.rfind("\n=", 0, k)
        j = markup.find("\n", i+1)
        paragraph_title = markup[i:j].strip().strip("= ")
        for paragraph in self.paragraphs:
            if paragraph.title == paragraph_title:
                paragraph.tables.append(table)
                table.paragraph = paragraph


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

        """ Returns a list of tables in the markup.

        A Wikipedia table looks like:
        {| border="1"
        |-
        |Cell 1 (no modifier - not aligned)
        |-
        |align="right" |Cell 2 (right aligned)
        |-
        |}

        """

        tables = []
        m = re.findall(self.re["table"], markup)
        for chunk in m:

            table = WikipediaTable()
            table.properties = chunk.split("\n")[0].strip("{|").strip()
            self.connect_table(table, chunk, markup)

            # Tables start with "{|".
            # On the same line can be properties, e.g. {| border="1"
            # The table heading starts with "|+".
            # A new row in the table starts with "|-".
            # The end of the table is marked with "|}".
            row = None
            for chunk in chunk.split("\n"):
                chunk = chunk.strip()
                if chunk.startswith("|+"):
                    title = self.plain(chunk.strip("|+"))
                    table.title = title
                elif chunk.startswith("|-"):
                    if row:
                        row.properties = chunk.strip("|-").strip()
                        table.append(row)
                    row = None
                elif chunk.startswith("|}"):
                    pass
                elif chunk.startswith("|") \
                  or chunk.startswith("!"):
                    row = self.parse_table_row(chunk, row)

            # Append the last row.
            if row: table.append(row)
            if len(table) > 0:
                tables.append(table)

        return tables

Response: Parses the markup and returns a list of tables in the markup.


Instruction:
Implement a Python 3 function for
parsing the markup and returns a list of references found in the markup.

Response:
def parse_references(self, markup):

        """ Returns a list of references found in the markup.

        References appear inline as <ref> footnotes,
        http:// external links, or {{cite}} citations.
        We replace it with (1)-style footnotes.
        Additional references data is gathered in
        parse_paragraph_references() when we parse paragraphs.

        References can also appear in image descriptions,
        tables and taxoboxes, so they might not always pop up in a paragraph.

        The plain() method finally replaces (1) by [1].

        """

        references = []

        # A Wikipedia reference note looks like:
        # <ref>In 1946, [[ENIAC]] consumed an estimated 174 kW.
        # By comparison, a typical personal computer may use around 400 W;
        # over four hundred times less. {{Ref harvard|kempf1961|Kempf 1961|a}}</ref>
        m = re.findall(self.re["reference"], markup)
        for reference in m:
            reference = re.sub("<ref> {0,1}cite", "<ref>{{cite", reference)
            if not reference.strip().startswith("[http://") and \
               not re.search("\{\{cite", reference):
                r = WikipediaReference()
                r.note = self.plain(re.sub("</{0,1}ref.*?>", "", reference))
                if r.note != "":
                    references.append(r)
                    p = " "+self.ref+"("+str(len(references))+")"
                    markup = markup.replace(reference, p, 1)
            else:
                # References containing a citation or url
                # are better handled by the next patterns.
                pass

        # A Wikipedia citation looks like:
        # {{cite journal
        # | last = Einstein
        # | first = Albert
        # | authorlink = Albert Einstein
        # | title = Sidelights on Relativity (Geometry and Experience)
        # | publisher = P. Dutton., Co
        # | date = 1923}}
        m = re.findall(self.re["citation"], markup)
        for citation in m:
            c = citation.replace("\n", "")
            r = WikipediaReference()
            for key in r.__dict__.keys():
                value = re.search("\| {0,1}"+key+"(.*?)[\|}]", c)
                if value:
                    value = value.group(1)
                    value = value.replace("link", "")
                    value = value.strip().strip(" =[]")
                    value = self.plain(value)
                    setattr(r, key, value)
            if r.first != "" and r.last != "":
                r.author = r.first + " " + r.last
            references.append(r)
            p = " "+self.ref+"("+str(len(references))+")"
            markup = markup.replace(citation, p, 1)

        # A Wikipedia embedded url looks like:
        # [http://www.pbs.org/wnet/hawking/html/home.html ''Stephen Hawking's Universe'']
        m = re.findall(self.re["url"], markup)
        for url in m:
            r = WikipediaReference()
            i = url.find(" ")
            if i > 0:
                r.url = url[:i].strip()
                r.note = self.plain(url[i:])
            else:
                r.url = url.strip()
            references.append(r)
            p = r.note+" "+self.ref+"("+str(len(references))+")"
            markup = markup.replace("["+url+"]", p, 1)

        # Since we parsed all citations first and then all notes and urls,
        # the ordering will not be correct in the markup,
        # e.g. (1) (11) (12) (2) (3).
        sorted = []
        m = re.findall(self.ref+"\(([0-9]*)\)", markup)
        for i in m:
            sorted.append(references[int(i)-1])
            markup = markup.replace(
                self.ref+"("+i+")",
                self.ref+"**("+str(len(sorted))+")"
                )
        markup = markup.replace(self.ref+"**", self.ref)
        for r in references:
            if r not in sorted:
                sorted.append(r)
        references = sorted

        return references, markup.strip()


Instruction:
Can you create a Python 3 function that
parses the markup for the categories.

Response:
def parse_categories(self, markup):

        """ Returns a list of categories the page belongs to.

        # A Wikipedia category link looks like:
        # [[Category:Computing]]
        # This indicates the page is included in the given category.
        # If "Category" is preceded by ":" this indicates a link to a category.

        """

        categories = []
        m = re.findall(self.re["category"], markup)
        for category in m:
            category = category.split("|")
            page = category[0].strip()
            display = u""
            if len(category) > 1:
                display = category[1].strip()
            #if not categories.has_key(page):
            #    categories[page] = WikipediaLink(page, u"", display)
            if not page in categories:
                categories.append(page)

        return categories


Instruction:
Implement a function in Python 3 to
parse the markup and returns a dictionary of translations for the page title.

Response:
def parse_translations(self, markup):

        """ Returns a dictionary of translations for the page title.

        A Wikipedia language link looks like: [[af:Rekenaar]].
        The parser will also fetch links like "user:" and "media:"
        but these are stripped against the dictionary of
        Wikipedia languages.

        You can get a translated page by searching Wikipedia
        with the appropriate language code and supplying
        the translated title as query.

        """

        global languages
        translations = {}
        m = re.findall(self.re["translation"], markup)
        for language, translation in m:
            if language in languages:
                translations[language] = translation

        return translations


Instruction:
Explain what the following Python 3 code does
def parse_disambiguation(self, markup):

        """ Gets the Wikipedia disambiguation page for this article.

        A Wikipedia disambiguation link refers to other pages
        with the same title but of smaller significance,
        e.g. {{dablink|For the IEEE magazine see [[Computer (magazine)]].}}

        """

        m = re.search(self.re["disambiguation"], markup)
        if m:
            return self.parse_links(m.group(1))
        else:
            return []

Response: Parses the disambiguation page for this article.


Instruction:
Implement a Python 3 function for
parsing the markup and returns a list of words that appear in bold in the article.

Response:
def parse_important(self, markup):

        """ Returns a list of words that appear in bold in the article.

        Things like table titles are not added to the list,
        these are probably bold because it makes the layout nice,
        not necessarily because they are important.

        """

        important = []
        table_titles = [table.title for table in self.tables]
        m = re.findall(self.re["bold"], markup)
        for bold in m:
            bold = self.plain(bold)
            if not bold in table_titles:
                important.append(bold.lower())

        return important


Instruction:
How would you explain what the following Python 3 function does
def sanitize(self, val):
        if self.type == NUMBER:
            try:
                return clamp(self.min, self.max, float(val))
            except ValueError:
                return 0.0
        elif self.type == TEXT:
            try:
                return unicode(str(val), "utf_8", "replace")
            except:
                return ""
        elif self.type == BOOLEAN:
            if unicode(val).lower() in ("true", "1", "yes"):
                return True
            else:
                return False

Response: Given a Variable and a value cleans it out


Instruction:
How would you explain what the following Python 3 function does
def compliesTo(self, v):
        if self.type == v.type:
            if self.type == NUMBER:
                if self.value < self.min or self.value > self.max:
                    return False
            return True
        return False

Response: Return whether I am compatible with the given var.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def isList(l):
    return hasattr(l, '__iter__') \
           or (type(l) in (types.ListType, types.TupleType))

Response: Convenience method that returns True if l is a listlike object.


Instruction:
Can you tell what is the following Python 3 function doing
def isString(s):
    try:
        return isinstance(s, unicode) or isinstance(s, basestring)
    except NameError:
        return isinstance(s, str)

Response:
Convenience method that works with all 2. x versions of Python
    to determine whether or not a string is like.


Instruction:
Make a summary of the following Python 3 code
def buildTagMap(default, *args):
    built = {}
    for portion in args:
        if hasattr(portion, 'items'):
            #It's a map. Merge it.
            for k,v in portion.items():
                built[k] = v
        elif isList(portion):
            #It's a list. Map each item to the default.
            for k in portion:
                built[k] = default
        else:
            #It's a scalar. Map it to the default.
            built[portion] = default
    return built

Response: Turns a list of maps lists or scalars into a single map.