Instruction:
Write a Python 3 script for
drawing the main panel of the current application.

Response:
def draw_panel(cb, pool, params, plane):
    """
    Draws the application's main panel, displaying the current Mandelbrot view.

    :param cb: Cursebox instance.
    :type cb: cursebox.Cursebox
    :param params: Current application parameters.
    :type params: params.Params
    :param plane: Plane containing the current Mandelbrot values.
    :type plane: plane.Plane
    """
    w = cb.width - MENU_WIDTH - 1
    h = cb.height - 1

    params.plane_w = w
    params.plane_h = h
    params.resize(w, h)

    palette = PALETTES[params.palette][1]
    if params.reverse_palette:
        palette = palette[::-1]

    # draw_gradient(t, 1, 1, w, h, palette, params.dither_type)

    generated = 0
    missing_coords = []

    # Check for coordinates that have no value in current plane
    xs = range(params.plane_x0, params.plane_x0 + params.plane_w - 1)
    ys = range(params.plane_y0, params.plane_y0 + params.plane_h - 1)
    for x in xs:
        for y in ys:
            if plane[x, y] is None:
                missing_coords.append((x, y, params))
                generated += 1

    # Compute all missing values via multiprocessing
    n_processes = 0
    if len(missing_coords) > 0:
        n_cores = pool._processes
        n_processes = len(missing_coords) // 256
        if n_processes > n_cores:
            n_processes = n_cores

        start = time.time()
        for i, result in enumerate(pool.imap_unordered(compute, missing_coords, chunksize=256)):
            plane[result[0], result[1]] = result[2]
            if time.time() - start > 2:
                if i % 200 == 0:
                    draw_progress_bar(cb, "Render is taking a longer time...", i, len(missing_coords))
                    cb.refresh()

    if generated > 0:
        params.log("Added %d missing cells" % generated)
        if n_processes > 1:
            params.log("(Used %d processes)" % n_processes)

    min_value = 0.0
    max_value = params.max_iterations
    max_iterations = params.max_iterations

    if params.adaptive_palette:
        min_value, max_value = plane.extrema(params.plane_x0, params.plane_y0,
                                             params.plane_w, params.plane_h)

    crosshairs_coord = None
    if params.crosshairs:
        crosshairs_coord = params.crosshairs_coord

    # Draw all values in cursebox
    for x in xs:
        for y in ys:
            value = (plane[x, y] + params.palette_offset) % (params.max_iterations + 1)
            if params.adaptive_palette:
                # Remap values from (min_value, max_value) to (0, max_iterations)
                if max_value - min_value > 0:
                    value = ((value - min_value) / (max_value - min_value)) * max_iterations
                else:
                    value = max_iterations

            # Dithered mode
            if params.dither_type < 2:
                draw_dithered_color(cb, x - params.plane_x0 + 1,
                                           y - params.plane_y0 + 1,
                                           palette, params.dither_type,
                                           value, max_iterations,
                                           crosshairs_coord=crosshairs_coord)
            # 256 colors mode
            else:
                draw_color(cb, x - params.plane_x0 + 1,
                              y - params.plane_y0 + 1,
                              value, max_iterations, palette,
                              crosshairs_coord=crosshairs_coord)

    # Draw bounding box
    draw_box(cb, 0, 0, w + 1, h + 1)


Instruction:
Given the following Python 3 function, write the documentation
def draw_menu(cb, params, qwertz):
    w = cb.width
    h = cb.height

    x0 = w - MENU_WIDTH + 1

    # Clear buffer inside the box
    fill(cb, x0, 1, MENU_WIDTH, h - 2, " ")

    def draw_option(key, value, shortcuts):
        """
        Helper function to draw options. Self-increments own counter.

        :param key: Name of the option.
        :param value: Value of the option.
        :param shortcuts: Keyboard shortcut keys.
        :return:
        """
        draw_text(cb, x0 + 1, 2 + draw_option.counter,
                  "%s %s %s" % (key, str(value).rjust(MENU_WIDTH - 14 - len(key)), shortcuts))
        draw_option.counter += 1
    draw_option.counter = 1

    z = "Z"
    y = "Y"
    if qwertz:
        z, y = y, z

    h_seps = [2]
    # Draw title
    draw_text(cb, x0, 1, ("Almonds %s" % __version__).center(MENU_WIDTH - 2))
    # Write options (and stats)
    # Mandelbrot position
    draw_option("Real", "{0:.13g}".format(params.mb_cx),
                "$[" + symbols["ARROW_LEFT"] + "]$, $[" + symbols["ARROW_RIGHT"] + "]$")
    draw_option("Imaginary", "{0:.13g}".format(params.mb_cy),
                "$[" + symbols["ARROW_UP"] + "]$, $[" + symbols["ARROW_DOWN"] + "]$")
    # FIXME: try to find a way to avoid this hack
    if is_native_windows():
        cb.put_arrow(x0 + 30, 3, "up", colors.default_bg(), colors.default_fg())
        cb.put_arrow(x0 + 35, 3, "down", colors.default_bg(), colors.default_fg())
        cb.put_arrow(x0 + 30, 4, "left", colors.default_bg(), colors.default_fg())
        cb.put_arrow(x0 + 35, 4, "right", colors.default_bg(), colors.default_fg())
    draw_option("Input coordinates...", "", "$[Enter]$")
    draw_option.counter += 1
    h_seps.append(draw_option.counter + 1)
    # Mandelbrot options
    draw_option("Move speed", params.move_speed, "$[C]$, $[V]$")
    draw_option("Zoom", "{0:.13g}".format(params.zoom), "$[" + y + "]$, $[U]$")
    draw_option("Iterations", params.max_iterations, "$[I]$, $[O]$")
    draw_option("Julia mode", "On" if params.julia else "Off", "$[J]$")
    draw_option.counter += 1
    h_seps.append(draw_option.counter + 1)
    # Palette options
    draw_option("Palette", PALETTES[params.palette][0], "$[P]$")
    draw_option("Color mode", DITHER_TYPES[params.dither_type][0], "$[D]$")
    draw_option("Order", "Reversed" if params.reverse_palette else "Normal", "$[R]$")
    draw_option("Mode", "Adaptive" if params.adaptive_palette else "Linear", "$[A]$")
    draw_option("Cycle!", "", "$[" + z + "]$")
    draw_option.counter += 1
    h_seps.append(draw_option.counter + 1)
    # Misc.
    draw_option("Hi-res capture", "", "$[H]$")
    draw_option("Crosshairs", "On" if params.crosshairs else "Off", "$[X]$")
    draw_option("Theme", "Dark" if colors.dark else "Light", "$[T]$")
    draw_option("Save", "", "$[S]$")
    draw_option("Load...", "", "$[L]$")
    draw_option("Exit", "", "$[ESC]$")

    # Draw box with separators
    middle = 3 + draw_option.counter
    draw_box(cb, w - MENU_WIDTH, 0, MENU_WIDTH, h, h_seps=h_seps + [middle - 1, middle + 1])

    # Draw log
    draw_text(cb, x0, middle, "Event log".center(MENU_WIDTH - 2))
    latest_logs = params.log.get_latest(h - middle)
    latest_logs = [textwrap.wrap(l, MENU_WIDTH - 4)[::-1] for l in latest_logs]  # Wrap all messages
    latest_logs = [l for ls in latest_logs for l in ls]                          # Flatten [[str]] -> [str]
    i = h - 2
    for l in latest_logs:
        draw_text(cb, x0 + 1, i, l)
        i -= 1
        if i == middle + 1:
            break

Response: Draws the main menu and options.


Instruction:
Make a summary of the following Python 3 code
def update_display(cb, pool, params, plane, qwertz):
    cb.clear()
    draw_panel(cb, pool, params, plane)
    update_position(params)  # Update Mandelbrot-space coordinates before drawing them
    draw_menu(cb, params, qwertz)
    cb.refresh()

Response: Draw all the panels and menu.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def save(params):
    if is_python3():
        import pickle
        cPickle = pickle
    else:
        import cPickle
    ts = datetime.datetime.fromtimestamp(time.time()).strftime("%Y-%m-%d_%H-%M-%S")
    if not os.path.exists("saves/"):
        os.makedirs("saves/")
    with open("saves/almonds_%s.params" % ts, "wb") as f:
        cPickle.dump(params, f)
        params.log("Current scene saved!")

Response: Saves the current parameters to a file.


Instruction:
Make a summary of the following Python 3 code
def capture(cb, pool, params):
    w, h = screen_resolution()

    # Re-adapt dimensions to match current plane ratio
    old_ratio = w / h
    new_ratio = params.plane_ratio
    if old_ratio > new_ratio:
        w = int(h * new_ratio)
    else:
        h = int(w / new_ratio)

    image = Image.new("RGB", (w, h), "white")
    pixels = image.load()

    # FIXME: refactor common code to get_palette(params)
    palette = PALETTES[params.palette][1]
    if params.reverse_palette:
        palette = palette[::-1]

    # All coordinates to be computed as single arguments for processes
    coords = [(x, y, w, h, params) for x in range(w) for y in range(h)]

    results = []
    # Dispatch work to pool and draw results as they come in
    for i, result in enumerate(pool.imap_unordered(compute_capture, coords, chunksize=256)):
        results.append(result)
        if i % 2000 == 0:
            draw_progress_bar(cb, "Capturing current scene...", i, w * h)
            cb.refresh()

    min_value = 0.0
    max_value = params.max_iterations
    max_iterations = params.max_iterations

    if params.adaptive_palette:
        from operator import itemgetter
        min_value = min(results, key=itemgetter(2))[2]
        max_value = max(results, key=itemgetter(2))[2]

    # Draw pixels
    for result in results:
        value = result[2]
        if params.adaptive_palette:
            # Remap values from (min_value, max_value) to (0, max_iterations)
            if max_value - min_value > 0:
                value = ((value - min_value) / (max_value - min_value)) * max_iterations
            else:
                value = max_iterations
        pixels[result[0], result[1]] = get_color(value, params.max_iterations, palette)

    if not os.path.exists("captures/"):
        os.makedirs("captures/")

    ts = datetime.datetime.fromtimestamp(time.time()).strftime("%Y-%m-%d_%H-%M-%S")
    filename = "captures/almonds_%s.png" % ts
    image.save(filename, "PNG")
    params.log("Current scene captured!")
    params.log("(Used %d processes)" % pool._processes)

    open_file(filename)

Response: Renders and saves a screen - sized picture of the current position.


Instruction:
Here you have a function in Python 3, explain what it does
def cycle(cb, pool, params, plane):
    step = params.max_iterations // 20
    if step == 0:
        step = 1
    for i in range(0, params.max_iterations, step):
        params.palette_offset = i
        draw_panel(cb, pool, params, plane)
        cb.refresh()
    params.palette_offset = 0

Response: Cycle the current Mandelbrot by drawing a palette.


Instruction:
Can you implement a function in Python 3 that
initializes coordinates and zoom for first use.

