Instruction:
Implement a function in Python 3 to
update the completion value for the specified record. Parameters: * user (django.contrib.auth.models.User): The user for whom the completion is being submitted. * course_key (opaque_keys.edx.keys.CourseKey): The course in which the submitted block is found. * block_key (opaque_keys.edx.keys.UsageKey): The block that has had its completion changed. * completion (float in range [0.0, 1.0]): The fractional completion value of the block (0.0 = incomplete, 1.0 = complete). Return Value: (BlockCompletion, bool): A tuple comprising the created or updated BlockCompletion object and a boolean value indicating whether the object was newly created by this call. Raises: ValueError: If the wrong type is passed for one of the parameters. django.core.exceptions.ValidationError: If a float is passed that is not between 0.0 and 1.0. django.db.DatabaseError: If there was a problem getting, creating, or updating the BlockCompletion record in the database. This will also be a more specific error, as described here: https://docs.djangoproject.com/en/1.11/ref/exceptions/#database-exceptions. IntegrityError and OperationalError are relatively common subclasses.

Response:
def submit_completion(self, user, course_key, block_key, completion):
        """
        Update the completion value for the specified record.

        Parameters:
            * user (django.contrib.auth.models.User): The user for whom the
              completion is being submitted.
            * course_key (opaque_keys.edx.keys.CourseKey): The course in
              which the submitted block is found.
            * block_key (opaque_keys.edx.keys.UsageKey): The block that has had
              its completion changed.
            * completion (float in range [0.0, 1.0]): The fractional completion
              value of the block (0.0 = incomplete, 1.0 = complete).

        Return Value:
            (BlockCompletion, bool): A tuple comprising the created or updated
            BlockCompletion object and a boolean value indicating whether the
            object was newly created by this call.

        Raises:

            ValueError:
                If the wrong type is passed for one of the parameters.

            django.core.exceptions.ValidationError:
                If a float is passed that is not between 0.0 and 1.0.

            django.db.DatabaseError:
                If there was a problem getting, creating, or updating the
                BlockCompletion record in the database.

                This will also be a more specific error, as described here:
                https://docs.djangoproject.com/en/1.11/ref/exceptions/#database-exceptions.
                IntegrityError and OperationalError are relatively common
                subclasses.
        """

        # Raise ValueError to match normal django semantics for wrong type of field.
        if not isinstance(course_key, CourseKey):
            raise ValueError(
                "course_key must be an instance of `opaque_keys.edx.keys.CourseKey`.  Got {}".format(type(course_key))
            )
        try:
            block_type = block_key.block_type
        except AttributeError:
            raise ValueError(
                "block_key must be an instance of `opaque_keys.edx.keys.UsageKey`.  Got {}".format(type(block_key))
            )
        if waffle.waffle().is_enabled(waffle.ENABLE_COMPLETION_TRACKING):
            try:
                with transaction.atomic():
                    obj, is_new = self.get_or_create(  # pylint: disable=unpacking-non-sequence
                        user=user,
                        course_key=course_key,
                        block_key=block_key,
                        defaults={
                            'completion': completion,
                            'block_type': block_type,
                        },
                    )
            except IntegrityError:
                # The completion was created concurrently by another process
                log.info(
                    "An IntegrityError was raised when trying to create a BlockCompletion for %s:%s:%s.  "
                    "Falling back to get().",
                    user,
                    course_key,
                    block_key,
                )
                obj = self.get(
                    user=user,
                    course_key=course_key,
                    block_key=block_key,
                )
                is_new = False
            if not is_new and obj.completion != completion:
                obj.completion = completion
                obj.full_clean()
                obj.save(update_fields={'completion', 'modified'})
        else:
            # If the feature is not enabled, this method should not be called.
            # Error out with a RuntimeError.
            raise RuntimeError(
                "BlockCompletion.objects.submit_completion should not be \
                called when the feature is disabled."
            )
        return obj, is_new


Instruction:
Write a Python 3 script to
submit a batch of completion objects for the given user and course.

Response:
def submit_batch_completion(self, user, course_key, blocks):
        """
        Performs a batch insertion of completion objects.

        Parameters:
            * user (django.contrib.auth.models.User): The user for whom the
              completions are being submitted.
            * course_key (opaque_keys.edx.keys.CourseKey): The course in
              which the submitted blocks are found.
            * blocks: A list of tuples of UsageKey to float completion values.
              (float in range [0.0, 1.0]): The fractional completion
              value of the block (0.0 = incomplete, 1.0 = complete).

        Return Value:
            Dict of (BlockCompletion, bool): A dictionary with a
            BlockCompletion object key and a value of bool. The boolean value
            indicates whether the object was newly created by this call.

        Raises:

            ValueError:
                If the wrong type is passed for one of the parameters.

            django.core.exceptions.ValidationError:
                If a float is passed that is not between 0.0 and 1.0.

            django.db.DatabaseError:
                If there was a problem getting, creating, or updating the
                BlockCompletion record in the database.
        """
        block_completions = {}
        for block, completion in blocks:
            (block_completion, is_new) = self.submit_completion(user, course_key, block, completion)
            block_completions[block_completion] = is_new
        return block_completions


Instruction:
Write a Python 3 function for
returning the full block key value with the run filled in.

Response:
def full_block_key(self):
        """
        Returns the "correct" usage key value with the run filled in.
        """
        if self.block_key.run is None:
            # pylint: disable=unexpected-keyword-arg, no-value-for-parameter
            return self.block_key.replace(course_key=self.course_key)
        return self.block_key


Instruction:
Can you generate a brief explanation for the following Python 3 code
def get_course_completions(cls, user, course_key):
        user_course_completions = cls.user_course_completion_queryset(user, course_key)
        return cls.completion_by_block_key(user_course_completions)

Response: Returns a dictionary mapping BlockKeys to completion values for the given user and course_key.


Instruction:
Can you implement a function in Python 3 that
returns a Queryset of completions for a given user and course_key.

Response:
def user_course_completion_queryset(cls, user, course_key):
        """
        Returns a Queryset of completions for a given user and course_key.
        """
        return cls.objects.filter(user=user, course_key=course_key)


Instruction:
Can you implement a function in Python 3 that
validates the batch object to make sure it is in the proper format.

Response:
def _validate_and_parse(self, batch_object):
        """
        Performs validation on the batch object to make sure it is in the proper format.

        Parameters:
            * batch_object: The data provided to a POST. The expected format is the following:
            {
                "username": "username",
                "course_key": "course-key",
                "blocks": {
                    "block_key1": 0.0,
                    "block_key2": 1.0,
                    "block_key3": 1.0,
                }
            }

        Return Value:
            * tuple: (User, CourseKey, List of tuples (UsageKey, completion_float)

        Raises:

            django.core.exceptions.ValidationError:
                If any aspect of validation fails a ValidationError is raised.

            ObjectDoesNotExist:
                If a database object cannot be found an ObjectDoesNotExist is raised.
        """
        if not waffle.waffle().is_enabled(waffle.ENABLE_COMPLETION_TRACKING):
            raise ValidationError(
                _("BlockCompletion.objects.submit_batch_completion should not be called when the feature is disabled.")
            )

        for key in self.REQUIRED_KEYS:
            if key not in batch_object:
                raise ValidationError(_("Key '{key}' not found.").format(key=key))

        username = batch_object['username']
        user = User.objects.get(username=username)

        course_key_obj = self._validate_and_parse_course_key(batch_object['course_key'])

        if not CourseEnrollment.is_enrolled(user, course_key_obj):
            raise ValidationError(_('User is not enrolled in course.'))

        blocks = batch_object['blocks']
        block_objs = []
        for block_key in blocks:
            block_key_obj = self._validate_and_parse_block_key(block_key, course_key_obj)
            completion = float(blocks[block_key])
            block_objs.append((block_key_obj, completion))

        return user, course_key_obj, block_objs


Instruction:
Given the following Python 3 function, write the documentation
def _validate_and_parse_course_key(self, course_key):
        try:
            return CourseKey.from_string(course_key)
        except InvalidKeyError:
            raise ValidationError(_("Invalid course key: {}").format(course_key))

Response: Validate and parse a course key.


Instruction:
How would you explain what the following Python 3 function does
def _validate_and_parse_block_key(self, block_key, course_key_obj):
        try:
            block_key_obj = UsageKey.from_string(block_key)
        except InvalidKeyError:
            raise ValidationError(_("Invalid block key: {}").format(block_key))

        if block_key_obj.run is None:
            expected_matching_course_key = course_key_obj.replace(run=None)
        else:
            expected_matching_course_key = course_key_obj

        if block_key_obj.course_key != expected_matching_course_key:
            raise ValidationError(
                _("Block with key: '{key}' is not in course {course}").format(key=block_key, course=course_key_obj)
            )

        return block_key_obj

Response: Validate and parse a given block key.


Instruction:
Given the following Python 3 function, write the documentation
def post(self, request, *args, **kwargs):  # pylint: disable=unused-argument
        batch_object = request.data or {}
        try:
            user, course_key, blocks = self._validate_and_parse(batch_object)
            BlockCompletion.objects.submit_batch_completion(user, course_key, blocks)
        except ValidationError as exc:
            return Response({
                "detail": _(' ').join(text_type(msg) for msg in exc.messages),
            }, status=status.HTTP_400_BAD_REQUEST)
        except ValueError as exc:
            return Response({
                "detail": text_type(exc),
            }, status=status.HTTP_400_BAD_REQUEST)
        except ObjectDoesNotExist as exc:
            return Response({
                "detail": text_type(exc),
            }, status=status.HTTP_404_NOT_FOUND)
        except DatabaseError as exc:
            return Response({
                "detail": text_type(exc),
            }, status=status.HTTP_500_INTERNAL_SERVER_ERROR)

        return Response({"detail": _("ok")}, status=status.HTTP_200_OK)

Response: A POST method that inserts a batch of completions.


Instruction:
Can you create a Python 3 function that
gets the completion for a user in a course.

