Instruction:
Write a Python 3 script for
returning a gradient of rgb values.

Response:
def gradient_rgb(
            self, text=None, fore=None, back=None, style=None,
            start=None, stop=None, step=1, linemode=True, movefactor=0):
        """ Return a black and white gradient.
            Arguments:
                text       : String to colorize.
                fore       : Foreground color, background will be gradient.
                back       : Background color, foreground will be gradient.
                style      : Name of style to use for the gradient.
                start      : Starting rgb value.
                stop       : Stopping rgb value.
                step       : Number of characters to colorize per color.
                             This allows a "wider" gradient.
                             This will always be greater than 0.
                linemode   : Colorize each line in the input.
                             Default: True
                movefactor : Amount to shift gradient for each line when
                             `linemode` is set.

       """
        gradargs = {
            'step': step,
            'fore': fore,
            'back': back,
            'style': style,
        }
        start = start or (0, 0, 0)
        stop = stop or (255, 255, 255)
        if linemode:
            method = self._gradient_rgb_lines
            gradargs['movefactor'] = movefactor
        else:
            method = self._gradient_rgb_line

        if text:
            return self.__class__(
                ''.join((
                    self.data or '',
                    method(
                        text,
                        start,
                        stop,
                        **gradargs
                    ),
                ))
            )

        # Operating on self.data.
        return self.__class__(
            method(
                self.stripped(),
                start,
                stop,
                **gradargs
            )
        )


Instruction:
How would you explain what the following Python 3 function does
def hex(self, value, text=None, back=None, style=None, rgb_mode=False):
        if rgb_mode:
            try:
                colrval = hex2rgb(value, allow_short=True)
            except ValueError:
                raise InvalidColr(value)
        else:
            try:
                colrval = hex2term(value, allow_short=True)
            except ValueError:
                raise InvalidColr(value)
        return self.chained(text=text, fore=colrval, back=back, style=style)

Response: A chained method that sets the fore color to an hex value.


Instruction:
Given the following Python 3 function, write the documentation
def join(self, *colrs, **colorkwargs):
        flat = []
        for clr in colrs:
            if isinstance(clr, (list, tuple, GeneratorType)):
                # Flatten any lists, at least once.
                flat.extend(str(c) for c in clr)
            else:
                flat.append(str(clr))

        if colorkwargs:
            fore = colorkwargs.get('fore', None)
            back = colorkwargs.get('back', None)
            style = colorkwargs.get('style', None)
            flat = (
                self.color(s, fore=fore, back=back, style=style)
                for s in flat
            )
        return self.__class__(self.data.join(flat))

Response: Like str. join except it returns a Colr.


Instruction:
Create a Python 3 function for
liking str. lstrip except it returns the Colr instance.

Response:
def lstrip(self, chars=None):
        """ Like str.lstrip, except it returns the Colr instance. """
        return self.__class__(
            self._str_strip('lstrip', chars),
            no_closing=chars and (closing_code in chars),
        )


Instruction:
Write a Python 3 script for
returning a new instance of the object with the rainbow gradient text.

Response:
def rainbow(
            self, text=None, fore=None, back=None, style=None,
            freq=0.1, offset=30, spread=3.0,
            linemode=True, movefactor=2, rgb_mode=False):
        """ Make rainbow gradient text.
            Arguments:
                text       : Text to make gradient.
                             Default: self.data
                fore       : Fore color to use (makes back the rainbow).
                             Default: None
                back       : Back color to use (makes fore the rainbow).
                             Default: None
                style      : Style for the rainbow.
                             Default: None
                freq       : Frequency of color change, a higher value means
                             more colors.
                             Best results when in the range 0.0-1.0.
                             Default: 0.1
                offset     : Offset for start of rainbow.
                             Default: 30
                spread     : Spread/width of each color.
                             Default: 3.0,
                linemode   : Colorize each line in the input.
                             Default: True
                movefactor : Factor for offset increase on each line when
                             using linemode.
                             Minimum value: 0
                             Default: 2
                rgb_mode   : Use RGB escape codes instead of extended 256 and
                             approximate hex matches.
        """
        if fore and back:
            raise ValueError('Cannot use both fore and back with rainbow()')

        rainbowargs = {
            'freq': freq,
            'spread': spread,
            'offset': offset,
            'fore': fore,
            'back': back,
            'style': style,
            'rgb_mode': rgb_mode,
        }
        if linemode:
            rainbowargs['movefactor'] = movefactor
            method = self._rainbow_lines
        else:
            method = self._rainbow_line

        if text:
            # Prepend existing self.data to the rainbow text.
            return self.__class__(
                ''.join((
                    self.data,
                    method(text, **rainbowargs)
                ))
            )

        # Operate on self.data.
        return self.__class__(
            method(self.stripped(), **rainbowargs)
        )


Instruction:
Can you tell what is the following Python 3 function doing
def rstrip(self, chars=None):
        return self.__class__(
            self._str_strip('rstrip', chars),
            no_closing=chars and (closing_code in chars),
        )

Response: Like str. rstrip except it returns the Colr instance.


Instruction:
How would you code a function in Python 3 to
like str. strip except it returns the Colr instance.

Response:
def strip(self, chars=None):
        """ Like str.strip, except it returns the Colr instance. """
        return self.__class__(
            self._str_strip('strip', chars),
            no_closing=chars and (closing_code in chars),
        )


Instruction:
Write a Python 3 script for
liking str except it returns a colorized Colr instance.

Response:
def as_colr(self, label_args=None, value_args=None):
        """ Like __str__, except it returns a colorized Colr instance. """
        label_args = label_args or {'fore': 'red'}
        value_args = value_args or {'fore': 'blue', 'style': 'bright'}
        return Colr(self.default_format.format(
            label=Colr(self.label, **label_args),
            value=Colr(repr(self.value), **value_args),
        ))


Instruction:
Implement a Python 3 function for
liking str except it returns a colorized Colr instance.

Response:
def as_colr(
            self, label_args=None, type_args=None, type_val_args=None,
            value_args=None):
        """ Like __str__, except it returns a colorized Colr instance. """
        label_args = label_args or {'fore': 'red'}
        type_args = type_args or {'fore': 'yellow'}
        type_val_args = type_val_args or {'fore': 'grey'}
        value_args = value_args or {'fore': 'blue', 'style': 'bright'}

        return Colr(self.default_format.format(
            label=Colr(':\n    ').join(
                Colr('Expecting color name/value', **label_args),
                ',\n    '.join(
                    '{lbl:<5} ({val})'.format(
                        lbl=Colr(l, **type_args),
                        val=Colr(v, **type_val_args),
                    )
                    for l, v in self.accepted_values
                )
            ),
            value=Colr(repr(self.value), **value_args)
        ))


Instruction:
Can you tell what is the following Python 3 function doing
def as_colr(
            self, label_args=None, type_args=None, type_val_args=None,
            value_args=None, spec_args=None):
        """ Like __str__, except it returns a colorized Colr instance. """
        label_args = label_args or {'fore': 'red'}
        type_args = type_args or {'fore': 'yellow'}
        type_val_args = type_val_args or {'fore': 'grey'}
        value_args = value_args or {'fore': 'blue', 'style': 'bright'}
        spec_args = spec_args or {'fore': 'blue'}
        spec_repr = repr(self.spec)
        spec_quote = spec_repr[0]
        val_repr = repr(self.value)
        val_quote = val_repr[0]
        return Colr(self.default_format.format(
            label=Colr(':\n    ').join(
                Colr('Bad format spec. color name/value', **label_args),
                ',\n    '.join(
                    '{lbl:<5} ({val})'.format(
                        lbl=Colr(l, **type_args),
                        val=Colr(v, **type_val_args),
                    )
                    for l, v in self.accepted_values
                )
            ),
            spec=Colr('=').join(
                Colr(v, **spec_args)
                for v in spec_repr[1:-1].split('=')
            ).join((spec_quote, spec_quote)),
            value=Colr(
                val_repr[1:-1],
                **value_args
            ).join((val_quote, val_quote)),
        ))

Response: Returns a string representation of the object as a Colr instance.


Instruction:
Given the following Python 3 function, write the documentation
def as_colr(
            self, label_args=None, type_args=None, value_args=None):
        """ Like __str__, except it returns a colorized Colr instance. """
        label_args = label_args or {'fore': 'red'}
        type_args = type_args or {'fore': 'yellow'}
        value_args = value_args or {'fore': 'blue', 'style': 'bright'}

        return Colr(self.default_format.format(
            label=Colr(':\n    ').join(
                Colr('Expecting style value', **label_args),
                Colr(',\n    ').join(
                    Colr(', ').join(
                        Colr(v, **type_args)
                        for v in t[1]
                    )
                    for t in _stylemap
                )
            ),
            value=Colr(repr(self.value), **value_args)
        ))

Response: Like str except it returns a colorized Colr instance.


Instruction:
How would you code a function in Python 3 to
ensure a file object is a tty.

Response:
def ensure_tty(file=sys.stdout):
    """ Ensure a file object is a tty. It must have an `isatty` method that
        returns True.
        TypeError is raised if the method doesn't exist, or returns False.
    """
    isatty = getattr(file, 'isatty', None)
    if isatty is None:
        raise TypeError(
            'Cannot detect tty, file has no `isatty` method: {}'.format(
                getattr(file, 'name', type(file).__name__)
            )
        )
    if not isatty():
        raise TypeError(
            'This will not work, file object is not a tty: {}'.format(
                getattr(file, 'name', type(file).__name__)
            )
        )
    return True


Instruction:
Can you tell what is the following Python 3 function doing
def erase_display(method=EraseMethod.ALL_MOVE, file=sys.stdout):
    erase.display(method).write(file=file)

Response: Erases the screen or part of the screen and then moves the screen to the home position.


Instruction:
Explain what the following Python 3 code does
def erase_line(method=EraseMethod.ALL, file=sys.stdout):
    erase.line(method).write(file=file)

Response: Erase a line or part of a language file.


Instruction:
Here you have a function in Python 3, explain what it does
def move_back(columns=1, file=sys.stdout):
    move.back(columns).write(file=file)

Response: Moves the cursor back by the specified number of columns.


Instruction:
Can you generate the documentation for the following Python 3 function
def move_column(column=1, file=sys.stdout):
    move.column(column).write(file=file)

Response: Move the cursor to the specified column.


Instruction:
Write a Python 3 function for
moving the cursor down a number of lines without changing columns.

Response:
def move_down(lines=1, file=sys.stdout):
    """ Move the cursor down a number of lines.

        Esc[<lines>B:
        Moves the cursor down by the specified number of lines without
        changing columns. If the cursor is already on the bottom line,
        ANSI.SYS ignores this sequence.
    """
    move.down(lines).write(file=file)


Instruction:
Make a summary of the following Python 3 code
def move_forward(columns=1, file=sys.stdout):
    move.forward(columns).write(file=file)

