Instruction:
Make a summary of the following Python 3 code
def save(self, form, name, composite_form, commit):
        if self.shall_save(form, name, composite_form):
            return composite_form.save(commit=commit)
        return None

Response: Save the nested form.


Instruction:
Explain what the following Python 3 code does
def allow_blank(self, form, name):
        if self.blank is not None:
            return self.blank
        model = form._meta.model
        field = model._meta.get_field(self.get_field_name(form, name))
        return field.blank

Response: Allow blank determines if the form might be completely empty.


Instruction:
Make a summary of the following Python 3 code
def get_formset(self, form, name):
        kwargs = self.get_kwargs(form, name)
        formset_class = self.get_formset_class(form, name)
        formset = formset_class(
            form.data if form.is_bound else None,
            form.files if form.is_bound else None,
            **kwargs)
        return formset

Response: Get an instance of the formset.


Instruction:
Here you have a function in Python 3, explain what it does
def get_formset_class(self, form, name):
        if self.formset_class is not None:
            return self.formset_class
        formset_class = inlineformset_factory(
            self.get_parent_model(form, name),
            self.get_model(form, name),
            **self.formset_factory_kwargs)
        return formset_class

Response:
Returns the formset class that was provided as argument to the the
            class constructor.


Instruction:
Explain what the following Python 3 code does
def init_app(self, app, config_prefix='MONGOALCHEMY'):

        self.config_prefix = config_prefix
        def key(suffix):
            return '%s_%s' % (config_prefix, suffix)

        if key('DATABASE') not in app.config:
            raise ImproperlyConfiguredError("You should provide a database name "
                                            "(the %s setting)." % key('DATABASE'))

        uri = _get_mongo_uri(app, key)
        rs = app.config.get(key('REPLICA_SET'))
        timezone = None
        if key('TIMEZONE') in app.config:
            timezone = pytz.timezone(app.config.get(key('TIMEZONE')))
        self.session = session.Session.connect(app.config.get(key('DATABASE')),
                                               safe=app.config.get(key('SAFE_SESSION'),
                                                                   False),
                                               timezone = timezone,
                                               host=uri, replicaSet=rs)
        self.Document._session = self.session

Response:
This callback can be used to initialize an application for the use with this
       .


Instruction:
Make a summary of the following Python 3 code
def prev(self, error_out=False):
        return self.query.paginate(self.page - 1, self.per_page, error_out)

Response: Return a : class : Pagination object for the previous page.


Instruction:
Can you generate the documentation for the following Python 3 function
def get(self, mongo_id):
        try:
            return self.filter(self.type.mongo_id == mongo_id).first()
        except exceptions.BadValueException:
            return None

Response: Returns a : class : Document instance from its mongo_id or None if not found.


Instruction:
Write a Python 3 function that can
like get but aborts with 404 if not found instead of returning None

Response:
def get_or_404(self, mongo_id):
        """Like :meth:`get` method but aborts with 404 if not found instead of
        returning `None`"""
        document = self.get(mongo_id)
        if document is None:
            abort(404)
        return document


Instruction:
Can you write a function in Python 3 where it
returns a pagination object for the given page.

Response:
def paginate(self, page, per_page=20, error_out=True):
        """Returns ``per_page`` items from page ``page`` By default, it will
        abort with 404 if no items were found and the page was larger than 1.
        This behaviour can be disabled by setting ``error_out`` to ``False``.

        Returns a :class:`Pagination` object."""
        if page < 1 and error_out:
            abort(404)

        items = self.skip((page - 1) * per_page).limit(per_page).all()

        if len(items) < 1 and page != 1 and error_out:
            abort(404)

        return Pagination(self, page, per_page, self.count(), items)


Instruction:
Make a summary of the following Python 3 code
def save(self, safe=None):
        self._session.insert(self, safe=safe)
        self._session.flush()

Response: Saves the document itself in the database.


Instruction:
Here you have a function in Python 3, explain what it does
def remove(self, safe=None):
        self._session.remove(self, safe=None)
        self._session.flush()

Response: Removes the document itself from the database.


Instruction:
How would you code a function in Python 3 to
list all authors. e.g.: GET /authors

Response:
def list_authors():
    """List all authors.

    e.g.: GET /authors"""
    authors = Author.query.all()
    content = '
Authors:
'
    for author in authors:
        content += '
%s
' % author.name
    return content


Instruction:
Implement a Python 3 function for
formatting this diagnostic for display.

Response:
def format(self, options=None):
        """
        Format this diagnostic for display. The options argument takes
        Diagnostic.Display* flags, which can be combined using bitwise OR. If
        the options argument is not provided, the default display options will
        be used.
        """
        if options is None:
            options = conf.lib.clang_defaultDiagnosticDisplayOptions()
        if options & ~Diagnostic._FormatOptionsMask:
            raise ValueError('Invalid format options')
        return conf.lib.clang_formatDiagnostic(self, options)


Instruction:
Can you tell what is the following Python 3 function doing
def name(self):
        if self._name_map is None:
            self._name_map = {}
            for key, value in self.__class__.__dict__.items():
                if isinstance(value, self.__class__):
                    self._name_map[value] = key
        return self._name_map[self]

Response: Get the enumeration name of this cursor kind.


Instruction:
How would you explain what the following Python 3 function does
def spelling(self):
        if not hasattr(self, '_spelling'):
            self._spelling = conf.lib.clang_getCursorSpelling(self)

        return self._spelling

Response: Return the spelling of the entity pointed at by the cursor.


Instruction:
Create a Python 3 function for
returning the display name for the entity referenced by this cursor.

Response:
def displayname(self):
        """
        Return the display name for the entity referenced by this cursor.

        The display name contains extra information that helps identify the
        cursor, such as the parameters of a function or template or the
        arguments of a class template specialization.
        """
        if not hasattr(self, '_displayname'):
            self._displayname = conf.lib.clang_getCursorDisplayName(self)

        return self._displayname


Instruction:
Can you generate a brief explanation for the following Python 3 code
def mangled_name(self):
        if not hasattr(self, '_mangled_name'):
            self._mangled_name = conf.lib.clang_Cursor_getMangling(self)

        return self._mangled_name

Response: Return the mangled name for the entity referenced by this cursor.


Instruction:
Can you generate the documentation for the following Python 3 function
def linkage(self):
        if not hasattr(self, '_linkage'):
            self._linkage = conf.lib.clang_getCursorLinkage(self)

        return LinkageKind.from_id(self._linkage)

Response: Return the linkage of this cursor.


Instruction:
Can you tell what is the following Python 3 function doing
def availability(self):
        if not hasattr(self, '_availability'):
            self._availability = conf.lib.clang_getCursorAvailability(self)

        return AvailabilityKind.from_id(self._availability)

Response: Returns the availability of the entity pointed at by the cursor.


Instruction:
Can you tell what is the following Python 3 function doing
def objc_type_encoding(self):
        if not hasattr(self, '_objc_type_encoding'):
            self._objc_type_encoding = \
              conf.lib.clang_getDeclObjCTypeEncoding(self)

        return self._objc_type_encoding

Response: Return the Objective - C type encoding as a str.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def from_source(cls, filename, args=None, unsaved_files=None, options=0,
                    index=None):
        """Create a TranslationUnit by parsing source.

        This is capable of processing source code both from files on the
        filesystem as well as in-memory contents.

        Command-line arguments that would be passed to clang are specified as
        a list via args. These can be used to specify include paths, warnings,
        etc. e.g. ["-Wall", "-I/path/to/include"].

        In-memory file content can be provided via unsaved_files. This is an
        iterable of 2-tuples. The first element is the str filename. The
        second element defines the content. Content can be provided as str
        source code or as file objects (anything with a read() method). If
        a file object is being used, content will be read until EOF and the
        read cursor will not be reset to its original position.

        options is a bitwise or of TranslationUnit.PARSE_XXX flags which will
        control parsing behavior.

        index is an Index instance to utilize. If not provided, a new Index
        will be created for this TranslationUnit.

        To parse source from the filesystem, the filename of the file to parse
        is specified by the filename argument. Or, filename could be None and
        the args list would contain the filename(s) to parse.

        To parse source from an in-memory buffer, set filename to the virtual
        filename you wish to associate with this source (e.g. "test.c"). The
        contents of that file are then provided in unsaved_files.

        If an error occurs, a TranslationUnitLoadError is raised.

        Please note that a TranslationUnit with parser errors may be returned.
        It is the caller's responsibility to check tu.diagnostics for errors.

        Also note that Clang infers the source language from the extension of
        the input filename. If you pass in source code containing a C++ class
        declaration with the filename "test.c" parsing will fail.
        """
        if args is None:
            args = []

        if unsaved_files is None:
            unsaved_files = []

        if index is None:
            index = Index.create()

        args_array = None
        if len(args) > 0:
            args_array = (c_char_p * len(args))(*[b(x) for x in args])

        unsaved_array = None
        if len(unsaved_files) > 0:
            unsaved_array = (_CXUnsavedFile * len(unsaved_files))()
            for i, (name, contents) in enumerate(unsaved_files):
                if hasattr(contents, "read"):
                    contents = contents.read()

                unsaved_array[i].name = b(name)
                unsaved_array[i].contents = b(contents)
                unsaved_array[i].length = len(contents)

        ptr = conf.lib.clang_parseTranslationUnit(index, filename, args_array,
                                    len(args), unsaved_array,
                                    len(unsaved_files), options)

        if not ptr:
            raise TranslationUnitLoadError("Error parsing translation unit.")

        return cls(ptr, index=index)

Response: Create a TranslationUnit instance from a source code.


Instruction:
Write a Python 3 script for
processing all the files with clang and extracts all relevant nodes from the generated AST.