Response:
def init_coords(cb, params):
    """
    Initializes coordinates and zoom for first use.

    Loads coordinates from Mandelbrot-space.

    :param cb: Cursebox instance.
    :type cb: cursebox.Cursebox
    :param params: Current application parameters.
    :type params: params.Params
    :return:
    """
    w = cb.width - MENU_WIDTH - 1
    h = cb.height - 1

    params.plane_w = w
    params.plane_h = h
    params.resize(w, h)

    zoom(params, 1)


Instruction:
How would you explain what the following Python 3 function does
def clamp(n, lower, upper):
    if lower > upper:
        lower, upper = upper, lower
    return max(min(upper, n), lower)

Response: Returns the given number n clamping the given lower and upper bounds.


Instruction:
Write a Python 3 function for
returning the current screen s resolution. Should be multi - platform.

Response:
def screen_resolution():
    """
    Returns the current screen's resolution.

    Should be multi-platform.

    :return: A tuple containing the width and height of the screen.
    """
    w = 0
    h = 0
    try:
        # Windows
        import ctypes
        user32 = ctypes.windll.user32
        w, h = user32.GetSystemMetrics(0), user32.GetSystemMetrics(1)
    except AttributeError:
        try:
            # Mac OS X
            import AppKit
            size = AppKit.NSScreen.screens()[0].frame().size
            w, h = int(size.width), int(size.height)
        except ImportError:
            try:
                # Linux
                import Xlib
                import Xlib.display
                display = Xlib.display.Display()
                root = display.screen().root
                size = root.get_geometry()
                w, h = size.width, size.height
            except ImportError:
                w = 1920
                h = 1080

    return w, h


Instruction:
Make a summary of the following Python 3 code
def open_file(filename):
    if sys.platform.startswith("darwin"):
        subprocess.call(("open", filename))
    elif sys.platform == "cygwin":
        subprocess.call(("cygstart", filename))
    elif os.name == "nt":
        os.system("start %s" % filename)
    elif os.name == "posix":
        subprocess.call(("xdg-open", filename))

Response: Open a file with its default application.


Instruction:
Write a Python 3 function for
returning the appropriate block drawing symbol for the given intensity.

Response:
def dither_symbol(value, dither):
    """
    Returns the appropriate block drawing symbol for the given intensity.
    :param value: intensity of the color, in the range [0.0, 1.0]
    :return: dithered symbol representing that intensity
    """
    dither = DITHER_TYPES[dither][1]
    return dither[int(round(value * (len(dither) - 1)))]


Instruction:
Can you implement a function in Python 3 that
draws a dithered color block on the terminal.

Response:
def draw_dithered_color(cb, x, y, palette, dither, n, n_max, crosshairs_coord=None):
    """
    Draws a dithered color block on the terminal, given a palette.
    :type cb: cursebox.CurseBox
    """
    i = n * (len(palette) - 1) / n_max
    c1 = palette[int(math.floor(i))]
    c2 = palette[int(math.ceil(i))]
    value = i - int(math.floor(i))

    symbol = dither_symbol(value, dither)

    if crosshairs_coord is not None:
        old_symbol = symbol
        symbol, crosshairs = get_crosshairs_symbol(x, y, old_symbol, crosshairs_coord)
        if crosshairs:
            sorted_palette = sort_palette(palette)
            if old_symbol == DITHER_TYPES[dither][1][0]:
                c2 = c1
            sorted_index = sorted_palette.index(c2)
            if sorted_index > len(sorted_palette) // 2:
                c1 = sorted_palette[0]
            else:
                c1 = sorted_palette[-1]

    cb.put(x, y, symbol, c1(), c2())


Instruction:
Explain what the following Python 3 code does
def draw_box(cb, x0, y0, w, h, fg=colors.default_fg, bg=colors.default_bg, h_seps=[], v_seps=[]):
    w -= 1
    h -= 1
    corners = [(x0, y0), (x0 + w, y0), (x0, y0 + h), (x0 + w, y0 + h)]

    fg = fg()
    bg = bg()

    for i, c in enumerate(corners):
        cb.put(c[0], c[1], BOX_CORNERS[i], fg, bg)

    for s in h_seps + [0, h]:
        cb.put(x0 + 1, y0 + s, symbols["BOX_HORIZONTAL"] * (w - 1), fg, bg)

    for y in range(1, h):
        for s in v_seps + [0, w]:
            cb.put(x0 + s, y0 + y, symbols["BOX_VERTICAL"], fg, bg)

    for s in h_seps:
        cb.put(x0,     y0 + s, symbols["BOX_X_LEFT"],  fg, bg)
        cb.put(x0 + w, y0 + s, symbols["BOX_X_RIGHT"], fg, bg)

    for s in v_seps:
        cb.put(x0 + s, y0,     symbols["BOX_X_TOP"],    fg, bg)
        cb.put(x0 + s, y0 + h, symbols["BOX_X_BOTTOM"], fg, bg)

Response: Draws a box in the given terminal.