Response: Moves the cursor forward by columns.


Instruction:
How would you code a function in Python 3 to
move the cursor to the next line in the sequence.

Response:
def move_next(lines=1, file=sys.stdout):
    """ Move the cursor to the beginning of the line, a number of lines down.
        Default: 1

        Esc[<lines>E
    """
    move.next(lines).write(file=file)


Instruction:
Create a Python 3 function for
moving the cursor to a new position.

Response:
def move_pos(line=1, column=1, file=sys.stdout):
    """ Move the cursor to a new position. Values are 1-based, and default
        to 1.

        Esc[<line>;<column>H
        or
        Esc[<line>;<column>f
    """
    move.pos(line=line, col=column).write(file=file)


Instruction:
How would you code a function in Python 3 to
move the cursor to the beginning of the line.

Response:
def move_prev(lines=1, file=sys.stdout):
    """ Move the cursor to the beginning of the line, a number of lines up.
        Default: 1

        Esc[<lines>F
    """
    move.prev(lines).write(file=file)


Instruction:
Write a Python 3 script for
moving the cursor up a number of lines without changing columns.

Response:
def move_up(lines=1, file=sys.stdout):
    """ Move the cursor up a number of lines.

        Esc[ValueA:
        Moves the cursor up by the specified number of lines without changing
        columns. If the cursor is already on the top line, ANSI.SYS ignores
        this sequence.
    """
    move.up(lines).write(file=file)


Instruction:
How would you code a function in Python 3 to
print some text in a single line in a single line.

Response:
def print_inplace(*args, **kwargs):
    """ Save cursor position, write some text, and then restore the position.
        Arguments:
            Same as `print()`.

        Keyword Arguments:
            Same as `print()`, except `end` defaults to '' (empty str),
            and these:
                delay : Time in seconds between character writes.
    """
    kwargs.setdefault('file', sys.stdout)
    kwargs.setdefault('end', '')
    pos_save(file=kwargs['file'])
    delay = None
    with suppress(KeyError):
        delay = kwargs.pop('delay')
    if delay is None:
        print(*args, **kwargs)
    else:
        for c in kwargs.get('sep', ' ').join(str(a) for a in args):
            kwargs['file'].write(c)
            kwargs['file'].flush()
            sleep(delay)
        if kwargs['end']:
            kwargs['file'].write(kwargs['end'])
    pos_restore(file=kwargs['file'])
    # Must flush to see changes.
    kwargs['file'].flush()


Instruction:
Can you tell what is the following Python 3 function doing
def print_flush(*args, **kwargs):
    kwargs.setdefault('file', sys.stdout)
    print(*args, **kwargs)
    kwargs['file'].flush()

Response: Like print except the file is. flushed afterwards.


Instruction:
Here you have a function in Python 3, explain what it does
def print_overwrite(*args, **kwargs):
    kwargs.setdefault('file', sys.stdout)
    kwargs.setdefault('end', '')
    delay = None
    with suppress(KeyError):
        delay = kwargs.pop('delay')
    erase_line()
    # Move to the beginning of the line.
    move_column(1, file=kwargs['file'])
    if delay is None:
        print(*args, **kwargs)
    else:
        for c in kwargs.get('sep', ' ').join(str(a) for a in args):
            kwargs['file'].write(c)
            kwargs['file'].flush()
            sleep(delay)
        if kwargs['end']:
            kwargs['file'].write(kwargs['end'])
    kwargs['file'].flush()

Response: Print some text to the current line and overwrite the current line.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def scroll_down(lines=1, file=sys.stdout):
    scroll.down(lines).write(file=file)

Response: Scroll the whole page down a number of lines


Instruction:
Write a Python 3 script for
scrolling the whole page up a number of lines

Response:
def scroll_up(lines=1, file=sys.stdout):
    """ Scroll the whole page up a number of lines, new lines are added to
        the bottom.

        Esc[<lines>S
    """
    scroll.up(lines).write(file=file)


Instruction:
Implement a function in Python 3 to
erase the screen or part of the screen.

Response:
def erase_display(self, method=EraseMethod.ALL_MOVE):
        """ Clear the screen or part of the screen.
            Arguments:
                method: One of these possible values:
                            EraseMethod.END or 0:
                                Clear from cursor to the end of the screen.
                            EraseMethod.START or 1:
                                Clear from cursor to the start of the screen.
                            EraseMethod.ALL_MOVE or 2:
                                Clear all, and move home.
                            EraseMethod.ALL_ERASE or 3:
                                Clear all, and erase scrollback buffer.
                            EraseMethod.ALL_MOVE_ERASE or 4:
                                Like doing 2 and 3 in succession.
                                This is a feature of Colr. It is not standard.
                        Default: EraseMethod.ALL_MOVE (2)
        """
        return self.chained(erase.display(method))


Instruction:
Write a Python 3 script to
erase a line or part of a line.

Response:
def erase_line(self, method=EraseMethod.ALL):
        """ Erase a line, or part of a line.
            Arguments:
                method : One of these possible values:
                            EraseMethod.END or 0:
                                Clear from cursor to the end of the line.
                            EraseMethod.START or 1:
                                Clear from cursor to the start of the line.
                            EraseMethod.ALL or 2:
                                Clear the entire line.
                         Default: EraseMethod.ALL (2)
        """
        return self.chained(erase.line(method=method))


Instruction:
Write a Python 3 script for
returning the last escape code in self. data.

Response:
def last_code(self):
        """ Return the last escape code in `self.data`.
            If no escape codes are found, '' is returned.
        """
        codes = self.data.split(escape_sequence)
        if not codes:
            return ''
        return ''.join((escape_sequence, codes[-1]))


Instruction:
Can you implement a function in Python 3 that
moves the cursor to a new position.

Response:
def move_pos(self, line=1, column=1):
        """ Move the cursor to a new position.
            Default: line 1, column 1
        """
        return self.chained(move.pos(line=line, column=column))


Instruction:
How would you explain what the following Python 3 function does
def repeat(self, count=2):
        # Subtracting one from the count means the code mentioned is
        # truly repeated exactly `count` times.
        # Control().move_up().repeat(3) ==
        # Control().move_up().move_up().move_up()
        try:
            return self.__class__(''.join((
                str(self),
                self.last_code() * (count - 1),
            )))
        except TypeError as ex:
            raise TypeError(
                '`count` must be an integer. Got: {!r}'.format(count)
            ) from ex

Response: Repeat the last 3 control codes a number of times. Returns a new Control with this one s data and the repeated code.


Instruction:
Create a Python 3 function for
repeating this entire Control code a number of times.

Response:
def repeat_all(self, count=2):
        """ Repeat this entire Control code a number of times.
            Returns a new Control with this one's data repeated.
        """
        try:
            return self.__class__(''.join(str(self) * count))
        except TypeError:
            raise TypeError(
                '`count` must be an integer. Got: {!r}'.format(count)
            )


Instruction:
Create a Python 3 function for
returning a tuple of r g b from a hex color.

Response:
def hex2rgb(hexval: str, allow_short: bool = False) -> RGB:
    """ Return a tuple of (R, G, B) from a hex color. """
    if not hexval:
        raise ValueError(
            'Expecting hex string (#RGB, #RRGGBB), got nothing: {!r}'.format(
                hexval
            )
        )
    try:
        hexval = hexval.strip().lstrip('#')
    except AttributeError:
        raise ValueError(
            'Expecting hex string (#RGB, #RRGGBB), got: ({}) {!r}'.format(
                type(hexval).__name__,
                hexval
            )
        )
    if allow_short:
        hexval = fix_hex(hexval)
    if not len(hexval) == 6:
        raise ValueError(
            'Not a length 3 or 6 hex string (#RGB, #RRGGBB), got: {}'.format(
                hexval
            )
        )
    try:
        val = tuple(
            int(''.join(hexval[i:i + 2]), 16)
            for i in range(0, len(hexval), 2)
        )
    except ValueError:
        # Bad hex string.
        raise ValueError('Invalid hex value: {}'.format(hexval))
    # Only needed to satisft typing. `return val` would work fine.
    r, g, b = val
    return r, g, b


Instruction:
Create a Python 3 function to
convert a hex value into a nearest terminal code number.

Response:
def hex2term(hexval: str, allow_short: bool = False) -> str:
    """ Convert a hex value into the nearest terminal code number. """
    return rgb2term(*hex2rgb(hexval, allow_short=allow_short))


Instruction:
How would you explain what the following Python 3 function does
def hex2termhex(hexval: str, allow_short: bool = False) -> str:
    return rgb2termhex(*hex2rgb(hexval, allow_short=allow_short))

Response: Convert a hex value into a nearest terminal color matched hex.


Instruction:
How would you code a function in Python 3 to
print all 256 xterm color codes.

Response:
def print_all() -> None:
    """ Print all 256 xterm color codes. """
    for code in sorted(term2hex_map):
        print(' '.join((
            '\033[48;5;{code}m{code:<3}:{hexval:<6}\033[0m',
            '\033[38;5;{code}m{code:<3}:{hexval:<6}\033[0m'
        )).format(code=code, hexval=term2hex_map[code]))


Instruction:
Make a summary of the following Python 3 code
def rgb2hex(r: int, g: int, b: int) -> str:
    return '{:02x}{:02x}{:02x}'.format(r, g, b)

Response: Convert rgb values to hex code.


Instruction:
How would you explain what the following Python 3 function does
def rgb2term(r: int, g: int, b: int) -> str:
    return hex2term_map[rgb2termhex(r, g, b)]

Response: Convert an rgb value to a terminal code.


Instruction:
Make a summary of the following Python 3 code
def rgb2termhex(r: int, g: int, b: int) -> str:
    incs = [0x00, 0x5f, 0x87, 0xaf, 0xd7, 0xff]

    res = []
    parts = r, g, b
    for part in parts:
        if (part < 0) or (part > 255):
            raise ValueError(
                'Expecting 0-255 for RGB code, got: {!r}'.format(parts)
            )
        i = 0
        while i < len(incs) - 1:
            s, b = incs[i], incs[i + 1]  # smaller, bigger
            if s <= part <= b:
                s1 = abs(s - part)
                b1 = abs(b - part)
                if s1 < b1:
                    closest = s
                else:
                    closest = b
                res.append(closest)
                break
            i += 1

    # Convert back into nearest hex value.
    return rgb2hex(*res)

Response: Convert an rgb value to the nearest hex value that matches a term code.


Instruction:
Explain what the following Python 3 code does
def term2hex(code: Numeric, default: Optional[str] = None) -> str:
    try:
        val = term2hex_map.get('{:02}'.format(int(code), default))
    except ValueError:
        raise ValueError(
            'Expecting an int or number string, got: {} ({})'.format(
                code,
                getattr(code, '__name__', type(code).__name__)))
    return val

Response: Convert a term code to a hex string.


Instruction:
How would you code a function in Python 3 to
initialize from an int terminal code.