Response:
def process(self):
        """
        process processes all the files with clang and extracts all relevant
        nodes from the generated AST
        """

        self.index = cindex.Index.create()
        self.headers = {}

        for f in self.files:
            if f in self.processed:
                continue

            print('Processing {0}'.format(os.path.basename(f)))

            tu = self.index.parse(f, self.flags)

            if len(tu.diagnostics) != 0:
                fatal = False

                for d in tu.diagnostics:
                    sys.stderr.write(d.format())
                    sys.stderr.write("\n")

                    if d.severity == cindex.Diagnostic.Fatal or \
                       d.severity == cindex.Diagnostic.Error:
                        fatal = True

                if fatal:
                    sys.stderr.write("\nCould not generate documentation due to parser errors\n")
                    sys.exit(1)

            if not tu:
                sys.stderr.write("Could not parse file %s...\n" % (f,))
                sys.exit(1)

            # Extract comments from files and included files that we are
            # supposed to inspect
            extractfiles = [f]

            for inc in tu.get_includes():
                filename = str(inc.include)
                self.headers[filename] = True

                if filename in self.processed or (not filename in self.files) or filename in extractfiles:
                    continue

                extractfiles.append(filename)

            for e in extractfiles:
                db = comment.CommentsDatabase(e, tu)

                self.add_categories(db.category_names)
                self.commentsdbs[e] = db

            self.visit(tu.cursor.get_children())

            for f in self.processing:
                self.processed[f] = True

            self.processing = {}

        # Construct hierarchy of nodes.
        for node in self.all_nodes:
            q = node.qid

            if node.parent is None:
                par = self.find_parent(node)

                # Lookup categories for things in the root
                if (par is None or par == self.root) and (not node.cursor is None):
                    location = node.cursor.extent.start
                    db = self.commentsdbs[location.file.name]

                    if db:
                        par = self.category_to_node[db.lookup_category(location)]

                if par is None:
                    par = self.root

                par.append(node)

            # Resolve comment
            cm = self.find_node_comment(node)

            if cm:
                node.merge_comment(cm)

        # Keep track of classes to resolve bases and subclasses
        classes = {}

        # Map final qid to node
        for node in self.all_nodes:
            q = node.qid
            self.qid_to_node[q] = node

            if isinstance(node, nodes.Class):
                classes[q] = node

        # Resolve bases and subclasses
        for qid in classes:
            classes[qid].resolve_bases(classes)


Instruction:
Write a Python 3 function for
visiting iterates over the cursor iterator and creates nodes from the AST cursors.

Response:
def visit(self, citer, parent=None):
        """
        visit iterates over the provided cursor iterator and creates nodes
        from the AST cursors.
        """
        if not citer:
            return

        while True:
            try:
                item = next(citer)
            except StopIteration:
                return

            # Check the source of item
            if not item.location.file:
                self.visit(item.get_children())
                continue

            # Ignore files we already processed
            if str(item.location.file) in self.processed:
                continue

            # Ignore files other than the ones we are scanning for
            if not str(item.location.file) in self.files:
                continue

            # Ignore unexposed things
            if item.kind == cindex.CursorKind.UNEXPOSED_DECL:
                self.visit(item.get_children(), parent)
                continue

            self.processing[str(item.location.file)] = True

            if item.kind in self.kindmap:
                cls = self.kindmap[item.kind]

                if not cls:
                    # Skip
                    continue

                # see if we already have a node for this thing
                node = self.usr_to_node[item.get_usr()]

                if not node or self.is_unique_anon_struct(node, parent):
                    # Only register new nodes if they are exposed.
                    if self.cursor_is_exposed(item):
                        node = cls(item, None)
                        self.register_node(node, parent)

                elif isinstance(parent, nodes.Typedef) and isinstance(node, nodes.Struct):
                    # Typedefs are handled a bit specially because what happens
                    # is that clang first exposes an unnamed struct/enum, and
                    # then exposes the typedef, with as a child again the
                    # cursor to the already defined struct/enum. This is a
                    # bit reversed as to how we normally process things.
                    self.register_anon_typedef(node, parent)
                else:
                    self.cursor_to_node[item] = node
                    node.add_ref(item)

                if node and node.process_children:
                    self.visit(item.get_children(), node)
            else:
                par = self.cursor_to_node[item.semantic_parent]

                if not par:
                    par = parent

                if par:
                    ret = par.visit(item, citer)

                    if not ret is None:
                        for node in ret:
                            self.register_node(node, par)

                ignoretop = [cindex.CursorKind.TYPE_REF, cindex.CursorKind.PARM_DECL]

                if (not par or ret is None) and not item.kind in ignoretop:
                    log.warning("Unhandled cursor: %s", item.kind)


Instruction:
Can you generate the documentation for the following Python 3 function
def extract(self, filename, tu):
        it = tu.get_tokens(extent=tu.get_extent(filename, (0, int(os.stat(filename).st_size))))

        while True:
            try:
                self.extract_loop(it)
            except StopIteration:
                break

Response: extract extracts comments from a translation unit for a given file by looking through all the COMMENT tokens in the TU and then extracting the comments.


Instruction:
Create a Python 3 function for
generating namedtuple with default values.

Response:
def defaultsnamedtuple(name, fields, defaults=None):
    '''
    Generate namedtuple with default values.

    :param name: name
    :param fields: iterable with field names
    :param defaults: iterable or mapping with field defaults
    :returns: defaultdict with given fields and given defaults
    :rtype: collections.defaultdict
    '''
    nt = collections.namedtuple(name, fields)
    nt.__new__.__defaults__ = (None,) * len(nt._fields)
    if isinstance(defaults, collections.Mapping):
        nt.__new__.__defaults__ = tuple(nt(**defaults))
    elif defaults:
        nt.__new__.__defaults__ = tuple(nt(*defaults))
    return nt


Instruction:
Implement a Python 3 function for
initializing this Flask extension for given app.

Response:
def init_app(self, app):
        '''
        Initialize this Flask extension for given app.
        '''
        self.app = app
        if not hasattr(app, 'extensions'):
            app.extensions = {}
        app.extensions['plugin_manager'] = self
        self.reload()


Instruction:
Write a Python 3 function for
reloading the internal state of the internal plugins.

Response:
def reload(self):
        '''
        Clear plugin manager state and reload plugins.

        This method will make use of :meth:`clear` and :meth:`load_plugin`,
        so all internal state will be cleared, and all plugins defined in
        :data:`self.app.config['plugin_modules']` will be loaded.
        '''
        self.clear()
        for plugin in self.app.config.get('plugin_modules', ()):
            self.load_plugin(plugin)


Instruction:
Can you tell what is the following Python 3 function doing
def import_plugin(self, plugin):
        '''
        Import plugin by given name, looking at :attr:`namespaces`.

        :param plugin: plugin module name
        :type plugin: str
        :raises PluginNotFoundError: if not found on any namespace
        '''
        names = [
            '%s%s%s' % (namespace, '' if namespace[-1] == '_' else '.', plugin)
            if namespace else
            plugin
            for namespace in self.namespaces
            ]

        for name in names:
            if name in sys.modules:
                return sys.modules[name]

        for name in names:
            try:
                __import__(name)
                return sys.modules[name]
            except (ImportError, KeyError):
                pass

        raise PluginNotFoundError(
            'No plugin module %r found, tried %r' % (plugin, names),
            plugin, names)

Response: Import plugin by given name looking at namespaces.


Instruction:
Can you implement a function in Python 3 that
loads plugin and register related data.

Response:
def load_plugin(self, plugin):
        '''
        Import plugin (see :meth:`import_plugin`) and load related data.

        If available, plugin's module-level :func:`register_plugin` function
        will be called with current plugin manager instance as first argument.

        :param plugin: plugin module name
        :type plugin: str
        :raises PluginNotFoundError: if not found on any namespace
        '''
        module = super(RegistrablePluginManager, self).load_plugin(plugin)
        if hasattr(module, 'register_plugin'):
            module.register_plugin(self)
        return module


Instruction:
Here you have a function in Python 3, explain what it does
def register_blueprint(self, blueprint):
        '''
        Register given blueprint on curren app.

        This method is provided for using inside plugin's module-level
        :func:`register_plugin` functions.

        :param blueprint: blueprint object with plugin endpoints
        :type blueprint: flask.Blueprint
        '''
        if blueprint not in self._blueprint_known:
            self.app.register_blueprint(blueprint)
            self._blueprint_known.add(blueprint)

Response: Register given blueprint on curren app.


Instruction:
Can you implement a function in Python 3 that
resolves widget callable properties into static ones.

Response:
def _resolve_widget(cls, file, widget):
        '''
        Resolve widget callable properties into static ones.

        :param file: file will be used to resolve callable properties.
        :type file: browsepy.file.Node
        :param widget: widget instance optionally with callable properties
        :type widget: object
        :returns: a new widget instance of the same type as widget parameter
        :rtype: object
        '''
        return widget.__class__(*[
            value(file) if callable(value) else value
            for value in widget
            ])


Instruction:
Can you implement a function in Python 3 that
iterates registered widgets optionally matching given criteria.

Response:
def iter_widgets(self, file=None, place=None):
        '''
        Iterate registered widgets, optionally matching given criteria.

        :param file: optional file object will be passed to widgets' filter
                     functions.
        :type file: browsepy.file.Node or None
        :param place: optional template place hint.
        :type place: str
        :yields: widget instances
        :ytype: object
        '''
        for filter, dynamic, cwidget in self._widgets:
            try:
                if file and filter and not filter(file):
                    continue
            except BaseException as e:
                # Exception is handled  as this method execution is deffered,
                # making hard to debug for plugin developers.
                warnings.warn(
                    'Plugin action filtering failed with error: %s' % e,
                    RuntimeWarning
                    )
                continue
            if place and place != cwidget.place:
                continue
            if file and dynamic:
                cwidget = self._resolve_widget(file, cwidget)
            yield cwidget


Instruction:
Write a Python 3 function for
creating a widget object based on given arguments.

Response:
def create_widget(self, place, type, file=None, **kwargs):
        '''
        Create a widget object based on given arguments.

        If file object is provided, callable arguments will be resolved:
        its return value will be used after calling them with file as first
        parameter.

        All extra `kwargs` parameters will be passed to widget constructor.

        :param place: place hint where widget should be shown.
        :type place: str
        :param type: widget type name as taken from :attr:`widget_types` dict
                     keys.
        :type type: str
        :param file: optional file object for widget attribute resolving
        :type type: browsepy.files.Node or None
        :returns: widget instance
        :rtype: object
        '''
        widget_class = self.widget_types.get(type, self.widget_types['base'])
        kwargs.update(place=place, type=type)
        try:
            element = widget_class(**kwargs)
        except TypeError as e:
            message = e.args[0] if e.args else ''
            if (
              'unexpected keyword argument' in message or
              'required positional argument' in message
              ):
                raise WidgetParameterException(
                    'type %s; %s; available: %r'
                    % (type, message, widget_class._fields)
                    )
            raise e
        if file and any(map(callable, element)):
            return self._resolve_widget(file, element)
        return element


