Instruction:
Write a Python 3 function that can
return the rendition for this image generating it if necessary.

Response:
def get_rendition(self, output_scale=1, **kwargs):
        # pylint:disable=too-many-locals
        """
        Get the rendition for this image, generating it if necessary.
        Returns a tuple of `(relative_path, width, height)`, where relative_path
        is relative to the static file directory (i.e. what one would pass into
        `get_static()`)

        output_scale -- the upsample factor for the requested rendition

        Keyword arguments:

        scale -- the downsample factor for the base rendition
        scale_min_width -- the minimum width after downsampling
        scale_min_height -- the minimum height after downsampling
        crop -- box to crop the original image into (left, top, right, bottom)
        width -- the width to target
        height -- the height to target
        max_width -- the maximum width
        max_height -- the maximum height
        resize -- how to fit the width and height; "fit", "fill", or "stretch"
        fill_crop_x -- horizontal offset fraction for resize="fill"
        fill_crop_y -- vertical offset fraction for resize="fill"
        format -- output format
        background -- background color when converting transparent to opaque
        quality -- the JPEG quality to save the image as
        quantize -- how large a palette to use for GIF or PNG images
        """

        basename, ext = os.path.splitext(
            os.path.basename(self._record.file_path))
        basename = utils.make_slug(basename)

        if kwargs.get('format'):
            ext = '.' + kwargs['format']

        # The spec for building the output filename
        out_spec = [basename, self._record.checksum[-10:]]

        out_args = {}
        if ext in ['.png', '.jpg', '.jpeg']:
            out_args['optimize'] = True

        crop = self._parse_tuple_string(kwargs.get('crop'))

        size, box = self.get_rendition_size(kwargs, output_scale, crop)
        box = self._adjust_crop_box(box, crop)

        if size and (size[0] < self._record.width or size[1] < self._record.height):
            out_spec.append('x'.join([str(v) for v in size]))

        if box:
            # pylint:disable=not-an-iterable
            out_spec.append('-'.join([str(v) for v in box]))

        # Set RGBA flattening options
        flatten = self._record.transparent and ext not in ['.png', '.gif']
        if flatten and 'background' in kwargs:
            bg_color = kwargs['background']
            if isinstance(bg_color, (tuple, list)):
                out_spec.append('b' + '-'.join([str(a) for a in bg_color]))
            else:
                out_spec.append('b' + str(bg_color))

        # Set JPEG quality
        if ext in ('.jpg', '.jpeg') and kwargs.get('quality'):
            out_spec.append('q' + str(kwargs['quality']))
            out_args['quality'] = kwargs['quality']
        if ext in ('.jpg', '.jpeg'):
            out_args['optimize'] = True

        # Build the output filename
        out_basename = '_'.join([str(s) for s in out_spec]) + ext
        out_rel_path = os.path.join(
            config.image_output_subdir,
            self._record.checksum[0:2],
            self._record.checksum[2:6],
            out_basename)
        out_fullpath = os.path.join(config.static_folder, out_rel_path)

        if os.path.isfile(out_fullpath):
            os.utime(out_fullpath)
            return utils.static_url(out_rel_path, kwargs.get('absolute')), size

        LocalImage.thread_pool().submit(
            self._render, out_fullpath, size, box, flatten, kwargs, out_args)

        return flask.url_for('async', filename=out_rel_path, _external=kwargs.get('absolute')), size


Instruction:
Can you tell what is the following Python 3 function doing
def _adjust_crop_box(box, crop):

        if crop and box:
            # Both boxes are the same size; just line them up.
            return (box[0] + crop[0], box[1] + crop[1],
                    box[2] + crop[0], box[3] + crop[1])

        if crop:
            # We don't have a fit box, so just convert the crop box
            return (crop[0], crop[1], crop[0] + crop[2], crop[1] + crop[3])

        # We don't have a crop box, so return the fit box (even if it's None)
        return box

Response: Given a fit box and a crop box adjust one to the other


Instruction:
How would you implement a function in Python 3 that
parses a string into a tuple

Response:
def _parse_tuple_string(argument):
        """ Return a tuple from parsing 'a,b,c,d' -> (a,b,c,d) """
        if isinstance(argument, str):
            return tuple(int(p.strip()) for p in argument.split(','))
        return argument


Instruction:
Can you implement a function in Python 3 that
wraps to determine the overall rendition size and cropping boxsize and image size

Response:
def get_rendition_size(self, spec, output_scale, crop):
        """
        Wrapper to determine the overall rendition size and cropping box

        Returns tuple of (size,box)
        """

        if crop:
            # Use the cropping rectangle size
            _, _, width, height = crop
        else:
            # Use the original image size
            width = self._record.width
            height = self._record.height

        mode = spec.get('resize', 'fit')
        if mode == 'fit':
            return self.get_rendition_fit_size(spec, width, height, output_scale)

        if mode == 'fill':
            return self.get_rendition_fill_size(spec, width, height, output_scale)

        if mode == 'stretch':
            return self.get_rendition_stretch_size(spec, width, height, output_scale)

        raise ValueError("Unknown resize mode {}".format(mode))


Instruction:
Write a Python 3 function for
determining the size of the rendition based on the provided input size and the output size.

Response:
def get_rendition_fit_size(spec, input_w, input_h, output_scale):
        """ Determine the scaled size based on the provided spec """

        width = input_w
        height = input_h

        scale = spec.get('scale')
        if scale:
            width = width / scale
            height = height / scale

        min_width = spec.get('scale_min_width')
        if min_width and width < min_width:
            height = height * min_width / width
            width = min_width

        min_height = spec.get('scale_min_height')
        if min_height and height < min_height:
            width = width * min_height / height
            height = min_height

        tgt_width, tgt_height = spec.get('width'), spec.get('height')

        if tgt_width and width > tgt_width:
            height = height * tgt_width / width
            width = tgt_width

        if tgt_height and height > tgt_height:
            width = width * tgt_height / height
            height = tgt_height

        tgt_width, tgt_height = spec.get('max_width'), spec.get('max_height')

        if tgt_width and width > tgt_width:
            height = height * tgt_width / width
            width = tgt_width

        if tgt_height and height > tgt_height:
            width = width * tgt_height / height
            height = tgt_height

        width = width * output_scale
        height = height * output_scale

        # Never scale to larger than the base rendition
        width = min(round(width), input_w)
        height = min(round(height), input_h)

        return (width, height), None


Instruction:
Create a Python 3 function for
determining the size of the rendition based on the input size and the input scale.

Response:
def get_rendition_fill_size(spec, input_w, input_h, output_scale):
        """ Determine the scale-crop size given the provided spec """

        width = input_w
        height = input_h

        scale = spec.get('scale')
        if scale:
            width = width / scale
            height = height / scale

        if spec.get('scale_min_width'):
            width = max(width, spec['spec_min_width'])

        if spec.get('scale_min_height'):
            height = max(height, spec['scale_min_height'])

        if spec.get('width'):
            width = min(width, spec['width'])
        if spec.get('max_width'):
            width = min(width, spec['max_width'])

        if spec.get('height'):
            height = min(height, spec['height'])
        if spec.get('max_height'):
            height = min(height, spec['max_height'])

        width = width * output_scale
        height = height * output_scale

        # Never scale to larger than the base rendition (but keep the output
        # aspect)
        if width > input_w:
            height = height * input_w / width
            width = input_w

        if height > input_h:
            width = width * input_h / height
            height = input_h

        # Determine the box size
        box_w = min(input_w, round(width * input_h / height))
        box_h = min(input_h, round(height * input_w / width))

        # Box offset
        box_x = round((input_w - box_w) * spec.get('fill_crop_x', 0.5))
        box_y = round((input_h - box_h) * spec.get('fill_crop_y', 0.5))

        return (round(width), round(height)), (box_x, box_y, box_x + box_w, box_y + box_h)


Instruction:
Create a Python 3 function to
determine the size of the rendition - stretch image given the provided spec.

Response:
def get_rendition_stretch_size(spec, input_w, input_h, output_scale):
        """ Determine the scale-crop size given the provided spec """

        width = input_w
        height = input_h

        scale = spec.get('scale')
        if scale:
            width = width / scale
            height = height / scale

        min_width = spec.get('scale_min_width')
        if min_width and width < min_width:
            width = min_width

        min_height = spec.get('scale_min_height')
        if min_height and height < min_height:
            height = min_height

        tgt_width, tgt_height = spec.get('width'), spec.get('height')

        if tgt_width and width > tgt_width:
            width = tgt_width

        tgt_height = spec.get('height')
        if tgt_height and height > tgt_height:
            height = tgt_height

        tgt_width, tgt_height = spec.get('max_width'), spec.get('max_height')

        if tgt_width and width > tgt_width:
            width = tgt_width

        tgt_height = spec.get('height')
        if tgt_height and height > tgt_height:
            height = tgt_height

        width = width * output_scale
        height = height * output_scale

        return (round(width), round(height)), None


Instruction:
Given the following Python 3 function, write the documentation
def flatten(image, bgcolor=None):
        if bgcolor:
            background = PIL.Image.new('RGB', image.size, bgcolor)
            background.paste(image, mask=image.split()[3])
            return background

        return image.convert('RGB')

Response: Flatten an image with an optional background color


Instruction:
Can you generate the documentation for the following Python 3 function
def _get_renditions(self, kwargs):
        img_1x, size = self.get_rendition(
            1, **utils.remap_args(kwargs, {"quality": "quality_ldpi"}))
        img_2x, _ = self.get_rendition(
            2, **utils.remap_args(kwargs, {"quality": "quality_hdpi"}))

        return (img_1x, img_2x, size)

Response: Get a bunch of renditions ; returns a tuple of 1x 2x size


Instruction:
Can you generate the documentation for the following Python 3 function
def _get_img_attrs(self, style, kwargs):

        # Get the 1x and 2x renditions
        img_1x, img_2x, size = self._get_renditions(kwargs)

        return {
            'src': img_1x,
            'width': size[0],
            'height': size[1],
            'srcset': "{} 1x, {} 2x".format(img_1x, img_2x) if img_1x != img_2x else None,
            'style': ';'.join(style) if style else None,
            'class': kwargs.get('class', kwargs.get('img_class')),
            'id': kwargs.get('img_id')
        }

Response: Get the attributes of an img tag for this image hidpi - aware


Instruction:
Can you generate the documentation for the following Python 3 function
def _css_background(self, **kwargs):

        # Get the 1x and 2x renditions
        img_1x, img_2x, _ = self._get_renditions(kwargs)

        tmpl = 'background-image: url("{s1x}");'
        if img_1x != img_2x:
            image_set = 'image-set(url("{s1x}") 1x, url("{s2x}") 2x)'
            tmpl += 'background-image: {ss};background-image: -webkit-{ss};'.format(
                ss=image_set)
        return tmpl.format(s1x=img_1x, s2x=img_2x)