Instruction:
Make a summary of the following Python 3 code
def draw_progress_bar(cb, message, value, max_value):
    m_x = cb.width // 2
    m_y = cb.height // 2
    w = len(message) + 4
    h = 3
    draw_box(cb, m_x - w // 2, m_y - 1, w, h)
    message = " %s " % message
    i = int((value / max_value) * (len(message) + 2))
    message = "$" + message[:i] + "$" + message[i:]
    draw_text(cb, m_x - w // 2 + 1, m_y, message)

Response: Draws a progress bar.


Instruction:
Make a summary of the following Python 3 code
def mandelbrot_iterate(c, max_iterations, julia_seed=None):
    z = c
    if julia_seed is not None:
        c = julia_seed
    for iterations in range(max_iterations):
        z = z * z + c
        if abs(z) > 1000:
            return z, iterations
    return z, max_iterations

Response: This function is used to iterate over the Mandelbrot fractal sequence.


Instruction:
Write a Python 3 function for
transforming the given coordinates from plane - space to Mandelbrot - space.

Response:
def get_coords(x, y, params):
    """
    Transforms the given coordinates from plane-space to Mandelbrot-space (real and imaginary).

    :param x: X coordinate on the plane.
    :param y: Y coordinate on the plane.
    :param params: Current application parameters.
    :type params: params.Params
    :return: Tuple containing the re-mapped coordinates in Mandelbrot-space.
    """
    n_x = x * 2.0 / params.plane_w * params.plane_ratio - 1.0
    n_y = y * 2.0 / params.plane_h - 1.0
    mb_x = params.zoom * n_x
    mb_y = params.zoom * n_y
    return mb_x, mb_y


Instruction:
Can you create a Python 3 function that
computes the number of iterations of the given plane - space coordinates.

Response:
def mandelbrot(x, y, params):
    """
    Computes the number of iterations of the given plane-space coordinates.

    :param x: X coordinate on the plane.
    :param y: Y coordinate on the plane.
    :param params: Current application parameters.
    :type params: params.Params
    :return: Discrete number of iterations.
    """
    mb_x, mb_y = get_coords(x, y, params)
    mb = mandelbrot_iterate(mb_x + 1j * mb_y, params.max_iterations, params.julia_seed)

    return mb[1]


Instruction:
How would you implement a function in Python 3 that
computes the number of iterations of the given pixel - space coordinates for high - res capture purposes.

Response:
def mandelbrot_capture(x, y, w, h, params):
    """
    Computes the number of iterations of the given pixel-space coordinates,
    for high-res capture purposes.

    Contrary to :func:`mandelbrot`, this function returns a continuous
    number of iterations to avoid banding.

    :param x: X coordinate on the picture
    :param y: Y coordinate on the picture
    :param w: Width of the picture
    :param h: Height of the picture
    :param params: Current application parameters.
    :type params: params.Params
    :return: Continuous number of iterations.
    """

    # FIXME: Figure out why these corrections are necessary or how to make them perfect
    # Viewport is offset compared to window when capturing without these (found empirically)
    if params.plane_ratio >= 1.0:
        x -= params.plane_w
    else:
        x += 3.0 * params.plane_w

    ratio = w / h
    n_x = x * 2.0 / w * ratio - 1.0
    n_y = y * 2.0 / h - 1.0
    mb_x = params.zoom * n_x + params.mb_cx
    mb_y = params.zoom * n_y + params.mb_cy

    mb = mandelbrot_iterate(mb_x + 1j * mb_y, params.max_iterations, params.julia_seed)
    z, iterations = mb

    # Continuous iteration count for no banding
    # https://en.wikipedia.org/wiki/Mandelbrot_set#Continuous_.28smooth.29_coloring
    nu = params.max_iterations
    if iterations < params.max_iterations:
        nu = iterations + 2 - abs(cmath.log(cmath.log(abs(z)) / cmath.log(params.max_iterations), 2))

    return clamp(nu, 0, params.max_iterations)


Instruction:
Can you generate a brief explanation for the following Python 3 code
def update_position(params):
    cx = params.plane_x0 + params.plane_w / 2.0
    cy = params.plane_y0 + params.plane_h / 2.0
    params.mb_cx, params.mb_cy = get_coords(cx, cy, params)

Response: Updates the Mandelbrot - space coordinates of the current application.


Instruction:
Write a Python 3 function for
applying a zoom on the current parameters.

Response:
def zoom(params, factor):
    """
    Applies a zoom on the current parameters.

    Computes the top-left plane-space coordinates from the Mandelbrot-space coordinates.

    :param params: Current application parameters.
    :param factor: Zoom factor by which the zoom ratio is divided (bigger factor, more zoom)
    """
    params.zoom /= factor

    n_x = params.mb_cx / params.zoom
    n_y = params.mb_cy / params.zoom

    params.plane_x0 = int((n_x + 1.0) * params.plane_w / (2.0 * params.plane_ratio)) - params.plane_w // 2
    params.plane_y0 = int((n_y + 1.0) * params.plane_h / 2.0) - params.plane_h // 2


Instruction:
Can you generate a brief explanation for the following Python 3 code
def resize(self, w, h):
        self.plane_w = w
        self.plane_h = h
        self.plane_ratio = self.char_ratio * w / h

        if self.crosshairs:
            self.crosshairs_coord = ((w + 2) // 2, (h + 2) // 2)

Response: Resets the plane ratio factor and the crosshairs coordinate.


Instruction:
Write a Python 3 script for
checking that the sender and entity handles match.

Response:
def check_sender_and_entity_handle_match(sender_handle, entity_handle):
    """Ensure that sender and entity handles match.

    Basically we've already verified the sender is who they say when receiving the payload. However, the sender might
    be trying to set another author in the payload itself, since Diaspora has the sender in both the payload headers
    AND the object. We must ensure they're the same.
    """
    if sender_handle != entity_handle:
        logger.warning("sender_handle and entity_handle don't match, aborting! sender_handle: %s, entity_handle: %s",
                       sender_handle, entity_handle)
        return False
    return True


Instruction:
Explain what the following Python 3 code does
def element_to_objects(
        element: etree.ElementTree, sender: str, sender_key_fetcher:Callable[[str], str]=None, user: UserType =None,
) -> List:
    """Transform an Element to a list of entities recursively.

    Possible child entities are added to each entity ``_children`` list.

    :param tree: Element
    :param sender: Payload sender id
    :param sender_key_fetcher: Function to fetch sender public key. If not given, key will always be fetched
        over network. The function should take sender handle as the only parameter.
    :param user: Optional receiving user object. If given, should have an ``id``.
    :returns: list of entities
    """
    entities = []
    cls = MAPPINGS.get(element.tag)
    if not cls:
        return []

    attrs = xml_children_as_dict(element)
    transformed = transform_attributes(attrs, cls)
    if hasattr(cls, "fill_extra_attributes"):
        transformed = cls.fill_extra_attributes(transformed)
    entity = cls(**transformed)
    # Add protocol name
    entity._source_protocol = "diaspora"
    # Save element object to entity for possible later use
    entity._source_object = etree.tostring(element)
    # Save receiving id to object
    if user:
        entity._receiving_actor_id = user.id
    if issubclass(cls, DiasporaRelayableMixin):
        # If relayable, fetch sender key for validation
        entity._xml_tags = get_element_child_info(element, "tag")
        if sender_key_fetcher:
            entity._sender_key = sender_key_fetcher(entity.actor_id)
        else:
            profile = retrieve_and_parse_profile(entity.handle)
            if profile:
                entity._sender_key = profile.public_key
    else:
        # If not relayable, ensure handles match
        if not check_sender_and_entity_handle_match(sender, entity.handle):
            return []
    try:
        entity.validate()
    except ValueError as ex:
        logger.error("Failed to validate entity %s: %s", entity, ex, extra={
            "attrs": attrs,
            "transformed": transformed,
        })
        return []
    # Extract mentions
    entity._mentions = entity.extract_mentions()
    # Do child elements
    for child in element:
        entity._children.extend(element_to_objects(child, sender, user=user))
    # Add to entities list
    entities.append(entity)
    return entities

Response: Transform an element tree to a list of entities.


Instruction:
How would you explain what the following Python 3 function does
def message_to_objects(
        message: str, sender: str, sender_key_fetcher:Callable[[str], str]=None, user: UserType =None,
) -> List:
    """Takes in a message extracted by a protocol and maps it to entities.

    :param message: XML payload
    :type message: str
    :param sender: Payload sender id
    :type message: str
    :param sender_key_fetcher: Function to fetch sender public key. If not given, key will always be fetched
        over network. The function should take sender handle as the only parameter.
    :param user: Optional receiving user object. If given, should have a `handle`.
    :returns: list of entities
    """
    doc = etree.fromstring(message)
    if doc.tag in TAGS:
        return element_to_objects(doc, sender, sender_key_fetcher, user)
    return []

Response: Takes in a message extracted by a protocol and maps it to a list of entities.


Instruction:
Write a Python 3 function for
transforming some attribute keys.

Response:
def transform_attributes(attrs, cls):
    """Transform some attribute keys.

    :param attrs: Properties from the XML
    :type attrs: dict
    :param cls: Class of the entity
    :type cls: class
    """
    transformed = {}
    for key, value in attrs.items():
        if value is None:
            value = ""
        if key == "text":
            transformed["raw_content"] = value
        elif key == "author":
            if cls == DiasporaProfile:
                # Diaspora Profile XML message contains no GUID. We need the guid. Fetch it.
                profile = retrieve_and_parse_profile(value)
                transformed['id'] = value
                transformed["guid"] = profile.guid
            else:
                transformed["actor_id"] = value
            transformed["handle"] = value
        elif key == 'guid':
            if cls != DiasporaProfile:
                transformed["id"] = value
                transformed["guid"] = value
        elif key in ("root_author", "recipient"):
            transformed["target_id"] = value
            transformed["target_handle"] = value
        elif key in ("target_guid", "root_guid", "parent_guid"):
            transformed["target_id"] = value
            transformed["target_guid"] = value
        elif key in ("first_name", "last_name"):
            values = [attrs.get('first_name'), attrs.get('last_name')]
            values = [v for v in values if v]
            transformed["name"] = " ".join(values)
        elif key == "image_url":
            if "image_urls" not in transformed:
                transformed["image_urls"] = {}
            transformed["image_urls"]["large"] = value
        elif key == "image_url_small":
            if "image_urls" not in transformed:
                transformed["image_urls"] = {}
            transformed["image_urls"]["small"] = value
        elif key == "image_url_medium":
            if "image_urls" not in transformed:
                transformed["image_urls"] = {}
            transformed["image_urls"]["medium"] = value
        elif key == "tag_string":
            if value:
                transformed["tag_list"] = value.replace("#", "").split(" ")
        elif key == "bio":
            transformed["raw_content"] = value
        elif key == "searchable":
            transformed["public"] = True if value == "true" else False
        elif key in ["target_type"] and cls == DiasporaRetraction:
            transformed["entity_type"] = DiasporaRetraction.entity_type_from_remote(value)
        elif key == "remote_photo_path":
            transformed["remote_path"] = value
        elif key == "remote_photo_name":
            transformed["remote_name"] = value
        elif key == "status_message_guid":
            transformed["linked_guid"] = value
            transformed["linked_type"] = "Post"
        elif key == "author_signature":
            transformed["signature"] = value
        elif key in BOOLEAN_KEYS:
            transformed[key] = True if value == "true" else False
        elif key in DATETIME_KEYS:
            transformed[key] = datetime.strptime(value, "%Y-%m-%dT%H:%M:%SZ")
        elif key in INTEGER_KEYS:
            transformed[key] = int(value)
        else:
            transformed[key] = value
    return transformed


Instruction:
Can you implement a function in Python 3 that
returns the correct entity for this protocol.

Response:
def get_outbound_entity(entity: BaseEntity, private_key: RsaKey):
    """Get the correct outbound entity for this protocol.

    We might have to look at entity values to decide the correct outbound entity.
    If we cannot find one, we should raise as conversion cannot be guaranteed to the given protocol.

    Private key of author is needed to be passed for signing the outbound entity.

    :arg entity: An entity instance which can be of a base or protocol entity class.
    :arg private_key: Private key of sender as an RSA object
    :returns: Protocol specific entity class instance.
    :raises ValueError: If conversion cannot be done.
    """
    if getattr(entity, "outbound_doc", None):
        # If the entity already has an outbound doc, just return the entity as is
        return entity
    outbound = None
    cls = entity.__class__
    if cls in [DiasporaPost, DiasporaImage, DiasporaComment, DiasporaLike, DiasporaProfile, DiasporaRetraction,
               DiasporaContact, DiasporaReshare]:
        # Already fine
        outbound = entity
    elif cls == Post:
        outbound = DiasporaPost.from_base(entity)
    elif cls == Comment:
        outbound = DiasporaComment.from_base(entity)
    elif cls == Reaction:
        if entity.reaction == "like":
            outbound = DiasporaLike.from_base(entity)
    elif cls == Follow:
        outbound = DiasporaContact.from_base(entity)
    elif cls == Profile:
        outbound = DiasporaProfile.from_base(entity)
    elif cls == Retraction:
        outbound = DiasporaRetraction.from_base(entity)
    elif cls == Share:
        outbound = DiasporaReshare.from_base(entity)
    if not outbound:
        raise ValueError("Don't know how to convert this base entity to Diaspora protocol entities.")
    if isinstance(outbound, DiasporaRelayableMixin) and not outbound.signature:
        # Sign by author if not signed yet. We don't want to overwrite any existing signature in the case
        # that this is being sent by the parent author
        outbound.sign(private_key)
        # If missing, also add same signature to `parent_author_signature`. This is required at the moment
        # in all situations but is apparently being removed.
        # TODO: remove this once Diaspora removes the extra signature
        outbound.parent_signature = outbound.signature
    return outbound


Instruction:
Write a Python 3 function that can
get information from child elements of this element as a list since order is important.

Response:
def get_element_child_info(doc, attr):
    """Get information from child elements of this elementas a list since order is important.

    Don't include signature tags.

    :param doc: XML element
    :param attr: Attribute to get from the elements, for example "tag" or "text".
    """
    props = []
    for child in doc:
        if child.tag not in ["author_signature", "parent_author_signature"]:
            props.append(getattr(child, attr))
    return props


Instruction:
Create a Python 3 function to
verify that the signed XML elements are signed by the claimed author.

Response:
def verify_relayable_signature(public_key, doc, signature):
    """
    Verify the signed XML elements to have confidence that the claimed
    author did actually generate this message.
    """
    sig_hash = _create_signature_hash(doc)
    cipher = PKCS1_v1_5.new(RSA.importKey(public_key))
    return cipher.verify(sig_hash, b64decode(signature))


Instruction:
Can you generate the documentation for the following Python 3 function
def parse_diaspora_webfinger(document):
    webfinger = {
        "hcard_url": None,
    }
    try:
        doc = json.loads(document)
        for link in doc["links"]:
            if link["rel"] == "http://microformats.org/profile/hcard":
                webfinger["hcard_url"] = link["href"]
                break
        else:
            logger.warning("parse_diaspora_webfinger: found JSON webfinger but it has no hcard href")
            raise ValueError
    except Exception:
        try:
            xrd = XRD.parse_xrd(document)
            webfinger["hcard_url"] = xrd.find_link(rels="http://microformats.org/profile/hcard").href
        except xml.parsers.expat.ExpatError:
            logger.warning("parse_diaspora_webfinger: found XML webfinger but it fails to parse (ExpatError)")
            pass
    return webfinger

Response: Parses Diaspora webfinger which is either in JSON format or XRD format.


Instruction:
How would you explain what the following Python 3 function does
def retrieve_diaspora_hcard(handle):
    webfinger = retrieve_and_parse_diaspora_webfinger(handle)
    document, code, exception = fetch_document(webfinger.get("hcard_url"))
    if exception:
        return None
    return document

Response: Retrieve a remote Diaspora hCard document.


Instruction:
Here you have a function in Python 3, explain what it does
def retrieve_and_parse_diaspora_webfinger(handle):
    try:
        host = handle.split("@")[1]
    except AttributeError:
        logger.warning("retrieve_and_parse_diaspora_webfinger: invalid handle given: %s", handle)
        return None
    document, code, exception = fetch_document(
        host=host, path="/.well-known/webfinger?resource=acct:%s" % quote(handle),
    )
    if document:
        return parse_diaspora_webfinger(document)
    hostmeta = retrieve_diaspora_host_meta(host)
    if not hostmeta:
        return None
    url = hostmeta.find_link(rels="lrdd").template.replace("{uri}", quote(handle))
    document, code, exception = fetch_document(url)
    if exception:
        return None
    return parse_diaspora_webfinger(document)

Response: Retrieve a and parse a remote Diaspora webfinger document.


Instruction:
Can you implement a function in Python 3 that
retrieves a remote Diaspora host - meta document.

Response:
def retrieve_diaspora_host_meta(host):
    """
    Retrieve a remote Diaspora host-meta document.

    :arg host: Host to retrieve from
    :returns: ``XRD`` instance
    """
    document, code, exception = fetch_document(host=host, path="/.well-known/host-meta")
    if exception:
        return None
    xrd = XRD.parse_xrd(document)
    return xrd


Instruction:
How would you implement a function in Python 3 that
gets the element text or None if no element.

Response:
def _get_element_text_or_none(document, selector):
    """
    Using a CSS selector, get the element and return the text, or None if no element.

    :arg document: ``HTMLElement`` document
    :arg selector: CSS selector
    :returns: str or None
    """
    element = document.cssselect(selector)
    if element:
        return element[0].text
    return None


Instruction:
Can you generate a brief explanation for the following Python 3 code
def _get_element_attr_or_none(document, selector, attribute):
    element = document.cssselect(selector)
    if element:
        return element[0].get(attribute)
    return None

Response: Get the element and return the given attribute value or None if no element is found.


Instruction:
Can you implement a function in Python 3 that
parses all the fields we can from a hCard document to get a Profile.

Response:
def parse_profile_from_hcard(hcard: str, handle: str):
    """
    Parse all the fields we can from a hCard document to get a Profile.

    :arg hcard: HTML hcard document (str)
    :arg handle: User handle in username@domain.tld format
    :returns: ``federation.entities.diaspora.entities.DiasporaProfile`` instance
    """
    from federation.entities.diaspora.entities import DiasporaProfile  # Circulars
    doc = html.fromstring(hcard)
    profile = DiasporaProfile(
        name=_get_element_text_or_none(doc, ".fn"),
        image_urls={
            "small": _get_element_attr_or_none(doc, ".entity_photo_small .photo", "src"),
            "medium": _get_element_attr_or_none(doc, ".entity_photo_medium .photo", "src"),
            "large": _get_element_attr_or_none(doc, ".entity_photo .photo", "src"),
        },
        public=True if _get_element_text_or_none(doc, ".searchable") == "true" else False,
        id=handle,
        handle=handle,
        guid=_get_element_text_or_none(doc, ".uid"),
        public_key=_get_element_text_or_none(doc, ".key"),
    )
    return profile


Instruction:
Make a summary of the following Python 3 code
def retrieve_and_parse_content(
        guid: str, handle: str, entity_type: str, sender_key_fetcher: Callable[[str], str]=None,
):
    """Retrieve remote content and return an Entity class instance.

    This is basically the inverse of receiving an entity. Instead, we fetch it, then call "handle_receive".

    :param sender_key_fetcher: Function to use to fetch sender public key. If not given, network will be used
        to fetch the profile and the key. Function must take handle as only parameter and return a public key.
    :returns: Entity object instance or ``None``
    """
    if not validate_handle(handle):
        return
    _username, domain = handle.split("@")
    url = get_fetch_content_endpoint(domain, entity_type.lower(), guid)
    document, status_code, error = fetch_document(url)
    if status_code == 200:
        request = RequestType(body=document)
        _sender, _protocol, entities = handle_receive(request, sender_key_fetcher=sender_key_fetcher)
        if len(entities) > 1:
            logger.warning("retrieve_and_parse_content - more than one entity parsed from remote even though we"
                           "expected only one! ID %s", guid)
        if entities:
            return entities[0]
        return
    elif status_code == 404:
        logger.warning("retrieve_and_parse_content - remote content %s not found", guid)
        return
    if error:
        raise error
    raise Exception("retrieve_and_parse_content - unknown problem when fetching document: %s, %s, %s" % (
        document, status_code, error,
    ))

Response: Retrieve remote content and parse it.


Instruction:
Here you have a function in Python 3, explain what it does
def retrieve_and_parse_profile(handle):
    hcard = retrieve_diaspora_hcard(handle)
    if not hcard:
        return None
    profile = parse_profile_from_hcard(hcard, handle)
    try:
        profile.validate()
    except ValueError as ex:
        logger.warning("retrieve_and_parse_profile - found profile %s but it didn't validate: %s",
                       profile, ex)
        return None
    return profile

Response: Retrieve the remote user and return a Profile object.


Instruction:
Create a Python 3 function to
get remote endpoint for delivering private payloads.

Response:
def get_private_endpoint(id: str, guid: str) -> str:
    """Get remote endpoint for delivering private payloads."""
    _username, domain = id.split("@")
    return "https://%s/receive/users/%s" % (domain, guid)


Instruction:
Make a summary of the following Python 3 code
def ensure_timezone(dt, tz=None):
    if dt.tzinfo is None:
        return dt.replace(tzinfo=tz or tzlocal())
    else:
        return dt

Response: Ensure the datetime <dt > has a timezone set using timezone <tz >.


Instruction:
Can you write a function in Python 3 where it
turns a list of dicts into XML nodes with tag names taken from the dict keys and element text taken from the dict values.

Response:
def struct_to_xml(node, struct):
    """
    Turn a list of dicts into XML nodes with tag names taken from the dict
    keys and element text taken from dict values. This is a list of dicts
    so that the XML nodes can be ordered in the XML output.
    """
    for obj in struct:
        for k, v in obj.items():
            etree.SubElement(node, k).text = v


Instruction:
Write a Python 3 script for
getting full XML representation of an entity.

Response:
def get_full_xml_representation(entity, private_key):
    """Get full XML representation of an entity.

    This contains the <XML><post>..</post></XML> wrapper.

    Accepts either a Base entity or a Diaspora entity.

    Author `private_key` must be given so that certain entities can be signed.
    """
    from federation.entities.diaspora.mappers import get_outbound_entity
    diaspora_entity = get_outbound_entity(entity, private_key)
    xml = diaspora_entity.to_xml()
    return "<XML><post>%s</post></XML>" % etree.tostring(xml).decode("utf-8")


Instruction:
How would you explain what the following Python 3 function does
def add_element_to_doc(doc, tag, value):
    element = doc.find(".//%s" % tag)
    if element is None:
        element = etree.SubElement(doc, tag)
    element.text = value

Response: Set text value of an etree. Element of tag appending a new element with given tag.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def generate_host_meta(template=None, *args, **kwargs):
    if template == "diaspora":
        hostmeta = DiasporaHostMeta(*args, **kwargs)
    else:
        hostmeta = BaseHostMeta(*args, **kwargs)
    return hostmeta.render()

Response: Generate a host - meta XRD document.


Instruction:
Can you generate the documentation for the following Python 3 function
def generate_legacy_webfinger(template=None, *args, **kwargs):
    if template == "diaspora":
        webfinger = DiasporaWebFinger(*args, **kwargs)
    else:
        webfinger = BaseLegacyWebFinger(*args, **kwargs)
    return webfinger.render()

Response: Generate a legacy webfinger XRD document.


Instruction:
Explain what the following Python 3 code does
def generate_nodeinfo2_document(**kwargs):
    return {
        "version": "1.0",
        "server": {
            "baseUrl": kwargs['server']['baseUrl'],
            "name": kwargs['server']['name'],
            "software": kwargs['server']['software'],
            "version": kwargs['server']['version'],
        },
        "organization": {
            "name": kwargs.get('organization', {}).get('name', None),
            "contact": kwargs.get('organization', {}).get('contact', None),
            "account": kwargs.get('organization', {}).get('account', None),
        },
        "protocols": kwargs.get('protocols', ["diaspora"]),
        "relay": kwargs.get('relay', ''),
        "services": {
            "inbound": kwargs.get('service', {}).get('inbound', []),
            "outbound": kwargs.get('service', {}).get('outbound', []),
        },
        "openRegistrations": kwargs['openRegistrations'],
        "usage": {
            "users": {
                "total": kwargs.get('usage', {}).get('users', {}).get('total'),
                "activeHalfyear": kwargs.get('usage', {}).get('users', {}).get('activeHalfyear'),
                "activeMonth": kwargs.get('usage', {}).get('users', {}).get('activeMonth'),
                "activeWeek": kwargs.get('usage', {}).get('users', {}).get('activeWeek'),
            },
            "localPosts": kwargs.get('usage', {}).get('localPosts'),
            "localComments": kwargs.get('usage', {}).get('localComments'),
        }
    }

Response: Generate a NodeInfo2 document.


Instruction:
Given the following Python 3 function, write the documentation
def generate_hcard(template=None, **kwargs):
    if template == "diaspora":
        hcard = DiasporaHCard(**kwargs)
    else:
        raise NotImplementedError()
    return hcard.render()

Response: Generate a hCard document.


Instruction:
How would you explain what the following Python 3 function does
def retrieve_remote_content(
        id: str, guid: str=None, handle: str=None, entity_type: str=None, sender_key_fetcher: Callable[[str], str]=None,
):
    """Retrieve remote content and return an Entity object.

    Currently, due to no other protocols supported, always use the Diaspora protocol.

    :param sender_key_fetcher: Function to use to fetch sender public key. If not given, network will be used
        to fetch the profile and the key. Function must take handle as only parameter and return a public key.
    :returns: Entity class instance or ``None``
    """
    # TODO add support for AP
    protocol_name = "diaspora"
    if not guid:
        guid = id
    utils = importlib.import_module("federation.utils.%s" % protocol_name)
    return utils.retrieve_and_parse_content(
        guid=guid, handle=handle, entity_type=entity_type, sender_key_fetcher=sender_key_fetcher,
    )

Response: Retrieve remote content and return an Entity object.


Instruction:
Can you generate the documentation for the following Python 3 function
def retrieve_remote_profile(id: str) -> Optional[Profile]:
    protocol = identify_protocol_by_id(id)
    utils = importlib.import_module(f"federation.utils.{protocol.PROTOCOL_NAME}")
    return utils.retrieve_and_parse_profile(id)

Response: High level retrieve profile method.


Instruction:
Can you generate the documentation for the following Python 3 function
def handle_receive(
        request: RequestType,
        user: UserType = None,
        sender_key_fetcher: Callable[[str], str] = None,
        skip_author_verification: bool = False
) -> Tuple[str, str, List]:
    """Takes a request and passes it to the correct protocol.

    Returns a tuple of:
      - sender id
      - protocol name
      - list of entities

    NOTE! The returned sender is NOT necessarily the *author* of the entity. By sender here we're
    talking about the sender of the *request*. If this object is being relayed by the sender, the author
    could actually be a different identity.

    :arg request: Request object of type RequestType - note not a HTTP request even though the structure is similar
    :arg user: User that will be passed to `protocol.receive` (only required on private encrypted content)
        MUST have a `private_key` and `id` if given.
    :arg sender_key_fetcher: Function that accepts sender handle and returns public key (optional)
    :arg skip_author_verification: Don't verify sender (test purposes, false default)
    :returns: Tuple of sender id, protocol name and list of entity objects
    """
    logger.debug("handle_receive: processing request: %s", request)
    found_protocol = identify_protocol_by_request(request)

    logger.debug("handle_receive: using protocol %s", found_protocol.PROTOCOL_NAME)
    protocol = found_protocol.Protocol()
    sender, message = protocol.receive(
        request, user, sender_key_fetcher, skip_author_verification=skip_author_verification)
    logger.debug("handle_receive: sender %s, message %s", sender, message)

    mappers = importlib.import_module("federation.entities.%s.mappers" % found_protocol.PROTOCOL_NAME)
    entities = mappers.message_to_objects(message, sender, sender_key_fetcher, user)
    logger.debug("handle_receive: entities %s", entities)

    return sender, found_protocol.PROTOCOL_NAME, entities

Response: Takes a request and passes it to the correct protocol.


Instruction:
Explain what the following Python 3 code does
def identify_id(id: str) -> bool:
    return re.match(r'^https?://', id, flags=re.IGNORECASE) is not None

Response: Try to identify whether this is an ActivityPub ID.


Instruction:
Explain what the following Python 3 code does
def identify_request(request: RequestType) -> bool:
    # noinspection PyBroadException
    try:
        data = json.loads(decode_if_bytes(request.body))
        if "@context" in data:
            return True
    except Exception:
        pass
    return False

Response: Identify whether this is an ActivityPub request.


Instruction:
How would you explain what the following Python 3 function does
def build_send(self, entity: BaseEntity, from_user: UserType, to_user_key: RsaKey = None) -> Union[str, Dict]:
        if hasattr(entity, "outbound_doc") and entity.outbound_doc is not None:
            # Use pregenerated outbound document
            rendered = entity.outbound_doc
        else:
            rendered = entity.to_as2()
        return rendered

Response: Builds the POST data for sending out to remotes.


Instruction:
Can you tell what is the following Python 3 function doing
def receive(
            self,
            request: RequestType,
            user: UserType = None,
            sender_key_fetcher: Callable[[str], str] = None,
            skip_author_verification: bool = False) -> Tuple[str, dict]:
        """
        Receive a request.

        For testing purposes, `skip_author_verification` can be passed. Authorship will not be verified.
        """
        self.user = user
        self.get_contact_key = sender_key_fetcher
        self.payload = json.loads(decode_if_bytes(request.body))
        self.request = request
        self.extract_actor()
        # Verify the message is from who it claims to be
        if not skip_author_verification:
            self.verify_signature()
        return self.actor, self.payload

Response:
Receive a request.

        For testing purposes, `skip_author_verification` can be passed. Authorship will not be verified.


Instruction:
Write a Python 3 script for
combining defaults with the Django configuration.

Response:
def get_configuration():
    """
    Combine defaults with the Django configuration.
    """
    configuration = {
        "get_object_function": None,
        "hcard_path": "/hcard/users/",
        "nodeinfo2_function": None,
        "process_payload_function": None,
        "search_path": None,
        # TODO remove or default to True once AP support is more ready
        "activitypub": False,
    }
    configuration.update(settings.FEDERATION)
    if not all([
        "get_private_key_function" in configuration,
        "get_profile_function" in configuration,
        "base_url" in configuration,
    ]):
        raise ImproperlyConfigured("Missing required FEDERATION settings, please check documentation.")
    return configuration


Instruction:
Here you have a function in Python 3, explain what it does
def get_function_from_config(item):
    config = get_configuration()
    func_path = config.get(item)
    module_path, func_name = func_path.rsplit(".", 1)
    module = importlib.import_module(module_path)
    func = getattr(module, func_name)
    return func

Response: Import the function to get profile by handle.


Instruction:
Can you generate the documentation for the following Python 3 function
def post_receive(self) -> None:
        from federation.utils.activitypub import retrieve_and_parse_profile  # Circulars
        try:
            from federation.utils.django import get_function_from_config
        except ImportError:
            logger.warning("ActivitypubFollow.post_receive - Unable to send automatic Accept back, only supported on "
                           "Django currently")
            return
        get_private_key_function = get_function_from_config("get_private_key_function")
        key = get_private_key_function(self.target_id)
        if not key:
            logger.warning("ActivitypubFollow.post_receive - Failed to send automatic Accept back: could not find "
                           "profile to sign it with")
            return
        accept = ActivitypubAccept(
            activity_id=f"{self.target_id}#accept-{uuid.uuid4()}",
            actor_id=self.target_id,
            target_id=self.activity_id,
        )
        try:
            profile = retrieve_and_parse_profile(self.actor_id)
        except Exception:
            profile = None
        if not profile:
            logger.warning("ActivitypubFollow.post_receive - Failed to fetch remote profile for sending back Accept")
            return
        try:
            handle_send(
                accept,
                UserType(id=self.target_id, private_key=key),
                recipients=[{
                    "fid": profile.inboxes["private"],
                    "protocol": "activitypub",
                    "public": False,
                }],
            )
        except Exception:
            logger.exception("ActivitypubFollow.post_receive - Failed to send Accept back")

Response: Send back an Accept message to the Activitypub server.


Instruction:
Write a Python 3 function that can
retrieve remote document by ID and return the entity.

Response:
def retrieve_and_parse_document(fid: str) -> Optional[Any]:
    """
    Retrieve remote document by ID and return the entity.
    """
    document, status_code, ex = fetch_document(fid, extra_headers={'accept': 'application/activity+json'})
    if document:
        document = json.loads(decode_if_bytes(document))
        entities = message_to_objects(document, fid)
        if entities:
            return entities[0]


Instruction:
Can you generate the documentation for the following Python 3 function
def retrieve_and_parse_profile(fid: str) -> Optional[ActivitypubProfile]:
    profile = retrieve_and_parse_document(fid)
    if not profile:
        return
    try:
        profile.validate()
    except ValueError as ex:
        logger.warning("retrieve_and_parse_profile - found profile %s but it didn't validate: %s",
                       profile, ex)
        return
    return profile

Response: Retrieve the remote fid and return a Profile object.


Instruction:
Write a Python 3 function that can
find the protocol that matches the given method and value.

Response:
def identify_protocol(method, value):
    # type: (str, Union[str, RequestType]) -> str
    """
    Loop through protocols, import the protocol module and try to identify the id or request.
    """
    for protocol_name in PROTOCOLS:
        protocol = importlib.import_module(f"federation.protocols.{protocol_name}.protocol")
        if getattr(protocol, f"identify_{method}")(value):
            return protocol
    else:
        raise NoSuitableProtocolFoundError()


Instruction:
How would you implement a function in Python 3 that
tries to identify whether this is a Diaspora request.

Response:
def identify_request(request: RequestType):
    """Try to identify whether this is a Diaspora request.

    Try first public message. Then private message. The check if this is a legacy payload.
    """
    # Private encrypted JSON payload
    try:
        data = json.loads(decode_if_bytes(request.body))
        if "encrypted_magic_envelope" in data:
            return True
    except Exception:
        pass
    # Public XML payload
    try:
        xml = etree.fromstring(encode_if_text(request.body))
        if xml.tag == MAGIC_ENV_TAG:
            return True
    except Exception:
        pass
    return False


Instruction:
Write a Python 3 script to
get the Magic Envelope and store it in the self. doc attribute.

Response:
def store_magic_envelope_doc(self, payload):
        """Get the Magic Envelope, trying JSON first."""
        try:
            json_payload = json.loads(decode_if_bytes(payload))
        except ValueError:
            # XML payload
            xml = unquote(decode_if_bytes(payload))
            xml = xml.lstrip().encode("utf-8")
            logger.debug("diaspora.protocol.store_magic_envelope_doc: xml payload: %s", xml)
            self.doc = etree.fromstring(xml)
        else:
            logger.debug("diaspora.protocol.store_magic_envelope_doc: json payload: %s", json_payload)
            self.doc = self.get_json_payload_magic_envelope(json_payload)


Instruction:
Can you create a Python 3 function that
receives a message from the client.

Response:
def receive(
            self,
            request: RequestType,
            user: UserType = None,
            sender_key_fetcher: Callable[[str], str] = None,
            skip_author_verification: bool = False) -> Tuple[str, str]:
        """Receive a payload.

        For testing purposes, `skip_author_verification` can be passed. Authorship will not be verified."""
        self.user = user
        self.get_contact_key = sender_key_fetcher
        self.store_magic_envelope_doc(request.body)
        # Open payload and get actual message
        self.content = self.get_message_content()
        # Get sender handle
        self.sender_handle = self.get_sender()
        # Verify the message is from who it claims to be
        if not skip_author_verification:
            self.verify_signature()
        return self.sender_handle, self.content


Instruction:
Can you generate the documentation for the following Python 3 function
def get_message_content(self):
        body = self.doc.find(
            ".//{http://salmon-protocol.org/ns/magic-env}data").text

        body = urlsafe_b64decode(body.encode("ascii"))

        logger.debug("diaspora.protocol.get_message_content: %s", body)
        return body

Response: Given the Slap XML extract out the payload.


Instruction:
Make a summary of the following Python 3 code
def verify_signature(self):
        if self.get_contact_key:
            sender_key = self.get_contact_key(self.sender_handle)
        else:
            sender_key = fetch_public_key(self.sender_handle)
        if not sender_key:
            raise NoSenderKeyFoundError("Could not find a sender contact to retrieve key")
        MagicEnvelope(doc=self.doc, public_key=sender_key, verify=True)

Response: Verify that the signed XML elements have the confidence of the claimedCOOKIE.


Instruction:
Explain what the following Python 3 code does
def build_send(self, entity: BaseEntity, from_user: UserType, to_user_key: RsaKey = None) -> Union[str, Dict]:
        if entity.outbound_doc is not None:
            # Use pregenerated outbound document
            xml = entity.outbound_doc
        else:
            xml = entity.to_xml()
        me = MagicEnvelope(etree.tostring(xml), private_key=from_user.private_key, author_handle=from_user.handle)
        rendered = me.render()
        if to_user_key:
            return EncryptedPayload.encrypt(rendered, to_user_key)
        return rendered

Response: Builds the POST data for sending out to remotes.


Instruction:
Explain what the following Python 3 code does
def validate_reaction(self):
        if self.reaction not in self._reaction_valid_values:
            raise ValueError("reaction should be one of: {valid}".format(
                valid=", ".join(self._reaction_valid_values)
            ))

Response: Ensure that the reaction is of a certain type.


Instruction:
Given the following Python 3 function, write the documentation
def validate_relationship(self):
        if self.relationship not in self._relationship_valid_values:
            raise ValueError("relationship should be one of: {valid}".format(
                valid=", ".join(self._relationship_valid_values)
            ))

Response: Ensure that the relationship is of a certain type.


Instruction:
Can you create a Python 3 function that
transforms an Element to a list of entities recursively.

Response:
def element_to_objects(payload: Dict) -> List:
    """
    Transform an Element to a list of entities recursively.
    """
    entities = []
    cls = MAPPINGS.get(payload.get('type'))
    if not cls:
        return []

    transformed = transform_attributes(payload, cls)
    entity = cls(**transformed)

    if hasattr(entity, "post_receive"):
        entity.post_receive()

    entities.append(entity)

    return entities


Instruction:
How would you explain what the following Python 3 function does
def get_outbound_entity(entity: BaseEntity, private_key):
    if getattr(entity, "outbound_doc", None):
        # If the entity already has an outbound doc, just return the entity as is
        return entity
    outbound = None
    cls = entity.__class__
    if cls in [ActivitypubAccept, ActivitypubFollow, ActivitypubProfile]:
        # Already fine
        outbound = entity
    elif cls == Accept:
        outbound = ActivitypubAccept.from_base(entity)
    elif cls == Follow:
        outbound = ActivitypubFollow.from_base(entity)
    elif cls == Profile:
        outbound = ActivitypubProfile.from_base(entity)
    if not outbound:
        raise ValueError("Don't know how to convert this base entity to ActivityPub protocol entities.")
    # TODO LDS signing
    # if isinstance(outbound, DiasporaRelayableMixin) and not outbound.signature:
    #     # Sign by author if not signed yet. We don't want to overwrite any existing signature in the case
    #     # that this is being sent by the parent author
    #     outbound.sign(private_key)
    #     # If missing, also add same signature to `parent_author_signature`. This is required at the moment
    #     # in all situations but is apparently being removed.
    #     # TODO: remove this once Diaspora removes the extra signature
    #     outbound.parent_signature = outbound.signature
    return outbound

Response: Returns the correct entity for this protocol.


Instruction:
Can you tell what is the following Python 3 function doing
def message_to_objects(
        message: Dict, sender: str, sender_key_fetcher: Callable[[str], str] = None, user: UserType = None,
) -> List:
    """
    Takes in a message extracted by a protocol and maps it to entities.
    """
    # We only really expect one element here for ActivityPub.
    return element_to_objects(message)

Response: Takes in a message extracted by a protocol and maps it to entities.


Instruction:
Can you create a Python 3 function that
does validation. 1) Check `_required` have been given 2) Make sure all attrs in required have a non-empty value 3) Loop through attributes and call their `validate_<attr>` methods, if any. 4) Validate allowed children 5) Validate signatures