Response:
def get(self, request, username, course_key, subsection_id):
        """
        Returns completion for a (user, subsection, course).
        """
        def get_completion(course_completions, all_blocks, block_id):
            """
            Recursively get the aggregate completion for a subsection,
            given the subsection block and a list of all blocks.

            Parameters:
                course_completions: a dictionary of completion values by block IDs
                all_blocks: a dictionary of the block structure for a subsection
                block_id: an ID of a block for which to get completion
            """
            block = all_blocks.get(block_id)
            child_ids = block.get('children', [])
            if not child_ids:
                return course_completions.get(block.serializer.instance, 0)

            completion = 0
            total_children = 0
            for child_id in child_ids:
                completion += get_completion(course_completions, all_blocks, child_id)
                total_children += 1

            return int(completion == total_children)

        user_id = User.objects.get(username=username).id
        block_types_filter = [
            'course',
            'chapter',
            'sequential',
            'vertical',
            'html',
            'problem',
            'video',
            'discussion',
            'drag-and-drop-v2'
        ]

        blocks = get_blocks(
            request,
            UsageKey.from_string(subsection_id),
            nav_depth=2,
            requested_fields=[
                'children'
            ],
            block_types_filter=block_types_filter
        )

        course_completions = BlockCompletion.get_course_completions(user_id, CourseKey.from_string(course_key))
        aggregated_completion = get_completion(course_completions, blocks['blocks'], blocks['root'])

        return Response({"completion": aggregated_completion}, status=status.HTTP_200_OK)


Instruction:
Can you generate the documentation for the following Python 3 function
def get_completions(self, candidates):
        queryset = BlockCompletion.user_course_completion_queryset(self._user, self._course_key).filter(
            block_key__in=candidates
        )
        completions = BlockCompletion.completion_by_block_key(queryset)
        candidates_with_runs = [candidate.replace(course_key=self._course_key) for candidate in candidates]
        for candidate in candidates_with_runs:
            if candidate not in completions:
                completions[candidate] = 0.0
        return completions

Response: Returns a dictionary mapping of the block keys to the present completion values of the associated blocks.


Instruction:
Explain what the following Python 3 code does
def vertical_is_complete(self, item):
        if item.location.block_type != 'vertical':
            raise ValueError('The passed in xblock is not a vertical type!')

        if not self.completion_tracking_enabled():
            return None

        # this is temporary local logic and will be removed when the whole course tree is included in completion
        child_locations = [
            child.location for child in item.get_children() if child.location.block_type != 'discussion'
        ]
        completions = self.get_completions(child_locations)
        for child_location in child_locations:
            if completions[child_location] < 1.0:
                return False
        return True

Response: Calculates and returns whether a particular vertical is complete.


Instruction:
Make a summary of the following Python 3 code
def can_mark_block_complete_on_view(self, block):
        return (
            XBlockCompletionMode.get_mode(block) == XBlockCompletionMode.COMPLETABLE
            and not getattr(block, 'has_custom_completion', False)
            and not getattr(block, 'has_score', False)
        )

Response: Returns True if the xblock can be marked complete on view.


Instruction:
Make a summary of the following Python 3 code
def blocks_to_mark_complete_on_view(self, blocks):
        blocks = {block for block in blocks if self.can_mark_block_complete_on_view(block)}
        completions = self.get_completions({block.location for block in blocks})
        return {block for block in blocks if completions.get(block.location, 0) < 1.0}

Response: Returns a set of blocks which should be marked complete on view and haven t yet been marked.


Instruction:
Create a Python 3 function to
submit a completion for a group of users.

Response:
def submit_group_completion(self, block_key, completion, users=None, user_ids=None):
        """
        Submit a completion for a group of users.

        Arguments:

            block_key (opaque_key.edx.keys.UsageKey): The block to submit completions for.
            completion (float): A value in the range [0.0, 1.0]
            users ([django.contrib.auth.models.User]): An optional iterable of Users that completed the block.
            user_ids ([int]): An optional iterable of ids of Users that completed the block.

        Returns a list of (BlockCompletion, bool) where the boolean indicates
        whether the given BlockCompletion was newly created.
        """
        if users is None:
            users = []
        if user_ids is None:
            user_ids = []
        more_users = User.objects.filter(id__in=user_ids)
        if len(more_users) < len(user_ids):
            found_ids = {u.id for u in more_users}
            not_found_ids = [pk for pk in user_ids if pk not in found_ids]
            raise User.DoesNotExist("User not found with id(s): {}".format(not_found_ids))
        users.extend(more_users)

        submitted = []
        for user in users:
            submitted.append(BlockCompletion.objects.submit_completion(
                user=user,
                course_key=self._course_key,
                block_key=block_key,
                completion=completion
            ))
        return submitted


Instruction:
Can you tell what is the following Python 3 function doing
def submit_completion(self, block_key, completion):
        return BlockCompletion.objects.submit_completion(
            user=self._user,
            course_key=self._course_key,
            block_key=block_key,
            completion=completion
        )

Response: Submit a completion for the given block_key and return a new BlockCompletion object.


Instruction:
Can you write a function in Python 3 where it
returns the key to the last completed block in a course.

Response:
def get_key_to_last_completed_course_block(user, course_key):
    """
    Returns the last block a "user" completed in a course (stated as "course_key").

    raises UnavailableCompletionData when the user has not completed blocks in
    the course.

    raises UnavailableCompletionData when the visual progress waffle flag is
    disabled.
    """

    last_completed_block = BlockCompletion.get_latest_block_completed(user, course_key)

    if last_completed_block is not None:
        return last_completed_block.block_key

    raise UnavailableCompletionData(course_key)


Instruction:
Create a Python 3 function for
throwing an exception if the Cerberus response is not successful.

Response:
def throw_if_bad_response(response):
    """Throw an exception if the Cerberus response is not successful."""
    try:
        response.raise_for_status()
    except RequestException:
        try:
            msg = 'Response code: {}; response body:\n{}'.format(response.status_code, json.dumps(response.json(), indent=2))
            raise CerberusClientException(msg)
        except ValueError:
            msg = 'Response code: {}; response body:\n{}'.format(response.status_code, response.text)
            raise CerberusClientException(msg)


Instruction:
Create a Python 3 function for
initializing a KeenClient instance using environment variables.

Response:
def _initialize_client_from_environment():
    ''' Initialize a KeenClient instance using environment variables. '''
    global _client, project_id, write_key, read_key, master_key, base_url

    if _client is None:
        # check environment for project ID and keys
        project_id = project_id or os.environ.get("KEEN_PROJECT_ID")
        write_key = write_key or os.environ.get("KEEN_WRITE_KEY")
        read_key = read_key or os.environ.get("KEEN_READ_KEY")
        master_key = master_key or os.environ.get("KEEN_MASTER_KEY")
        base_url = base_url or os.environ.get("KEEN_BASE_URL")

        if not project_id:
            raise InvalidEnvironmentError("Please set the KEEN_PROJECT_ID environment variable or set keen.project_id!")

        _client = KeenClient(project_id,
                             write_key=write_key,
                             read_key=read_key,
                             master_key=master_key,
                             base_url=base_url)


Instruction:
Implement a Python 3 function for
adding an event to the Keen

Response:
def add_event(event_collection, body, timestamp=None):
    """ Adds an event.

    Depending on the persistence strategy of the client,
    this will either result in the event being uploaded to Keen
    immediately or will result in saving the event to some local cache.

    :param event_collection: the name of the collection to insert the
    event to
    :param body: dict, the body of the event to insert the event to
    :param timestamp: datetime, optional, the timestamp of the event
    """
    _initialize_client_from_environment()
    _client.add_event(event_collection, body, timestamp=timestamp)


Instruction:
Explain what the following Python 3 code does
def generate_image_beacon(event_collection, body, timestamp=None):
    _initialize_client_from_environment()
    return _client.generate_image_beacon(event_collection, body, timestamp=timestamp)

Response: Generates an image beacon URL.


Instruction:
Write a Python 3 script for
performing a count query Counts the number of events that meet the given criteria. :param event_collection: string, the name of the collection to query :param timeframe: string or dict, the timeframe in which the events happened example: "previous_7_days" :param timezone: int, the timezone you'd like to use for the timeframe and interval in seconds :param interval: string, the time interval used for measuring data over time example: "daily" :param filters: array of dict, contains the filters you'd like to apply to the data example: [{"property_name":"device", "operator":"eq", "property_value":"iPhone"}] :param group_by: string or array of strings, the name(s) of the properties you would like to group you results by. example: "customer.id" or ["browser","operating_system"] :param order_by: dictionary or list of dictionary objects containing the property_name(s) to order by and the desired direction(s) of sorting. Example: {"property_name":"result", "direction":keen.direction.DESCENDING} May not be used without a group_by specified. :param limit: positive integer limiting the displayed results of a query using order_by :param max_age: an integer, greater than 30 seconds, the maximum 'staleness' you're willing to trade for increased query performance, in seconds

Response:
def count(event_collection, timeframe=None, timezone=None, interval=None, filters=None, group_by=None, order_by=None,
          max_age=None, limit=None):
    """ Performs a count query

    Counts the number of events that meet the given criteria.

    :param event_collection: string, the name of the collection to query
    :param timeframe: string or dict, the timeframe in which the events
    happened example: "previous_7_days"
    :param timezone: int, the timezone you'd like to use for the timeframe
    and interval in seconds
    :param interval: string, the time interval used for measuring data over
    time example: "daily"
    :param filters: array of dict, contains the filters you'd like to apply to the data
    example: [{"property_name":"device", "operator":"eq", "property_value":"iPhone"}]
    :param group_by: string or array of strings, the name(s) of the properties you would
    like to group you results by.  example: "customer.id" or ["browser","operating_system"]
    :param order_by: dictionary or list of dictionary objects containing the property_name(s)
    to order by and the desired direction(s) of sorting.
    Example: {"property_name":"result", "direction":keen.direction.DESCENDING}
    May not be used without a group_by specified.
    :param limit: positive integer limiting the displayed results of a query using order_by
    :param max_age: an integer, greater than 30 seconds, the maximum 'staleness' you're
    willing to trade for increased query performance, in seconds

    """
    _initialize_client_from_environment()
    return _client.count(event_collection=event_collection, timeframe=timeframe, timezone=timezone,
                         interval=interval, filters=filters, group_by=group_by, order_by=order_by,
                         max_age=max_age, limit=limit)


Instruction:
Explain what the following Python 3 code does
def sum(event_collection, target_property, timeframe=None, timezone=None, interval=None, filters=None,
        group_by=None, order_by=None, max_age=None, limit=None):
    """ Performs a sum query

    Adds the values of a target property for events that meet the given criteria.

    :param event_collection: string, the name of the collection to query
    :param target_property: string, the name of the event property you would like use
    :param timeframe: string or dict, the timeframe in which the events
    happened example: "previous_7_days"
    :param timezone: int, the timezone you'd like to use for the timeframe
    and interval in seconds
    :param interval: string, the time interval used for measuring data over
    time example: "daily"
    :param filters: array of dict, contains the filters you'd like to apply to the data
    example: [{"property_name":"device", "operator":"eq", "property_value":"iPhone"}]
    :param group_by: string or array of strings, the name(s) of the properties you would
    like to group you results by.  example: "customer.id" or ["browser","operating_system"]
    :param order_by: dictionary or list of dictionary objects containing the property_name(s)
    to order by and the desired direction(s) of sorting.
    Example: {"property_name":"result", "direction":keen.direction.DESCENDING}
    May not be used without a group_by specified.
    :param limit: positive integer limiting the displayed results of a query using order_by
    :param max_age: an integer, greater than 30 seconds, the maximum 'staleness' you're
    willing to trade for increased query performance, in seconds

    """
    _initialize_client_from_environment()
    return _client.sum(event_collection=event_collection, timeframe=timeframe, timezone=timezone,
                       interval=interval, filters=filters, group_by=group_by, order_by=order_by,
                       target_property=target_property, max_age=max_age, limit=limit)