Response:
def _init_code(self, code: int) -> None:
        """ Initialize from an int terminal code. """
        if -1 < code < 256:
            self.code = '{:02}'.format(code)
            self.hexval = term2hex(code)
            self.rgb = hex2rgb(self.hexval)
        else:
            raise ValueError(' '.join((
                'Code must be in the range 0-255, inclusive.',
                'Got: {} ({})'
            )).format(code, getattr(code, '__name__', type(code).__name__)))


Instruction:
Explain what the following Python 3 code does
def _init_hex(self, hexval: str) -> None:
        self.hexval = hex2termhex(fix_hex(hexval))
        self.code = hex2term(self.hexval)
        self.rgb = hex2rgb(self.hexval)

Response: Initialize from a hex value string.


Instruction:
Write a Python 3 function for
initializing from red green blue args.

Response:
def _init_rgb(self, r: int, g: int, b: int) -> None:
        """ Initialize from red, green, blue args. """
        if self.rgb_mode:
            self.rgb = (r, g, b)
            self.hexval = rgb2hex(r, g, b)
        else:
            self.rgb = hex2rgb(rgb2termhex(r, g, b))
            self.hexval = rgb2termhex(r, g, b)

        self.code = hex2term(self.hexval)


Instruction:
How would you explain what the following Python 3 function does
def from_code(cls, code: int) -> 'ColorCode':
        c = cls()
        c._init_code(code)
        return c

Response: Return a ColorCode from a terminal code.


Instruction:
Can you write a function in Python 3 where it
returns a ColorCode from a hex string.

Response:
def from_hex(cls, hexval: str) -> 'ColorCode':
        """ Return a ColorCode from a hex string. """
        c = cls()
        c._init_hex(hexval)
        return c


Instruction:
Implement a Python 3 function for
creating a ColorCode from a RGB tuple.

Response:
def from_rgb(cls, r: int, g: int, b: int) -> 'ColorCode':
        """ Return a ColorCode from a RGB tuple. """
        c = cls()
        c._init_rgb(r, g, b)
        return c


Instruction:
Explain what the following Python 3 code does
def commit(func):
    '''Used as a decorator for automatically making session commits'''
    def wrap(**kwarg):
        with session_withcommit() as session:
            a = func(**kwarg)
            session.add(a)
        return session.query(songs).order_by(
            songs.song_id.desc()).first().song_id
    return wrap

Response: Used as a decorator for automatically making session commits


Instruction:
Can you tell what is the following Python 3 function doing
def get_songs()->Iterator:
    with session_withcommit() as session:
        val = session.query(songs).all()
        for row in val:
            yield row

Response: Return an iterator over the songs that have the fingerprinted flag set TRUE ( 1 ).


Instruction:
Can you write a function in Python 3 where it
returns the instance of the hub.

Response:
def get_hub():
    """Return the instance of the hub."""
    try:
        hub = _local.hub
    except AttributeError:
        # The Hub can only be instantiated from the root fiber. No other fibers
        # can run until the Hub is there, so the root will always be the first
        # one to call get_hub().
        assert fibers.current().parent is None
        hub = _local.hub = Hub()
    return hub


Instruction:
Implement a function in Python 3 to
sleep for *secs* seconds.

Response:
def sleep(secs):
    """Sleep for *secs* seconds. The *secs* argument can be an int or a float."""
    hub = get_hub()
    try:
        with switch_back(secs, hub):
            hub.switch()
    except Timeout:
        pass


Instruction:
Can you generate the documentation for the following Python 3 function
def switch(self, value=None):
        if self._hub is None or not self._fiber.is_alive():
            return
        self._hub.run_callback(self._fiber.switch, value)
        self._hub = self._fiber = None

Response: Switch to the origin fiber.


Instruction:
Write a Python 3 script for
throwing an exception into the origin fiber. The exception is thrown the next time the event loop runs.

Response:
def throw(self, typ, val=None, tb=None):
        """Throw an exception into the origin fiber. The exception is thrown
        the next time the event loop runs."""
        # The might seem redundant with self._fiber.cancel(exc), but it isn't
        # as self._fiber might be a "raw" fibers.Fiber() that doesn't have a
        # cancel() method.
        if self._hub is None or not self._fiber.is_alive():
            return
        self._hub.run_callback(self._fiber.throw, typ, val, tb)
        self._hub = self._fiber = None


Instruction:
Can you generate the documentation for the following Python 3 function
def close(self):
        if self._loop is None:
            return
        if fibers.current().parent is not None:
            raise RuntimeError('close() may only be called in the root fiber')
        elif compat.get_thread_ident() != self._thread:
            raise RuntimeError('cannot close() from a different thread')
        self._closing = True
        self._interrupt_loop()
        # Note how we are switching to the Hub without a switchback condition
        # being in place. This works because the hub is our child and upon
        # a child fiber exit its parent is switched in.
        self.switch()

Response: Close the hub and wait for it to be closed.


Instruction:
Can you create a Python 3 function that
switches the current fiber to the hub.

Response:
def switch(self):
        """Switch to the hub.

        This method pauses the current fiber and runs the event loop. The
        caller should ensure that it has set up appropriate callbacks so that
        it will get scheduled again, preferably using :class:`switch_back`. In
        this case then return value of this method will be an ``(args,
        kwargs)`` tuple containing the arguments passed to the switch back
        instance.

        If this method is called from the root fiber then there are two
        additional cases. If the hub exited due to a call to :meth:`close`,
        then this method returns None. And if the hub exited due to a
        exception, that exception is re-raised here.
        """
        if self._loop is None or not self.is_alive():
            raise RuntimeError('hub is closed/dead')
        elif fibers.current() is self:
            raise RuntimeError('cannot switch to myself')
        elif compat.get_thread_ident() != self._thread:
            raise RuntimeError('cannot switch from a different thread')
        value = super(Hub, self).switch()
        # A fiber exit will cause its parent to be switched to. All fibers in
        # the system should be children of the Hub, *except* the Hub itself
        # which is a child of the root fiber. So do an explicit check here to
        # see if the Hub exited unexpectedly, and if so raise an error.
        if fibers.current().parent is None and not self.is_alive() \
                    and self._loop is not None:
            raise RuntimeError('hub exited unexpectedly')
        return value


Instruction:
Create a Python 3 function to
queue a callback. The *callback* will be called with positional arguments *args* in the next iteration of the event loop. If you add multiple callbacks, they will be called in the order that you added them. The callback will run in the Hub's fiber. This method is thread-safe: it is allowed to queue a callback from a different thread than the one running the Hub.

Response:
def run_callback(self, callback, *args):
        """Queue a callback.

        The *callback* will be called with positional arguments *args* in the
        next iteration of the event loop. If you add multiple callbacks, they
        will be called in the order that you added them. The callback will run
        in the Hub's fiber.

        This method is thread-safe: it is allowed to queue a callback from a
        different thread than the one running the Hub.
        """
        if self._loop is None:
            raise RuntimeError('hub is closed')
        elif not callable(callback):
            raise TypeError('"callback": expecting a callable')
        self._callbacks.append((callback, args))  # thread-safe
        self._interrupt_loop()


Instruction:
Write a Python 3 script to
return a string describing a message for debugging purposes.

Response:
def message_info(message):
    """Return a string describing a message, for debugging purposes."""
    method = message.get('method')
    msgid = message.get('id')
    error = message.get('error')
    if method and msgid is not None:
        return 'method call "{}", id = "{}"'.format(method, msgid)
    elif method:
        return 'notification "{}"'.format(method)
    elif error is not None and msgid is not None:
        return 'error reply to id = "{}"'.format(msgid)
    elif error is not None:
        code = error.get('code', '(none)')
        return 'error reply: {}'.format(errorcode.get(code, code))
    else:
        return 'method return for id = "{}"'.format(msgid)


Instruction:
Can you create a Python 3 function that
returns a unique message ID.

Response:
def next_id(self):
        """Return a unique message ID."""
        msgid = self._id_template.format(self._next_id)
        self._next_id += 1
        return msgid


Instruction:
Create a Python 3 function to
return a new instance for version.

Response:
def create(version):
        """Return a new instance for *version*, which can be either `'1.0'`
        or `'2.0'`."""
        clsname = 'JsonRpcV{}'.format(version.rstrip('.0'))
        cls = globals()[clsname]
        return cls(version)


Instruction:
Here you have a function in Python 3, explain what it does
def send_message(self, message):
        if self._error:
            raise compat.saved_exc(self._error)
        elif self._transport is None:
            raise JsonRpcError('not connected')
        self._version.check_message(message)
        self._writer.write(serialize(message))

Response: Send a raw JSON - RPC message.


Instruction:
Can you generate the documentation for the following Python 3 function
def call_method(self, method, *args):
        message = self._version.create_request(method, args)
        msgid = message['id']
        try:
            with switch_back(self._timeout) as switcher:
                self._method_calls[msgid] = switcher
                self.send_message(message)
                args, _ = self._hub.switch()
        finally:
            self._method_calls.pop(msgid, None)
        response = args[0]
        assert response['id'] == msgid
        error = response.get('error')
        if error is not None:
            raise JsonRpcError('error response calling "{}"'.format(method), error)
        return response['result']

Response: Call a JSON - RPC method and wait for its result.


Instruction:
Implement a Python 3 function for
sending a JSON - RPC notification.

Response:
def send_notification(self, method, *args):
        """Send a JSON-RPC notification.

        The notification *method* is sent with positional arguments *args*.
        """
        message = self._version.create_request(method, args, notification=True)
        self.send_message(message)


Instruction:
How would you explain what the following Python 3 function does
def send_response(self, request, result=None, error=None):
        message = self._version.create_response(request, result, error)
        self.send_message(message)

Response: Respond to a JSON - RPC method call.


Instruction:
How would you implement a function in Python 3 that
returns the DBus signature for the supplied Python object.

Response:
def sigFromPy( pobj ):
    """
    Returns the DBus signature type for the argument. If the argument is an
    instance of one of the type wrapper classes, the exact type signature
    corresponding to the wrapper class will be used. If the object has a
    variable named 'dbusSignature', the value of that variable will be
    used. Otherwise, a generic type will be used (i.e "i" for a Python int)

    @rtype: C{string}
    @returns: The DBus signature for the supplied Python object
    """
    sig = getattr(pobj, 'dbusSignature', None)

    if sig is not None:
        return sig

    elif isinstance(pobj,        int): return 'i'
    elif isinstance(pobj, six.integer_types): return 'x'
    elif isinstance(pobj,      float): return 'd'
    elif isinstance(pobj, six.string_types): return 's'

    elif isinstance(pobj,       list):
        vtype = type(pobj[0])
        same = True
        for v in pobj[1:]:
            if not vtype is type(v):
                same = False
        if same:
            return 'a' + sigFromPy(pobj[0])
        else:
            return 'av'

    elif isinstance(pobj,       dict):
        same = True
        vtype = None
        for k,v in six.iteritems(pobj):
            if vtype is None:
                vtype = type(v)
            elif not vtype is type(v):
                same = False
        if same:
            return 'a{' + sigFromPy(k) + sigFromPy(v) + '}'
        else:
            return 'a{' + sigFromPy(k) + 'v}'

    else:
        raise MarshallingError('Invalid Python type for variant: ' + repr(pobj))