Instruction:
Explain what the following Python 3 code does
def register_widget(self, place=None, type=None, widget=None, filter=None,
                        **kwargs):
        '''
        Create (see :meth:`create_widget`) or use provided widget and register
        it.

        This method provides this dual behavior in order to simplify widget
        creation-registration on an functional single step without sacrifycing
        the reusability of a object-oriented approach.

        :param place: where widget should be placed. This param conflicts
                      with `widget` argument.
        :type place: str or None
        :param type: widget type name as taken from :attr:`widget_types` dict
                     keys. This param conflicts with `widget` argument.
        :type type: str or None
        :param widget: optional widget object will be used as is. This param
                       conflicts with both place and type arguments.
        :type widget: object or None
        :raises TypeError: if both widget and place or type are provided at
                           the same time (they're mutually exclusive).
        :returns: created or given widget object
        :rtype: object
        '''
        if bool(widget) == bool(place or type):
            raise InvalidArgumentError(
                'register_widget takes either place and type or widget'
                )
        widget = widget or self.create_widget(place, type, **kwargs)
        dynamic = any(map(callable, widget))
        self._widgets.append((filter, dynamic, widget))
        return widget

Response: Create or use provided widget and register it with the internal list of available widgets.


Instruction:
Can you write a function in Python 3 where it
clears plugin manager state.

Response:
def clear(self):
        '''
        Clear plugin manager state.

        Registered mimetype functions will be disposed after calling this
        method.
        '''
        self._mimetype_functions = list(self._default_mimetype_functions)
        super(MimetypePluginManager, self).clear()


Instruction:
Make a summary of the following Python 3 code
def get_mimetype(self, path):
        '''
        Get mimetype of given path calling all registered mime functions (and
        default ones).

        :param path: filesystem path of file
        :type path: str
        :returns: mimetype
        :rtype: str
        '''
        for fnc in self._mimetype_functions:
            mime = fnc(path)
            if mime:
                return mime
        return mimetype.by_default(path)

Response: Get mimetype of given path calling all registered mime functions and return the mimetype of the file.


Instruction:
Can you implement a function in Python 3 that
gives a plugin name extracts its registered_arguments as an iterable of ( args kwargs ) tuples.

Response:
def extract_plugin_arguments(self, plugin):
        '''
        Given a plugin name, extracts its registered_arguments as an
        iterable of (args, kwargs) tuples.

        :param plugin: plugin name
        :type plugin: str
        :returns: iterable if (args, kwargs) tuples.
        :rtype: iterable
        '''
        module = self.import_plugin(plugin)
        if hasattr(module, 'register_arguments'):
            manager = ArgumentPluginManager()
            module.register_arguments(manager)
            return manager._argparse_argkwargs
        return ()


Instruction:
Can you write a function in Python 3 where it
processes given argument list based on registered arguments and given base.

Response:
def load_arguments(self, argv, base=None):
        '''
        Process given argument list based on registered arguments and given
        optional base :class:`argparse.ArgumentParser` instance.

        This method saves processed arguments on itself, and this state won't
        be lost after :meth:`clean` calls.

        Processed argument state will be available via :meth:`get_argument`
        method.

        :param argv: command-line arguments (without command itself)
        :type argv: iterable of str
        :param base: optional base :class:`argparse.ArgumentParser` instance.
        :type base: argparse.ArgumentParser or None
        :returns: argparse.Namespace instance with processed arguments as
                  given by :meth:`argparse.ArgumentParser.parse_args`.
        :rtype: argparse.Namespace
        '''
        plugin_parser = argparse.ArgumentParser(add_help=False)
        plugin_parser.add_argument('--plugin', action='append', default=[])
        parent = base or plugin_parser
        parser = argparse.ArgumentParser(
            parents=(parent,),
            add_help=False,
            **getattr(parent, 'defaults', {})
            )
        plugins = [
            plugin
            for plugins in plugin_parser.parse_known_args(argv)[0].plugin
            for plugin in plugins.split(',')
            ]
        for plugin in sorted(set(plugins), key=plugins.index):
            arguments = self.extract_plugin_arguments(plugin)
            if arguments:
                group = parser.add_argument_group('%s arguments' % plugin)
                for argargs, argkwargs in arguments:
                    group.add_argument(*argargs, **argkwargs)
        self._argparse_arguments = parser.parse_args(argv)
        return self._argparse_arguments


Instruction:
How would you implement a function in Python 3 that
iterates over the sorting - cookie from cookies dictionary.

Response:
def iter_cookie_browse_sorting(cookies):
    '''
    Get sorting-cookie from cookies dictionary.

    :yields: tuple of path and sorting property
    :ytype: 2-tuple of strings
    '''
    try:
        data = cookies.get('browse-sorting', 'e30=').encode('ascii')
        for path, prop in json.loads(base64.b64decode(data).decode('utf-8')):
            yield path, prop
    except (ValueError, TypeError, KeyError) as e:
        logger.exception(e)


Instruction:
Given the following Python 3 function, write the documentation
def get_cookie_browse_sorting(path, default):
    '''
    Get sorting-cookie data for path of current request.

    :returns: sorting property
    :rtype: string
    '''
    if request:
        for cpath, cprop in iter_cookie_browse_sorting(request.cookies):
            if path == cpath:
                return cprop
    return default

Response: Get sorting - cookie data for a given path.


Instruction:
Can you implement a function in Python 3 that
returns a function that returns a tuple with sorting gunction and reverse bool

Response:
def browse_sortkey_reverse(prop):
    '''
    Get sorting function for directory listing based on given attribute
    name, with some caveats:
    * Directories will be first.
    * If *name* is given, link widget lowercase text will be used istead.
    * If *size* is given, bytesize will be used.

    :param prop: file attribute name
    :returns: tuple with sorting gunction and reverse bool
    :rtype: tuple of a dict and a bool
    '''
    if prop.startswith('-'):
        prop = prop[1:]
        reverse = True
    else:
        reverse = False

    if prop == 'text':
        return (
            lambda x: (
                x.is_directory == reverse,
                x.link.text.lower() if x.link and x.link.text else x.name
                ),
            reverse
            )
    if prop == 'size':
        return (
            lambda x: (
                x.is_directory == reverse,
                x.stats.st_size
                ),
            reverse
            )
    return (
        lambda x: (
            x.is_directory == reverse,
            getattr(x, prop, None)
            ),
        reverse
        )


Instruction:
Given the following Python 3 function, write the documentation
def stream_template(template_name, **context):
    '''
    Some templates can be huge, this function returns an streaming response,
    sending the content in chunks and preventing from timeout.

    :param template_name: template
    :param **context: parameters for templates.
    :yields: HTML strings
    '''
    app.update_template_context(context)
    template = app.jinja_env.get_template(template_name)
    stream = template.generate(context)
    return Response(stream_with_context(stream))

Response: Returns a streaming response with the given template.


Instruction:
How would you code a function in Python 3 to
return a dictionary with uppercase keys as keys.

Response:
def gendict(cls, *args, **kwargs):
        '''
        Pre-translated key dictionary constructor.

        See :type:`dict` for more info.

        :returns: dictionary with uppercase keys
        :rtype: dict
        '''
        gk = cls.genkey
        return dict((gk(k), v) for k, v in dict(*args, **kwargs).items())


Instruction:
Write a Python 3 script to
return the next state jump.

Response:
def nearest(self):
        '''
        Get the next state jump.

        The next jump is calculated looking at :attr:`current` state
        and its possible :attr:`jumps` to find the nearest and bigger
        option in :attr:`pending` data.

        If none is found, the returned next state label will be None.

        :returns: tuple with index, substring and next state label
        :rtype: tuple
        '''
        try:
            options = self.jumps[self.current]
        except KeyError:
            raise KeyError(
                'Current state %r not defined in %s.jumps.'
                % (self.current, self.__class__)
                )
        offset = len(self.start)
        index = len(self.pending)
        if self.streaming:
            index -= max(map(len, options))
        key = (index, 1)
        result = (index, '', None)
        for amark, anext in options.items():
            asize = len(amark)
            aindex = self.pending.find(amark, offset, index + asize)
            if aindex > -1:
                index = aindex
                akey = (aindex, -asize)
                if akey < key:
                    key = akey
                    result = (aindex, amark, anext)
        return result


Instruction:
Can you tell what is the following Python 3 function doing
def transform(self, data, mark, next):
        '''
        Apply the appropriate transformation function on current state data,
        which is supposed to end at this point.

        It is expected transformation logic makes use of :attr:`start`,
        :attr:`current` and :attr:`streaming` instance attributes to
        bettee know the state is being left.

        :param data: string to transform (includes start)
        :type data: str
        :param mark: string producing the new state jump
        :type mark: str
        :param next: state is about to star, None on finish
        :type next: str or None

        :returns: transformed data
        :rtype: str
        '''
        method = getattr(self, 'transform_%s' % self.current, None)
        return method(data, mark, next) if method else data

Response: Apply the appropriate transformation function on current state data and return the transformed data.


Instruction:
Given the following Python 3 function, write the documentation
def feed(self, data=''):
        '''
        Optionally add pending data, switch into streaming mode, and yield
        result chunks.

        :yields: result chunks
        :ytype: str
        '''
        self.streaming = True
        self.pending += data
        for i in self:
            yield i

Response: Feed the data into a generator.


Instruction:
How would you implement a function in Python 3 that
yields the result of the next iteration.

Response:
def finish(self, data=''):
        '''
        Optionally add pending data, turn off streaming mode, and yield
        result chunks, which implies all pending data will be consumed.

        :yields: result chunks
        :ytype: str
        '''
        self.pending += data
        self.streaming = False
        for i in self:
            yield i


Instruction:
How would you implement a function in Python 3 that
fills the internal tar file with the contents of the current object.

Response:
def fill(self):
        '''
        Writes data on internal tarfile instance, which writes to current
        object, using :meth:`write`.

        As this method is blocking, it is used inside a thread.

        This method is called automatically, on a thread, on initialization,
        so there is little need to call it manually.
        '''
        if self.exclude:
            exclude = self.exclude
            ap = functools.partial(os.path.join, self.path)
            self._tarfile.add(
                self.path, "",
                filter=lambda info: None if exclude(ap(info.name)) else info
                )
        else:
            self._tarfile.add(self.path, "")
        self._tarfile.close()  # force stream flush
        self._finished += 1
        if not self._result.is_set():
            self._result.set()


Instruction:
Write a Python 3 script to
write method used by internal tarfile instance to output data. This method blocks tarfile execution once internal buffer is full. As this method is blocking, it is used inside the same thread of :meth:`fill`. :param data: bytes to write to internal buffer :type data: bytes :returns: number of bytes written :rtype: int