Response: This function performs a sum of the values of a target property for events in the given timeframe.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def extraction(event_collection, timeframe=None, timezone=None, filters=None, latest=None, email=None,
               property_names=None):
    """ Performs a data extraction

    Returns either a JSON object of events or a response
     indicating an email will be sent to you with data.

    :param event_collection: string, the name of the collection to query
    :param timeframe: string or dict, the timeframe in which the events
    happened example: "previous_7_days"
    :param timezone: int, the timezone you'd like to use for the timeframe
    and interval in seconds
    :param filters: array of dict, contains the filters you'd like to apply to the data
    example: [{"property_name":"device", "operator":"eq", "property_value":"iPhone"}]
    :param latest: int, the number of most recent records you'd like to return
    :param email: string, optional string containing an email address to email results to
    :param property_names: string or list of strings, used to limit the properties returned

    """
    _initialize_client_from_environment()
    return _client.extraction(event_collection=event_collection, timeframe=timeframe, timezone=timezone,
                              filters=filters, latest=latest, email=email, property_names=property_names)

Response: This function performs a data extraction of a single object in a timeframe.


Instruction:
Given the following Python 3 function, write the documentation
def multi_analysis(event_collection, analyses, timeframe=None, interval=None, timezone=None,
                   filters=None, group_by=None, order_by=None, max_age=None, limit=None):
    """ Performs a multi-analysis query

    Returns a dictionary of analysis results.

    :param event_collection: string, the name of the collection to query
    :param analyses: dict, the types of analyses you'd like to run.  example:
    {"total money made":{"analysis_type":"sum","target_property":"purchase.price",
    "average price":{"analysis_type":"average","target_property":"purchase.price"}
    :param timeframe: string or dict, the timeframe in which the events
    happened example: "previous_7_days"
    :param interval: string, the time interval used for measuring data over
    time example: "daily"
    :param timezone: int, the timezone you'd like to use for the timeframe
    and interval in seconds
    :param filters: array of dict, contains the filters you'd like to apply to the data
    example: [{"property_name":"device", "operator":"eq", "property_value":"iPhone"}]
    :param group_by: string or array of strings, the name(s) of the properties you would
    like to group you results by.  example: "customer.id" or ["browser","operating_system"]
    :param order_by: dictionary or list of dictionary objects containing the property_name(s)
    to order by and the desired direction(s) of sorting.
    Example: {"property_name":"result", "direction":keen.direction.DESCENDING}
    May not be used without a group_by specified.
    :param limit: positive integer limiting the displayed results of a query using order_by
    :param max_age: an integer, greater than 30 seconds, the maximum 'staleness' you're
    willing to trade for increased query performance, in seconds

    """
    _initialize_client_from_environment()
    return _client.multi_analysis(event_collection=event_collection, timeframe=timeframe,
                                  interval=interval, timezone=timezone, filters=filters,
                                  group_by=group_by, order_by=order_by, analyses=analyses,
                                  max_age=max_age, limit=limit)

Response: Performs a multi - analysis on the object in the specified timeframe.


Instruction:
Can you generate the documentation for the following Python 3 function
def create_access_key(name, is_active=True, permitted=[], options={}):
    _initialize_client_from_environment()
    return _client.create_access_key(name=name, is_active=is_active,
                                     permitted=permitted, options=options)

Response: Creates a new master key.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def update_access_key_full(access_key_id, name, is_active, permitted, options):
    _initialize_client_from_environment()
    return _client.update_access_key_full(access_key_id, name, is_active, permitted, options)

Response: Updates the name is_active permitted and options values for a given access key.


Instruction:
How would you code a function in Python 3 to
wrap for opj_version library routine.

Response:
def version():
    """Wrapper for opj_version library routine."""
    try:
        OPENJP2.opj_version.restype = ctypes.c_char_p
    except:
        return "0.0.0"

    v = OPENJP2.opj_version()
    return v.decode('utf-8') if sys.hexversion >= 0x03000000 else v


Instruction:
How would you explain what the following Python 3 function does
def check_error(status):
    global ERROR_MSG_LST
    if status != 1:
        if len(ERROR_MSG_LST) > 0:
            # clear out the existing error message so that we don't pick up
            # a bad one next time around.
            msg = '\n'.join(ERROR_MSG_LST)
            ERROR_MSG_LST = []
            raise OpenJPEGLibraryError(msg)
        else:
            raise OpenJPEGLibraryError("OpenJPEG function failure.")

Response:
Check if an error occured in the OpenJPEG
           .


Instruction:
How would you implement a function in Python 3 that
creates a J2K or JJP2 compress structure.

Response:
def create_compress(codec_format):
    """Creates a J2K/JP2 compress structure.

    Wraps the openjp2 library function opj_create_compress.

    Parameters
    ----------
    codec_format : int
        Specifies codec to select.  Should be one of CODEC_J2K or CODEC_JP2.

    Returns
    -------
    codec :  Reference to CODEC_TYPE instance.
    """
    OPENJP2.opj_create_compress.restype = CODEC_TYPE
    OPENJP2.opj_create_compress.argtypes = [CODEC_FORMAT_TYPE]

    codec = OPENJP2.opj_create_compress(codec_format)
    return codec


Instruction:
Write a Python 3 script to
read an entire image and returns a tree of image data structures.

Response:
def decode(codec, stream, image):
    """Reads an entire image.

    Wraps the openjp2 library function opj_decode.

    Parameters
    ----------
    codec : CODEC_TYPE
        The JPEG2000 codec
    stream : STREAM_TYPE_P
        The stream to decode.
    image : ImageType
        Output image structure.

    Raises
    ------
    RuntimeError
        If the OpenJPEG library routine opj_decode fails.
    """
    OPENJP2.opj_decode.argtypes = [CODEC_TYPE, STREAM_TYPE_P,
                                   ctypes.POINTER(ImageType)]
    OPENJP2.opj_decode.restype = check_error

    OPENJP2.opj_decode(codec, stream, image)


Instruction:
Make a summary of the following Python 3 code
def decode_tile_data(codec, tidx, data, data_size, stream):
    OPENJP2.opj_decode_tile_data.argtypes = [CODEC_TYPE,
                                             ctypes.c_uint32,
                                             ctypes.POINTER(ctypes.c_uint8),
                                             ctypes.c_uint32,
                                             STREAM_TYPE_P]
    OPENJP2.opj_decode_tile_data.restype = check_error

    datap = data.ctypes.data_as(ctypes.POINTER(ctypes.c_uint8))
    OPENJP2.opj_decode_tile_data(codec,
                                 ctypes.c_uint32(tidx),
                                 datap,
                                 ctypes.c_uint32(data_size),
                                 stream)

Response: Reads the data of a single tile into a new set of pages.


Instruction:
Make a summary of the following Python 3 code
def create_decompress(codec_format):
    OPENJP2.opj_create_decompress.argtypes = [CODEC_FORMAT_TYPE]
    OPENJP2.opj_create_decompress.restype = CODEC_TYPE

    codec = OPENJP2.opj_create_decompress(codec_format)
    return codec

Response: Creates a J2K or JJP2 decompress structure.


Instruction:
Explain what the following Python 3 code does
def destroy_codec(codec):
    OPENJP2.opj_destroy_codec.argtypes = [CODEC_TYPE]
    OPENJP2.opj_destroy_codec.restype = ctypes.c_void_p
    OPENJP2.opj_destroy_codec(codec)

Response: Wraps the openjp2 library function opj_destroy_codec.


Instruction:
Here you have a function in Python 3, explain what it does
def encode(codec, stream):
    OPENJP2.opj_encode.argtypes = [CODEC_TYPE, STREAM_TYPE_P]
    OPENJP2.opj_encode.restype = check_error

    OPENJP2.opj_encode(codec, stream)

Response: Wraps openjp2 library routine opj_encode.


Instruction:
Write a Python 3 function that can
get the decoded tile from the codec

Response:
def get_decoded_tile(codec, stream, imagep, tile_index):
    """get the decoded tile from the codec

    Wraps the openjp2 library function opj_get_decoded_tile.

    Parameters
    ----------
    codec : CODEC_TYPE
        The jpeg2000 codec.
    stream : STREAM_TYPE_P
        The input stream.
    image : ImageType
        Output image structure.
    tiler_index : int
        Index of the tile which will be decoded.

    Raises
    ------
    RuntimeError
        If the OpenJPEG library routine opj_get_decoded_tile fails.
    """
    OPENJP2.opj_get_decoded_tile.argtypes = [CODEC_TYPE,
                                             STREAM_TYPE_P,
                                             ctypes.POINTER(ImageType),
                                             ctypes.c_uint32]
    OPENJP2.opj_get_decoded_tile.restype = check_error

    OPENJP2.opj_get_decoded_tile(codec, stream, imagep, tile_index)


Instruction:
Given the following Python 3 function, write the documentation
def end_compress(codec, stream):
    OPENJP2.opj_end_compress.argtypes = [CODEC_TYPE, STREAM_TYPE_P]
    OPENJP2.opj_end_compress.restype = check_error
    OPENJP2.opj_end_compress(codec, stream)

Response: End of compressing the current image.


Instruction:
How would you implement a function in Python 3 that
ends of decompressing the current image.

Response:
def end_decompress(codec, stream):
    """End of decompressing the current image.

    Wraps the openjp2 library function opj_end_decompress.

    Parameters
    ----------
    codec : CODEC_TYPE
        Compressor handle.
    stream : STREAM_TYPE_P
        Output stream buffer.

    Raises
    ------
    RuntimeError
        If the OpenJPEG library routine opj_end_decompress fails.
    """
    OPENJP2.opj_end_decompress.argtypes = [CODEC_TYPE, STREAM_TYPE_P]
    OPENJP2.opj_end_decompress.restype = check_error
    OPENJP2.opj_end_decompress(codec, stream)


Instruction:
Implement a Python 3 function for
wrapping for openjp2 library function opj_image_destroy.

