Instruction:
Can you create a Python 3 function that
populates the decompression structure with appropriate input parameters.

Response:
def _populate_dparams(self, rlevel, tile=None, area=None):
        """Populate decompression structure with appropriate input parameters.

        Parameters
        ----------
        rlevel : int
            Factor by which to rlevel output resolution.
        area : tuple
            Specifies decoding image area,
            (first_row, first_col, last_row, last_col)
        tile : int
            Number of tile to decode.
        """
        if opj2.OPENJP2 is not None:
            dparam = opj2.set_default_decoder_parameters()
        else:
            dparam = opj.DecompressionParametersType()
            opj.set_default_decoder_parameters(ctypes.byref(dparam))

        infile = self.filename.encode()
        nelts = opj2.PATH_LEN - len(infile)
        infile += b'0' * nelts
        dparam.infile = infile

        # Return raw codestream components instead of "interpolating" the
        # colormap?
        dparam.flags |= 1 if self.ignore_pclr_cmap_cdef else 0

        dparam.decod_format = self._codec_format
        dparam.cp_layer = self._layer

        # Must check the specified rlevel against the maximum.
        if rlevel != 0:
            # Must check the specified rlevel against the maximum.
            max_rlevel = self.codestream.segment[2].num_res
            if rlevel == -1:
                # -1 is shorthand for the largest rlevel
                rlevel = max_rlevel
            elif rlevel < -1 or rlevel > max_rlevel:
                msg = ("rlevel must be in the range [-1, {max_rlevel}] "
                       "for this image.")
                msg = msg.format(max_rlevel=max_rlevel)
                raise IOError(msg)

        dparam.cp_reduce = rlevel

        if area is not None:
            if area[0] < 0 or area[1] < 0 or area[2] <= 0 or area[3] <= 0:
                msg = ("The upper left corner coordinates must be nonnegative "
                       "and the lower right corner coordinates must be "
                       "positive.  The specified upper left and lower right "
                       "coordinates are ({y0}, {x0}) and ({y1}, {x1}).")
                msg = msg.format(x0=area[1], y0=area[0],
                                 x1=area[3], y1=area[2])
                raise IOError(msg)
            dparam.DA_y0 = area[0]
            dparam.DA_x0 = area[1]
            dparam.DA_y1 = area[2]
            dparam.DA_x1 = area[3]

        if tile is not None:
            dparam.tile_index = tile
            dparam.nb_tile_to_decode = 1

        self._dparams = dparam


Instruction:
Can you write a function in Python 3 where it
reads a JPEG 2000 image.

Response:
def read_bands(self, rlevel=0, layer=None, area=None, tile=None,
                   verbose=False, ignore_pclr_cmap_cdef=False):
        """Read a JPEG 2000 image.

        The only time you should use this method is when the image has
        different subsampling factors across components.  Otherwise you should
        use the read method.

        Parameters
        ----------
        layer : int, optional
            Number of quality layer to decode.
        rlevel : int, optional
            Factor by which to rlevel output resolution.
        area : tuple, optional
            Specifies decoding image area,
            (first_row, first_col, last_row, last_col)
        tile : int, optional
            Number of tile to decode.
        ignore_pclr_cmap_cdef : bool
            Whether or not to ignore the pclr, cmap, or cdef boxes during any
            color transformation.  Defaults to False.
        verbose : bool, optional
            Print informational messages produced by the OpenJPEG library.

        Returns
        -------
        list
            List of the individual image components.

        See also
        --------
        read : read JPEG 2000 image

        Examples
        --------
        >>> import glymur
        >>> jfile = glymur.data.nemo()
        >>> jp = glymur.Jp2k(jfile)
        >>> components_lst = jp.read_bands(rlevel=1)
        """
        if version.openjpeg_version < '2.1.0':
            msg = ("You must have at least version 2.1.0 of OpenJPEG "
                   "installed before using this method.  Your version of "
                   "OpenJPEG is {version}.")
            msg = msg.format(version=version.openjpeg_version)
            raise IOError(msg)

        self.ignore_pclr_cmap_cdef = ignore_pclr_cmap_cdef
        self.layer = layer
        self._populate_dparams(rlevel, tile=tile, area=area)
        lst = self._read_openjp2_common()
        return lst


Instruction:
Can you tell what is the following Python 3 function doing
def _extract_image(self, raw_image):
        ncomps = raw_image.contents.numcomps

        # Make a pass thru the image, see if any of the band datatypes or
        # dimensions differ.
        dtypes, nrows, ncols = [], [], []
        for k in range(raw_image.contents.numcomps):
            component = raw_image.contents.comps[k]
            dtypes.append(self._component2dtype(component))
            nrows.append(component.h)
            ncols.append(component.w)
        is_cube = all(r == nrows[0] and c == ncols[0] and d == dtypes[0]
                      for r, c, d in zip(nrows, ncols, dtypes))

        if is_cube:
            image = np.zeros((nrows[0], ncols[0], ncomps), dtypes[0])
        else:
            image = []

        for k in range(raw_image.contents.numcomps):
            component = raw_image.contents.comps[k]

            self._validate_nonzero_image_size(nrows[k], ncols[k], k)

            addr = ctypes.addressof(component.data.contents)
            with warnings.catch_warnings():
                warnings.simplefilter("ignore")
                nelts = nrows[k] * ncols[k]
                band = np.ctypeslib.as_array(
                    (ctypes.c_int32 * nelts).from_address(addr))
                if is_cube:
                    image[:, :, k] = np.reshape(band.astype(dtypes[k]),
                                                (nrows[k], ncols[k]))
                else:
                    image.append(np.reshape(band.astype(dtypes[k]),
                                 (nrows[k], ncols[k])))

        if is_cube and image.shape[2] == 1:
            # The third dimension has just a single layer.  Make the image
            # data 2D instead of 3D.
            image.shape = image.shape[0:2]

        return image

Response: Extracts the unequally - sized components from the image structure.


Instruction:
Explain what the following Python 3 code does
def _component2dtype(self, component):
        if component.prec > 16:
            msg = "Unhandled precision: {0} bits.".format(component.prec)
            raise IOError(msg)

        if component.sgnd:
            dtype = np.int8 if component.prec <=8 else np.int16
        else:
            dtype = np.uint8 if component.prec <=8 else np.uint16

        return dtype

Response: Return the numpy datatype for an OpenJPEG component.


Instruction:
Implement a function in Python 3 to
retrieve the codestream entry for the current file.

Response:
def get_codestream(self, header_only=True):
        """Retrieve codestream.

        Parameters
        ----------
        header_only : bool, optional
            If True, only marker segments in the main header are parsed.
            Supplying False may impose a large performance penalty.

        Returns
        -------
        Codestream
            Object describing the codestream syntax.

        Examples
        --------
        >>> import glymur
        >>> jfile = glymur.data.nemo()
        >>> jp2 = glymur.Jp2k(jfile)
        >>> codestream = jp2.get_codestream()
        >>> print(codestream.segment[1])
        SIZ marker segment @ (3233, 47)
            Profile:  no profile
            Reference Grid Height, Width:  (1456 x 2592)
            Vertical, Horizontal Reference Grid Offset:  (0 x 0)
            Reference Tile Height, Width:  (1456 x 2592)
            Vertical, Horizontal Reference Tile Offset:  (0 x 0)
            Bitdepth:  (8, 8, 8)
            Signed:  (False, False, False)
            Vertical, Horizontal Subsampling:  ((1, 1), (1, 1), (1, 1))
        """
        with open(self.filename, 'rb') as fptr:
            if self._codec_format == opj2.CODEC_J2K:
                codestream = Codestream(fptr, self.length,
                                        header_only=header_only)
            else:
                box = [x for x in self.box if x.box_id == 'jp2c']
                fptr.seek(box[0].offset)
                read_buffer = fptr.read(8)
                (box_length, _) = struct.unpack('>I4s', read_buffer)
                if box_length == 0:
                    # The length of the box is presumed to last until the end
                    # of the file.  Compute the effective length of the box.
                    box_length = os.path.getsize(fptr.name) - fptr.tell() + 8
                elif box_length == 1:
                    # Seek past the XL field.
                    read_buffer = fptr.read(8)
                    box_length, = struct.unpack('>Q', read_buffer)
                codestream = Codestream(fptr, box_length - 8,
                                        header_only=header_only)

            return codestream


Instruction:
Can you implement a function in Python 3 that
populates the image structure needed for compression.

Response:
def _populate_image_struct(self, image, imgdata):
        """Populates image struct needed for compression.

        Parameters
        ----------
        image : ImageType(ctypes.Structure)
            Corresponds to image_t type in openjp2 headers.
        img_array : ndarray
            Image data to be written to file.
        """

        numrows, numcols, num_comps = imgdata.shape
        for k in range(num_comps):
            self._validate_nonzero_image_size(numrows, numcols, k)

        # set image offset and reference grid
        image.contents.x0 = self._cparams.image_offset_x0
        image.contents.y0 = self._cparams.image_offset_y0
        image.contents.x1 = (image.contents.x0 +
                             (numcols - 1) * self._cparams.subsampling_dx + 1)
        image.contents.y1 = (image.contents.y0 +
                             (numrows - 1) * self._cparams.subsampling_dy + 1)

        # Stage the image data to the openjpeg data structure.
        for k in range(0, num_comps):
            if self._cparams.rsiz in (core.OPJ_PROFILE_CINEMA_2K,
                                      core.OPJ_PROFILE_CINEMA_4K):
                image.contents.comps[k].prec = 12
                image.contents.comps[k].bpp = 12

            layer = np.ascontiguousarray(imgdata[:, :, k], dtype=np.int32)
            dest = image.contents.comps[k].data
            src = layer.ctypes.data
            ctypes.memmove(dest, src, layer.nbytes)

        return image


Instruction:
Write a Python 3 function for
raising IOError if the image has no area of zero.

Response:
def _validate_nonzero_image_size(self, nrows, ncols, component_index):
        """The image cannot have area of zero.
        """
        if nrows == 0 or ncols == 0:
            # Letting this situation continue would segfault openjpeg.
            msg = "Component {0} has dimensions {1} x {2}"
            msg = msg.format(component_index, nrows, ncols)
            raise IOError(msg)


Instruction:
Write a Python 3 function for
validating the JP2 box sequence.

