Instruction:
Given the following Python 3 function, write the documentation
def warnpy3k(message, category=None, stacklevel=1):
    if sys.py3kwarning:
        if category is None:
            category = DeprecationWarning
        warn(message, category, stacklevel+1)

Response: Issue a deprecation warning for Python 3. x related changes.


Instruction:
How would you implement a function in Python 3 that
hooks to write a warning to a file ; replace if you like.

Response:
def _show_warning(message, category, filename, lineno, file=None, line=None):
    """Hook to write a warning to a file; replace if you like."""
    if file is None:
        file = sys.stderr
        if file is None:
            # sys.stderr is None - warnings get lost
            return
    try:
        file.write(formatwarning(message, category, filename, lineno, line))
    except (IOError, UnicodeError):
        pass # the file (probably stderr) is invalid - this warning gets lost.


Instruction:
How would you implement a function in Python 3 that
functions to format a warning the standard way.

Response:
def formatwarning(message, category, filename, lineno, line=None):
    """Function to format a warning the standard way."""
    try:
        unicodetype = unicode
    except NameError:
        unicodetype = ()
    try:
        message = str(message)
    except UnicodeEncodeError:
        pass
    s =  "%s: %s: %s\n" % (lineno, category.__name__, message)
    line = linecache.getline(filename, lineno) if line is None else line
    if line:
        line = line.strip()
        if isinstance(s, unicodetype) and isinstance(line, str):
            line = unicode(line, 'latin1')
        s += "  %s\n" % line
    if isinstance(s, unicodetype) and isinstance(filename, str):
        enc = sys.getfilesystemencoding()
        if enc:
            try:
                filename = unicode(filename, enc)
            except UnicodeDecodeError:
                pass
    s = "%s:%s" % (filename, s)
    return s


Instruction:
Implement a Python 3 function for
adding a new entry to the list of filters that match the given message.

Response:
def filterwarnings(action, message="", category=Warning, module="", lineno=0,
                   append=0):
    """Insert an entry into the list of warnings filters (at the front).

    'action' -- one of "error", "ignore", "always", "default", "module",
                or "once"
    'message' -- a regex that the warning message must match
    'category' -- a class that the warning must be a subclass of
    'module' -- a regex that the module name must match
    'lineno' -- an integer line number, 0 matches all warnings
    'append' -- if true, append to the list of filters
    """
    assert action in ("error", "ignore", "always", "default", "module",
                      "once"), "invalid action: %r" % (action,)
    assert isinstance(message, basestring), "message must be a string"
    assert isinstance(category, type), "category must be a class"
    assert issubclass(category, Warning), "category must be a Warning subclass"
    assert isinstance(module, basestring), "module must be a string"
    assert isinstance(lineno, int) and lineno >= 0, \
           "lineno must be an int >= 0"
    item = (action, re.compile(message, re.I), category,
            re.compile(module), lineno)
    if append:
        filters.append(item)
    else:
        filters.insert(0, item)


Instruction:
Can you create a Python 3 function that
inserts a simple filter into the list of filters.

Response:
def simplefilter(action, category=Warning, lineno=0, append=0):
    """Insert a simple entry into the list of warnings filters (at the front).

    A simple filter matches all modules and messages.
    'action' -- one of "error", "ignore", "always", "default", "module",
                or "once"
    'category' -- a class that the warning must be a subclass of
    'lineno' -- an integer line number, 0 matches all warnings
    'append' -- if true, append to the list of filters
    """
    assert action in ("error", "ignore", "always", "default", "module",
                      "once"), "invalid action: %r" % (action,)
    assert isinstance(lineno, int) and lineno >= 0, \
           "lineno must be an int >= 0"
    item = (action, None, category, None, lineno)
    if append:
        filters.append(item)
    else:
        filters.insert(0, item)


Instruction:
Implement a function in Python 3 to
issue a warning or maybe raise an exception.

Response:
def warn(message, category=None, stacklevel=1):
    """Issue a warning, or maybe ignore it or raise an exception."""
    # Check if message is already a Warning object
    if isinstance(message, Warning):
        category = message.__class__
    # Check category argument
    if category is None:
        category = UserWarning
    assert issubclass(category, Warning)
    # Get context information
    try:
        caller = sys._getframe(stacklevel)
    except ValueError:
        globals = sys.__dict__
        lineno = 1
    else:
        globals = caller.f_globals
        lineno = caller.f_lineno
    if '__name__' in globals:
        module = globals['__name__']
    else:
        module = "<string>"
    filename = globals.get('__file__')
    if filename:
        fnl = filename.lower()
        if fnl.endswith((".pyc", ".pyo")):
            filename = filename[:-1]
    else:
        if module == "__main__":
            try:
                filename = sys.argv[0]
            except AttributeError:
                # embedded interpreters don't have sys.argv, see bug #839151
                filename = '__main__'
        if not filename:
            filename = module
    registry = globals.setdefault("__warningregistry__", {})
    warn_explicit(message, category, filename, lineno, module, registry,
                  globals)


Instruction:
Make a summary of the following Python 3 code
def _hash(self):
        MAX = sys.maxint
        MASK = 2 * MAX + 1
        n = len(self)
        h = 1927868237 * (n + 1)
        h &= MASK
        for x in self:
            hx = hash(x)
            h ^= (hx ^ (hx << 16) ^ 89869747)  * 3644798167
            h &= MASK
        h = h * 69069 + 907133923
        h &= MASK
        if h > MAX:
            h -= MASK + 1
        if h == -1:
            h = 590923713
        return h

Response: Compute the hash value of a set of items.


Instruction:
Can you write a function in Python 3 where it
removes an element from the set.

Response:
def remove(self, value):
        """Remove an element. If not a member, raise a KeyError."""
        if value not in self:
            raise KeyError(value)
        self.discard(value)


Instruction:
Make a summary of the following Python 3 code
def pop(self):
        it = iter(self)
        try:
            value = next(it)
        except StopIteration:
            raise KeyError
        self.discard(value)
        return value

Response: Return the popped value. Raise KeyError if empty.


Instruction:
Here you have a function in Python 3, explain what it does
def update(*args, **kwds):
        ''' D.update([E, ]**F) -> None.  Update D from mapping/iterable E and F.
            If E present and has a .keys() method, does:     for k in E: D[k] = E[k]
            If E present and lacks .keys() method, does:     for (k, v) in E: D[k] = v
            In either case, this is followed by: for k, v in F.items(): D[k] = v
        '''
        if not args:
            raise TypeError("descriptor 'update' of 'MutableMapping' object "
                            "needs an argument")
        self = args[0]
        args = args[1:]
        if len(args) > 1:
            raise TypeError('update expected at most 1 arguments, got %d' %
                            len(args))
        if args:
            other = args[0]
            if isinstance(other, Mapping):
                for key in other:
                    self[key] = other[key]
            elif hasattr(other, "keys"):
                for key in other.keys():
                    self[key] = other[key]
            else:
                for key, value in other:
                    self[key] = value
        for key, value in kwds.items():
            self[key] = value

Response: Update the object with the contents of the object.


Instruction:
Make a summary of the following Python 3 code
def index(self, value):
        '''S.index(value) -> integer -- return first index of value.
           Raises ValueError if the value is not present.
        '''
        for i, v in enumerate(self):
            if v == value:
                return i
        raise ValueError

Response: S. index - Returns the first index of value.


Instruction:
Write a Python 3 function that can
reverse the list of all the elements of the array.