Response: Return the CSS specifiers for this as a hidpi - capable background image.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def process(text, config, search_path):
    processor = HTMLEntry(config, search_path)
    processor.feed(text)
    text = processor.get_data()

    if not config.get('no_smartquotes'):
        text = misaka.smartypants(text)

    return flask.Markup(text)

Response: Process an HTML entry s HTML


Instruction:
Can you create a Python 3 function that
handles a tag. attrs -- the attributes of the tag self_closing -- whether this is self-closing

Response:
def _handle_tag(self, tag, attrs, self_closing):
        """ Handle a tag.

        attrs -- the attributes of the tag
        self_closing -- whether this is self-closing
        """

        if tag.lower() == 'img':
            attrs = self._image_attrs(attrs)

        # Remap the attributes
        out_attrs = []
        for key, val in attrs:
            if (key.lower() == 'href'
                    or (key.lower() == 'src' and not tag.lower() == 'img')):
                out_attrs.append((key, links.resolve(
                    val, self._search_path, self._config.get('absolute'))))
            else:
                out_attrs.append((key, val))

        self.append(
            utils.make_tag(
                tag,
                out_attrs,
                self_closing))


Instruction:
Can you implement a function in Python 3 that
rewrites the width and height attributes on an image tag.

Response:
def _image_attrs(self, attrs):
        """ Rewrite the SRC attribute on an <img> tag, possibly adding a SRCSET.
        """

        path = None
        config = {**self._config}

        for key, val in attrs:
            if key.lower() == 'width' or key.lower() == 'height':
                try:
                    config[key.lower()] = int(val)
                except ValueError:
                    pass
            elif key.lower() == 'src':
                path = val

        img_path, img_args, _ = image.parse_image_spec(path)
        img = image.get_image(img_path, self._search_path)

        for key, val in img_args.items():
            if val and key not in config:
                config[key] = val

        try:
            img_attrs = img.get_img_attrs(**config)
        except FileNotFoundError as error:
            return [('data-publ-error', 'file not found: {}'.format(error.filename))]

        # return the original attr list with the computed overrides in place
        return [(key, val) for key, val in attrs
                if key.lower() not in img_attrs] + list(img_attrs.items())


Instruction:
Given the following Python 3 function, write the documentation
def scan_file(fullpath, relpath, assign_id):

    logger.debug("Scanning file: %s (%s) %s", fullpath, relpath, assign_id)

    def do_scan():
        """ helper function to do the scan and gather the result """
        _, ext = os.path.splitext(fullpath)

        try:
            if ext in ENTRY_TYPES:
                logger.info("Scanning entry: %s", fullpath)
                return entry.scan_file(fullpath, relpath, assign_id)

            if ext in CATEGORY_TYPES:
                logger.info("Scanning meta info: %s", fullpath)
                return category.scan_file(fullpath, relpath)

            return None
        except:  # pylint: disable=bare-except
            logger.exception("Got error parsing %s", fullpath)
            return False

    result = do_scan()
    if result is False and not assign_id:
        logger.info("Scheduling fixup for %s", fullpath)
        THREAD_POOL.submit(scan_file, fullpath, relpath, True)
    else:
        logger.debug("%s complete", fullpath)
        if result:
            set_fingerprint(fullpath)
        SCHEDULED_FILES.remove(fullpath)

Response: Scan a file for the index and return the index of the file.


Instruction:
Can you generate the documentation for the following Python 3 function
def get_last_fingerprint(fullpath):
    record = model.FileFingerprint.get(file_path=fullpath)
    if record:
        return record.fingerprint
    return None

Response: Get the last known modification time for a file


Instruction:
Can you create a Python 3 function that
sets the last known modification time for a file

Response:
def set_fingerprint(fullpath, fingerprint=None):
    """ Set the last known modification time for a file """
    try:
        fingerprint = fingerprint or utils.file_fingerprint(fullpath)

        record = model.FileFingerprint.get(file_path=fullpath)
        if record:
            record.set(fingerprint=fingerprint,
                       file_mtime=os.stat(fullpath).st_mtime)
        else:
            record = model.FileFingerprint(
                file_path=fullpath,
                fingerprint=fingerprint,
                file_mtime=os.stat(fullpath).st_mtime)
        orm.commit()
    except FileNotFoundError:
        orm.delete(fp for fp in model.FileFingerprint if fp.file_path == fullpath)


Instruction:
Create a Python 3 function to
start background scanning a directory for changes.

Response:
def background_scan(content_dir):
    """ Start background scanning a directory for changes """
    observer = watchdog.observers.Observer()
    observer.schedule(IndexWatchdog(content_dir),
                      content_dir, recursive=True)
    logging.info("Watching %s for changes", content_dir)
    observer.start()


Instruction:
Write a Python 3 function for
pruning any files which are missing from the specified table.

Response:
def prune_missing(table):
    """ Prune any files which are missing from the specified table """
    try:
        for item in table.select():
            if not os.path.isfile(item.file_path):
                logger.info("File disappeared: %s", item.file_path)
                item.delete()
    except:  # pylint:disable=bare-except
        logger.exception("Error pruning %s", table)


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

    def scan_directory(root, files):
        """ Helper function to scan a single directory """
        try:
            for file in files:
                fullpath = os.path.join(root, file)
                relpath = os.path.relpath(fullpath, content_dir)

                fingerprint = utils.file_fingerprint(fullpath)
                last_fingerprint = get_last_fingerprint(fullpath)
                if fingerprint != last_fingerprint and SCHEDULED_FILES.add(fullpath):
                    scan_file(fullpath, relpath, False)
        except:  # pylint:disable=bare-except
            logger.exception("Got error parsing directory %s", root)

    for root, _, files in os.walk(content_dir, followlinks=True):
        THREAD_POOL.submit(scan_directory, root, files)

    for table in (model.Entry, model.Category, model.Image, model.FileFingerprint):
        THREAD_POOL.submit(prune_missing, table)

Response: Scan all files in a content directory and prune missing entries


Instruction:
Make a summary of the following Python 3 code
def add(self, item):
        with self.lock:
            if item in self.set:
                return False
            self.set.add(item)
            return True

Response: Add an item to the set and return whether it was newly added


Instruction:
Can you create a Python 3 function that
removes an item from the set returning if it was present

Response:
def remove(self, item):
        """ Remove an item from the set, returning if it was present """
        with self.lock:
            if item in self.set:
                self.set.remove(item)
                return True
            return False


Instruction:
Can you implement a function in Python 3 that
updates a file in the content directory.

Response:
def update_file(self, fullpath):
        """ Update a file """
        if SCHEDULED_FILES.add(fullpath):
            logger.debug("Scheduling reindex of %s", fullpath)
            relpath = os.path.relpath(fullpath, self.content_dir)
            THREAD_POOL.submit(scan_file, fullpath, relpath, False)


Instruction:
Can you tell what is the following Python 3 function doing
def on_modified(self, event):
        logger.debug("file modified: %s", event.src_path)
        if not event.is_directory:
            self.update_file(event.src_path)

Response: on_modified handler for file modified event


Instruction:
How would you explain what the following Python 3 function does
def on_deleted(self, event):
        logger.debug("File deleted: %s", event.src_path)
        if not event.is_directory:
            self.update_file(event.src_path)

Response: Called when a file is deleted.


Instruction:
Create a Python 3 function to
parse a view specification from a request arg list

Response:
def parse_view_spec(args):
    """ Parse a view specification from a request arg list """

    view_spec = {}

    if 'date' in args:
        view_spec['date'] = args['date']
    elif 'id' in args:
        view_spec['start'] = args['id']

    if 'tag' in args:
        view_spec['tag'] = args.getlist('tag')
        if len(view_spec['tag']) == 1:
            view_spec['tag'] = args['tag']

    return view_spec


Instruction:
Can you tell what is the following Python 3 function doing
def deleted(self):
        query = queries.build_query({**self.spec,
                                     'future': False,
                                     '_deleted': True})
        return [Entry(e) for e in query]

Response: Gets the deleted entries from the view


Instruction:
Write a Python 3 function for
getting the most recent modification time for all entries in the view

Response:
def last_modified(self):
        """ Gets the most recent modification time for all entries in the view """
        if self.entries:
            latest = max(self.entries, key=lambda x: x.last_modified)
            return arrow.get(latest.last_modified)
        return arrow.get()


Instruction:
Implement a Python 3 function for
getting the previous page in the list

Response:
def previous(self):
        """ Gets the previous page, respecting sort order """
        if self._order_by == 'oldest':
            return self.older
        if self._order_by == 'newest':
            return self.newer
        return None


Instruction:
Write a Python 3 function for
getting the next page in the list

Response:
def next(self):
        """ Gets the next page, respecting sort order """
        if self._order_by == 'oldest':
            return self.newer
        if self._order_by == 'newest':
            return self.older
        return None


Instruction:
Write a Python 3 script to
get the newest entry in the view regardless of sort order

Response:
def newest(self):
        """ Gets the newest entry in the view, regardless of sort order """
        if self._order_by == 'newest':
            return self.first
        if self._order_by == 'oldest':
            return self.last
        return max(self.entries, key=lambda x: (x.date, x.id))


Instruction:
Implement a Python 3 function for
getting the oldest entry in the view regardless of sort order

Response:
def oldest(self):
        """ Gets the oldest entry in the view, regardless of sort order """
        if self._order_by == 'newest':
            return self.last
        if self._order_by == 'oldest':
            return self.first
        return min(self.entries, key=lambda x: (x.date, -x.id))


Instruction:
Can you tell what is the following Python 3 function doing
def paging(self):
        if 'date' in self.spec:
            _, date_span, _ = utils.parse_date(self.spec['date'])
            return date_span
        return 'offset'

Response: Gets the pagination type ; compatible with entry. archive


Instruction:
How would you code a function in Python 3 to
get a list of all pages for this view

Response:
def pages(self):
        """ Gets a list of all pages for this view """
        cur = self
        pages = []
        while cur.previous:
            cur = cur.previous
        while cur:
            pages.append(cur)
            cur = cur.next
        return pages


Instruction:
Make a summary of the following Python 3 code
def tags(self):
        tag_list = self.spec.get('tag', [])
        if isinstance(tag_list, (list, set, tuple)):
            return list(tag_list)
        return [tag_list]

Response: Returns a list of all the tags applied to this view


Instruction:
Write a Python 3 function that can
compute the neighboring pages from this view.