Response:
def _validate_jp2_box_sequence(self, boxes):
        """Run through series of tests for JP2 box legality.

        This is non-exhaustive.
        """
        JP2_IDS = ['colr', 'cdef', 'cmap', 'jp2c', 'ftyp', 'ihdr', 'jp2h',
                   'jP  ', 'pclr', 'res ', 'resc', 'resd', 'xml ', 'ulst',
                   'uinf', 'url ', 'uuid']

        self._validate_signature_compatibility(boxes)
        self._validate_jp2h(boxes)
        self._validate_jp2c(boxes)
        if boxes[1].brand == 'jpx ':
            self._validate_jpx_box_sequence(boxes)
        else:
            # Validate the JP2 box IDs.
            count = self._collect_box_count(boxes)
            for box_id in count.keys():
                if box_id not in JP2_IDS:
                    msg = ("The presence of a '{0}' box requires that the "
                           "file type brand be set to 'jpx '.")
                    raise IOError(msg.format(box_id))

            self._validate_jp2_colr(boxes)


Instruction:
Write a Python 3 script for
validating JP2 requirements on colour specification boxes.

Response:
def _validate_jp2_colr(self, boxes):
        """
        Validate JP2 requirements on colour specification boxes.
        """
        lst = [box for box in boxes if box.box_id == 'jp2h']
        jp2h = lst[0]
        for colr in [box for box in jp2h.box if box.box_id == 'colr']:
            if colr.approximation != 0:
                msg = ("A JP2 colr box cannot have a non-zero approximation "
                       "field.")
                raise IOError(msg)


Instruction:
Create a Python 3 function for
running through series of tests for JPX box legality.

Response:
def _validate_jpx_box_sequence(self, boxes):
        """Run through series of tests for JPX box legality."""
        self._validate_label(boxes)
        self._validate_jpx_compatibility(boxes, boxes[1].compatibility_list)
        self._validate_singletons(boxes)
        self._validate_top_level(boxes)


Instruction:
Can you tell what is the following Python 3 function doing
def _validate_signature_compatibility(self, boxes):
        # Check for a bad sequence of boxes.
        # 1st two boxes must be 'jP  ' and 'ftyp'
        if boxes[0].box_id != 'jP  ' or boxes[1].box_id != 'ftyp':
            msg = ("The first box must be the signature box and the second "
                   "must be the file type box.")
            raise IOError(msg)

        # The compatibility list must contain at a minimum 'jp2 '.
        if 'jp2 ' not in boxes[1].compatibility_list:
            msg = "The ftyp box must contain 'jp2 ' in the compatibility list."
            raise IOError(msg)

Response: Validate the file signature and compatibility status.


Instruction:
Can you tell what is the following Python 3 function doing
def _validate_jp2c(self, boxes):
        # jp2c must be preceeded by jp2h
        jp2h_lst = [idx for (idx, box) in enumerate(boxes)
                    if box.box_id == 'jp2h']
        jp2h_idx = jp2h_lst[0]
        jp2c_lst = [idx for (idx, box) in enumerate(boxes)
                    if box.box_id == 'jp2c']
        if len(jp2c_lst) == 0:
            msg = ("A codestream box must be defined in the outermost "
                   "list of boxes.")
            raise IOError(msg)

        jp2c_idx = jp2c_lst[0]
        if jp2h_idx >= jp2c_idx:
            msg = "The codestream box must be preceeded by a jp2 header box."
            raise IOError(msg)

Response: Validate the codestream box in relation to other boxes.


Instruction:
Can you tell what is the following Python 3 function doing
def _validate_jp2h(self, boxes):
        self._check_jp2h_child_boxes(boxes, 'top-level')

        jp2h_lst = [box for box in boxes if box.box_id == 'jp2h']
        jp2h = jp2h_lst[0]

        # 1st jp2 header box cannot be empty.
        if len(jp2h.box) == 0:
            msg = "The JP2 header superbox cannot be empty."
            raise IOError(msg)

        # 1st jp2 header box must be ihdr
        if jp2h.box[0].box_id != 'ihdr':
            msg = ("The first box in the jp2 header box must be the image "
                   "header box.")
            raise IOError(msg)

        # colr must be present in jp2 header box.
        colr_lst = [j for (j, box) in enumerate(jp2h.box)
                    if box.box_id == 'colr']
        if len(colr_lst) == 0:
            msg = "The jp2 header box must contain a color definition box."
            raise IOError(msg)
        colr = jp2h.box[colr_lst[0]]

        self._validate_channel_definition(jp2h, colr)

Response: Validate the JP2 Header box.


Instruction:
Can you generate the documentation for the following Python 3 function
def _validate_channel_definition(self, jp2h, colr):
        cdef_lst = [j for (j, box) in enumerate(jp2h.box)
                    if box.box_id == 'cdef']
        if len(cdef_lst) > 1:
            msg = ("Only one channel definition box is allowed in the "
                   "JP2 header.")
            raise IOError(msg)
        elif len(cdef_lst) == 1:
            cdef = jp2h.box[cdef_lst[0]]
            if colr.colorspace == core.SRGB:
                if any([chan + 1 not in cdef.association or
                        cdef.channel_type[chan] != 0 for chan in [0, 1, 2]]):
                    msg = ("All color channels must be defined in the "
                           "channel definition box.")
                    raise IOError(msg)
            elif colr.colorspace == core.GREYSCALE:
                if 0 not in cdef.channel_type:
                    msg = ("All color channels must be defined in the "
                           "channel definition box.")
                    raise IOError(msg)

Response: Validate the channel definition box.


Instruction:
Can you tell what is the following Python 3 function doing
def _check_jp2h_child_boxes(self, boxes, parent_box_name):
        JP2H_CHILDREN = set(['bpcc', 'cdef', 'cmap', 'ihdr', 'pclr'])

        box_ids = set([box.box_id for box in boxes])
        intersection = box_ids.intersection(JP2H_CHILDREN)
        if len(intersection) > 0 and parent_box_name not in ['jp2h', 'jpch']:
            msg = "A {0} box can only be nested in a JP2 header box."
            raise IOError(msg.format(list(intersection)[0]))

        # Recursively check any contained superboxes.
        for box in boxes:
            if hasattr(box, 'box'):
                self._check_jp2h_child_boxes(box.box, box.box_id)

Response: Checks that all child boxes of a JP2 header are in the JP2 header.


Instruction:
Write a Python 3 function that can
count the occurences of each box type.

Response:
def _collect_box_count(self, boxes):
        """Count the occurences of each box type."""
        count = Counter([box.box_id for box in boxes])

        # Add the counts in the superboxes.
        for box in boxes:
            if hasattr(box, 'box'):
                count.update(self._collect_box_count(box.box))

        return count


Instruction:
Explain what the following Python 3 code does
def _check_superbox_for_top_levels(self, boxes):
        # We are only looking at the boxes contained in a superbox, so if any
        # of the blacklisted boxes show up here, it's an error.
        TOP_LEVEL_ONLY_BOXES = set(['dtbl'])
        box_ids = set([box.box_id for box in boxes])
        intersection = box_ids.intersection(TOP_LEVEL_ONLY_BOXES)
        if len(intersection) > 0:
            msg = "A {0} box cannot be nested in a superbox."
            raise IOError(msg.format(list(intersection)[0]))

        # Recursively check any contained superboxes.
        for box in boxes:
            if hasattr(box, 'box'):
                self._check_superbox_for_top_levels(box.box)

Response: Check that all boxes are at the top level.


Instruction:
Here you have a function in Python 3, explain what it does
def _validate_top_level(self, boxes):
        # Add the counts in the superboxes.
        for box in boxes:
            if hasattr(box, 'box'):
                self._check_superbox_for_top_levels(box.box)

        count = self._collect_box_count(boxes)

        # If there is one data reference box, then there must also be one ftbl.
        if 'dtbl' in count and 'ftbl' not in count:
            msg = ('The presence of a data reference box requires the '
                   'presence of a fragment table box as well.')
            raise IOError(msg)

Response: Validate that all boxes are at the top level.


Instruction:
Explain what the following Python 3 code does
def _validate_singletons(self, boxes):
        count = self._collect_box_count(boxes)
        # Which boxes occur more than once?
        multiples = [box_id for box_id, bcount in count.items() if bcount > 1]
        if 'dtbl' in multiples:
            raise IOError('There can only be one dtbl box in a file.')

Response: Validate that there are no singletons in a file.


Instruction:
How would you explain what the following Python 3 function does
def _validate_jpx_compatibility(self, boxes, compatibility_list):
        JPX_IDS = ['asoc', 'nlst']
        jpx_cl = set(compatibility_list)
        for box in boxes:
            if box.box_id in JPX_IDS:
                if len(set(['jpx ', 'jpxb']).intersection(jpx_cl)) == 0:
                    msg = ("A JPX box requires that either 'jpx ' or 'jpxb' "
                           "be present in the ftype compatibility list.")
                    raise RuntimeError(msg)
            if hasattr(box, 'box') != 0:
                # Same set of checks on any child boxes.
                self._validate_jpx_compatibility(box.box, compatibility_list)

Response: Validate that all JPX boxes are present in the compatibility list.


Instruction:
Write a Python 3 script to
validate that all label boxes are inside association codestream headers or codestream compositing layer header boxes.

Response:
def _validate_label(self, boxes):
        """
        Label boxes can only be inside association, codestream headers, or
        compositing layer header boxes.
        """
        for box in boxes:
            if box.box_id != 'asoc':
                if hasattr(box, 'box'):
                    for boxi in box.box:
                        if boxi.box_id == 'lbl ':
                            msg = ("A label box cannot be nested inside a "
                                   "{0} box.")
                            msg = msg.format(box.box_id)
                            raise IOError(msg)
                    # Same set of checks on any child boxes.
                    self._validate_label(box.box)


Instruction:
Create a Python 3 function to
fulfill an HTTP request to Keen s API.

Response:
def fulfill(self, method, *args, **kwargs):

        """ Fulfill an HTTP request to Keen's API. """

        return getattr(self.session, method)(*args, **kwargs)


Instruction:
How would you explain what the following Python 3 function does
def post_event(self, event):

        url = "{0}/{1}/projects/{2}/events/{3}".format(self.base_url, self.api_version,
                                                       self.project_id,
                                                       event.event_collection)
        headers = utilities.headers(self.write_key)
        payload = event.to_json()
        response = self.fulfill(HTTPMethods.POST, url, data=payload, headers=headers, timeout=self.post_timeout)
        self._error_handling(response)

Response: Post an event to the Keen IO API.


Instruction:
Can you generate the documentation for the following Python 3 function
def post_events(self, events):

        """
        Posts a single event to the Keen IO API. The write key must be set first.

        :param events: an Event to upload
        """

        url = "{0}/{1}/projects/{2}/events".format(self.base_url, self.api_version,
                                                   self.project_id)
        headers = utilities.headers(self.write_key)
        payload = json.dumps(events)
        response = self.fulfill(HTTPMethods.POST, url, data=payload, headers=headers, timeout=self.post_timeout)
        self._error_handling(response)
        return self._get_response_json(response)

Response: Post a single event to the Keen IO API.