Response:
def reverse(self):
        'S.reverse() -- reverse *IN PLACE*'
        n = len(self)
        for i in range(n//2):
            self[i], self[n-i-1] = self[n-i-1], self[i]


Instruction:
Make a summary of the following Python 3 code
def go_str(value):
  io = StringIO.StringIO()
  io.write('"')
  for c in value:
    if c in _ESCAPES:
      io.write(_ESCAPES[c])
    elif c in _SIMPLE_CHARS:
      io.write(c)
    else:
      io.write(r'\x{:02x}'.format(ord(c)))
  io.write('"')
  return io.getvalue()

Response: Returns value as a valid Go string literal.


Instruction:
Given the following Python 3 function, write the documentation
def write_block(self, block_, body):
    self.write('for ; πF.State() >= 0; πF.PopCheckpoint() {')
    with self.indent_block():
      self.write('switch πF.State() {')
      self.write('case 0:')
      for checkpoint in block_.checkpoints:
        self.write_tmpl('case $state: goto Label$state', state=checkpoint)
      self.write('default: panic("unexpected function state")')
      self.write('}')
      # Assume that body is aligned with goto labels.
      with self.indent_block(-1):
        self.write(body)
    self.write('}')

Response: Outputs the boilerplate needed for code blocks like functions.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def acquire(self, blocking=1):
        me = _get_ident()
        if self.__owner == me:
            self.__count = self.__count + 1
            if __debug__:
                self._note("%s.acquire(%s): recursive success", self, blocking)
            return 1
        rc = self.__block.acquire(blocking)
        if rc:
            self.__owner = me
            self.__count = 1
            if __debug__:
                self._note("%s.acquire(%s): initial success", self, blocking)
        else:
            if __debug__:
                self._note("%s.acquire(%s): failure", self, blocking)
        return rc

Response:
Acquire a lock, blocking or non-blocking.

        When invoked without arguments: if this thread already owns the lock,
        increment the recursion level by one, and return immediately. Otherwise,
        if another thread owns the lock, block until the lock is unlocked. Once
        the lock is unlocked (not owned by any thread), then grab ownership, set
        the recursion level to one, and return. If more than one thread is
        blocked waiting until the lock is unlocked, only one at a time will be
        able to grab ownership of the lock. There is no return value in this
        case.

        When invoked with the blocking argument set to true, do the same thing
        as when called without arguments, and return true.

        When invoked with the blocking argument set to false, do not block. If a
        call without an argument would block, return false immediately;
        otherwise, do the same thing as when called without arguments, and
        return true.


Instruction:
Can you generate the documentation for the following Python 3 function
def release(self):
        if self.__owner != _get_ident():
            raise RuntimeError("cannot release un-acquired lock")
        self.__count = count = self.__count - 1
        if not count:
            self.__owner = None
            self.__block.release()
            if __debug__:
                self._note("%s.release(): final release", self)
        else:
            if __debug__:
                self._note("%s.release(): non-final release", self)

Response:
Release a lock, decrementing the recursion level.

        If after the decrement it is zero, reset the lock to unlocked (not owned
        by any thread), and if any other threads are blocked waiting for the
        lock to become unlocked, allow exactly one of them to proceed. If after
        the decrement the recursion level is still nonzero, the lock remains
        locked and owned by the calling thread.

        Only call this method when the calling thread owns the lock. A
        RuntimeError is raised if this method is called when the lock is
        unlocked.

        There is no return value.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def wait(self, timeout=None):
        if not self._is_owned():
            raise RuntimeError("cannot wait on un-acquired lock")
        waiter = _allocate_lock()
        waiter.acquire()
        self.__waiters.append(waiter)
        saved_state = self._release_save()
        try:    # restore state no matter what (e.g., KeyboardInterrupt)
            if timeout is None:
                waiter.acquire()
                if __debug__:
                    self._note("%s.wait(): got it", self)
            else:
                # Balancing act:  We can't afford a pure busy loop, so we
                # have to sleep; but if we sleep the whole timeout time,
                # we'll be unresponsive.  The scheme here sleeps very
                # little at first, longer as time goes on, but never longer
                # than 20 times per second (or the timeout time remaining).
                endtime = _time() + timeout
                delay = 0.0005 # 500 us -> initial delay of 1 ms
                while True:
                    gotit = waiter.acquire(0)
                    if gotit:
                        break
                    remaining = endtime - _time()
                    if remaining <= 0:
                        break
                    delay = min(delay * 2, remaining, .05)
                    _sleep(delay)
                if not gotit:
                    if __debug__:
                        self._note("%s.wait(%s): timed out", self, timeout)
                    try:
                        self.__waiters.remove(waiter)
                    except ValueError:
                        pass
                else:
                    if __debug__:
                        self._note("%s.wait(%s): got it", self, timeout)
        finally:
            self._acquire_restore(saved_state)

Response: Wait until the current thread is notified or until a timeout occurs.


Instruction:
Here you have a function in Python 3, explain what it does
def notify(self, n=1):
        if not self._is_owned():
            raise RuntimeError("cannot notify on un-acquired lock")
        __waiters = self.__waiters
        waiters = __waiters[:n]
        if not waiters:
            if __debug__:
                self._note("%s.notify(): no waiters", self)
            return
        self._note("%s.notify(): notifying %d waiter%s", self, n,
                   n!=1 and "s" or "")
        for waiter in waiters:
            waiter.release()
            try:
                __waiters.remove(waiter)
            except ValueError:
                pass

Response: Wake up at most n threads waiting on this condition.


Instruction:
Implement a Python 3 function for
acquiring a semaphore of the current value.

Response:
def acquire(self, blocking=1):
        """Acquire a semaphore, decrementing the internal counter by one.

        When invoked without arguments: if the internal counter is larger than
        zero on entry, decrement it by one and return immediately. If it is zero
        on entry, block, waiting until some other thread has called release() to
        make it larger than zero. This is done with proper interlocking so that
        if multiple acquire() calls are blocked, release() will wake exactly one
        of them up. The implementation may pick one at random, so the order in
        which blocked threads are awakened should not be relied on. There is no
        return value in this case.

        When invoked with blocking set to true, do the same thing as when called
        without arguments, and return true.

        When invoked with blocking set to false, do not block. If a call without
        an argument would block, return false immediately; otherwise, do the
        same thing as when called without arguments, and return true.

        """
        rc = False
        with self.__cond:
            while self.__value == 0:
                if not blocking:
                    break
                if __debug__:
                    self._note("%s.acquire(%s): blocked waiting, value=%s",
                            self, blocking, self.__value)
                self.__cond.wait()
            else:
                self.__value = self.__value - 1
                if __debug__:
                    self._note("%s.acquire: success, value=%s",
                            self, self.__value)
                rc = True
        return rc


Instruction:
Can you generate a brief explanation for the following Python 3 code
def release(self):
        with self.__cond:
            self.__value = self.__value + 1
            if __debug__:
                self._note("%s.release: success, value=%s",
                        self, self.__value)
            self.__cond.notify()

Response:
Release a semaphore, incrementing the internal counter by one.

        When the counter is zero on entry and another thread is waiting for it
        to become larger than zero again, wake up that thread.


Instruction:
Can you implement a function in Python 3 that
releases a semaphore, incrementing the internal counter by one. When the counter is zero on entry and another thread is waiting for it to become larger than zero again, wake up that thread. If the number of releases exceeds the number of acquires, raise a ValueError.

Response:
def release(self):
        """Release a semaphore, incrementing the internal counter by one.

        When the counter is zero on entry and another thread is waiting for it
        to become larger than zero again, wake up that thread.

        If the number of releases exceeds the number of acquires,
        raise a ValueError.

        """
        with self.__cond:
            if self.__value >= self._initial_value:
                raise ValueError("Semaphore released too many times")
            self.__value += 1
            self.__cond.notify()


Instruction:
Write a Python 3 script to
set the internal flag to true.

Response:
def set(self):
        """Set the internal flag to true.

        All threads waiting for the flag to become true are awakened. Threads
        that call wait() once the flag is true will not block at all.

        """
        with self.__cond:
            self.__flag = True
            self.__cond.notify_all()


Instruction:
Write a Python 3 script to
block until the internal flag is set to True or until timeout occurs.

Response:
def wait(self, timeout=None):
        """Block until the internal flag is true.

        If the internal flag is true on entry, return immediately. Otherwise,
        block until another thread calls set() to set the flag to true, or until
        the optional timeout occurs.

        When the timeout argument is present and not None, it should be a
        floating point number specifying a timeout for the operation in seconds
        (or fractions thereof).

        This method returns the internal flag on exit, so it will always return
        True except if a timeout is given and the operation times out.

        """
        with self.__cond:
            if not self.__flag:
                self.__cond.wait(timeout)
            return self.__flag


Instruction:
Make a summary of the following Python 3 code
def start(self):
        if not self.__initialized:
            raise RuntimeError("thread.__init__() not called")
        if self.__started.is_set():
            raise RuntimeError("threads can only be started once")
        if __debug__:
            self._note("%s.start(): starting thread", self)
        with _active_limbo_lock:
            _limbo[self] = self
        try:
            _start_new_thread(self.__bootstrap, ())
        except Exception:
            with _active_limbo_lock:
                del _limbo[self]
            raise
        self.__started.wait()

Response: Start the thread s activity.


Instruction:
Here you have a function in Python 3, explain what it does
def run(self):
        try:
            if self.__target:
                self.__target(*self.__args, **self.__kwargs)
        finally:
            # Avoid a refcycle if the thread is running a function with
            # an argument that has a member that points to the thread.
            del self.__target, self.__args, self.__kwargs

Response: Method representing the thread s activity.


Instruction:
Can you tell what is the following Python 3 function doing
def join(self, timeout=None):
        if not self.__initialized:
            raise RuntimeError("Thread.__init__() not called")
        if not self.__started.is_set():
            raise RuntimeError("cannot join thread before it is started")
        if self is current_thread():
            raise RuntimeError("cannot join current thread")

        if __debug__:
            if not self.__stopped:
                self._note("%s.join(): waiting until thread stops", self)
        self.__block.acquire()
        try:
            if timeout is None:
                while not self.__stopped:
                    self.__block.wait()
                if __debug__:
                    self._note("%s.join(): thread stopped", self)
            else:
                deadline = _time() + timeout
                while not self.__stopped:
                    delay = deadline - _time()
                    if delay <= 0:
                        if __debug__:
                            self._note("%s.join(): timed out", self)
                        break
                    self.__block.wait(delay)
                else:
                    if __debug__:
                        self._note("%s.join(): thread stopped", self)
        finally:
            self.__block.release()

Response: Wait until the thread terminates.


Instruction:
Can you implement a function in Python 3 that
debugs helper to print the ABC registry.

Response:
def _dump_registry(cls, file=None):
        """Debug helper to print the ABC registry."""
        print >> file, "Class: %s.%s" % (cls.__module__, cls.__name__)
        print >> file, "Inv.counter: %s" % ABCMeta._abc_invalidation_counter
        for name in sorted(cls.__dict__.keys()):
            if name.startswith("_abc_"):
                value = getattr(cls, name)
                print >> file, "%s: %r" % (name, value)


Instruction:
Can you generate the documentation for the following Python 3 function
def b2a_qp(data, quotetabs=False, istext=True, header=False):
    MAXLINESIZE = 76

    # See if this string is using CRLF line ends
    lf = data.find('\n')
    crlf = lf > 0 and data[lf-1] == '\r'

    inp = 0
    linelen = 0
    odata = []
    while inp < len(data):
        c = data[inp]
        if (c > '~' or
            c == '=' or
            (header and c == '_') or
            (c == '.' and linelen == 0 and (inp+1 == len(data) or
                                            data[inp+1] == '\n' or
                                            data[inp+1] == '\r')) or
            (not istext and (c == '\r' or c == '\n')) or
            ((c == '\t' or c == ' ') and (inp + 1 == len(data))) or
            (c <= ' ' and c != '\r' and c != '\n' and
             (quotetabs or (not quotetabs and (c != '\t' and c != ' '))))):
            linelen += 3
            if linelen >= MAXLINESIZE:
                odata.append('=')
                if crlf: odata.append('\r')
                odata.append('\n')
                linelen = 3
            odata.append('=' + two_hex_digits(ord(c)))
            inp += 1
        else:
            if (istext and
                (c == '\n' or (inp+1 < len(data) and c == '\r' and
                               data[inp+1] == '\n'))):
                linelen = 0
                # Protect against whitespace on end of line
                if (len(odata) > 0 and
                    (odata[-1] == ' ' or odata[-1] == '\t')):
                    ch = ord(odata[-1])
                    odata[-1] = '='
                    odata.append(two_hex_digits(ch))

                if crlf: odata.append('\r')
                odata.append('\n')
                if c == '\r':
                    inp += 2
                else:
                    inp += 1
            else:
                if (inp + 1 < len(data) and
                    data[inp+1] != '\n' and
                    (linelen + 1) >= MAXLINESIZE):
                    odata.append('=')
                    if crlf: odata.append('\r')
                    odata.append('\n')
                    linelen = 0

                linelen += 1
                if header and c == ' ':
                    c = '_'
                odata.append(c)
                inp += 1
    return ''.join(odata)

Response: Convert a string of ISO - 8601 to a QP string.


Instruction:
Given the following Python 3 function, write the documentation
def rlecode_hqx(s):
    if not s:
        return ''
    result = []
    prev = s[0]
    count = 1
    # Add a dummy character to get the loop to go one extra round.
    # The dummy must be different from the last character of s.
    # In the same step we remove the first character, which has
    # already been stored in prev.
    if s[-1] == '!':
        s = s[1:] + '?'
    else:
        s = s[1:] + '!'

    for c in s:
        if c == prev and count < 255:
            count += 1
        else:
            if count == 1:
                if prev != '\x90':
                    result.append(prev)
                else:
                    result += ['\x90', '\x00']
            elif count < 4:
                if prev != '\x90':
                    result += [prev] * count
                else:
                    result += ['\x90', '\x00'] * count
            else:
                if prev != '\x90':
                    result += [prev, '\x90', chr(count)]
                else:
                    result += ['\x90', '\x00', '\x90', chr(count)]
            count = 1
            prev = c

    return ''.join(result)

Response: This function is used to decode a string in CPython s format.


Instruction:
How would you explain what the following Python 3 function does
def _match_abbrev(s, wordmap):
    # Is there an exact match?
    if s in wordmap:
        return s
    else:
        # Isolate all words with s as a prefix.
        possibilities = [word for word in wordmap.keys()
                         if word.startswith(s)]
        # No exact match, so there had better be just one possibility.
        if len(possibilities) == 1:
            return possibilities[0]
        elif not possibilities:
            raise BadOptionError(s)
        else:
            # More than one possible completion: ambiguous prefix.
            possibilities.sort()
            raise AmbiguousOptionError(s, possibilities)

Response: Match an option abbreviation.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def _format_text(self, text):
        text_width = max(self.width - self.current_indent, 11)
        indent = " "*self.current_indent
        return textwrap.fill(text,
                             text_width,
                             initial_indent=indent,
                             subsequent_indent=indent)

Response: Format a text block of free - form text for inclusion in the current indentation level.


Instruction:
Write a Python 3 script to
return a comma - separated list of option strings & metavariables.

Response:
def format_option_strings(self, option):
        """Return a comma-separated list of option strings & metavariables."""
        if option.takes_value():
            metavar = option.metavar or option.dest.upper()
            short_opts = [self._short_opt_fmt % (sopt, metavar)
                          for sopt in option._short_opts]
            long_opts = [self._long_opt_fmt % (lopt, metavar)
                         for lopt in option._long_opts]
        else:
            short_opts = option._short_opts
            long_opts = option._long_opts

        if self.short_first:
            opts = short_opts + long_opts
        else:
            opts = long_opts + short_opts

        return ", ".join(opts)


Instruction:
Create a Python 3 function for
updating the option values from an arbitrary dictionary but only use keys from dict that already have a corresponding attribute COOKIEID in self.

Response:
def _update_careful(self, dict):
        """
        Update the option values from an arbitrary dictionary, but only
        use keys from dict that already have a corresponding attribute
        in self.  Any keys in dict without a corresponding attribute
        are silently ignored.
        """
        for attr in dir(self):
            if attr in dict:
                dval = dict[attr]
                if dval is not None:
                    setattr(self, attr, dval)


Instruction:
Given the following Python 3 function, write the documentation
def destroy(self):
        OptionContainer.destroy(self)
        for group in self.option_groups:
            group.destroy()
        del self.option_list
        del self.option_groups
        del self.formatter

Response: Destroys the option container.


Instruction:
Explain what the following Python 3 code does
def parse_args(self, args=None, values=None):
        rargs = self._get_args(args)
        if values is None:
            values = self.get_default_values()

        # Store the halves of the argument list as attributes for the
        # convenience of callbacks:
        #   rargs
        #     the rest of the command-line (the "r" stands for
        #     "remaining" or "right-hand")
        #   largs
        #     the leftover arguments -- ie. what's left after removing
        #     options and their arguments (the "l" stands for "leftover"
        #     or "left-hand")
        self.rargs = rargs
        self.largs = largs = []
        self.values = values

        try:
            stop = self._process_args(largs, rargs, values)
        except (BadOptionError, OptionValueError), err:
            self.error(str(err))

        args = largs + rargs
        return self.check_values(values, args)

Response: Parse the command - line options and return a list of values and the list of arguments.


Instruction:
Can you generate the documentation for the following Python 3 function
def print_help(self, file=None):
        if file is None:
            file = sys.stdout
        encoding = self._get_encoding(file)
        # file.write(self.format_help().encode(encoding, "replace"))
        file.write(self.format_help())

Response:
Print an extended help message listing all options and any
        help text provided with them to file.


Instruction:
Can you implement a function in Python 3 that
inserts item x into list a and keep it sorted assuming a is sorted.

Response:
def insort_right(a, x, lo=0, hi=None):
    """Insert item x in list a, and keep it sorted assuming a is sorted.

    If x is already in a, insert it to the right of the rightmost x.

    Optional args lo (default 0) and hi (default len(a)) bound the
    slice of a to be searched.
    """

    if lo < 0:
        raise ValueError('lo must be non-negative')
    if hi is None:
        hi = len(a)
    while lo < hi:
        mid = (lo+hi)//2
        if x < a[mid]: hi = mid
        else: lo = mid+1
    a.insert(lo, x)


Instruction:
Can you implement a function in Python 3 that
returns the index where to insert item x in list a assuming a is sorted.

Response:
def bisect_right(a, x, lo=0, hi=None):
    """Return the index where to insert item x in list a, assuming a is sorted.

    The return value i is such that all e in a[:i] have e <= x, and all e in
    a[i:] have e > x.  So if x already appears in the list, a.insert(x) will
    insert just after the rightmost x already there.

    Optional args lo (default 0) and hi (default len(a)) bound the
    slice of a to be searched.
    """

    if lo < 0:
        raise ValueError('lo must be non-negative')
    if hi is None:
        hi = len(a)
    while lo < hi:
        mid = (lo+hi)//2
        if x < a[mid]: hi = mid
        else: lo = mid+1
    return lo


Instruction:
Can you implement a function in Python 3 that
returns the index where to insert item x in list a assuming a is sorted.

Response:
def bisect_left(a, x, lo=0, hi=None):
    """Return the index where to insert item x in list a, assuming a is sorted.

    The return value i is such that all e in a[:i] have e < x, and all e in
    a[i:] have e >= x.  So if x already appears in the list, a.insert(x) will
    insert just before the leftmost x already there.

    Optional args lo (default 0) and hi (default len(a)) bound the
    slice of a to be searched.
    """

    if lo < 0:
        raise ValueError('lo must be non-negative')
    if hi is None:
        hi = len(a)
    while lo < hi:
        mid = (lo+hi)//2
        if a[mid] < x: lo = mid+1
        else: hi = mid
    return lo


Instruction:
Implement a function in Python 3 to
lock a mutex call the function with supplied argument when it is acquired.

Response:
def lock(self, function, argument):
        """Lock a mutex, call the function with supplied argument
        when it is acquired.  If the mutex is already locked, place
        function and argument in the queue."""
        if self.testandset():
            function(argument)
        else:
            self.queue.append((function, argument))


Instruction:
Implement a function in Python 3 to
unlock a mutex. If the queue is not empty, call the next function with its argument.

Response:
def unlock(self):
        """Unlock a mutex.  If the queue is not empty, call the next
        function with its argument."""
        if self.queue:
            function, argument = self.queue.popleft()
            function(argument)
        else:
            self.locked = False


Instruction:
Explain what the following Python 3 code does
def clear(self):
        'od.clear() -> None.  Remove all items from od.'
        root = self.__root
        root[:] = [root, root, None]
        self.__map.clear()
        dict.clear(self)

Response: Remove all items from od.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def popitem(self, last=True):
        '''od.popitem() -> (k, v), return and remove a (key, value) pair.
        Pairs are returned in LIFO order if last is true or FIFO order if false.

        '''
        if not self:
            raise KeyError('dictionary is empty')
        key = next(reversed(self) if last else iter(self))
        value = self.pop(key)
        return key, value

Response: od. popitem - Remove and return a key value pair. last - boolean indicates whether the key is last or not.


Instruction:
Can you tell what is the following Python 3 function doing
def update(*args, **kwds):
        '''Like dict.update() but add counts instead of replacing them.

        Source can be an iterable, a dictionary, or another Counter instance.

        >>> c = Counter('which')
        >>> c.update('witch')           # add elements from another iterable
        >>> d = Counter('watch')
        >>> c.update(d)                 # add elements from another counter
        >>> c['h']                      # four 'h' in which, witch, and watch
        4

        '''
        # The regular dict.update() operation makes no sense here because the
        # replace behavior results in the some of original untouched counts
        # being mixed-in with all of the other counts for a mismash that
        # doesn't have a straight-forward interpretation in most counting
        # contexts.  Instead, we implement straight-addition.  Both the inputs
        # and outputs are allowed to contain zero and negative counts.

        if not args:
            raise TypeError("descriptor 'update' of 'Counter' object "
                            "needs an argument")
        self = args[0]
        args = args[1:]
        if len(args) > 1:
            raise TypeError('expected at most 1 arguments, got %d' % len(args))
        iterable = args[0] if args else None
        if iterable is not None:
            if isinstance(iterable, Mapping):
                if self:
                    self_get = self.get
                    for elem, count in iterable.iteritems():
                        self[elem] = self_get(elem, 0) + count
                else:
                    super(Counter, self).update(iterable) # fast path when counter is empty
            else:
                self_get = self.get
                for elem in iterable:
                    self[elem] = self_get(elem, 0) + 1
        if kwds:
            self.update(kwds)

Response: Like dict. update but add counts instead of replacing them.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def subtract(*args, **kwds):
        '''Like dict.update() but subtracts counts instead of replacing them.
        Counts can be reduced below zero.  Both the inputs and outputs are
        allowed to contain zero and negative counts.

        Source can be an iterable, a dictionary, or another Counter instance.

        >>> c = Counter('which')
        >>> c.subtract('witch')             # subtract elements from another iterable
        >>> c.subtract(Counter('watch'))    # subtract elements from another counter
        >>> c['h']                          # 2 in which, minus 1 in witch, minus 1 in watch
        0
        >>> c['w']                          # 1 in which, minus 1 in witch, minus 1 in watch
        -1

        '''
        if not args:
            raise TypeError("descriptor 'subtract' of 'Counter' object "
                            "needs an argument")
        self = args[0]
        args = args[1:]
        if len(args) > 1:
            raise TypeError('expected at most 1 arguments, got %d' % len(args))
        iterable = args[0] if args else None
        if iterable is not None:
            self_get = self.get
            if isinstance(iterable, Mapping):
                for elem, count in iterable.items():
                    self[elem] = self_get(elem, 0) - count
            else:
                for elem in iterable:
                    self[elem] = self_get(elem, 0) - 1
        if kwds:
            self.subtract(kwds)

Response: Like dict. update but subtracts counts instead of replacing them.


Instruction:
Given the following Python 3 function, write the documentation
def digest(self):

    A = self.A
    B = self.B
    C = self.C
    D = self.D
    input = [] + self.input
    count = [] + self.count

    index = (self.count[0] >> 3) & 0x3f

    if index < 56:
      padLen = 56 - index
    else:
      padLen = 120 - index

    padding = [b'\200'] + [b'\000'] * 63
    self.update(padding[:padLen])

    # Append length (before padding).
    bits = _bytelist2long(self.input[:56]) + count

    self._transform(bits)

    # Store state in digest.
    digest = struct.pack("<IIII", self.A, self.B, self.C, self.D)

    self.A = A
    self.B = B
    self.C = C
    self.D = D
    self.input = input
    self.count = count

    return digest

Response: Terminate the message - digest computation and return digest.


Instruction:
Create a Python 3 function for
returning a copy of the md5 object.

Response:
def copy(self):
    """Return a clone object.

    Return a copy ('clone') of the md5 object. This can be used
    to efficiently compute the digests of strings that share
    a common initial substring.
    """
    if 0:  # set this to 1 to make the flow space crash
      return copy.deepcopy(self)
    clone = self.__class__()
    clone.length = self.length
    clone.count = [] + self.count[:]
    clone.input = [] + self.input
    clone.A = self.A
    clone.B = self.B
    clone.C = self.C
    clone.D = self.D
    return clone


Instruction:
Can you tell what is the following Python 3 function doing
def compile(pattern, flags, code, groups=0, groupindex={}, indexgroup=[None]):
    return SRE_Pattern(pattern, flags, code, groups, groupindex, indexgroup)

Response: Compiles a pattern descriptor to a SRE_Pattern object.


Instruction:
Explain what the following Python 3 code does
def search(self, string, pos=0, endpos=sys.maxint):
        state = _State(string, pos, endpos, self.flags)
        if state.search(self._code):
            return SRE_Match(self, state)
        else:
            return None

Response:
Search through string looking for a location where this regular
        expression produces a match and return a corresponding MatchObject
        instance. Return None if no match is found. Return None if no match is found.


Instruction:
Create a Python 3 function to
return a list of all non - overlapping matches of pattern in string.

Response:
def findall(self, string, pos=0, endpos=sys.maxint):
        """Return a list of all non-overlapping matches of pattern in string."""
        matchlist = []
        state = _State(string, pos, endpos, self.flags)
        while state.start <= state.end:
            state.reset()
            state.string_position = state.start
            if not state.search(self._code):
                break
            match = SRE_Match(self, state)
            if self.groups == 0 or self.groups == 1:
                item = match.group(self.groups)
            else:
                item = match.groups("")
            matchlist.append(item)
            if state.string_position == state.start:
                state.start += 1
            else:
                state.start = state.string_position
        return matchlist


Instruction:
Write a Python 3 function that can
return the string obtained by replacing the leftmost non - overlapping occurrences of pattern in string by the replacement repl.

Response:
def sub(self, repl, string, count=0):
        """Return the string obtained by replacing the leftmost non-overlapping
        occurrences of pattern in string by the replacement repl."""
        return self._subx(repl, string, count, False)


Instruction:
Implement a Python 3 function for
returning the tuple ( new_string number_of_subs_made ) found by replacing repl.

Response:
def subn(self, repl, string, count=0):
        """Return the tuple (new_string, number_of_subs_made) found by replacing
        the leftmost non-overlapping occurrences of pattern with the replacement
        repl."""
        return self._subx(repl, string, count, True)


Instruction:
Can you generate a brief explanation for the following Python 3 code
def split(self, string, maxsplit=0):
        splitlist = []
        state = _State(string, 0, sys.maxint, self.flags)
        n = 0
        last = state.start
        while not maxsplit or n < maxsplit:
            state.reset()
            state.string_position = state.start
            if not state.search(self._code):
                break
            if state.start == state.string_position: # zero-width match
                if last == state.end:                # or end of string
                    break
                state.start += 1
                continue
            splitlist.append(string[last:state.start])
            # add groups (if any)
            if self.groups:
                match = SRE_Match(self, state)
                # TODO: Use .extend once it is implemented.
                # splitlist.extend(list(match.groups(None)))
                splitlist += (list(match.groups(None)))
            n += 1
            last = state.start = state.string_position
        splitlist.append(string[last:state.end])
        return splitlist

Response: Split string by the occurrences of pattern.


Instruction:
Create a Python 3 function to
return a list of all non - overlapping matches of pattern in string.

Response:
def finditer(self, string, pos=0, endpos=sys.maxint):
        """Return a list of all non-overlapping matches of pattern in string."""
        scanner = self.scanner(string, pos, endpos)
        return iter(scanner.search, None)


Instruction:
Can you generate the documentation for the following Python 3 function
def _create_regs(self, state):
        regs = [(state.start, state.string_position)]
        for group in range(self.re.groups):
            mark_index = 2 * group
            if mark_index + 1 < len(state.marks) \
                                    and state.marks[mark_index] is not None \
                                    and state.marks[mark_index + 1] is not None:
                regs.append((state.marks[mark_index], state.marks[mark_index + 1]))
            else:
                regs.append((-1, -1))
        return tuple(regs)

Response: Creates a tuple of index pairs representing matched groups.


Instruction:
Can you write a function in Python 3 where it
returns a tuple containing all the subgroups of the match. The default argument is used for groups that did not participate in the the match.

Response:
def groups(self, default=None):
        """Returns a tuple containing all the subgroups of the match. The
        default argument is used for groups that did not participate in the
        match (defaults to None)."""
        groups = []
        for indices in self.regs[1:]:
            if indices[0] >= 0:
                groups.append(self.string[indices[0]:indices[1]])
            else:
                groups.append(default)
        return tuple(groups)


Instruction:
Write a Python 3 script to
return a dictionary containing all the named subgroups of the match.

Response:
def groupdict(self, default=None):
        """Return a dictionary containing all the named subgroups of the match.
        The default argument is used for groups that did not participate in the
        match (defaults to None)."""
        groupdict = {}
        for key, value in self.re.groupindex.items():
            groupdict[key] = self._get_slice(value, default)
        return groupdict


Instruction:
Implement a Python 3 function for
returning one or more subgroups of the match. Each argument is either a group index or a group name.

Response:
def group(self, *args):
        """Returns one or more subgroups of the match. Each argument is either a
        group index or a group name."""
        if len(args) == 0:
            args = (0,)
        grouplist = []
        for group in args:
            grouplist.append(self._get_slice(self._get_index(group), None))
        if len(grouplist) == 1:
            return grouplist[0]
        else:
            return tuple(grouplist)


Instruction:
Can you generate the documentation for the following Python 3 function
def fast_search(self, pattern_codes):
        # pattern starts with a known prefix
        # <5=length> <6=skip> <7=prefix data> <overlap data>
        flags = pattern_codes[2]
        prefix_len = pattern_codes[5]
        prefix_skip = pattern_codes[6] # don't really know what this is good for
        prefix = pattern_codes[7:7 + prefix_len]
        overlap = pattern_codes[7 + prefix_len - 1:pattern_codes[1] + 1]
        pattern_codes = pattern_codes[pattern_codes[1] + 1:]
        i = 0
        string_position = self.string_position
        while string_position < self.end:
            while True:
                if ord(self.string[string_position]) != prefix[i]:
                    if i == 0:
                        break
                    else:
                        i = overlap[i]
                else:
                    i += 1
                    if i == prefix_len:
                        # found a potential match
                        self.start = string_position + 1 - prefix_len
                        self.string_position = string_position + 1 \
                                                     - prefix_len + prefix_skip
                        if flags & SRE_INFO_LITERAL:
                            return True # matched all of pure literal pattern
                        if self.match(pattern_codes[2 * prefix_skip:]):
                            return True
                        i = overlap[i]
                    break
            string_position += 1
        return False

Response:
Searches for a pattern in a string as fast as possible using information from
        an optimization info block.


Instruction:
Explain what the following Python 3 code does
def push_new_context(self, pattern_offset):
        child_context = _MatchContext(self.state,
            self.pattern_codes[self.code_position + pattern_offset:])
        self.state.context_stack.append(child_context)
        return child_context

Response: Creates a new child context and pushes it on the stack.


Instruction:
Implement a function in Python 3 to
return True if the current context matches False if it doesn t and None if it doesn t match.

Response:
def match(self, context):
        """Returns True if the current context matches, False if it doesn't and
        None if matching is not finished, ie must be resumed after child
        contexts have been matched."""
        while context.remaining_codes() > 0 and context.has_matched is None:
            opcode = context.peek_code()
            if not self.dispatch(opcode, context):
                return None
        if context.has_matched is None:
            context.has_matched = False
        return context.has_matched


Instruction:
Can you tell what is the following Python 3 function doing
def dispatch(self, opcode, context):
        if id(context) in self.executing_contexts:
            generator = self.executing_contexts[id(context)]
            del self.executing_contexts[id(context)]
            has_finished = generator.next()
        else:
            method = self.DISPATCH_TABLE.get(opcode, _OpcodeDispatcher.unknown)
            has_finished = method(self, context)
            if hasattr(has_finished, "next"): # avoid using the types module
                generator = has_finished
                has_finished = generator.next()
        if not has_finished:
            self.executing_contexts[id(context)] = generator
        return has_finished

Response:
Dispatches a given opcode on a given context. Returns True if the context
            is done matching False otherwise.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def check_charset(self, ctx, char):
        self.set_dispatcher.reset(char)
        save_position = ctx.code_position
        result = None
        while result is None:
            result = self.set_dispatcher.dispatch(ctx.peek_code(), ctx)
        ctx.code_position = save_position
        return result

Response: Checks whether a character matches the set of arbitrary length.


Instruction:
Given the following Python 3 function, write the documentation
def count_repetitions(self, ctx, maxcount):
        count = 0
        real_maxcount = ctx.state.end - ctx.string_position
        if maxcount < real_maxcount and maxcount != MAXREPEAT:
            real_maxcount = maxcount
        # XXX could special case every single character pattern here, as in C.
        # This is a general solution, a bit hackisch, but works and should be
        # efficient.
        code_position = ctx.code_position
        string_position = ctx.string_position
        ctx.skip_code(4)
        reset_position = ctx.code_position
        while count < real_maxcount:
            # this works because the single character pattern is followed by
            # a success opcode
            ctx.code_position = reset_position
            self.dispatch(ctx.peek_code(), ctx)
            if ctx.has_matched is False: # could be None as well
                break
            count += 1
        ctx.has_matched = None
        ctx.code_position = code_position
        ctx.string_position = string_position
        return count

Response: Returns the number of repetitions of a single item starting from the current string position.


Instruction:
Explain what the following Python 3 code does
def extract(s):
    res = decoder.match(s)
    if res is None: raise NotANumber, s
    sign, intpart, fraction, exppart = res.group(1,2,3,4)
    if sign == '+': sign = ''
    if fraction: fraction = fraction[1:]
    if exppart: expo = int(exppart[1:])
    else: expo = 0
    return sign, intpart, fraction, expo

Response: Extracts a non - zero or non - negative integer from a non - zero or non - negative integer.


Instruction:
Can you generate the documentation for the following Python 3 function
def unexpo(intpart, fraction, expo):
    if expo > 0: # Move the point left
        f = len(fraction)
        intpart, fraction = intpart + fraction[:expo], fraction[expo:]
        if expo > f:
            intpart = intpart + '0'*(expo-f)
    elif expo < 0: # Move the point right
        i = len(intpart)
        intpart, fraction = intpart[:expo], intpart[expo:] + fraction
        if expo < -i:
            fraction = '0'*(-expo-i) + fraction
    return intpart, fraction

Response: Remove the exponent by changing intpart and fraction.


Instruction:
Write a Python 3 script for
rounding or extend the fraction to size digs.

Response:
def roundfrac(intpart, fraction, digs):
    """Round or extend the fraction to size digs."""
    f = len(fraction)
    if f <= digs:
        return intpart, fraction + '0'*(digs-f)
    i = len(intpart)
    if i+digs < 0:
        return '0'*-digs, ''
    total = intpart + fraction
    nextdigit = total[i+digs]
    if nextdigit >= '5': # Hard case: increment last digit, may have carry!
        n = i + digs - 1
        while n >= 0:
            if total[n] != '9': break
            n = n-1
        else:
            total = '0' + total
            i = i+1
            n = 0
        total = total[:n] + chr(ord(total[n]) + 1) + '0'*(len(total)-n-1)
        intpart, fraction = total[:i], total[i:]
    if digs >= 0:
        return intpart, fraction[:digs]
    else:
        return intpart[:digs] + '0'*-digs, ''


Instruction:
How would you implement a function in Python 3 that
formats x as - ddd. ddd with digs digits after the point and at least one digit before the point .

Response:
def fix(x, digs):
    """Format x as [-]ddd.ddd with 'digs' digits after the point
    and at least one digit before.
    If digs <= 0, the point is suppressed."""
    if type(x) != type(''): x = repr(x)
    try:
        sign, intpart, fraction, expo = extract(x)
    except NotANumber:
        return x
    intpart, fraction = unexpo(intpart, fraction, expo)
    intpart, fraction = roundfrac(intpart, fraction, digs)
    while intpart and intpart[0] == '0': intpart = intpart[1:]
    if intpart == '': intpart = '0'
    if digs > 0: return sign + intpart + '.' + fraction
    else: return sign + intpart


Instruction:
Implement a function in Python 3 to
format x as - d. dddE [+- ] ddd with digs digits after the point and exactly one digit before the point .

Response:
def sci(x, digs):
    """Format x as [-]d.dddE[+-]ddd with 'digs' digits after the point
    and exactly one digit before.
    If digs is <= 0, one digit is kept and the point is suppressed."""
    if type(x) != type(''): x = repr(x)
    sign, intpart, fraction, expo = extract(x)
    if not intpart:
        while fraction and fraction[0] == '0':
            fraction = fraction[1:]
            expo = expo - 1
        if fraction:
            intpart, fraction = fraction[0], fraction[1:]
            expo = expo - 1
        else:
            intpart = '0'
    else:
        expo = expo + len(intpart) - 1
        intpart, fraction = intpart[0], intpart[1:] + fraction
    digs = max(0, digs)
    intpart, fraction = roundfrac(intpart, fraction, digs)
    if len(intpart) > 1:
        intpart, fraction, expo = \
            intpart[0], intpart[1:] + fraction[:-1], \
            expo + len(intpart) - 1
    s = sign + intpart
    if digs > 0: s = s + '.' + fraction
    e = repr(abs(expo))
    e = '0'*(3-len(e)) + e
    if expo < 0: e = '-' + e
    else: e = '+' + e
    return s + 'e' + e


Instruction:
Can you tell what is the following Python 3 function doing
def getrandbits(self, k):
    if k <= 0:
      raise ValueError('number of bits must be greater than zero')
    if k != int(k):
      raise TypeError('number of bits should be an integer')
    numbytes = (k + 7) // 8                       # bits / 8 and rounded up
    x = _int_from_bytes(_gorandom(numbytes))
    return x >> (numbytes * 8 - k)

Response: Generates an int with k random bits.


Instruction:
Given the following Python 3 function, write the documentation
def _randbelow(self, n):
    # TODO
    # change once int.bit_length is implemented.
    # k = n.bit_length()
    k = _int_bit_length(n)
    r = self.getrandbits(k)
    while r >= n:
      r = self.getrandbits(k)
    return r

Response: Return a random int in the range [ 0 n ).


Instruction:
Can you generate a brief explanation for the following Python 3 code
def getopt(args, shortopts, longopts = []):

    opts = []
    if type(longopts) == type(""):
        longopts = [longopts]
    else:
        longopts = list(longopts)
    while args and args[0].startswith('-') and args[0] != '-':
        if args[0] == '--':
            args = args[1:]
            break
        if args[0].startswith('--'):
            opts, args = do_longs(opts, args[0][2:], longopts, args[1:])
        else:
            opts, args = do_shorts(opts, args[0][1:], shortopts, args[1:])

    return opts, args

Response: Parses command line options and parameter list.


Instruction:
Can you tell what is the following Python 3 function doing
def gnu_getopt(args, shortopts, longopts = []):

    opts = []
    prog_args = []
    if isinstance(longopts, str):
        longopts = [longopts]
    else:
        longopts = list(longopts)

    # Allow options after non-option arguments?
    if shortopts.startswith('+'):
        shortopts = shortopts[1:]
        all_options_first = True
    elif os.environ.get("POSIXLY_CORRECT"):
        all_options_first = True
    else:
        all_options_first = False

    while args:
        if args[0] == '--':
            prog_args += args[1:]
            break

        if args[0][:2] == '--':
            opts, args = do_longs(opts, args[0][2:], longopts, args[1:])
        elif args[0][:1] == '-' and args[0] != '-':
            opts, args = do_shorts(opts, args[0][1:], shortopts, args[1:])
        else:
            if all_options_first:
                prog_args += args
                break
            else:
                prog_args.append(args[0])
                args = args[1:]

    return opts, prog_args

Response: This function is used by GNU to parse GNU command line options.


Instruction:
Can you generate the documentation for the following Python 3 function
def filter(names, pat):
    import os
    # import posixpath
    result=[]
    # pat=os.path.normcase(pat)
    try:
        re_pat = _cache[pat]
    except KeyError:
        res = translate(pat)
        if len(_cache) >= _MAXCACHE:
            # _cache.clear()
            globals()['_cache'] = {}
        _cache[pat] = re_pat = re.compile(res)
    match = re_pat.match
    # if os.path is posixpath:
    if 1:
        # normcase on posix is NOP. Optimize it away from the loop.
        for name in names:
            if match(name):
                result.append(name)
    else:
        for name in names:
            if match(os.path.normcase(name)):
                result.append(name)
    return result

Response: Return the subset of the list NAMES that match PAT


Instruction:
Explain what the following Python 3 code does
def fnmatchcase(name, pat):

    try:
        re_pat = _cache[pat]
    except KeyError:
        res = translate(pat)
        if len(_cache) >= _MAXCACHE:
            # _cache.clear()
            globals()['_cache'] = {}
        _cache[pat] = re_pat = re.compile(res)
    return re_pat.match(name) is not None

Response: Test whether FILENAME matches PATTERN including case.


Instruction:
Can you tell what is the following Python 3 function doing
def translate(pat):

    i, n = 0, len(pat)
    res = ''
    while i < n:
        c = pat[i]
        i = i+1
        if c == '*':
            res = res + '.*'
        elif c == '?':
            res = res + '.'
        elif c == '[':
            j = i
            if j < n and pat[j] == '!':
                j = j+1
            if j < n and pat[j] == ']':
                j = j+1
            while j < n and pat[j] != ']':
                j = j+1
            if j >= n:
                res = res + '\\['
            else:
                stuff = pat[i:j].replace('\\','\\\\')
                i = j+1
                if stuff[0] == '!':
                    stuff = '^' + stuff[1:]
                elif stuff[0] == '^':
                    stuff = '\\' + stuff
                res = '%s[%s]' % (res, stuff)
        else:
            res = res + re.escape(c)
    return res + '\Z(?ms)'

Response: Translate a shell PATTERN to a regular expression.


Instruction:
Can you tell what is the following Python 3 function doing
def task_done(self):
        self.all_tasks_done.acquire()
        try:
            unfinished = self.unfinished_tasks - 1
            if unfinished <= 0:
                if unfinished < 0:
                    raise ValueError('task_done() called too many times')
                self.all_tasks_done.notify_all()
            self.unfinished_tasks = unfinished
        finally:
            self.all_tasks_done.release()

Response: Indicate that a task is complete.


Instruction:
Write a Python 3 script to
return the approximate size of the queue ( not reliable.

Response:
def qsize(self):
        """Return the approximate size of the queue (not reliable!)."""
        self.mutex.acquire()
        n = self._qsize()
        self.mutex.release()
        return n


Instruction:
How would you implement a function in Python 3 that
returns True if the queue is empty False otherwise.

Response:
def empty(self):
        """Return True if the queue is empty, False otherwise (not reliable!)."""
        self.mutex.acquire()
        n = not self._qsize()
        self.mutex.release()
        return n


Instruction:
Can you tell what is the following Python 3 function doing
def full(self):
        self.mutex.acquire()
        n = 0 < self.maxsize == self._qsize()
        self.mutex.release()
        return n

Response: Return True if the queue is full False otherwise.


Instruction:
Create a Python 3 function for
putting an item into the queue.

Response:
def put(self, item, block=True, timeout=None):
        """Put an item into the queue.

        If optional args 'block' is true and 'timeout' is None (the default),
        block if necessary until a free slot is available. If 'timeout' is
        a non-negative number, it blocks at most 'timeout' seconds and raises
        the Full exception if no free slot was available within that time.
        Otherwise ('block' is false), put an item on the queue if a free slot
        is immediately available, else raise the Full exception ('timeout'
        is ignored in that case).
        """
        self.not_full.acquire()
        try:
            if self.maxsize > 0:
                if not block:
                    if self._qsize() == self.maxsize:
                        raise Full
                elif timeout is None:
                    while self._qsize() == self.maxsize:
                        self.not_full.wait()
                elif timeout < 0:
                    raise ValueError("'timeout' must be a non-negative number")
                else:
                    endtime = _time() + timeout
                    while self._qsize() == self.maxsize:
                        remaining = endtime - _time()
                        if remaining <= 0.0:
                            raise Full
                        self.not_full.wait(remaining)
            self._put(item)
            self.unfinished_tasks += 1
            self.not_empty.notify()
        finally:
            self.not_full.release()


Instruction:
How would you explain what the following Python 3 function does
def calculate_transitive_deps(modname, script, gopath):
  deps = set()
  def calc(modname, script):
    if modname in deps:
      return
    deps.add(modname)
    for imp in collect_imports(modname, script, gopath):
      if imp.is_native:
        deps.add(imp.name)
        continue
      parts = imp.name.split('.')
      calc(imp.name, imp.script)
      if len(parts) == 1:
        continue
      # For submodules, the parent packages are also deps.
      package_dir, filename = os.path.split(imp.script)
      if filename == '__init__.py':
        package_dir = os.path.dirname(package_dir)
      for i in xrange(len(parts) - 1, 0, -1):
        modname = '.'.join(parts[:i])
        script = os.path.join(package_dir, '__init__.py')
        calc(modname, script)
        package_dir = os.path.dirname(package_dir)
  calc(modname, script)
  deps.remove(modname)
  return deps

Response: Determines all modules that script transitively depends upon.


Instruction:
Implement a Python 3 function for
processing a future import statement returning a set of flags it defines.

Response:
def _make_future_features(node):
  """Processes a future import statement, returning set of flags it defines."""
  assert isinstance(node, ast.ImportFrom)
  assert node.module == '__future__'
  features = FutureFeatures()
  for alias in node.names:
    name = alias.name
    if name in _FUTURE_FEATURES:
      if name not in _IMPLEMENTED_FUTURE_FEATURES:
        msg = 'future feature {} not yet implemented by grumpy'.format(name)
        raise util.ParseError(node, msg)
      setattr(features, name, True)
    elif name == 'braces':
      raise util.ParseError(node, 'not a chance')
    elif name not in _REDUNDANT_FUTURE_FEATURES:
      msg = 'future feature {} is not defined'.format(name)
      raise util.ParseError(node, msg)
  return features


Instruction:
Implement a function in Python 3 to
accumulate a set of flags for the compiler __future__ imports.

Response:
def parse_future_features(mod):
  """Accumulates a set of flags for the compiler __future__ imports."""
  assert isinstance(mod, ast.Module)
  found_docstring = False
  for node in mod.body:
    if isinstance(node, ast.ImportFrom):
      if node.module == '__future__':
        return node, _make_future_features(node)
      break
    elif isinstance(node, ast.Expr) and not found_docstring:
      if not isinstance(node.value, ast.Str):
        break
      found_docstring = True
    else:
      break
  return None, FutureFeatures()


Instruction:
Can you generate a brief explanation for the following Python 3 code
def contextmanager(func):
    @wraps(func)
    def helper(*args, **kwds):
        return GeneratorContextManager(func(*args, **kwds))
    return helper

Response: Decorator that returns a generator that yields all the available items in the sequence.


Instruction:
Can you create a Python 3 function that
combines multiple context managers into a single nested context manager.

Response:
def nested(*managers):
    """Combine multiple context managers into a single nested context manager.

   This function has been deprecated in favour of the multiple manager form
   of the with statement.

   The one advantage of this function over the multiple manager form of the
   with statement is that argument unpacking allows it to be
   used with a variable number of context managers as follows:

      with nested(*managers):
          do_something()

    """
    warn("With-statements now directly support multiple context managers",
         DeprecationWarning, 3)
    exits = []
    vars = []
    exc = (None, None, None)
    try:
        for mgr in managers:
            exit = mgr.__exit__
            enter = mgr.__enter__
            vars.append(enter())
            exits.append(exit)
        yield vars
    except:
        exc = sys.exc_info()
    finally:
        while exits:
            exit = exits.pop()
            try:
                if exit(*exc):
                    exc = (None, None, None)
            except:
                exc = sys.exc_info()
        if exc != (None, None, None):
            # Don't rely on sys.exc_info() still containing
            # the right information. Another exception may
            # have been raised and caught by an exit method
            raise exc[0], exc[1], exc[2]


Instruction:
Can you tell what is the following Python 3 function doing
def decode(self, s, _w=WHITESPACE.match):
        obj, end = self.raw_decode(s, idx=_w(s, 0).end())
        end = _w(s, end).end()
        if end != len(s):
            raise ValueError(errmsg("Extra data", s, end, len(s)))
        return obj

Response: Decode a string or unicode object into a Python object.


Instruction:
Can you tell what is the following Python 3 function doing
def tf_loss(self, states, internals, reward, update, reference=None):
        prediction = self.predict(states=states, internals=internals, update=update)
        return tf.nn.l2_loss(t=(prediction - reward))

Response: Returns the TensorFlow operations for calculating the L2 loss between predicted state values and actual rewards.


Instruction:
Create a Python 3 function for
returning the TensorFlow variables used by the baseline.

Response:
def get_variables(self, include_nontrainable=False):
        """
        Returns the TensorFlow variables used by the baseline.

        Returns:
            List of variables
        """
        if include_nontrainable:
            return [self.all_variables[key] for key in sorted(self.all_variables)]
        else:
            return [self.variables[key] for key in sorted(self.variables)]


Instruction:
Write a Python 3 function that can
create a baseline from a specification dict.

Response:
def from_spec(spec, kwargs=None):
        """
        Creates a baseline from a specification dict.
        """
        baseline = util.get_object(
            obj=spec,
            predefined_objects=tensorforce.core.baselines.baselines,
            kwargs=kwargs
        )
        assert isinstance(baseline, Baseline)
        return baseline


Instruction:
Make a summary of the following Python 3 code
def reset(self):
        # Send command.
        self.protocol.send({"cmd": "reset"}, self.socket)
        # Wait for response.
        response = self.protocol.recv(self.socket)
        # Extract observations.
        return self.extract_observation(response)

Response: reset the current state of the current set of items


Instruction:
Write a Python 3 function for
executing a single step in the UE4 game.

Response:
def execute(self, action):
        """
        Executes a single step in the UE4 game. This step may be comprised of one or more actual game ticks for all of
        which the same given
        action- and axis-inputs (or action number in case of discretized actions) are repeated.
        UE4 distinguishes between action-mappings, which are boolean actions (e.g. jump or dont-jump) and axis-mappings,
        which are continuous actions
        like MoveForward with values between -1.0 (run backwards) and 1.0 (run forwards), 0.0 would mean: stop.
        """
        action_mappings, axis_mappings = [], []

        # TODO: what if more than one actions are passed?

        # Discretized -> each action is an int
        if self.discretize_actions:
            # Pull record from discretized_actions, which will look like: [A, Right, SpaceBar].
            combination = self.discretized_actions[action]
            # Translate to {"axis_mappings": [('A', 1.0), (Right, 1.0)], "action_mappings": [(SpaceBar, True)]}
            for key, value in combination:
                # Action mapping (True or False).
                if isinstance(value, bool):
                    action_mappings.append((key, value))
                # Axis mapping: always use 1.0 as value as UE4 already multiplies with the correct scaling factor.
                else:
                    axis_mappings.append((key, value))
        # Non-discretized: Each action is a dict of action- and axis-mappings defined in UE4 game's input settings.
        # Re-translate Incoming action names into keyboard keys for the server.
        elif action:
            try:
                action_mappings, axis_mappings = self.translate_abstract_actions_to_keys(action)
            except KeyError as e:
                raise TensorForceError("Action- or axis-mapping with name '{}' not defined in connected UE4 game!".
                                       format(e))

        # message = {"cmd": "step", 'delta_time': 0.33,
        #     'actions': [('X', True), ('Y', False)],
        #     'axes': [('Left': 1.0), ('Up': -1.0)]
        # }
        message = dict(
            cmd="step",
            delta_time=self.delta_time,
            num_ticks=self.num_ticks,
            actions=action_mappings,
            axes=axis_mappings
        )
        self.protocol.send(message, self.socket)
        # Wait for response (blocks).
        response = self.protocol.recv(self.socket)
        r = response.pop(b"_reward", 0.0)
        is_terminal = response.pop(b"_is_terminal", False)

        obs = self.extract_observation(response)
        # Cache last observation
        self.last_observation = obs
        return obs, is_terminal, r


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

        # Solve single tuple with name and value -> should become a list (len=1) of this tuple.
        if len(abstract) >= 2 and not isinstance(abstract[1], (list, tuple)):
            abstract = list((abstract,))

        # Now go through the list and translate each axis into an actual keyboard key (or mouse event/etc..).
        actions, axes = [], []
        for a in abstract:
            # first_key = key-name (action mapping or discretized axis mapping) OR tuple (key-name, scale) (continuous
            # axis mapping)
            first_key = self.action_space_desc[a[0]]["keys"][0]
            # action mapping
            if isinstance(first_key, (bytes, str)):
                actions.append((first_key, a[1]))
            # axis mapping
            elif isinstance(first_key, tuple):
                axes.append((first_key[0], a[1] * first_key[1]))
            else:
                raise TensorForceError("action_space_desc contains unsupported type for key {}!".format(a[0]))

        return actions, axes

Response: Translate a list of tuples with some key and translated value into a list of tuples with some key and translated value.


Instruction:
How would you implement a function in Python 3 that
creates a list of discrete action(-combinations) in case we want to learn with a discrete set of actions, but only have action-combinations (maybe even continuous) available from the env. E.g. the UE4 game has the following action/axis-mappings: ```javascript { 'Fire': {'type': 'action', 'keys': ('SpaceBar',)}, 'MoveRight': {'type': 'axis', 'keys': (('Right', 1.0), ('Left', -1.0), ('A', -1.0), ('D', 1.0))}, } ``` -> this method will discretize them into the following 6 discrete actions: ```javascript [ [(Right, 0.0),(SpaceBar, False)], [(Right, 0.0),(SpaceBar, True)] [(Right, -1.0),(SpaceBar, False)], [(Right, -1.0),(SpaceBar, True)], [(Right, 1.0),(SpaceBar, False)], [(Right, 1.0),(SpaceBar, True)], ] ```

Response:
def discretize_action_space_desc(self):
        """
        Creates a list of discrete action(-combinations) in case we want to learn with a discrete set of actions,
        but only have action-combinations (maybe even continuous) available from the env.
        E.g. the UE4 game has the following action/axis-mappings:

        ```javascript
        {
        'Fire':
            {'type': 'action', 'keys': ('SpaceBar',)},
        'MoveRight':
            {'type': 'axis', 'keys': (('Right', 1.0), ('Left', -1.0), ('A', -1.0), ('D', 1.0))},
        }
        ```

        -> this method will discretize them into the following 6 discrete actions:

        ```javascript
        [
        [(Right, 0.0),(SpaceBar, False)],
        [(Right, 0.0),(SpaceBar, True)]
        [(Right, -1.0),(SpaceBar, False)],
        [(Right, -1.0),(SpaceBar, True)],
        [(Right, 1.0),(SpaceBar, False)],
        [(Right, 1.0),(SpaceBar, True)],
        ]
        ```

        """
        # Put all unique_keys lists in one list and itertools.product that list.
        unique_list = []
        for nice, record in self.action_space_desc.items():
            list_for_record = []
            if record["type"] == "axis":
                # The main key for this record (always the first one)
                head_key = record["keys"][0][0]
                # The reference value (divide by this one to get the others)
                head_value = record["keys"][0][1]
                # The zero key (idle action; axis scale=0.0)
                list_for_record.append((head_key, 0.0))
                set_ = set()
                for key_and_scale in self.action_space_desc[nice]["keys"]:
                    # Build unique lists of mappings (each axis value should only be represented once).
                    if key_and_scale[1] not in set_:
                        list_for_record.append((head_key, key_and_scale[1] / head_value))
                        set_.add(key_and_scale[1])
            else:
                # Action-mapping
                list_for_record = [(record["keys"][0], False), (record["keys"][0], True)]
            unique_list.append(list_for_record)

        def so(in_):
            # in_ is List[Tuple[str,any]] -> sort by concat'd sequence of str(any's)
            st = ""
            for i in in_:
                st += str(i[1])
            return st

        # Then sort and get the entire list of all possible sorted meaningful key-combinations.
        combinations = list(itertools.product(*unique_list))
        combinations = list(map(lambda x: sorted(list(x), key=lambda y: y[0]), combinations))
        combinations = sorted(combinations, key=so)
        # Store that list as discretized_actions.
        self.discretized_actions = combinations


Instruction:
Write a Python 3 script for
resetting the environment to its initial state.

Response:
def reset(self):
        """
        Resets the environment to its initialization state. This method needs to be called to start a
        new episode after the last episode ended.

        :return: initial state
        """
        self.level.reset()  # optional: episode=-1, seed=None
        return self.level.observations()[self.state_attribute]


Instruction:
Make a summary of the following Python 3 code
def execute(self, action):
        adjusted_action = list()
        for action_spec in self.level.action_spec():
            if action_spec['min'] == -1 and action_spec['max'] == 1:
                adjusted_action.append(action[action_spec['name']] - 1)
            else:
                adjusted_action.append(action[action_spec['name']])  # clip?
        action = np.array(adjusted_action, dtype=np.intc)

        reward = self.level.step(action=action, num_steps=self.repeat_action)
        state = self.level.observations()['RGB_INTERLACED']
        terminal = not self.level.is_running()
        return state, terminal, reward

Response: Execute the action given in the action_spec and return the next state terminal and the reward.


Instruction:
Here you have a function in Python 3, explain what it does
def tf_initialize(self, x_init, b):
        if x_init is None:
            # Initial guess is zero vector if not given.
            x_init = [tf.zeros(shape=util.shape(t)) for t in b]

        initial_args = super(ConjugateGradient, self).tf_initialize(x_init)

        # r_0 := b - A * x_0
        # c_0 := r_0
        conjugate = residual = [t - fx for t, fx in zip(b, self.fn_x(x_init))]

        # r_0^2 := r^T * r
        squared_residual = tf.add_n(inputs=[tf.reduce_sum(input_tensor=(res * res)) for res in residual])

        return initial_args + (conjugate, residual, squared_residual)

Response: This function is called by tf_step_x_init when the first iteration of the loop body is called.


Instruction:
Write a Python 3 script to
return a term that is true if another iteration should be performed.

Response:
def tf_next_step(self, x, iteration, conjugate, residual, squared_residual):
        """
        Termination condition: max number of iterations, or residual sufficiently small.

        Args:
            x: Current solution estimate $x_t$.
            iteration: Current iteration counter $t$.
            conjugate: Current conjugate $c_t$.
            residual: Current residual $r_t$.
            squared_residual: Current squared residual $r_t^2$.

        Returns:
            True if another iteration should be performed.
        """
        next_step = super(ConjugateGradient, self).tf_next_step(x, iteration, conjugate, residual, squared_residual)
        return tf.logical_and(x=next_step, y=(squared_residual >= util.epsilon))


Instruction:
Can you write a function in Python 3 where it
creates the TensorFlow operations for performing an optimization step.

Response:
def tf_step(self, time, variables, **kwargs):
        """
        Creates the TensorFlow operations for performing an optimization step.

        Args:
            time: Time tensor.
            variables: List of variables to optimize.
            **kwargs: Additional arguments passed on to the internal optimizer.

        Returns:
            List of delta tensors corresponding to the updates for each optimized variable.
        """
        deltas = self.optimizer.step(time=time, variables=variables, **kwargs)

        with tf.control_dependencies(control_inputs=deltas):
            clipped_deltas = list()
            exceeding_deltas = list()
            for delta in deltas:
                clipped_delta = tf.clip_by_value(
                    t=delta,
                    clip_value_min=-self.clipping_value,
                    clip_value_max=self.clipping_value
                )
                clipped_deltas.append(clipped_delta)
                exceeding_deltas.append(clipped_delta - delta)

        applied = self.apply_step(variables=variables, deltas=exceeding_deltas)

        with tf.control_dependencies(control_inputs=(applied,)):
            return [delta + 0.0 for delta in clipped_deltas]


Instruction:
Here you have a function in Python 3, explain what it does
def from_spec(spec, kwargs=None):
        layer = util.get_object(
            obj=spec,
            predefined_objects=tensorforce.core.networks.layers,
            kwargs=kwargs
        )
        assert isinstance(layer, Layer)
        return layer

Response: Creates a layer from a specification dict.


Instruction:
Write a Python 3 function that can
create the deltas for the action based on the given Q values.

Response:
def tf_q_delta(self, q_value, next_q_value, terminal, reward):
        """
        Creates the deltas (or advantage) of the Q values.

        :return: A list of deltas per action
        """
        for _ in range(util.rank(q_value) - 1):
            terminal = tf.expand_dims(input=terminal, axis=1)
            reward = tf.expand_dims(input=reward, axis=1)

        multiples = (1,) + util.shape(q_value)[1:]
        terminal = tf.tile(input=terminal, multiples=multiples)
        reward = tf.tile(input=reward, multiples=multiples)

        zeros = tf.zeros_like(tensor=next_q_value)
        next_q_value = tf.where(condition=terminal, x=zeros, y=(self.discount * next_q_value))

        return reward + next_q_value - q_value


Instruction:
Explain what the following Python 3 code does
def target_optimizer_arguments(self):
        variables = self.target_network.get_variables() + [
            variable for name in sorted(self.target_distributions)
            for variable in self.target_distributions[name].get_variables()
        ]
        source_variables = self.network.get_variables() + [
            variable for name in sorted(self.distributions)
            for variable in self.distributions[name].get_variables()
        ]
        arguments = dict(
            time=self.global_timestep,
            variables=variables,
            source_variables=source_variables
        )
        if self.global_model is not None:
            arguments['global_variables'] = self.global_model.target_network.get_variables() + [
                variable for name in sorted(self.global_model.target_distributions)
                for variable in self.global_model.target_distributions[name].get_variables()
            ]
        return arguments

Response: Returns the target optimizer arguments as a dict.


Instruction:
How would you implement a function in Python 3 that
creates an Environment object from a specification dict.

Response:
def from_spec(spec, kwargs):
        """
        Creates an environment from a specification dict.
        """
        env = tensorforce.util.get_object(
            obj=spec,
            predefined_objects=tensorforce.environments.environments,
            kwargs=kwargs
        )
        assert isinstance(env, Environment)
        return env


Instruction:
Can you tell what is the following Python 3 function doing
def setup(app):
    global _is_sphinx
    _is_sphinx = True
    app.add_config_value('no_underscore_emphasis', False, 'env')
    app.add_source_parser('.md', M2RParser)
    app.add_directive('mdinclude', MdInclude)

Response: When used for spinx extension.


Instruction:
Can you implement a function in Python 3 that
passes through rest role.

Response:
def output_image_link(self, m):
        """Pass through rest role."""
        return self.renderer.image_link(
            m.group('url'), m.group('target'), m.group('alt'))


Instruction:
Here you have a function in Python 3, explain what it does
def output_eol_literal_marker(self, m):
        marker = ':' if m.group(1) is None else ''
        return self.renderer.eol_literal_marker(marker)

Response: Pass through rest link.


Instruction:
How would you implement a function in Python 3 that
renders list tags like ul and ol.

Response:
def list(self, body, ordered=True):
        """Rendering list tags like ``<ul>`` and ``<ol>``.

        :param body: body contents of the list.
        :param ordered: whether this list is ordered or not.
        """
        mark = '#. ' if ordered else '* '
        lines = body.splitlines()
        for i, line in enumerate(lines):
            if line and not line.startswith(self.list_marker):
                lines[i] = ' ' * len(mark) + line
        return '\n{}\n'.format(
            '\n'.join(lines)).replace(self.list_marker, mark)


Instruction:
Write a Python 3 function for
rendering table element. Wrap header and body in it.

Response:
def table(self, header, body):
        """Rendering table element. Wrap header and body in it.

        :param header: header part of the table.
        :param body: body part of the table.
        """
        table = '\n.. list-table::\n'
        if header and not header.isspace():
            table = (table + self.indent + ':header-rows: 1\n\n' +
                     self._indent_block(header) + '\n')
        else:
            table = table + '\n'
        table = table + self._indent_block(body) + '\n\n'
        return table


Instruction:
Explain what the following Python 3 code does
def table_row(self, content):
        contents = content.splitlines()
        if not contents:
            return ''
        clist = ['* ' + contents[0]]
        if len(contents) > 1:
            for c in contents[1:]:
                clist.append('  ' + c)
        return '\n'.join(clist) + '\n'

Response: Rendering a table row. Like <tr >.


Instruction:
Can you tell what is the following Python 3 function doing
def codespan(self, text):
        if '``' not in text:
            return '\ ``{}``\ '.format(text)
        else:
            # actually, docutils split spaces in literal
            return self._raw_html(
                ''
                '{}'
                ''.format(text.replace('`', '`')))

Response: Rendering inline code text.


Instruction:
Write a Python 3 script for
rendering a given link with content and title.

Response:
def link(self, link, title, text):
        """Rendering a given link with content and title.

        :param link: href link for ``<a>`` tag.
        :param title: title content for `title` attribute.
        :param text: text content for description.
        """
        if title:
            raise NotImplementedError('sorry')
        return '\ `{text} <{target}>`_\ '.format(target=link, text=text)


Instruction:
Implement a Python 3 function for
rendering an image with title and text.

Response:
def image(self, src, title, text):
        """Rendering a image with title and text.

        :param src: source link of the image.
        :param title: title text of the image.
        :param text: alt text of the image.
        """
        # rst does not support title option
        # and I couldn't find title attribute in HTML standard
        return '\n'.join([
            '',
            '.. image:: {}'.format(src),
            '   :target: {}'.format(src),
            '   :alt: {}'.format(text),
            '',
        ])


Instruction:
Create a Python 3 function to
parse the next line of the file and return a new instance of the class.

Response:
def run(self):
        """Most of this method is from ``docutils.parser.rst.Directive``.

        docutils version: 0.12
        """
        if not self.state.document.settings.file_insertion_enabled:
            raise self.warning('"%s" directive disabled.' % self.name)
        source = self.state_machine.input_lines.source(
            self.lineno - self.state_machine.input_offset - 1)
        source_dir = os.path.dirname(os.path.abspath(source))
        path = rst.directives.path(self.arguments[0])
        path = os.path.normpath(os.path.join(source_dir, path))
        path = utils.relative_path(None, path)
        path = nodes.reprunicode(path)

        # get options (currently not use directive-specific options)
        encoding = self.options.get(
            'encoding', self.state.document.settings.input_encoding)
        e_handler = self.state.document.settings.input_encoding_error_handler
        tab_width = self.options.get(
            'tab-width', self.state.document.settings.tab_width)

        # open the inclding file
        try:
            self.state.document.settings.record_dependencies.add(path)
            include_file = io.FileInput(source_path=path,
                                        encoding=encoding,
                                        error_handler=e_handler)
        except UnicodeEncodeError as error:
            raise self.severe('Problems with "%s" directive path:\n'
                              'Cannot encode input file path "%s" '
                              '(wrong locale?).' %
                              (self.name, SafeString(path)))
        except IOError as error:
            raise self.severe('Problems with "%s" directive path:\n%s.' %
                              (self.name, ErrorString(error)))

        # read from the file
        try:
            rawtext = include_file.read()
        except UnicodeError as error:
            raise self.severe('Problem with "%s" directive:\n%s' %
                              (self.name, ErrorString(error)))

        config = self.state.document.settings.env.config
        converter = M2R(no_underscore_emphasis=config.no_underscore_emphasis)
        include_lines = statemachine.string2lines(converter(rawtext),
                                                  tab_width,
                                                  convert_whitespace=True)
        self.state_machine.insert_input(include_lines, path)
        return []


Instruction:
How would you code a function in Python 3 to
clone a given Agent and returns a list of the original Agent s in the first slot.

Response:
def clone_worker_agent(agent, factor, environment, network, agent_config):
    """
    Clones a given Agent (`factor` times) and returns a list of the cloned Agents with the original Agent
    in the first slot.

    Args:
        agent (Agent): The Agent object to clone.
        factor (int): The length of the final list.
        environment (Environment): The Environment to use for all cloned agents.
        network (LayeredNetwork): The Network to use (or None) for an Agent's Model.
        agent_config (dict): A dict of Agent specifications passed into the Agent's c'tor as kwargs.
    Returns:
        The list with `factor` cloned agents (including the original one).
    """
    ret = [agent]
    for i in xrange(factor - 1):
        worker = WorkerAgentGenerator(type(agent))(
            states=environment.states,
            actions=environment.actions,
            network=network,
            model=agent.model,
            **agent_config
        )
        ret.append(worker)

    return ret


Instruction:
Implement a Python 3 function for
executing this runner by starting all Agents in parallel (each one in one thread). Args: episodes (int): Deprecated; see num_episodes. max_timesteps (int): Deprecated; see max_episode_timesteps.

Response:
def run(
        self,
        num_episodes=-1,
        max_episode_timesteps=-1,
        episode_finished=None,
        summary_report=None,
        summary_interval=0,
        num_timesteps=None,
        deterministic=False,
        episodes=None,
        max_timesteps=None,
        testing=False,
        sleep=None
    ):
        """
        Executes this runner by starting all Agents in parallel (each one in one thread).

        Args:
            episodes (int): Deprecated; see num_episodes.
            max_timesteps (int): Deprecated; see max_episode_timesteps.
        """

        # Renamed episodes into num_episodes to match BaseRunner's signature (fully backw. compatible).
        if episodes is not None:
            num_episodes = episodes
            warnings.warn("WARNING: `episodes` parameter is deprecated, use `num_episodes` instead.",
                          category=DeprecationWarning)
        assert isinstance(num_episodes, int)
        # Renamed max_timesteps into max_episode_timesteps to match single Runner's signature (fully backw. compatible).
        if max_timesteps is not None:
            max_episode_timesteps = max_timesteps
            warnings.warn("WARNING: `max_timesteps` parameter is deprecated, use `max_episode_timesteps` instead.",
                          category=DeprecationWarning)
        assert isinstance(max_episode_timesteps, int)

        if summary_report is not None:
            warnings.warn("WARNING: `summary_report` parameter is deprecated, use `episode_finished` callback "
                          "instead to generate summaries every n episodes.",
                          category=DeprecationWarning)

        self.reset()

        # Reset counts/stop-condition for this run.
        self.global_episode = 0
        self.global_timestep = 0
        self.should_stop = False

        # Create threads.
        threads = [threading.Thread(target=self._run_single, args=(t, self.agent[t], self.environment[t],),
                                    kwargs={"deterministic": deterministic,
                                            "max_episode_timesteps": max_episode_timesteps,
                                            "episode_finished": episode_finished,
                                            "testing": testing,
                                            "sleep": sleep})
                   for t in range(len(self.agent))]

        # Start threads.
        self.start_time = time.time()
        [t.start() for t in threads]

        # Stay idle until killed by SIGINT or a global stop condition is met.
        try:
            next_summary = 0
            next_save = 0 if self.save_frequency_unit != "s" else time.time()
            while any([t.is_alive() for t in threads]) and self.global_episode < num_episodes or num_episodes == -1:
                self.time = time.time()

                # This is deprecated (but still supported) and should be covered by the `episode_finished` callable.
                if summary_report is not None and self.global_episode > next_summary:
                    summary_report(self)
                    next_summary += summary_interval

                if self.save_path and self.save_frequency is not None:
                    do_save = True
                    current = None
                    if self.save_frequency_unit == "e" and self.global_episode > next_save:
                        current = self.global_episode
                    elif self.save_frequency_unit == "s" and self.time > next_save:
                        current = self.time
                    elif self.save_frequency_unit == "t" and self.global_timestep > next_save:
                        current = self.global_timestep
                    else:
                        do_save = False

                    if do_save:
                        self.agent[0].save_model(self.save_path)
                        # Make sure next save is later than right now.
                        while next_save < current:
                            next_save += self.save_frequency
                time.sleep(1)

        except KeyboardInterrupt:
            print('Keyboard interrupt, sending stop command to threads')

        self.should_stop = True

        # Join threads.
        [t.join() for t in threads]
        print('All threads stopped')


Instruction:
Implement a function in Python 3 to
convert integer to x y coordinates.

Response:
def _int_to_pos(self, flat_position):
        """Returns x, y from flat_position integer.

        Args:
            flat_position: flattened position integer

        Returns: x, y

        """
        return flat_position % self.env.action_space.screen_shape[0],\
            flat_position % self.env.action_space.screen_shape[1]


Instruction:
Can you tell what is the following Python 3 function doing
def _wait_state(self, state, reward, terminal):
        while state == [None] or not state:
             state, terminal, reward = self._execute(dict(key=0))

        return state, terminal, reward

Response: Wait until the state is in the specified state.


Instruction:
Write a Python 3 script to
apply the given step deltas to the variable values.

Response:
def apply_step(self, variables, deltas):
        """
        Applies the given (and already calculated) step deltas to the variable values.

        Args:
            variables: List of variables.
            deltas: List of deltas of same length.

        Returns:
            The step-applied operation. A tf.group of tf.assign_add ops.
        """
        if len(variables) != len(deltas):
            raise TensorForceError("Invalid variables and deltas lists.")
        return tf.group(
            *(tf.assign_add(ref=variable, value=delta) for variable, delta in zip(variables, deltas))
        )