Response:
def image_destroy(image):
    """Deallocate any resources associated with an image.

    Wraps the openjp2 library function opj_image_destroy.

    Parameters
    ----------
    image : ImageType pointer
        Image resource to be disposed.
    """
    OPENJP2.opj_image_destroy.argtypes = [ctypes.POINTER(ImageType)]
    OPENJP2.opj_image_destroy.restype = ctypes.c_void_p

    OPENJP2.opj_image_destroy(image)


Instruction:
Implement a Python 3 function for
wrapping for openjp2 library function opj_image_create.

Response:
def image_create(comptparms, clrspc):
    """Creates a new image structure.

    Wraps the openjp2 library function opj_image_create.

    Parameters
    ----------
    cmptparms : comptparms_t
        The component parameters.
    clrspc : int
        Specifies the color space.

    Returns
    -------
    image : ImageType
        Reference to ImageType instance.
    """
    OPENJP2.opj_image_create.argtypes = [ctypes.c_uint32,
                                         ctypes.POINTER(ImageComptParmType),
                                         COLOR_SPACE_TYPE]
    OPENJP2.opj_image_create.restype = ctypes.POINTER(ImageType)

    image = OPENJP2.opj_image_create(len(comptparms),
                                     comptparms,
                                     clrspc)
    return image


Instruction:
Write a Python 3 script for
wrapping for openjp2 library function opj_image_tile_create.

Response:
def image_tile_create(comptparms, clrspc):
    """Creates a new image structure.

    Wraps the openjp2 library function opj_image_tile_create.

    Parameters
    ----------
    cmptparms : comptparms_t
        The component parameters.
    clrspc : int
        Specifies the color space.

    Returns
    -------
    image : ImageType
        Reference to ImageType instance.
    """
    ARGTYPES = [ctypes.c_uint32,
                ctypes.POINTER(ImageComptParmType),
                COLOR_SPACE_TYPE]
    OPENJP2.opj_image_tile_create.argtypes = ARGTYPES
    OPENJP2.opj_image_tile_create.restype = ctypes.POINTER(ImageType)

    image = OPENJP2.opj_image_tile_create(len(comptparms),
                                          comptparms,
                                          clrspc)
    return image


Instruction:
Can you generate a brief explanation for the following Python 3 code
def read_header(stream, codec):
    ARGTYPES = [STREAM_TYPE_P, CODEC_TYPE,
                ctypes.POINTER(ctypes.POINTER(ImageType))]
    OPENJP2.opj_read_header.argtypes = ARGTYPES
    OPENJP2.opj_read_header.restype = check_error

    imagep = ctypes.POINTER(ImageType)()
    OPENJP2.opj_read_header(stream, codec, ctypes.byref(imagep))
    return imagep

Response: Decodes an image header.


Instruction:
Create a Python 3 function for
reading a tile header from the specified codec and stream.

Response:
def read_tile_header(codec, stream):
    """Reads a tile header.

    Wraps the openjp2 library function opj_read_tile_header.

    Parameters
    ----------
    codec : codec_t
        The JPEG2000 codec to read.
    stream : STREAM_TYPE_P
        The JPEG2000 stream.

    Returns
    -------
    tile_index : int
        index of the tile being decoded
    data_size : int
        number of bytes for the decoded area
    x0, y0 : int
        upper left-most coordinate of tile
    x1, y1 : int
        lower right-most coordinate of tile
    ncomps : int
        number of components in the tile
    go_on : bool
        indicates that decoding should continue

    Raises
    ------
    RuntimeError
        If the OpenJPEG library routine opj_read_tile_header fails.
    """
    ARGTYPES = [CODEC_TYPE,
                STREAM_TYPE_P,
                ctypes.POINTER(ctypes.c_uint32),
                ctypes.POINTER(ctypes.c_uint32),
                ctypes.POINTER(ctypes.c_int32),
                ctypes.POINTER(ctypes.c_int32),
                ctypes.POINTER(ctypes.c_int32),
                ctypes.POINTER(ctypes.c_int32),
                ctypes.POINTER(ctypes.c_uint32),
                ctypes.POINTER(BOOL_TYPE)]
    OPENJP2.opj_read_tile_header.argtypes = ARGTYPES
    OPENJP2.opj_read_tile_header.restype = check_error

    tile_index = ctypes.c_uint32()
    data_size = ctypes.c_uint32()
    col0 = ctypes.c_int32()
    row0 = ctypes.c_int32()
    col1 = ctypes.c_int32()
    row1 = ctypes.c_int32()
    ncomps = ctypes.c_uint32()
    go_on = BOOL_TYPE()
    OPENJP2.opj_read_tile_header(codec,
                                 stream,
                                 ctypes.byref(tile_index),
                                 ctypes.byref(data_size),
                                 ctypes.byref(col0),
                                 ctypes.byref(row0),
                                 ctypes.byref(col1),
                                 ctypes.byref(row1),
                                 ctypes.byref(ncomps),
                                 ctypes.byref(go_on))
    go_on = bool(go_on.value)
    return (tile_index.value,
            data_size.value,
            col0.value,
            row0.value,
            col1.value,
            row1.value,
            ncomps.value,
            go_on)


Instruction:
Can you implement a function in Python 3 that
wraps openjp2 library function opj_set_decode area.

Response:
def set_decode_area(codec, image, start_x=0, start_y=0, end_x=0, end_y=0):
    """Wraps openjp2 library function opj_set_decode area.

    Sets the given area to be decoded.  This function should be called right
    after read_header and before any tile header reading.

    Parameters
    ----------
    codec : CODEC_TYPE
        Codec initialized by create_decompress function.
    image : ImageType pointer
        The decoded image previously set by read_header.
    start_x, start_y : optional, int
        The left and upper position of the rectangle to decode.
    end_x, end_y : optional, int
        The right and lower position of the rectangle to decode.

    Raises
    ------
    RuntimeError
        If the OpenJPEG library routine opj_set_decode_area fails.
    """
    OPENJP2.opj_set_decode_area.argtypes = [CODEC_TYPE,
                                            ctypes.POINTER(ImageType),
                                            ctypes.c_int32,
                                            ctypes.c_int32,
                                            ctypes.c_int32,
                                            ctypes.c_int32]
    OPENJP2.opj_set_decode_area.restype = check_error

    OPENJP2.opj_set_decode_area(codec, image,
                                ctypes.c_int32(start_x),
                                ctypes.c_int32(start_y),
                                ctypes.c_int32(end_x),
                                ctypes.c_int32(end_y))


Instruction:
Can you generate the documentation for the following Python 3 function
def set_default_decoder_parameters():
    ARGTYPES = [ctypes.POINTER(DecompressionParametersType)]
    OPENJP2.opj_set_default_decoder_parameters.argtypes = ARGTYPES
    OPENJP2.opj_set_default_decoder_parameters.restype = ctypes.c_void_p

    dparams = DecompressionParametersType()
    OPENJP2.opj_set_default_decoder_parameters(ctypes.byref(dparams))
    return dparams

Response: Wraps openjp2 library function opj_set_default_decoder_parameters. Opj_set_default_decoder_parameters returns a new object with decoding parameters set to default values.


Instruction:
Write a Python 3 function that can
wrap openjp2 library function opj_set_default_encoder_parameters and returns the resulting value.

Response:
def set_default_encoder_parameters():
    """Wraps openjp2 library function opj_set_default_encoder_parameters.

    Sets encoding parameters to default values.  That means

        lossless
        1 tile
        size of precinct : 2^15 x 2^15 (means 1 precinct)
        size of code-block : 64 x 64
        number of resolutions: 6
        no SOP marker in the codestream
        no EPH marker in the codestream
        no sub-sampling in x or y direction
        no mode switch activated
        progression order: LRCP
        no index file
        no ROI upshifted
        no offset of the origin of the image
        no offset of the origin of the tiles
        reversible DWT 5-3

    The signature for this function differs from its C library counterpart, as
    the the C function pass-by-reference parameter becomes the Python return
    value.

    Returns
    -------
    cparameters : CompressionParametersType
        Compression parameters.
    """
    ARGTYPES = [ctypes.POINTER(CompressionParametersType)]
    OPENJP2.opj_set_default_encoder_parameters.argtypes = ARGTYPES
    OPENJP2.opj_set_default_encoder_parameters.restype = ctypes.c_void_p

    cparams = CompressionParametersType()
    OPENJP2.opj_set_default_encoder_parameters(ctypes.byref(cparams))
    return cparams


Instruction:
How would you code a function in Python 3 to
wrap openjp2 library routine opj_set_error_handler.

Response:
def set_error_handler(codec, handler, data=None):
    """Wraps openjp2 library function opj_set_error_handler.

    Set the error handler use by openjpeg.

    Parameters
    ----------
    codec : CODEC_TYPE
        Codec initialized by create_compress function.
    handler : python function
        The callback function to be used.
    user_data : anything
        User/client data.

    Raises
    ------
    RuntimeError
        If the OpenJPEG library routine opj_set_error_handler fails.
    """
    OPENJP2.opj_set_error_handler.argtypes = [CODEC_TYPE,
                                              ctypes.c_void_p,
                                              ctypes.c_void_p]
    OPENJP2.opj_set_error_handler.restype = check_error
    OPENJP2.opj_set_error_handler(codec, handler, data)


Instruction:
Here you have a function in Python 3, explain what it does
def set_info_handler(codec, handler, data=None):
    OPENJP2.opj_set_info_handler.argtypes = [CODEC_TYPE,
                                             ctypes.c_void_p,
                                             ctypes.c_void_p]
    OPENJP2.opj_set_info_handler.restype = check_error
    OPENJP2.opj_set_info_handler(codec, handler, data)

Response: Wraps openjp2 library routine opj_set_info_handler.


Instruction:
Implement a Python 3 function for
wrapping openjp2 library routine opj_set_warning_handler.

Response:
def set_warning_handler(codec, handler, data=None):
    """Wraps openjp2 library function opj_set_warning_handler.

    Set the warning handler use by openjpeg.

    Parameters
    ----------
    codec : CODEC_TYPE
        Codec initialized by create_compress function.
    handler : python function
        The callback function to be used.
    user_data : anything
        User/client data.

    Raises
    ------
    RuntimeError
        If the OpenJPEG library routine opj_set_warning_handler fails.
    """
    OPENJP2.opj_set_warning_handler.argtypes = [CODEC_TYPE,
                                                ctypes.c_void_p,
                                                ctypes.c_void_p]
    OPENJP2.opj_set_warning_handler.restype = check_error

    OPENJP2.opj_set_warning_handler(codec, handler, data)


Instruction:
How would you code a function in Python 3 to
wrap openjp2 library routine opj_setup_decoder.