Instruction:
Write a Python 3 function for
validating that a given order_by is well - formed and returns True if either no order_by is present or if the order_by is well - formed or False if it is not well - formed.

Response:
def _order_by_is_valid_or_none(self, params):
        """
        Validates that a given order_by has proper syntax.

        :param params: Query params.
        :return: Returns True if either no order_by is present, or if the order_by is well-formed.
        """
        if not "order_by" in params or not params["order_by"]:
            return True

        def _order_by_dict_is_not_well_formed(d):
            if not isinstance(d, dict):
                # Bad type.
                return True
            if "property_name" in d and d["property_name"]:
                if "direction" in d and not direction.is_valid_direction(d["direction"]):
                    # Bad direction provided.
                    return True
                for k in d:
                    if k != "property_name" and k != "direction":
                        # Unexpected key.
                        return True
                # Everything looks good!
                return False
            # Missing required key.
            return True

        # order_by is converted to a list before this point if it wasn't one before.
        order_by_list = json.loads(params["order_by"])

        for order_by in order_by_list:
            if _order_by_dict_is_not_well_formed(order_by):
                return False
        if not "group_by" in params or not params["group_by"]:
            # We must have group_by to have order_by make sense.
            return False
        return True


Instruction:
Here you have a function in Python 3, explain what it does
def _limit_is_valid_or_none(self, params):
        if not "limit" in params or not params["limit"]:
            return True
        if not isinstance(params["limit"], int) or params["limit"] < 1:
            return False
        if not "order_by" in params:
            return False
        return True

Response: Validates that a given limit is present or is well - formed. Returns True if it is well - formed.


Instruction:
Can you create a Python 3 function that
performs a query using the Keen IO analysis API.

Response:
def query(self, analysis_type, params, all_keys=False):
        """
        Performs a query using the Keen IO analysis API.  A read key must be set first.

        """
        if not self._order_by_is_valid_or_none(params):
            raise ValueError("order_by given is invalid or is missing required group_by.")
        if not self._limit_is_valid_or_none(params):
            raise ValueError("limit given is invalid or is missing required order_by.")

        url = "{0}/{1}/projects/{2}/queries/{3}".format(self.base_url, self.api_version,
                                                        self.project_id, analysis_type)

        headers = utilities.headers(self.read_key)
        payload = params
        response = self.fulfill(HTTPMethods.GET, url, params=payload, headers=headers, timeout=self.get_timeout)
        self._error_handling(response)

        response = response.json()

        if not all_keys:
            response = response["result"]

        return response


Instruction:
How would you implement a function in Python 3 that
deletes events from the Keen IO API.

Response:
def delete_events(self, event_collection, params):
        """
        Deletes events via the Keen IO API. A master key must be set first.

        :param event_collection: string, the event collection from which event are being deleted

        """

        url = "{0}/{1}/projects/{2}/events/{3}".format(self.base_url,
                                                       self.api_version,
                                                       self.project_id,
                                                       event_collection)
        headers = utilities.headers(self.master_key)
        response = self.fulfill(HTTPMethods.DELETE, url, params=params, headers=headers, timeout=self.post_timeout)

        self._error_handling(response)
        return True


Instruction:
Can you generate the documentation for the following Python 3 function
def get_collection(self, event_collection):

        url = "{0}/{1}/projects/{2}/events/{3}".format(self.base_url, self.api_version,
                                                       self.project_id, event_collection)
        headers = utilities.headers(self.read_key)
        response = self.fulfill(HTTPMethods.GET, url, headers=headers, timeout=self.get_timeout)
        self._error_handling(response)

        return response.json()

Response: Retrieves information about a specific event collection.


Instruction:
Write a Python 3 function for
adding permissions to the existing list of permissions on this key.

Response:
def add_access_key_permissions(self, access_key_id, permissions):
        """
        Adds to the existing list of permissions on this key with the contents of this list.
        Will not remove any existing permissions or modify the remainder of the key.

        :param access_key_id: the 'key' value of the access key to add permissions to
        :param permissions: the new permissions to add to the existing list of permissions
        """
        # Get current state via HTTPS.
        current_access_key = self.get_access_key(access_key_id)

        # Copy and only change the single parameter.
        payload_dict = KeenApi._build_access_key_dict(current_access_key)

        # Turn into sets to avoid duplicates.
        old_permissions = set(payload_dict["permitted"])
        new_permissions = set(permissions)
        combined_permissions = old_permissions.union(new_permissions)
        payload_dict["permitted"] = list(combined_permissions)

        # Now just treat it like a full update.
        return self.update_access_key_full(access_key_id, **payload_dict)


Instruction:
Can you implement a function in Python 3 that
removes a list of permissions from the existing list of permissions.

Response:
def remove_access_key_permissions(self, access_key_id, permissions):
        """
        Removes a list of permissions from the existing list of permissions.
        Will not remove all existing permissions unless all such permissions are included
        in this list. Not to be confused with key revocation.

        See also: revoke_access_key()

        :param access_key_id: the 'key' value of the access key to remove some permissions from
        :param permissions: the permissions you wish to remove from this access key
        """
        # Get current state via HTTPS.
        current_access_key = self.get_access_key(access_key_id)

        # Copy and only change the single parameter.
        payload_dict = KeenApi._build_access_key_dict(current_access_key)

        # Turn into sets to avoid duplicates.
        old_permissions = set(payload_dict["permitted"])
        removal_permissions = set(permissions)
        reduced_permissions = old_permissions.difference(removal_permissions)
        payload_dict["permitted"] = list(reduced_permissions)

        # Now just treat it like a full update.
        return self.update_access_key_full(access_key_id, **payload_dict)


Instruction:
How would you code a function in Python 3 to
update the name is_active permitted and options values of a given master key.

Response:
def update_access_key_full(self, access_key_id, name, is_active, permitted, options):
        """
        Replaces the 'name', 'is_active', 'permitted', and 'options' values of a given key.
        A master key must be set first.

        :param access_key_id: the 'key' value of the access key for which the values will be replaced
        :param name: the new name desired for this access key
        :param is_active: whether the key should become enabled (True) or revoked (False)
        :param permitted: the new list of permissions desired for this access key
        :param options: the new dictionary of options for this access key
        """
        url = "{0}/{1}/projects/{2}/keys/{3}".format(self.base_url, self.api_version,
                                                     self.project_id, access_key_id)
        headers = utilities.headers(self.master_key)
        payload_dict = {
            "name": name,
            "is_active": is_active,
            "permitted": permitted,
            "options": options
        }
        payload = json.dumps(payload_dict)
        response = self.fulfill(HTTPMethods.POST, url, data=payload, headers=headers, timeout=self.get_timeout)
        self._error_handling(response)
        return response.json()


Instruction:
Can you create a Python 3 function that
fetches all Cached Datasets for a Project.

Response:
def all(self):
        """ Fetch all Cached Datasets for a Project. Read key must be set.
        """
        return self._get_json(HTTPMethods.GET,
                              self._cached_datasets_url,
                              self._get_master_key())


Instruction:
Implement a function in Python 3 to
fetch a single Cached Dataset for a Project.

Response:
def get(self, dataset_name):
        """ Fetch a single Cached Dataset for a Project. Read key must be set.

        :param dataset_name: Name of Cached Dataset (not `display_name`)
        """
        url = "{0}/{1}".format(self._cached_datasets_url, dataset_name)
        return self._get_json(HTTPMethods.GET, url, self._get_read_key())


Instruction:
Given the following Python 3 function, write the documentation
def create(self, dataset_name, query, index_by, display_name):
        url = "{0}/{1}".format(self._cached_datasets_url, dataset_name)
        payload = {
            "query": query,
            "index_by": index_by,
            "display_name": display_name
        }
        return self._get_json(HTTPMethods.PUT, url, self._get_master_key(), json=payload)

Response: Create a Cached Dataset for a Project.


Instruction:
Can you tell what is the following Python 3 function doing
def results(self, dataset_name, index_by, timeframe):
        url = "{0}/{1}/results".format(self._cached_datasets_url, dataset_name)

        index_by = index_by if isinstance(index_by, str) else json.dumps(index_by)
        timeframe = timeframe if isinstance(timeframe, str) else json.dumps(timeframe)

        query_params = {
            "index_by": index_by,
            "timeframe": timeframe
        }

        return self._get_json(
            HTTPMethods.GET, url, self._get_read_key(), params=query_params
        )

Response: Retrieve results from a Cached Dataset. Read key must be set.


Instruction:
Can you tell what is the following Python 3 function doing
def delete(self, dataset_name):
        url = "{0}/{1}".format(self._cached_datasets_url, dataset_name)
        self._get_json(HTTPMethods.DELETE, url, self._get_master_key())
        return True

Response: Delete a Cached Dataset.


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

    # Current directory.
    fname = os.path.join(os.getcwd(), 'glymurrc')
    if os.path.exists(fname):
        return fname

    confdir = get_configdir()
    if confdir is not None:
        fname = os.path.join(confdir, 'glymurrc')
        if os.path.exists(fname):
            return fname

    # didn't find a configuration file.
    return None

Response: Return the path to the configuration file.


Instruction:
Explain what the following Python 3 code does
def load_library_handle(libname, path):

    if path is None or path in ['None', 'none']:
        # Either could not find a library via ctypes or
        # user-configuration-file, or we could not find it in any of the
        # default locations, or possibly the user intentionally does not want
        # one of the libraries to load.
        return None

    try:
        if os.name == "nt":
            opj_lib = ctypes.windll.LoadLibrary(path)
        else:
            opj_lib = ctypes.CDLL(path)
    except (TypeError, OSError):
        msg = 'The {libname} library at {path} could not be loaded.'
        msg = msg.format(path=path, libname=libname)
        warnings.warn(msg, UserWarning)
        opj_lib = None

    return opj_lib

Response: Load the library return the ctypes handle.


Instruction:
Given the following Python 3 function, write the documentation
def read_config_file(libname):
    filename = glymurrc_fname()
    if filename is None:
        # There's no library file path to return in this case.
        return None

    # Read the configuration file for the library location.
    parser = ConfigParser()
    parser.read(filename)
    try:
        path = parser.get('library', libname)
    except (NoOptionError, NoSectionError):
        path = None
    return path

Response: Reads the configuration file for the specified library.


Instruction:
Can you write a function in Python 3 where it
tries to ascertain locations of openjp2 openjpeg libraries. Returns ------- tuple of library handles

Response:
def glymur_config():
    """
    Try to ascertain locations of openjp2, openjpeg libraries.

    Returns
    -------
    tuple
        tuple of library handles
    """
    handles = (load_openjpeg_library(x) for x in ['openjp2', 'openjpeg'])
    handles = tuple(handles)

    if all(handle is None for handle in handles):
        msg = "Neither the openjp2 nor the openjpeg library could be loaded.  "
        warnings.warn(msg)
    return handles