Response:
def write(self, data):
        '''
        Write method used by internal tarfile instance to output data.
        This method blocks tarfile execution once internal buffer is full.

        As this method is blocking, it is used inside the same thread of
        :meth:`fill`.

        :param data: bytes to write to internal buffer
        :type data: bytes
        :returns: number of bytes written
        :rtype: int
        '''
        self._add.wait()
        self._data += data
        if len(self._data) > self._want:
            self._add.clear()
            self._result.set()
        return len(data)


Instruction:
Can you write a function in Python 3 where it
reads method gets data from internal buffer while releasing locks when needed.

Response:
def read(self, want=0):
        '''
        Read method, gets data from internal buffer while releasing
        :meth:`write` locks when needed.

        The lock usage means it must ran on a different thread than
        :meth:`fill`, ie. the main thread, otherwise will deadlock.

        The combination of both write and this method running on different
        threads makes tarfile being streamed on-the-fly, with data chunks being
        processed and retrieved on demand.

        :param want: number bytes to read, defaults to 0 (all available)
        :type want: int
        :returns: tarfile data as bytes
        :rtype: bytes
        '''
        if self._finished:
            if self._finished == 1:
                self._finished += 1
                return ""
            return EOFError("EOF reached")

        # Thread communication
        self._want = want
        self._add.set()
        self._result.wait()
        self._result.clear()

        if want:
            data = self._data[:want]
            self._data = self._data[want:]
        else:
            data = self._data
            self._data = bytes()
        return data


Instruction:
Explain what the following Python 3 code does
def isexec(path):
    '''
    Check if given path points to an executable file.

    :param path: file path
    :type path: str
    :return: True if executable, False otherwise
    :rtype: bool
    '''
    return os.path.isfile(path) and os.access(path, os.X_OK)

Response: Check if given path points to an executable file.


Instruction:
Create a Python 3 function to
decode given path. :param path: path will be decoded if using bytes :type path: bytes or str :param os_name: operative system name, defaults to os.name :type os_name: str :param fs_encoding: current filesystem encoding, defaults to autodetected :type fs_encoding: str :return: decoded path :rtype: str

Response:
def fsdecode(path, os_name=os.name, fs_encoding=FS_ENCODING, errors=None):
    '''
    Decode given path.

    :param path: path will be decoded if using bytes
    :type path: bytes or str
    :param os_name: operative system name, defaults to os.name
    :type os_name: str
    :param fs_encoding: current filesystem encoding, defaults to autodetected
    :type fs_encoding: str
    :return: decoded path
    :rtype: str
    '''
    if not isinstance(path, bytes):
        return path
    if not errors:
        use_strict = PY_LEGACY or os_name == 'nt'
        errors = 'strict' if use_strict else 'surrogateescape'
    return path.decode(fs_encoding, errors=errors)


Instruction:
Can you write a function in Python 3 where it
encodes given path. :param path: path will be encoded if not using bytes :type path: bytes or str :param os_name: operative system name, defaults to os.name :type os_name: str :param fs_encoding: current filesystem encoding, defaults to autodetected :type fs_encoding: str :return: encoded path :rtype: bytes

Response:
def fsencode(path, os_name=os.name, fs_encoding=FS_ENCODING, errors=None):
    '''
    Encode given path.

    :param path: path will be encoded if not using bytes
    :type path: bytes or str
    :param os_name: operative system name, defaults to os.name
    :type os_name: str
    :param fs_encoding: current filesystem encoding, defaults to autodetected
    :type fs_encoding: str
    :return: encoded path
    :rtype: bytes
    '''
    if isinstance(path, bytes):
        return path
    if not errors:
        use_strict = PY_LEGACY or os_name == 'nt'
        errors = 'strict' if use_strict else 'surrogateescape'
    return path.encode(fs_encoding, errors=errors)


Instruction:
Create a Python 3 function for
getting current work directory s absolute path.

Response:
def getcwd(fs_encoding=FS_ENCODING, cwd_fnc=os.getcwd):
    '''
    Get current work directory's absolute path.
    Like os.getcwd but garanteed to return an unicode-str object.

    :param fs_encoding: filesystem encoding, defaults to autodetected
    :type fs_encoding: str
    :param cwd_fnc: callable used to get the path, defaults to os.getcwd
    :type cwd_fnc: Callable
    :return: path
    :rtype: str
    '''
    path = fsdecode(cwd_fnc(), fs_encoding=fs_encoding)
    return os.path.abspath(path)


Instruction:
Here you have a function in Python 3, explain what it does
def getdebug(environ=os.environ, true_values=TRUE_VALUES):
    '''
    Get if app is expected to be ran in debug mode looking at environment
    variables.

    :param environ: environment dict-like object
    :type environ: collections.abc.Mapping
    :returns: True if debug contains a true-like string, False otherwise
    :rtype: bool
    '''
    return environ.get('DEBUG', '').lower() in true_values

Response: Returns True if the app is expected to be ran in debug mode False otherwise.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def deprecated(func_or_text, environ=os.environ):
    '''
    Decorator used to mark functions as deprecated. It will result in a
    warning being emmitted hen the function is called.

    Usage:

    >>> @deprecated
    ... def fnc():
    ...     pass

    Usage (custom message):

    >>> @deprecated('This is deprecated')
    ... def fnc():
    ...     pass

    :param func_or_text: message or callable to decorate
    :type func_or_text: callable
    :param environ: optional environment mapping
    :type environ: collections.abc.Mapping
    :returns: nested decorator or new decorated function (depending on params)
    :rtype: callable
    '''
    def inner(func):
        message = (
            'Deprecated function {}.'.format(func.__name__)
            if callable(func_or_text) else
            func_or_text
            )

        @functools.wraps(func)
        def new_func(*args, **kwargs):
            with warnings.catch_warnings():
                if getdebug(environ):
                    warnings.simplefilter('always', DeprecationWarning)
                warnings.warn(message, category=DeprecationWarning,
                              stacklevel=3)
            return func(*args, **kwargs)
        return new_func
    return inner(func_or_text) if callable(func_or_text) else inner

Response: A decorator used to mark functions as deprecated.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def pathsplit(value, sep=os.pathsep):
    '''
    Get enviroment PATH elements as list.

    This function only cares about spliting across OSes.

    :param value: path string, as given by os.environ['PATH']
    :type value: str
    :param sep: PATH separator, defaults to os.pathsep
    :type sep: str
    :yields: every path
    :ytype: str
    '''
    for part in value.split(sep):
        if part[:1] == part[-1:] == '"' or part[:1] == part[-1:] == '\'':
            part = part[1:-1]
        yield part

Response: Returns a generator that yields all the enviroment PATH elements in the given string.


Instruction:
How would you explain what the following Python 3 function does
def pathparse(value, sep=os.pathsep, os_sep=os.sep):
    '''
    Get enviroment PATH directories as list.

    This function cares about spliting, escapes and normalization of paths
    across OSes.

    :param value: path string, as given by os.environ['PATH']
    :type value: str
    :param sep: PATH separator, defaults to os.pathsep
    :type sep: str
    :param os_sep: OS filesystem path separator, defaults to os.sep
    :type os_sep: str
    :yields: every path
    :ytype: str
    '''
    escapes = []
    normpath = ntpath.normpath if os_sep == '\\' else posixpath.normpath
    if '\\' not in (os_sep, sep):
        escapes.extend((
            ('\\\\', '<ESCAPE-ESCAPE>', '\\'),
            ('\\"', '<ESCAPE-DQUOTE>', '"'),
            ('\\\'', '<ESCAPE-SQUOTE>', '\''),
            ('\\%s' % sep, '<ESCAPE-PATHSEP>', sep),
            ))
    for original, escape, unescape in escapes:
        value = value.replace(original, escape)
    for part in pathsplit(value, sep=sep):
        if part[-1:] == os_sep and part != os_sep:
            part = part[:-1]
        for original, escape, unescape in escapes:
            part = part.replace(escape, unescape)
        yield normpath(fsdecode(part))

Response: A generator function that returns every path in the given path string.


Instruction:
Write a Python 3 script for
getting all pathconf variables for given path.

Response:
def pathconf(path,
             os_name=os.name,
             isdir_fnc=os.path.isdir,
             pathconf_fnc=getattr(os, 'pathconf', None),
             pathconf_names=getattr(os, 'pathconf_names', ())):
    '''
    Get all pathconf variables for given path.

    :param path: absolute fs path
    :type path: str
    :returns: dictionary containing pathconf keys and their values (both str)
    :rtype: dict
    '''

    if pathconf_fnc and pathconf_names:
        return {key: pathconf_fnc(path, key) for key in pathconf_names}
    if os_name == 'nt':
        maxpath = 246 if isdir_fnc(path) else 259  # 260 minus <END>
    else:
        maxpath = 255  # conservative sane default
    return {
        'PC_PATH_MAX': maxpath,
        'PC_NAME_MAX': maxpath - len(path),
        }


Instruction:
Write a Python 3 function that can
get command absolute path.

Response:
def which(name,
          env_path=ENV_PATH,
          env_path_ext=ENV_PATHEXT,
          is_executable_fnc=isexec,
          path_join_fnc=os.path.join,
          os_name=os.name):
    '''
    Get command absolute path.

    :param name: name of executable command
    :type name: str
    :param env_path: OS environment executable paths, defaults to autodetected
    :type env_path: list of str
    :param is_executable_fnc: callable will be used to detect if path is
                              executable, defaults to `isexec`
    :type is_executable_fnc: Callable
    :param path_join_fnc: callable will be used to join path components
    :type path_join_fnc: Callable
    :param os_name: os name, defaults to os.name
    :type os_name: str
    :return: absolute path
    :rtype: str or None
    '''
    for path in env_path:
        for suffix in env_path_ext:
            exe_file = path_join_fnc(path, name) + suffix
            if is_executable_fnc(exe_file):
                return exe_file
    return None


Instruction:
How would you implement a function in Python 3 that
escapes all special regex characters in pattern.

Response:
def re_escape(pattern, chars=frozenset("()[]{}?*+|^$\\.-#")):
    '''
    Escape all special regex characters in pattern.
    Logic taken from regex module.

    :param pattern: regex pattern to escape
    :type patterm: str
    :returns: escaped pattern
    :rtype: str
    '''
    escape = '\\{}'.format
    return ''.join(
        escape(c) if c in chars or c.isspace() else
        '\\000' if c == '\x00' else c
        for c in pattern
        )