Response:
def setup_decoder(codec, dparams):
    """Wraps openjp2 library function opj_setup_decoder.

    Setup the decoder with decompression parameters.

    Parameters
    ----------
    codec:  CODEC_TYPE
        Codec initialized by create_compress function.
    dparams:  DecompressionParametersType
        Decompression parameters.

    Raises
    ------
    RuntimeError
        If the OpenJPEG library routine opj_setup_decoder fails.
    """
    ARGTYPES = [CODEC_TYPE, ctypes.POINTER(DecompressionParametersType)]
    OPENJP2.opj_setup_decoder.argtypes = ARGTYPES
    OPENJP2.opj_setup_decoder.restype = check_error

    OPENJP2.opj_setup_decoder(codec, ctypes.byref(dparams))


Instruction:
Implement a Python 3 function for
wrapping openjp2 library routine opj_setup_encoder.

Response:
def setup_encoder(codec, cparams, image):
    """Wraps openjp2 library function opj_setup_encoder.

    Setup the encoder parameters using the current image and using user
    parameters.

    Parameters
    ----------
    codec : CODEC_TYPE
        codec initialized by create_compress function
    cparams : CompressionParametersType
        compression parameters
    image : ImageType
        input-filled image

    Raises
    ------
    RuntimeError
        If the OpenJPEG library routine opj_setup_encoder fails.
    """
    ARGTYPES = [CODEC_TYPE,
                ctypes.POINTER(CompressionParametersType),
                ctypes.POINTER(ImageType)]
    OPENJP2.opj_setup_encoder.argtypes = ARGTYPES
    OPENJP2.opj_setup_encoder.restype = check_error
    OPENJP2.opj_setup_encoder(codec, ctypes.byref(cparams), image)


Instruction:
Can you write a function in Python 3 where it
wraps openjp2 library routine opj_start_compress.

Response:
def start_compress(codec, image, stream):
    """Wraps openjp2 library function opj_start_compress.

    Start to compress the current image.

    Parameters
    ----------
    codec : CODEC_TYPE
        Compressor handle.
    image : pointer to ImageType
        Input filled image.
    stream : STREAM_TYPE_P
        Input stream.

    Raises
    ------
    RuntimeError
        If the OpenJPEG library routine opj_start_compress fails.
    """
    OPENJP2.opj_start_compress.argtypes = [CODEC_TYPE,
                                           ctypes.POINTER(ImageType),
                                           STREAM_TYPE_P]
    OPENJP2.opj_start_compress.restype = check_error

    OPENJP2.opj_start_compress(codec, image, stream)


Instruction:
Explain what the following Python 3 code does
def stream_create_default_file_stream(fname, isa_read_stream):
    ARGTYPES = [ctypes.c_char_p, ctypes.c_int32]
    OPENJP2.opj_stream_create_default_file_stream.argtypes = ARGTYPES
    OPENJP2.opj_stream_create_default_file_stream.restype = STREAM_TYPE_P
    read_stream = 1 if isa_read_stream else 0
    file_argument = ctypes.c_char_p(fname.encode())
    stream = OPENJP2.opj_stream_create_default_file_stream(file_argument,
                                                           read_stream)
    return stream

Response: Wraps openjp2 library function opj_stream_create_default_vile_stream.


Instruction:
Can you write a function in Python 3 where it
wraps openjp2 library function opj_stream_destroy.

Response:
def stream_destroy(stream):
    """Wraps openjp2 library function opj_stream_destroy.

    Destroys the stream created by create_stream.

    Parameters
    ----------
    stream : STREAM_TYPE_P
        The file stream.
    """
    OPENJP2.opj_stream_destroy.argtypes = [STREAM_TYPE_P]
    OPENJP2.opj_stream_destroy.restype = ctypes.c_void_p
    OPENJP2.opj_stream_destroy(stream)


Instruction:
Create a Python 3 function for
wrapping openjp2 library function opj_write_tile.

Response:
def write_tile(codec, tile_index, data, data_size, stream):
    """Wraps openjp2 library function opj_write_tile.

    Write a tile into an image.

    Parameters
    ----------
    codec : CODEC_TYPE
        The jpeg2000 codec
    tile_index : int
        The index of the tile to write, zero-indexing assumed
    data : array
        Image data arranged in usual C-order
    data_size : int
        Size of a tile in bytes
    stream : STREAM_TYPE_P
        The stream to write data to

    Raises
    ------
    RuntimeError
        If the OpenJPEG library routine opj_write_tile fails.
    """
    OPENJP2.opj_write_tile.argtypes = [CODEC_TYPE,
                                       ctypes.c_uint32,
                                       ctypes.POINTER(ctypes.c_uint8),
                                       ctypes.c_uint32,
                                       STREAM_TYPE_P]
    OPENJP2.opj_write_tile.restype = check_error

    datap = data.ctypes.data_as(ctypes.POINTER(ctypes.c_uint8))
    OPENJP2.opj_write_tile(codec,
                           ctypes.c_uint32(int(tile_index)),
                           datap,
                           ctypes.c_uint32(int(data_size)),
                           stream)


Instruction:
Make a summary of the following Python 3 code
def paddingLength(str_len, blocksize=AES_blocksize):
  ''' Function to calculate the length of the required padding
  Input: (int) str_len   - String length of the text
         (int) blocksize - block size of the algorithm
  Returns: (int) number of required pad bytes for string of size.'''
  assert 0 < blocksize < 255, 'blocksize must be between 0 and 255'
  assert str_len > 0 , 'string length should be non-negative'

  'If the last block is already full, append an extra block of padding'
  pad_len = blocksize - (str_len % blocksize)

  return pad_len

Response: Function to calculate the length of the required padding bytes for a given string of size.


Instruction:
Can you generate the documentation for the following Python 3 function
def removeCMSPadding(str, blocksize=AES_blocksize):
  '''CMS padding: Remove padding with bytes containing the number of padding bytes '''
  try:
    pad_len = ord(str[-1]) # last byte contains number of padding bytes
  except TypeError:
    pad_len = str[-1]
  assert pad_len <= blocksize, 'padding error'
  assert pad_len <= len(str), 'padding error'

  return str[:-pad_len]

Response: CMS padding : Remove padding with bytes containing the number of padding bytes


Instruction:
Create a Python 3 function for
appending padding to the end of a string according to ANSI X. 923

Response:
def appendBitPadding(str, blocksize=AES_blocksize):
  '''Bit padding a.k.a. One and Zeroes Padding
  A single set ('1') bit is added to the message and then as many reset ('0') bits as required (possibly none) are added.
  Input: (str) str - String to be padded
         (int) blocksize - block size of the algorithm
  Return: Padded string according to ANSI X.923 standart

  Used in when padding bit strings.
  0x80 in binary is 10000000
  0x00 in binary is 00000000

  Defined in ANSI X.923 (based on NIST Special Publication 800-38A) and ISO/IEC 9797-1 as Padding Method 2.
  Used in hash functions MD5 and SHA, described in RFC 1321 step 3.1.
  '''
  pad_len = paddingLength(len(str), blocksize) - 1

  padding = chr(0x80)+'\0'*pad_len

  return str + padding


Instruction:
How would you code a function in Python 3 to
remove bit padding with 0x80 followed by zero bytes

Response:
def removeBitPadding(str, blocksize=AES_blocksize):
    'Remove bit padding with 0x80 followed by zero (null) bytes'
    pad_len = 0
    for char in str[::-1]: # str[::-1] reverses string
        if char == '\0':
            pad_len += 1
        else:
            break
    pad_len += 1
    str = str[:-pad_len]

    return str


Instruction:
Write a Python 3 function that can
remove Padding with zeroes + last byte equal to the number of padding bytes

Response:
def removeZeroLenPadding(str, blocksize=AES_blocksize):
  'Remove Padding with zeroes + last byte equal to the number of padding bytes'
  try:
    pad_len = ord(str[-1]) # last byte contains number of padding bytes
  except TypeError:
    pad_len = str[-1]
  assert pad_len < blocksize, 'padding error'
  assert pad_len < len(str), 'padding error'

  return str[:-pad_len]


Instruction:
Can you create a Python 3 function that
pads with null bytes

Response:
def appendNullPadding(str, blocksize=AES_blocksize):
  'Pad with null bytes'
  pad_len = paddingLength(len(str), blocksize)

  padding = '\0'*pad_len

  return str + padding


Instruction:
Here you have a function in Python 3, explain what it does
def removeNullPadding(str, blocksize=AES_blocksize):
    'Remove padding with null bytes'
    pad_len = 0
    for char in str[::-1]: # str[::-1] reverses string
        if char == '\0':
            pad_len += 1
        else:
            break
    str = str[:-pad_len]
    return str

Response: Remove padding with null bytes


Instruction:
Explain what the following Python 3 code does
def removeSpacePadding(str, blocksize=AES_blocksize):
    'Remove padding with spaces'
    pad_len = 0
    for char in str[::-1]: # str[::-1] reverses string
        if char == ' ':
            pad_len += 1
        else:
            break

    str = str[:-pad_len]

    return str

Response: Remove padding with spaces


Instruction:
Can you generate the documentation for the following Python 3 function
def appendRandomLenPadding(str, blocksize=AES_blocksize):
  'ISO 10126 Padding (withdrawn, 2007): Pad with random bytes + last byte equal to the number of padding bytes'
  pad_len = paddingLength(len(str), blocksize) - 1

  from os import urandom

  padding = urandom(pad_len)+chr(pad_len)

  return str + padding

Response: ISO 10126 Padding ( withdrawn 2007 ) Pad with random bytes + last byte equal to the number of padding bytes


Instruction:
Write a Python 3 script to
remove random padding from the end of the string

Response:
def removeRandomLenPadding(str, blocksize=AES_blocksize):
  'ISO 10126 Padding (withdrawn, 2007): Remove Padding with random bytes + last byte equal to the number of padding bytes'
  pad_len = ord(str[-1]) # last byte contains number of padding bytes
  assert pad_len < blocksize, 'padding error'
  assert pad_len < len(str), 'padding error'

  return str[:-pad_len]


Instruction:
Given the following Python 3 function, write the documentation
def appendPadding(str, blocksize=AES_blocksize, mode='CMS'):
  ''' Pad (append padding to) string for use with symmetric encryption algorithm
    Input: (string) str - String to be padded
           (int)    blocksize - block size of the encryption algorithm
           (string) mode - padding scheme one in (CMS, Bit, ZeroLen, Null, Space, Random)
    Return:(string) Padded string according to chosen padding mode
  '''
  if mode not in (0,'CMS'):
    for k in MODES.keys():
        if mode in k:
            return globals()['append'+k[1]+'Padding'](str, blocksize)
        else:
            return appendCMSPadding(str, blocksize)
  else:
      return appendCMSPadding(str, blocksize)