Instruction:
Given the following Python 3 function, write the documentation
def marshal( compoundSignature, variableList, startByte = 0, lendian=True ):
    chunks = list()
    bstart = startByte

    if hasattr(variableList, 'dbusOrder'):
        order = getattr(variableList, 'dbusOrder')
        variableList = [ getattr(variableList, attr_name) for attr_name in order ]

    for ct, var in zip(genCompleteTypes( compoundSignature ), variableList):
        tcode   = ct[0]
        padding = pad[tcode]( startByte )

        if padding:
            startByte += len(padding)
            chunks.append( padding )

        nbytes, vchunks = marshallers[ tcode ]( ct, var, startByte, lendian )

        startByte += nbytes

        chunks.extend( vchunks )

    return startByte - bstart, chunks

Response: This function encodes the Python objects in variableList into the DBus wire - format and returns a list of binary strings.


Instruction:
Given the following Python 3 function, write the documentation
def spawn(func, *args, **kwargs):
    fiber = Fiber(func, args, **kwargs)
    fiber.start()
    return fiber

Response: Spawn a new fiber.


Instruction:
Here you have a function in Python 3, explain what it does
def start(self):
        target = getattr(self._target, '__qualname__', self._target.__name__)
        self._log.debug('starting fiber {}, target {}', self.name, target)
        self._hub.run_callback(self.switch)

Response:
Schedule the fiber to be started in the next iteration of the
        event loop.


Instruction:
Implement a function in Python 3 to
schedule the fiber to be cancelled in the next iteration of the fiber event loop.

Response:
def cancel(self, message=None):
        """Schedule the fiber to be cancelled in the next iteration of the
        event loop.

        Cancellation works by throwing a :class:`~gruvi.Cancelled` exception
        into the fiber. If *message* is provided, it will be set as the value
        of the exception.
        """
        if not self.is_alive():
            return
        if message is None:
            message = 'cancelled by Fiber.cancel()'
        self._hub.run_callback(self.throw, Cancelled, Cancelled(message))


Instruction:
Given the following Python 3 function, write the documentation
def align_matches(self, matches: list)->Optional[dict]:
        # align by diffs
        diff_counter: dict = {}
        largest = 0
        largest_count = 0
        song_id = -1
        for sid, diff in matches:

            if diff not in diff_counter:
                diff_counter[diff] = {}
            if sid not in diff_counter[diff]:
                diff_counter[diff][sid] = 0
            diff_counter[diff][sid] += 1

            if diff_counter[diff][sid] > largest_count:
                largest = diff
                largest_count = diff_counter[diff][sid]
                song_id = sid

        # extract idenfication
        song = database.get_song_by_id(song_id)
        if song:
            songname = song.song_name
        else:
            return None

        # return match info
        nseconds = round(
            float(largest) / fingerprint.DEFAULT_FS *
            fingerprint.DEFAULT_WINDOW_SIZE * fingerprint.DEFAULT_OVERLAP_RATIO,
            5
        )
        song = {
            'song_id': song_id,
            'song_name': songname,
            MetaMusic.CONFIDENCE: largest_count,
            MetaMusic.OFFSET: int(largest),
            'offset_seconds': nseconds,
            'file_sha1': binascii.hexlify(song.file_sha1).decode('utf-8'),
        }
        return song

Response: Aligns matches in time with other matches and returns a dictionary with match information.


Instruction:
How would you code a function in Python 3 to
return a string representation of an IP address tuple or a socket address.

Response:
def saddr(address):
    """Return a string representation for an address.

    The *address* paramater can be a pipe name, an IP address tuple, or a
    socket address.

    The return value is always a ``str`` instance.
    """
    if isinstance(address, six.string_types):
        return address
    elif isinstance(address, tuple) and len(address) >= 2 and ':' in address[0]:
        return '[{}]:{}'.format(address[0], address[1])
    elif isinstance(address, tuple) and len(address) >= 2:
        return '{}:{}'.format(*address)
    else:
        raise TypeError('illegal address type: {!s}'.format(type(address)))


Instruction:
Can you generate the documentation for the following Python 3 function
def paddr(address):
    if not isinstance(address, six.string_types):
        raise TypeError('expecting a string')
    if address.startswith('['):
        p1 = address.find(']:')
        if p1 == -1:
            raise ValueError
        return (address[1:p1], int(address[p1+2:]))
    elif ':' in address:
        p1 = address.find(':')
        return (address[:p1], int(address[p1+1:]))
    else:
        return address

Response: Parse a string representation of an address.


Instruction:
How would you implement a function in Python 3 that
resolves an Internet node name and service into a socket address.

Response:
def getaddrinfo(node, service=0, family=0, socktype=0, protocol=0, flags=0, timeout=30):
    """Resolve an Internet *node* name and *service* into a socket address.

    The *family*, *socktype* and *protocol* are optional arguments that specify
    the address family, socket type and protocol, respectively. The *flags*
    argument allows you to pass flags to further modify the resolution process.
    See the :func:`socket.getaddrinfo` function for a detailed description of
    these arguments.

    The return value is a list of ``(family, socktype, proto, canonname,
    sockaddr)`` tuples. The fifth element (``sockaddr``) is the socket address.
    It will be a 2-tuple ``(addr, port)`` for an IPv4 address, and a 4-tuple
    ``(addr, port, flowinfo, scopeid)`` for an IPv6 address.

    The address resolution is performed in the libuv thread pool.
    """
    hub = get_hub()
    with switch_back(timeout) as switcher:
        request = pyuv.dns.getaddrinfo(hub.loop, node, service, family,
                                       socktype, protocol, flags, callback=switcher)
        switcher.add_cleanup(request.cancel)
        result = hub.switch()
    result, error = result[0]
    if error:
        message = pyuv.errno.strerror(error)
        raise pyuv.error.UVError(error, message)
    return result


Instruction:
Make a summary of the following Python 3 code
def getnameinfo(sockaddr, flags=0, timeout=30):
    hub = get_hub()
    with switch_back(timeout) as switcher:
        request = pyuv.dns.getnameinfo(hub.loop, sockaddr, flags, callback=switcher)
        switcher.add_cleanup(request.cancel)
        result = hub.switch()
    result, error = result[0]
    if error:
        message = pyuv.errno.strerror(error)
        raise pyuv.error.UVError(error, message)
    return result

Response: Resolve a socket address sockaddr back to a node service tuple.


Instruction:
Explain what the following Python 3 code does
def get_codes(s: Union[str, 'ChainedBase']) -> List[str]:
    return codegrabpat.findall(str(s))

Response: Grab all escape codes from a string.


Instruction:
Can you tell what is the following Python 3 function doing
def get_code_indices(s: Union[str, 'ChainedBase']) -> Dict[int, str]:
    indices = {}
    i = 0
    codes = get_codes(s)
    for code in codes:
        codeindex = s.index(code)
        realindex = i + codeindex
        indices[realindex] = code
        codelen = len(code)
        i = realindex + codelen
        s = s[codeindex + codelen:]
    return indices

Response: Retrieve a dict of index and escape code for a given string.


Instruction:
How would you explain what the following Python 3 function does
def get_indices(s: Union[str, 'ChainedBase']) -> Dict[int, str]:
    codes = get_code_indices(s)
    if not codes:
        # This function is not for non-escape-code stuff, but okay.
        return {i: c for i, c in enumerate(s)}

    indices = {}
    for codeindex in sorted(codes):
        code = codes[codeindex]
        if codeindex == 0:
            indices[codeindex] = code
            continue
        # Grab characters before codeindex.
        start = max(indices or {0: ''}, key=int)
        startcode = indices.get(start, '')
        startlen = start + len(startcode)
        indices.update({i: s[i] for i in range(startlen, codeindex)})
        indices[codeindex] = code

    if not indices:
        return {i: c for i, c in enumerate(s)}
    lastindex = max(indices, key=int)
    lastitem = indices[lastindex]
    start = lastindex + len(lastitem)
    textlen = len(s)
    if start < (textlen - 1):
        # Grab chars after last code.
        indices.update({i: s[i] for i in range(start, textlen)})
    return indices

Response:
Retrieve a dict of characters and escape codes with their real index
        into the string as the key.


Instruction:
Can you tell what is the following Python 3 function doing
def strip_codes(s: Union[str, 'ChainedBase']) -> str:
    return codepat.sub('', str(s) if (s or (s == 0)) else '')

Response: Strip all color codes from a string.


Instruction:
Write a Python 3 function that can
add a new callback.

Response:
def add_callback(self, events, callback):
        """Add a new callback."""
        if self._poll is None:
            raise RuntimeError('poll instance is closed')
        if events & ~(READABLE|WRITABLE):
            raise ValueError('illegal event mask: {}'.format(events))
        if events & READABLE:
            self._readers += 1
        if events & WRITABLE:
            self._writers += 1
        handle = add_callback(self, callback, events)
        self._sync()
        return handle


Instruction:
Can you implement a function in Python 3 that
removes a callback from the poll.

Response:
def remove_callback(self, handle):
        """Remove a callback."""
        if self._poll is None:
            raise RuntimeError('poll instance is closed')
        remove_callback(self, handle)
        if handle.extra & READABLE:
            self._readers -= 1
        if handle.extra & WRITABLE:
            self._writers -= 1
        self._sync()


Instruction:
Can you generate the documentation for the following Python 3 function
def update_callback(self, handle, events):
        if self._poll is None:
            raise RuntimeError('poll instance is closed')
        if not has_callback(self, handle):
            raise ValueError('no such callback')
        if events & ~(READABLE|WRITABLE):
            raise ValueError('illegal event mask: {}'.format(events))
        if handle.extra == events:
            return
        if handle.extra & READABLE:
            self._readers -= 1
        if handle.extra & WRITABLE:
            self._writers -= 1
        if events & READABLE:
            self._readers += 1
        if events & WRITABLE:
            self._writers += 1
        handle.extra = events
        self._sync()

Response: Update the event mask for a callback.


Instruction:
Can you generate the documentation for the following Python 3 function
def close(self):
        if self._poll is None:
            return
        self._poll.close()
        self._poll = None
        self._readers = 0
        self._writers = 0
        self._events = 0
        clear_callbacks(self)

Response: Close the poll instance.


Instruction:
Given the following Python 3 function, write the documentation
def add_callback(self, fd, events, callback):
        if self._mpoll is None:
            raise RuntimeError('Poller instance is closed')
        try:
            mpoll = self._mpoll[fd]
        except KeyError:
            mpoll = self._mpoll[fd] = MultiPoll(self._loop, fd)
        handle = mpoll.add_callback(events, callback)
        return handle