Instruction:
Can you generate a brief explanation for the following Python 3 code
def get_configdir():
    if 'XDG_CONFIG_HOME' in os.environ:
        return os.path.join(os.environ['XDG_CONFIG_HOME'], 'glymur')

    if 'HOME' in os.environ and os.name != 'nt':
        # HOME is set by WinPython to something unusual, so we don't
        # necessarily want that.
        return os.path.join(os.environ['HOME'], '.config', 'glymur')

    # Last stand.  Should handle windows... others?
    return os.path.join(os.path.expanduser('~'), 'glymur')

Response: Return string representing the configuration directory.


Instruction:
Explain what the following Python 3 code does
def set_option(key, value):
    if key not in _options.keys():
        raise KeyError('{key} not valid.'.format(key=key))
    _options[key] = value

Response: Set the value of the specified option.


Instruction:
Write a Python 3 script to
reset one or more options to their default value.

Response:
def reset_option(key):
    """
    Reset one or more options to their default value.

    Pass "all" as argument to reset all options.

    Available options:

        parse.full_codestream
        print.xml
        print.codestream
        print.short

    Parameter
    ---------
    key : str
        Name of a single option.
    """
    global _options
    if key == 'all':
        _options = copy.deepcopy(_original_options)
    else:
        if key not in _options.keys():
            raise KeyError('{key} not valid.'.format(key=key))
        _options[key] = _original_options[key]


Instruction:
Create a Python 3 function to
set printing options for JPEG 2000 boxes.

Response:
def set_printoptions(**kwargs):
    """Set printing options.

    These options determine the way JPEG 2000 boxes are displayed.

    Parameters
    ----------
    short : bool, optional
        When True, only the box ID, offset, and length are displayed.  Useful
        for displaying only the basic structure or skeleton of a JPEG 2000
        file.
    xml : bool, optional
        When False, printing of the XML contents of any XML boxes or UUID XMP
        boxes is suppressed.
    codestream : bool, optional
        When False, the codestream segments are not printed.  Otherwise the
        segments are printed depending on how set_parseoptions has been used.

    See also
    --------
    get_printoptions

    Examples
    --------
    To put back the default options, you can use:

    >>> import glymur
    >>> glymur.set_printoptions(short=False, xml=True, codestream=True)
    """
    warnings.warn('Use set_option instead of set_printoptions.',
                  DeprecationWarning)
    for key, value in kwargs.items():
        if key not in ['short', 'xml', 'codestream']:
            raise KeyError('"{0}" not a valid keyword parameter.'.format(key))
        set_option('print.' + key, value)


Instruction:
Write a Python 3 function for
returning the current print options.

Response:
def get_printoptions():
    """Return the current print options.

    Returns
    -------
    dict
        Dictionary of current print options with keys

          - short : bool
          - xml : bool
          - codestream : bool

        For a full description of these options, see `set_printoptions`.

    See also
    --------
    set_printoptions
    """
    warnings.warn('Use get_option instead of get_printoptions.',
                  DeprecationWarning)
    d = {}
    for key in ['short', 'xml', 'codestream']:
        d[key] = _options['print.' + key]
    return d


Instruction:
Can you implement a function in Python 3 that
adds a slash to the end of a string

Response:
def _add_slash(self, string=None):
        """ if a string doesn't end in a '/' add one """
        if(not str.endswith(string, '/')):
            return str.join('', [string, '/'])
        return str(string)


Instruction:
How would you implement a function in Python 3 that
sets the Cerberus token based on auth type

Response:
def _set_token(self):
        """Set the Cerberus token based on auth type"""
        try:
            self.token = os.environ['CERBERUS_TOKEN']
            if self.verbose:
                print("Overriding Cerberus token with environment variable.", file=sys.stderr)
            logger.info("Overriding Cerberus token with environment variable.")
            return
        except:
            pass
        if self.username:
            ua = UserAuth(self.cerberus_url, self.username, self.password)
            self.token = ua.get_token()
        else:
            awsa = AWSAuth(self.cerberus_url, region=self.region, aws_session=self.aws_session, verbose=self.verbose)
            self.token = awsa.get_token()


Instruction:
Given the following Python 3 function, write the documentation
def get_roles(self):
        roles_resp = get_with_retry(self.cerberus_url + '/v1/role',
                                  headers=self.HEADERS)

        throw_if_bad_response(roles_resp)
        return roles_resp.json()

Response: Get all the roles that can be granted to a safe deposit box.


Instruction:
Explain what the following Python 3 code does
def get_role(self, key):

        json_resp = self.get_roles()
        for item in json_resp:
            if key in item["name"]:
                return item["id"]
        raise CerberusClientException("Key '%s' not found" % key)

Response: Return id of named role.


Instruction:
How would you implement a function in Python 3 that
simplifies version of get_roles that returns a dict of just name : id for the roles

Response:
def list_roles(self):
        """Simplified version of get_roles that returns a dict of just name: id for the roles"""

        json_resp = self.get_roles()
        temp_dict = {}
        for item in json_resp:
            temp_dict[item["name"]] = item["id"]
        return temp_dict


Instruction:
Write a Python 3 script to
return a list of categories that a safe deposit box can belong to

Response:
def get_categories(self):
        """ Return a list of categories that a safe deposit box can belong to"""
        sdb_resp = get_with_retry(self.cerberus_url + '/v1/category',
                                headers=self.HEADERS)

        throw_if_bad_response(sdb_resp)
        return sdb_resp.json()


Instruction:
Create a Python 3 function for
creating a new safe deposit box.

Response:
def create_sdb(self, name, category_id, owner, description="", user_group_permissions=None,
                   iam_principal_permissions=None):
        """Create a safe deposit box.

        You need to refresh your token before the iam role is granted permission to the new safe deposit box.
        Keyword arguments:
            name (string) -- name of the safe deposit box
            category_id (string) -- category id that determines where to store the sdb. (ex: shared, applications)
            owner (string) -- AD group that owns the safe deposit box
            description (string) -- Description of the safe deposit box
            user_group_permissions (list) -- list of dictionaries containing the key name and maybe role_id
            iam_principal_permissions (list) -- list of dictionaries containing the key name iam_principal_arn
            and role_id
        """

        # Do some sanity checking
        if user_group_permissions is None:
            user_group_permissions = []
        if iam_principal_permissions is None:
            iam_principal_permissions = []
        if list != type(user_group_permissions):
            raise(TypeError('Expected list, but got ' + str(type(user_group_permissions))))
        if list != type(iam_principal_permissions):
            raise(TypeError('Expected list, but got ' + str(type(iam_principal_permissions))))
        temp_data = {
            "name": name,
            "description": description,
            "category_id": category_id,
            "owner": owner,
        }
        if len(user_group_permissions) > 0:
            temp_data["user_group_permissions"] = user_group_permissions
        if len(iam_principal_permissions) > 0:
            temp_data["iam_principal_permissions"] = iam_principal_permissions
        data = json.encoder.JSONEncoder().encode(temp_data)
        sdb_resp = post_with_retry(self.cerberus_url + '/v2/safe-deposit-box', data=str(data), headers=self.HEADERS)

        throw_if_bad_response(sdb_resp)
        return sdb_resp.json()


Instruction:
Can you write a function in Python 3 where it
deletes a safe deposit box specified by id

Response:
def delete_sdb(self, sdb_id):
        """ Delete a safe deposit box specified by id

        Keyword arguments:
        sdb_id -- this is the id of the safe deposit box, not the path."""
        sdb_resp = delete_with_retry(self.cerberus_url + '/v2/safe-deposit-box/' + sdb_id,
                                   headers=self.HEADERS)
        throw_if_bad_response(sdb_resp)
        return sdb_resp


Instruction:
How would you explain what the following Python 3 function does
def get_sdb_path(self, sdb):
        sdb_id = self.get_sdb_id(sdb)
        sdb_resp = get_with_retry(
            self.cerberus_url + '/v1/safe-deposit-box/' + sdb_id + '/',
            headers=self.HEADERS
        )

        throw_if_bad_response(sdb_resp)

        return sdb_resp.json()['path']

Response: Return the path for a SDB


Instruction:
Write a Python 3 function for
returning the keys for a SDB which are need for the full secure data path

Response:
def get_sdb_keys(self, path):
        """Return the keys for a SDB, which are need for the full secure data path"""
        list_resp = get_with_retry(
            self.cerberus_url + '/v1/secret/' + path + '/?list=true',
            headers=self.HEADERS
        )

        throw_if_bad_response(list_resp)

        return list_resp.json()['data']['keys']


Instruction:
Write a Python 3 script to
return the ID for the given safe deposit box.

Response:
def get_sdb_id(self, sdb):
        """ Return the ID for the given safe deposit box.

        Keyword arguments:
        sdb -- This is the name of the safe deposit box, not the path"""
        json_resp = self.get_sdbs()
        for r in json_resp:
            if r['name'] == sdb:
                return str(r['id'])

        # If we haven't returned yet then we didn't find what we were
        # looking for.
        raise CerberusClientException("'%s' not found" % sdb)


Instruction:
How would you implement a function in Python 3 that
gives the path return the ID for the given safe deposit box.

Response:
def get_sdb_id_by_path(self, sdb_path):
        """ Given the path, return the ID for the given safe deposit box."""
        json_resp = self.get_sdbs()

        # Deal with the supplied path possibly missing an ending slash
        path = self._add_slash(sdb_path)

        for r in json_resp:
            if r['path'] == path:
                return str(r['id'])

        # If we haven't returned yet then we didn't find what we were
        # looking for.
        raise CerberusClientException("'%s' not found" % sdb_path)


Instruction:
Write a Python 3 script for
getting the details for a given safe deposit box id

Response:
def get_sdb_by_id(self, sdb_id):
        """ Return the details for the given safe deposit box id

        Keyword arguments:
        sdb_id -- this is the id of the safe deposit box, not the path.
        """
        sdb_resp = get_with_retry(self.cerberus_url + '/v2/safe-deposit-box/' + sdb_id,
                                headers=self.HEADERS)

        throw_if_bad_response(sdb_resp)

        return sdb_resp.json()


Instruction:
Make a summary of the following Python 3 code
def get_sdb_secret_version_paths(self, sdb_id):
        sdb_resp = get_with_retry(str.join('', [self.cerberus_url, '/v1/sdb-secret-version-paths/', sdb_id]),
                                headers=self.HEADERS)

        throw_if_bad_response(sdb_resp)

        return sdb_resp.json()

Response: This function returns the SDB secret version paths. This function takes the sdb_id and returns the JSON object.


Instruction:
Can you tell what is the following Python 3 function doing
def list_sdbs(self):
        sdb_raw = self.get_sdbs()
        sdbs = []
        for s in sdb_raw:
            sdbs.append(s['name'])

        return sdbs