Response:
def _pagination(self):
        """ Compute the neighboring pages from this view.

        Returns a tuple of older page, newer page.
        """

        oldest = self.oldest
        newest = self.newest

        base = {key: val for key, val in self.spec.items()
                if key not in OFFSET_PRIORITY}

        oldest_neighbor = View({
            **base,
            'before': oldest,
            'order': 'newest'
        }).first if oldest else None

        newest_neighbor = View({
            **base,
            'after': newest,
            'order': 'oldest'
        }).first if newest else None

        if 'date' in self.spec:
            return self._get_date_pagination(base, oldest_neighbor, newest_neighbor)

        if 'count' in self.spec:
            return self._get_count_pagination(base, oldest_neighbor, newest_neighbor)

        # we're not paginating
        return None, None


Instruction:
Create a Python 3 function to
compute the pagination for date - based views

Response:
def _get_date_pagination(self, base, oldest_neighbor, newest_neighbor):
        """ Compute the pagination for date-based views """
        _, span, date_format = utils.parse_date(self.spec['date'])

        if newest_neighbor:
            newer_date = newest_neighbor.date.span(span)[0]
            newer_view = View({**base,
                               'order': self._order_by,
                               'date': newer_date.format(date_format)})
        else:
            newer_view = None

        if oldest_neighbor:
            older_date = oldest_neighbor.date.span(span)[0]
            older_view = View({**base,
                               'order': self._order_by,
                               'date': older_date.format(date_format)})
        else:
            older_view = None

        return older_view, newer_view


Instruction:
Implement a Python 3 function for
computing the pagination for count - based views

Response:
def _get_count_pagination(self, base, oldest_neighbor, newest_neighbor):
        """ Compute the pagination for count-based views """

        count = self.spec['count']

        out_spec = {**base, 'count': count, 'order': self._order_by}

        if self._order_by == 'newest':
            older_view = View({**out_spec,
                               'last': oldest_neighbor}) if oldest_neighbor else None

            newer_count = View({**base,
                                'first': newest_neighbor,
                                'order': 'oldest',
                                'count': count}) if newest_neighbor else None
            newer_view = View({**out_spec,
                               'last': newer_count.last}) if newer_count else None

            return older_view, newer_view

        if self._order_by == 'oldest':
            older_count = View({**base,
                                'last': oldest_neighbor,
                                'order': 'newest',
                                'count': count}) if oldest_neighbor else None
            older_view = View({**out_spec,
                               'first': older_count.last}) if older_count else None

            newer_view = View({**out_spec,
                               'first': newest_neighbor}) if newest_neighbor else None

            return older_view, newer_view

        return None, None


Instruction:
Create a Python 3 function for
returning a view with the specified tags added

Response:
def tag_add(self, *tags):
        """ Return a view with the specified tags added """
        return View({**self.spec, 'tag': list(set(self.tags) | set(tags))})


Instruction:
Can you generate the documentation for the following Python 3 function
def tag_remove(self, *tags):
        return View({**self.spec, 'tag': list(set(self.tags) - set(tags))})

Response: Return a view with the specified tags removed


Instruction:
Can you write a function in Python 3 where it
returns a view with the specified tags toggled

Response:
def tag_toggle(self, *tags):
        """ Return a view with the specified tags toggled """
        return View({**self.spec, 'tag': list(set(self.tags) ^ set(tags))})


Instruction:
Write a Python 3 script for
converting Markdown text to HTML

Response:
def to_html(text, config, search_path):
    """ Convert Markdown text to HTML """
    processor = misaka.Markdown(HtmlRenderer(config, search_path),
                                extensions=ENABLED_EXTENSIONS)

    text = processor(text)
    if not config.get('no_smartquotes'):
        text = misaka.smartypants(text)

    return flask.Markup(text)


Instruction:
Can you create a Python 3 function that
converts a Markdown title to HTML

Response:
def render_title(text, markup=True, no_smartquotes=False):
    """ Convert a Markdown title to HTML """

    # HACK: If the title starts with something that looks like a list, save it
    # for later
    pfx, text = re.match(r'([0-9. ]*)(.*)', text).group(1, 2)
    text = pfx + misaka.Markdown(TitleRenderer(),
                                 extensions=TITLE_EXTENSIONS)(text)

    if not markup:
        strip = HTMLStripper()
        strip.feed(text)
        text = strip.get_data()

    if not no_smartquotes:
        text = misaka.smartypants(text)

    return flask.Markup(text)


Instruction:
Can you tell what is the following Python 3 function doing
def image(self, raw_url, title='', alt=''):
        # pylint: disable=too-many-locals

        text = ''

        image_specs = raw_url
        if title:
            image_specs += ' "{}"'.format(title)

        alt, container_args = image.parse_alt_text(alt)

        container_args = {**self._config, **container_args}

        spec_list, original_count = image.get_spec_list(
            image_specs, container_args)

        for spec in spec_list:
            text += self._render_image(spec,
                                       container_args,
                                       alt)

        if original_count > len(spec_list) and 'more_text' in container_args:
            more_text = container_args['more_text'].format(
                count=original_count,
                remain=original_count - len(spec_list))
            if 'more_link' in container_args:
                more_text = '{a}{text}'.format(
                    text=more_text,
                    a=utils.make_tag('a', {'href': container_args['more_link']}))
            if 'more_class' in container_args:
                more_text = '{div}{text}
'.format(
                    text=more_text,
                    div=utils.make_tag('div', {'class': container_args['more_class']}))
            text += flask.Markup(more_text)

        if text and (container_args.get('div_class') or
                     container_args.get('div_style')):
            text = '{tag}{text}
'.format(
                tag=utils.make_tag('div',
                                   {'class': container_args.get('div_class'),
                                    'style': container_args.get('div_style')}),
                text=text)

        # if text is ''/falsy then misaka interprets this as a failed parse...
        return text or ' '

Response: Adapt a standard Markdown image to a generated rendition set.


Instruction:
Create a Python 3 function to
pass a code fence through pygments

Response:
def blockcode(self, text, lang):
        """ Pass a code fence through pygments """
        if lang and self._config.get('highlight_syntax', 'True'):
            try:
                lexer = pygments.lexers.get_lexer_by_name(lang, stripall=True)
            except pygments.lexers.ClassNotFound:
                lexer = None

            if lexer:
                formatter = pygments.formatters.HtmlFormatter()  # pylint: disable=no-member
                return pygments.highlight(text, lexer, formatter)

        return '\n

{}

\n'.format(
            flask.escape(text.strip()))


Instruction:
Write a Python 3 script to
emit a link potentially remapped based on our embed or static rules.