Instruction:
Can you generate a brief explanation for the following Python 3 code
def register_plugin(manager):
    '''
    Register blueprints and actions using given plugin manager.

    :param manager: plugin manager
    :type manager: browsepy.manager.PluginManager
    '''
    manager.register_blueprint(player)
    manager.register_mimetype_function(detect_playable_mimetype)

    # add style tag
    manager.register_widget(
        place='styles',
        type='stylesheet',
        endpoint='player.static',
        filename='css/browse.css'
    )

    # register link actions
    manager.register_widget(
        place='entry-link',
        type='link',
        endpoint='player.audio',
        filter=PlayableFile.detect
    )
    manager.register_widget(
        place='entry-link',
        icon='playlist',
        type='link',
        endpoint='player.playlist',
        filter=PlayListFile.detect
    )

    # register action buttons
    manager.register_widget(
        place='entry-actions',
        css='play',
        type='button',
        endpoint='player.audio',
        filter=PlayableFile.detect
    )
    manager.register_widget(
        place='entry-actions',
        css='play',
        type='button',
        endpoint='player.playlist',
        filter=PlayListFile.detect
    )

    # check argument (see `register_arguments`) before registering
    if manager.get_argument('player_directory_play'):
        # register header button
        manager.register_widget(
            place='header',
            type='button',
            endpoint='player.directory',
            text='Play directory',
            filter=PlayableDirectory.detect
            )

Response: Register plugin with given plugin manager.


Instruction:
Write a Python 3 function that can
make absolute path relative to an absolute base.

Response:
def relativize_path(path, base, os_sep=os.sep):
    '''
    Make absolute path relative to an absolute base.

    :param path: absolute path
    :type path: str
    :param base: absolute base path
    :type base: str
    :param os_sep: path component separator, defaults to current OS separator
    :type os_sep: str
    :return: relative path
    :rtype: str or unicode
    :raises OutsideDirectoryBase: if path is not below base
    '''
    if not check_base(path, base, os_sep):
        raise OutsideDirectoryBase("%r is not under %r" % (path, base))
    prefix_len = len(base)
    if not base.endswith(os_sep):
        prefix_len += len(os_sep)
    return path[prefix_len:]


Instruction:
Create a Python 3 function to
make filesystem absolute path uri relative using given absolute base path.

Response:
def abspath_to_urlpath(path, base, os_sep=os.sep):
    '''
    Make filesystem absolute path uri relative using given absolute base path.

    :param path: absolute path
    :param base: absolute base path
    :param os_sep: path component separator, defaults to current OS separator
    :return: relative uri
    :rtype: str or unicode
    :raises OutsideDirectoryBase: if resulting path is not below base
    '''
    return relativize_path(path, base, os_sep).replace(os_sep, '/')


Instruction:
Given the following Python 3 function, write the documentation
def urlpath_to_abspath(path, base, os_sep=os.sep):
    '''
    Make uri relative path fs absolute using a given absolute base path.

    :param path: relative path
    :param base: absolute base path
    :param os_sep: path component separator, defaults to current OS separator
    :return: absolute path
    :rtype: str or unicode
    :raises OutsideDirectoryBase: if resulting path is not below base
    '''
    prefix = base if base.endswith(os_sep) else base + os_sep
    realpath = os.path.abspath(prefix + path.replace('/', os_sep))
    if check_path(base, realpath) or check_under_base(realpath, base):
        return realpath
    raise OutsideDirectoryBase("%r is not under %r" % (realpath, base))

Response: Make uri relative path fs absolute using a given absolute base path.


Instruction:
Make a summary of the following Python 3 code
def generic_filename(path):
    '''
    Extract filename of given path os-indepently, taking care of known path
    separators.

    :param path: path
    :return: filename
    :rtype: str or unicode (depending on given path)
    '''

    for sep in common_path_separators:
        if sep in path:
            _, path = path.rsplit(sep, 1)
    return path

Response: Extract filename of given path os - indepently taking care of known path separators.


Instruction:
Can you create a Python 3 function that
cleans restricted characters in a path.

Response:
def clean_restricted_chars(path, restricted_chars=restricted_chars):
    '''
    Get path without restricted characters.

    :param path: path
    :return: path without restricted characters
    :rtype: str or unicode (depending on given path)
    '''
    for character in restricted_chars:
        path = path.replace(character, '_')
    return path


Instruction:
Write a Python 3 function for
checking if given filename is forbidden on current OS or filesystem.

Response:
def check_forbidden_filename(filename,
                             destiny_os=os.name,
                             restricted_names=restricted_names):
    '''
    Get if given filename is forbidden for current OS or filesystem.

    :param filename:
    :param destiny_os: destination operative system
    :param fs_encoding: destination filesystem filename encoding
    :return: wether is forbidden on given OS (or filesystem) or not
    :rtype: bool
    '''
    return (
      filename in restricted_names or
      destiny_os == 'nt' and
      filename.split('.', 1)[0].upper() in nt_device_names
      )


Instruction:
Can you tell what is the following Python 3 function doing
def check_path(path, base, os_sep=os.sep):
    '''
    Check if both given paths are equal.

    :param path: absolute path
    :type path: str
    :param base: absolute base path
    :type base: str
    :param os_sep: path separator, defaults to os.sep
    :type base: str
    :return: wether two path are equal or not
    :rtype: bool
    '''
    base = base[:-len(os_sep)] if base.endswith(os_sep) else base
    return os.path.normcase(path) == os.path.normcase(base)

Response: Checks if two given paths are equal.


Instruction:
Write a Python 3 script to
check if given absolute path is under given base.

Response:
def check_base(path, base, os_sep=os.sep):
    '''
    Check if given absolute path is under or given base.

    :param path: absolute path
    :type path: str
    :param base: absolute base path
    :type base: str
    :param os_sep: path separator, defaults to os.sep
    :return: wether path is under given base or not
    :rtype: bool
    '''
    return (
        check_path(path, base, os_sep) or
        check_under_base(path, base, os_sep)
        )


Instruction:
Make a summary of the following Python 3 code
def check_under_base(path, base, os_sep=os.sep):
    '''
    Check if given absolute path is under given base.

    :param path: absolute path
    :type path: str
    :param base: absolute base path
    :type base: str
    :param os_sep: path separator, defaults to os.sep
    :return: wether file is under given base or not
    :rtype: bool
    '''
    prefix = base if base.endswith(os_sep) else base + os_sep
    return os.path.normcase(path).startswith(os.path.normcase(prefix))

Response: Check if given absolute path is under given base.


Instruction:
Can you write a function in Python 3 where it
returns a secure filename for the given path.

Response:
def secure_filename(path, destiny_os=os.name, fs_encoding=compat.FS_ENCODING):
    '''
    Get rid of parent path components and special filenames.

    If path is invalid or protected, return empty string.

    :param path: unsafe path, only basename will be used
    :type: str
    :param destiny_os: destination operative system (defaults to os.name)
    :type destiny_os: str
    :param fs_encoding: fs path encoding (defaults to detected)
    :type fs_encoding: str
    :return: filename or empty string
    :rtype: str
    '''
    path = generic_filename(path)
    path = clean_restricted_chars(
        path,
        restricted_chars=(
            nt_restricted_chars
            if destiny_os == 'nt' else
            restricted_chars
            ))
    path = path.strip(' .')  # required by nt, recommended for others

    if check_forbidden_filename(path, destiny_os=destiny_os):
        return ''

    if isinstance(path, bytes):
        path = path.decode('latin-1', errors=underscore_replace)

    # Decode and recover from filesystem encoding in order to strip unwanted
    # characters out
    kwargs = {
        'os_name': destiny_os,
        'fs_encoding': fs_encoding,
        'errors': underscore_replace,
        }
    fs_encoded_path = compat.fsencode(path, **kwargs)
    fs_decoded_path = compat.fsdecode(fs_encoded_path, **kwargs)
    return fs_decoded_path


Instruction:
Explain what the following Python 3 code does
def alternative_filename(filename, attempt=None):
    '''
    Generates an alternative version of given filename.

    If an number attempt parameter is given, will be used on the alternative
    name, a random value will be used otherwise.

    :param filename: original filename
    :param attempt: optional attempt number, defaults to null
    :return: new filename
    :rtype: str or unicode
    '''
    filename_parts = filename.rsplit(u'.', 2)
    name = filename_parts[0]
    ext = ''.join(u'.%s' % ext for ext in filename_parts[1:])
    if attempt is None:
        choose = random.choice
        extra = u' %s' % ''.join(choose(fs_safe_characters) for i in range(8))
    else:
        extra = u' (%d)' % attempt
    return u'%s%s%s' % (name, extra, ext)

Response: Generates an alternative version of given filename.


Instruction:
How would you explain what the following Python 3 function does
def scandir(path, app=None):
    '''
    Config-aware scandir. Currently, only aware of ``exclude_fnc``.

    :param path: absolute path
    :type path: str
    :param app: flask application
    :type app: flask.Flask or None
    :returns: filtered scandir entries
    :rtype: iterator
    '''
    exclude = app and app.config.get('exclude_fnc')
    if exclude:
        return (
            item
            for item in compat.scandir(path)
            if not exclude(item.path)
            )
    return compat.scandir(path)

Response: Config - aware scandir. Currently only aware of exclude_fnc.


Instruction:
Write a Python 3 function that can
return True if current node should be shown False otherwise.

Response:
def is_excluded(self):
        '''
        Get if current node shouldn't be shown, using :attt:`app` config's
        exclude_fnc.

        :returns: True if excluded, False otherwise
        '''
        exclude = self.app and self.app.config['exclude_fnc']
        return exclude and exclude(self.path)


Instruction:
Create a Python 3 function for
returning a list of namedtuples containing the widgets that are available for this node.

Response:
def widgets(self):
        '''
        List widgets with filter return True for this node (or without filter).

        Remove button is prepended if :property:can_remove returns true.

        :returns: list of widgets
        :rtype: list of namedtuple instances
        '''
        widgets = []
        if self.can_remove:
            widgets.append(
                self.plugin_manager.create_widget(
                    'entry-actions',
                    'button',
                    file=self,
                    css='remove',
                    endpoint='remove'
                    )
                )
        return widgets + self.plugin_manager.get_widgets(file=self)


Instruction:
Here you have a function in Python 3, explain what it does
def link(self):
        '''
        Get last widget with place "entry-link".

        :returns: widget on entry-link (ideally a link one)
        :rtype: namedtuple instance
        '''
        link = None
        for widget in self.widgets:
            if widget.place == 'entry-link':
                link = widget
        return link

Response: Get last widget with place entry - link.


Instruction:
Given the following Python 3 function, write the documentation
def can_remove(self):
        '''
        Get if current node can be removed based on app config's
        directory_remove.

        :returns: True if current node can be removed, False otherwise.
        :rtype: bool
        '''
        dirbase = self.app.config["directory_remove"]
        return bool(dirbase and check_under_base(self.path, dirbase))

