Instruction:
Can you generate the documentation for the following Python 3 function
def cli(**args):
    import shakedown

    # Read configuration options from ~/.shakedown (if exists)
    args = read_config(args)

    # Set configuration defaults
    args = set_config_defaults(args)

    if args['quiet']:
        shakedown.cli.quiet = True

    if not args['dcos_url']:
        try:
            args['dcos_url'] = dcos_url()
        except:
            click.secho('error: cluster URL not set, use --dcos-url or see --help for more information.', fg='red', bold=True)
            sys.exit(1)

    if not args['dcos_url']:
        click.secho('error: --dcos-url is a required option; see --help for more information.', fg='red', bold=True)
        sys.exit(1)

    if args['ssh_key_file']:
        shakedown.cli.ssh_key_file = args['ssh_key_file']

    if args['ssh_user']:
        shakedown.cli.ssh_user = args['ssh_user']

    if not args['no_banner']:
        echo(banner(), n=False)

    echo('Running pre-flight checks...', d='step-maj')

    # required modules and their 'version' method
    imported = {}
    requirements = {
        'pytest': '__version__',
        'dcos': 'version'
    }

    for req in requirements:
        ver = requirements[req]

        echo("Checking for {} library...".format(req), d='step-min', n=False)
        try:
            imported[req] = importlib.import_module(req, package=None)
        except ImportError:
            click.secho("error: {p} is not installed; run 'pip install {p}'.".format(p=req), fg='red', bold=True)
            sys.exit(1)

        echo(getattr(imported[req], requirements[req]))

    if shakedown.attach_cluster(args['dcos_url']):
        echo('Checking DC/OS cluster version...', d='step-min', n=False)
        echo(shakedown.dcos_version())
    else:
        with imported['dcos'].cluster.setup_directory() as temp_path:
            imported['dcos'].cluster.set_attached(temp_path)

            imported['dcos'].config.set_val('core.dcos_url', args['dcos_url'])
            if args['ssl_no_verify']:
                imported['dcos'].config.set_val('core.ssl_verify', 'False')

            try:
                imported['dcos'].cluster.setup_cluster_config(args['dcos_url'], temp_path, False)
            except:
                echo('Authenticating with DC/OS cluster...', d='step-min')
                authenticated = False
                token = imported['dcos'].config.get_config_val("core.dcos_acs_token")
                if token is not None:
                    echo('trying existing ACS token...', d='step-min', n=False)
                    try:
                        shakedown.dcos_leader()

                        authenticated = True
                        echo(fchr('PP'), d='pass')
                    except imported['dcos'].errors.DCOSException:
                        echo(fchr('FF'), d='fail')
                if not authenticated and args['oauth_token']:
                    try:
                        echo('trying OAuth token...', d='item-maj', n=False)
                        token = shakedown.authenticate_oauth(args['oauth_token'])

                        with stdchannel_redirected(sys.stderr, os.devnull):
                            imported['dcos'].config.set_val('core.dcos_acs_token', token)

                        authenticated = True
                        echo(fchr('PP'), d='pass')
                    except:
                       echo(fchr('FF'), d='fail')
                if not authenticated and args['username'] and args['password']:
                    try:
                        echo('trying username and password...', d='item-maj', n=False)
                        token = shakedown.authenticate(args['username'], args['password'])

                        with stdchannel_redirected(sys.stderr, os.devnull):
                            imported['dcos'].config.set_val('core.dcos_acs_token', token)

                        authenticated = True
                        echo(fchr('PP'), d='pass')
                    except:
                        echo(fchr('FF'), d='fail')

                if authenticated:
                    imported['dcos'].cluster.setup_cluster_config(args['dcos_url'], temp_path, False)

                    echo('Checking DC/OS cluster version...', d='step-min', n=False)
                    echo(shakedown.dcos_version())
                else:
                    click.secho("error: no authentication credentials or token found.", fg='red', bold=True)
                    sys.exit(1)

    class shakedown:
        """ This encapsulates a PyTest wrapper plugin
        """

        state = {}

        stdout = []

        tests = {
            'file': {},
            'test': {}
        }

        report_stats = {
            'passed':[],
            'skipped':[],
            'failed':[],
            'total_passed':0,
            'total_skipped':0,
            'total_failed':0,
        }

        def output(title, state, text, status=True):
            """ Capture and display stdout/stderr output

                :param title: the title of the output box (eg. test name)
                :type title: str
                :param state: state of the result (pass, fail)
                :type state: str
                :param text: the stdout/stderr output
                :type text: str
                :param status: whether to output a status marker
                :type status: bool
            """
            if state == 'fail':
                schr = fchr('FF')
            elif state == 'pass':
                schr = fchr('PP')
            elif state == 'skip':
                schr = fchr('SK')
            else:
                schr = ''

            if status:
                if not args['stdout_inline']:
                    if state == 'fail':
                        echo(schr, d='fail')
                    elif state == 'pass':
                        echo(schr, d='pass')
                else:
                    if not text:
                        if state == 'fail':
                            echo(schr, d='fail')
                        elif state == 'pass':
                            if '::' in title:
                                echo(title.split('::')[-1], d='item-min', n=False)
                            echo(schr, d='pass')

            if text and args['stdout'] in [state, 'all']:
                o = decorate(schr + ': ', 'quote-head-' + state)
                o += click.style(decorate(title, style=state), bold=True) + "\n"
                o += decorate(str(text).strip(), style='quote-' + state)

                if args['stdout_inline']:
                    echo(o)
                else:
                    shakedown.stdout.append(o)

        def pytest_collectreport(self, report):
            """ Collect and validate individual test files
            """

            if not 'collect' in shakedown.state:
                shakedown.state['collect'] = 1
                echo('Collecting and validating test files...', d='step-min')

            if report.nodeid:
                echo(report.nodeid, d='item-maj', n=False)

                state = None

                if report.failed:
                    state = 'fail'
                if report.passed:
                    state = 'pass'
                if report.skipped:
                    state = 'skip'

                if state:
                    if report.longrepr:
                        shakedown.output(report.nodeid, state, report.longrepr)
                    else:
                        shakedown.output(report.nodeid, state, None)

        def pytest_sessionstart(self):
            """ Tests have been collected, begin running them...
            """

            echo('Initiating testing phase...', d='step-maj')

        def pytest_report_teststatus(self, report):
            """ Print report results to the console as they are run
            """

            try:
                report_file, report_test = report.nodeid.split('::', 1)
            except ValueError:
                return

            if not 'test' in shakedown.state:
                shakedown.state['test'] = 1
                echo('Running individual tests...', d='step-min')

            if not report_file in shakedown.tests['file']:
                shakedown.tests['file'][report_file] = 1
                echo(report_file, d='item-maj')
            if not report.nodeid in shakedown.tests['test']:
                shakedown.tests['test'][report.nodeid] = {}
                if args['stdout_inline']:
                    echo('')
                    echo(report_test + ':', d='item-min')
                else:
                    echo(report_test, d='item-min', n=False)

            if report.failed:
                shakedown.tests['test'][report.nodeid]['fail'] = True

            if report.when == 'teardown' and not 'tested' in shakedown.tests['test'][report.nodeid]:
                shakedown.output(report.nodeid, 'pass', None)

            # Suppress excess terminal output
            return report.outcome, None, None

        def pytest_runtest_logreport(self, report):
            """ Log the [stdout, stderr] results of tests if desired
            """

            state = None

            for secname, content in report.sections:
                if report.failed:
                    state = 'fail'
                if report.passed:
                    state = 'pass'
                if report.skipped:
                    state = 'skip'

                if state and secname != 'Captured stdout call':
                    module = report.nodeid.split('::', 1)[0]
                    cap_type = secname.split(' ')[-1]

                    if not 'setup' in shakedown.tests['test'][report.nodeid]:
                        shakedown.tests['test'][report.nodeid]['setup'] = True
                        shakedown.output(module + ' ' + cap_type, state, content, False)
                    elif cap_type == 'teardown':
                        shakedown.output(module + ' ' + cap_type, state, content, False)
                elif state and report.when == 'call':
                    if 'tested' in shakedown.tests['test'][report.nodeid]:
                        shakedown.output(report.nodeid, state, content, False)
                    else:
                        shakedown.tests['test'][report.nodeid]['tested'] = True
                        shakedown.output(report.nodeid, state, content)

            # Capture execution crashes
            if hasattr(report.longrepr, 'reprcrash'):
                longreport = report.longrepr

                if 'tested' in shakedown.tests['test'][report.nodeid]:
                    shakedown.output(report.nodeid, 'fail', 'error: ' + str(longreport.reprcrash), False)
                else:
                    shakedown.tests['test'][report.nodeid]['tested'] = True
                    shakedown.output(report.nodeid, 'fail', 'error: ' + str(longreport.reprcrash))

        def pytest_sessionfinish(self, session, exitstatus):
            """ Testing phase is complete; print extra reports (stdout/stderr, JSON) as requested
            """

            echo('Test phase completed.', d='step-maj')

            if ('stdout' in args and args['stdout']) and shakedown.stdout:
                for output in shakedown.stdout:
                    echo(output)

    opts = ['-q', '--tb=no', "--timeout={}".format(args['timeout'])]

    if args['fail'] == 'fast':
        opts.append('-x')

    if args['pytest_option']:
        for opt in args['pytest_option']:
            opts.append(opt)

    if args['stdout_inline']:
        opts.append('-s')

    if args['tests']:
        tests_to_run = []
        for test in args['tests']:
            tests_to_run.extend(test.split())
        for test in tests_to_run:
            opts.append(test)

    exitstatus = imported['pytest'].main(opts, plugins=[shakedown()])

    sys.exit(exitstatus)

Response: This is the main CLI for the DCOS test - harness tool.


Instruction:
Create a Python 3 function to
find the bounding box of the tile that is available at a given zoom level.

Response:
def find_coverage(self, zoom):
        """
        Returns the bounding box (minx, miny, maxx, maxy) of an adjacent
        group of tiles at this zoom level.
        """
        # Find a group of adjacent available tiles at this zoom level
        rows = self._query('''SELECT tile_column, tile_row FROM tiles
                              WHERE zoom_level=?
                              ORDER BY tile_column, tile_row;''', (zoom,))
        t = rows.fetchone()
        xmin, ymin = t
        previous = t
        while t and t[0] - previous[0] <= 1:
            # adjacent, go on
            previous = t
            t = rows.fetchone()
        xmax, ymax = previous
        # Transform (xmin, ymin) (xmax, ymax) to pixels
        S = self.tilesize
        bottomleft = (xmin * S, (ymax + 1) * S)
        topright = ((xmax + 1) * S, ymin * S)
        # Convert center to (lon, lat)
        proj = GoogleProjection(S, [zoom])  # WGS84
        return proj.unproject_pixels(bottomleft, zoom) + proj.unproject_pixels(topright, zoom)