Response: Return a list of all sdbs by Name


Instruction:
Can you implement a function in Python 3 that
updates a safe deposit box.

Response:
def update_sdb(self, sdb_id, owner=None, description=None, user_group_permissions=None,
                   iam_principal_permissions=None):
        """
        Update a safe deposit box.

        Keyword arguments:

            owner (string) -- AD group that owns the safe deposit box
            description (string) -- Description of the safe deposit box
            user_group_permissions (list) -- list of dictionaries containing the key name and maybe role_id
            iam_principal_permissions (list) -- list of dictionaries containing the key name iam_principal_arn
            and role_id
        """
        # Grab current data
        old_data = self.get_sdb_by_id(sdb_id)

        # Assemble information to update
        temp_data = {}
        keys = ('owner', 'description', 'iam_principal_permissions', 'user_group_permissions')
        for k in keys:
            if k in old_data:
                temp_data[k] = old_data[k]
        if owner is not None:
            temp_data["owner"] = owner
        if description is not None:
            temp_data["description"] = description
        if user_group_permissions is not None and len(user_group_permissions) > 0:
            temp_data["user_group_permissions"] = user_group_permissions
        if iam_principal_permissions is not None and len(iam_principal_permissions) > 0:
            temp_data["iam_principal_permissions"] = iam_principal_permissions

        data = json.encoder.JSONEncoder().encode(temp_data)
        sdb_resp = put_with_retry(self.cerberus_url + '/v2/safe-deposit-box/' + sdb_id, data=str(data),
                                headers=self.HEADERS)

        throw_if_bad_response(sdb_resp)
        return sdb_resp.json()


Instruction:
Can you create a Python 3 function that
deletes a file at the given secure data path

Response:
def delete_file(self, secure_data_path):
        """Delete a file at the given secure data path"""
        secret_resp = delete_with_retry(self.cerberus_url + '/v1/secure-file/' + secure_data_path,
                                      headers=self.HEADERS)
        throw_if_bad_response(secret_resp)
        return secret_resp


Instruction:
Make a summary of the following Python 3 code
def get_file_metadata(self, secure_data_path, version=None):
        if not version:
            version = "CURRENT"

        payload = {'versionId': str(version)}
        secret_resp = head_with_retry(str.join('', [self.cerberus_url, '/v1/secure-file/', secure_data_path]),
                                    params=payload, headers=self.HEADERS)

        throw_if_bad_response(secret_resp)

        return secret_resp.headers

Response: Get just the metadata for a file


Instruction:
How would you implement a function in Python 3 that
parses the header metadata to pull out the filename and store it under the key filename.

Response:
def _parse_metadata_filename(self, metadata):
        """
        Parse the header metadata to pull out the filename and then store it under the key 'filename'
        """
        index = metadata['Content-Disposition'].index('=')+1
        metadata['filename'] = metadata['Content-Disposition'][index:].replace('"', '')
        return metadata


Instruction:
Write a Python 3 function for
getting a file and the metadata and header information around it.

Response:
def get_file(self, secure_data_path, version=None):
        """
        Return a requests.structures.CaseInsensitiveDict object containing a file and the
        metadata/header information around it.

        The binary data of the file is under the key 'data'
        """

        query = self._get_file(secure_data_path, version)
        resp = query.headers.copy()
        resp = self._parse_metadata_filename(resp)
        resp['data'] = query.content

        return resp


Instruction:
Write a Python 3 function for
getting the versions of a particular file in the safety deposit box

Response:
def get_file_versions(self, secure_data_path, limit=None, offset=None):
        """
        Get versions of a particular file
        This is just a shim to get_secret_versions

        secure_data_path -- full path to the file in the safety deposit box
        limit -- Default(100), limits how many records to be returned from the api at once.
        offset -- Default(0), used for pagination.  Will request records from the given offset.
        """

        return self.get_secret_versions(secure_data_path, limit, offset)


Instruction:
Given the following Python 3 function, write the documentation
def _get_all_file_version_ids(self, secure_data_path, limit=None):

        offset = 0
        # Prime the versions dictionary so that all the logic can happen in the loop
        versions = {'has_next': True, 'next_offset': 0}
        while (versions['has_next']):
            offset = versions['next_offset']
            versions = self.get_file_versions(secure_data_path, limit, offset)
            for summary in versions['secure_data_version_summaries']:
                yield summary

Response: Returns a generator that yields all the file version ids that are available for the file.


Instruction:
Given the following Python 3 function, write the documentation
def _get_all_file_versions(self, secure_data_path, limit=None):
        for secret in self._get_all_file_version_ids(secure_data_path, limit):
            yield {'secret': self.get_file_data(secure_data_path, version=secret['id']),
                   'version': secret}

Response: Returns a generator that yields all the file versions of the file and its version info


Instruction:
Can you implement a function in Python 3 that
returns the list of files in the path.

Response:
def list_files(self, secure_data_path, limit=None, offset=None):
        """Return the list of files in the path.  May need to be paginated"""

        # Make sure that limit and offset are in range.
        # Set the normal defaults
        if not limit or limit <= 0:
            limit = 100

        if not offset or offset < 0:
            offset = 0

        payload = {'limit': str(limit), 'offset': str(offset)}

        # Because of the addition of versionId and the way URLs are constructed, secure_data_path should
        #  always end in a '/'.
        secure_data_path = self._add_slash(secure_data_path)
        secret_resp = get_with_retry(self.cerberus_url + '/v1/secure-files/' + secure_data_path,
                                   params=payload, headers=self.HEADERS)
        throw_if_bad_response(secret_resp)
        return secret_resp.json()


Instruction:
Here you have a function in Python 3, explain what it does
def put_file(self, secure_data_path, filehandle, content_type=None):

        # Parse out the filename from the path
        filename = secure_data_path.rsplit('/', 1)

        if content_type:
            data = {'file-content': (filename, filehandle, content_type)}
        else:
            data = {'file-content': (filename, filehandle)}

        headers = self.HEADERS.copy()
        if 'Content-Type' in headers:
            headers.__delitem__('Content-Type')

        secret_resp = post_with_retry(self.cerberus_url + '/v1/secure-file/' + secure_data_path,
                                    files=data, headers=headers)
        throw_if_bad_response(secret_resp)
        return secret_resp

Response: This method uploads a file to a secure data path


Instruction:
Can you generate the documentation for the following Python 3 function
def get_secret(self, secure_data_path, key, version=None):
        warnings.warn(
            "get_secret is deprecated, use get_secrets_data instead",
            DeprecationWarning
        )
        secret_resp_json = self._get_secrets(secure_data_path, version)

        if key in secret_resp_json['data']:
            return secret_resp_json['data'][key]
        else:
            raise CerberusClientException("Key '%s' not found" % key)

Response: Get a secret from the Cerberus server


Instruction:
Can you generate the documentation for the following Python 3 function
def _get_secrets(self, secure_data_path, version=None):
        if not version:
            version = "CURRENT"
        payload = {'versionId': str(version)}
        secret_resp = get_with_retry(str.join('', [self.cerberus_url, '/v1/secret/', secure_data_path]),
                                   params=payload, headers=self.HEADERS)

        throw_if_bad_response(secret_resp)

        return secret_resp.json()

Response: Returns full json secrets based on the secure data path


Instruction:
Can you generate the documentation for the following Python 3 function
def get_secrets(self, secure_data_path, version=None):
        warnings.warn(
            "get_secrets is deprecated, use get_secrets_data instead",
            DeprecationWarning
        )
        return self._get_secrets(secure_data_path, version)

Response: Deprecated method to get json secrets based on the secure data path


Instruction:
How would you implement a function in Python 3 that
gets versions of a particular secret key.

Response:
def get_secret_versions(self, secure_data_path, limit=None, offset=None):
        """
        Get versions of a particular secret key

        secure_data_path -- full path to the key in the safety deposit box
        limit -- Default(100), limits how many records to be returned from the api at once.
        offset -- Default(0), used for pagination.  Will request records from the given offset.
        """

        # Make sure that limit and offset are in range.
        # Set the normal defaults
        if not limit or limit <= 0:
            limit = 100

        if not offset or offset < 0:
            offset = 0

        payload = {'limit': str(limit), 'offset': str(offset)}
        secret_resp = get_with_retry(str.join('', [self.cerberus_url, '/v1/secret-versions/', secure_data_path]),
                                   params=payload, headers=self.HEADERS)
        throw_if_bad_response(secret_resp)
        return secret_resp.json()


Instruction:
Can you generate the documentation for the following Python 3 function
def _get_all_secret_version_ids(self, secure_data_path, limit=None):

        offset = 0
        # Prime the versions dictionary so that all the logic can happen in the loop
        versions = {'has_next': True, 'next_offset': 0}
        while (versions['has_next']):
            offset = versions['next_offset']
            versions = self.get_secret_versions(secure_data_path, limit, offset)
            for summary in versions['secure_data_version_summaries']:
                yield summary

Response: Returns a generator that returns all the secret version ids that are available for the given secure data path.


Instruction:
Write a Python 3 script to
return a generator that yields all the secrets and their versions

Response:
def _get_all_secret_versions(self, secure_data_path, limit=None):
        """
        Convenience function that returns a generator yielding the contents of secrets and their version info
        secure_data_path -- full path to the key in the safety deposit box
        limit -- Default(100), limits how many records to be returned from the api at once.
        """
        for secret in self._get_all_secret_version_ids(secure_data_path, limit):
            yield {'secret': self.get_secrets_data(secure_data_path, version=secret['id']),
                   'version': secret}


Instruction:
Write a Python 3 script to
return json secrets based on the secure_data_path

Response:
def list_secrets(self, secure_data_path):
        """Return json secrets based on the secure_data_path, this will list keys in a folder"""

        # Because of the addition of versionId and the way URLs are constructed, secure_data_path should
        #  always end in a '/'.
        secure_data_path = self._add_slash(secure_data_path)
        secret_resp = get_with_retry(self.cerberus_url + '/v1/secret/' + secure_data_path + '?list=true',
                                   headers=self.HEADERS)
        throw_if_bad_response(secret_resp)
        return secret_resp.json()


Instruction:
Implement a function in Python 3 to
write secret to a secure data path