Response:
Returns True if current node can be removed based on app config s
        directory_remove.


Instruction:
Here you have a function in Python 3, explain what it does
def parent(self):
        '''
        Get parent node if available based on app config's directory_base.

        :returns: parent object if available
        :rtype: Node instance or None
        '''
        if check_path(self.path, self.app.config['directory_base']):
            return None
        parent = os.path.dirname(self.path) if self.path else None
        return self.directory_class(parent, self.app) if parent else None

Response: Get parent node if available based on app config s directory_base.


Instruction:
How would you explain what the following Python 3 function does
def ancestors(self):
        '''
        Get list of ancestors until app config's directory_base is reached.

        :returns: list of ancestors starting from nearest.
        :rtype: list of Node objects
        '''
        ancestors = []
        parent = self.parent
        while parent:
            ancestors.append(parent)
            parent = parent.parent
        return ancestors

Response: Get list of ancestors until app config s directory_base is reached.


Instruction:
How would you implement a function in Python 3 that
gets human - readable last modification date - time.

Response:
def modified(self):
        '''
        Get human-readable last modification date-time.

        :returns: iso9008-like date-time string (without timezone)
        :rtype: str
        '''
        try:
            dt = datetime.datetime.fromtimestamp(self.stats.st_mtime)
            return dt.strftime('%Y.%m.%d %H:%M:%S')
        except OSError:
            return None


Instruction:
Given the following Python 3 function, write the documentation
def from_urlpath(cls, path, app=None):
        '''
        Alternative constructor which accepts a path as taken from URL and uses
        the given app or the current app config to get the real path.

        If class has attribute `generic` set to True, `directory_class` or
        `file_class` will be used as type.

        :param path: relative path as from URL
        :param app: optional, flask application
        :return: file object pointing to path
        :rtype: File
        '''
        app = app or current_app
        base = app.config['directory_base']
        path = urlpath_to_abspath(path, base)
        if not cls.generic:
            kls = cls
        elif os.path.isdir(path):
            kls = cls.directory_class
        else:
            kls = cls.file_class
        return kls(path=path, app=app)

Response:
Alternative constructor which accepts a path as taken from URL and uses
        the given app or current app config to get the real path.


Instruction:
How would you explain what the following Python 3 function does
def _find_paths(self, current_dir, patterns):
        pattern = patterns[0]
        patterns = patterns[1:]
        has_wildcard = is_pattern(pattern)
        using_globstar = pattern == "**"

        # This avoids os.listdir() for performance
        if has_wildcard:
            entries = [x.name for x in scandir(current_dir)]
        else:
            entries = [pattern]

        if using_globstar:
            matching_subdirs = map(lambda x: x[0], walk(current_dir))
        else:
            subdirs = [e for e in entries
                       if os.path.isdir(os.path.join(current_dir, e))]
            matching_subdirs = match_entries(subdirs, pattern)

        # For terminal globstar, add a pattern for all files in subdirs
        if using_globstar and not patterns:
            patterns = ['*']

        if patterns:  # we've still got more directories to traverse
            for subdir in matching_subdirs:
                absolute_path = os.path.join(current_dir, subdir)
                for match in self._find_paths(absolute_path, patterns):
                    yield match

        else:  # we've got the last pattern
            if not has_wildcard:
                entries = [pattern + '.wsp', pattern + '.wsp.gz']
            files = [e for e in entries
                     if os.path.isfile(os.path.join(current_dir, e))]
            matching_files = match_entries(files, pattern + '.*')

            for _basename in matching_files + matching_subdirs:
                yield os.path.join(current_dir, _basename)

Response:
Recursively generates absolute paths whose components
AttributeNames underneath current_dir match the corresponding pattern in patterns


Instruction:
Can you tell what is the following Python 3 function doing
def union_overlapping(intervals):
    disjoint_intervals = []

    for interval in intervals:
        if disjoint_intervals and disjoint_intervals[-1].overlaps(interval):
            disjoint_intervals[-1] = disjoint_intervals[-1].union(interval)
        else:
            disjoint_intervals.append(interval)

    return disjoint_intervals

Response: Union any overlapping intervals in the given set.


Instruction:
Given the following Python 3 function, write the documentation
def recurse(query, index):
    for node in app.store.find(query):
        if node.is_leaf:
            index.add(node.path)
        else:
            recurse('{0}.*'.format(node.path), index)

Response: Recursively walk across paths adding leaves to the index as they re found.


Instruction:
Implement a function in Python 3 to
set the aggregation method of the file at the given path.

Response:
def setAggregationMethod(path, aggregationMethod, xFilesFactor=None):
  """setAggregationMethod(path,aggregationMethod,xFilesFactor=None)

path is a string
aggregationMethod specifies the method to use when propagating data (see ``whisper.aggregationMethods``)
xFilesFactor specifies the fraction of data points in a propagation interval that must have known values for a propagation to occur.  If None, the existing xFilesFactor in path will not be changed
"""
  fh = None
  try:

    fh = open(path,'r+b')
    if LOCK:
      fcntl.flock( fh.fileno(), fcntl.LOCK_EX )

    packedMetadata = fh.read(metadataSize)

    try:
      (aggregationType,maxRetention,xff,archiveCount) = struct.unpack(metadataFormat,packedMetadata)
    except:
      raise CorruptWhisperFile("Unable to read header", fh.name)

    try:
      newAggregationType = struct.pack( longFormat, aggregationMethodToType[aggregationMethod] )
    except KeyError:
      raise InvalidAggregationMethod("Unrecognized aggregation method: %s" %
            aggregationMethod)

    if xFilesFactor is not None:
        #use specified xFilesFactor
        xff = struct.pack( floatFormat, float(xFilesFactor) )
    else:
	#retain old value
        xff = struct.pack( floatFormat, xff )

    #repack the remaining header information
    maxRetention = struct.pack( longFormat, maxRetention )
    archiveCount = struct.pack(longFormat, archiveCount)

    packedMetadata = newAggregationType + maxRetention + xff + archiveCount
    fh.seek(0)
    #fh.write(newAggregationType)
    fh.write(packedMetadata)

    if AUTOFLUSH:
      fh.flush()
      os.fsync(fh.fileno())

      if CACHE_HEADERS and fh.name in __headerCache:
        del __headerCache[fh.name]

  finally:
    if fh:
      fh.close()

  return aggregationTypeToMethod.get(aggregationType, 'average')


Instruction:
Create a Python 3 function to
validate an archiveList. An ArchiveList must: 1. Have at least one archive config. Example: (60, 86400) 2. No archive may be a duplicate of another. 3. Higher precision archives' precision must evenly divide all lower precision archives' precision. 4. Lower precision archives must cover larger time intervals than higher precision archives. 5. Each archive must have at least enough points to consolidate to the next archive Returns True or False

Response:
def validateArchiveList(archiveList):
  """ Validates an archiveList.
  An ArchiveList must:
  1. Have at least one archive config. Example: (60, 86400)
  2. No archive may be a duplicate of another.
  3. Higher precision archives' precision must evenly divide all lower precision archives' precision.
  4. Lower precision archives must cover larger time intervals than higher precision archives.
  5. Each archive must have at least enough points to consolidate to the next archive

  Returns True or False
  """

  if not archiveList:
    raise InvalidConfiguration("You must specify at least one archive configuration!")

  archiveList = sorted(archiveList, key=lambda a: a[0]) #sort by precision (secondsPerPoint)

  for i,archive in enumerate(archiveList):
    if i == len(archiveList) - 1:
      break

    nextArchive = archiveList[i+1]
    if not archive[0] < nextArchive[0]:
      raise InvalidConfiguration("A Whisper database may not configured having"
        "two archives with the same precision (archive%d: %s, archive%d: %s)" %
        (i, archive, i + 1, nextArchive))

    if nextArchive[0] % archive[0] != 0:
      raise InvalidConfiguration("Higher precision archives' precision "
        "must evenly divide all lower precision archives' precision "
        "(archive%d: %s, archive%d: %s)" %
        (i, archive[0], i + 1, nextArchive[0]))

    retention = archive[0] * archive[1]
    nextRetention = nextArchive[0] * nextArchive[1]

    if not nextRetention > retention:
      raise InvalidConfiguration("Lower precision archives must cover "
        "larger time intervals than higher precision archives "
        "(archive%d: %s seconds, archive%d: %s seconds)" %
        (i, retention, i + 1, nextRetention))

    archivePoints = archive[1]
    pointsPerConsolidation = nextArchive[0] // archive[0]
    if not archivePoints >= pointsPerConsolidation:
      raise InvalidConfiguration("Each archive must have at least enough points "
        "to consolidate to the next archive (archive%d consolidates %d of "
        "archive%d's points but it has only %d total points)" %
        (i + 1, pointsPerConsolidation, i, archivePoints))


Instruction:
Create a Python 3 function for
creating a new file in the Whisper file system.

Response:
def create(path,archiveList,xFilesFactor=None,aggregationMethod=None,sparse=False,useFallocate=False):
  """create(path,archiveList,xFilesFactor=0.5,aggregationMethod='average')

path is a string
archiveList is a list of archives, each of which is of the form (secondsPerPoint,numberOfPoints)
xFilesFactor specifies the fraction of data points in a propagation interval that must have known values for a propagation to occur
aggregationMethod specifies the function to use when propagating data (see ``whisper.aggregationMethods``)
"""
  # Set default params
  if xFilesFactor is None:
    xFilesFactor = 0.5
  if aggregationMethod is None:
    aggregationMethod = 'average'

  #Validate archive configurations...
  validateArchiveList(archiveList)

  #Looks good, now we create the file and write the header
  if os.path.exists(path):
    raise InvalidConfiguration("File %s already exists!" % path)
  fh = None
  try:
    fh = open(path,'wb')
    if LOCK:
      fcntl.flock( fh.fileno(), fcntl.LOCK_EX )

    aggregationType = struct.pack( longFormat, aggregationMethodToType.get(aggregationMethod, 1) )
    oldest = max([secondsPerPoint * points for secondsPerPoint,points in archiveList])
    maxRetention = struct.pack( longFormat, oldest )
    xFilesFactor = struct.pack( floatFormat, float(xFilesFactor) )
    archiveCount = struct.pack(longFormat, len(archiveList))
    packedMetadata = aggregationType + maxRetention + xFilesFactor + archiveCount
    fh.write(packedMetadata)
    headerSize = metadataSize + (archiveInfoSize * len(archiveList))
    archiveOffsetPointer = headerSize

    for secondsPerPoint,points in archiveList:
      archiveInfo = struct.pack(archiveInfoFormat, archiveOffsetPointer, secondsPerPoint, points)
      fh.write(archiveInfo)
      archiveOffsetPointer += (points * pointSize)

    #If configured to use fallocate and capable of fallocate use that, else
    #attempt sparse if configure or zero pre-allocate if sparse isn't configured.
    if CAN_FALLOCATE and useFallocate:
      remaining = archiveOffsetPointer - headerSize
      fallocate(fh, headerSize, remaining)
    elif sparse:
      fh.seek(archiveOffsetPointer - 1)
      fh.write('\x00')
    else:
      remaining = archiveOffsetPointer - headerSize
      chunksize = 16384
      zeroes = b'\x00' * chunksize
      while remaining > chunksize:
        fh.write(zeroes)
        remaining -= chunksize
      fh.write(zeroes[:remaining])

    if AUTOFLUSH:
      fh.flush()
      os.fsync(fh.fileno())
  finally:
    if fh:
      fh.close()