Instruction:
Here you have a function in Python 3, explain what it does
def tile(self, z, x, y):
        logger.debug(_("Download tile %s") % ((z, x, y),))
        # Render each keyword in URL ({s}, {x}, {y}, {z}, {size} ... )
        size = self.tilesize
        s = self.tiles_subdomains[(x + y) % len(self.tiles_subdomains)];
        try:
            url = self.tiles_url.format(**locals())
        except KeyError as e:
            raise DownloadError(_("Unknown keyword %s in URL") % e)

        logger.debug(_("Retrieve tile at %s") % url)
        r = DOWNLOAD_RETRIES
        sleeptime = 1
        while r > 0:
            try:
                request = requests.get(url, headers=self.headers)
                if request.status_code == 200:
                    return request.content
                raise DownloadError(_("Status code : %s, url : %s") % (request.status_code, url))
            except requests.exceptions.ConnectionError as e:
                logger.debug(_("Download error, retry (%s left). (%s)") % (r, e))
                r -= 1
                time.sleep(sleeptime)
                # progressivly sleep longer to wait for this tile
                if (sleeptime <= 10) and (r % 2 == 0):
                    sleeptime += 1  # increase wait
        raise DownloadError(_("Cannot download URL %s") % url)

Response: Download the specified tile from the specified URL.


Instruction:
Create a Python 3 function for
rendering the specified tile with Mapnik

Response:
def tile(self, z, x, y):
        """
        Render the specified tile with Mapnik
        """
        logger.debug(_("Render tile %s") % ((z, x, y),))
        proj = GoogleProjection(self.tilesize, [z])
        return self.render(proj.tile_bbox((z, x, y)))


Instruction:
Can you generate the documentation for the following Python 3 function
def render(self, bbox, width=None, height=None):
        width = width or self.tilesize
        height = height or self.tilesize
        self._prepare_rendering(bbox, width=width, height=height)

        # Render image with default Agg renderer
        tmpfile = NamedTemporaryFile(delete=False)
        im = mapnik.Image(width, height)
        mapnik.render(self._mapnik, im)
        im.save(tmpfile.name, 'png256')  # TODO: mapnik output only to file?
        tmpfile.close()
        content = open(tmpfile.name, 'rb').read()
        os.unlink(tmpfile.name)
        return content

Response: Render the specified tile with Mapnik


Instruction:
Given the following Python 3 function, write the documentation
def grid(self, z, x, y, fields, layer):
        logger.debug(_("Render grid %s") % ((z, x, y),))
        proj = GoogleProjection(self.tilesize, [z])
        return self.render_grid(proj.tile_bbox((z, x, y)), fields, layer)

Response: Render a grid with Mapnik s tile bounding box.


Instruction:
Make a summary of the following Python 3 code
def render_grid(self, bbox, grid_fields, layer, width=None, height=None):
        width = width or self.tilesize
        height = height or self.tilesize
        self._prepare_rendering(bbox, width=width, height=height)

        grid = mapnik.Grid(width, height)
        mapnik.render_layer(self._mapnik, grid, layer=layer, fields=grid_fields)
        grid = grid.encode()
        return json.dumps(grid)

Response: Render the specified grid with Mapnik


Instruction:
Can you create a Python 3 function that
returns a tuple of z x y coordinates for the tile at the given zoom level and position.

Response:
def tile_at(self, zoom, position):
        """
        Returns a tuple of (z, x, y)
        """
        x, y = self.project_pixels(position, zoom)
        return (zoom, int(x/self.tilesize), int(y/self.tilesize))


Instruction:
Implement a Python 3 function for
returning the coordinates in meters from WGS84

Response:
def project(self, lng_lat):
        """
        Returns the coordinates in meters from WGS84
        """
        (lng, lat) = lng_lat
        x = lng * DEG_TO_RAD
        lat = max(min(MAX_LATITUDE, lat), -MAX_LATITUDE)
        y = lat * DEG_TO_RAD
        y = log(tan((pi / 4) + (y / 2)))
        return (x*EARTH_RADIUS, y*EARTH_RADIUS)


Instruction:
Create a Python 3 function for
converting a color string to a color tuple.

Response:
def string2rgba(cls, colorstring):
        """ Convert #RRGGBBAA to an (R, G, B, A) tuple """
        colorstring = colorstring.strip()
        if colorstring[0] == '#':
            colorstring = colorstring[1:]
        if len(colorstring) < 6:
            raise ValueError("input #%s is not in #RRGGBB format" % colorstring)
        r, g, b = colorstring[:2], colorstring[2:4], colorstring[4:6]
        a = 'ff'
        if len(colorstring) > 6:
            a = colorstring[6:8]
        r, g, b, a = [int(n, 16) for n in (r, g, b, a)]
        return (r, g, b, a)


Instruction:
Explain what the following Python 3 code does
def tileslist(self, bbox, zoomlevels):
        proj = GoogleProjection(self.tile_size, zoomlevels, self.tile_scheme)
        return proj.tileslist(bbox)

Response: Build the tiles list within the bottom - left or top - right bounding box at the specified zoom levels.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def add_layer(self, tilemanager, opacity=1.0):
        assert has_pil, _("Cannot blend layers without python PIL")
        assert self.tile_size == tilemanager.tile_size, _("Cannot blend layers whose tile size differs")
        assert 0 <= opacity <= 1, _("Opacity should be between 0.0 (transparent) and 1.0 (opaque)")
        self.cache.basename += '%s%.1f' % (tilemanager.cache.basename, opacity)
        self._layers.append((tilemanager, opacity))

Response: Add a layer to be blended on top of the tile.


Instruction:
Write a Python 3 function for
adding an image filter for post - processing.

Response:
def add_filter(self, filter_):
        """ Add an image filter for post-processing """
        assert has_pil, _("Cannot add filters without python PIL")
        self.cache.basename += filter_.basename
        self._filters.append(filter_)


Instruction:
Here you have a function in Python 3, explain what it does
def tile(self, z_x_y):
        (z, x, y) = z_x_y
        logger.debug(_("tile method called with %s") % ([z, x, y]))

        output = self.cache.read((z, x, y))
        if output is None:
            output = self.reader.tile(z, x, y)
            # Blend layers
            if len(self._layers) > 0:
                logger.debug(_("Will blend %s layer(s)") % len(self._layers))
                output = self._blend_layers(output, (z, x, y))
            # Apply filters
            for f in self._filters:
                image = f.process(self._tile_image(output))
                output = self._image_tile(image)
            # Save result to cache
            self.cache.save(output, (z, x, y))

            self.rendered += 1
        return output

Response: Return the binary content of the tile and seed the cache.


Instruction:
Given the following Python 3 function, write the documentation
def grid(self, z_x_y):
        # sources.py -> MapnikRenderer -> grid
        (z, x, y) = z_x_y
        content = self.reader.grid(z, x, y, self.grid_fields, self.grid_layer)
        return content

Response: Return the UTFGrid content for the given z - x - y.


Instruction:
Can you generate the documentation for the following Python 3 function
def _blend_layers(self, imagecontent, z_x_y):
        (z, x, y) = z_x_y
        result = self._tile_image(imagecontent)
        # Paste each layer
        for (layer, opacity) in self._layers:
            try:
                # Prepare tile of overlay, if available
                overlay = self._tile_image(layer.tile((z, x, y)))
            except (IOError, DownloadError, ExtractionError)as e:
                logger.warn(e)
                continue
            # Extract alpha mask
            overlay = overlay.convert("RGBA")
            r, g, b, a = overlay.split()
            overlay = Image.merge("RGB", (r, g, b))
            a = ImageEnhance.Brightness(a).enhance(opacity)
            overlay.putalpha(a)
            mask = Image.merge("L", (a,))
            result.paste(overlay, (0, 0), mask)
        # Read result
        return self._image_tile(result)

Response: Blends all layers into a single tile.


Instruction:
Implement a function in Python 3 to
tile binary content as PIL Image.

Response:
def _tile_image(self, data):
        """
        Tile binary content as PIL Image.
        """
        image = Image.open(BytesIO(data))
        return image.convert('RGBA')


Instruction:
Can you generate a brief explanation for the following Python 3 code
def zoomlevels(self):
        zooms = set()
        for coverage in self._bboxes:
            for zoom in coverage[1]:
                zooms.add(zoom)
        return sorted(zooms)

Response: Return the list of covered zoom levels in ascending order


Instruction:
Can you implement a function in Python 3 that
builds a MBTile file and add coverage to the metadata.