Response: Add a callback to be called when events occur.


Instruction:
Can you create a Python 3 function that
removes a callback from the Poller.

Response:
def remove_callback(self, fd, handle):
        """Remove a callback added by :meth:`~Poller.add_callback`.

        If this is the last callback that is registered for the fd then this
        will deallocate the ``MultiPoll`` instance and close the libuv handle.
        """
        if self._mpoll is None:
            raise RuntimeError('Poller instance is closed')
        mpoll = self._mpoll.get(fd)
        if mpoll is None:
            raise ValueError('not watching fd {}'.format(fd))
        mpoll.remove_callback(handle)


Instruction:
Can you implement a function in Python 3 that
updates the event mask associated with an existing callback.

Response:
def update_callback(self, fd, handle, events):
        """Update the event mask associated with an existing callback.

        If you want to temporarily disable a callback then you can use this
        method with an *events* argument of ``0``. This is more efficient than
        removing the callback and adding it again later.
        """
        if self._mpoll is None:
            raise RuntimeError('Poller instance is closed')
        mpoll = self._mpoll.get(fd)
        if mpoll is None:
            raise ValueError('not watching fd {}'.format(fd))
        mpoll.update_callback(handle, events)


Instruction:
Can you generate a brief explanation for the following Python 3 code
def close(self):
        if self._mpoll is None:
            return
        for mpoll in self._mpoll.values():
            mpoll.close()
        self._mpoll.clear()
        self._mpoll = None

Response: Close all active poll instances and remove all callbacks.


Instruction:
Write a Python 3 script for
attempting the next authentication method or raises a failure if all mechanisms have been tried.

Response:
def authTryNextMethod(self):
        """
        Tries the next authentication method or raises a failure if all mechanisms
        have been tried.
        """
        if not self.authOrder:
            raise DBusAuthenticationFailed()

        self.authMech  = self.authOrder.pop()

        if self.authMech == 'DBUS_COOKIE_SHA1':
            self.sendAuthMessage('AUTH ' + self.authMech + ' ' +
                                 hexlify(getpass.getuser()))
        elif self.authMech == 'ANONYMOUS':
            self.sendAuthMessage('AUTH ' + self.authMech + ' ' +
                                 hexlify("txdbus"))
        else:
            self.sendAuthMessage('AUTH ' + self.authMech)


Instruction:
Create a Python 3 function to
read the DBus cookie from the cookie_context file and returns the hex cookie of the DBus cookie.

Response:
def _authGetDBusCookie(self, cookie_context, cookie_id):
        """
        Reads the requested cookie_id from the cookie_context file
        """
        # XXX   Ensure we obtain the correct directory for the
        #       authenticating user and that that user actually
        #       owns the keyrings directory

        if self.cookie_dir is None:
            cookie_dir = os.path.expanduser('~/.dbus-keyrings')
        else:
            cookie_dir = self.cookie_dir

        dstat = os.stat(cookie_dir)

        if dstat.st_mode & 0x36:  # 066
            raise Exception('User keyrings directory is writeable by other users. Aborting authentication')

        import pwd
        if dstat.st_uid != pwd.getpwuid(os.geteuid()).pw_uid:
            raise Exception('Keyrings directory is not owned by the current user. Aborting authentication!')

        f = open(os.path.join(cookie_dir, cookie_context), 'r')

        try:
            for line in f:
                try:
                    k_id, k_time, k_cookie_hex = line.split()
                    if k_id == cookie_id:
                        return k_cookie_hex
                except:
                    pass
        finally:
            f.close()


Instruction:
Can you generate the documentation for the following Python 3 function
def add_callback(obj, callback, args=()):
    callbacks = obj._callbacks
    node = Node(callback, args)
    # Store a single callback directly in _callbacks
    if callbacks is None:
        obj._callbacks = node
        return node
    # Otherwise use a dllist.
    if not isinstance(callbacks, dllist):
        obj._callbacks = dllist()
        obj._callbacks.insert(callbacks)
        callbacks = obj._callbacks
    callbacks.insert(node)
    return node

Response: Add a callback to an object.


Instruction:
How would you implement a function in Python 3 that
removes a callback from an object.

Response:
def remove_callback(obj, handle):
    """Remove a callback from an object."""
    callbacks = obj._callbacks
    if callbacks is handle:
        obj._callbacks = None
    elif isinstance(callbacks, dllist):
        callbacks.remove(handle)
        if not callbacks:
            obj._callbacks = None


Instruction:
Implement a Python 3 function for
returning whether a callback is currently registered for an object.

Response:
def has_callback(obj, handle):
    """Return whether a callback is currently registered for an object."""
    callbacks = obj._callbacks
    if not callbacks:
        return False
    if isinstance(callbacks, Node):
        return handle is callbacks
    else:
        return handle in callbacks


Instruction:
Write a Python 3 function that can
pop a single callback from the list of callbacks.

Response:
def pop_callback(obj):
    """Pop a single callback."""
    callbacks = obj._callbacks
    if not callbacks:
        return
    if isinstance(callbacks, Node):
        node = callbacks
        obj._callbacks = None
    else:
        node = callbacks.first
        callbacks.remove(node)
        if not callbacks:
            obj._callbacks = None
    return node.data, node.extra


Instruction:
How would you explain what the following Python 3 function does
def clear_callbacks(obj):
    callbacks = obj._callbacks
    if isinstance(callbacks, dllist):
        # Help the garbage collector by clearing all links.
        callbacks.clear()
    obj._callbacks = None

Response: Remove all callbacks from an object.


Instruction:
How would you explain what the following Python 3 function does
def walk_callbacks(obj, func, log=None):
    callbacks = obj._callbacks
    if isinstance(callbacks, Node):
        node = callbacks
        try:
            if not func(node.data, node.extra):
                obj._callbacks = None
        except Exception:
            if log is None:
                log = logging.get_logger()
            log.exception('uncaught exception in callback')
    elif isinstance(callbacks, dllist):
        for node in callbacks:
            try:
                if func(node.data, node.extra):
                    continue
                callbacks.remove(node)
            except Exception:
                if log is None:
                    log = logging.get_logger()
                log.exception('uncaught exception in callback')
        if not callbacks:
            obj._callbacks = None

Response:
Walks the callbacks list and calls func for all those those
    callbacks for which the function returns True.


Instruction:
Write a Python 3 function for
running callbacks on the object.

Response:
def run_callbacks(obj, log=None):
    """Run callbacks."""
    def run_callback(callback, args):
        return callback(*args)
    return walk_callbacks(obj, run_callback, log)


Instruction:
How would you code a function in Python 3 to
return a ConfigurationModel serializer class for the supplied configuration_model.

Response:
def get_serializer_class(configuration_model):
    """ Returns a ConfigurationModel serializer class for the supplied configuration_model. """
    class AutoConfigModelSerializer(ModelSerializer):
        """Serializer class for configuration models."""

        class Meta(object):
            """Meta information for AutoConfigModelSerializer."""
            model = configuration_model
            fields = '__all__'

        def create(self, validated_data):
            if "changed_by_username" in self.context:
                model = get_user_model()
                validated_data['changed_by'] = model.objects.get(username=self.context["changed_by_username"])
            return super(AutoConfigModelSerializer, self).create(validated_data)

    return AutoConfigModelSerializer


Instruction:
Write a Python 3 script to
give a stream containing JSON, deserializers the JSON into ConfigurationModel instances. The stream is expected to be in the following format: { "model": "config_models.ExampleConfigurationModel", "data": [ { "enabled": True, "color": "black" ... }, { "enabled": False, "color": "yellow" ... }, ... ] } If the provided stream does not contain valid JSON for the ConfigurationModel specified, an Exception will be raised. Arguments: stream: The stream of JSON, as described above. username: The username of the user making the change. This must match an existing user. Returns: the number of created entries

Response:
def deserialize_json(stream, username):
    """
    Given a stream containing JSON, deserializers the JSON into ConfigurationModel instances.

    The stream is expected to be in the following format:
        { "model": "config_models.ExampleConfigurationModel",
          "data":
            [
              { "enabled": True,
                "color": "black"
                ...
              },
              { "enabled": False,
                "color": "yellow"
                ...
              },
              ...
            ]
        }

    If the provided stream does not contain valid JSON for the ConfigurationModel specified,
    an Exception will be raised.

    Arguments:
            stream: The stream of JSON, as described above.
            username: The username of the user making the change. This must match an existing user.

    Returns: the number of created entries
    """
    parsed_json = JSONParser().parse(stream)
    serializer_class = get_serializer_class(apps.get_model(parsed_json["model"]))
    list_serializer = serializer_class(data=parsed_json["data"], context={"changed_by_username": username}, many=True)
    if list_serializer.is_valid():
        model_class = serializer_class.Meta.model
        for data in reversed(list_serializer.validated_data):
            if model_class.equal_to_current(data):
                list_serializer.validated_data.remove(data)

        entries_created = len(list_serializer.validated_data)
        list_serializer.save()
        return entries_created
    else:
        raise Exception(list_serializer.error_messages)


Instruction:
Write a Python 3 function that can
return all field names excluding reverse foreign key relationships.

Response:
def get_displayable_field_names(self):
        """
        Return all field names, excluding reverse foreign key relationships.
        """
        return [
            f.name
            for f in self.model._meta.get_fields()
            if not f.one_to_many
        ]


Instruction:
Make a summary of the following Python 3 code
def choices(self, changelist):
        show_all = self.used_parameters.get(self.parameter_name) == "1"
        return (
            {
                'display': _('Current Configuration'),
                'selected': not show_all,
                'query_string': changelist.get_query_string({}, [self.parameter_name]),
            },
            {
                'display': _('All (Show History)'),
                'selected': show_all,
                'query_string': changelist.get_query_string({self.parameter_name: "1"}, []),
            }
        )

Response: Returns a list of choices ready to be output in the template.


Instruction:
Can you generate the documentation for the following Python 3 function
def get_queryset(self, request):
        if request.GET.get(ShowHistoryFilter.parameter_name) == '1':
            queryset = self.model.objects.with_active_flag()
        else:
            # Show only the most recent row for each key.
            queryset = self.model.objects.current_set()
        ordering = self.get_ordering(request)
        if ordering:
            return queryset.order_by(*ordering)
        return queryset

Response: Returns the queryset for the most recent entry for the given request.


Instruction:
Create a Python 3 function to
edit link for the change view

Response:
def edit_link(self, inst):
        """ Edit link for the change view """
        if not inst.is_active:
            return u'--'
        update_url = reverse('admin:{}_{}_add'.format(self.model._meta.app_label, self.model._meta.model_name))
        update_url += "?source={}".format(inst.pk)
        return u'{}'.format(update_url, _('Update'))