Response:
def put_secret(self, secure_data_path, secret, merge=True):
        """Write secret(s) to a secure data path provided a dictionary of key/values

        Keyword arguments:
        secure_data_path -- full path in the safety deposit box that contains the key
        secret -- A dictionary containing key/values to be written at the secure data path
        merge -- Boolean that determines if the provided secret keys should be merged with
            the values already present at the secure data path.  If False the keys will
            completely overwrite what was stored at the secure data path. (default True)
        """
        # json encode the input.  Cerberus is sensitive to double vs single quotes.
        # an added bonus is that json encoding transforms python2 unicode strings
        # into a compatible format.
        data = json.encoder.JSONEncoder().encode(secret)
        if merge:
            data = self.secret_merge(secure_data_path, secret)
        secret_resp = post_with_retry(self.cerberus_url + '/v1/secret/' + secure_data_path,
                                    data=str(data), headers=self.HEADERS)
        throw_if_bad_response(secret_resp)
        return secret_resp


Instruction:
Make a summary of the following Python 3 code
def secret_merge(self, secure_data_path, key):
        get_resp = get_with_retry(self.cerberus_url + '/v1/secret/' + secure_data_path, headers=self.HEADERS)
        temp_key = {}
        # Ignore a return of 404 since it means the key might not exist
        if get_resp.status_code == requests.codes.bad and get_resp.status_code not in [403, 404]:
            throw_if_bad_response(get_resp)
        elif get_resp.status_code in [403, 404]:
            temp_key = {}
        else:
            temp_key = get_resp.json()['data']
        # Allow key to be either a string describing a dict or a dict.
        if type(key) == str:
            temp_key.update(ast.literal_eval(key))
        else:
            temp_key.update(key)
        # This is a bit of a hack to get around python 2 treating unicode strings
        # differently.  Cerberus will throw a 400 if we try to post python 2 style
        # unicode stings as the payload.
        combined_key = json.encoder.JSONEncoder().encode(temp_key)
        return combined_key

Response: Compare key and values at secure_data_path and merges them.


Instruction:
Here you have a function in Python 3, explain what it does
def _get_v4_signed_headers(self):
        if self.aws_session is None:
            boto_session = session.Session()
            creds = boto_session.get_credentials()
        else:
            creds = self.aws_session.get_credentials()
        if creds is None:
            raise CerberusClientException("Unable to locate AWS credentials")
        readonly_credentials = creds.get_frozen_credentials()

        # hardcode get-caller-identity request
        data = OrderedDict((('Action','GetCallerIdentity'), ('Version', '2011-06-15')))
        url = 'https://sts.{}.amazonaws.com/'.format(self.region)
        request_object = awsrequest.AWSRequest(method='POST', url=url, data=data)

        signer = auth.SigV4Auth(readonly_credentials, 'sts', self.region)
        signer.add_auth(request_object)
        return request_object.headers

Response: Returns V4 signed get - caller - identity request headers


Instruction:
Can you generate the documentation for the following Python 3 function
def get_token(self):
        signed_headers = self._get_v4_signed_headers()
        for header in self.HEADERS:
            signed_headers[header] = self.HEADERS[header]

        resp = post_with_retry(self.cerberus_url + '/v2/auth/sts-identity', headers=signed_headers)
        throw_if_bad_response(resp)

        token = resp.json()['client_token']
        iam_principal_arn = resp.json()['metadata']['aws_iam_principal_arn']
        if self.verbose:
            print('Successfully authenticated with Cerberus as {}'.format(iam_principal_arn), file=sys.stderr)
        logger.info('Successfully authenticated with Cerberus as {}'.format(iam_principal_arn))

        return token

Response: Returns a client token from Cerberus


Instruction:
Can you tell what is the following Python 3 function doing
def tiff_header(read_buffer):
    # First 8 should be (73, 73, 42, 8) or (77, 77, 42, 8)
    data = struct.unpack('BB', read_buffer[0:2])
    if data[0] == 73 and data[1] == 73:
        # little endian
        endian = '<'
    elif data[0] == 77 and data[1] == 77:
        # big endian
        endian = '>'
    else:
        msg = ("The byte order indication in the TIFF header ({byte_order}) "
               "is invalid.  It should be either {little_endian} or "
               "{big_endian}.")
        msg = msg.format(byte_order=read_buffer[6:8],
                         little_endian=bytes([73, 73]),
                         big_endian=bytes([77, 77]))
        raise IOError(msg)

    _, offset = struct.unpack(endian + 'HI', read_buffer[2:8])

    # This is the 'Exif Image' portion.
    exif = ExifImageIfd(endian, read_buffer, offset)
    return exif.processed_ifd

Response: Interpret the uuid raw data as a tiff header.


Instruction:
Implement a function in Python 3 to
interpret an Exif image tag data payload.

Response:
def parse_tag(self, dtype, count, offset_buf):
        """Interpret an Exif image tag data payload.
        """
        try:
            fmt = self.datatype2fmt[dtype][0] * count
            payload_size = self.datatype2fmt[dtype][1] * count
        except KeyError:
            msg = 'Invalid TIFF tag datatype ({0}).'.format(dtype)
            raise IOError(msg)

        if payload_size <= 4:
            # Interpret the payload from the 4 bytes in the tag entry.
            target_buffer = offset_buf[:payload_size]
        else:
            # Interpret the payload at the offset specified by the 4 bytes in
            # the tag entry.
            offset, = struct.unpack(self.endian + 'I', offset_buf)
            target_buffer = self.read_buffer[offset:offset + payload_size]

        if dtype == 2:
            # ASCII
            payload = target_buffer.decode('utf-8').rstrip('\x00')

        else:
            payload = struct.unpack(self.endian + fmt, target_buffer)
            if dtype == 5 or dtype == 10:
                # Rational or Signed Rational.  Construct the list of values.
                rational_payload = []
                for j in range(count):
                    value = float(payload[j * 2]) / float(payload[j * 2 + 1])
                    rational_payload.append(value)
                payload = rational_payload
            if count == 1:
                # If just a single value, then return a scalar instead of a
                # tuple.
                payload = payload[0]

        return payload


Instruction:
Write a Python 3 script to
map the tag name instead of tag number to the tag value.

Response:
def post_process(self, tagnum2name):
        """Map the tag name instead of tag number to the tag value.
        """
        for tag, value in self.raw_ifd.items():
            try:
                tag_name = tagnum2name[tag]
            except KeyError:
                # Ok, we don't recognize this tag.  Just use the numeric id.
                msg = 'Unrecognized Exif tag ({tag}).'.format(tag=tag)
                warnings.warn(msg, UserWarning)
                tag_name = tag
            self.processed_ifd[tag_name] = value


Instruction:
Make a summary of the following Python 3 code
def all(self):

        response = self._get_json(HTTPMethods.GET, self.saved_query_url, self._get_master_key())

        return response

Response: Gets all saved queries for a project from the Keen IO API.


Instruction:
How would you code a function in Python 3 to
get a single saved query for a project from the Keen IO API given a query name.

Response:
def get(self, query_name):
        """
        Gets a single saved query for a project from the Keen IO API given a
        query name.
        Master key must be set.
        """

        url = "{0}/{1}".format(self.saved_query_url, query_name)
        response = self._get_json(HTTPMethods.GET, url, self._get_master_key())

        return response


Instruction:
Create a Python 3 function for
getting a single saved query with a result object for a project given a query name.

Response:
def results(self, query_name):
        """
        Gets a single saved query with a 'result' object for a project from the
        Keen IO API given a query name.
        Read or Master key must be set.
        """

        url = "{0}/{1}/result".format(self.saved_query_url, query_name)
        response = self._get_json(HTTPMethods.GET, url, self._get_read_key())

        return response


Instruction:
Implement a function in Python 3 to
create a new Keen IO Saved Query.

Response:
def create(self, query_name, saved_query):
        """
        Creates the saved query via a PUT request to Keen IO Saved Query endpoint.
        Master key must be set.
        """
        url = "{0}/{1}".format(self.saved_query_url, query_name)
        payload = saved_query

        # To support clients that may have already called dumps() to work around how this used to
        # work, make sure it's not a str. Hopefully it's some sort of mapping. When we actually
        # try to send the request, client code will get an InvalidJSONError if payload isn't
        # a json-formatted string.
        if not isinstance(payload, str):
            payload = json.dumps(saved_query)

        response = self._get_json(HTTPMethods.PUT, url, self._get_master_key(), data=payload)

        return response


Instruction:
Make a summary of the following Python 3 code
def update(self, query_name, saved_query_attributes):

        query_name_attr_name = "query_name"
        refresh_rate_attr_name = "refresh_rate"
        query_attr_name = "query"
        metadata_attr_name = "metadata"

        old_saved_query = self.get(query_name)

        # Create a new query def to send back. We cannot send values for attributes like 'urls',
        # 'last_modified_date', 'run_information', etc.
        new_saved_query = {
            query_name_attr_name: old_saved_query[query_name_attr_name], # expected
            refresh_rate_attr_name: old_saved_query[refresh_rate_attr_name], # expected
            query_attr_name: {}
        }

        # If metadata was set, preserve it. The Explorer UI currently stores information here.
        old_metadata = (old_saved_query[metadata_attr_name]
                       if metadata_attr_name in old_saved_query
                       else None)

        if old_metadata:
            new_saved_query[metadata_attr_name] = old_metadata

        # Preserve any non-empty properties of the existing query. We get back values like None
        # for 'group_by', 'interval' or 'timezone', but those aren't accepted values when updating.
        old_query = old_saved_query[query_attr_name] # expected

        # Shallow copy since we want the entire object heirarchy to start with.
        for (key, value) in six.iteritems(old_query):
            if value:
                new_saved_query[query_attr_name][key] = value

        # Now, recursively overwrite any attributes passed in.
        SavedQueriesInterface._deep_update(new_saved_query, saved_query_attributes)

        return self.create(query_name, new_saved_query)

Response: Updates the attributes of the specified query_name with the values from the given dict of attributes to be updated.


Instruction:
Write a Python 3 script to
delete a saved query from a project with a query name.

Response:
def delete(self, query_name):
        """
        Deletes a saved query from a project with a query name.
        Master key must be set.
        """

        url = "{0}/{1}".format(self.saved_query_url, query_name)
        self._get_json(HTTPMethods.DELETE, url, self._get_master_key())

        return True


Instruction:
Implement a function in Python 3 to
pad an input string to a given block size.

Response:
def pad_aes256(s):
    """
    Pads an input string to a given block size.
    :param s: string
    :returns: The padded string.
    """
    if len(s) % AES.block_size == 0:
        return s

    return Padding.appendPadding(s, blocksize=AES.block_size)


Instruction:
How would you explain what the following Python 3 function does
def unpad_aes256(s):
    if not s:
        return s

    try:
        return Padding.removePadding(s, blocksize=AES.block_size)
    except AssertionError:
        # if there's an error while removing padding, just return s.
        return s

Response: Removes padding from an input string based on a given block size.


Instruction:
Can you generate the documentation for the following Python 3 function
def old_pad(s):
    if len(s) % OLD_BLOCK_SIZE == 0:
        return s

    return Padding.appendPadding(s, blocksize=OLD_BLOCK_SIZE)