Response: Pads a string to be used with symmetric encryption algorithm


Instruction:
Write a Python 3 script for
removing padding from string

Response:
def removePadding(str, blocksize=AES_blocksize, mode='CMS'):
  ''' Remove padding from string
  Input: (str) str - String to be padded
         (int) blocksize - block size of the algorithm
         (string) mode - padding scheme one in (CMS, Bit, ZeroLen, Null, Space, Random)
  Return:(string) Decrypted string without padding
    '''
  if mode not in (0,'CMS'):
    for k in MODES.keys():
        if mode in k:
            return globals()['append'+k[1]+'Padding'](str, blocksize)
        else:
            return removeCMSPadding(str, blocksize)
  else:
      return removeCMSPadding(str, blocksize)


Instruction:
Can you generate the documentation for the following Python 3 function
def _default_error_handler(msg, _):
    msg = "OpenJPEG library error:  {0}".format(msg.decode('utf-8').rstrip())
    opj2.set_error_message(msg)

Response: Default error handler callback for libopenjp2.


Instruction:
Can you tell what is the following Python 3 function doing
def _default_warning_handler(library_msg, _):
    library_msg = library_msg.decode('utf-8').rstrip()
    msg = "OpenJPEG library warning:  {0}".format(library_msg)
    warnings.warn(msg, UserWarning)

Response: Default warning handler callback.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def parse(self):
        self.length = os.path.getsize(self.filename)

        with open(self.filename, 'rb') as fptr:

            # Make sure we have a JPEG2000 file.  It could be either JP2 or
            # J2C.  Check for J2C first, single box in that case.
            read_buffer = fptr.read(2)
            signature, = struct.unpack('>H', read_buffer)
            if signature == 0xff4f:
                self._codec_format = opj2.CODEC_J2K
                # That's it, we're done.  The codestream object is only
                # produced upon explicit request.
                return

            self._codec_format = opj2.CODEC_JP2

            # Should be JP2.
            # First 4 bytes should be 12, the length of the 'jP  ' box.
            # 2nd 4 bytes should be the box ID ('jP  ').
            # 3rd 4 bytes should be the box signature (13, 10, 135, 10).
            fptr.seek(0)
            read_buffer = fptr.read(12)
            values = struct.unpack('>I4s4B', read_buffer)
            box_length = values[0]
            box_id = values[1]
            signature = values[2:]
            if (((box_length != 12) or (box_id != b'jP  ') or
                 (signature != (13, 10, 135, 10)))):
                msg = '{filename} is not a JPEG 2000 file.'
                msg = msg.format(filename=self.filename)
                raise IOError(msg)

            # Back up and start again, we know we have a superbox (box of
            # boxes) here.
            fptr.seek(0)
            self.box = self.parse_superbox(fptr)
            self._validate()

Response: Parses the JPEG 2000 file.


Instruction:
Implement a function in Python 3 to
validate the JPEG 2000 outermost superbox.

Response:
def _validate(self):
        """Validate the JPEG 2000 outermost superbox.  These checks must be
        done at a file level.
        """
        # A JP2 file must contain certain boxes.  The 2nd box must be a file
        # type box.
        if not isinstance(self.box[1], FileTypeBox):
            msg = "{filename} does not contain a valid File Type box."
            msg = msg.format(filename=self.filename)
            raise IOError(msg)

        # A jp2-branded file cannot contain an "any ICC profile
        ftyp = self.box[1]
        if ftyp.brand == 'jp2 ':
            jp2h = [box for box in self.box if box.box_id == 'jp2h'][0]
            colrs = [box for box in jp2h.box if box.box_id == 'colr']
            for colr in colrs:
                if colr.method not in (core.ENUMERATED_COLORSPACE,
                                       core.RESTRICTED_ICC_PROFILE):
                    msg = ("Color Specification box method must specify "
                           "either an enumerated colorspace or a restricted "
                           "ICC profile if the file type box brand is 'jp2 '.")
                    warnings.warn(msg, UserWarning)


Instruction:
Can you tell what is the following Python 3 function doing
def _set_cinema_params(self, cinema_mode, fps):
        if re.match("1.5|2.0", version.openjpeg_version) is not None:
            msg = ("Writing Cinema2K or Cinema4K files is not supported with "
                   "OpenJPEG library versions less than 2.1.0.  The installed "
                   "version of OpenJPEG is {version}.")
            msg = msg.format(version=version.openjpeg_version)
            raise IOError(msg)

        # Cinema modes imply MCT.
        self._cparams.tcp_mct = 1

        if cinema_mode == 'cinema2k':
            if fps not in [24, 48]:
                msg = 'Cinema2K frame rate must be either 24 or 48.'
                raise IOError(msg)

            if fps == 24:
                self._cparams.rsiz = core.OPJ_PROFILE_CINEMA_2K
                self._cparams.max_comp_size = core.OPJ_CINEMA_24_COMP
                self._cparams.max_cs_size = core.OPJ_CINEMA_24_CS
            else:
                self._cparams.rsiz = core.OPJ_PROFILE_CINEMA_2K
                self._cparams.max_comp_size = core.OPJ_CINEMA_48_COMP
                self._cparams.max_cs_size = core.OPJ_CINEMA_48_CS

        else:
            # cinema4k
            self._cparams.rsiz = core.OPJ_PROFILE_CINEMA_4K

Response: Populate the internal structures for the cinema2k and cinema4k compression parameters.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def _populate_cparams(self, img_array, mct=None, cratios=None, psnr=None,
                          cinema2k=None, cinema4k=None, irreversible=None,
                          cbsize=None, eph=None, grid_offset=None, modesw=None,
                          numres=None, prog=None, psizes=None, sop=None,
                          subsam=None, tilesize=None, colorspace=None):
        """Directs processing of write method arguments.

        Parameters
        ----------
        img_array : ndarray
            Image data to be written to file.
        kwargs : dictionary
            Non-image keyword inputs provided to write method.
        """
        other_args = (mct, cratios, psnr, irreversible, cbsize, eph,
                      grid_offset, modesw, numres, prog, psizes, sop, subsam)
        if (((cinema2k is not None or cinema4k is not None) and
             (not all([arg is None for arg in other_args])))):
            msg = ("Cannot specify cinema2k/cinema4k along with any other "
                   "options.")
            raise IOError(msg)

        if cratios is not None and psnr is not None:
            msg = "Cannot specify cratios and psnr options together."
            raise IOError(msg)

        if version.openjpeg_version_tuple[0] == 1:
            cparams = opj.set_default_encoder_parameters()
        else:
            cparams = opj2.set_default_encoder_parameters()

        outfile = self.filename.encode()
        num_pad_bytes = opj2.PATH_LEN - len(outfile)
        outfile += b'0' * num_pad_bytes
        cparams.outfile = outfile

        if self.filename[-4:].endswith(('.jp2', '.JP2')):
            cparams.codec_fmt = opj2.CODEC_JP2
        else:
            cparams.codec_fmt = opj2.CODEC_J2K

        # Set defaults to lossless to begin.
        cparams.tcp_rates[0] = 0
        cparams.tcp_numlayers = 1
        cparams.cp_disto_alloc = 1

        cparams.irreversible = 1 if irreversible else 0

        if cinema2k is not None:
            self._cparams = cparams
            self._set_cinema_params('cinema2k', cinema2k)
            return

        if cinema4k is not None:
            self._cparams = cparams
            self._set_cinema_params('cinema4k', cinema4k)
            return

        if cbsize is not None:
            cparams.cblockw_init = cbsize[1]
            cparams.cblockh_init = cbsize[0]

        if cratios is not None:
            cparams.tcp_numlayers = len(cratios)
            for j, cratio in enumerate(cratios):
                cparams.tcp_rates[j] = cratio
            cparams.cp_disto_alloc = 1

        cparams.csty |= 0x02 if sop else 0
        cparams.csty |= 0x04 if eph else 0

        if grid_offset is not None:
            cparams.image_offset_x0 = grid_offset[1]
            cparams.image_offset_y0 = grid_offset[0]

        if modesw is not None:
            for shift in range(6):
                power_of_two = 1 << shift
                if modesw & power_of_two:
                    cparams.mode |= power_of_two

        if numres is not None:
            cparams.numresolution = numres

        if prog is not None:
            cparams.prog_order = core.PROGRESSION_ORDER[prog.upper()]

        if psnr is not None:
            cparams.tcp_numlayers = len(psnr)
            for j, snr_layer in enumerate(psnr):
                cparams.tcp_distoratio[j] = snr_layer
            cparams.cp_fixed_quality = 1

        if psizes is not None:
            for j, (prch, prcw) in enumerate(psizes):
                cparams.prcw_init[j] = prcw
                cparams.prch_init[j] = prch
            cparams.csty |= 0x01
            cparams.res_spec = len(psizes)

        if subsam is not None:
            cparams.subsampling_dy = subsam[0]
            cparams.subsampling_dx = subsam[1]

        if tilesize is not None:
            cparams.cp_tdx = tilesize[1]
            cparams.cp_tdy = tilesize[0]
            cparams.tile_size_on = opj2.TRUE

        if mct is None:
            # If the multi component transform was not specified, we infer
            # that it should be used if the color space is RGB.
            cparams.tcp_mct = 1 if self._colorspace == opj2.CLRSPC_SRGB else 0
        else:
            if self._colorspace == opj2.CLRSPC_GRAY:
                msg = ("Cannot specify usage of the multi component transform "
                       "if the colorspace is gray.")
                raise IOError(msg)
            cparams.tcp_mct = 1 if mct else 0

        self._validate_compression_params(img_array, cparams, colorspace)

        self._cparams = cparams

Response: Populate the cparams object with the appropriate values.


Instruction:
Can you create a Python 3 function that
writes image data to a JP2 JPX J2k file.

Response:
def _write(self, img_array, verbose=False, **kwargs):
        """Write image data to a JP2/JPX/J2k file.  Intended usage of the
        various parameters follows that of OpenJPEG's opj_compress utility.

        This method can only be used to create JPEG 2000 images that can fit
        in memory.
        """
        if re.match("0|1.[0-4]", version.openjpeg_version) is not None:
            msg = ("You must have at least version 1.5 of OpenJPEG "
                   "in order to write images.")
            raise RuntimeError(msg)

        self._determine_colorspace(**kwargs)
        self._populate_cparams(img_array, **kwargs)

        if opj2.OPENJP2 is not None:
            self._write_openjp2(img_array, verbose=verbose)
        else:
            self._write_openjpeg(img_array, verbose=verbose)