Response:
def run(self, force=False):
        """
        Build a MBTile file.

        force -- overwrite if MBTiles file already exists.
        """
        if os.path.exists(self.filepath):
            if force:
                logger.warn(_("%s already exists. Overwrite.") % self.filepath)
                os.remove(self.filepath)
            else:
                # Already built, do not do anything.
                logger.info(_("%s already exists. Nothing to do.") % self.filepath)
                return

        # Clean previous runs
        self._clean_gather()

        # If no coverage added, use bottom layer metadata
        if len(self._bboxes) == 0 and len(self._layers) > 0:
            bottomlayer = self._layers[0]
            metadata = bottomlayer.reader.metadata()
            if 'bounds' in metadata:
                logger.debug(_("Use bounds of bottom layer %s") % bottomlayer)
                bbox = map(float, metadata.get('bounds', '').split(','))
                zoomlevels = range(int(metadata.get('minzoom', 0)), int(metadata.get('maxzoom', 0)))
                self.add_coverage(bbox=bbox, zoomlevels=zoomlevels)

        # Compute list of tiles
        tileslist = set()
        for bbox, levels in self._bboxes:
            logger.debug(_("Compute list of tiles for bbox %s on zooms %s.") % (bbox, levels))
            bboxlist = self.tileslist(bbox, levels)
            logger.debug(_("Add %s tiles.") % len(bboxlist))
            tileslist = tileslist.union(bboxlist)
            logger.debug(_("%s tiles in total.") % len(tileslist))
        self.nbtiles = len(tileslist)
        if not self.nbtiles:
            raise EmptyCoverageError(_("No tiles are covered by bounding boxes : %s") % self._bboxes)
        logger.debug(_("%s tiles to be packaged.") % self.nbtiles)

        # Go through whole list of tiles and gather them in tmp_dir
        self.rendered = 0
        for (z, x, y) in tileslist:
            try:
                self._gather((z, x, y))
            except Exception as e:
                logger.warn(e)
                if not self.ignore_errors:
                    raise

        logger.debug(_("%s tiles were missing.") % self.rendered)

        # Some metadata
        middlezoom = self.zoomlevels[len(self.zoomlevels) // 2]
        lat = self.bounds[1] + (self.bounds[3] - self.bounds[1])/2
        lon = self.bounds[0] + (self.bounds[2] - self.bounds[0])/2
        metadata = {}
        metadata['name'] = str(uuid.uuid4())
        metadata['format'] = self._tile_extension[1:]
        metadata['minzoom'] = self.zoomlevels[0]
        metadata['maxzoom'] = self.zoomlevels[-1]
        metadata['bounds'] = '%s,%s,%s,%s' % tuple(self.bounds)
        metadata['center'] = '%s,%s,%s' % (lon, lat, middlezoom)
        #display informations from the grids on hover
        content_to_display = ''
        for field_name in self.grid_fields:
            content_to_display += "{{{ %s }}}<br>" % field_name
        metadata['template'] = '{{#__location__}}{{/__location__}} {{#__teaser__}} \
        %s {{/__teaser__}}{{#__full__}}{{/__full__}}' % content_to_display
        metadatafile = os.path.join(self.tmp_dir, 'metadata.json')
        with open(metadatafile, 'w') as output:
            json.dump(metadata, output)

        # TODO: add UTF-Grid of last layer, if any

        # Package it!
        logger.info(_("Build MBTiles file '%s'.") % self.filepath)
        extension = self.tile_format.split("image/")[-1]
        disk_to_mbtiles(
            self.tmp_dir,
            self.filepath,
            format=extension,
            scheme=self.cache.scheme
        )

        try:
            os.remove("%s-journal" % self.filepath)  # created by mbutil
        except OSError as e:
            pass
        self._clean_gather()


Instruction:
Create a Python 3 function to
return a grid of x y tuples representing the juxtaposition of tiles on the specified bounding box at the specified zoomlevel.

Response:
def grid_tiles(self, bbox, zoomlevel):
        """
        Return a grid of (x, y) tuples representing the juxtaposition
        of tiles on the specified ``bbox`` at the specified ``zoomlevel``.
        """
        tiles = self.tileslist(bbox, [zoomlevel])
        grid = {}
        for (z, x, y) in tiles:
            if not grid.get(y):
                grid[y] = []
            grid[y].append(x)
        sortedgrid = []
        for y in sorted(grid.keys(), reverse=self.tile_scheme == 'tms'):
            sortedgrid.append([(x, y) for x in sorted(grid[y])])
        return sortedgrid


Instruction:
Make a summary of the following Python 3 code
def export_image(self, bbox, zoomlevel, imagepath):
        assert has_pil, _("Cannot export image without python PIL")
        grid = self.grid_tiles(bbox, zoomlevel)
        width = len(grid[0])
        height = len(grid)
        widthpix = width * self.tile_size
        heightpix = height * self.tile_size

        result = Image.new("RGBA", (widthpix, heightpix))
        offset = (0, 0)
        for i, row in enumerate(grid):
            for j, (x, y) in enumerate(row):
                offset = (j * self.tile_size, i * self.tile_size)
                img = self._tile_image(self.tile((zoomlevel, x, y)))
                result.paste(img, offset)
        logger.info(_("Save resulting image to '%s'") % imagepath)
        result.save(imagepath)

Response: Exports the image for the specified bounding box and zoomlevel.


Instruction:
Write a Python 3 function that can
run therough GPOS and make an alphabetically ordered list of scripts.

Response:
def _makeScriptOrder(gpos):
    """
    Run therough GPOS and make an alphabetically
    ordered list of scripts. If DFLT is in the list,
    move it to the front.
    """
    scripts = []
    for scriptRecord in gpos.ScriptList.ScriptRecord:
        scripts.append(scriptRecord.ScriptTag)
    if "DFLT" in scripts:
        scripts.remove("DFLT")
        scripts.insert(0, "DFLT")
    return sorted(scripts)


Instruction:
Write a Python 3 function that can
gather kerning and classes from the applicable lookups and return them in script order.

Response:
def _gatherDataFromLookups(gpos, scriptOrder):
    """
    Gather kerning and classes from the applicable lookups
    and return them in script order.
    """
    lookupIndexes = _gatherLookupIndexes(gpos)
    seenLookups = set()
    kerningDictionaries = []
    leftClassDictionaries = []
    rightClassDictionaries = []
    for script in scriptOrder:
        kerning = []
        leftClasses = []
        rightClasses = []
        for lookupIndex in lookupIndexes[script]:
            if lookupIndex in seenLookups:
                continue
            seenLookups.add(lookupIndex)
            result = _gatherKerningForLookup(gpos, lookupIndex)
            if result is None:
                continue
            k, lG, rG = result
            kerning.append(k)
            leftClasses.append(lG)
            rightClasses.append(rG)
        if kerning:
            kerningDictionaries.append(kerning)
            leftClassDictionaries.append(leftClasses)
            rightClassDictionaries.append(rightClasses)
    return kerningDictionaries, leftClassDictionaries, rightClassDictionaries


Instruction:
How would you implement a function in Python 3 that
gathers a mapping of script to lookup indexes for each kern feature.

Response:
def _gatherLookupIndexes(gpos):
    """
    Gather a mapping of script to lookup indexes
    referenced by the kern feature for each script.
    Returns a dictionary of this structure:
        {
            "latn" : [0],
            "DFLT" : [0]
        }
    """
    # gather the indexes of the kern features
    kernFeatureIndexes = [index for index, featureRecord in enumerate(gpos.FeatureList.FeatureRecord) if featureRecord.FeatureTag == "kern"]
    # find scripts and languages that have kern features
    scriptKernFeatureIndexes = {}
    for scriptRecord in gpos.ScriptList.ScriptRecord:
        script = scriptRecord.ScriptTag
        thisScriptKernFeatureIndexes = []
        defaultLangSysRecord = scriptRecord.Script.DefaultLangSys
        if defaultLangSysRecord is not None:
            f = []
            for featureIndex in defaultLangSysRecord.FeatureIndex:
                if featureIndex not in kernFeatureIndexes:
                    continue
                f.append(featureIndex)
            if f:
                thisScriptKernFeatureIndexes.append((None, f))
        if scriptRecord.Script.LangSysRecord is not None:
            for langSysRecord in scriptRecord.Script.LangSysRecord:
                langSys = langSysRecord.LangSysTag
                f = []
                for featureIndex in langSysRecord.LangSys.FeatureIndex:
                    if featureIndex not in kernFeatureIndexes:
                        continue
                    f.append(featureIndex)
                if f:
                    thisScriptKernFeatureIndexes.append((langSys, f))
        scriptKernFeatureIndexes[script] = thisScriptKernFeatureIndexes
    # convert the feature indexes to lookup indexes
    scriptLookupIndexes = {}
    for script, featureDefinitions in scriptKernFeatureIndexes.items():
        lookupIndexes = scriptLookupIndexes[script] = []
        for language, featureIndexes in featureDefinitions:
            for featureIndex in featureIndexes:
                featureRecord = gpos.FeatureList.FeatureRecord[featureIndex]
                for lookupIndex in featureRecord.Feature.LookupListIndex:
                    if lookupIndex not in lookupIndexes:
                        lookupIndexes.append(lookupIndex)
    # done
    return scriptLookupIndexes


Instruction:
Implement a Python 3 function for
gathering the kerning and left clases and right classes for a particular lookup.

Response:
def _gatherKerningForLookup(gpos, lookupIndex):
    """
    Gather the kerning and class data for a particular lookup.
    Returns kerning, left clases, right classes.
    The kerning dictionary is of this structure:
        {
            ("a", "a") : 10,
            ((1, 1, 3), "a") : -20
        }
    The class dictionaries have this structure:
        {
            (1, 1, 3) : ["x", "y", "z"]
        }
    Where the tuple means this:
        (lookup index, subtable index, class index)
    """
    allKerning = {}
    allLeftClasses = {}
    allRightClasses = {}
    lookup = gpos.LookupList.Lookup[lookupIndex]
    # only handle pair positioning and extension
    if lookup.LookupType not in (2, 9):
        return
    for subtableIndex, subtable in enumerate(lookup.SubTable):
        if lookup.LookupType == 2:
            format = subtable.Format
            lookupType = subtable.LookupType
            if (lookupType, format) == (2, 1):
                kerning = _handleLookupType2Format1(subtable)
                allKerning.update(kerning)
            elif (lookupType, format) == (2, 2):
                kerning, leftClasses, rightClasses = _handleLookupType2Format2(subtable, lookupIndex, subtableIndex)
                allKerning.update(kerning)
                allLeftClasses.update(leftClasses)
                allRightClasses.update(rightClasses)
        elif lookup.LookupType == 9:
            extSubtable = subtable.ExtSubTable
            format = extSubtable.Format
            lookupType = extSubtable.LookupType
            if (lookupType, format) == (2, 1):
                kerning = _handleLookupType2Format1(extSubtable)
                allKerning.update(kerning)
            elif (lookupType, format) == (2, 2):
                kerning, leftClasses, rightClasses = _handleLookupType2Format2(extSubtable, lookupIndex, subtableIndex)
                allKerning.update(kerning)
                allLeftClasses.update(leftClasses)
                allRightClasses.update(rightClasses)
    # done
    return allKerning, allLeftClasses, allRightClasses


Instruction:
How would you implement a function in Python 3 that
handles a Lookup Type 2 Format 1 subtable.

Response:
def _handleLookupType2Format1(subtable):
    """
    Extract a kerning dictionary from a Lookup Type 2 Format 1.
    """
    kerning = {}
    coverage = subtable.Coverage.glyphs
    valueFormat1 = subtable.ValueFormat1
    pairSets = subtable.PairSet
    for index, leftGlyphName in enumerate(coverage):
        pairSet = pairSets[index]
        for pairValueRecord in pairSet.PairValueRecord:
            rightGlyphName = pairValueRecord.SecondGlyph
            if valueFormat1:
                value = pairValueRecord.Value1
            else:
                value = pairValueRecord.Value2
            if hasattr(value, "XAdvance"):
                value = value.XAdvance
                kerning[leftGlyphName, rightGlyphName] = value
    return kerning


Instruction:
Write a Python 3 script to
handle a Lookup Type 2 Format 2.

Response:
def _handleLookupType2Format2(subtable, lookupIndex, subtableIndex):
    """
    Extract kerning, left class and right class dictionaries from a Lookup Type 2 Format 2.
    """
    # extract the classes
    leftClasses = _extractFeatureClasses(lookupIndex=lookupIndex, subtableIndex=subtableIndex, classDefs=subtable.ClassDef1.classDefs, coverage=subtable.Coverage.glyphs)
    rightClasses = _extractFeatureClasses(lookupIndex=lookupIndex, subtableIndex=subtableIndex, classDefs=subtable.ClassDef2.classDefs)
    # extract the pairs
    kerning = {}
    for class1RecordIndex, class1Record in enumerate(subtable.Class1Record):
        for class2RecordIndex, class2Record in enumerate(class1Record.Class2Record):
            leftClass = (lookupIndex, subtableIndex, class1RecordIndex)
            rightClass = (lookupIndex, subtableIndex, class2RecordIndex)
            valueFormat1 = subtable.ValueFormat1
            if valueFormat1:
                value = class2Record.Value1
            else:
                value = class2Record.Value2
            if hasattr(value, "XAdvance") and value.XAdvance != 0:
                value = value.XAdvance
                kerning[leftClass, rightClass] = value
    return kerning, leftClasses, rightClasses


Instruction:
Here you have a function in Python 3, explain what it does
def _mergeKerningDictionaries(kerningDictionaries):
    # work through the dictionaries backwards since
    # this uses an update to load the kerning. this
    # will ensure that the script order is honored.
    kerning = {}
    for dictionaryGroup in reversed(kerningDictionaries):
        for dictionary in dictionaryGroup:
            kerning.update(dictionary)
    # done.
    return kerning

Response: Merge all of the kerning dictionaries found into one flat dictionary.


Instruction:
Here you have a function in Python 3, explain what it does
def _findSingleMemberGroups(classDictionaries):
    toRemove = {}
    for classDictionaryGroup in classDictionaries:
        for classDictionary in classDictionaryGroup:
            for name, members in list(classDictionary.items()):
                if len(members) == 1:
                    toRemove[name] = list(members)[0]
                    del classDictionary[name]
    return toRemove

Response: Find all classes that have only one member.


Instruction:
Write a Python 3 script to
translate group names into glyph names in pairs

Response:
def _removeSingleMemberGroupReferences(kerning, leftGroups, rightGroups):
    """
    Translate group names into glyph names in pairs
    if the group only contains one glyph.
    """
    new = {}
    for (left, right), value in kerning.items():
        left = leftGroups.get(left, left)
        right = rightGroups.get(right, right)
        new[left, right] = value
    return new


Instruction:
Given the following Python 3 function, write the documentation
def _mergeClasses(classDictionaries):
    # build a mapping of members to names
    memberTree = {}
    for classDictionaryGroup in classDictionaries:
        for classDictionary in classDictionaryGroup:
            for name, members in classDictionary.items():
                if members not in memberTree:
                    memberTree[members] = set()
                memberTree[members].add(name)
    # find members that have more than one name
    classes = {}
    rename = {}
    for members, names in memberTree.items():
        name = names.pop()
        if len(names) > 0:
            for otherName in names:
                rename[otherName] = name
        classes[name] = members
    return classes, rename

Response:
This function merges the classes that have the exact same list
    of members and flag them for removal.


Instruction:
Can you write a function in Python 3 where it
sets the final names into the groups.

Response:
def _setGroupNames(classes, classRename):
    """
    Set the final names into the groups.
    """
    groups = {}
    for groupName, glyphList in classes.items():
        groupName = classRename.get(groupName, groupName)
        # if the glyph list has only one member,
        # the glyph name will be used in the pairs.
        # no group is needed.
        if len(glyphList) == 1:
            continue
        groups[groupName] = glyphList
    return groups


Instruction:
Explain what the following Python 3 code does
def _validateClasses(classes):
    glyphToClass = {}
    for className, glyphList in classes.items():
        for glyphName in glyphList:
            if glyphName not in glyphToClass:
                glyphToClass[glyphName] = set()
            glyphToClass[glyphName].add(className)
    for glyphName, groupList in glyphToClass.items():
        if len(groupList) > 1:
            raise ExtractorError("Kerning classes are in an conflicting state.")

Response: Validate that a glyph is part of more than one class.


Instruction:
Implement a Python 3 function for
replacing the renamed pair members in the kerning with the new ones.

Response:
def _replaceRenamedPairMembers(kerning, leftRename, rightRename):
    """
    Populate the renamed pair members into the kerning.
    """
    renamedKerning = {}
    for (left, right), value in kerning.items():
        left = leftRename.get(left, left)
        right = rightRename.get(right, right)
        renamedKerning[left, right] = value
    return renamedKerning


Instruction:
Can you tell what is the following Python 3 function doing
def _renameClasses(classes, prefix):
    renameMap = {}
    for classID, glyphList in classes.items():
        if len(glyphList) == 0:
            groupName = "%s_empty_lu.%d_st.%d_cl.%d" % (prefix, classID[0], classID[1], classID[2])
        elif len(glyphList) == 1:
            groupName = list(glyphList)[0]
        else:
            glyphList = list(sorted(glyphList))
            groupName = prefix + glyphList[0]
        renameMap[classID] = groupName
    return renameMap

Response: Returns a dictionary mapping class IDs to nice strings.


Instruction:
Can you tell what is the following Python 3 function doing
def _extractFeatureClasses(lookupIndex, subtableIndex, classDefs, coverage=None):
    # gather the class members
    classDict = {}
    for glyphName, classIndex in classDefs.items():
        if classIndex not in classDict:
            classDict[classIndex] = set()
        classDict[classIndex].add(glyphName)
    # specially handle class index 0
    revisedClass0 = set()
    if coverage is not None and 0 in classDict:
        for glyphName in classDict[0]:
            if glyphName in coverage:
                revisedClass0.add(glyphName)
    elif coverage is not None and 0 not in classDict:
        revisedClass0 = set(coverage)
        for glyphList in classDict.values():
            revisedClass0 = revisedClass0 - glyphList
    classDict[0] = revisedClass0
    # flip the class map around
    classes = {}
    for classIndex, glyphList in classDict.items():
        classes[lookupIndex, subtableIndex, classIndex] = frozenset(glyphList)
    return classes

Response: Extract classes for a specific lookup in a specific subtable.


Instruction:
Can you write a function in Python 3 where it
gets the voters from the server.

Response:
def _get_voters(cls, session, owner_id, poll_id, answer_id):
        """
        https://vk.com/dev/polls.getVoters
        """
        from .users import User

        return session.fetch_items("polls.getVoters", User._get_users, count=100, owner_id=owner_id, poll_id=poll_id, answer_ids=answer_id)


Instruction:
Write a Python 3 function that can
add a module as an included module.

Response:
def add_include(self, name, module_spec):
        """Adds a module as an included module.

        :param name:
            Name under which the included module should be exposed in the
            current module.
        :param module_spec:
            ModuleSpec of the included module.
        """
        assert name, 'name is required'
        assert self.can_include

        if name in self.includes:
            raise ThriftCompilerError(
                'Cannot include module "%s" as "%s" in "%s". '
                'The name is already taken.'
                % (module_spec.name, name, self.path)
            )

        self.includes[name] = module_spec
        self.scope.add_include(name, module_spec.scope, module_spec.surface)


Instruction:
Here you have a function in Python 3, explain what it does
def link(self):
        if self.linked:
            return self

        self.linked = True

        included_modules = []

        # Link includes
        for include in self.includes.values():
            included_modules.append(include.link().surface)

        self.scope.add_surface('__includes__', tuple(included_modules))
        self.scope.add_surface('__thrift_source__', self.thrift_source)

        # Link self
        for linker in LINKERS:
            linker(self.scope).link()

        self.scope.add_surface('loads', Deserializer(self.protocol))
        self.scope.add_surface('dumps', Serializer(self.protocol))

        return self

Response: Link all the types in this module and all included modules.


Instruction:
Write a Python 3 script to
compile the given Thrift document into a Python module.

Response:
def compile(self, name, contents, path=None):
        """Compile the given Thrift document into a Python module.

        The generated module contains,

        .. py:attribute:: __services__

            A collection of generated classes for all services defined in the
            thrift file.

            .. versionchanged:: 1.0

                Renamed from ``services`` to ``__services__``.

        .. py:attribute:: __types__

            A collection of generated types for all types defined in the
            thrift file.

            .. versionchanged:: 1.0

                Renamed from ``types`` to ``__types__``.

        .. py:attribute:: __includes__

            A collection of modules included by this module.

            .. versionadded:: 1.0

        .. py:attribute:: __constants__

            A mapping of constant name to value for all constants defined in
            the thrift file.

            .. versionchanged:: 1.0

                Renamed from ``constants`` to ``__constants__``.

        .. py:attribute:: __thrift_source__

            Contents of the .thrift file from which this module was compiled.

            .. versionadded:: 1.1

        .. py:function:: dumps(obj)

            Serializes the given object using the protocol the compiler was
            instantiated with.

        .. py:function:: loads(cls, payload)

            Deserializes an object of type ``cls`` from ``payload`` using the
            protocol the compiler was instantiated with.

        .. py:function:: dumps.message(obj, seqid=0)

            Serializes the given request or response into a
            :py:class:`~thriftrw.wire.Message` using the protocol that the
            compiler was instantiated with.

            See :ref:`calling-apache-thrift`.

            .. versionadded:: 1.0

        .. py:function:: loads.message(service, payload)

            Deserializes a :py:class:`~thriftrw.wire.Message`  from
            ``payload`` using the protocol the compiler was instantiated with.
            A request or response of a method defined in the given service is
            parsed in the message body.

            See :ref:`calling-apache-thrift`.

            .. versionadded:: 1.0

        And one class each for every struct, union, exception, enum, and
        service defined in the IDL.

        Service classes have references to
        :py:class:`thriftrw.spec.ServiceFunction` objects for each method
        defined in the service.

        :param str name:
            Name of the Thrift document. This will be the name of the
            generated module.
        :param str contents:
            Thrift document to compile
        :param str path:
            Path to the Thrift file being compiled. If not specified, imports
            from within the Thrift file will be disallowed.
        :returns:
            ModuleSpec of the generated module.
        """
        assert name

        if path:
            path = os.path.abspath(path)
            if path in self._module_specs:
                return self._module_specs[path]

        module_spec = ModuleSpec(name, self.protocol, path, contents)
        if path:
            self._module_specs[path] = module_spec

        program = self.parser.parse(contents)

        header_processor = HeaderProcessor(self, module_spec, self.include_as)
        for header in program.headers:
            header.apply(header_processor)

        generator = Generator(module_spec.scope, strict=self.strict)
        for definition in program.definitions:
            generator.process(definition)

        return module_spec


Instruction:
Make a summary of the following Python 3 code
def t_LITERAL(self, t):
        r'(\"([^\\\n]|(\\.))*?\")|\'([^\\\n]|(\\.))*?\''
        s = t.value[1:-1]
        maps = {
            't': '\t',
            'r': '\r',
            'n': '\n',
            '\\': '\\',
            '\'': '\'',
            '"': '\"'
        }
        i = 0
        length = len(s)
        val = ''
        while i < length:
            if s[i] == '\\':
                i += 1
                if s[i] in maps:
                    val += maps[s[i]]
                else:
                    msg = 'Cannot escape character: %s' % s[i]
                    raise ThriftParserError(msg)
            else:
                val += s[i]
            i += 1

        t.value = val
        return t

Response: t_LITERAL is a parser for the ISO - 8601 tag.


Instruction:
Can you generate the documentation for the following Python 3 function
def t_IDENTIFIER(self, t):
        r'[a-zA-Z_](\.[a-zA-Z_0-9]|[a-zA-Z_0-9])*'

        if t.value in THRIFT_KEYWORDS:
            # Not an identifier after all.
            t.type = t.value.upper()

        return t

Response: t_IDENTIFIER is a identifier


Instruction:
Can you tell what is the following Python 3 function doing
def input(self, data):
        # input(..) doesn't reset the lineno. We have to do that manually.
        self._lexer.lineno = 1
        return self._lexer.input(data)

Response: Reset the lexer and feed in new input.


Instruction:
Can you create a Python 3 function that
creates a photo object from a JSON response.

Response:
def from_json(cls, session, photo_json):
        """
        https://vk.com/dev/objects/photo
        """
        photo = cls()
        photo.id = photo_json.get('id')
        photo.album_id = photo_json.get('album_id')
        photo.owner_id = photo_json.get('owner_id')
        photo.user_id = photo_json.get('user_id')
        photo.text = photo_json.get('text')
        photo.type = "photo"
        photo.date = photo_json.get('date')
        photo.photo_75 = photo_json.get('photo_75')
        photo.photo_130 = photo_json.get('photo_130')
        photo.photo_604 = photo_json.get('photo_604')
        photo.photo_807 = photo_json.get('photo_807')
        photo.photo_1280 = photo_json.get('photo_1280')
        photo.photo_2560 = photo_json.get('photo_2560')
        photo._session = session
        return photo


Instruction:
Write a Python 3 function for
getting all photos for a user or group.

Response:
def _get_photos(session, user_or_group_id):
        """
        https://vk.com/dev/photos.getAll
        """
        response = session.fetch_items("photos.getAll", Photo.from_json, count=200, owner_id=user_or_group_id)
        return response


Instruction:
Can you generate the documentation for the following Python 3 function
def _get_owner_cover_photo_upload_server(session, group_id, crop_x=0, crop_y=0, crop_x2=795, crop_y2=200):
        group_id = abs(group_id)
        response = session.fetch("photos.getOwnerCoverPhotoUploadServer", group_id=group_id, crop_x=crop_x, crop_y=crop_y, crop_x2=crop_x2, crop_y2=crop_y2)
        return response['upload_url']

Response: Get owner cover photo upload server.


Instruction:
Make a summary of the following Python 3 code
def _save_owner_cover_photo(session, hash, photo):
        response = session.fetch('photos.saveOwnerCoverPhoto', hash=hash, photo=photo)
        return response

Response: Save a photo to the owner cover.


Instruction:
How would you explain what the following Python 3 function does
def _get_save_wall_photo(session, photo, server, hash, user_id=None, group_id=None):
        if group_id < 0:
            group_id = abs(group_id)

        response = session.fetch("photos.saveWallPhoto", photo=photo, server=server, hash=hash, user_id=user_id, group_id=group_id)[0]
        return response['id'], response['owner_id']

Response: Get the ID and owner ID of a save wall photo.


Instruction:
Create a Python 3 function for
getting the ID and owner ID of a save messages photo.

Response:
def _get_save_messages_photo(session, photo, server, hash):
        """
        https://vk.com/dev/photos.saveMessagesPhoto
        """
        response = session.fetch("photos.saveMessagesPhoto", photo=photo, server=server, hash=hash)[0]
        return response['id'], response['owner_id']


Instruction:
Given the following Python 3 function, write the documentation
def get_city(self):
        response = self._session.fetch("users.get", user_ids=self.id, fields="city")[0]
        if response.get('city'):
            return City.from_json(self._session, response.get('city'))

Response: Returns the city of the user if it exists else None.


Instruction:
Can you generate the documentation for the following Python 3 function
def get_country(self):
        response = self._session.fetch("users.get", user_ids=self.id, fields="country")[0]
        if response.get('country'):
            return Country.from_json(self._session, response.get('country'))

Response: Get the country of the user.


Instruction:
Make a summary of the following Python 3 code
def get_followers(self):
        response = self._session.fetch_items("users.getFollowers", self.from_json, self._session,  count=1000, user_id=self.id, fields=self.USER_FIELDS)
        return response

Response: Get a list of followers for this user.


Instruction:
Can you implement a function in Python 3 that
gets a User object from the session.

Response:
def _get_user(session, slug_or_user_id):
        """
        :param slug_or_user_id: str or int
        :return: User
        """
        user_json_items = session.fetch('users.get', user_ids=slug_or_user_id, fields=User.USER_FIELDS)
        return User.from_json(session, user_json_items[0])


Instruction:
Can you implement a function in Python 3 that
gets the data from the

Response:
def get_data():
    """
    Currently pretends to talk to an instrument and get back the magnitud
    and phase of the measurement.
    """

    # pretend we're measuring a noisy resonance at zero
    y = 1.0 / (1.0 + 1j*(n_x.get_value()-0.002)*1000) + _n.random.rand()*0.1

    # and that it takes time to do so
    _t.sleep(0.1)

    # return mag phase
    return abs(y), _n.angle(y, True)


Instruction:
Implement a function in Python 3 to
list the keys and values.

Response:
def List(self):
        """
        Lists the keys and values.
        """
        print()
        for key in list(self.keys()):
            print(key,'=',self[key])
        print()


Instruction:
Write a Python 3 script to
set the key - value pair and dumps to the preferences file.

Response:
def Set(self, key, value):
        """
        Sets the key-value pair and dumps to the preferences file.
        """
        if not value == None: self.prefs[key] = value
        else:                 self.prefs.pop(key)

        self.Dump()


Instruction:
How would you implement a function in Python 3 that
creates a directory of the specified path in the spinmob directory.

Response:
def MakeDir(self, path="temp"):
        """
        Creates a directory of the specified path in the .spinmob directory.
        """
        full_path = _os.path.join(self.path_home, path)

        # only make it if it doesn't exist!
        if not _os.path.exists(full_path): _os.makedirs(full_path)


Instruction:
Write a Python 3 function for
listing the directory of the user s log files.

Response:
def ListDir(self, path="temp"):
        """
        Returns a list of files in the specified path (directory), or an
        empty list if the directory doesn't exist.
        """
        full_path = _os.path.join(self.path_home, path)

        # only if the path exists!
        if _os.path.exists(full_path) and _os.path.isdir(full_path):
            return _os.listdir(full_path)
        else:
            return []


Instruction:
How would you code a function in Python 3 to
convert list to string

Response:
def _convert_list2str(self, fields):
        """
        :param fields: ('bdate', 'domain')
        :return: 'bdate,domain'
        """
        if isinstance(fields, tuple) or isinstance(fields, list):
            return ','.join(fields)
        return fields


Instruction:
Here you have a function in Python 3, explain what it does
def p_start(self, p):
        '''start : header definition'''
        p[0] = ast.Program(headers=p[1], definitions=p[2])

Response: start : header definition


Instruction:
Given the following Python 3 function, write the documentation
def p_include(self, p):
        '''include : INCLUDE IDENTIFIER LITERAL
                   | INCLUDE LITERAL'''
        if len(p) == 4:
            p[0] = ast.Include(name=p[2], path=p[3], lineno=p.lineno(1))
        else:
            p[0] = ast.Include(name=None, path=p[2], lineno=p.lineno(1))

Response:
include : INCLUDE IDENTIFIER LITERAL
                   | INCLUDE LITERAL


Instruction:
Here you have a function in Python 3, explain what it does
def p_namespace(self, p):
        '''namespace : NAMESPACE namespace_scope IDENTIFIER'''
        p[0] = ast.Namespace(scope=p[2], name=p[3], lineno=p.lineno(1))

Response: parse a NAMESPACE node


Instruction:
Make a summary of the following Python 3 code
def p_const(self, p):
        '''const : CONST field_type IDENTIFIER '=' const_value
                 | CONST field_type IDENTIFIER '=' const_value sep'''
        p[0] = ast.Const(
            name=p[3],
            value_type=p[2],
            value=p[5],
            lineno=p.lineno(3),
        )

Response: parse a CONST expression


Instruction:
Can you generate the documentation for the following Python 3 function
def p_const_value_primitive(self, p):
        '''const_value_primitive : INTCONSTANT
                                 | DUBCONSTANT
                                 | LITERAL
                                 | const_bool'''
        p[0] = ast.ConstPrimitiveValue(p[1], lineno=p.lineno(1))

Response: Parse the CONST_VALUE_PRIMITIVE instruction.


Instruction:
Can you tell what is the following Python 3 function doing
def p_const_list(self, p):
        '''const_list : '[' const_list_seq ']' '''
        p[0] = ast.ConstList(list(p[2]), p.lineno(1))

Response: const_list : '[' const_list_seq ']'


Instruction:
How would you implement a function in Python 3 that
parses a CONSTANT_REF node

Response:
def p_const_ref(self, p):
        '''const_ref : IDENTIFIER'''
        p[0] = ast.ConstReference(p[1], lineno=p.lineno(1))


Instruction:
Implement a Python 3 function for
parsing TYPEDEF field_type IDENTIFIER annotations

Response:
def p_typedef(self, p):
        '''typedef : TYPEDEF field_type IDENTIFIER annotations'''
        p[0] = ast.Typedef(
            name=p[3], target_type=p[2], annotations=p[4], lineno=p.lineno(3)
        )


Instruction:
Explain what the following Python 3 code does
def p_enum(self, p):  # noqa
        '''enum : ENUM IDENTIFIER '{' enum_seq '}' annotations'''
        p[0] = ast.Enum(
            name=p[2], items=p[4], annotations=p[6], lineno=p.lineno(2)
        )

Response: Parse an enum statement.


Instruction:
Can you generate the documentation for the following Python 3 function
def p_enum_item(self, p):
        '''enum_item : IDENTIFIER '=' INTCONSTANT annotations
                     | IDENTIFIER annotations'''
        if len(p) == 5:
            p[0] = ast.EnumItem(
                name=p[1], value=p[3], annotations=p[4], lineno=p.lineno(1)
            )
        else:
            p[0] = ast.EnumItem(
                name=p[1], value=None, annotations=p[2], lineno=p.lineno(1)
            )

Response: Parse an enum item.


Instruction:
How would you explain what the following Python 3 function does
def p_struct(self, p):
        '''struct : STRUCT IDENTIFIER '{' field_seq '}' annotations'''
        p[0] = ast.Struct(
            name=p[2], fields=p[4], annotations=p[6], lineno=p.lineno(2)
        )

Response: parse a STRUCT object


Instruction:
Given the following Python 3 function, write the documentation
def p_exception(self, p):
        '''exception : EXCEPTION IDENTIFIER '{' field_seq '}' annotations'''
        p[0] = ast.Exc(
            name=p[2], fields=p[4], annotations=p[6], lineno=p.lineno(2)
        )

Response: parse an exception expression


Instruction:
Can you tell what is the following Python 3 function doing
def p_service(self, p):
        '''service : SERVICE IDENTIFIER '{' function_seq '}' annotations
                   | SERVICE IDENTIFIER EXTENDS IDENTIFIER \
                     '{' function_seq '}' annotations
        '''

        if len(p) == 7:
            p[0] = ast.Service(
                name=p[2],
                functions=p[4],
                parent=None,
                annotations=p[6],
                lineno=p.lineno(2),
            )
        else:
            p[0] = ast.Service(
                name=p[2],
                functions=p[6],
                parent=ast.ServiceReference(p[4], p.lineno(4)),
                annotations=p[8],
                lineno=p.lineno(2),
            )

Response: parse a service statement


Instruction:
How would you code a function in Python 3 to
parse a function expression

Response:
def p_function(self, p):
        '''function : oneway function_type IDENTIFIER '(' field_seq ')' \
                      throws annotations '''
        p[0] = ast.Function(
            name=p[3],
            parameters=p[5],
            return_type=p[2],
            exceptions=p[7],
            oneway=p[1],
            annotations=p[8],
            lineno=p.lineno(3),
        )


Instruction:
How would you implement a function in Python 3 that
parses a field declaration

Response:
def p_field(self, p):
        '''field : field_id field_req field_type IDENTIFIER annotations
                 | field_id field_req field_type IDENTIFIER '=' const_value \
                   annotations'''

        if len(p) == 8:
            default = p[6]
            annotations = p[7]
        else:
            default = None
            annotations = p[5]

        p[0] = ast.Field(
            id=p[1],
            name=p[4],
            field_type=p[3],
            requiredness=p[2],
            default=default,
            annotations=annotations,
            lineno=p.lineno(4),
        )


Instruction:
Can you implement a function in Python 3 that
parses the field ID.

Response:
def p_field_id(self, p):
        '''field_id : INTCONSTANT ':'
                    | '''
        if len(p) == 3:

            if p[1] == 0:
                # Prevent users from ever using field ID 0. It's reserved for
                # internal use only.
                raise ThriftParserError(
                    'Line %d: Field ID 0 is reserved for internal use.'
                    % p.lineno(1)
                )

            p[0] = p[1]
        else:
            p[0] = None


Instruction:
Can you create a Python 3 function that
parses a ref_type expression

Response:
def p_ref_type(self, p):
        '''ref_type : IDENTIFIER'''
        p[0] = ast.DefinedType(p[1], lineno=p.lineno(1))


Instruction:
Can you write a function in Python 3 where it
parses the base type of the object.

Response:
def p_base_type(self, p):  # noqa
        '''base_type : BOOL annotations
                     | BYTE annotations
                     | I8 annotations
                     | I16 annotations
                     | I32 annotations
                     | I64 annotations
                     | DOUBLE annotations
                     | STRING annotations
                     | BINARY annotations'''

        name = p[1]
        if name == 'i8':
            name = 'byte'

        p[0] = ast.PrimitiveType(name, p[2])


Instruction:
Here you have a function in Python 3, explain what it does
def p_map_type(self, p):
        '''map_type : MAP '<' field_type ',' field_type '>' annotations'''
        p[0] = ast.MapType(key_type=p[3], value_type=p[5], annotations=p[7])

Response: parse a MAP type


Instruction:
Given the following Python 3 function, write the documentation
def p_list_type(self, p):
        '''list_type : LIST '<' field_type '>' annotations'''
        p[0] = ast.ListType(value_type=p[3], annotations=p[5])

Response: parse LIST < field_type > annotations


Instruction:
How would you code a function in Python 3 to
set < field_type > annotations

Response:
def p_set_type(self, p):
        '''set_type : SET '<' field_type '>' annotations'''
        p[0] = ast.SetType(value_type=p[3], annotations=p[5])


Instruction:
Given the following Python 3 function, write the documentation
def _parse_seq(self, p):
        # This basically says:
        #
        # - When you reach the end of the list, construct and return an empty
        #   deque.
        # - Otherwise, prepend to start of what you got from the parser.
        #
        # So this ends up constructing an in-order list.
        if len(p) == 4:
            p[3].appendleft(p[1])
            p[0] = p[3]
        elif len(p) == 3:
            p[2].appendleft(p[1])
            p[0] = p[2]
        elif len(p) == 1:
            p[0] = deque()
        else:
            raise ThriftParserError(
                'Wrong number of tokens received for expression at line %d'
                % p.lineno(1)
            )

Response: Helper function to parse a sequence rule.


Instruction:
Create a Python 3 function to
parse the given input.

Response:
def parse(self, input, **kwargs):
        """Parse the given input.

        :param input:
            String containing the text to be parsed.
        :raises thriftrw.errors.ThriftParserError:
            For parsing errors.
        """
        return self._parser.parse(input, lexer=self._lexer, **kwargs)


Instruction:
Implement a function in Python 3 to
get comments from the VK.

Response:
def _get_comments(session, group_or_user_id, wall_id):
        """
        https://vk.com/dev/wall.getComments
        """
        return session.fetch_items("wall.getComments", Comment.from_json, count=100, owner_id=group_or_user_id, post_id=wall_id, need_likes=1)


Instruction:
Can you generate a brief explanation for the following Python 3 code
def _get_comments_count(session, group_or_user_id, wall_id):
        response = session.fetch("wall.getComments", count=100, owner_id=group_or_user_id, post_id=wall_id)
        return response.get('count')

Response: Get the number of comments for a given user in a given group.


Instruction:
How would you explain what the following Python 3 function does
def get_likes(self):
        from .users import User
        return self._session.fetch_items('likes.getList', User._get_user, count=100, type='post', owner_id=self.from_id, item_id=self.id)

Response: Get a list of likes.


Instruction:
Can you write a function in Python 3 where it
gets the number of likes for this item.

Response:
def get_likes_count(self):
        """
        https://vk.com/dev/likes.getList
        """
        response = self._session.fetch('likes.getList', count=1, type='post', owner_id=self.from_id, item_id=self.id)
        likes_count = response.get('count')
        return likes_count


Instruction:
Can you create a Python 3 function that
gets all reposts for this post.

Response:
def get_reposts(self):
        """
        https://vk.com/dev/wall.getReposts
        """
        return self._session.fetch_items('wall.getReposts', self.from_json, count=1000, owner_id=self.from_id, post_id=self.id)


Instruction:
Given the following Python 3 function, write the documentation
def _wall_post(session, owner_id, message=None, attachments=None, from_group=True):
        response = session.fetch("wall.post", owner_id=owner_id, message=message, attachments=attachments, from_group=from_group)
        return response

Response: Post a new entry to the Wall.


Instruction:
Implement a function in Python 3 to
get the number of friends for a user

Response:
def _get_friends_count(session, user_id):
        """
        https://vk.com/dev/friends.get
        """
        response = session.fetch('friends.get', user_id=user_id, count=1)
        return response["count"]


Instruction:
How would you explain what the following Python 3 function does
def acquire_fake_data(number_of_points=1000):
    # time array
    t = _n.linspace(0,10,number_of_points)

    return(t, [_n.cos(t)*(1.0+0.2*_n.random.random(number_of_points)),
               _n.sin(t      +0.5*_n.random.random(number_of_points))])

Response:
This function generates some fake data and returns two channels of data in the form of
    time_array [ channel1 channel2... ]


Instruction:
Make a summary of the following Python 3 code
def load(path=None, first_data_line='auto', filters='*.*', text='Select a file, FACEHEAD.', default_directory='default_directory', quiet=True, header_only=False, transpose=False, **kwargs):
    d = databox(**kwargs)
    d.load_file(path=path, first_data_line=first_data_line,
                filters=filters, text=text, default_directory=default_directory,
                header_only=header_only)

    if not quiet: print("\nloaded", d.path, "\n")

    if transpose: return d.transpose()
    return d

Response: Load a data file into the databox data class.


Instruction:
Can you generate the documentation for the following Python 3 function
def load_multiple(paths=None, first_data_line="auto", filters="*.*", text="Select some files, FACEHEAD.", default_directory="default_directory", quiet=True, header_only=False, transpose=False, **kwargs):
    if paths == None: paths = _s.dialogs.load_multiple(filters, text, default_directory)
    if paths is None : return

    datas = []
    for path in paths:
        if _os.path.isfile(path): datas.append(load(path=path, first_data_line=first_data_line,
                filters=filters, text=text, default_directory=default_directory,
                header_only=header_only, transpose=transpose, **kwargs))

    return datas

Response: Load a list of data files into a list of databox data objects.


Instruction:
Make a summary of the following Python 3 code
def more_info(self):
        print("\nDatabox Instance", self.path)
        print("\nHeader")
        for h in self.hkeys: print("  "+h+":", self.h(h))
        s = "\nColumns ("+str(len(self.ckeys))+"): "
        for c in self.ckeys: s = s+c+", "
        print(s[:-2])

Response: Prints out more information about the databox.


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

        # start with numpy
        globbies = dict(_n.__dict__)
        globbies.update(_special.__dict__)

        # update with required stuff
        globbies.update({'h':self.h, 'c':self.c, 'd':self, 'self':self})

        # update with user stuff
        globbies.update(self.extra_globals)

        return globbies

Response: Returns the globals needed for eval statements.


Instruction:
Write a Python 3 script to
load a file and store the header info in self. headers and self. columns.

Response:
def load_file(self, path=None, first_data_line='auto', filters='*.*', text='Select a file, FACEPANTS.', default_directory=None, header_only=False, quiet=False):
        """
        This will clear the databox, load a file, storing the header info in
        self.headers, and the data in self.columns

        If first_data_line="auto", then the first data line is assumed to be
        the first line where all the elements are numbers.

        If you specify a first_data_line (index, starting at 0), the columns
        need not be numbers. Everything above will be considered header
        information and below will be data columns.

        In both cases, the line used to label the columns will always be the
        last header line with the same (or more) number of elements as the
        first data line.

        Parameters
        ----------
        path=None
            Path to the file. Using None will bring up a dialog.
        filters='*.*'
            Filter for the file dialog (if path isn't specified)
        text='Select a file, FACEPANTS.'
            Prompt on file dialog
        default_directory=None
            Which spinmob.settings key to use for the dialog's default
            directory. Will create one if it doesn't already exist.
        header_only=False
            Only load the header
        quiet=False
            Don't print anything while loading.
        """

        # Set the default directory
        if default_directory is None: default_directory = self.directory

        # Ask user for a file to open
        if path == None:
            path = _s.dialogs.load(filters=filters,
                                        default_directory=self.directory,
                                        text=text)
        self.path = path

        if path is None:
            return None

        # make sure the file exists!
        if not _os.path.exists(path):
            if not quiet: print("ERROR: "+repr(path)+" does not exist.")
            return None

        # clear all the existing data
        self.clear()

        # First check if the file is SPINMOB_BINARY format!
        f = open(path, 'rb')

        # If this file is in SPINMOB_BINARY mode!
        if f.read(14).decode('utf-8') == 'SPINMOB_BINARY':

            # Next character is the delimiter
            self.delimiter = f.read(1).decode('utf-8')

            # Find the newline and get the data type
            s = ' '
            while not s[-1] == '\n': s = s+f.read(1).decode('utf-8')

            # Rest of the line is the binary dtype
            self.h(SPINMOB_BINARY = s.strip())

            # Now manually assemble the header lines to use in the analysis
            # below. If I try readline() on the binary file, it will crash.
            lines = ['\n']

            # The end of the header is specified by 'SPINMOB_BINARY' on its own line.
            while not lines[-1] == 'SPINMOB_BINARY':

                # Get the next line, one character at a time.
                s = ' '
                while not s[-1] == '\n': s = s+f.read(1).decode('utf-8')

                # Okay we have it
                lines.append(s.strip())

            # Pop that last line, which should be 'SPINMOB_BINARY'
            lines.pop(-1)

            # We've reached the end of the header.

        # Close the binary read.
        f.close()

        # If we're not in binary mode, we can read all the lines and find
        # the delimiter as usual. (In binary mode, the delimiter is specified)
        if not 'SPINMOB_BINARY' in self.hkeys:

            # For non-binary files, we always read all the lines.
            f = open(path, 'r')
            lines = f.readlines()
            f.close()

            # Determine the delimiter
            if self.delimiter is None:

                # loop from the end of the file until we get something other than white space
                for n in range(len(lines)):

                    # strip away the white space
                    s = lines[-n-1].strip()

                    # if this line has any content
                    if len(s) > 0:

                        # try the different delimiter schemes until we find one
                        # that produces a number. Otherwise it's ambiguous.
                        if   _s.fun.is_a_number(s.split(None)[0]): self.delimiter = None
                        elif _s.fun.is_a_number(s.split(',') [0]): self.delimiter = ','
                        elif _s.fun.is_a_number(s.split(';') [0]): self.delimiter = ';'

                        # quit the loop!
                        break

        # Done reading lines and auto-determining delimiter.

        ##### Pares the header from lines
        self.header_lines = []

        for n in range(len(lines)):

            # split the line by the delimiter
            s = lines[n].strip().split(self.delimiter)

            # remove a trailing whitespace entry if it exists.
            if len(s) and s[-1].strip() == '': s.pop(-1)

            # first check and see if this is a data line (all elements are numbers)
            if first_data_line == "auto" and _s.fun.elements_are_numbers(s):

                # we've reached the first data line
                first_data_line = n

                # quit the header loop
                break;

            ### after that check, we know it's a header line

            # save the lines for the avid user.
            self.header_lines.append(lines[n].strip())

            # store the hkey and the rest of it
            if len(s):
                hkey      = s[0]
                if self.delimiter is None: remainder = ' '.join(s[1:])
                else:                      remainder = self.delimiter.join(s[1:])

                # first thing to try is simply evaluating the remaining string
                try: self.insert_header(hkey, eval(remainder, self._globals()))

                # otherwise store the string
                except: self.insert_header(hkey, remainder)

        # now we have a valid set of column ckeys one way or another, and we know first_data_line.
        if header_only: return self

        # Deal with the binary mode
        if 'SPINMOB_BINARY' in self.hkeys:

            # Read the binary file
            f = open(path, 'rb')
            s = f.read()
            f.close()

            # Get the delimiter for easier coding
            delimiter = self.delimiter.encode('utf-8')

            # Get the binary mode, e.g., 'float32'
            binary = self.h('SPINMOB_BINARY')

            # Number of bytes per element
            size = eval('_n.'+binary+'().itemsize', dict(_n=_n))

            # Location of first ckey
            start = s.find(b'SPINMOB_BINARY',14) + 15

            # Continue until we reach the last character.
            while not start >= len(s):

                # Get the location of the end of the ckey
                stop  = s.find(delimiter, start)

                # Woa, Nelly! We're at the end of the file.
                if stop == -1: break
                ckey  = s[start:stop].decode('utf-8').strip()

                # Get the array length
                start = stop+1
                stop  = s.find(b'\n', start)
                length = int(s[start:stop].strip())

                # Get the data!
                start = stop+1
                stop  = start+size*length
                self[ckey] = _n.fromstring(s[start:stop], binary)

                # Go to next ckey
                start = stop+1

        # Otherwise we have a text file to load.
        else:
            # Make sure first_data_line isn't still 'auto'
            # which happens if there's no data, or if it's a binary file
            if first_data_line == "auto" and not 'SPINMOB_BINARY' in self.hkeys:
                if not quiet: print("\ndatabox.load_file(): Could not find a line of pure data! Perhaps check the delimiter?")
                return self

            ##### at this point we've found the first_data_line,

            # look for the ckeys

            # special case: no header
            if first_data_line == 0: ckeys = []

            # start by assuming it's the previous line
            else: ckeys = lines[first_data_line-1].strip().split(self.delimiter)

            # count the number of actual data columns for comparison
            column_count = len(lines[first_data_line].strip().split(self.delimiter))

            # check to see if ckeys is equal in length to the
            # number of data columns. If it isn't, it's a false ckeys line
            if len(ckeys) >= column_count:
                # it is close enough
                # if we have too many column keys, mention it
                while len(ckeys) > column_count:
                    extra = ckeys.pop(-1)
                    if not quiet: print("Extra ckey: "+extra)

            else:
                # it is an invalid ckeys line. Generate our own!
                ckeys = []
                for m in range(0, column_count): ckeys.append("c"+str(m))

            # last step with ckeys: make sure they're all different!
            self.ckeys = []
            while len(ckeys):

                # remove the key
                ckey = ckeys.pop(0)

                # if there is a duplicate
                if (ckey in ckeys) or (ckey in self.ckeys):
                    # increase the label index until it's unique
                    n=0
                    while (ckey+"_"+str(n) in ckeys) or (ckey+"_"+str(n) in self.ckeys): n+=1
                    ckey = ckey+"_"+str(n)
                self.ckeys.append(ckey)

            # initialize the columns arrays
            # I did benchmarks and there's not much improvement by using numpy-arrays here.
            for label in self.ckeys: self.columns[label] = []

            # Python 2 format
            #if _sys.version_info[0] == 2:
            try:
                def fix(x): return str(x.replace('i','j'))

                # loop over the remaining data lines, converting to numbers
                z = _n.genfromtxt((fix(x) for x in lines[first_data_line:]),
                                  delimiter=self.delimiter,
                                  dtype=_n.complex)

            # Python 3 format
            except:
                def fix(x): return bytearray(x.replace('i','j'), encoding='utf-8')

                # loop over the remaining data lines, converting to numbers
                z = _n.genfromtxt((fix(x) for x in lines[first_data_line:]),
                                  delimiter=self.delimiter,
                                  dtype=_n.complex)

            # genfromtxt returns a 1D array if there is only one data line.
            # highly confusing behavior, numpy!
            if len(_n.shape(z)) == 1:
                # check to make sure the data file contains only 1 column of data
                rows_of_data = len(lines) - first_data_line
                if rows_of_data == 1: z = _n.array([z])
                else: z = _n.array(z)

            # fix for different behavior of genfromtxt on single columns
            if len(z.shape) == 2: z = z.transpose()
            else:                 z = [z]

            # Add all the columns
            for n in range(len(self.ckeys)):

                # if any of the imaginary components are non-zero, use complex
                if _n.any(_n.imag(z[n])): self[n] = z[n]
                else:                     self[n] = _n.real(z[n])

        # Done with loading in the columns of data

        # now, as an added bonus, rename some of the obnoxious headers
        for k in self.obnoxious_ckeys:
            if k in self.columns:
                self.columns[self.obnoxious_ckeys[k]] = self.columns[k]

        return self


Instruction:
Can you generate a brief explanation for the following Python 3 code
def save_file(self, path=None, filters='*.dat', force_extension=None, force_overwrite=False, header_only=False, delimiter='use current', binary=None):

        # Make sure there isn't a problem later with no-column databoxes
        if len(self)==0: header_only=True

        # This is the final path. We now write to a temporary file in the user
        # directory, then move it to the destination. This (hopefully) fixes
        # problems with sync programs.
        if path in [None]: path = _s.dialogs.save(filters, default_directory=self.directory)
        if path in ["", None]:
            print("Aborted.")
            return False

        # Force the extension (we do this here redundantly, because the user may have also
        # specified a path explicitly)
        if  not force_extension == None:

            # In case the user put "*.txt" instead of just "txt"
            force_extension = force_extension.replace('*','').replace('.','')

            # If the file doesn't end with the extension, add it
            if not _os.path.splitext(path)[-1][1:] == force_extension:
                path = path + '.' + force_extension

        # Save the path for future reference
        self.path=path

        # if the path exists, make a backup
        if _os.path.exists(path) and not force_overwrite:
            _os.rename(path,path+".backup")

        # get the delimiter
        if delimiter == "use current":
            if self.delimiter is None: delimiter = "\t"
            else:                      delimiter = self.delimiter

        # figure out the temporary path
        temporary_path = _os.path.join(_s.settings.path_home, "temp-"+str(int(1e3*_time.time()))+'-'+str(int(1e9*_n.random.rand(1))))

        # open the temporary file
        f = open(temporary_path, 'w')

        # Override any existing binary if we're supposed to
        if binary in [False, 'text', 'Text', 'ASCII', 'csv', 'CSV']:
            self.pop_header('SPINMOB_BINARY', True)
            binary = None

        # If the binary flag is any kind of binary format, add the key
        if not binary in [None, False, 'text', 'Text', 'ASCII', 'csv', 'CSV']:
            self.h(SPINMOB_BINARY=binary)

        # Now use the header element to determine the binary mode
        if 'SPINMOB_BINARY' in self.hkeys:

            # Get the binary mode (we'll use this later)
            binary = self.pop_header('SPINMOB_BINARY')

            # If it's "True", default to float32
            if binary in ['True', True, 1]: binary = 'float32'

            # Write the special first key.
            f.write('SPINMOB_BINARY' + delimiter + binary + '\n')

        # Write the usual header
        for k in self.hkeys: f.write(k + delimiter + repr(self.headers[k]) + "\n")
        f.write('\n')

        # if we're not just supposed to write the header
        if not header_only:

            # Normal ascii saving mode.
            if binary in [None, 'None', False, 'False']:

                # write the ckeys
                elements = []
                for ckey in self.ckeys:
                    elements.append(str(ckey).replace(delimiter,'_'))
                f.write(delimiter.join(elements) + "\n")

                # now loop over the data
                for n in range(0, len(self[0])):
                    # loop over each column
                    elements = []
                    for m in range(0, len(self.ckeys)):
                        # write the data if there is any, otherwise, placeholder
                        if n < len(self[m]):
                            elements.append(str(self[m][n]))
                        else:
                            elements.append('_')
                    f.write(delimiter.join(elements) + "\n")

            # Binary mode
            else:
                # Announce that we're done with the header. It's binary time
                f.write('SPINMOB_BINARY\n')

                # Loop over the ckeys
                for n in range(len(self.ckeys)):

                    # Get the binary data string
                    data_string = _n.array(self[n]).astype(binary).tostring()

                    # Write the column
                    #  ckey + delimiter + count + \n + datastring + \n
                    f.write(str(self.ckeys[n]).replace(delimiter,'_')
                           + delimiter + str(len(self[n])) + '\n')
                    f.close()
                    f = open(temporary_path, 'ab')
                    f.write(data_string)
                    f.close()
                    f = open(temporary_path, 'a')
                    f.write('\n')

        f.close()

        # now move it
        _shutil.move(temporary_path, path)

        return self

Response: Save the data to an ascii file.


Instruction:
Create a Python 3 function to
return then'th data point from all columns.

Response:
def get_data_point(self, n):
        """
        Returns the n'th data point (starting at 0) from all columns.

        Parameters
        ----------
        n
            Index of data point to return.
        """
        # loop over the columns and pop the data
        point = []
        for k in self.ckeys: point.append(self[k][n])
        return point


Instruction:
Write a Python 3 function for
inserting a data point at index.

Response:
def insert_data_point(self, new_data, index=None):
        """
        Inserts a data point at index n.

        Parameters
        ----------
        new_data
            A list or array of new data points, one for each column.
        index
            Where to insert the point(s) in each column. None => append.
        """

        if not len(new_data) == len(self.columns) and not len(self.columns)==0:
            print("ERROR: new_data must have as many elements as there are columns.")
            return

        # otherwise, we just auto-add this data point as new columns
        elif len(self.columns)==0:
            for i in range(len(new_data)): self[i] = [new_data[i]]

        # otherwise it matches length so just insert it.
        else:
            for i in range(len(new_data)):

                # get the array and turn it into a list
                data = list(self[i])

                # append or insert
                if index is None: data.append(       new_data[i])
                else:             data.insert(index, new_data[i])

                # reconvert to an array
                self[i] = _n.array(data)

        return self


Instruction:
Can you implement a function in Python 3 that
executes a script and returns the result.

Response:
def execute_script(self, script, g=None):
        """
        Runs a script, returning the result.

        Parameters
        ----------
        script
            String script to be evaluated (see below).
        g=None
            Optional dictionary of additional globals for the script evaluation.
            These will automatically be inserted into self.extra_globals.

        Usage
        -----
        Scripts are of the form:

        "3.0 + x/y - d[0] where x=3.0*c('my_column')+h('setting'); y=d[1]"

        By default, "d" refers to the databox object itself, giving access to
        everything and enabling complete control over the universe. Meanwhile,
        c() and h() give quick reference to d.c() and d.h() to get columns and
        header lines. Additionally, these scripts can see all of the numpy
        functions like sin, cos, sqrt, etc.

        If you would like access to additional globals in a script,
        there are a few options in addition to specifying the g parametres.
        You can set self.extra_globals to the appropriate globals dictionary
        or add globals using self.insert_global(). Setting g=globals() will
        automatically insert all of your current globals into this databox
        instance.

        There are a few shorthand scripts available as well. You can simply type
        a column name such as 'my_column' or a column number like 2. However, I
        only added this functionality as a shortcut, and something like
        "2.0*a where a=my_column" will not work unless 'my_column is otherwise
        defined. I figure since you're already writing a complicated script in
        that case, you don't want to accidentally shortcut your way into using
        a column instead of a constant! Use "2.0*a where a=c('my_column')"
        instead.
        """

        # add any extra user-supplied global variables for the eventual eval() call.
        if not g==None: self.extra_globals.update(g)

        # If the script is not a list of scripts, return the script value.
        # This is the termination of a recursive call.
        if not _s.fun.is_iterable(script):

            # special case
            if script is None: return None

            # get the expression and variables dictionary
            [expression, v] = self._parse_script(script)

            # if there was a problem parsing the script
            if v is None:
                print("ERROR: Could not parse '"+script+"'")
                return None

            # get all the numpy stuff too
            g = self._globals()
            g.update(v)

            # otherwise, evaluate the script using python's eval command
            return eval(expression, g)

        # Otherwise, this is a list of (lists of) scripts. Make the recursive call.
        output = []
        for s in script: output.append(self.execute_script(s))

        return output


Instruction:
Can you tell what is the following Python 3 function doing
def _parse_script(self, script, n=0):

        if n > 1000:
            print("This script ran recursively 1000 times!")
            a = input("<enter> or (q)uit: ")
            if a.strip().lower() in ['q', 'quit']:
                script = None

        if script is None: return [None, None]

        # check if the script is simply an integer
        if type(script) in [int,int]:
            if script<0: script = script+len(self.ckeys)
            return ["___"+str(script), {"___"+str(script):self[script]}]

        # the scripts would like to use calls like "h('this')/3.0*c('that')",
        # so to make eval() work we should add these functions to a local list

        # first split up by "where"
        split_script = script.split(" where ")

        ########################################
        # Scripts without a "where" statement:
        ########################################

        # if it's a simple script, like "column0" or "c(3)/2.0"
        if len(split_script) is 1:
            if self.debug: print("script of length 1")

            # try to evaluate the script

            # first try to evaluate it as a simple column label
            if n==0 and script in self.ckeys:
                # only try this on the zero'th attempt
                # if this is a recursive call, there can be ambiguities if the
                # column names are number strings
                return ['___', {'___':self[script]}]

            # Otherwise, evaluate it.
            try:
                b = eval(script, self._globals())
                return ['___', {'___':b}]
            except:
                print()
                print("ERROR: Could not evaluate '"+str(script)+"'")
                return [None, None]

        #######################################
        # Full-on fancy scripts
        #######################################

        # otherwise it's a complicated script like "c(1)-a/2 where a=h('this')"

        # tidy up the expression
        expression = split_script[0].strip()

        # now split the variables list up by ,
        varsplit = split_script[1].split(';')

        # loop over the entries in the list of variables, storing the results
        # of evaluation in the "stuff" dictionary
        stuff = dict()
        for var in varsplit:

            # split each entry by the "=" sign
            s = var.split("=")
            if len(s) == 1:
                print(s, "has no '=' in it")
                return [None, None]

            # tidy up into "variable" and "column label"
            v = s[0].strip()
            c = s[1].strip()

            # now try to evaluate c, given our current globbies

            # recursively call this sub-script. At the end of all this mess
            # we want the final return value to be the first expression
            # and a full dictionary of variables to fill it
            [x,y] = self._parse_script(c, n+1)

            # if it's not working, just quit out.
            if y is None: return [None, None]

            stuff[v] = y[x]

        # at this point we've found or generated the list
        return [expression, stuff]

Response: This function parses a script and returns a list of the appropriate column names.


Instruction:
Write a Python 3 script to
copy the headers from the source databox to this databoxes

Response:
def copy_headers(self, source_databox):
        """
        Loops over the hkeys of the source_databox, updating this databoxes' header.
        """
        for k in source_databox.hkeys: self.insert_header(k, source_databox.h(k))

        return self


Instruction:
Given the following Python 3 function, write the documentation
def copy_columns(self, source_databox):
        for k in source_databox.ckeys: self.insert_column(source_databox[k], k)

        return self

Response: Copy the columns from the source databox to this databoxes


Instruction:
Make a summary of the following Python 3 code
def copy_all(self, source_databox):
        self.copy_headers(source_databox)
        self.copy_columns(source_databox)
        return self

Response: Copies the header and columns from source_databox to this databox.


Instruction:
Given the following Python 3 function, write the documentation
def insert_globals(self, *args, **kwargs):
        for a in args: kwargs[a.__name__] = a
        self.extra_globals.update(kwargs)

Response: Adds or overwrites the supplied object in the self. extra_globals dictionary.


Instruction:
Can you tell what is the following Python 3 function doing
def insert_header(self, hkey, value, index=None):
        #if hkey is '': return

        # if it's an integer, use the hkey from the list
        if type(hkey) in [int, int]: hkey = self.hkeys[hkey]

        # set the data
        self.headers[str(hkey)] = value
        if not hkey in self.hkeys:
            if index is None: self.hkeys.append(str(hkey))
            else:             self.hkeys.insert(index, str(hkey))
        return self

Response: This will insert a value into the header and hkeys.


Instruction:
Here you have a function in Python 3, explain what it does
def is_same_as(self, other_databox, headers=True, columns=True, header_order=True, column_order=True, ckeys=True):
        d = other_databox

        if not hasattr(other_databox, '_is_spinmob_databox'): return False

        # Proceed by testing things one at a time, returning false if one fails
        if headers:

            # Same number of elements
            if not len(self.hkeys) == len(d.hkeys): return False

            # Elements
            if header_order and not self.hkeys == d.hkeys: return False

            # Each value
            for k in self.hkeys:
                # Make sure the key exists
                if not k in d.hkeys: return False

                # Make sure it's the same.
                if not self.h(k) == d.h(k): return False

        if columns:

            # Same number of columns
            if not len(self.ckeys) == len(d.ckeys): return False

            # If we're checking columns by ckeys
            if ckeys:

                # Columns
                if column_order and not self.ckeys == d.ckeys: return False

                # Each value of each array
                for k in self.ckeys:
                    # Make sure the key exists
                    if not k in d.ckeys: return False

                    # Check the values
                    if not (_n.array(self[k]) == _n.array(d[k])).all(): return False

            # Otherwise we're ignoring ckeys
            else:
                for n in range(len(self.ckeys)):
                    if not (_n.array(self[n]) == _n.array(d[n])).all(): return False

        # Passes all tests
        return True

Response: Tests that the information in this databox is the same as that of the other databox.