Response:
def validate(self):
        """Do validation.

        1) Check `_required` have been given
        2) Make sure all attrs in required have a non-empty value
        3) Loop through attributes and call their `validate_<attr>` methods, if any.
        4) Validate allowed children
        5) Validate signatures
        """
        attributes = []
        validates = []
        # Collect attributes and validation methods
        for attr in dir(self):
            if not attr.startswith("_"):
                attr_type = type(getattr(self, attr))
                if attr_type != "method":
                    if getattr(self, "validate_{attr}".format(attr=attr), None):
                        validates.append(getattr(self, "validate_{attr}".format(attr=attr)))
                    attributes.append(attr)
        self._validate_empty_attributes(attributes)
        self._validate_required(attributes)
        self._validate_attributes(validates)
        self._validate_children()
        self._validate_signatures()


Instruction:
Make a summary of the following Python 3 code
def _validate_required(self, attributes):
        required_fulfilled = set(self._required).issubset(set(attributes))
        if not required_fulfilled:
            raise ValueError(
                "Not all required attributes fulfilled. Required: {required}".format(required=set(self._required))
            )

Response: Ensure required attributes are present.


Instruction:
Make a summary of the following Python 3 code
def _validate_empty_attributes(self, attributes):
        attrs_to_check = set(self._required) & set(attributes)
        for attr in attrs_to_check:
            value = getattr(self, attr)  # We should always have a value here
            if value is None or value == "":
                raise ValueError(
                    "Attribute %s cannot be None or an empty string since it is required." % attr
                )