Instruction:
Make a summary of the following Python 3 code
def _write_openjpeg(self, img_array, verbose=False):
        if img_array.ndim == 2:
            # Force the image to be 3D.  Just makes things easier later on.
            img_array = img_array.reshape(img_array.shape[0],
                                          img_array.shape[1],
                                          1)

        self._populate_comptparms(img_array)

        with ExitStack() as stack:
            image = opj.image_create(self._comptparms, self._colorspace)
            stack.callback(opj.image_destroy, image)

            numrows, numcols, numlayers = img_array.shape

            # 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, numlayers):
                layer = np.ascontiguousarray(img_array[:, :, k],
                                             dtype=np.int32)
                dest = image.contents.comps[k].data
                src = layer.ctypes.data
                ctypes.memmove(dest, src, layer.nbytes)

            cinfo = opj.create_compress(self._cparams.codec_fmt)
            stack.callback(opj.destroy_compress, cinfo)

            # Setup the info, warning, and error handlers.
            # Always use the warning and error handler.  Use of an info
            # handler is optional.
            event_mgr = opj.EventMgrType()
            _info_handler = _INFO_CALLBACK if verbose else None
            event_mgr.info_handler = _info_handler
            event_mgr.warning_handler = ctypes.cast(_WARNING_CALLBACK,
                                                    ctypes.c_void_p)
            event_mgr.error_handler = ctypes.cast(_ERROR_CALLBACK,
                                                  ctypes.c_void_p)

            opj.setup_encoder(cinfo, ctypes.byref(self._cparams), image)

            cio = opj.cio_open(cinfo)
            stack.callback(opj.cio_close, cio)

            if not opj.encode(cinfo, cio, image):
                raise IOError("Encode error.")

            pos = opj.cio_tell(cio)

            blob = ctypes.string_at(cio.contents.buffer, pos)
            fptr = open(self.filename, 'wb')
            stack.callback(fptr.close)
            fptr.write(blob)

        self.parse()

Response: Write JPEG 2000 file using OpenJPEG 1. 5 interface.


Instruction:
Given the following Python 3 function, write the documentation
def _validate_j2k_colorspace(self, cparams, colorspace):
        if cparams.codec_fmt == opj2.CODEC_J2K and colorspace is not None:
            msg = 'Do not specify a colorspace when writing a raw codestream.'
            raise IOError(msg)

Response: Validate that the colorspace is valid for J2K.


Instruction:
Write a Python 3 script to
validate code block size.

Response:
def _validate_codeblock_size(self, cparams):
        """
        Code block dimensions must satisfy certain restrictions.

        They must both be a power of 2 and the total area defined by the width
        and height cannot be either too great or too small for the codec.
        """
        if cparams.cblockw_init != 0 and cparams.cblockh_init != 0:
            # These fields ARE zero if uninitialized.
            width = cparams.cblockw_init
            height = cparams.cblockh_init
            if height * width > 4096 or height < 4 or width < 4:
                msg = ("The code block area is specified as "
                       "{height} x {width} = {area} square pixels.  "
                       "Code block area cannot exceed 4096 square pixels.  "
                       "Code block height and width dimensions must be larger "
                       "than 4 pixels.")
                msg = msg.format(height=height, width=width,
                                 area=height * width)
                raise IOError(msg)
            if ((math.log(height, 2) != math.floor(math.log(height, 2)) or
                 math.log(width, 2) != math.floor(math.log(width, 2)))):
                msg = ("Bad code block size ({height} x {width}).  "
                       "The dimensions must be powers of 2.")
                msg = msg.format(height=height, width=width)
                raise IOError(msg)


Instruction:
Implement a function in Python 3 to
validate the precinct size of the current class.

Response:
def _validate_precinct_size(self, cparams):
        """
        Precinct dimensions must satisfy certain restrictions if specified.

        They must both be a power of 2 and must both be at least twice the
        size of their codeblock size counterparts.
        """
        code_block_specified = False
        if cparams.cblockw_init != 0 and cparams.cblockh_init != 0:
            code_block_specified = True

        if cparams.res_spec != 0:
            # precinct size was not specified if this field is zero.
            for j in range(cparams.res_spec):
                prch = cparams.prch_init[j]
                prcw = cparams.prcw_init[j]
                if j == 0 and code_block_specified:
                    height, width = cparams.cblockh_init, cparams.cblockw_init
                    if prch < height * 2 or prcw < width * 2:
                        msg = ("The highest resolution precinct size "
                               "({prch} x {prcw}) must be at least twice that "
                               "of the code block size "
                               "({cbh} x {cbw}).")
                        msg = msg.format(prch=prch, prcw=prcw,
                                         cbh=height, cbw=width)
                        raise IOError(msg)
                if ((math.log(prch, 2) != math.floor(math.log(prch, 2)) or
                     math.log(prcw, 2) != math.floor(math.log(prcw, 2)))):
                    msg = ("Bad precinct size ({height} x {width}).  "
                           "Precinct dimensions must be powers of 2.")
                    msg = msg.format(height=prch, width=prcw)
                    raise IOError(msg)


Instruction:
Can you tell what is the following Python 3 function doing
def _validate_image_rank(self, img_array):
        if img_array.ndim == 1 or img_array.ndim > 3:
            msg = "{0}D imagery is not allowed.".format(img_array.ndim)
            raise IOError(msg)

Response: Images must be either 2D or 3D.


Instruction:
Can you tell what is the following Python 3 function doing
def _validate_image_datatype(self, img_array):
        if img_array.dtype != np.uint8 and img_array.dtype != np.uint16:
            msg = ("Only uint8 and uint16 datatypes are currently supported "
                   "when writing.")
            raise RuntimeError(msg)

Response: Validate the image datatype.


Instruction:
Can you tell what is the following Python 3 function doing
def _validate_compression_params(self, img_array, cparams, colorspace):
        self._validate_j2k_colorspace(cparams, colorspace)
        self._validate_codeblock_size(cparams)
        self._validate_precinct_size(cparams)
        self._validate_image_rank(img_array)
        self._validate_image_datatype(img_array)

Response: Check that the compression parameters are valid.


Instruction:
Can you generate the documentation for the following Python 3 function
def _determine_colorspace(self, colorspace=None, **kwargs):
        if colorspace is None:
            # Must infer the colorspace from the image dimensions.
            if len(self.shape) < 3:
                # A single channel image is grayscale.
                self._colorspace = opj2.CLRSPC_GRAY
            elif self.shape[2] == 1 or self.shape[2] == 2:
                # A single channel image or an image with two channels is going
                # to be greyscale.
                self._colorspace = opj2.CLRSPC_GRAY
            else:
                # Anything else must be RGB, right?
                self._colorspace = opj2.CLRSPC_SRGB
        else:
            if colorspace.lower() not in ('rgb', 'grey', 'gray'):
                msg = 'Invalid colorspace "{0}".'.format(colorspace)
                raise IOError(msg)
            elif colorspace.lower() == 'rgb' and self.shape[2] < 3:
                msg = 'RGB colorspace requires at least 3 components.'
                raise IOError(msg)

            # Turn the colorspace from a string to the enumerated value that
            # the library expects.
            COLORSPACE_MAP = {'rgb': opj2.CLRSPC_SRGB,
                              'gray': opj2.CLRSPC_GRAY,
                              'grey': opj2.CLRSPC_GRAY,
                              'ycc': opj2.CLRSPC_YCC}

            self._colorspace = COLORSPACE_MAP[colorspace.lower()]

Response: Determine the colorspace from the supplied inputs.


Instruction:
Here you have a function in Python 3, explain what it does
def _write_openjp2(self, img_array, verbose=False):
        if img_array.ndim == 2:
            # Force the image to be 3D.  Just makes things easier later on.
            numrows, numcols = img_array.shape
            img_array = img_array.reshape(numrows, numcols, 1)

        self._populate_comptparms(img_array)

        with ExitStack() as stack:
            image = opj2.image_create(self._comptparms, self._colorspace)
            stack.callback(opj2.image_destroy, image)

            self._populate_image_struct(image, img_array)

            codec = opj2.create_compress(self._cparams.codec_fmt)
            stack.callback(opj2.destroy_codec, codec)

            if self._verbose or verbose:
                info_handler = _INFO_CALLBACK
            else:
                info_handler = None

            opj2.set_info_handler(codec, info_handler)
            opj2.set_warning_handler(codec, _WARNING_CALLBACK)
            opj2.set_error_handler(codec, _ERROR_CALLBACK)

            opj2.setup_encoder(codec, self._cparams, image)

            strm = opj2.stream_create_default_file_stream(self.filename,
                                                          False)
            stack.callback(opj2.stream_destroy, strm)

            opj2.start_compress(codec, image, strm)
            opj2.encode(codec, strm)
            opj2.end_compress(codec, strm)

        # Refresh the metadata.
        self.parse()

Response: Write JPEG 2000 file using OpenJPEG 2. x interface.


Instruction:
Can you create a Python 3 function that
appends a JP2 box to the file in - place.

Response:
def append(self, box):
        """Append a JP2 box to the file in-place.

        Parameters
        ----------
        box : Jp2Box
            Instance of a JP2 box.  Only UUID and XML boxes can currently be
            appended.
        """
        if self._codec_format == opj2.CODEC_J2K:
            msg = "Only JP2 files can currently have boxes appended to them."
            raise IOError(msg)

        if not ((box.box_id == 'xml ') or
                (box.box_id == 'uuid' and
                 box.uuid == UUID('be7acfcb-97a9-42e8-9c71-999491e3afac'))):
            msg = ("Only XML boxes and XMP UUID boxes can currently be "
                   "appended.")
            raise IOError(msg)

        # Check the last box.  If the length field is zero, then rewrite
        # the length field to reflect the true length of the box.
        with open(self.filename, 'rb') as ifile:
            offset = self.box[-1].offset
            ifile.seek(offset)
            read_buffer = ifile.read(4)
            box_length, = struct.unpack('>I', read_buffer)
            if box_length == 0:
                # Reopen the file in write mode and rewrite the length field.
                true_box_length = os.path.getsize(ifile.name) - offset
                with open(self.filename, 'r+b') as ofile:
                    ofile.seek(offset)
                    write_buffer = struct.pack('>I', true_box_length)
                    ofile.write(write_buffer)

        # Can now safely append the box.
        with open(self.filename, 'ab') as ofile:
            box.write(ofile)

        self.parse()


Instruction:
Write a Python 3 script for
creating a new JP2 file with the contents of the codestream.