Instruction:
Can you write a function in Python 3 where it
overrides django. contrib. admin. templatetags. admin_modify. submit_row.

Response:
def submit_row(context):
    """
    Overrides 'django.contrib.admin.templatetags.admin_modify.submit_row'.

    Manipulates the context going into that function by hiding all of the buttons
    in the submit row if the key `readonly` is set in the context.
    """
    ctx = original_submit_row(context)

    if context.get('readonly', False):
        ctx.update({
            'show_delete_link': False,
            'show_save_as_new': False,
            'show_save_and_add_another': False,
            'show_save_and_continue': False,
            'show_save': False,
        })
    else:
        return ctx


Instruction:
Explain what the following Python 3 code does
def current_set(self):
        assert self.model.KEY_FIELDS != (), "Just use model.current() if there are no KEY_FIELDS"
        return self.get_queryset().filter(
            pk__in=self._current_ids_subquery()
        ).annotate(
            is_active=models.Value(1, output_field=models.IntegerField())
        )

Response: A queryset for the active configuration entries only. Only useful if KEY_FIELDS is set.


Instruction:
Write a Python 3 script for
saving the current configuration entry to the database.

Response:
def save(self, force_insert=False, force_update=False, using=None,
             update_fields=None):
        """
        Clear the cached value when saving a new configuration entry
        """
        # Always create a new entry, instead of updating an existing model
        self.pk = None  # pylint: disable=invalid-name
        super(ConfigurationModel, self).save(
            force_insert,
            force_update,
            using,
            update_fields
        )
        cache.delete(self.cache_key_name(*[getattr(self, key) for key in self.KEY_FIELDS]))
        if self.KEY_FIELDS:
            cache.delete(self.key_values_cache_key_name())


Instruction:
Can you generate the documentation for the following Python 3 function
def cache_key_name(cls, *args):
        if cls.KEY_FIELDS != ():
            if len(args) != len(cls.KEY_FIELDS):
                raise TypeError(
                    "cache_key_name() takes exactly {} arguments ({} given)".format(len(cls.KEY_FIELDS), len(args))
                )
            # pylint: disable=unicode-builtin
            return 'configuration/{}/current/{}'.format(cls.__name__, ','.join(six.text_type(arg) for arg in args))
        else:
            return 'configuration/{}/current'.format(cls.__name__)

Response: Return the name of the key to use to cache the current configuration


Instruction:
Can you tell what is the following Python 3 function doing
def current(cls, *args):
        cached = cache.get(cls.cache_key_name(*args))
        if cached is not None:
            return cached

        key_dict = dict(zip(cls.KEY_FIELDS, args))
        try:
            current = cls.objects.filter(**key_dict).order_by('-change_date')[0]
        except IndexError:
            current = cls(**key_dict)

        cache.set(cls.cache_key_name(*args), current, cls.cache_timeout)
        return current

Response: Return the active configuration entry from the database or by creating a new one if it does not exist.


Instruction:
Can you create a Python 3 function that
keys for fetching unique key values from the cache

Response:
def key_values_cache_key_name(cls, *key_fields):
        """ Key for fetching unique key values from the cache """
        key_fields = key_fields or cls.KEY_FIELDS
        return 'configuration/{}/key_values/{}'.format(cls.__name__, ','.join(key_fields))


Instruction:
Can you write a function in Python 3 where it
returns a list of unique values for the given key_fields.

Response:
def key_values(cls, *key_fields, **kwargs):
        """
        Get the set of unique values in the configuration table for the given
        key[s]. Calling cls.current(*value) for each value in the resulting
        list should always produce an entry, though any such entry may have
        enabled=False.

        Arguments:
            key_fields: The positional arguments are the KEY_FIELDS to return. For example if
                you had a course embargo configuration where each entry was keyed on (country,
                course), then you might want to know "What countries have embargoes configured?"
                with cls.key_values('country'), or "Which courses have country restrictions?"
                with cls.key_values('course'). You can also leave this unspecified for the
                default, which returns the distinct combinations of all keys.
            flat: If you pass flat=True as a kwarg, it has the same effect as in Django's
                'values_list' method: Instead of returning a list of lists, you'll get one list
                of values. This makes sense to use whenever there is only one key being queried.

        Return value:
            List of lists of each combination of keys found in the database.
            e.g. [("Italy", "course-v1:SomeX+some+2015"), ...] for the course embargo example
        """
        flat = kwargs.pop('flat', False)
        assert not kwargs, "'flat' is the only kwarg accepted"
        key_fields = key_fields or cls.KEY_FIELDS
        cache_key = cls.key_values_cache_key_name(*key_fields)
        cached = cache.get(cache_key)
        if cached is not None:
            return cached
        values = list(cls.objects.values_list(*key_fields, flat=flat).order_by().distinct())
        cache.set(cache_key, values, cls.cache_timeout)
        return values


Instruction:
Write a Python 3 script for
returning True if the fields of this instance are equal False otherwise.

Response:
def fields_equal(self, instance, fields_to_ignore=("id", "change_date", "changed_by")):
        """
        Compares this instance's fields to the supplied instance to test for equality.
        This will ignore any fields in `fields_to_ignore`.

        Note that this method ignores many-to-many fields.

        Args:
            instance: the model instance to compare
            fields_to_ignore: List of fields that should not be compared for equality. By default
            includes `id`, `change_date`, and `changed_by`.

        Returns: True if the checked fields are all equivalent, else False
        """
        for field in self._meta.get_fields():
            if not field.many_to_many and field.name not in fields_to_ignore:
                if getattr(instance, field.name) != getattr(self, field.name):
                    return False

        return True


Instruction:
Write a Python 3 function that can
compare this instance to a model instance constructed from the supplied JSON.

Response:
def equal_to_current(cls, json, fields_to_ignore=("id", "change_date", "changed_by")):
        """
        Compares for equality this instance to a model instance constructed from the supplied JSON.
        This will ignore any fields in `fields_to_ignore`.

        Note that this method cannot handle fields with many-to-many associations, as those can only
        be set on a saved model instance (and saving the model instance will create a new entry).
        All many-to-many field entries will be removed before the equality comparison is done.

        Args:
            json: json representing an entry to compare
            fields_to_ignore: List of fields that should not be compared for equality. By default
            includes `id`, `change_date`, and `changed_by`.

        Returns: True if the checked fields are all equivalent, else False
        """

        # Remove many-to-many relationships from json.
        # They require an instance to be already saved.
        info = model_meta.get_field_info(cls)
        for field_name, relation_info in info.relations.items():
            if relation_info.to_many and (field_name in json):
                json.pop(field_name)

        new_instance = cls(**json)
        key_field_args = tuple(getattr(new_instance, key) for key in cls.KEY_FIELDS)
        current = cls.current(*key_field_args)
        # If current.id is None, no entry actually existed and the "current" method created it.
        if current.id is not None:
            return current.fields_equal(new_instance, fields_to_ignore)

        return False


Instruction:
Can you generate a brief explanation for the following Python 3 code
def create_atomic_wrapper(cls, wrapped_func):
        def _create_atomic_wrapper(*args, **kwargs):
            """Actual wrapper."""
            # When a view call fails due to a permissions error, it raises an exception.
            # An uncaught exception breaks the DB transaction for any following DB operations
            # unless it's wrapped in a atomic() decorator or context manager.
            with transaction.atomic():
                return wrapped_func(*args, **kwargs)

        return _create_atomic_wrapper

Response: Returns a wrapped function that wraps the given function with atomic operations.


Instruction:
Can you generate the documentation for the following Python 3 function
def as_view(cls, **initkwargs):
        view = super(AtomicMixin, cls).as_view(**initkwargs)
        return cls.create_atomic_wrapper(view)

Response: Overrides as_view to add atomic transaction.


Instruction:
How would you explain what the following Python 3 function does
def require_config(config_model):
    def _decorator(func):
        """
        Decorator implementation.
        """
        @wraps(func)
        def _inner(*args, **kwargs):
            """
            Wrapper implementation.
            """
            if not config_model.current().enabled:
                return HttpResponseNotFound()
            return func(*args, **kwargs)
        return _inner
    return _decorator

Response: Decorator that enables or disables a view based on the current configuration model.


Instruction:
How would you code a function in Python 3 to
merge a list of feature layers into one.

Response:
def merge(file, feature_layers):
    ''' Retrieve a list of OSciMap4 tile responses and merge them into one.

        get_tiles() retrieves data and performs basic integrity checks.
    '''
    tile = VectorTile(extents)

    for layer in feature_layers:
        tile.addFeatures(layer['features'], layer['name'])

    tile.complete()

    data = tile.out.SerializeToString()
    file.write(struct.pack(">I", len(data)))
    file.write(data)


Instruction:
Given the following Python 3 function, write the documentation
def _make_valid_if_necessary(shape):
    if shape.type in ('Polygon', 'MultiPolygon') and not shape.is_valid:
        shape = shape.buffer(0)

        # return value from buffer is usually valid, but it's
        # not clear from the docs whether this is guaranteed,
        # so return None if not.
        if not shape.is_valid:
            return None

    return shape

Response: Make valid shape if necessary.


Instruction:
Explain what the following Python 3 code does
def _accumulate_props(dest_props, src_props):
    props_size = 0
    if src_props:
        for k, v in src_props.items():
            if v is not None:
                props_size += len(k) + _sizeof(v)
                dest_props[k] = v
    return props_size

Response:
Helper function to accumulate a dict of properties
WorkItem and non - None src_props into dest_props