Response: Check that required attributes are not empty.


Instruction:
Write a Python 3 script to
check that the children we have are allowed here.

Response:
def _validate_children(self):
        """Check that the children we have are allowed here."""
        for child in self._children:
            if child.__class__ not in self._allowed_children:
                raise ValueError(
                    "Child %s is not allowed as a children for this %s type entity." % (
                        child, self.__class__
                    )
                )


Instruction:
Write a Python 3 script for
ensuring participation is of a certain type.

Response:
def validate_participation(self):
        """Ensure participation is of a certain type."""
        if self.participation not in self._participation_valid_values:
            raise ValueError("participation should be one of: {valid}".format(
                valid=", ".join(self._participation_valid_values)
            ))


Instruction:
Can you create a Python 3 function that
returns a set of unique tags contained in raw_content.

Response:
def tags(self):
        """Returns a `set` of unique tags contained in `raw_content`."""
        if not self.raw_content:
            return set()
        return {word.strip("#").lower() for word in self.raw_content.split() if word.startswith("#") and len(word) > 1}


Instruction:
Explain what the following Python 3 code does
def handle_create_payload(
        entity: BaseEntity,
        author_user: UserType,
        protocol_name: str,
        to_user_key: RsaKey = None,
        parent_user: UserType = None,
) -> str:
    """Create a payload with the given protocol.

    Any given user arguments must have ``private_key`` and ``handle`` attributes.

    :arg entity: Entity object to send. Can be a base entity or a protocol specific one.
    :arg author_user: User authoring the object.
    :arg protocol_name: Protocol to create payload for.
    :arg to_user_key: Public key of user private payload is being sent to, required for private payloads.
    :arg parent_user: (Optional) User object of the parent object, if there is one. This must be given for the
                      Diaspora protocol if a parent object exists, so that a proper ``parent_author_signature`` can
                      be generated. If given, the payload will be sent as this user.
    :returns: Built payload message (str)
    """
    mappers = importlib.import_module(f"federation.entities.{protocol_name}.mappers")
    protocol = importlib.import_module(f"federation.protocols.{protocol_name}.protocol")
    protocol = protocol.Protocol()
    outbound_entity = mappers.get_outbound_entity(entity, author_user.private_key)
    if parent_user:
        outbound_entity.sign_with_parent(parent_user.private_key)
    send_as_user = parent_user if parent_user else author_user
    data = protocol.build_send(entity=outbound_entity, from_user=send_as_user, to_user_key=to_user_key)
    return data