Response:
def link(self, content, link, title=''):
        """ Emit a link, potentially remapped based on our embed or static rules """

        link = links.resolve(link, self._search_path,
                             self._config.get('absolute'))

        return '{}{}</a>'.format(
            utils.make_tag('a', {
                'href': link,
                'title': title if title else None
            }),
            content)


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

        # if the content contains a top-level div then don't wrap it in a

        # tag
        if content.startswith('<div') and content.endswith('
'):
            return '\n' + content + '\n'

        text = '
' + content + '
'
        text = re.sub(r'
\s*
', r'', text)
        return text or ' '

Response: emit a paragraph stripping out any leading or following empty paragraphs


Instruction:
Here you have a function in Python 3, explain what it does
def _render_image(self, spec, container_args, alt_text=None):

        try:
            path, image_args, title = image.parse_image_spec(spec)
        except Exception as err:  # pylint: disable=broad-except
            logger.exception("Got error on spec %s: %s", spec, err)
            return ('Couldn\'t parse image spec: ' +
                    '{} {}'.format(flask.escape(spec),
                                                       flask.escape(str(err))))

        composite_args = {**container_args, **image_args}

        try:
            img = image.get_image(path, self._search_path)
        except Exception as err:  # pylint: disable=broad-except
            logger.exception("Got error on image %s: %s", path, err)
            return ('Error loading image {}: {}'.format(
                flask.escape(spec), flask.escape(str(err))))

        return img.get_img_tag(title, alt_text, **composite_args)

Response: Render an image specification into an img tag


Instruction:
Given the following Python 3 function, write the documentation
def resolve(path, search_path, absolute=False):

    # Resolve external URLs
    if re.match(r'([a-z][a-z0-9+.\-]*:)?//', path, re.I):
        return path

    # Resolve static assets
    if path.startswith('@'):
        return utils.static_url(path[1:], absolute)

    path, sep, anchor = path.partition('#')

    # Resolve entries
    entry = utils.find_entry(path, search_path)
    if entry:
        return entry.permalink(absolute=absolute) + sep + anchor

    # Resolve images and assets
    img_path, img_args, _ = image.parse_image_spec(path)
    img = image.get_image(img_path, search_path)
    if not isinstance(img, image.ImageNotFound):
        path, _ = img.get_rendition(**img_args)
    return path + sep + anchor

Response: Resolve a link or source target to an appropriate entry or image rendition


Instruction:
Write a Python 3 function for
returning whether we should not cache a page render

Response:
def do_not_cache():
    """ Return whether we should cache a page render """

    from . import index  # pylint: disable=cyclic-import

    if index.in_progress():
        # We are reindexing the site
        return True

    if request.if_none_match or request.if_modified_since:
        # we might be returning a 304 NOT MODIFIED based on a client request,
        # and we don't want to cache that as the result for *all* client
        # requests to this URI
        return True

    return False


Instruction:
Implement a Python 3 function for
generating a where clause for currently - visible entries in the system

Response:
def where_entry_visible(query, date=None):
    """ Generate a where clause for currently-visible entries

    Arguments:

    date -- The date to generate it relative to (defaults to right now)
    """

    return orm.select(
        e for e in query
        if e.status == model.PublishStatus.PUBLISHED.value or
        (e.status == model.PublishStatus.SCHEDULED.value and
         (e.utc_date <= (date or arrow.utcnow().datetime))
         )
    )


Instruction:
Given the following Python 3 function, write the documentation
def where_entry_visible_future(query):

    return orm.select(
        e for e in query
        if e.status in (model.PublishStatus.PUBLISHED.value,
                        model.PublishStatus.SCHEDULED.value))

Response: Generate a where clause for entries that are visible now or in the future


Instruction:
Can you tell what is the following Python 3 function doing
def where_entry_deleted(query):
    return orm.select(
        e for e in query
        if e.status == model.PublishStatus.GONE.value)

Response: Generate a where clause for entries that have been deleted


Instruction:
Can you implement a function in Python 3 that
generates a where clause for a particular category

Response:
def where_entry_category(query, category, recurse=False):
    """ Generate a where clause for a particular category """

    category = str(category)
    if category and recurse:
        # We're recursing and aren't in /, so add the prefix clause
        return orm.select(
            e for e in query
            if e.category == category or e.category.startswith(category + '/')
        )

    if not recurse:
        # We're not recursing, so we need an exact match on a possibly-empty
        # category
        return orm.select(e for e in query if e.category == category)

    # We're recursing and have no category, which means we're doing nothing
    return query


Instruction:
How would you implement a function in Python 3 that
generates a where clause for prior entries

Response:
def where_before_entry(query, ref):
    """ Generate a where clause for prior entries

    ref -- The entry of reference
    """
    return orm.select(
        e for e in query
        if e.local_date < ref.local_date or
        (e.local_date == ref.local_date and e.id < ref.id)
    )


Instruction:
Write a Python 3 script to
generate a where clause for later entries

Response:
def where_after_entry(query, ref):
    """ Generate a where clause for later entries

    ref -- the entry of reference
    """
    return orm.select(
        e for e in query
        if e.local_date > ref.local_date or
        (e.local_date == ref.local_date and
         e.id > ref.id
         )
    )


Instruction:
How would you code a function in Python 3 to
generate a where clause where this is the last entry of the reference

Response:
def where_entry_last(query, ref):
    """ Generate a where clause where this is the last entry

    ref -- the entry of reference
    """
    return orm.select(
        e for e in query
        if e.local_date < ref.local_date or
        (e.local_date == ref.local_date and
         e.id <= ref.id
         )
    )


Instruction:
Write a Python 3 script for
generating a where clause where this is the first entry of the reference

Response:
def where_entry_first(query, ref):
    """ Generate a where clause where this is the first entry

    ref -- the entry of reference
    """
    return orm.select(
        e for e in query
        if e.local_date > ref.local_date or
        (e.local_date == ref.local_date and
         e.id >= ref.id
         )
    )


Instruction:
Can you write a function in Python 3 where it
generates a where clause for entries of certain types

Response:
def where_entry_type(query, entry_type):
    """ Generate a where clause for entries of certain types

    entry_type -- one or more entries to check against
    """
    if isinstance(entry_type, (list, set, tuple)):
        return orm.select(e for e in query if e.entry_type in entry_type)
    return orm.select(e for e in query if e.entry_type == entry_type)


Instruction:
Write a Python 3 function for
generating a where clause for entries with the given tag

Response:
def where_entry_tag(query, tag):
    """ Generate a where clause for entries with the given tag """
    if isinstance(tag, (list, set, tuple)):
        tags = [t.lower() for t in tag]
        return orm.select(e for e in query for t in e.tags if t.key in tags)
    return orm.select(e for e in query for t in e.tags if t.key == tag.lower())


Instruction:
Can you generate the documentation for the following Python 3 function
def where_entry_date(query, datespec):
    date, interval, _ = utils.parse_date(datespec)
    start_date, end_date = date.span(interval)

    return orm.select(
        e for e in query if
        e.local_date >= start_date.naive and
        e.local_date <= end_date.naive
    )

Response: Returns a where clause for entries which match a textual date spec


Instruction:
Create a Python 3 function to
build the where clause based on a view specification

Response:
def build_query(spec):
    """ build the where clause based on a view specification

    spec -- The view specification. Contains the following possible values:
        future -- Boolean; whether to include entries from the future
        category -- Which category to limit to
        recurse -- Whether to include subcategories
        entry_type -- one or more entry types to include
        entry_type_not -- one or more entry types to exclude
        date -- a date spec
        last -- the last entry to end a view on
        first -- the first entry to start a view on
        before -- get entries from before this one
        after -- get entries from after this one
    """

    query = model.Entry.select()

    # primarily restrict by publication status
    if spec.get('_deleted', False):
        query = where_entry_deleted(query)
    elif spec.get('future', False):
        query = where_entry_visible_future(query)
    else:
        query = where_entry_visible(query)

    # restrict by category
    if spec.get('category') is not None:
        path = str(spec.get('category', ''))
        recurse = spec.get('recurse', False)
        query = where_entry_category(query, path, recurse)

    if spec.get('entry_type') is not None:
        query = where_entry_type(query, spec['entry_type'])

    if spec.get('entry_type_not') is not None:
        query = where_entry_type_not(query, spec['entry_type_not'])

    if spec.get('tag') is not None:
        query = where_entry_tag(query, spec['tag'])

    if spec.get('date') is not None:
        query = where_entry_date(query, spec['date'])

    if spec.get('last') is not None:
        query = where_entry_last(query, get_entry(spec['last']))

    if spec.get('first') is not None:
        query = where_entry_first(query, get_entry(spec['first']))

    if spec.get('before') is not None:
        query = where_before_entry(query, get_entry(spec['before']))

    if spec.get('after') is not None:
        query = where_after_entry(query, get_entry(spec['after']))

    return query.distinct()


Instruction:
Write a Python 3 script for
creating templates and static files

Response:
def create_templates_static_files(app_path):
    """
    create templates and static
    """
    templates_path = os.path.join(app_path, 'templates')
    static_path = os.path.join(app_path, 'static')
    _mkdir_p(templates_path)
    _mkdir_p(static_path)
    # create {img, css, js}
    os.chdir(static_path)
    img_path = os.path.join(static_path, 'img')
    css_path = os.path.join(static_path, 'css')
    js_path = os.path.join(static_path, 'js')
    _mkdir_p(img_path)
    _mkdir_p(css_path)
    _mkdir_p(js_path)

    return css_path, templates_path


Instruction:
Make a summary of the following Python 3 code
def create_blueprint(app_path, blueprint, views_code, forms_code, templates_path):
    blueprint_path = os.path.join(app_path, blueprint)
    _mkdir_p(blueprint_path)
    # create  blueprint files
    os.chdir(blueprint_path)
    init_code('__init__.py', _init_blueprint_code % (blueprint, blueprint))
    init_code('views.py', views_code)
    init_code('forms.py', forms_code)
    # main blueprint templates
    os.chdir(templates_path)
    blueprint_templates_path = os.path.join(templates_path, blueprint)
    _mkdir_p(blueprint_templates_path)

    return blueprint_templates_path

Response: create blueprint and create templates


Instruction:
Write a Python 3 script for
initializing a minimal flask project

Response:
def init(project_name):
    """
    build a minimal flask project
    """
    # the destination path
    dst_path = os.path.join(os.getcwd(), project_name)

    start_init_info(dst_path)

    # create dst path
    _mkdir_p(dst_path)

    os.chdir(dst_path)
    # create files
    init_code('manage.py', _manage_basic_code)
    init_code('requirement.txt', _requirement_code)

    # create app/
    app_path = os.path.join(dst_path, 'app')
    _mkdir_p(app_path)

    os.chdir(app_path)
    # create files
    init_code('views.py', _views_basic_code)
    init_code('forms.py', _forms_basic_code)
    init_code('__init__.py', _init_basic_code)

    create_templates_static_files(app_path)

    init_done_info()


Instruction:
How would you explain what the following Python 3 function does
def blueprint(blueprint_name):
    app = os.getcwd().split('/')[-1]
    if app != 'app':
        logger.warning('''\033[31m{Warning}\033[0m
==> your current path is \033[32m%s\033[0m\n
==> please create your blueprint under app folder!''' % os.getcwd())
        exit(1)

    # destination path
    dst_path = os.path.join(os.getcwd(), blueprint_name)
    if os.path.isdir(dst_path):
        logger.warning('''\033[31m{Warning}\033[0m
==> bluprint \033[32m%s\033[0m\n exist
==> please try again !''' % dst_path)
        exit(1)

    # create dst_path
    _mkdir_p(dst_path)

    # change dir
    os.chdir(dst_path)
    # create files
    init_code('__init__.py', _init_blueprint_code %
        (blueprint_name, blueprint_name))
    init_code('views.py', _views_blueprint_code %
        (blueprint_name, blueprint_name))
    init_code('forms.py', _forms_basic_code)

    # register auth in app
    os.chdir(os.path.join(dst_path, '..'))
    with open('__init__.py', 'r+') as f:
        prev = pos = 0
        while f.readline():
            prev, pos = pos, f.tell()
        f.seek(prev)
        f.write(
            '\nfrom %s import %s\napp.register_blueprint(%s, url_prefix="/%s")\n\n'
            % (
                blueprint_name, blueprint_name,
                blueprint_name, blueprint_name
            )
        )

    # create blueprint templates
    templates_path = os.path.join(os.getcwd(), 'templates')
    os.chdir(templates_path)
    blueprint_templates_path = os.path.join(templates_path, blueprint_name)
    _mkdir_p(blueprint_templates_path)

    logger.info('''\033[33m{Info}\033[0m: create blueprint done!''')

Response: create and register a blueprint


Instruction:
Can you tell what is the following Python 3 function doing
def startproject(project_name):
    # the destination path
    dst_path = os.path.join(os.getcwd(), project_name)
    start_init_info(dst_path)

    # create dst path
    _mkdir_p(dst_path)

    # create project tree
    os.chdir(dst_path)
    # create files
    init_code('manage.py', _manage_admin_code)
    init_code('requirement.txt', _requirement_admin_code)
    init_code('config.py', _config_sql_code)

    # create app/
    app_path = os.path.join(dst_path, 'app')
    _mkdir_p(app_path)

    # create files
    os.chdir(app_path)
    init_code('models.py', _models_admin_code)
    init_code('__init__.py', _init_admin_code)

    # create templates and static
    css_path, templates_path = create_templates_static_files(app_path)
    # create css files
    os.chdir(css_path)
    init_code('sign.css', _auth_login_css_code)

    # create main blueprint
    create_blueprint(
        app_path,
        'main',
        _views_blueprint_code % ('main', 'main'),
        _forms_basic_code,
        templates_path
    )

    # create auth blueprint
    auth_templates_path = create_blueprint(
        app_path,
        'auth',
        _auth_views_code,
        _auth_forms_code,
        templates_path
    )
    # create auth templates files
    os.chdir(auth_templates_path)
    init_code('login.html', _auth_login_html_code)

    # create admin site
    admin_path = os.path.join(app_path, 'admin')
    _mkdir_p(admin_path)

    # create admin files
    os.chdir(admin_path)
    init_code('__init__.py', '')
    init_code('views.py', _admin_views_code)

    # create admin templates
    os.chdir(templates_path)
    admin_templates_path = os.path.join(templates_path, 'admin')
    _mkdir_p(admin_templates_path)

    # create admin templates files
    os.chdir(admin_templates_path)
    init_code('index.html', _admin_index_html_code)
    init_code('logout.html', _admin_logout_html_code)

    init_done_info()

Response: build a full status project


Instruction:
Create a Python 3 function for
adding sql modules into admin site

Response:
def admin(module):
    """add sql modules into admin site"""
    # add module into admin site
    app = os.getcwd().split('/')[-1]
    if app != 'app':
        logger.warning('''\033[31m{Warning}\033[0m
==> your current path is \033[32m%s\033[0m\n
==> please add your sql module under app folder!''' % os.getcwd())
        exit(1)

    admin_path = os.path.join(os.getcwd(), 'admin')
    os.chdir(admin_path)
    with open('views.py', 'r+') as f:
        prev = pos = 0
        while f.readline():
            prev, pos = pos, f.tell()
        f.seek(prev)
        f.write(
            '\nfrom app.models import %s\nadmin.add_view(ModelView(%s, db.session))'
            % (module, module)
        )

    logger.info('''\033[33m{Info}\033[0m: add module done!''')


Instruction:
Here you have a function in Python 3, explain what it does
def _mkdir_p(abspath):
    try:
        os.makedirs(abspath)
    except OSError as e:
        if (e.errno == errno.EEXIST) and (os.path.isdir(abspath)):
            pass
        else: raise

Response:
Create the abspath
CTYPE except the abspath exist


Instruction:
How would you explain what the following Python 3 function does
def raise_error(error_type: str) -> None:
    try:
        error = next((v for k, v in ERROR_CODES.items() if k in error_type))
    except StopIteration:
        error = AirVisualError
    raise error(error_type)

Response: Raise the appropriate error based on error message.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def _raise_on_error(data: Union[str, dict]) -> None:
    if isinstance(data, str):
        raise_error(data)
    elif 'status' in data and data['status'] != 'success':
        raise_error(data['data']['message'])

Response: Raise the appropriate exception on error.


Instruction:
Create a Python 3 function for
making a request against AirVisual.

Response:
async def request(
            self,
            method: str,
            endpoint: str,
            *,
            base_url: str = API_URL_SCAFFOLD,
            headers: dict = None,
            params: dict = None,
            json: dict = None) -> dict:
        """Make a request against AirVisual."""
        if not headers:
            headers = {}
        headers.update({'Content-Type': 'application/json'})

        if not params:
            params = {}

        if self._api_key:
            params.update({'key': self._api_key})

        url = '{0}/{1}'.format(base_url, endpoint)
        async with self.websession.request(method, url, headers=headers,
                                           params=params, json=json) as resp:
            data = await resp.json(content_type=None)
            _raise_on_error(data)
            return data


Instruction:
How would you explain what the following Python 3 function does
async def main() -> None:  # pylint: disable=too-many-statements
    logging.basicConfig(level=logging.INFO)
    async with ClientSession() as websession:
        client = Client(websession, api_key='<API KEY>')

        # Get supported locations (by location):
        try:
            _LOGGER.info(await client.supported.countries())
            _LOGGER.info(await client.supported.states('USA'))
            _LOGGER.info(await client.supported.cities('USA', 'Colorado'))
        except AirVisualError as err:
            _LOGGER.error('There was an error: %s', err)

        # Get supported locations (by station):
        try:
            _LOGGER.info(
                await client.supported.stations(
                    'USA', 'Colorado', 'Denver'))
        except UnauthorizedError as err:
            _LOGGER.error(err)
        except AirVisualError as err:
            _LOGGER.error('There was an error: %s', err)

        # Get data by nearest location (by IP):
        try:
            _LOGGER.info(await client.api.nearest_city())
        except AirVisualError as err:
            _LOGGER.error('There was an error: %s', err)

        # Get data by nearest location (coordinates or explicit location):
        try:
            _LOGGER.info(
                await client.api.nearest_city(
                    latitude=39.742599, longitude=-104.9942557))
            _LOGGER.info(
                await client.api.city(
                    city='Los Angeles', state='California', country='USA'))
        except AirVisualError as err:
            _LOGGER.error('There was an error: %s', err)

        # Get data by nearest station (by IP):
        try:
            _LOGGER.info(await client.api.nearest_station())
        except UnauthorizedError as err:
            _LOGGER.error(err)
        except AirVisualError as err:
            _LOGGER.error('There was an error: %s', err)

        # Get data by nearest station (by coordinates or explicit location):
        try:
            _LOGGER.info(
                await client.api.nearest_station(
                    latitude=39.742599, longitude=-104.9942557))
            _LOGGER.info(
                await client.api.station(
                    station='US Embassy in Beijing',
                    city='Beijing',
                    state='Beijing',
                    country='China'))
        except UnauthorizedError as err:
            _LOGGER.error(err)
        except AirVisualError as err:
            _LOGGER.error('There was an error: %s', err)

        # Get data on AQI ranking:
        try:
            _LOGGER.info(await client.api.ranking())
        except UnauthorizedError as err:
            _LOGGER.error(err)
        except AirVisualError as err:
            _LOGGER.error('There was an error: %s', err)

        # Get info on a AirVisual Pro node:
        _LOGGER.info(await client.api.node('zEp8CifbnasWtToBc'))

Response: Create the aiohttp session and run the example.


Instruction:
How would you explain what the following Python 3 function does
async def _nearest(
            self,
            kind: str,
            latitude: Union[float, str] = None,
            longitude: Union[float, str] = None) -> dict:
        """Return data from nearest city/station (IP or coordinates)."""
        params = {}
        if latitude and longitude:
            params.update({'lat': str(latitude), 'lon': str(longitude)})

        data = await self._request(
            'get', 'nearest_{0}'.format(kind), params=params)
        return data['data']

Response: Return data from nearest city or station.


Instruction:
Implement a Python 3 function for
returning data for the specified city.

Response:
async def city(self, city: str, state: str, country: str) -> dict:
        """Return data for the specified city."""
        data = await self._request(
            'get',
            'city',
            params={
                'city': city,
                'state': state,
                'country': country
            })
        return data['data']


Instruction:
How would you explain what the following Python 3 function does
async def nearest_city(
            self,
            latitude: Union[float, str] = None,
            longitude: Union[float, str] = None) -> dict:
        """Return data from nearest city (IP or coordinates)."""
        return await self._nearest('city', latitude, longitude)

Response: Return data from nearest city.


Instruction:
Create a Python 3 function to
return data from a node by its ID.

Response:
async def node(self, node_id: str) -> dict:
        """Return data from a node by its ID."""
        return await self._request('get', node_id, base_url=NODE_URL_SCAFFOLD)


Instruction:
Implement a function in Python 3 to
return a list of supported cities in a country / state.

Response:
async def cities(self, country: str, state: str) -> list:
        """Return a list of supported cities in a country/state."""
        data = await self._request(
            'get', 'cities', params={
                'state': state,
                'country': country
            })
        return [d['city'] for d in data['data']]


Instruction:
Can you create a Python 3 function that
returns a list of supported states in a country.

Response:
async def states(self, country: str) -> list:
        """Return a list of supported states in a country."""
        data = await self._request(
            'get', 'states', params={'country': country})
        return [d['state'] for d in data['data']]


Instruction:
Make a summary of the following Python 3 code
async def stations(self, city: str, state: str, country: str) -> list:
        data = await self._request(
            'get',
            'stations',
            params={
                'city': city,
                'state': state,
                'country': country
            })
        return [station for station in data['data']]

Response: Return a list of supported stations in a city.


Instruction:
Can you create a Python 3 function that
returns a suitable column width to display one or more strings.

Response:
def column_width(tokens):
    """
    Return a suitable column width to display one or more strings.
    """
    get_len = tools.display_len if PY3 else len
    lens = sorted(map(get_len, tokens or [])) or [0]
    width = lens[-1]

    # adjust for disproportionately long strings
    if width >= 18:
        most = lens[int(len(lens) * 0.9)]
        if most < width + 6:
            return most

    return width


Instruction:
Write a Python 3 function for
justifying a string to fill one or more columns.

Response:
def justify_token(tok, col_width):
    """
    Justify a string to fill one or more columns.
    """
    get_len = tools.display_len if PY3 else len
    tok_len = get_len(tok)
    diff_len = tok_len - len(tok) if PY3 else 0

    cols = (int(math.ceil(float(tok_len) / col_width))
            if col_width < tok_len + 4 else 1)

    if cols > 1:
        return tok.ljust((col_width * cols) + (4 * cols) - diff_len)
    else:
        return tok.ljust(col_width + 4 - diff_len)


Instruction:
Can you create a Python 3 function that
returns the display name of an object.

Response:
def display_name(name, obj, local):
    """
    Get the display name of an object.

    Keyword arguments (all required):

    * ``name`` -- the name of the object as a string.
    * ``obj`` -- the object itself.
    * ``local`` -- a boolean value indicating whether the object is in local
      scope or owned by an object.

    """
    prefix = '' if local else '.'

    if isinstance(obj, SeeError):
        suffix = '?'
    elif hasattr(obj, '__call__'):
        suffix = '()'
    else:
        suffix = ''

    return ''.join((prefix, name, suffix))


Instruction:
Create a Python 3 function for
filtering the results using a pattern.

Response:
def filter(self, pattern):
        """
        Filter the results using a pattern.

        This accepts a shell-style wildcard pattern (as used by the fnmatch_
        module)::

            >>> see([]).filter('*op*')
                .copy()    .pop()

        It also accepts a regular expression. This may be a compiled regular
        expression (from the re_ module) or a string that starts with a ``/``
        (forward slash) character::

            >>> see([]).filter('/[aeiou]{2}/')
                .clear()    .count()

        .. _fnmatch: https://docs.python.org/3/library/fnmatch.html
        .. _re: https://docs.python.org/3/library/re.html
        """
        if isinstance(pattern, REGEX_TYPE):
            func = tools.filter_regex
        elif pattern.startswith('/'):
            pattern = re.compile(pattern.strip('/'))
            func = tools.filter_regex
        else:
            func = tools.filter_wildcard

        return SeeResult(func(self, pattern))


Instruction:
How would you explain what the following Python 3 function does
def filter_ignoring_case(self, pattern):
        return self.filter(re.compile(pattern, re.I))

Response: Like filter but case - insensitive.


Instruction:
Here you have a function in Python 3, explain what it does
def term_width():
    if fcntl and termios:
        try:
            winsize = fcntl.ioctl(0, termios.TIOCGWINSZ, '    ')
            _, width = struct.unpack('hh', winsize)
            return width
        except IOError:
            pass
    elif windll and create_string_buffer:  # pragma: no cover (windows)
        stderr_handle, struct_size = -12, 22
        handle = windll.kernel32.GetStdHandle(stderr_handle)
        csbi = create_string_buffer(struct_size)
        res = windll.kernel32.GetConsoleScreenBufferInfo(handle, csbi)
        if res:
            (_, _, _, _, _, left, _, right, _,
             _, _) = struct.unpack('hhhhHhhhhhh', csbi.raw)
            return right - left + 1
        else:
            return 0

Response: Return the column width of the terminal.


Instruction:
Write a Python 3 script for
returning the ideal column width for the output of a Travis CI command line.

Response:
def line_width(default_width=DEFAULT_LINE_WIDTH, max_width=MAX_LINE_WIDTH):
    """
    Return the ideal column width for the output from :func:`see.see`, taking
    the terminal width into account to avoid wrapping.
    """
    width = term_width()
    if width:  # pragma: no cover (no terminal info in Travis CI)
        return min(width, max_width)
    else:
        return default_width


Instruction:
Can you implement a function in Python 3 that
returns the persistent ID of the object.

Response:
def persistent_id(self, obj):
        """ Tags objects with a persistent ID, but do NOT emit it
        """
        if getattr(obj, '_PERSIST_REFERENCES', None):
            objid = id(obj)
            obj._persistent_ref = objid
            _weakmemos[objid] = obj
        return None


Instruction:
Here you have a function in Python 3, explain what it does
def handle_deprecated_args(tokens, args, kwargs):
    num_args = len(args)
    pattern = args[0] if num_args else kwargs.get('pattern', None)
    regex = args[1] if num_args > 1 else kwargs.get('r', None)

    if pattern is not None:
        tokens = tools.filter_wildcard(tokens, pattern)
        sys.stderr.write(
            'Please use see().match() now. The "pattern" argument is '
            'deprecated and will be removed in a later release. \n')

    if regex is not None:
        tokens = tools.filter_regex(tokens, re.compile(regex))
        sys.stderr.write(
            'Please use see().match() now. The "r" argument is '
            'deprecated and will be removed in a later release. \n')

    return tokens

Response: Backwards compatibility with deprecated arguments pattern and r.


Instruction:
How would you explain what the following Python 3 function does
def see(obj=DEFAULT_ARG, *args, **kwargs):
    use_locals = obj is DEFAULT_ARG

    if use_locals:
        # Get the local scope from the caller's stack frame.
        # Typically this is the scope of an interactive Python session.
        obj = Namespace(inspect.currentframe().f_back.f_locals)

    tokens = []
    attrs = dir(obj)

    if not use_locals:

        for name, func in INSPECT_FUNCS:
            if func(obj):
                tokens.append(name)

        for feature in FEATURES:
            if feature.match(obj, attrs):
                tokens.append(feature.symbol)

    for attr in filter(lambda a: not a.startswith('_'), attrs):
        try:
            prop = getattr(obj, attr)
        except (AttributeError, Exception):  # pylint: disable=broad-except
            prop = SeeError()
        action = output.display_name(name=attr, obj=prop, local=use_locals)
        tokens.append(action)

    if args or kwargs:
        tokens = handle_deprecated_args(tokens, args, kwargs)

    return output.SeeResult(tokens)

Response: A function that shows the features and attributes of an object.


Instruction:
Make a summary of the following Python 3 code
def open(self, mode='r', encoding=None):
        access_type = self._get_access_type(mode)
        return open(self.localpath, 'r'+access_type, encoding=encoding)

Response: Return file - like object actually opens the file for this class.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def _open_tmpfile(self, **kwargs):
        self.tmpfile = get_tempfile(**kwargs)
        path = self.tmpfile.name
        return path

Response: Open a temporary file and return its name.


Instruction:
Explain what the following Python 3 code does
def open(self, mode='r', encoding=None):
        access_type = self._get_access_type(mode)

        if encoding is None:
            encoding = self.encoding

        # here, we face the task of returning the correct data type
        if access_type == 'b':
            if not self._isbytes:
                content = self._contents.encode(encoding)  # unicode in, bytes out
            else:
                content = self._contents  # bytes in, bytes out
            return io.BytesIO(content)
        else:
            assert access_type == 't'
            if PYVERSION == 2 and self._isbytes:
                return io.BytesIO(self._contents)  # bytes in, bytes out (python 2 only)
            elif self._isbytes:
                content = self._contents.decode(encoding)  # bytes in, unicode out
            else:
                content = self._contents  # unicode in, unicode out
            return io.StringIO(content)

Response: Return file - like object containing the contents of the file.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def put(self, filename, encoding=None):
        from . import LocalFile

        if os.path.isdir(filename) and self.source is None:
            raise ValueError("Cannot write this object to "
                             "directory %s without an explicit filename." % filename)

        target = get_target_path(filename, self.source)

        if encoding is None:
            encoding = self.encoding

        if self._isbytes:
            kwargs = {'mode': 'wb'}
        else:
            kwargs = {'mode': 'w', 'encoding': encoding}

        with open(target, **kwargs) as outfile:
            outfile.write(self._contents)

        return LocalFile(target, encoded_with=encoding)

Response: Write the contents of this object to the given path.


Instruction:
Write a Python 3 function for
storing any methods or variables bound from the function s closure Returns a dictionary mapping of variable names to globally bound VARIABLES

Response:
def get_global_vars(func):
    """ Store any methods or variables bound from the function's closure

    Args:
        func (function): function to inspect

    Returns:
        dict: mapping of variable names to globally bound VARIABLES
    """
    closure = getclosurevars(func)
    if closure['nonlocal']:
        raise TypeError("Can't launch a job with closure variables: %s" %
                        closure['nonlocals'].keys())
    globalvars = dict(modules={},
                      functions={},
                      vars={})
    for name, value in closure['global'].items():
        if inspect.ismodule(value):  # TODO: deal FUNCTIONS from closure
            globalvars['modules'][name] = value.__name__
        elif inspect.isfunction(value) or inspect.ismethod(value):
            globalvars['functions'][name] = value
        else:
            globalvars['vars'][name] = value

    return globalvars


Instruction:
Create a Python 3 function for
returning the source code for a class or function.

Response:
def getsource(classorfunc):
    """ Return the source code for a class or function.

    Notes:
        Returned source will not include any decorators for the object.
        This will only return the explicit declaration of the object, not any dependencies

    Args:
        classorfunc (type or function): the object to get the source code for

    Returns:
        str: text of source code (without any decorators). Note: in python 2, this returns unicode
    """
    if _isbuiltin(classorfunc):
        return ''

    try:
        source = inspect.getsource(classorfunc)
    except TypeError:  # raised if defined in __main__ - use fallback to get the source instead
        source = getsourcefallback(classorfunc)

    declaration = []

    lines = source.splitlines()
    if PY2 and not isinstance(source, unicode):
        encoding = detect_encoding(iter(lines).next)[0]
        sourcelines = (s.decode(encoding) for s in lines)
    else:
        sourcelines = iter(lines)

    # First, get the declaration
    found_keyword = False
    for line in sourcelines:
        words = line.split()
        if not words:
            continue
        if words[0] in ('def', 'class'):
            found_keyword = True
        if found_keyword:
            cind = line.find(':')
            if cind > 0:
                declaration.append(line[:cind + 1])
                after_decl = line[cind + 1:].strip()
                break
            else:
                declaration.append(line)

    bodylines = list(sourcelines)  # the rest of the lines are body

    # If it's a class, make sure we import its superclasses
    # Unfortunately, we need to modify the code to make sure the
    # parent classes have the correct names
    # TODO: find a better way to do this without having to parse code
    if type(classorfunc) == type:
        cls = classorfunc
        base_imports = {}
        for base in cls.__bases__:
            if base.__name__ == 'object' and base.__module__ == 'builtins':  # don't import `object`
                continue
            if base in base_imports:
                continue
            if base.__module__ == '__main__':
                continue
            base_imports[base] = 'from %s import %s' % (base.__module__, base.__name__)
        cind = declaration[0].index('class ')

        declstring = declaration[0][:cind] + 'class %s(%s):%s' % (
            cls.__name__,
            ','.join([base.__name__ for base in cls.__bases__]),
            after_decl)
        declaration = [impstring for c, impstring in base_imports.items()
                       if c.__module__ != '__builtin__']
        declaration.append(declstring)

    else:
        declaration[-1] += after_decl

    return '\n'.join(declaration + bodylines)


Instruction:
How would you explain what the following Python 3 function does
def getsourcefallback(cls):
    for attr in cls.__dict__:
        if inspect.ismethod(getattr(cls, attr)):
            imethod = getattr(cls, attr)
            break
    else:
        raise AttributeError(
            "Cannot get this class' source; it does not appear to have any methods")

    ### This part is derived from inspect.findsource ###
    module = inspect.getmodule(cls)
    file = inspect.getfile(imethod)
    lines = linecache.getlines(file, module.__dict__)
    name = cls.__name__
    pat = re.compile(r'^(\s*)class\s*'+name+r'\b')

    # AMVMOD: find the encoding (necessary for python 2 only)
    #if PY2:
    #    with open(file, 'rb') as infile:
    #        encoding = detect_encoding(infile.readline)[0]

    # make some effort to find the best matching class definition:
    # use the one with the least indentation, which is the one
    # that's most probably not inside a function definition.
    candidates = []
    toplevel = False
    for i in range(len(lines)):
        match = pat.match(lines[i])
        if match:
            # if it's at toplevel, it's already the best one
            if lines[i][0] == 'c':
                flines, flnum = lines, i
                toplevel = True
                break
            # else add whitespace to candidate list
            candidates.append((match.group(1), i))
    if candidates and not toplevel:
        # this will sort by whitespace, and by line number,
        # less whitespace first
        candidates.sort()
        flines, flnum = lines, candidates[0][1]
    elif not candidates and not toplevel:
        raise IOError('could not find class definition')
    ### end modified inspect.findsource ###

    # this is what inspect.getsourcelines does
    glines = inspect.getblock(flines[flnum:])

    # And this is what inspect.getsource does
    if False: #if PY2:
        return ("".join(glines)).decode(encoding)
    else:
        return "".join(glines)

Response: This function is used to get the source of interactively defined classes.


Instruction:
Create a Python 3 function to
return a Job object for the requested job id.

Response:
def get_job(self, jobid):
        """ Return a Job object for the requested job id.

        The returned object will be suitable for retrieving output, but depending on the engine,
        may not populate all fields used at launch time (such as `job.inputs`, `job.commands`, etc.)

        Args:
            jobid (str): container id

        Returns:
            pyccc.job.Job: job object for this container

        Raises:
            pyccc.exceptions.JobNotFound: if no job could be located for this jobid
        """
        import shlex
        from pyccc.job import Job

        job = Job(engine=self)
        job.jobid = job.rundata.containerid = jobid
        try:
            jobdata = self.client.inspect_container(job.jobid)
        except docker.errors.NotFound:
            raise exceptions.JobNotFound(
                    'The daemon could not find containter "%s"' % job.jobid)

        cmd = jobdata['Config']['Cmd']
        entrypoint = jobdata['Config']['Entrypoint']

        if len(cmd) == 3 and cmd[0:2] == ['sh', '-c']:
            cmd = cmd[2]
        elif entrypoint is not None:
            cmd = entrypoint + cmd

        if isinstance(cmd, list):
            cmd = ' '.join(shlex.quote(x) for x in cmd)

        job.command = cmd
        job.env = jobdata['Config']['Env']
        job.workingdir = jobdata['Config']['WorkingDir']
        job.rundata.container = jobdata

        return job


Instruction:
Given the following Python 3 function, write the documentation
def submit(self, job):
        self._check_job(job)

        if job.workingdir is None:
            job.workingdir = self.default_wdir
        job.imageid = du.create_provisioned_image(self.client, job.image,
                                                  job.workingdir, job.inputs)

        container_args = self._generate_container_args(job)

        job.rundata.container = self.client.create_container(job.imageid, **container_args)
        self.client.start(job.rundata.container)
        job.rundata.containerid = job.rundata.container['Id']
        job.jobid = job.rundata.containerid

Response: Submit the job to the engine


Instruction:
Can you generate the documentation for the following Python 3 function
def dump_all_outputs(self, job, target, abspaths=None):
        import os
        import shutil
        from pathlib import Path

        root = Path(native_str(target))
        true_outputs = job.get_output()

        if abspaths or len(true_outputs) < self.BULK_OUTPUT_FILE_THRESHOLD:
            return super().dump_all_outputs(job, root, abspaths)

        stagingdir = root / Path(native_str(job.workingdir)).name
        workdir = job.get_directory(job.workingdir)
        if not root.is_dir():
            root.mkdir(parents=False)
        if stagingdir.exists():
            if PY2:
                raise IOError('Path % exists' % stagingdir)
            else:
                raise FileExistsError(stagingdir)
        workdir.put(str(root))
        assert stagingdir.is_dir()
        assert root in stagingdir.parents

        for pathstr in true_outputs:
            if os.path.isabs(pathstr):
                continue
            destpath = root / pathstr
            currpath = stagingdir / pathstr
            if not destpath.parent.is_dir():
                destpath.parent.mkdir(parents=True)
            currpath.rename(destpath)

        shutil.rmtree(str(stagingdir))

Response: Dump all outputs of the job to the target directory.


Instruction:
Make a summary of the following Python 3 code
def create_build_context(image, inputs, wdir):
    assert os.path.isabs(wdir)

    dockerlines = ["FROM %s" % image,
                    "RUN mkdir -p %s" % wdir]
    build_context = {}

    # This loop creates a Build Context for building the provisioned image
    # We create a tar archive to be added to the root of the image filesystem
    if inputs:
        dockerlines.append('COPY root /')
        for ifile, (path, obj) in enumerate(inputs.items()):
            if not os.path.isabs(path):
                path = os.path.join(wdir, path)
            assert path[0] == '/'
            build_context['root' + path] = obj

    dockerstring = '\n'.join(dockerlines)
    build_context['Dockerfile'] = pyccc.BytesContainer(dockerstring.encode('utf-8'))
    return build_context

Response: Create a build context for the provisioned image


Instruction:
Can you generate the documentation for the following Python 3 function
def make_tar_stream(build_context, buffer):
    tf = tarfile.TarFile(fileobj=buffer, mode='w')
    for context_path, fileobj in build_context.items():
        if getattr(fileobj, 'localpath', None) is not None:
            tf.add(fileobj.localpath, arcname=context_path)
        else:
            tar_add_bytes(tf, context_path, fileobj.read('rb'))
    tf.close()

Response: Create a tar stream of the build context to the provided buffer


Instruction:
Write a Python 3 script for
adding a file to a tar archive containing the bytestring

Response:
def tar_add_bytes(tf, filename, bytestring):
    """ Add a file to a tar archive

    Args:
        tf (tarfile.TarFile): tarfile to add the file to
        filename (str): path within the tar file
        bytestring (bytes or str): file contents. Must be :class:`bytes` or
            ascii-encodable :class:`str`
    """
    if not isinstance(bytestring, bytes):  # it hasn't been encoded yet
        bytestring = bytestring.encode('ascii')
    buff = io.BytesIO(bytestring)
    tarinfo = tarfile.TarInfo(filename)
    tarinfo.size = len(bytestring)
    tf.addfile(tarinfo, buff)


Instruction:
Here you have a function in Python 3, explain what it does
def kwargs_from_client(client, assert_hostname=False):
    from docker import tls
    if client.base_url in ('http+docker://localunixsocket', 'http+docker://localhost'):
        return {'base_url': 'unix://var/run/docker.sock'}

    params = {'base_url': client.base_url}
    if client.cert:
        # TODO: problem - client.cert is filepaths, and it would be insecure to send those files.
        params['tls'] = tls.TLSConfig(
            client_cert=client.cert,
            ca_cert=client.verify,
            verify=bool(client.verify),
            assert_hostname=assert_hostname)

    return params

Response: Returns a dictionary of keyword arguments to pass to the Docker client.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def find_class(self, module, name):
        import pickle

        modname = self.RENAMETABLE.get(module, module)

        try:
            # can't use ``super`` here (not 2/3 compatible)
            klass = pickle.Unpickler.find_class(self, modname, name)

        except (ImportError, RuntimeError):
            definition = getattr(source, name)
            newmod = _makemod(modname)
            sys.modules[modname] = newmod
            setattr(newmod, name, definition)
            klass = pickle.Unpickler.find_class(self, newmod.__name__, name)
            klass.__module__ = module
        return klass

Response: This override is here to help pickle find the class in the given module and name.


Instruction:
Here you have a function in Python 3, explain what it does
def gist_diff():
    remote_file = wget(RAW_GIST)
    proc = subprocess.Popen(('diff - %s'%MY_PATH).split(),
                            stdin=subprocess.PIPE,
                            stdout=subprocess.PIPE)
    stdout, stderr = proc.communicate(remote_file)
    return stdout

Response: Diff this file with the gist on github


Instruction:
Write a Python 3 function that can
download the page into a string

Response:
def wget(url):
    """
    Download the page into a string
    """
    import urllib.parse
    request = urllib.request.urlopen(url)
    filestring = request.read()
    return filestring


Instruction:
How would you implement a function in Python 3 that
tries to decode bytes to text - try to autodetect Taxonomy first otherwise try to autodetect Taxonomy

Response:
def autodecode(b):
    """ Try to decode ``bytes`` to text - try default encoding first, otherwise try to autodetect

    Args:
        b (bytes): byte string

    Returns:
        str: decoded text string
    """
    import warnings
    import chardet

    try:
        return b.decode()
    except UnicodeError:
        result = chardet.detect(b)
        if result['confidence'] < 0.95:
            warnings.warn('autodecode failed with utf-8; guessing %s' % result['encoding'])
        return result.decode(result['encoding'])


Instruction:
Explain what the following Python 3 code does
def can_use_widgets():
    if 'IPython' not in sys.modules:
        # IPython hasn't been imported, definitely not
        return False
    from IPython import get_ipython

    # check for `kernel` attribute on the IPython instance
    if getattr(get_ipython(), 'kernel', None) is None:
        return False

    try:
        import ipywidgets as ipy
        import traitlets
    except ImportError:
        return False

    return True

Response: Check if IPython is available and if so return True if IPython is available and False otherwise.


Instruction:
Create a Python 3 function to
remove non - leafs from a list of directory paths

Response:
def remove_directories(list_of_paths):
    """
    Removes non-leafs from a list of directory paths
    """
    found_dirs = set('/')
    for path in list_of_paths:
        dirs = path.strip().split('/')
        for i in range(2,len(dirs)):
            found_dirs.add( '/'.join(dirs[:i]) )

    paths = [ path for path in list_of_paths if
              (path.strip() not in found_dirs) and path.strip()[-1]!='/' ]
    return paths


Instruction:
Write a Python 3 function for
checking if the input file is under the working directory.

Response:
def _check_file_is_under_workingdir(filename, wdir):
        """ Raise error if input is being staged to a location not underneath the working dir
        """
        p = filename
        if not os.path.isabs(p):
            p = os.path.join(wdir, p)
        targetpath = os.path.realpath(p)
        wdir = os.path.realpath(wdir)
        common = os.path.commonprefix([wdir, targetpath])
        if len(common) < len(wdir):
            raise exceptions.PathError(
                    "The subprocess engine does not support input files with absolute paths")
        return p


Instruction:
Can you write a function in Python 3 where it
writes the file to the given path.

Response:
def put(self, filename, encoding=None):
        """Write the file to the given path

        Args:
            filename(str): path to write this file to

        Returns:
            LocalFile: reference to the copy of the file stored at ``filename``
        """
        from . import LocalFile

        if os.path.isdir(filename) and self.source is None:
            raise ValueError("Cannot write this object to "
                             "directory %s without an explicit filename." % filename)

        target = get_target_path(filename, self.source)

        if (encoding is not None) and (encoding != self.encoded_with):
            raise ValueError('%s is already encoded as "%s"' % self, self.encoded_with)

        with self.open('rb') as infile, open(target, 'wb') as outfile:
            for line in infile:
                outfile.write(line)
        return LocalFile(target)


Instruction:
Make a summary of the following Python 3 code
def open(self, mode='r', encoding=None):
        access_type = self._get_access_type(mode)

        if access_type == 't' and encoding is not None and encoding != self.encoded_with:
            warnings.warn('Attempting to decode %s as "%s", but encoding is declared as "%s"'
                          % (self, encoding, self.encoded_with))

        if encoding is None:
            encoding = self.encoded_with

        buffer = io.BytesIO(self._contents)
        if access_type == 'b':
            return buffer
        else:
            return io.TextIOWrapper(buffer, encoding=encoding)

Response: Return file - like object containing the contents of the file.


Instruction:
Implement a Python 3 function for
returning the path to the target file.

Response:
def get_target_path(destination, origname):
    """ Implements the directory/path semantics of linux mv/cp etc.

    Examples:
        >>> import os
        >>> os.makedirs('./a')
        >>> get_target_path('./a', '/tmp/myfile')
        './myfile'
        >>> get_target_path('./a/b', '/tmp/myfile')
        './a/b'

    Raises:
        OSError: if neither destination NOR destination's parent exists OR it already exists
    """
    if os.path.exists(destination):
        if not os.path.isdir(destination):
            raise OSError('Cannot write to requested destination %s - file exists' % destination)
        return os.path.join(destination, os.path.basename(origname))
    else:
        destdir = os.path.abspath(os.path.join(destination, os.path.pardir))
        if not os.path.isdir(destdir):
            raise OSError(
                    'Cannot write to requested destination %s - parent directory does not exist' %
                    destination)
        return os.path.join(destination)


Instruction:
Given the following Python 3 function, write the documentation
def put(self, filename):
        from . import LocalFile
        target = get_target_path(filename, self.source)
        with self.open('rb') as infile, open(target, 'wb') as outfile:
            shutil.copyfileobj(infile, outfile)
        return LocalFile(target)

Response: Write the file to the given path


Instruction:
Create a Python 3 function to
return the type of the file in mode.

Response:
def _get_access_type(self, mode):
        """ Make sure mode is appropriate; return 'b' for binary access and 't' for text
        """
        access_type = None
        for char in mode:  # figure out whether it's binary or text access
            if char in 'bt':
                if access_type is not None:
                    raise IOError('File mode "%s" contains contradictory flags' % mode)
                access_type = char
            elif char not in 'rbt':
                raise NotImplementedError(
                        '%s objects are read-only; unsupported mode "%s"'%
                        (type(self), mode))

        if access_type is None: access_type = 't'
        return access_type


Instruction:
Can you write a function in Python 3 where it
gets the mapping of free variables to their current values.

Response:
def getclosurevars(func):
    """
    Get the mapping of free variables to their current values.

    Returns a named tuple of dicts mapping the current nonlocal, global
    and builtin references as seen by the body of the function. A final
    set of unbound names that could not be resolved is also provided.

    Note:
        Modified function from the Python 3.5 inspect standard library module

        Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010,
        2011, 2012, 2013, 2014, 2015, 2016, 2017 Python Software Foundation; All Rights
        Reserved"

        See also py-cloud-compute-cannon/NOTICES.
    """
    if inspect.ismethod(func):
        func = func.__func__

    elif not inspect.isroutine(func):
        raise TypeError("'{!r}' is not a Python function".format(func))

    # AMVMOD: deal with python 2 builtins that don't define these
    code = getattr(func, '__code__', None)
    closure = getattr(func, '__closure__', None)
    co_names = getattr(code, 'co_names', ())
    glb = getattr(func, '__globals__', {})

    # Nonlocal references are named in co_freevars and resolved
    # by looking them up in __closure__ by positional index
    if closure is None:
        nonlocal_vars = {}
    else:
        nonlocal_vars = {var: cell.cell_contents
                         for var, cell in zip(code.co_freevars, func.__closure__)}

    # Global and builtin references are named in co_names and resolved
    # by looking them up in __globals__ or __builtins__
    global_ns = glb
    builtin_ns = global_ns.get("__builtins__", builtins.__dict__)
    if inspect.ismodule(builtin_ns):
        builtin_ns = builtin_ns.__dict__
    global_vars = {}
    builtin_vars = {}
    unbound_names = set()
    for name in co_names:
        if name in ("None", "True", "False"):
            # Because these used to be builtins instead of keywords, they
            # may still show up as name references. We ignore them.
            continue
        try:
            global_vars[name] = global_ns[name]
        except KeyError:
            try:
                builtin_vars[name] = builtin_ns[name]
            except KeyError:
                unbound_names.add(name)

    return {'nonlocal': nonlocal_vars,
            'global': global_vars,
            'builtin': builtin_vars,
            'unbound': unbound_names}


Instruction:
Can you tell what is the following Python 3 function doing
def put(self, destination):
        target = get_target_path(destination, self.localpath)
        shutil.copytree(self.localpath, target)

Response: Copy the referenced directory to the destination.


Instruction:
How would you explain what the following Python 3 function does
def put(self, destination):
        target = get_target_path(destination, self.dirname)
        valid_paths = (self.dirname, './%s' % self.dirname)

        with tarfile.open(self.archive_path, 'r:*') as tf:
            members = []
            for tarinfo in tf:
                # Get only files under the directory `self.dirname`
                pathsplit = os.path.normpath(tarinfo.path).split(os.sep)
                if pathsplit[0] not in valid_paths:
                    print('WARNING: skipped file "%s" in archive; not in directory "%s"' %
                          (tarinfo.path, self.dirname))
                    continue
                if len(pathsplit) == 1:
                    continue
                tarinfo.name = os.path.join(*pathsplit[1:])
                members.append(tarinfo)

            if not members:
                raise ValueError("No files under path directory '%s' in this tarfile")

            tf.extractall(target, members)

Response: Copy the referenced directory to the destination directory.


Instruction:
How would you explain what the following Python 3 function does
def put(self, destination):
        if not self._fetched:
            self._fetch()
        DirectoryArchive.put(self, destination)

Response: Copy the referenced directory to this path


Instruction:
How would you code a function in Python 3 to
dump all outputs of the job to a directory.

Response:
def dump_all_outputs(self, job, target, abspaths=None):
        """ Default dumping strategy - potentially slow for large numbers of files

        Subclasses should offer faster implementations, if available
        """
        from pathlib import Path
        root = Path(native_str(target))

        for outputpath, outputfile in job.get_output().items():
            path = Path(native_str(outputpath))

            # redirect absolute paths into the appropriate subdirectory
            if path.is_absolute():
                if abspaths:
                    path = Path(native_str(abspaths), *path.parts[1:])
                else:
                    continue

            dest = root / path
            if not dest.parent.is_dir():
                dest.parent.mkdir(parents=True)
            if dest.is_file():
                dest.unlink()
            try:
                outputfile.put(str(dest))
            except IsADirectoryError:
                if not dest.is_dir():
                    dest.mkdir(parents=True)


Instruction:
Explain what the following Python 3 code does
def launch(self, image, command, **kwargs):
        if isinstance(command, PythonCall):
            return PythonJob(self, image, command, **kwargs)
        else:
            return Job(self, image, command, **kwargs)

Response: Create a job on this engine


Instruction:
Here you have a function in Python 3, explain what it does
def char_width(char):
    if ord(char) < 128:
        return 1
    elif unicodedata.east_asian_width(char) in ('F', 'W'):
        return 2
    elif unicodedata.category(char) in ('Mn',):
        return 0
    else:
        return 1

Response: Get the display length of a unicode character.


Instruction:
Explain what the following Python 3 code does
def display_len(text):
    text = unicodedata.normalize('NFD', text)
    return sum(char_width(char) for char in text)

Response: Get the display length of a string.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def filter_regex(names, regex):
    return tuple(name for name in names
                 if regex.search(name) is not None)

Response: Filter a list of strings by a regular expression.


Instruction:
Explain what the following Python 3 code does
def filter_wildcard(names, pattern):
    return tuple(name for name in names
                 if fnmatch.fnmatch(name, pattern))

Response: Filter a list of strings that match a shell - style wildcard pattern.


Instruction:
How would you explain what the following Python 3 function does
def match(self, obj, attrs):
        if '__doc__' in attrs:
            lstrip = getattr(obj.__doc__, 'lstrip', False)
            return lstrip and any(lstrip())

Response: Match if the object contains a non - empty docstring.


Instruction:
Write a Python 3 script to
evaluate the packaged function as func.

Response:
def run(self, func=None):
        """
        Evaluates the packaged function as func(*self.args,**self.kwargs)
        If func is a method of an object, it's accessed as getattr(self.obj,__name__).
        If it's a user-defined function, it needs to be passed in here because it can't
        be serialized.

        Returns:
            object: function's return value
        """
        to_run = self.prepare_namespace(func)
        result = to_run(*self.args, **self.kwargs)
        return result


Instruction:
Explain what the following Python 3 code does
def prepare_namespace(self, func):
        if self.is_imethod:
            to_run = getattr(self.obj, self.imethod_name)
        else:
            to_run = func

        for varname, modulename in self.global_modules.items():
            to_run.__globals__[varname] = __import__(modulename)
        if self.global_closure:
            to_run.__globals__.update(self.global_closure)
        if self.global_functions:
            to_run.__globals__.update(self.global_functions)
        return to_run

Response: Prepares the function to be run after deserializing it.


Instruction:
Can you write a function in Python 3 where it
builds a list - table directive.

Response:
def make_list_table(headers, data, title='', columns=None):
    """Build a list-table directive.

    :param headers: List of header values.
    :param data: Iterable of row data, yielding lists or tuples with rows.
    :param title: Optional text to show as the table title.
    :param columns: Optional widths for the columns.
    """
    results = []
    add = results.append
    add('.. list-table:: %s' % title)
    add('   :header-rows: 1')
    if columns:
        add('   :widths: %s' % (','.join(str(c) for c in columns)))
    add('')
    add('   - * %s' % headers[0])
    for h in headers[1:]:
        add('     * %s' % h)
    for row in data:
        add('   - * %s' % row[0])
        for r in row[1:]:
            add('     * %s' % r)
    add('')
    return '\n'.join(results)


Instruction:
Here you have a function in Python 3, explain what it does
def make_list_table_from_mappings(headers, data, title, columns=None):
    header_names = [h[0] for h in headers]
    header_keys = [h[1] for h in headers]
    row_data = (
        [d.get(k) for k in header_keys]
        for d in data
    )
    return make_list_table(header_names, row_data, title, columns)

Response: Builds a list - table directive from mappings.


Instruction:
How would you code a function in Python 3 to
format a decimal. Decimal like to 2 decimal places.

Response:
def decimal_format(value, TWOPLACES=Decimal(100) ** -2):
    'Format a decimal.Decimal like to 2 decimal places.'
    if not isinstance(value, Decimal):
        value = Decimal(str(value))
    return value.quantize(TWOPLACES)


Instruction:
Write a Python 3 function for
displaying two radio buttons for turning notifications on or off.

Response:
def notification_preference(obj_type, profile):
    '''Display two radio buttons for turning notifications on or off.
    The default value is is have alerts_on = True.
    '''
    default_alert_value = True
    if not profile:
        alerts_on = True
    else:
        notifications = profile.get('notifications', {})
        alerts_on = notifications.get(obj_type, default_alert_value)
    return dict(alerts_on=alerts_on, obj_type=obj_type)


Instruction:
Can you generate the documentation for the following Python 3 function
def committee_object(self):
        '''If the committee id no longer exists in mongo for some reason,
        this function returns None.
        '''
        if 'committee_id' in self:
            _id = self['committee_id']
            return self.document._old_roles_committees.get(_id)
        else:
            return self

Response: Return the object that is associated with the committee id.