Instruction:
Explain what the following Python 3 code does
def metatile_children_with_size(coord, metatile_zoom, nominal_zoom, tile_size):

    from tilequeue.tile import coord_children_subrange
    from tilequeue.tile import metatile_zoom_from_size

    assert tile_size >= 256
    assert tile_size <= 256 * (1 << metatile_zoom)
    assert _is_power_of_2(tile_size)

    # delta is how many zoom levels _lower_ we want the child tiles, based on
    # their tile size. 256px tiles are defined as being at nominal zoom, so
    # delta = 0 for them.
    delta = metatile_zoom_from_size(tile_size // 256)

    zoom = nominal_zoom - delta

    return list(coord_children_subrange(coord, zoom, zoom))

Response: Returns a list of all the coords which are children of the input metatile at the given coord with the given zoom and size tile_size corrected for the given nominal zoom.


Instruction:
How would you implement a function in Python 3 that
calculates the tile sizes for a given zoom level.

Response:
def calculate_sizes_by_zoom(coord, metatile_zoom, cfg_tile_sizes, max_zoom):
    """
    Returns a map of nominal zoom to the list of tile sizes to generate at that
    zoom.

    This is because we want to generate different metatile contents at
    different zoom levels. At the most detailed zoom level, we want to generate
    the smallest tiles possible, as this allows "overzooming" by simply
    extracting the smaller tiles. At the minimum zoom, we want to get as close
    as we can to zero nominal zoom by using any "unused" space in the metatile
    for larger tile sizes that we're not generating.

    For example, with 1x1 metatiles, the tile size is always 256px, and the
    function will return {coord.zoom: [256]}

    Note that max_zoom should be the maximum *coordinate* zoom, not nominal
    zoom.
    """

    from tilequeue.tile import metatile_zoom_from_size

    tile_size_by_zoom = {}
    nominal_zoom = coord.zoom + metatile_zoom

    # check that the tile sizes are correct and within range.
    for tile_size in cfg_tile_sizes:
        assert tile_size >= 256
        assert tile_size <= 256 * (1 << metatile_zoom)
        assert _is_power_of_2(tile_size)

    if coord.zoom >= max_zoom:
        # all the tile_sizes down to 256 at the nominal zoom.
        tile_sizes = []
        tile_sizes.extend(cfg_tile_sizes)

        lowest_tile_size = min(tile_sizes)
        while lowest_tile_size > 256:
            lowest_tile_size //= 2
            tile_sizes.append(lowest_tile_size)

        tile_size_by_zoom[nominal_zoom] = tile_sizes

    elif coord.zoom <= 0:
        # the tile_sizes, plus max(tile_sizes) size at nominal zooms decreasing
        # down to 0 (or as close as we can get)
        tile_size_by_zoom[nominal_zoom] = cfg_tile_sizes

        max_tile_size = max(cfg_tile_sizes)
        max_tile_zoom = metatile_zoom_from_size(max_tile_size // 256)
        assert max_tile_zoom <= metatile_zoom
        for delta in range(0, metatile_zoom - max_tile_zoom):
            z = nominal_zoom - (delta + 1)
            tile_size_by_zoom[z] = [max_tile_size]

    else:
        # the tile_sizes at nominal zoom only.
        tile_size_by_zoom[nominal_zoom] = cfg_tile_sizes

    return tile_size_by_zoom


Instruction:
Write a Python 3 script for
calculating the cut coordinates at a given zoom.

Response:
def calculate_cut_coords_by_zoom(
        coord, metatile_zoom, cfg_tile_sizes, max_zoom):
    """
    Returns a map of nominal zoom to the list of cut coordinates at that
    nominal zoom.

    Note that max_zoom should be the maximum coordinate zoom, not nominal
    zoom.
    """

    tile_sizes_by_zoom = calculate_sizes_by_zoom(
        coord, metatile_zoom, cfg_tile_sizes, max_zoom)

    cut_coords_by_zoom = {}
    for nominal_zoom, tile_sizes in tile_sizes_by_zoom.iteritems():
        cut_coords = []
        for tile_size in tile_sizes:
            cut_coords.extend(metatile_children_with_size(
                coord, metatile_zoom, nominal_zoom, tile_size))

        cut_coords_by_zoom[nominal_zoom] = cut_coords

    return cut_coords_by_zoom


Instruction:
Can you tell what is the following Python 3 function doing
def tiles_are_equal(tile_data_1, tile_data_2, fmt):

    if fmt and fmt == zip_format:
        return metatiles_are_equal(tile_data_1, tile_data_2)

    else:
        return tile_data_1 == tile_data_2

Response: Returns True if the tile data is equal in tile_data_1 and tile_data_2.


Instruction:
Write a Python 3 function for
writing the tile data if the data has changed.

Response:
def write_tile_if_changed(store, tile_data, coord, format):
    """
    Only write tile data if different from existing.

    Try to read the tile data from the store first. If the existing
    data matches, don't write. Returns whether the tile was written.
    """

    existing_data = store.read_tile(coord, format)
    if not existing_data or \
       not tiles_are_equal(existing_data, tile_data, format):
        store.write_tile(tile_data, coord, format)
        return True
    else:
        return False


Instruction:
Here you have a function in Python 3, explain what it does
def _override_cfg(container, yamlkeys, value):

    key = yamlkeys[0]
    rest = yamlkeys[1:]

    if len(rest) == 0:
        # no rest means we found the key to update.
        container[key] = value

    elif key in container:
        # still need to find the leaf in the tree, so recurse.
        _override_cfg(container[key], rest, value)

    else:
        # need to create a sub-tree down to the leaf to insert into.
        subtree = {}
        _override_cfg(subtree, rest, value)
        container[key] = subtree

Response: Override a hierarchical key in the config setting it to the value.


Instruction:
Can you create a Python 3 function that
generates a full pyramid for a single coordinate.

Response:
def coord_pyramid(coord, zoom_start, zoom_stop):
    """
    generate full pyramid for coord

    Generate the full pyramid for a single coordinate. Note that zoom_stop is
    exclusive.
    """
    if zoom_start <= coord.zoom:
        yield coord
    for child_coord in coord_children_range(coord, zoom_stop):
        if zoom_start <= child_coord.zoom:
            yield child_coord


Instruction:
Can you generate a brief explanation for the following Python 3 code
def coord_pyramids(coords, zoom_start, zoom_stop):
    for coord in coords:
        for child in coord_pyramid(coord, zoom_start, zoom_stop):
            yield child

Response: Generate full pyramid for coords


Instruction:
Given the following Python 3 function, write the documentation
def emit_toi_stats(toi_set, peripherals):

    count_by_zoom = defaultdict(int)
    total = 0
    for coord_int in toi_set:
        coord = coord_unmarshall_int(coord_int)
        count_by_zoom[coord.zoom] += 1
        total += 1

    peripherals.stats.gauge('tiles-of-interest.count', total)
    for zoom, count in count_by_zoom.items():
        peripherals.stats.gauge(
            'tiles-of-interest.by-zoom.z{:02d}'.format(zoom),
            count
        )

Response: Calculates new TOI stats and emits them via statsd.


Instruction:
Can you create a Python 3 function that
loads all tiles of interest into the top level hierarchy.

Response:
def tilequeue_load_tiles_of_interest(cfg, peripherals):
    """
    Given a newline-delimited file containing tile coordinates in
    `zoom/column/row` format, load those tiles into the tiles of interest.
    """
    logger = make_logger(cfg, 'load_tiles_of_interest')

    toi_filename = "toi.txt"
    logger.info('Loading tiles of interest from %s ... ', toi_filename)

    with open(toi_filename, 'r') as f:
        new_toi = load_set_from_fp(f)

    logger.info('Loading tiles of interest from %s ... done', toi_filename)
    logger.info('Setting new TOI (with %s tiles) ... ', len(new_toi))

    peripherals.toi.set_tiles_of_interest(new_toi)
    emit_toi_stats(new_toi, peripherals)

    logger.info('Setting new TOI (with %s tiles) ... done', len(new_toi))

    logger.info('Loading tiles of interest ... done')


Instruction:
Write a Python 3 script for
checking which files exist on s3 but are not in toi.

Response:
def tilequeue_stuck_tiles(cfg, peripherals):
    """
    Check which files exist on s3 but are not in toi.
    """
    store = _make_store(cfg)
    format = lookup_format_by_extension('zip')
    layer = 'all'

    assert peripherals.toi, 'Missing toi'
    toi = peripherals.toi.fetch_tiles_of_interest()

    for coord in store.list_tiles(format, layer):
        coord_int = coord_marshall_int(coord)
        if coord_int not in toi:
            print serialize_coord(coord)


Instruction:
Can you generate the documentation for the following Python 3 function
def tilequeue_tile_status(cfg, peripherals, args):
    logger = make_logger(cfg, 'tile_status')

    # friendly warning to avoid confusion when this command outputs nothing
    # at all when called with no positional arguments.
    if not args.coords:
        logger.warning('No coordinates given on the command line.')
        return

    # pre-load TOI to avoid having to do it for each coordinate
    toi = None
    if peripherals.toi:
        toi = peripherals.toi.fetch_tiles_of_interest()

    # TODO: make these configurable!
    tile_format = lookup_format_by_extension('zip')
    store = _make_store(cfg)

    for coord_str in args.coords:
        coord = deserialize_coord(coord_str)

        # input checking! make sure that the coordinate is okay to use in
        # the rest of the code.
        if not coord:
            logger.warning('Could not deserialize %r as coordinate', coord_str)
            continue

        if not coord_is_valid(coord):
            logger.warning('Coordinate is not valid: %r (parsed from %r)',
                           coord, coord_str)
            continue

        # now we think we probably have a valid coordinate. go look up
        # whether it exists in various places.

        logger.info("=== %s ===", coord_str)
        coord_int = coord_marshall_int(coord)

        if peripherals.inflight_mgr:
            is_inflight = peripherals.inflight_mgr.is_inflight(coord)
            logger.info('inflight: %r', is_inflight)

        if toi:
            in_toi = coord_int in toi
            logger.info('in TOI: %r' % (in_toi,))

        data = store.read_tile(coord, tile_format)
        logger.info('tile in store: %r', bool(data))

Response: Report the status of the given tiles in the store queue and TOI.


Instruction:
Create a Python 3 function for
commanding to take tile expiry path and enqueue for rawr tile generation

Response:
def tilequeue_rawr_enqueue(cfg, args):
    """command to take tile expiry path and enqueue for rawr tile generation"""
    from tilequeue.stats import RawrTileEnqueueStatsHandler
    from tilequeue.rawr import make_rawr_enqueuer_from_cfg

    msg_marshall_yaml = cfg.yml.get('message-marshall')
    assert msg_marshall_yaml, 'Missing message-marshall config'
    msg_marshaller = make_message_marshaller(msg_marshall_yaml)

    logger = make_logger(cfg, 'rawr_enqueue')
    stats = make_statsd_client_from_cfg(cfg)
    stats_handler = RawrTileEnqueueStatsHandler(stats)
    rawr_enqueuer = make_rawr_enqueuer_from_cfg(
        cfg, logger, stats_handler, msg_marshaller)

    with open(args.expiry_path) as fh:
        coords = create_coords_generator_from_tiles_file(fh)
        rawr_enqueuer(coords)


Instruction:
Can you generate a brief explanation for the following Python 3 code
def _tilequeue_rawr_setup(cfg):
    rawr_yaml = cfg.yml.get('rawr')
    assert rawr_yaml is not None, 'Missing rawr configuration in yaml'

    rawr_postgresql_yaml = rawr_yaml.get('postgresql')
    assert rawr_postgresql_yaml, 'Missing rawr postgresql config'

    from raw_tiles.formatter.msgpack import Msgpack
    from raw_tiles.gen import RawrGenerator
    from raw_tiles.source.conn import ConnectionContextManager
    from raw_tiles.source import parse_sources
    from raw_tiles.source import DEFAULT_SOURCES as DEFAULT_RAWR_SOURCES
    from tilequeue.rawr import RawrS3Sink
    from tilequeue.rawr import RawrStoreSink
    import boto3
    # pass through the postgresql yaml config directly
    conn_ctx = ConnectionContextManager(rawr_postgresql_yaml)

    rawr_source_list = rawr_yaml.get('sources', DEFAULT_RAWR_SOURCES)
    assert isinstance(rawr_source_list, list), \
        'RAWR source list should be a list'
    assert len(rawr_source_list) > 0, \
        'RAWR source list should be non-empty'

    rawr_store = rawr_yaml.get('store')
    if rawr_store:
        store = make_store(
            rawr_store, credentials=cfg.subtree('aws credentials'))
        rawr_sink = RawrStoreSink(store)

    else:
        rawr_sink_yaml = rawr_yaml.get('sink')
        assert rawr_sink_yaml, 'Missing rawr sink config'
        sink_type = rawr_sink_yaml.get('type')
        assert sink_type, 'Missing rawr sink type'
        if sink_type == 's3':
            s3_cfg = rawr_sink_yaml.get('s3')
            assert s3_cfg, 'Missing s3 config'
            bucket = s3_cfg.get('bucket')
            assert bucket, 'Missing rawr sink bucket'
            sink_region = s3_cfg.get('region')
            assert sink_region, 'Missing rawr sink region'
            prefix = s3_cfg.get('prefix')
            assert prefix, 'Missing rawr sink prefix'
            extension = s3_cfg.get('extension')
            assert extension, 'Missing rawr sink extension'
            tags = s3_cfg.get('tags')
            from tilequeue.store import make_s3_tile_key_generator
            tile_key_gen = make_s3_tile_key_generator(s3_cfg)

            s3_client = boto3.client('s3', region_name=sink_region)
            rawr_sink = RawrS3Sink(
                s3_client, bucket, prefix, extension, tile_key_gen, tags)
        elif sink_type == 'none':
            from tilequeue.rawr import RawrNullSink
            rawr_sink = RawrNullSink()
        else:
            assert 0, 'Unknown rawr sink type %s' % sink_type

    rawr_source = parse_sources(rawr_source_list)
    rawr_formatter = Msgpack()
    rawr_gen = RawrGenerator(rawr_source, rawr_formatter, rawr_sink)

    return rawr_gen, conn_ctx

Response: command to read from rawr queue and generate rawr tiles


Instruction:
Make a summary of the following Python 3 code
def tilequeue_rawr_seed_toi(cfg, peripherals):
    tiles_of_interest = peripherals.toi.fetch_tiles_of_interest()
    coords = map(coord_unmarshall_int, tiles_of_interest)
    _tilequeue_rawr_seed(cfg, peripherals, coords)

Response: command to read the toi and enqueue the corresponding rawr tiles


Instruction:
Given the following Python 3 function, write the documentation
def tilequeue_rawr_seed_all(cfg, peripherals):

    rawr_yaml = cfg.yml.get('rawr')
    assert rawr_yaml is not None, 'Missing rawr configuration in yaml'

    group_by_zoom = rawr_yaml.get('group-zoom')
    assert group_by_zoom is not None, 'Missing group-zoom rawr config'

    max_coord = 2 ** group_by_zoom

    # creating the list of all coordinates here might be a lot of memory, but
    # if we handle the TOI okay then we should be okay with z10. if the group
    # by zoom is much larger, then it might start running into problems.
    coords = []
    for x in xrange(0, max_coord):
        for y in xrange(0, max_coord):
            coords.append(Coordinate(zoom=group_by_zoom, column=x, row=y))

    _tilequeue_rawr_seed(cfg, peripherals, coords)

Response: command to enqueue all the tiles at the group - by zoom


Instruction:
Can you tell what is the following Python 3 function doing
def encode_single_layer(out, features, zoom):
    precision = precision_for_zoom(zoom)
    fs = create_layer_feature_collection(features, precision)
    json.dump(fs, out)

Response: Encode a list of features into a GeoJSON stream.


Instruction:
Create a Python 3 function for
encoding a list of features_by_layer into a JSON file.

Response:
def encode_multiple_layers(out, features_by_layer, zoom):
    """
    features_by_layer should be a dict: layer_name -> feature tuples
    """
    precision = precision_for_zoom(zoom)
    geojson = {}
    for layer_name, features in features_by_layer.items():
        fs = create_layer_feature_collection(features, precision)
        geojson[layer_name] = fs
    json.dump(geojson, out)


Instruction:
Can you generate a brief explanation for the following Python 3 code
def update_arc_indexes(geometry, merged_arcs, old_arcs):
    if geometry['type'] in ('Point', 'MultiPoint'):
        return

    elif geometry['type'] == 'LineString':
        for arc_index, old_arc in enumerate(geometry['arcs']):
            geometry['arcs'][arc_index] = len(merged_arcs)
            merged_arcs.append(old_arcs[old_arc])

    elif geometry['type'] == 'Polygon':
        for ring in geometry['arcs']:
            for arc_index, old_arc in enumerate(ring):
                ring[arc_index] = len(merged_arcs)
                merged_arcs.append(old_arcs[old_arc])

    elif geometry['type'] == 'MultiLineString':
        for part in geometry['arcs']:
            for arc_index, old_arc in enumerate(part):
                part[arc_index] = len(merged_arcs)
                merged_arcs.append(old_arcs[old_arc])

    elif geometry['type'] == 'MultiPolygon':
        for part in geometry['arcs']:
            for ring in part:
                for arc_index, old_arc in enumerate(ring):
                    ring[arc_index] = len(merged_arcs)
                    merged_arcs.append(old_arcs[old_arc])

    else:
        raise NotImplementedError("Can't do %s geometries" % geometry['type'])

Response: Updates arc indexes and add arcs to merged_arcs along the way.


Instruction:
Implement a Python 3 function for
returning a TopoJSON transform dictionary and a point - transforming function.

Response:
def get_transform(bounds, size=4096):
    """ Return a TopoJSON transform dictionary and a point-transforming function.

        Size is the tile size in pixels and sets the implicit output
        resolution.
    """
    tx, ty = bounds[0], bounds[1]
    sx, sy = (bounds[2] - bounds[0]) / size, (bounds[3] - bounds[1]) / size

    def forward(lon, lat):
        """ Transform a longitude and latitude to TopoJSON integer space.
        """
        return int(round((lon - tx) / sx)), int(round((lat - ty) / sy))

    return dict(translate=(tx, ty), scale=(sx, sy)), forward


Instruction:
Create a Python 3 function for
encoding a list of features into a TopoJSON file.

Response:
def encode(file, features_by_layer, bounds, size=4096):
    """ Encode a dict of layername: (shape, props, id) features into a
        TopoJSON stream.

        If no id is available, pass in None

        Geometries in the features list are assumed to be unprojected
        lon, lats.  Bounds are given in geographic coordinates as
        (xmin, ymin, xmax, ymax).

        Size is the number of integer coordinates which span the extent
        of the tile.
    """
    transform, forward = get_transform(bounds, size=size)
    arcs = []

    geometries_by_layer = {}

    for layer, features in features_by_layer.iteritems():
        geometries = []
        for shape, props, fid in features:
            if shape.type == 'GeometryCollection':
                continue

            geometry = dict(properties=props)

            if fid is not None:
                geometry['id'] = fid

            elif shape.type == 'Point':
                geometry.update(dict(
                    type='Point',
                    coordinates=forward(shape.x, shape.y)))

            elif shape.type == 'LineString':
                geometry.update(dict(type='LineString', arcs=[len(arcs)]))
                arcs.append(diff_encode(shape, forward))

            elif shape.type == 'Polygon':
                geometry.update(dict(type='Polygon', arcs=[]))

                rings = [shape.exterior] + list(shape.interiors)

                for ring in rings:
                    geometry['arcs'].append([len(arcs)])
                    arcs.append(diff_encode(ring, forward))

            elif shape.type == 'MultiPoint':
                geometry.update(dict(type='MultiPoint', coordinates=[]))

                for point in shape.geoms:
                    geometry['coordinates'].append(forward(point.x, point.y))

            elif shape.type == 'MultiLineString':
                geometry.update(dict(type='MultiLineString', arcs=[]))

                for line in shape.geoms:
                    geometry['arcs'].append([len(arcs)])
                    arcs.append(diff_encode(line, forward))

            elif shape.type == 'MultiPolygon':
                geometry.update(dict(type='MultiPolygon', arcs=[]))

                for polygon in shape.geoms:
                    rings = [polygon.exterior] + list(polygon.interiors)
                    polygon_arcs = []

                    for ring in rings:
                        polygon_arcs.append([len(arcs)])
                        arcs.append(diff_encode(ring, forward))

                    geometry['arcs'].append(polygon_arcs)

            else:
                raise NotImplementedError("Can't do %s geometries" %
                                          shape.type)

            geometries.append(geometry)

        geometries_by_layer[layer] = dict(
            type='GeometryCollection',
            geometries=geometries,
        )

    result = dict(
        type='Topology',
        transform=transform,
        objects=geometries_by_layer,
        arcs=arcs,
    )

    json.dump(result, file)


Instruction:
Create a Python 3 function to
filter out any bounding box that overlaps with the bounding box.

Response:
def jinja_filter_bbox_overlaps(bounds, geometry_col_name, srid=3857):
    """
    Check whether the boundary of the geometry intersects with the bounding
    box.

    Note that the usual meaning of "overlaps" in GIS terminology is that the
    boundaries of the box and polygon intersect, but not the interiors. This
    means that if the box or polygon is completely within the other, then
    st_overlaps will be false.

    However, that's not what we want. This is used for boundary testing, and
    while we don't want to pull out a whole country boundary if the bounding
    box is fully within it, we _do_ want to if the country boundary is within
    the bounding box.

    Therefore, this test has an extra "or st_contains" test to also pull in any
    boundaries which are completely within the bounding box.
    """

    min_point = 'ST_MakePoint(%.12f, %.12f)' % (bounds[0], bounds[1])
    max_point = 'ST_MakePoint(%.12f, %.12f)' % (bounds[2], bounds[3])
    bbox_no_srid = 'ST_MakeBox2D(%s, %s)' % (min_point, max_point)
    bbox = 'ST_SetSrid(%s, %d)' % (bbox_no_srid, srid)
    bbox_filter = \
        '((%(col)s && %(bbox)s) AND (' \
        '  st_overlaps(%(col)s, %(bbox)s) OR' \
        '  st_contains(%(bbox)s, %(col)s)' \
        '))' \
        % dict(col=geometry_col_name, bbox=bbox)
    return bbox_filter


Instruction:
Create a Python 3 function to
create a DataFetcher object which is a function which returns a list of rows.

Response:
def make_db_data_fetcher(postgresql_conn_info, template_path, reload_templates,
                         query_cfg, io_pool):
    """
    Returns an object which is callable with the zoom and unpadded bounds and
    which returns a list of rows.
    """

    sources = parse_source_data(query_cfg)
    queries_generator = make_queries_generator(
        sources, template_path, reload_templates)
    return DataFetcher(
        postgresql_conn_info, queries_generator, io_pool)