Response: Create a payload for the given entity.


Instruction:
How would you explain what the following Python 3 function does
def handle_send(
        entity: BaseEntity,
        author_user: UserType,
        recipients: List[Dict],
        parent_user: UserType = None,
) -> None:
    """Send an entity to remote servers.

    Using this we will build a list of payloads per protocol. After that, each recipient will get the generated
    protocol payload delivered. Delivery to the same endpoint will only be done once so it's ok to include
    the same endpoint as a receiver multiple times.

    Any given user arguments must have ``private_key`` and ``fid`` attributes.

    :arg entity: Entity object to send. Can be a base entity or a protocol specific one.
    :arg author_user: User authoring the object.
    :arg recipients: A list of recipients to delivery to. Each recipient is a dict
                     containing at minimum the "fid", "public" and "protocol" keys.

                     For ActivityPub and Diaspora payloads, "fid" should be an URL of the endpoint to deliver to.

                     The "protocol" should be a protocol name that is known for this recipient.

                     The "public" value should be a boolean to indicate whether the payload should be flagged as a
                     public payload.

                     TODO: support guessing the protocol over networks? Would need caching of results

                     For private deliveries to Diaspora protocol recipients, "public_key" is also required.

                     For example
                     [
                        {
                            "fid": "https://domain.tld/receive/users/1234-5678-0123-4567",
                            "protocol": "diaspora",
                            "public": False,
                            "public_key": <RSAPublicKey object>,
                        },
                        {
                            "fid": "https://domain2.tld/receive/public",
                            "protocol": "diaspora",
                            "public": True,
                        },
                        {
                            "fid": "https://domain4.tld/sharedinbox/",
                            "protocol": "activitypub",
                            "public": True,
                        },
                        {
                            "fid": "https://domain4.tld/profiles/jill",
                            "protocol": "activitypub",
                            "public": False,
                        },
                     ]
    :arg parent_user: (Optional) User object of the parent object, if there is one. This must be given for the
                      Diaspora protocol if a parent object exists, so that a proper ``parent_author_signature`` can
                      be generated. If given, the payload will be sent as this user.
    """
    payloads = []
    public_payloads = {
        "activitypub": {
            "auth": None,
            "payload": None,
            "urls": set(),
        },
        "diaspora": {
            "auth": None,
            "payload": None,
            "urls": set(),
        },
    }

    # Flatten to unique recipients
    unique_recipients = unique_everseen(recipients)

    # Generate payloads and collect urls
    for recipient in unique_recipients:
        fid = recipient["fid"]
        public_key = recipient.get("public_key")
        protocol = recipient["protocol"]
        public = recipient["public"]

        if protocol == "activitypub":
            try:
                payload = handle_create_payload(entity, author_user, protocol, parent_user=parent_user)
                if public:
                    payload["to"] = "https://www.w3.org/ns/activitystreams#Public"
                else:
                    payload["to"] = fid
                payload = json.dumps(payload).encode("utf-8")
            except Exception as ex:
                logger.error("handle_send - failed to generate private payload for %s: %s", fid, ex)
                continue
            payloads.append({
                "auth": get_http_authentication(author_user.private_key, f"{author_user.id}#main-key"),
                "payload": payload,
                "content_type": 'application/ld+json; profile="https://www.w3.org/ns/activitystreams"',
                "urls": {fid},
            })
        elif protocol == "diaspora":
            if public:
                if public_key:
                    raise ValueError("handle_send - Diaspora recipient cannot be public and use encrypted delivery")
                if not public_payloads[protocol]["payload"]:
                    public_payloads[protocol]["payload"] = handle_create_payload(
                        entity, author_user, protocol, parent_user=parent_user,
                    )
                public_payloads["diaspora"]["urls"].add(fid)
            else:
                if not public_key:
                    raise ValueError("handle_send - Diaspora recipient cannot be private without a public key for "
                                     "encrypted delivery")
                # Private payload
                try:
                    payload = handle_create_payload(
                        entity, author_user, "diaspora", to_user_key=public_key, parent_user=parent_user,
                    )
                    payload = json.dumps(payload)
                except Exception as ex:
                    logger.error("handle_send - failed to generate private payload for %s: %s", fid, ex)
                    continue
                payloads.append({
                    "urls": {fid}, "payload": payload, "content_type": "application/json", "auth": None,
                })

    # Add public diaspora payload
    if public_payloads["diaspora"]["payload"]:
        payloads.append({
            "urls": public_payloads["diaspora"]["urls"], "payload": public_payloads["diaspora"]["payload"],
            "content_type": "application/magic-envelope+xml", "auth": None,
        })

    logger.debug("handle_send - %s", payloads)

    # Do actual sending
    for payload in payloads:
        for url in payload["urls"]:
            try:
                send_document(
                    url,
                    payload["payload"],
                    auth=payload["auth"],
                    headers={"Content-Type": payload["content_type"]},
                )
            except Exception as ex:
                logger.error("handle_send - failed to send payload to %s: %s, payload: %s", url, ex, payload["payload"])

Response: This function handles the send request for the given entity.


Instruction:
Create a Python 3 function to
get the key_id from the sig element which contains urlsafe_b64encoded Diaspora handle.

Response:
def get_sender(doc):
        """Get the key_id from the `sig` element which contains urlsafe_b64encoded Diaspora handle.

        :param doc: ElementTree document
        :returns: Diaspora handle
        """
        key_id = doc.find(".//{%s}sig" % NAMESPACE).get("key_id")
        return urlsafe_b64decode(key_id).decode("utf-8")


Instruction:
Given the following Python 3 function, write the documentation
def create_payload(self):
        doc = etree.fromstring(self.message)
        self.payload = etree.tostring(doc, encoding="utf-8")
        self.payload = urlsafe_b64encode(self.payload).decode("ascii")
        return self.payload

Response:
Create the payload doc.
            is the class name of the message.