Instruction:
Write a Python 3 function for
updating a file in the formula

Response:
def update(path,value,timestamp=None):
  """update(path,value,timestamp=None)

path is a string
value is a float
timestamp is either an int or float
"""
  value = float(value)
  fh = None
  try:
    fh = open(path,'r+b')
    return file_update(fh, value, timestamp)
  finally:
    if fh:
      fh.close()


Instruction:
Can you implement a function in Python 3 that
fetches returns a tuple of timeInfo and valueList for the file at path

Response:
def fetch(path,fromTime,untilTime=None,now=None):
  """fetch(path,fromTime,untilTime=None)

path is a string
fromTime is an epoch time
untilTime is also an epoch time, but defaults to now.

Returns a tuple of (timeInfo, valueList)
where timeInfo is itself a tuple of (fromTime, untilTime, step)

Returns None if no data can be returned
"""
  fh = None
  try:
    fh = open(path,'rb')
    return file_fetch(fh, fromTime, untilTime, now)
  finally:
    if fh:
      fh.close()


Instruction:
Given the following Python 3 function, write the documentation
def __archive_fetch(fh, archive, fromTime, untilTime):
  fromInterval = int( fromTime - (fromTime % archive['secondsPerPoint']) ) + archive['secondsPerPoint']
  untilInterval = int( untilTime - (untilTime % archive['secondsPerPoint']) ) + archive['secondsPerPoint']
  if fromInterval == untilInterval:
    # Zero-length time range: always include the next point
    untilInterval += archive['secondsPerPoint']
  fh.seek(archive['offset'])
  packedPoint = fh.read(pointSize)
  (baseInterval,baseValue) = struct.unpack(pointFormat,packedPoint)

  if baseInterval == 0:
    step = archive['secondsPerPoint']
    points = (untilInterval - fromInterval) // step
    timeInfo = (fromInterval,untilInterval,step)
    valueList = [None] * points
    return (timeInfo,valueList)

  #Determine fromOffset
  timeDistance = fromInterval - baseInterval
  pointDistance = timeDistance // archive['secondsPerPoint']
  byteDistance = pointDistance * pointSize
  fromOffset = archive['offset'] + (byteDistance % archive['size'])

  #Determine untilOffset
  timeDistance = untilInterval - baseInterval
  pointDistance = timeDistance // archive['secondsPerPoint']
  byteDistance = pointDistance * pointSize
  untilOffset = archive['offset'] + (byteDistance % archive['size'])

  #Read all the points in the interval
  fh.seek(fromOffset)
  if fromOffset < untilOffset: #If we don't wrap around the archive
    seriesString = fh.read(untilOffset - fromOffset)
  else: #We do wrap around the archive, so we need two reads
    archiveEnd = archive['offset'] + archive['size']
    seriesString = fh.read(archiveEnd - fromOffset)
    fh.seek(archive['offset'])
    seriesString += fh.read(untilOffset - archive['offset'])

  #Now we unpack the series data we just read (anything faster than unpack?)
  byteOrder,pointTypes = pointFormat[0],pointFormat[1:]
  points = len(seriesString) // pointSize
  seriesFormat = byteOrder + (pointTypes * points)
  unpackedSeries = struct.unpack(seriesFormat, seriesString)

  #And finally we construct a list of values (optimize this!)
  valueList = [None] * points #pre-allocate entire list for speed
  currentInterval = fromInterval
  step = archive['secondsPerPoint']

  for i in xrange(0,len(unpackedSeries),2):
    pointTime = unpackedSeries[i]
    if pointTime == currentInterval:
      pointValue = unpackedSeries[i+1]
      valueList[i//2] = pointValue #in-place reassignment is faster than append()
    currentInterval += step

  timeInfo = (fromInterval,untilInterval,step)
  return (timeInfo,valueList)

Response: Fetch data from a single archive.


Instruction:
Can you create a Python 3 function that
merges the data from one whisper file into another.

Response:
def merge(path_from, path_to):
  """ Merges the data from one whisper file into another. Each file must have
  the same archive configuration
"""
  fh_from = open(path_from, 'rb')
  fh_to = open(path_to, 'rb+')
  return file_merge(fh_from, fh_to)


Instruction:
Make a summary of the following Python 3 code
def diff(path_from, path_to, ignore_empty = False):
  fh_from = open(path_from, 'rb')
  fh_to = open(path_to, 'rb')
  diffs = file_diff(fh_from, fh_to, ignore_empty)
  fh_to.close()
  fh_from.close()
  return diffs

Response: Compare two whisper databases.


Instruction:
Write a Python 3 script to
add data to the time series

Response:
def add_data(self, path, time_info, data, exprs):
        """
        Stores data before it can be put into a time series
        """
        # Dont add if empty
        if not nonempty(data):
            for d in self.data[path]:
                if nonempty(d['values']):
                    return

        # Add data to path
        for expr in exprs:
            self.paths[expr].add(path)
        self.data[path].append({
            'time_info': time_info,
            'values': data
        })


Instruction:
Given the following Python 3 function, write the documentation
def extract_variants(pattern):
    v1, v2 = pattern.find('{'), pattern.find('}')
    if v1 > -1 and v2 > v1:
        variations = pattern[v1+1:v2].split(',')
        variants = [pattern[:v1] + v + pattern[v2+1:] for v in variations]
    else:
        variants = [pattern]
    return list(_deduplicate(variants))

Response: Extract the variants from a pattern.


Instruction:
Here you have a function in Python 3, explain what it does
def match_entries(entries, pattern):
    matching = []

    for variant in expand_braces(pattern):
        matching.extend(fnmatch.filter(entries, variant))

    return list(_deduplicate(matching))

Response:
A drop - in replacement for fnmatch. filter that supports pattern
    variants.


Instruction:
Here you have a function in Python 3, explain what it does
def expand_braces(pattern):
    res = set()

    # Used instead of s.strip('{}') because strip is greedy.
    # We want to remove only ONE leading { and ONE trailing }, if both exist
    def remove_outer_braces(s):
        if s[0] == '{' and s[-1] == '}':
            return s[1:-1]
        return s

    match = EXPAND_BRACES_RE.search(pattern)
    if match is not None:
        sub = match.group(1)
        v1, v2 = match.span(1)
        if "," in sub:
            for pat in sub.strip('{}').split(','):
                subpattern = pattern[:v1] + pat + pattern[v2:]
                res.update(expand_braces(subpattern))
        else:
            subpattern = pattern[:v1] + remove_outer_braces(sub) + pattern[v2:]
            res.update(expand_braces(subpattern))
    else:
        res.add(pattern.replace('\\}', '}'))

    return list(res)

Response: Find the rightmost innermost set of braces and expand its contents recursively.


Instruction:
Make a summary of the following Python 3 code
def select_host(self, metric):
        key = self.keyfunc(metric)
        nodes = []
        servers = set()
        for node in self.hash_ring.get_nodes(key):
            server, instance = node
            if server in servers:
                continue
            servers.add(server)
            nodes.append(node)
            if len(servers) >= self.replication_factor:
                break
        available = [n for n in nodes if self.is_available(n)]
        return random.choice(available or nodes)

Response: Returns the carbon host that has data for the given metric.


Instruction:
Can you implement a function in Python 3 that
iterates over valid finite values in an iterable.

Response:
def safeArgs(args):
    """Iterate over valid, finite values in an iterable.

    Skip any items that are None, NaN, or infinite.
    """
    return (arg for arg in args
            if arg is not None and not math.isnan(arg) and not math.isinf(arg))


Instruction:
Given the following Python 3 function, write the documentation
def dataLimits(data, drawNullAsZero=False, stacked=False):
    missingValues = any(None in series for series in data)
    finiteData = [series for series in data
                  if not series.options.get('drawAsInfinite')]

    yMinValue = safeMin(safeMin(series) for series in finiteData)

    if yMinValue is None:
        # This can only happen if there are no valid, non-infinite data.
        return (0.0, 1.0)

    if yMinValue > 0.0 and drawNullAsZero and missingValues:
        yMinValue = 0.0

    if stacked:
        length = safeMin(len(series) for series in finiteData)
        sumSeries = []

        for i in range(0, length):
            sumSeries.append(safeSum(series[i] for series in finiteData))
        yMaxValue = safeMax(sumSeries)
    else:
        yMaxValue = safeMax(safeMax(series) for series in finiteData)

    if yMaxValue < 0.0 and drawNullAsZero and missingValues:
        yMaxValue = 0.0

    return (yMinValue, yMaxValue)

Response: Return the range of values in data as yMinValue yMaxValue.


Instruction:
Can you create a Python 3 function that
formats the given value in standardized units.

Response:
def format_units(v, step=None, system="si", units=None):
    """Format the given value in standardized units.

    ``system`` is either 'binary' or 'si'

    For more info, see:
        http://en.wikipedia.org/wiki/SI_prefix
        http://en.wikipedia.org/wiki/Binary_prefix
    """
    if v is None:
        return 0, ''

    for prefix, size in UnitSystems[system]:
        if condition(v, size, step):
            v2 = v / size
            if v2 - math.floor(v2) < 0.00000000001 and v > 1:
                v2 = float(math.floor(v2))
            if units:
                prefix = "%s%s" % (prefix, units)
            return v2, prefix

    if v - math.floor(v) < 0.00000000001 and v > 1:
        v = float(math.floor(v))
    if units:
        prefix = units
    else:
        prefix = ''
    return v, prefix


Instruction:
How would you implement a function in Python 3 that
checks that value is a finite number.

Response:
def checkFinite(value, name='value'):
        """Check that value is a finite number.

        If it is, return it. If not, raise GraphError describing the
        problem, using name in the error message.
        """
        if math.isnan(value):
            raise GraphError('Encountered NaN %s' % (name,))
        elif math.isinf(value):
            raise GraphError('Encountered infinite %s' % (name,))
        return value


Instruction:
Given the following Python 3 function, write the documentation
def reconcileLimits(self):
        if self.minValue < self.maxValue:
            # The limits are already OK.
            return

        minFixed = (self.minValueSource in ['min'])
        maxFixed = (self.maxValueSource in ['max', 'limit'])

        if minFixed and maxFixed:
            raise GraphError('The %s must be less than the %s' %
                             (self.minValueSource, self.maxValueSource))
        elif minFixed:
            self.maxValue = self.minValue + self.chooseDelta(self.minValue)
        elif maxFixed:
            self.minValue = self.maxValue - self.chooseDelta(self.maxValue)
        else:
            delta = self.chooseDelta(max(abs(self.minValue),
                                         abs(self.maxValue)))
            average = (self.minValue + self.maxValue) / 2.0
            self.minValue = average - delta
            self.maxValue = average + delta

Response: Reconciles the limits of the current value with the values of the current value.


Instruction:
Implement a function in Python 3 to
apply the specified settings to the current axis.

Response:
def applySettings(self, axisMin=None, axisMax=None, axisLimit=None):
        """Apply the specified settings to this axis.

        Set self.minValue, self.minValueSource, self.maxValue,
        self.maxValueSource, and self.axisLimit reasonably based on the
        parameters provided.

        Arguments:

        axisMin -- a finite number, or None to choose a round minimum
            limit that includes all of the data.

        axisMax -- a finite number, 'max' to use the maximum value
            contained in the data, or None to choose a round maximum limit
            that includes all of the data.

        axisLimit -- a finite number to use as an upper limit on maxValue,
            or None to impose no upper limit.
        """
        if axisMin is not None and not math.isnan(axisMin):
            self.minValueSource = 'min'
            self.minValue = self.checkFinite(axisMin, 'axis min')

        if axisMax == 'max':
            self.maxValueSource = 'extremum'
        elif axisMax is not None and not math.isnan(axisMax):
            self.maxValueSource = 'max'
            self.maxValue = self.checkFinite(axisMax, 'axis max')

        if axisLimit is None or math.isnan(axisLimit):
            self.axisLimit = None
        elif axisLimit < self.maxValue:
            self.maxValue = self.checkFinite(axisLimit, 'axis limit')
            self.maxValueSource = 'limit'
            # The limit has already been imposed, so there is no need to
            # remember it:
            self.axisLimit = None
        elif math.isinf(axisLimit):
            # It must be positive infinity, which is the same as no limit:
            self.axisLimit = None
        else:
            # We still need to remember axisLimit to avoid rounding top to
            # a value larger than axisLimit:
            self.axisLimit = axisLimit

        self.reconcileLimits()


Instruction:
Given the following Python 3 function, write the documentation
def makeLabel(self, value):
        value, prefix = format_units(value, self.step,
                                     system=self.unitSystem)
        span, spanPrefix = format_units(self.span, self.step,
                                        system=self.unitSystem)
        if prefix:
            prefix += " "
        if value < 0.1:
            return "%g %s" % (float(value), prefix)
        elif value < 1.0:
            return "%.2f %s" % (float(value), prefix)
        if span > 10 or spanPrefix != prefix:
            if type(value) is float:
                return "%.1f %s" % (value, prefix)
            else:
                return "%d %s" % (int(value), prefix)
        elif span > 3:
            return "%.1f %s" % (float(value), prefix)
        elif span > 0.1:
            return "%.2f %s" % (float(value), prefix)
        else:
            return "%g %s" % (float(value), prefix)

Response: Create a label for the specified value.


Instruction:
Can you create a Python 3 function that
generates allowed steps with step < = minStep in increasing order.

Response:
def generateSteps(self, minStep):
        """Generate allowed steps with step >= minStep in increasing order."""
        self.checkFinite(minStep)

        if self.binary:
            base = 2.0
            mantissas = [1.0]
            exponent = math.floor(math.log(minStep, 2) - EPSILON)
        else:
            base = 10.0
            mantissas = [1.0, 2.0, 5.0]
            exponent = math.floor(math.log10(minStep) - EPSILON)

        while True:
            multiplier = base ** exponent
            for mantissa in mantissas:
                value = mantissa * multiplier
                if value >= minStep * (1.0 - EPSILON):
                    yield value
            exponent += 1


Instruction:
Can you generate the documentation for the following Python 3 function
def computeSlop(self, step, divisor):
        bottom = step * math.floor(self.minValue / float(step) + EPSILON)
        top = bottom + step * divisor

        if top >= self.maxValue - EPSILON * step:
            return max(top - self.maxValue, self.minValue - bottom)
        else:
            return None

Response: Compute the slop that would result from step and divisor.


Instruction:
Write a Python 3 script for
choosing a nice pretty size for the steps between axis labels.

Response:
def chooseStep(self, divisors=None, binary=False):
        """Choose a nice, pretty size for the steps between axis labels.

        Our main constraint is that the number of divisions must be taken
        from the divisors list. We pick a number of divisions and a step
        size that minimizes the amount of whitespace ("slop") that would
        need to be included outside of the range [self.minValue,
        self.maxValue] if we were to push out the axis values to the next
        larger multiples of the step size.

        The minimum step that could possibly cover the variance satisfies

            minStep * max(divisors) >= variance

        or

            minStep = variance / max(divisors)

        It's not necessarily possible to cover the variance with a step
        that size, but we know that any smaller step definitely *cannot*
        cover it. So we can start there.

        For a sufficiently large step size, it is definitely possible to
        cover the variance, but at some point the slop will start growing.
        Let's define the slop to be

            slop = max(minValue - bottom, top - maxValue)

        Then for a given, step size, we know that

            slop >= (1/2) * (step * min(divisors) - variance)

        (the factor of 1/2 is for the best-case scenario that the slop is
        distributed equally on the two sides of the range). So suppose we
        already have a choice that yields bestSlop. Then there is no need
        to choose steps so large that the slop is guaranteed to be larger
        than bestSlop. Therefore, the maximum step size that we need to
        consider is

            maxStep = (2 * bestSlop + variance) / min(divisors)

        """
        self.binary = binary
        if divisors is None:
            divisors = [4, 5, 6]
        else:
            for divisor in divisors:
                self.checkFinite(divisor, 'divisor')
                if divisor < 1:
                    raise GraphError('Divisors must be greater than or equal '
                                     'to one')

        if self.minValue == self.maxValue:
            if self.minValue == 0.0:
                self.maxValue = 1.0
            elif self.minValue < 0.0:
                self.minValue *= 1.1
                self.maxValue *= 0.9
            else:
                self.minValue *= 0.9
                self.maxValue *= 1.1

        variance = self.maxValue - self.minValue

        bestSlop = None
        bestStep = None
        for step in self.generateSteps(variance / float(max(divisors))):
            if (
                bestSlop is not None and
                step * min(divisors) >= 2 * bestSlop + variance
            ):
                break
            for divisor in divisors:
                slop = self.computeSlop(step, divisor)
                if slop is not None and (bestSlop is None or slop < bestSlop):
                    bestSlop = slop
                    bestStep = step

        self.step = bestStep


Instruction:
Can you write a function in Python 3 where it
returns a comma - separated list of unique path expressions.

Response:
def formatPathExpressions(seriesList):
    """
    Returns a comma-separated list of unique path expressions.
    """
    pathExpressions = sorted(set([s.pathExpression for s in seriesList]))
    return ','.join(pathExpressions)


Instruction:
Can you write a function in Python 3 where it
shorts form: sum() This will add metrics together and return the sum at each datapoint. (See integral for a sum over time) Example:: &target=sum(company.server.application*.requestsHandled) This would show the sum of all requests handled per minute (provided requestsHandled are collected once a minute). If metrics with different retention rates are combined, the coarsest metric is graphed, and the sum of the other metrics is averaged for the metrics with finer retention rates.

Response:
def sumSeries(requestContext, *seriesLists):
    """
    Short form: sum()

    This will add metrics together and return the sum at each datapoint. (See
    integral for a sum over time)

    Example::

        &target=sum(company.server.application*.requestsHandled)

    This would show the sum of all requests handled per minute (provided
    requestsHandled are collected once a minute).     If metrics with different
    retention rates are combined, the coarsest metric is graphed, and the sum
    of the other metrics is averaged for the metrics with finer retention
    rates.

    """
    if not seriesLists or not any(seriesLists):
        return []
    seriesList, start, end, step = normalize(seriesLists)
    name = "sumSeries(%s)" % formatPathExpressions(seriesList)
    values = (safeSum(row) for row in zip_longest(*seriesList))
    series = TimeSeries(name, start, end, step, values)
    series.pathExpression = name
    return [series]


Instruction:
Create a Python 3 function for
summing the given seriesList with wildcards at the given positions.

Response:
def sumSeriesWithWildcards(requestContext, seriesList, *positions):
    """
    Call sumSeries after inserting wildcards at the given position(s).

    Example::

        &target=sumSeriesWithWildcards(host.cpu-[0-7].cpu-{user,system}.value,
                                       1)

    This would be the equivalent of::

        &target=sumSeries(host.*.cpu-user.value)&target=sumSeries(
            host.*.cpu-system.value)

    """
    newSeries = {}
    newNames = list()

    for series in seriesList:
        newname = '.'.join(map(lambda x: x[1],
                               filter(lambda i: i[0] not in positions,
                                      enumerate(series.name.split('.')))))
        if newname in newSeries:
            newSeries[newname] = sumSeries(requestContext,
                                           (series, newSeries[newname]))[0]
        else:
            newSeries[newname] = series
            newNames.append(newname)
        newSeries[newname].name = newname

    return [newSeries[name] for name in newNames]


Instruction:
Here you have a function in Python 3, explain what it does
def averageSeriesWithWildcards(requestContext, seriesList, *positions):
    matchedList = defaultdict(list)
    for series in seriesList:
        newname = '.'.join(map(lambda x: x[1],
                               filter(lambda i: i[0] not in positions,
                                      enumerate(series.name.split('.')))))
        matchedList[newname].append(series)
    result = []
    for name in matchedList:
        [series] = averageSeries(requestContext, (matchedList[name]))
        series.name = name
        result.append(series)
    return result

Response: Augment a seriesList with wildcards at the given positions.