Response: Pads an input string to a given block size.


Instruction:
Explain what the following Python 3 code does
def old_unpad(s):
    if not s:
        return s

    try:
        return Padding.removePadding(s, blocksize=OLD_BLOCK_SIZE)
    except AssertionError:
        # if there's an error while removing padding, just return s.
        return s

Response: Removes padding from an input string based on a given block size.


Instruction:
Given the following Python 3 function, write the documentation
def encode_aes256(key, plaintext):
    if len(key) != 64:
        raise TypeError("encode_aes256() expects a 256 bit key encoded as a 64 hex character string")

    # generate AES.block_size cryptographically secure random bytes for our IV (initial value)
    iv = os.urandom(AES.block_size)
    # set up an AES cipher object
    cipher = AES.new(binascii.unhexlify(key.encode('ascii')), mode=AES.MODE_CBC, IV=iv)
    # encrypt the plaintext after padding it
    ciphertext = cipher.encrypt(ensure_bytes(pad_aes256(plaintext)))
    # append the hexed IV and the hexed ciphertext
    iv_plus_encrypted = binascii.hexlify(iv) + binascii.hexlify(ciphertext)
    # return that
    return iv_plus_encrypted

Response: This function encodes some given plaintext with the given key and returns the ciphertext of the ciphertext.


Instruction:
Explain what the following Python 3 code does
def old_encode_aes(key, plaintext):
    # generate 16 cryptographically secure random bytes for our IV (initial value)
    iv = os.urandom(16)
    # set up an AES cipher object
    cipher = AES.new(ensure_bytes(old_pad(key)), mode=AES.MODE_CBC, IV=iv)
    # encrypte the plaintext after padding it
    ciphertext = cipher.encrypt(ensure_bytes(old_pad(plaintext)))
    # append the hexed IV and the hexed ciphertext
    iv_plus_encrypted = binascii.hexlify(iv) + binascii.hexlify(ciphertext)
    # return that
    return iv_plus_encrypted

Response: This method encrypts some given plaintext with the given key and returns the ciphertext of the encrypted plaintext.


Instruction:
Explain what the following Python 3 code does
def old_decode_aes(key, iv_plus_encrypted):
    # grab first 16 bytes (aka 32 characters of hex) - that's the IV
    hexed_iv = iv_plus_encrypted[:32]
    # grab everything else - that's the ciphertext (aka encrypted message)
    hexed_ciphertext = iv_plus_encrypted[32:]
    # unhex the iv and ciphertext
    iv = binascii.unhexlify(hexed_iv)
    ciphertext = binascii.unhexlify(hexed_ciphertext)
    # set up the correct AES cipher object
    cipher = AES.new(ensure_bytes(old_pad(key)), mode=AES.MODE_CBC, IV=iv)
    # decrypt!
    plaintext = cipher.decrypt(ciphertext)
    # return the unpadded version of this
    return old_unpad(plaintext)

Response: Utility method to decode a payload consisting of the hexed IV + the hexed ciphertext using the given key.


Instruction:
Can you implement a function in Python 3 that
returns auth response which has client token unless MFA is required

Response:
def get_auth(self):
        """Returns auth response which has client token unless MFA is required"""
        auth_resp = get_with_retry(self.cerberus_url + '/v2/auth/user',
                                 auth=(self.username, self.password),
                                 headers=self.HEADERS)

        if auth_resp.status_code != 200:
            throw_if_bad_response(auth_resp)

        return auth_resp.json()


Instruction:
Given the following Python 3 function, write the documentation
def get_token(self):
        auth_resp = self.get_auth()

        if auth_resp['status'] == 'mfa_req':
            token_resp = self.get_mfa(auth_resp)
        else:
            token_resp = auth_resp

        token = token_resp['data']['client_token']['client_token']
        return token

Response: sets client token from Cerberus


Instruction:
Can you generate the documentation for the following Python 3 function
def get_mfa(self, auth_resp):
        devices = auth_resp['data']['devices']
        if len(devices) == 1:
            # If there's only one option, don't show selection prompt
            selection = "0"
            x = 1
        else:
            print("Found the following MFA devices")
            x=0
            for device in devices:
                print("{0}: {1}".format(x, device['name']))
                x = x + 1

            selection = input("Enter a selection: ")
        if selection.isdigit():
            selection_num=int(str(selection))
        else:
            raise CerberusClientException( str.join('', ["Selection: '", selection,"' is not a number"]))

        if (selection_num >= x) or (selection_num < 0):
            raise CerberusClientException(str.join('', ["Selection: '", str(selection_num), "' is out of range"]))

        sec_code = input('Enter ' + auth_resp['data']['devices'][selection_num]['name'] + ' security code: ')

        mfa_resp = post_with_retry(
            self.cerberus_url + '/v2/auth/mfa_check',
            json={'otp_token': sec_code,
                  'device_id': auth_resp['data']['devices'][selection_num]['id'],
                  'state_token': auth_resp['data']['state_token']},
            headers=self.HEADERS
        )

        if mfa_resp.status_code != 200:
            throw_if_bad_response(mfa_resp)

        return mfa_resp.json()

Response: Gets MFA code from user and returns response which includes the client token


Instruction:
Explain what the following Python 3 code does
def _parse_standard_flag(read_buffer, mask_length):
    # The mask length tells us the format string to use when unpacking
    # from the buffer read from file.
    mask_format = {1: 'B', 2: 'H', 4: 'I'}[mask_length]

    num_standard_flags, = struct.unpack_from('>H', read_buffer, offset=0)

    # Read in standard flags and standard masks.  Each standard flag should
    # be two bytes, but the standard mask flag is as long as specified by
    # the mask length.
    fmt = '>' + ('H' + mask_format) * num_standard_flags
    data = struct.unpack_from(fmt, read_buffer, offset=2)

    standard_flag = data[0:num_standard_flags * 2:2]
    standard_mask = data[1:num_standard_flags * 2:2]

    return standard_flag, standard_mask

Response: Construct standard flag and standard mask data from the file.


Instruction:
Can you implement a function in Python 3 that
constructs vendor features and vendor mask data from the buffer.

Response:
def _parse_vendor_features(read_buffer, mask_length):
    """Construct vendor features, vendor mask data from the file.

    Specifically working on Reader Requirements box.

    Parameters
    ----------
    fptr : file object
        File object for JP2K file.
    mask_length : int
        Length of vendor mask flag
    """
    # The mask length tells us the format string to use when unpacking
    # from the buffer read from file.
    mask_format = {1: 'B', 2: 'H', 4: 'I'}[mask_length]

    num_vendor_features, = struct.unpack_from('>H', read_buffer)

    # Each vendor feature consists of a 16-byte UUID plus a mask whose
    # length is specified by, you guessed it, "mask_length".
    entry_length = 16 + mask_length
    vendor_feature = []
    vendor_mask = []
    for j in range(num_vendor_features):
        uslice = slice(2 + j * entry_length, 2 + (j + 1) * entry_length)
        ubuffer = read_buffer[uslice]
        vendor_feature.append(UUID(bytes=ubuffer[0:16]))

        vmask = struct.unpack('>' + mask_format, ubuffer[16:])
        vendor_mask.append(vmask)

    return vendor_feature, vendor_mask


Instruction:
Here you have a function in Python 3, explain what it does
def _dispatch_validation_error(self, msg, writing=False):
        if writing:
            raise IOError(msg)
        else:
            warnings.warn(msg)

Response: Dispatches a validation error depending on circumstance.


Instruction:
Given the following Python 3 function, write the documentation
def _indent(self, textstr, indent_level=4):
        if sys.hexversion >= 0x03030000:
            return textwrap.indent(textstr, ' ' * indent_level)
        else:
            lst = [(' ' * indent_level + x) for x in textstr.split('\n')]
            return '\n'.join(lst)

Response:
Indent a string.

        Textwrap's indent method only exists for 3.3 or above.  In 2.7 we have
        to fake it.

        Parameters
        ----------
        textstring : str
            String to be indented.
        indent_level : str
            Number of spaces of indentation to add.

        Returns
        -------
        str
            Possibly multi-line string indented by the specified amount.


Instruction:
Create a Python 3 function for
writing a superbox. Parameters ---------- fptr : file or file object Superbox (box of boxes) to be written to this file. box_id : bytes 4-byte sequence that identifies the superbox.

Response:
def _write_superbox(self, fptr, box_id):
        """Write a superbox.

        Parameters
        ----------
        fptr : file or file object
            Superbox (box of boxes) to be written to this file.
        box_id : bytes
            4-byte sequence that identifies the superbox.
        """
        # Write the contained boxes, then come back and write the length.
        orig_pos = fptr.tell()
        fptr.write(struct.pack('>I4s', 0, box_id))
        for box in self.box:
            box.write(fptr)

        end_pos = fptr.tell()
        fptr.seek(orig_pos)
        fptr.write(struct.pack('>I', end_pos - orig_pos))
        fptr.seek(end_pos)


Instruction:
Implement a Python 3 function for
parsing the current box.

Response:
def _parse_this_box(self, fptr, box_id, start, num_bytes):
        """Parse the current box.

        Parameters
        ----------
        fptr : file
            Open file object, currently points to start of box payload, not the
            start of the box.
        box_id : str
            4-letter identifier for the current box.
        start, num_bytes : int
            Byte offset and length of the current box.

        Returns
        -------
        Jp2kBox
            Object corresponding to the current box.
        """
        try:
            parser = _BOX_WITH_ID[box_id].parse

        except KeyError:
            # We don't recognize the box ID, so create an UnknownBox and be
            # done with it.
            msg = ('Unrecognized box ({box_id}) encountered at byte offset '
                   '{offset}.')
            msg = msg.format(box_id=box_id, offset=fptr.tell() - 8)
            warnings.warn(msg, UserWarning)
            box = UnknownBox(box_id, offset=start, length=num_bytes,
                             longname='Unknown')

            return box

        try:
            box = parser(fptr, start, num_bytes)
        except ValueError as err:
            msg = ("Encountered an unrecoverable ValueError while parsing a "
                   "{box_id} box at byte offset {offset}.  The original error "
                   "message was \"{original_error_message}\".")
            msg = msg.format(box_id=_BOX_WITH_ID[box_id].longname,
                             offset=start,
                             original_error_message=str(err))
            warnings.warn(msg, UserWarning)
            box = UnknownBox(box_id.decode('utf-8'),
                             length=num_bytes,
                             offset=start, longname='Unknown')

        return box