Instruction:
Explain what the following Python 3 code does
def _build_signature(self):
        sig_contents = \
            self.payload + "." + \
            b64encode(b"application/xml").decode("ascii") + "." + \
            b64encode(b"base64url").decode("ascii") + "." + \
            b64encode(b"RSA-SHA256").decode("ascii")
        sig_hash = SHA256.new(sig_contents.encode("ascii"))
        cipher = PKCS1_v1_5.new(self.private_key)
        sig = urlsafe_b64encode(cipher.sign(sig_hash))
        key_id = urlsafe_b64encode(bytes(self.author_handle, encoding="utf-8"))
        return sig, key_id

Response: Create the signature using the private key.


Instruction:
Write a Python 3 script to
verify Magic Envelope document against public key.

Response:
def verify(self):
        """Verify Magic Envelope document against public key."""
        if not self.public_key:
            self.fetch_public_key()
        data = self.doc.find(".//{http://salmon-protocol.org/ns/magic-env}data").text
        sig = self.doc.find(".//{http://salmon-protocol.org/ns/magic-env}sig").text
        sig_contents = '.'.join([
            data,
            b64encode(b"application/xml").decode("ascii"),
            b64encode(b"base64url").decode("ascii"),
            b64encode(b"RSA-SHA256").decode("ascii")
        ])
        sig_hash = SHA256.new(sig_contents.encode("ascii"))
        cipher = PKCS1_v1_5.new(RSA.importKey(self.public_key))
        if not cipher.verify(sig_hash, urlsafe_b64decode(sig)):
            raise SignatureVerificationError("Signature cannot be verified using the given public key")


Instruction:
Write a Python 3 script for
extracting mentions from an entity with raw_content.

Response:
def extract_mentions(self):
        """
        Extract mentions from an entity with ``raw_content``.

        :return: set
        """
        if not hasattr(self, "raw_content"):
            return set()
        mentions = re.findall(r'@{[^;]+; [\w.-]+@[^}]+}', self.raw_content)
        if not mentions:
            return set()
        mentions = {s.split(';')[1].strip(' }') for s in mentions}
        mentions = {s for s in mentions}
        return mentions


Instruction:
Given the following Python 3 function, write the documentation
def fetch_country_by_ip(ip):
    iplookup = ipdata.ipdata()
    data = iplookup.lookup(ip)
    if data.get('status') != 200:
        return ''

    return data.get('response', {}).get('country_code', '')

Response: Fetch the country code by IP


Instruction:
Can you generate a brief explanation for the following Python 3 code
def fetch_host_ip(host: str) -> str:
    try:
        ip = socket.gethostbyname(host)
    except socket.gaierror:
        return ''

    return ip

Response: Fetch ip by host


Instruction:
Explain what the following Python 3 code does
def fetch_host_ip_and_country(host: str) -> Tuple:
    ip = fetch_host_ip(host)
    if not host:
        return '', ''

    country = fetch_country_by_ip(ip)

    return ip, country

Response: Fetch ip and country by host


Instruction:
Create a Python 3 function to
parse a date string as specified by HTTP RFC 7231 section 7. 1. 1.

Response:
def parse_http_date(date):
    """
    Parse a date format as specified by HTTP RFC7231 section 7.1.1.1.

    The three formats allowed by the RFC are accepted, even if only the first
    one is still in widespread use.

    Return an integer expressed in seconds since the epoch, in UTC.

    Implementation copied from Django.
    https://github.com/django/django/blob/master/django/utils/http.py#L157
    License: BSD 3-clause
    """
    MONTHS = 'jan feb mar apr may jun jul aug sep oct nov dec'.split()
    __D = r'(?P<day>\d{2})'
    __D2 = r'(?P<day>[ \d]\d)'
    __M = r'(?P<mon>\w{3})'
    __Y = r'(?P<year>\d{4})'
    __Y2 = r'(?P<year>\d{2})'
    __T = r'(?P<hour>\d{2}):(?P<min>\d{2}):(?P<sec>\d{2})'
    RFC1123_DATE = re.compile(r'^\w{3}, %s %s %s %s GMT$' % (__D, __M, __Y, __T))
    RFC850_DATE = re.compile(r'^\w{6,9}, %s-%s-%s %s GMT$' % (__D, __M, __Y2, __T))
    ASCTIME_DATE = re.compile(r'^\w{3} %s %s %s %s$' % (__M, __D2, __T, __Y))
    # email.utils.parsedate() does the job for RFC1123 dates; unfortunately
    # RFC7231 makes it mandatory to support RFC850 dates too. So we roll
    # our own RFC-compliant parsing.
    for regex in RFC1123_DATE, RFC850_DATE, ASCTIME_DATE:
        m = regex.match(date)
        if m is not None:
            break
    else:
        raise ValueError("%r is not in a valid HTTP date format" % date)
    try:
        year = int(m.group('year'))
        if year < 100:
            if year < 70:
                year += 2000
            else:
                year += 1900
        month = MONTHS.index(m.group('mon').lower()) + 1
        day = int(m.group('day'))
        hour = int(m.group('hour'))
        min = int(m.group('min'))
        sec = int(m.group('sec'))
        result = datetime.datetime(year, month, day, hour, min, sec)
        return calendar.timegm(result.utctimetuple())
    except Exception as exc:
        raise ValueError("%r is not a valid date" % date) from exc


Instruction:
Implement a Python 3 function for
getting HTTP signature authentication for a request.

Response:
def get_http_authentication(private_key: RsaKey, private_key_id: str) -> HTTPSignatureHeaderAuth:
    """
    Get HTTP signature authentication for a request.
    """
    key = private_key.exportKey()
    return HTTPSignatureHeaderAuth(
        headers=["(request-target)", "user-agent", "host", "date"],
        algorithm="rsa-sha256",
        key=key,
        key_id=private_key_id,
    )


Instruction:
Write a Python 3 script for
verifying the HTTP signature in a request.

Response:
def verify_request_signature(request: RequestType, public_key: Union[str, bytes]):
    """
    Verify HTTP signature in request against a public key.
    """
    key = encode_if_text(public_key)
    date_header = request.headers.get("Date")
    if not date_header:
        raise ValueError("Rquest Date header is missing")

    ts = parse_http_date(date_header)
    dt = datetime.datetime.utcfromtimestamp(ts).replace(tzinfo=pytz.utc)
    delta = datetime.timedelta(seconds=30)
    now = datetime.datetime.utcnow().replace(tzinfo=pytz.utc)
    if dt < now - delta or dt > now + delta:
        raise ValueError("Request Date is too far in future or past")

    HTTPSignatureHeaderAuth.verify(request, key_resolver=lambda **kwargs: key)


Instruction:
Can you generate the documentation for the following Python 3 function
def to_xml(self):
        element = etree.Element(self._tag_name)
        struct_to_xml(element, [
            {"text": self.raw_content},
            {"guid": self.guid},
            {"author": self.handle},
            {"public": "true" if self.public else "false"},
            {"created_at": format_dt(self.created_at)},
            {"provider_display_name": self.provider_display_name},
        ])
        return element

Response: Convert to XML message.


Instruction:
Write a Python 3 script to
convert to XML message.

Response:
def to_xml(self):
        """Convert to XML message."""
        element = etree.Element(self._tag_name)
        struct_to_xml(element, [
            {"author": self.handle},
            {"recipient": self.target_handle},
            {"following": "true" if self.following else "false"},
            {"sharing": "true" if self.following else "false"},
        ])
        return element


Instruction:
Can you create a Python 3 function that
converts to XML message.

Response:
def to_xml(self):
        """Convert to XML message."""
        element = etree.Element(self._tag_name)
        struct_to_xml(element, [
            {"author": self.handle},
            {"first_name": self.name},
            {"last_name": ""},  # We only have one field - splitting it would be artificial
            {"image_url": self.image_urls["large"]},
            {"image_url_small": self.image_urls["small"]},
            {"image_url_medium": self.image_urls["medium"]},
            {"gender": self.gender},
            {"bio": self.raw_content},
            {"location": self.location},
            {"searchable": "true" if self.public else "false"},
            {"nsfw": "true" if self.nsfw else "false"},
            {"tag_string": " ".join(["#%s" % tag for tag in self.tag_list])},
        ])
        return element


Instruction:
Make a summary of the following Python 3 code
def to_xml(self):
        element = etree.Element(self._tag_name)
        struct_to_xml(element, [
            {"author": self.handle},
            {"target_guid": self.target_guid},
            {"target_type": DiasporaRetraction.entity_type_to_remote(self.entity_type)},
        ])
        return element

Response: Convert to XML message.


Instruction:
Implement a Python 3 function for
converting entity type between our Entity names and Diaspora names.

Response:
def entity_type_to_remote(value):
        """Convert entity type between our Entity names and Diaspora names."""
        if value in DiasporaRetraction.mapped.values():
            values = list(DiasporaRetraction.mapped.values())
            index = values.index(value)
            return list(DiasporaRetraction.mapped.keys())[index]
        return value


Instruction:
Implement a function in Python 3 to
build a dict of attributes and their values ignoring any properties functions and anything that starts with an underscore.

Response:
def get_base_attributes(entity):
    """Build a dict of attributes of an entity.

    Returns attributes and their values, ignoring any properties, functions and anything that starts
    with an underscore.
    """
    attributes = {}
    cls = entity.__class__
    for attr, _ in inspect.getmembers(cls, lambda o: not isinstance(o, property) and not inspect.isroutine(o)):
        if not attr.startswith("_"):
            attributes[attr] = getattr(entity, attr)
    return attributes


Instruction:
Can you implement a function in Python 3 that
pads an input string to be a multiple of block_size bytes.

Response:
def pkcs7_pad(inp, block_size):
    """
    Using the PKCS#7 padding scheme, pad <inp> to be a multiple of
    <block_size> bytes. Ruby's AES encryption pads with this scheme, but
    pycrypto doesn't support it.

    Implementation copied from pyaspora:
    https://github.com/mjnovice/pyaspora/blob/master/pyaspora/diaspora/protocol.py#L209
    """
    val = block_size - len(inp) % block_size
    if val == 0:
        return inp + (bytes([block_size]) * block_size)
    else:
        return inp + (bytes([val]) * val)


Instruction:
Can you tell what is the following Python 3 function doing
def pkcs7_unpad(data):
    if isinstance(data, str):
        return data[0:-ord(data[-1])]
    else:
        return data[0:-data[-1]]

Response: Remove the padding bytes that were added at point of encryption.


Instruction:
Explain what the following Python 3 code does
def encrypt(payload, public_key):
        iv, key, encrypter = EncryptedPayload.get_iv_key_encrypter()
        aes_key_json = EncryptedPayload.get_aes_key_json(iv, key)
        cipher = PKCS1_v1_5.new(public_key)
        aes_key = b64encode(cipher.encrypt(aes_key_json))
        padded_payload = pkcs7_pad(payload.encode("utf-8"), AES.block_size)
        encrypted_me = b64encode(encrypter.encrypt(padded_payload))
        return {
            "aes_key": aes_key.decode("utf-8"),
            "encrypted_magic_envelope": encrypted_me.decode("utf8"),
        }

Response: Encrypt a payload using an encrypted JSON wrapper.


Instruction:
Can you create a Python 3 function that
returns the template in JSON form

Response:
def template(self):
        """Returns the template in JSON form"""
        if self._template:
            return self._template

        template_json = self.read_template(self.args.tmplname)

        self._template = loads(template_json)
        return self._template