Response:
def wrap(self, filename, boxes=None):
        """Create a new JP2/JPX file wrapped in a new set of JP2 boxes.

        This method is primarily aimed at wrapping a raw codestream in a set of
        of JP2 boxes (turning it into a JP2 file instead of just a raw
        codestream), or rewrapping a codestream in a JP2 file in a new "jacket"
        of JP2 boxes.

        Parameters
        ----------
        filename : str
            JP2 file to be created from a raw codestream.
        boxes : list
            JP2 box definitions to define the JP2 file format.  If not
            provided, a default ""jacket" is assumed, consisting of JP2
            signature, file type, JP2 header, and contiguous codestream boxes.
            A JPX file rewrapped without the boxes argument results in a JP2
            file encompassing the first codestream.

        Returns
        -------
        Jp2k
            Newly wrapped Jp2k object.

        Examples
        --------
        >>> import glymur, tempfile
        >>> jfile = glymur.data.goodstuff()
        >>> j2k = glymur.Jp2k(jfile)
        >>> tfile = tempfile.NamedTemporaryFile(suffix='jp2')
        >>> jp2 = j2k.wrap(tfile.name)
        """
        if boxes is None:
            boxes = self._get_default_jp2_boxes()

        self._validate_jp2_box_sequence(boxes)

        with open(filename, 'wb') as ofile:
            for box in boxes:
                if box.box_id != 'jp2c':
                    box.write(ofile)
                else:
                    self._write_wrapped_codestream(ofile, box)
            ofile.flush()

        jp2 = Jp2k(filename)
        return jp2


Instruction:
Can you create a Python 3 function that
writes the codestream of the codestream.

Response:
def _write_wrapped_codestream(self, ofile, box):
        """Write wrapped codestream."""
        # Codestreams require a bit more care.
        # Am I a raw codestream?
        if len(self.box) == 0:
            # Yes, just write the codestream box header plus all
            # of myself out to file.
            ofile.write(struct.pack('>I', self.length + 8))
            ofile.write(b'jp2c')
            with open(self.filename, 'rb') as ifile:
                ofile.write(ifile.read())
            return

        # OK, I'm a jp2/jpx file.  Need to find out where the raw codestream
        # actually starts.
        offset = box.offset
        if offset == -1:
            if self.box[1].brand == 'jpx ':
                msg = ("The codestream box must have its offset and length "
                       "attributes fully specified if the file type brand is "
                       "JPX.")
                raise IOError(msg)

            # Find the first codestream in the file.
            jp2c = [_box for _box in self.box if _box.box_id == 'jp2c']
            offset = jp2c[0].offset

        # Ready to write the codestream.
        with open(self.filename, 'rb') as ifile:
            ifile.seek(offset)

            # Verify that the specified codestream is right.
            read_buffer = ifile.read(8)
            L, T = struct.unpack_from('>I4s', read_buffer, 0)
            if T != b'jp2c':
                msg = "Unable to locate the specified codestream."
                raise IOError(msg)
            if L == 0:
                # The length of the box is presumed to last until the end of
                # the file.  Compute the effective length of the box.
                L = os.path.getsize(ifile.name) - ifile.tell() + 8

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

            ifile.seek(offset)
            read_buffer = ifile.read(L)
            ofile.write(read_buffer)


Instruction:
How would you code a function in Python 3 to
create a default set of JP2 boxes.

Response:
def _get_default_jp2_boxes(self):
        """Create a default set of JP2 boxes."""
        # Try to create a reasonable default.
        boxes = [JPEG2000SignatureBox(),
                 FileTypeBox(),
                 JP2HeaderBox(),
                 ContiguousCodestreamBox()]
        height = self.codestream.segment[1].ysiz
        width = self.codestream.segment[1].xsiz
        num_components = len(self.codestream.segment[1].xrsiz)
        if num_components < 3:
            colorspace = core.GREYSCALE
        else:
            if len(self.box) == 0:
                # Best guess is SRGB
                colorspace = core.SRGB
            else:
                # Take whatever the first jp2 header / color specification
                # says.
                jp2hs = [box for box in self.box if box.box_id == 'jp2h']
                colorspace = jp2hs[0].box[1].colorspace

        boxes[2].box = [ImageHeaderBox(height=height, width=width,
                                       num_components=num_components),
                        ColourSpecificationBox(colorspace=colorspace)]

        return boxes


Instruction:
Here you have a function in Python 3, explain what it does
def _remove_ellipsis(self, index, numrows, numcols, numbands):
        # Remove the first ellipsis we find.
        rows = slice(0, numrows)
        cols = slice(0, numcols)
        bands = slice(0, numbands)
        if index[0] is Ellipsis:
            if len(index) == 2:
                # jp2k[..., other_slice]
                newindex = (rows, cols, index[1])
            else:
                # jp2k[..., cols, bands]
                newindex = (rows, index[1], index[2])
        elif index[1] is Ellipsis:
            if len(index) == 2:
                # jp2k[rows, ...]
                newindex = (index[0], cols, bands)
            else:
                # jp2k[rows, ..., bands]
                newindex = (index[0], cols, index[2])
        else:
            # Assume that we don't have 4D imagery, of course.
            newindex = (index[0], index[1], bands)

        return newindex

Response: Remove the first ellipsis in the index so that it references the image.


Instruction:
Here you have a function in Python 3, explain what it does
def _read(self, **kwargs):
        if re.match("0|1.[01234]", version.openjpeg_version):
            msg = ("You must have a version of OpenJPEG at least as high as "
                   "1.5.0 before you can read JPEG2000 images with glymur.  "
                   "Your version is {version}")
            raise TypeError(msg.format(version=version.openjpeg_version))

        if version.openjpeg_version_tuple[0] < 2:
            img = self._read_openjpeg(**kwargs)
        else:
            img = self._read_openjp2(**kwargs)
        return img

Response: Read a JPEG 2000 image.


Instruction:
Can you tell what is the following Python 3 function doing
def _subsampling_sanity_check(self):
        dxs = np.array(self.codestream.segment[1].xrsiz)
        dys = np.array(self.codestream.segment[1].yrsiz)
        if np.any(dxs - dxs[0]) or np.any(dys - dys[0]):
            msg = ("The read_bands method should be used with the subsampling "
                   "factors are different. "
                   "\n\n{siz_segment}")
            msg = msg.format(siz_segment=str(self.codestream.segment[1]))
            raise IOError(msg)

Response: Check for differing subsample factors.


Instruction:
How would you implement a function in Python 3 that
reads a JPEG 2000 image using libopenjpeg.

Response:
def _read_openjpeg(self, rlevel=0, verbose=False, area=None):
        """Read a JPEG 2000 image using libopenjpeg.

        Parameters
        ----------
        rlevel : int, optional
            Factor by which to rlevel output resolution.  Use -1 to get the
            lowest resolution thumbnail.
        verbose : bool, optional
            Print informational messages produced by the OpenJPEG library.
        area : tuple, optional
            Specifies decoding image area,
            (first_row, first_col, last_row, last_col)

        Returns
        -------
        ndarray
            The image data.

        Raises
        ------
        RuntimeError
            If the image has differing subsample factors.
        """
        self._subsampling_sanity_check()

        self._populate_dparams(rlevel)

        with ExitStack() as stack:
            try:
                self._dparams.decod_format = self._codec_format

                dinfo = opj.create_decompress(self._dparams.decod_format)

                event_mgr = opj.EventMgrType()
                handler = ctypes.cast(_INFO_CALLBACK, ctypes.c_void_p)
                event_mgr.info_handler = handler if self.verbose else None
                event_mgr.warning_handler = ctypes.cast(_WARNING_CALLBACK,
                                                        ctypes.c_void_p)
                event_mgr.error_handler = ctypes.cast(_ERROR_CALLBACK,
                                                      ctypes.c_void_p)
                opj.set_event_mgr(dinfo, ctypes.byref(event_mgr))

                opj.setup_decoder(dinfo, self._dparams)

                with open(self.filename, 'rb') as fptr:
                    src = fptr.read()
                cio = opj.cio_open(dinfo, src)

                raw_image = opj.decode(dinfo, cio)

                stack.callback(opj.image_destroy, raw_image)
                stack.callback(opj.destroy_decompress, dinfo)
                stack.callback(opj.cio_close, cio)

                image = self._extract_image(raw_image)

            except ValueError:
                opj2.check_error(0)

        if area is not None:
            x0, y0, x1, y1 = area
            extent = 2 ** rlevel

            area = [int(round(float(x) / extent + 2 ** -20)) for x in area]
            rows = slice(area[0], area[2], None)
            cols = slice(area[1], area[3], None)
            image = image[rows, cols]

        return image


Instruction:
How would you implement a function in Python 3 that
reads a JPEG 2000 image using libopenjp2.

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

        Parameters
        ----------
        layer : int, optional
            Number of quality layer to decode.
        rlevel : int, optional
            Factor by which to rlevel output resolution.  Use -1 to get the
            lowest resolution thumbnail.
        area : tuple, optional
            Specifies decoding image area,
            (first_row, first_col, last_row, last_col)
        tile : int, optional
            Number of tile to decode.
        verbose : bool, optional
            Print informational messages produced by the OpenJPEG library.

        Returns
        -------
        ndarray
            The image data.

        Raises
        ------
        RuntimeError
            If the image has differing subsample factors.
        """
        self.layer = layer
        self._subsampling_sanity_check()
        self._populate_dparams(rlevel, tile=tile, area=area)
        image = self._read_openjp2_common()
        return image


Instruction:
How would you implement a function in Python 3 that
reads a JPEG 2000 image using libopenjp2.

Response:
def _read_openjp2_common(self):
        """
        Read a JPEG 2000 image using libopenjp2.

        Returns
        -------
        ndarray or lst
            Either the image as an ndarray or a list of ndarrays, each item
            corresponding to one band.
        """
        with ExitStack() as stack:
            filename = self.filename
            stream = opj2.stream_create_default_file_stream(filename, True)
            stack.callback(opj2.stream_destroy, stream)
            codec = opj2.create_decompress(self._codec_format)
            stack.callback(opj2.destroy_codec, codec)

            opj2.set_error_handler(codec, _ERROR_CALLBACK)
            opj2.set_warning_handler(codec, _WARNING_CALLBACK)

            if self._verbose:
                opj2.set_info_handler(codec, _INFO_CALLBACK)
            else:
                opj2.set_info_handler(codec, None)

            opj2.setup_decoder(codec, self._dparams)
            raw_image = opj2.read_header(stream, codec)
            stack.callback(opj2.image_destroy, raw_image)

            if self._dparams.nb_tile_to_decode:
                opj2.get_decoded_tile(codec, stream, raw_image,
                                      self._dparams.tile_index)
            else:
                opj2.set_decode_area(codec, raw_image,
                                     self._dparams.DA_x0, self._dparams.DA_y0,
                                     self._dparams.DA_x1, self._dparams.DA_y1)
                opj2.decode(codec, stream, raw_image)

            opj2.end_decompress(codec, stream)

            image = self._extract_image(raw_image)

        return image