Instruction:
Make a summary of the following Python 3 code
def parse_superbox(self, fptr):

        superbox = []

        start = fptr.tell()

        while True:

            # Are we at the end of the superbox?
            if start >= self.offset + self.length:
                break

            read_buffer = fptr.read(8)
            if len(read_buffer) < 8:
                msg = "Extra bytes at end of file ignored."
                warnings.warn(msg, UserWarning)
                return superbox

            (box_length, box_id) = struct.unpack('>I4s', read_buffer)
            if box_length == 0:
                # The length of the box is presumed to last until the end of
                # the file.  Compute the effective length of the box.
                num_bytes = os.path.getsize(fptr.name) - fptr.tell() + 8

            elif box_length == 1:
                # The length of the box is in the XL field, a 64-bit value.
                read_buffer = fptr.read(8)
                num_bytes, = struct.unpack('>Q', read_buffer)

            else:
                # The box_length value really is the length of the box!
                num_bytes = box_length

            box = self._parse_this_box(fptr, box_id, start, num_bytes)

            superbox.append(box)

            # Position to the start of the next box.
            if num_bytes > self.length:
                # Length of the current box goes past the end of the
                # enclosing superbox.
                msg = '{0} box has incorrect box length ({1})'
                msg = msg.format(box_id, num_bytes)
                warnings.warn(msg)
            elif fptr.tell() > start + num_bytes:
                # The box must be invalid somehow, as the file pointer is
                # positioned past the end of the box.
                msg = ('{box_id} box may be invalid, the file pointer is '
                       'positioned {num_bytes} bytes past the end of the box.')
                msg = msg.format(box_id=box_id,
                                 num_bytes=fptr.tell() - (start + num_bytes))
                warnings.warn(msg, UserWarning)
            fptr.seek(start + num_bytes)

            start += num_bytes

        return superbox

Response:
Parse a superbox (box consisting of nothing but other boxes.

        Parameters
        ----------
        fptr : file
            Open file object.

        Returns
        -------
        list
            List of top-level boxes in the JPEG 2000 file.


Instruction:
Write a Python 3 function for
verifying that the box obeys the specifications.

Response:
def _validate(self, writing=False):
        """Verify that the box obeys the specifications."""
        if self.colorspace is not None and self.icc_profile is not None:
            msg = ("Colorspace and icc_profile cannot both be set when "
                   "creating a ColourSpecificationBox.")
            self._dispatch_validation_error(msg, writing=writing)

        if self.method not in _COLORSPACE_METHODS.keys():
            msg = "Invalid colorspace method value ({method})."
            msg = msg.format(method=self.method)
            if writing:
                raise IOError(msg)
            else:
                warnings.warn(msg, UserWarning)

        if self.approximation not in _APPROXIMATION_MEASURES.keys():
            msg = "Invalid colr approximation value ({approx})."
            msg = msg.format(approx=self.approximation)
            if not writing:
                # Don't bother to check this for the case of writing=True
                # because it's already handles in the wrapping code.
                warnings.warn(msg, UserWarning)


Instruction:
Here you have a function in Python 3, explain what it does
def _write_validate(self):
        if self.colorspace is None:
            msg = ("Writing colr boxes without enumerated "
                   "colorspaces is not supported at this time.")
            self._dispatch_validation_error(msg, writing=True)

        if self.icc_profile is None:
            if self.colorspace not in [SRGB, GREYSCALE, YCC]:
                msg = ("Colorspace should correspond to one of SRGB, "
                       "GREYSCALE, or YCC.")
                self._dispatch_validation_error(msg, writing=True)

        self._validate(writing=True)

Response:
In addition to constructor validation steps run validation steps
        for writing.


Instruction:
How would you explain what the following Python 3 function does
def write(self, fptr):
        self._write_validate()
        length = 15 if self.icc_profile is None else 11 + len(self.icc_profile)
        fptr.write(struct.pack('>I4s', length, b'colr'))

        read_buffer = struct.pack('>BBBI',
                                  self.method,
                                  self.precedence,
                                  self.approximation,
                                  self.colorspace)
        fptr.write(read_buffer)

Response: Write an Colour Specification box to file.


Instruction:
Make a summary of the following Python 3 code
def parse(cls, fptr, offset, length):
        num_bytes = offset + length - fptr.tell()
        read_buffer = fptr.read(num_bytes)

        lst = struct.unpack_from('>BBB', read_buffer, offset=0)
        method, precedence, approximation = lst

        if method == 1:
            # enumerated colour space
            colorspace, = struct.unpack_from('>I', read_buffer, offset=3)
            if colorspace not in _COLORSPACE_MAP_DISPLAY.keys():
                msg = "Unrecognized colorspace ({colorspace})."
                msg = msg.format(colorspace=colorspace)
                warnings.warn(msg, UserWarning)
            icc_profile = None

        else:
            # ICC profile
            colorspace = None
            if (num_bytes - 3) < 128:
                msg = ("ICC profile header is corrupt, length is "
                       "only {length} when it should be at least 128.")
                warnings.warn(msg.format(length=num_bytes - 3), UserWarning)
                icc_profile = None
            else:
                profile = _ICCProfile(read_buffer[3:])
                icc_profile = profile.header

        return cls(method=method,
                   precedence=precedence,
                   approximation=approximation,
                   colorspace=colorspace,
                   icc_profile=icc_profile,
                   length=length,
                   offset=offset)

Response: Parse the JPEG 2000 color specification box.


Instruction:
How would you explain what the following Python 3 function does
def _validate(self, writing=False):
        # channel type and association must be specified.
        if not ((len(self.index) == len(self.channel_type)) and
                (len(self.channel_type) == len(self.association))):
            msg = ("The length of the index ({index}), channel_type "
                   "({channel_type}), and association ({association}) inputs "
                   "must be the same.")
            msg = msg.format(index=len(self.index),
                             channel_type=len(self.channel_type),
                             association=len(self.association))
            self._dispatch_validation_error(msg, writing=writing)

        # channel types must be one of 0, 1, 2, 65535
        if any(x not in [0, 1, 2, 65535] for x in self.channel_type):
            msg = ("channel_type specified as {channel_type}, but all values "
                   "must be in the set of\n\n"
                   "    0     - colour image data for associated color\n"
                   "    1     - opacity\n"
                   "    2     - premultiplied opacity\n"
                   "    65535 - unspecified\n")
            msg = msg.format(channel_type=self.channel_type)
            self._dispatch_validation_error(msg, writing=writing)

Response: Verify that the box obeys the specifications.


Instruction:
Explain what the following Python 3 code does
def write(self, fptr):
        self._validate(writing=True)
        num_components = len(self.association)
        fptr.write(struct.pack('>I4s', 8 + 2 + num_components * 6, b'cdef'))
        fptr.write(struct.pack('>H', num_components))
        for j in range(num_components):
            fptr.write(struct.pack('>' + 'H' * 3,
                                   self.index[j],
                                   self.channel_type[j],
                                   self.association[j]))

Response: Write a channel definition box to file.


Instruction:
How would you explain what the following Python 3 function does
def parse(cls, fptr, offset, length):
        num_bytes = offset + length - fptr.tell()
        read_buffer = fptr.read(num_bytes)

        # Read the number of components.
        num_components, = struct.unpack_from('>H', read_buffer)

        data = struct.unpack_from('>' + 'HHH' * num_components, read_buffer,
                                  offset=2)
        index = data[0:num_components * 6:3]
        channel_type = data[1:num_components * 6:3]
        association = data[2:num_components * 6:3]

        return cls(index=tuple(index),
                   channel_type=tuple(channel_type),
                   association=tuple(association),
                   length=length, offset=offset)

Response:
Parse the ComponentDefinitionBox
            box.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def _validate(self, writing=True):
        if any([box.box_id != 'colr' for box in self.box]):
            msg = ("Colour group boxes can only contain colour specification "
                   "boxes.")
            self._dispatch_validation_error(msg, writing=writing)

Response: Verify that the box obeys the specifications.


Instruction:
Write a Python 3 script to
write a colour group box to file.

Response:
def write(self, fptr):
        """Write a colour group box to file.
        """
        self._validate(writing=True)
        self._write_superbox(fptr, b'cgrp')


Instruction:
Make a summary of the following Python 3 code
def write(self, fptr):
        length = 8 + 4 * len(self.component_index)
        write_buffer = struct.pack('>I4s', length, b'cmap')
        fptr.write(write_buffer)

        for j in range(len(self.component_index)):
            write_buffer = struct.pack('>HBB',
                                       self.component_index[j],
                                       self.mapping_type[j],
                                       self.palette_index[j])
            fptr.write(write_buffer)

Response: Write a Component Mapping box to file.


Instruction:
Implement a Python 3 function for
parsing the ComponentMappingBox box.

Response:
def parse(cls, fptr, offset, length):
        """Parse component mapping box.

        Parameters
        ----------
        fptr : file
            Open file object.
        offset : int
            Start position of box in bytes.
        length : int
            Length of the box in bytes.

        Returns
        -------
        ComponentMappingBox
            Instance of the current component mapping box.
        """
        num_bytes = offset + length - fptr.tell()
        num_components = int(num_bytes / 4)

        read_buffer = fptr.read(num_bytes)
        data = struct.unpack('>' + 'HBB' * num_components, read_buffer)

        component_index = data[0:num_bytes:3]
        mapping_type = data[1:num_bytes:3]
        palette_index = data[2:num_bytes:3]

        return cls(component_index, mapping_type, palette_index,
                   length=length, offset=offset)


Instruction:
Given the following Python 3 function, write the documentation
def parse(cls, fptr, offset=0, length=0):
        main_header_offset = fptr.tell()
        if config.get_option('parse.full_codestream'):
            codestream = Codestream(fptr, length, header_only=False)
        else:
            codestream = None
        box = cls(codestream, main_header_offset=main_header_offset,
                  length=length, offset=offset)
        box._filename = fptr.name
        box._length = length
        return box

Response: Parse a contiguous codestream box.


Instruction:
Given the following Python 3 function, write the documentation
def _validate(self, writing=False):
        for box in self.DR:
            if box.box_id != 'url ':
                msg = ('Child boxes of a data reference box can only be data '
                       'entry URL boxes.')
                self._dispatch_validation_error(msg, writing=writing)

Response: Verify that the data reference box obeys the specifications.


Instruction:
Write a Python 3 function for
writing a Data Reference box to file.

Response:
def write(self, fptr):
        """Write a Data Reference box to file.
        """
        self._write_validate()

        # Very similar to the way a superbox is written.
        orig_pos = fptr.tell()
        fptr.write(struct.pack('>I4s', 0, b'dtbl'))

        # Write the number of data entry url boxes.
        write_buffer = struct.pack('>H', len(self.DR))
        fptr.write(write_buffer)

        for box in self.DR:
            box.write(fptr)

        end_pos = fptr.tell()
        fptr.seek(orig_pos)
        fptr.write(struct.pack('>I', end_pos - orig_pos))
        fptr.seek(end_pos)