Instruction:
Create a Python 3 function to
return the creation time of the specified LogRecord as formatted text.

Response:
def formatTime(self, record, datefmt=None):
        """Return the creation time of the specified LogRecord as formatted text.

        If ``datefmt`` (a string) is specified, it is used to format the creation time of the record.
        If ``datefmt`` is 'Z' then creation time of the record will be in Zulu Time Zone.
        Otherwise, the ISO8601 format is used.
        """
        ct = self.converter(record.created)
        if datefmt:
            if datefmt == 'Z':
                t = time.strftime("%Y-%m-%dT%H:%M:%S", ct)
                s = "{}.{:03.0f}Z".format(t, record.msecs)
            else:
                s = time.strftime(datefmt, ct)
        else:
            t = time.strftime(self.default_time_format, ct)
            s = self.default_msec_format % (t, record.msecs)

        return s


Instruction:
Write a Python 3 function for
renaming level names. :param mapping: Mapping level names to new ones :type mapping: dict

Response:
def override_level_names(self, mapping):
        """Rename level names.

        :param mapping: Mapping level names to new ones
        :type mapping: dict
        """
        if not isinstance(mapping, dict):
            return
        for key, val in mapping.items():
            if key in self._level_names:
                self._level_names[key] = val


Instruction:
Create a Python 3 function to
override default color of elements.

Response:
def override_colors(self, colors):
        """Override default color of elements.

        :param colors: New color value for given elements
        :type colors: dict
        """
        if not isinstance(colors, dict):
            return
        for key in self._color[True]:
            if key in colors:
                self._color[True][key] = colors[key]


Instruction:
Implement a Python 3 function for
preparing log record with given fields.

Response:
def __prepare_record(self, record, enabled_fields):
        """Prepare log record with given fields."""
        message = record.getMessage()
        if hasattr(record, 'prefix'):
            message = "{}{}".format((str(record.prefix) + ' ') if record.prefix else '', message)

        obj = {
            'name': record.name,
            'asctime': self.formatTime(record, self.datefmt),
            'created': record.created,
            'msecs': record.msecs,
            'relativeCreated': record.relativeCreated,
            'levelno': record.levelno,
            'levelname': self._level_names[record.levelname],
            'thread': record.thread,
            'threadName': record.threadName,
            'process': record.process,
            'pathname': record.pathname,
            'filename': record.filename,
            'module': record.module,
            'lineno': record.lineno,
            'funcName': record.funcName,
            'message': message,
            'exception': record.exc_info[0].__name__ if record.exc_info else None,
            'stacktrace': record.exc_text,
        }

        if not isinstance(enabled_fields, list):
            enabled_fields = [str(enabled_fields)]

        ef = {}
        for item in enabled_fields:
            if not isinstance(item, (str, tuple)):
                continue
            if not isinstance(item, tuple):
                ef[item] = item
            else:
                ef[item[0]] = item[1]

        result = {}
        for key, val in obj.items():
            if key in ef:
                result[ef[key]] = val

        return result


Instruction:
Can you tell what is the following Python 3 function doing
def __obj2json(self, obj):
        return json.dumps(obj, indent=self._indent, sort_keys=self._sort_keys)

Response: Serialize obj to a JSON formatted string.


Instruction:
Can you tell what is the following Python 3 function doing
def validate_host(cert, name):
    cn = None
    for t, v in cert.get_subject().get_components():
        if t == b'CN':
            cn = v
            break

    if cn == name:
        return True

    # checking SAN
    s_name = name.decode('ascii')
    for i in range(cert.get_extension_count()):
        ext = cert.get_extension(i)
        if ext.get_short_name() == b'subjectAltName':
            s = str(ext)
            # SANs are usually have form like: DNS:hostname
            if s.startswith('DNS:') and s[4:] == s_name:
                return True

    # TODO handle wildcards
    return False

Response:
Validates host name against certificate
    Returns True if host name matches certificate
    Returns False if host name matches certificate


Instruction:
Can you generate a brief explanation for the following Python 3 code
def revert_to_clear(tds_sock):
    enc_conn = tds_sock.conn.sock
    clear_conn = enc_conn._transport
    enc_conn.shutdown()
    tds_sock.conn.sock = clear_conn
    tds_sock._writer._transport = clear_conn
    tds_sock._reader._transport = clear_conn

Response:
Reverts connection back to non - encrypted mode
    Used when client sent ENCRYPT_OFF flag.


Instruction:
Can you tell what is the following Python 3 function doing
def tds7_crypt_pass(password):
    encoded = bytearray(ucs2_codec.encode(password)[0])
    for i, ch in enumerate(encoded):
        encoded[i] = ((ch << 4) & 0xff | (ch >> 4)) ^ 0xA5
    return encoded

Response: Mangle password according to tds rules


Instruction:
Explain what the following Python 3 code does
def unpack(self, struc):
        buf, offset = readall_fast(self, struc.size)
        return struc.unpack_from(buf, offset)

Response: Unpacks given structure from stream


Instruction:
How would you code a function in Python 3 to
read num_chars UCS2 string from the stream

Response:
def read_ucs2(self, num_chars):
        """ Reads num_chars UCS2 string from the stream """
        buf = readall(self, num_chars * 2)
        return ucs2_codec.decode(buf)[0]


Instruction:
Here you have a function in Python 3, explain what it does
def get_collation(self):
        buf = readall(self, Collation.wire_size)
        return Collation.unpack(buf)

Response: Reads a Collation object from the stream.


Instruction:
Explain what the following Python 3 code does
def _read_packet(self):
        try:
            pos = 0
            while pos < _header.size:
                received = self._transport.recv_into(self._bufview[pos:_header.size-pos])
                if received == 0:
                    raise tds_base.ClosedConnectionError()
                pos += received
        except tds_base.TimeoutError:
            self._session.put_cancel()
            raise
        self._pos = _header.size
        self._type, self._status, self._size, self._session._spid, _ = _header.unpack_from(self._bufview, 0)
        self._have = pos
        while pos < self._size:
            received = self._transport.recv_into(self._bufview[pos:], self._size - pos)
            if received == 0:
                raise tds_base.ClosedConnectionError()
            pos += received
            self._have += received

Response: Reads next TDS packet from the underlying transport.


Instruction:
Create a Python 3 function for
reading a single packet and returns the payload of the packet.

Response:
def read_whole_packet(self):
        """ Reads single packet and returns bytes payload of the packet

        Can only be called when transport's read pointer is at the beginning
        of the packet.
        """
        self._read_packet()
        return readall(self, self._size - _header.size)


Instruction:
Can you generate the documentation for the following Python 3 function
def write(self, data):
        data_off = 0
        while data_off < len(data):
            left = len(self._buf) - self._pos
            if left <= 0:
                self._write_packet(final=False)
            else:
                to_write = min(left, len(data) - data_off)
                self._buf[self._pos:self._pos + to_write] = data[data_off:data_off + to_write]
                self._pos += to_write
                data_off += to_write

Response: Writes given bytes buffer into the stream


Instruction:
Write a Python 3 script for
writing a string to the stream.

Response:
def write_string(self, s, codec):
        """ Write string encoding it with codec into stream """
        for i in range(0, len(s), self.bufsize):
            chunk = s[i:i + self.bufsize]
            buf, consumed = codec.encode(chunk)
            assert consumed == len(chunk)
            self.write(buf)


Instruction:
Can you generate the documentation for the following Python 3 function
def _write_packet(self, final):
        status = 1 if final else 0
        _header.pack_into(self._buf, 0, self._type, status, self._pos, 0, self._packet_no)
        self._packet_no = (self._packet_no + 1) % 256
        self._transport.sendall(self._buf[:self._pos])
        self._pos = 8

Response: Writes a single TDS packet into underlying transport.


Instruction:
Can you tell what is the following Python 3 function doing
def raise_db_exception(self):
        if not self.messages:
            raise tds_base.Error("Request failed, server didn't send error message")
        msg = None
        while True:
            msg = self.messages[-1]
            if msg['msgno'] == 3621:  # the statement has been terminated
                self.messages = self.messages[:-1]
            else:
                break

        error_msg = ' '.join(m['message'] for m in self.messages)
        ex = _create_exception_by_message(msg, error_msg)
        raise ex

Response: Raises exception from last server message


Instruction:
Can you generate the documentation for the following Python 3 function
def get_type_info(self, curcol):
        r = self._reader
        # User defined data type of the column
        if tds_base.IS_TDS72_PLUS(self):
            user_type = r.get_uint()
        else:
            user_type = r.get_usmallint()
        curcol.column_usertype = user_type
        curcol.flags = r.get_usmallint()  # Flags
        type_id = r.get_byte()
        serializer_class = self._tds.type_factory.get_type_serializer(type_id)
        curcol.serializer = serializer_class.from_stream(r)

Response: Reads TYPE_INFO structure from the reader and stores it in the curcol.


Instruction:
Can you write a function in Python 3 where it
reads and processes COLMETADATA stream and returns a list of COLINFO structs.

Response:
def tds7_process_result(self):
        """ Reads and processes COLMETADATA stream

        This stream contains a list of returned columns.
        Stream format link: http://msdn.microsoft.com/en-us/library/dd357363.aspx
        """
        self.log_response_message('got COLMETADATA')
        r = self._reader

        # read number of columns and allocate the columns structure

        num_cols = r.get_smallint()

        # This can be a DUMMY results token from a cursor fetch

        if num_cols == -1:
            return

        self.param_info = None
        self.has_status = False
        self.ret_status = None
        self.skipped_to_status = False
        self.rows_affected = tds_base.TDS_NO_COUNT
        self.more_rows = True
        self.row = [None] * num_cols
        self.res_info = info = _Results()

        #
        # loop through the columns populating COLINFO struct from
        # server response
        #
        header_tuple = []
        for col in range(num_cols):
            curcol = tds_base.Column()
            info.columns.append(curcol)
            self.get_type_info(curcol)

            curcol.column_name = r.read_ucs2(r.get_byte())
            precision = curcol.serializer.precision
            scale = curcol.serializer.scale
            size = curcol.serializer.size
            header_tuple.append(
                (curcol.column_name,
                 curcol.serializer.get_typeid(),
                 None,
                 size,
                 precision,
                 scale,
                 curcol.flags & tds_base.Column.fNullable))
        info.description = tuple(header_tuple)
        return info


Instruction:
How would you explain what the following Python 3 function does
def process_param(self):
        self.log_response_message('got RETURNVALUE message')
        r = self._reader
        if tds_base.IS_TDS72_PLUS(self):
            ordinal = r.get_usmallint()
        else:
            r.get_usmallint()  # ignore size
            ordinal = self._out_params_indexes[self.return_value_index]
        name = r.read_ucs2(r.get_byte())
        r.get_byte()  # 1 - OUTPUT of sp, 2 - result of udf
        param = tds_base.Column()
        param.column_name = name
        self.get_type_info(param)
        param.value = param.serializer.read(r)
        self.output_params[ordinal] = param
        self.return_value_index += 1

Response: Reads and processes the next parameter from the stream.