Instruction:
Write a Python 3 function for
checking shape and dtype of vector and scales it to given length

Response:
def validate(self, instance, value):
        """Check shape and dtype of vector and scales it to given length"""

        value = super(BaseVector, self).validate(instance, value)

        if self.length is not None:
            try:
                value.length = self._length_array(value)
            except ZeroDivisionError:
                self.error(
                    instance, value,
                    error_class=ZeroDivValidationError,
                    extra='The vector must have a length specified.'
                )
        return value


Instruction:
Here you have a function in Python 3, explain what it does
def validate(self, instance, value):
        if isinstance(value, string_types):
            if (
                    value.upper() not in VECTOR_DIRECTIONS or
                    value.upper() in ('Z', '-Z', 'UP', 'DOWN')
            ):
                self.error(instance, value)
            value = VECTOR_DIRECTIONS[value.upper()][:2]

        return super(Vector2, self).validate(instance, value)

Response:
Check shape and dtype of vector
        validate also coerces the vector from valid strings


Instruction:
How would you explain what the following Python 3 function does
def validate(self, instance, value):
        if not isinstance(value, (tuple, list, np.ndarray)):
            self.error(instance, value)
        if isinstance(value, (tuple, list)):
            for i, val in enumerate(value):
                if isinstance(val, string_types):
                    if val.upper() not in VECTOR_DIRECTIONS:
                        self.error(
                            instance=instance,
                            value=val,
                            extra='This is an invalid Vector3 representation.',
                        )
                    value[i] = VECTOR_DIRECTIONS[val.upper()]

        return super(Vector3Array, self).validate(instance, value)

Response:
Check shape and dtype of vector
COOKIES validate also coerces the vector from valid strings and scales it to the given length.


Instruction:
Can you write a function in Python 3 where it
evaluates the given string with respect to the locale defined by lng.

Response:
def localize(self, lng: str) -> str:
        """
        Evaluate the given string with respect to the locale defined by ``lng``.

        If no string is available in the currently active language, this will give you
        the string in the system's default language. If this is unavailable as well, it
        will give you the string in the first language available.

        :param lng: A locale code, e.g. ``de``. If you specify a code including a country
            or region like ``de-AT``, exact matches will be used preferably, but if only
            a ``de`` or ``de-AT`` translation exists, this might be returned as well.
        """
        if self.data is None:
            return ""

        if isinstance(self.data, dict):
            firstpart = lng.split('-')[0]
            similar = [l for l in self.data.keys() if (l.startswith(firstpart + "-") or firstpart == l) and l != lng]
            if self.data.get(lng):
                return self.data[lng]
            elif self.data.get(firstpart):
                return self.data[firstpart]
            elif similar and any([self.data.get(s) for s in similar]):
                for s in similar:
                    if self.data.get(s):
                        return self.data.get(s)
            elif self.data.get(settings.LANGUAGE_CODE):
                return self.data[settings.LANGUAGE_CODE]
            elif len(self.data):
                return list(self.data.items())[0][1]
            else:
                return ""
        else:
            return str(self.data)


Instruction:
How would you implement a function in Python 3 that
adds listeners to a HasProperties instance

Response:
def _set_listener(instance, obs):
    """Add listeners to a HasProperties instance"""
    if obs.names is everything:
        names = list(instance._props)
    else:
        names = obs.names
    for name in names:
        if name not in instance._listeners:
            instance._listeners[name] = {typ: [] for typ in LISTENER_TYPES}
        instance._listeners[name][obs.mode] += [obs]


Instruction:
Can you create a Python 3 function that
gets the listeners of a changed Property on a HasProperties instance

Response:
def _get_listeners(instance, change):
    """Gets listeners of changed Property on a HasProperties instance"""
    if (
            change['mode'] not in listeners_disabled._quarantine and           #pylint: disable=protected-access
            change['name'] in instance._listeners
    ):
        return instance._listeners[change['name']][change['mode']]
    return []


Instruction:
Can you generate the documentation for the following Python 3 function
def observer(names_or_instance, names=None, func=None, change_only=False):

    mode = 'observe_change' if change_only else 'observe_set'

    if names is None and func is None:
        return Observer(names_or_instance, mode)
    obs = Observer(names, mode)(func)
    _set_listener(names_or_instance, obs)
    return obs

Response: Defines a callback function that will fire on a property or property value of a HasProperties object.


Instruction:
How would you implement a function in Python 3 that
defines a callback function to fire on class validation or property set

Response:
def validator(names_or_instance, names=None, func=None):
    """Specify a callback function to fire on class validation OR property set

    This function has two modes of operation:

    1. Registering callback functions that validate Property values when
       they are set, before the change is saved to the HasProperties instance.
       This mode is very similar to the :code:`observer` function.
    2. Registering callback functions that fire only when the HasProperties
       :code:`validate` method is called. This allows for cross-validation
       of Properties that should only fire when all required Properties are
       set.

    **Mode 1:**

    Validator functions on a HasProperties class fire on set but before the
    observed Property or Properties have been changed (unlike observer
    functions that fire after the value has been changed).

    You can use this method as a decorator inside a HasProperties class

    .. code::

        @properties.validator('variable_name')
        def callback_function(self, change):
            print(change)

    or you can use it to register a function to a single HasProperties
    instance

    .. code::

        properties.validator(my_has_props, 'variable_name', callback_function)

    The variable name must refer to a Property name on the HasProperties
    class. A list of Property names may also be used; the same
    callback function will fire when any of these Properties change. Also,
    :class:`properties.everything <properties.utils.Sentinel>` may be
    specified instead of the variable name. In that case, the callback
    function will fire when any Property changes.

    The callback function must take two arguments. The first is the
    HasProperties instance; the second is the change notification dictionary.
    This dictionary contains:

    * 'name' - the name of the changed Property
    * 'previous' - the value of the Property prior to change (this will be
      :code:`properties.undefined` if the value was not previously set)
    * 'value' - the new value of the Property (this will be
      :code:`properties.undefined` if the value is deleted)
    * 'mode' - the mode of the change; for validators, this is 'validate'

    **Mode 2:**

    When used as a decorator without arguments (i.e. called directly on a
    HasProperties method), the decorated method is registered as a class
    validator. These methods execute only when :code:`validate()` is called
    on the HasProperties instance.

    .. code::

        @properties.validator
        def validation_method(self):
            print('validating instance of {}'.format(self.__class__))

    The decorated function must only take one argument, the HasProperties
    instance.
    """

    if names is None and func is None:
        if callable(names_or_instance):
            return ClassValidator(names_or_instance)
        return Observer(names_or_instance, 'validate')
    val = Observer(names, 'validate')(func)
    _set_listener(names_or_instance, val)
    return val


Instruction:
Given the following Python 3 function, write the documentation
def build_from_bases(bases, classdict, attr, attr_dict):
    output = OrderedDict()
    output_keys = set()
    all_bases = []
    # Go through the bases from furthest to nearest ancestor
    for base in reversed(bases):
        # Only keep the items that are still defined on the bases
        if base is not object and isinstance(base, PropertyMetaclass):
            output_keys = output_keys.union(getattr(base, attr))
        # Collect all bases so we ensure overridden items are assigned
        # in the correct order
        for item in reversed(base.__mro__):
            if item is object or not isinstance(item, PropertyMetaclass):
                continue
            if item not in all_bases:
                all_bases.append(item)
    # Update the items in reverse MRO order; only keep those that are
    # defined on the bases
    for base in all_bases:
        for key, val in iteritems(getattr(base, attr)):
            if key in base.__dict__ and key in output_keys:
                output.update({key: val})
    # Remove all items that were overridden by this class; this is
    # potentially a superset of the items added back in the next step.
    for key in classdict:
        if key in output:
            output.pop(key)
    # Update the items with those defined on this class
    output.update(attr_dict)
    return output

Response: Helper function to build private HasProperties attributes from bases classdict and attr.


Instruction:
How would you explain what the following Python 3 function does
def equal(value_a, value_b):
    if (
            not isinstance(value_a, HasProperties) or
            not isinstance(value_b, HasProperties)
    ):
        return value_a == value_b
    if getattr(value_a, '_testing_equality', False):
        return False
    value_a._testing_equality = True                                           #pylint: disable=protected-access
    try:
        if value_a is value_b:
            return True
        if value_a.__class__ is not value_b.__class__:
            return False
        for prop in itervalues(value_a._props):
            prop_a = getattr(value_a, prop.name)
            prop_b = getattr(value_b, prop.name)
            if prop_a is None and prop_b is None:
                continue
            if (
                    prop_a is not None and
                    prop_b is not None and
                    prop.equal(prop_a, prop_b)
            ):
                continue
            return False
        return True
    finally:
        value_a._testing_equality = False

Response: Returns True if two values are equivalent to the current value.


Instruction:
How would you code a function in Python 3 to
return a copy of a HasProperties instance

Response:
def copy(value, **kwargs):
    """Return a copy of a **HasProperties** instance

    A copy is produced by serializing the HasProperties instance then
    deserializing it to a new instance. Therefore, if any properties
    cannot be serialized/deserialized, :code:`copy` will fail. Any
    keyword arguments will be passed through to both :code:`serialize`
    and :code:`deserialize`.
    """

    if not isinstance(value, HasProperties):
        raise ValueError('properties.copy may only be used to copy'
                         'HasProperties instances')
    kwargs.update({'include_class': kwargs.get('include_class', True)})
    kwargs.update({'trusted': kwargs.get('trusted', True)})
    return value.__class__.deserialize(value.serialize(**kwargs), **kwargs)


Instruction:
How would you implement a function in Python 3 that
reverts specified property to default value

Response:
def _reset(self, name=None):
        """Revert specified property to default value

        If no property is specified, all properties are returned to default.
        """
        if name is None:
            for key in self._props:
                if isinstance(self._props[key], basic.Property):
                    self._reset(key)
            return
        if name not in self._props:
            raise AttributeError("Input name '{}' is not a known "
                                 "property or attribute".format(name))
        if not isinstance(self._props[name], basic.Property):
            raise AttributeError("Cannot reset GettableProperty "
                                 "'{}'".format(name))
        if name in self._defaults:
            val = self._defaults[name]
        else:
            val = self._props[name].default
        if callable(val):
            val = val()
        setattr(self, name, val)


Instruction:
Create a Python 3 function for
validating the current object.

Response:
def validate(self):
        """Call all registered class validator methods

        These are all methods decorated with :code:`@properties.validator`.
        Validator methods are expected to raise a ValidationError if they
        fail.
        """
        if getattr(self, '_getting_validated', False):
            return True
        self._getting_validated = True
        self._validation_error_tuples = []
        self._non_validation_error = None
        try:
            for val in itervalues(self._class_validators):
                try:
                    if isinstance(val.func, string_types):
                        valid = getattr(self, val.func)()
                    else:
                        valid = val.func(self)
                    if valid is False:
                        raise utils.ValidationError(
                            'Validation failed', None, None, self
                        )
                except utils.ValidationError as val_err:
                    self._validation_error_tuples += val_err.error_tuples
                except GENERIC_ERRORS as err:
                    if not self._non_validation_error:
                        self._non_validation_error = err
            if self._validation_error_tuples:
                self._error_hook(self._validation_error_tuples)
                msgs = ['Validation failed:']
                msgs += [val.message for val in self._validation_error_tuples]
                raise utils.ValidationError(
                    message='\n- '.join(msgs),
                    _error_tuples=self._validation_error_tuples,
                )
            if self._non_validation_error:
                raise self._non_validation_error                               #pylint: disable=raising-bad-type
            return True
        finally:
            self._getting_validated = False
            self._validation_error_tuples = None
            self._non_validation_error = None


Instruction:
Can you write a function in Python 3 where it
asserts that all the properties are valid on validate

Response:
def _validate_props(self):
        """Assert that all the properties are valid on validate()"""
        for key, prop in iteritems(self._props):
            try:
                value = self._get(key)
                err_msg = 'Invalid value for property {}: {}'.format(key, value)
                if value is not None:
                    change = dict(name=key, previous=value, value=value,
                                  mode='validate')
                    self._notify(change)
                    if not prop.equal(value, change['value']):
                        raise utils.ValidationError(err_msg, 'invalid',
                                                    prop.name, self)
                if not prop.assert_valid(self):
                    raise utils.ValidationError(err_msg, 'invalid',
                                                prop.name, self)
            except utils.ValidationError as val_err:
                if getattr(self, '_validation_error_tuples', None) is not None:
                    self._validation_error_tuples += val_err.error_tuples
                else:
                    raise
        return True


Instruction:
Can you generate the documentation for the following Python 3 function
def serialize(self, include_class=True, save_dynamic=False, **kwargs):
        if getattr(self, '_getting_serialized', False):
            raise utils.SelfReferenceError('Object contains unserializable '
                                           'self reference')
        self._getting_serialized = True
        try:
            kwargs.update({
                'include_class': include_class,
                'save_dynamic': save_dynamic
            })
            if save_dynamic:
                prop_source = self._props
            else:
                prop_source = self._backend
            data = (
                (key, self._props[key].serialize(getattr(self, key), **kwargs))
                for key in prop_source
            )
            json_dict = {k: v for k, v in data if v is not None}
            if include_class:
                json_dict.update({'__class__': self.__class__.__name__})
            return json_dict
        finally:
            self._getting_serialized = False

Response: Serializes a HasProperties instance to a dictionary.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def deserialize(cls, value, trusted=False, strict=False,                   #pylint: disable=too-many-locals
                    assert_valid=False, **kwargs):
        """Creates **HasProperties** instance from serialized dictionary

        This uses the Property deserializers to deserialize all
        JSON-compatible dictionary values into their corresponding Property
        values on a new instance of a **HasProperties** class. Extra keys
        in the dictionary that do not correspond to Properties will be
        ignored.

        **Parameters**:

        * **value** - Dictionary to deserialize new instance from.
        * **trusted** - If True (and if the input dictionary has
          :code:`'__class__'` keyword and this class is in the registry), the
          new **HasProperties** class will come from the dictionary.
          If False (the default), only the **HasProperties** class this
          method is called on will be constructed.
        * **strict** - Requires :code:`'__class__'`, if present on the input
          dictionary, to match the deserialized instance's class. Also
          disallows unused properties in the input dictionary. Default
          is False.
        * **assert_valid** - Require deserialized instance to be valid.
          Default is False.
        * Any other keyword arguments will be passed through to the Property
          deserializers.
        """
        if not isinstance(value, dict):
            raise ValueError(
                'HasProperties class {} must deserialize from dictionary, '
                'not input of type {}'.format(
                    cls.__name__, value.__class__.__name__
                )
            )
        output_cls = cls._deserialize_class(
            input_cls_name=value.get('__class__'),
            trusted=trusted,
            strict=strict,
        )
        instance = kwargs.pop('_instance', None)
        if instance is not None and not isinstance(instance, output_cls):
            raise ValueError(
                'Input _instance must be of class {}, not {}'.format(
                    output_cls.__name__, instance.__class__.__name__
                )
            )
        state, unused = utils.filter_props(output_cls, value, True)
        unused.pop('__class__', None)
        if unused and strict:
            raise ValueError(
                'Unused properties during deserialization: {}'.format(
                    ', '.join(unused)
                )
            )
        kwargs.update({'trusted': trusted, 'strict': strict})
        newstate = {}
        for key, val in iteritems(state):
            newstate[key] = output_cls._props[key].deserialize(val, **kwargs)
        mutable, immutable = utils.filter_props(output_cls, newstate, False)
        with handlers.listeners_disabled():
            if instance is None:
                instance = output_cls(**mutable)
            else:
                for key, val in iteritems(mutable):
                    setattr(instance, key, val)
        for key, val in iteritems(immutable):
            valid_val = output_cls._props[key].validate(instance, val)
            instance._backend[key] = valid_val
        if assert_valid and not instance.validate():
            raise utils.ValidationError('Deserialized instance is not valid')
        return instance

Response: Deserializes a dictionary into a new instance of the specified class.


Instruction:
Can you tell what is the following Python 3 function doing
def _deserialize_class(cls, input_cls_name, trusted, strict):
        if not input_cls_name or input_cls_name == cls.__name__:
            return cls
        if trusted and input_cls_name in cls._REGISTRY:
            return cls._REGISTRY[input_cls_name]
        if strict:
            raise ValueError(
                'Class name {} from deserialization input dictionary does '
                'not match input class {}'.format(input_cls_name, cls.__name__)
            )
        return cls

Response: Returns the HasProperties class to use for deserialization


Instruction:
Explain what the following Python 3 code does
def report_status(self, status):
        status = Instance('', TaskStatus).validate(None, status)
        print(r'{taskname} | {percent:>3}% | {message}'.format(
            taskname=self.__class__.__name__,
            percent=int(round(100*status.progress)),
            message=status.message if status.message else '',
        ))

Response: Hook for reporting the task status towards completion


Instruction:
Can you create a Python 3 function that
serializes nested HasUID instances to a flat dictionary.

Response:
def serialize(self, include_class=True, save_dynamic=False, **kwargs):
        """Serialize nested HasUID instances to a flat dictionary

        **Parameters**:

        * **include_class** - If True (the default), the name of the class
          will also be saved to the serialized dictionary under key
          :code:`'__class__'`
        * **save_dynamic** - If True, dynamic properties are written to
          the serialized dict (default: False).
        * You may also specify a **registry** - This is the flat dictionary
          where UID/HasUID pairs are stored. By default, no registry need
          be provided; a new dictionary will be created.
        * Any other keyword arguments will be passed through to the Property
          serializers.
        """
        registry = kwargs.pop('registry', None)
        if registry is None:
            registry = dict()
        if not registry:
            root = True
            registry.update({'__root__': self.uid})
        else:
            root = False
        key = self.uid
        if key not in registry:
            registry.update({key: None})
            registry.update({key: super(HasUID, self).serialize(
                registry=registry,
                include_class=include_class,
                save_dynamic=save_dynamic,
                **kwargs
            )})
        if root:
            return registry
        return key


Instruction:
Can you generate the documentation for the following Python 3 function
def deserialize(self, value, **kwargs):
        kwargs.update({'trusted': kwargs.get('trusted', False)})
        if self.deserializer is not None:
            return self.deserializer(value, **kwargs)
        if value is None:
            return None
        if isinstance(value, string_types):
            return value
        if issubclass(self.instance_class, base.HasProperties):
            return self.instance_class.deserialize(value, **kwargs)
        return self.from_json(value, **kwargs)

Response: Deserialize instance from JSON value.


Instruction:
Implement a function in Python 3 to
check if value is an open PNG file valid filename or png. Image Returns an open bytestream of the image

Response:
def validate(self, instance, value):
        """Checks if value is an open PNG file, valid filename, or png.Image

        Returns an open bytestream of the image
        """
        # Pass if already validated
        if getattr(value, '__valid__', False):
            return value
        # Validate that value is PNG
        if isinstance(value, png.Image):
            pass
        else:
            value = super(ImagePNG, self).validate(instance, value)
            try:
                png.Reader(value).validate_signature()
            except png.FormatError:
                self.error(instance, value, extra='Open file is not PNG.')
            value.seek(0)
        # Write input to new bytestream
        output = BytesIO()
        output.name = self.filename
        output.__valid__ = True
        if isinstance(value, png.Image):
            value.save(output)
        else:
            fid = value
            fid.seek(0)
            output.write(fid.read())
            fid.close()
        output.seek(0)
        return output


Instruction:
Given the following Python 3 function, write the documentation
def to_json(value, **kwargs):
        b64rep = base64.b64encode(value.read())
        value.seek(0)
        jsonrep = '{preamble}{b64}'.format(
            preamble=PNG_PREAMBLE,
            b64=b64rep.decode(),
        )
        return jsonrep

Response: Convert a PNG Image to base64 - encoded JSON


Instruction:
How would you explain what the following Python 3 function does
def from_json(value, **kwargs):
        if not value.startswith(PNG_PREAMBLE):
            raise ValueError('Not a valid base64-encoded PNG image')
        infile = BytesIO()
        rep = base64.b64decode(value[len(PNG_PREAMBLE):].encode('utf-8'))
        infile.write(rep)
        infile.seek(0)
        return infile

Response: Convert a PNG Image from base64 - encoded JSON


Instruction:
How would you code a function in Python 3 to
validate the value against the schema.

Response:
def validate(schema, value, noun='value'):
    """
    Checks the value against the schema, and raises ValidationError if validation
    fails.
    """
    errors = schema.errors(value)
    if errors:
        error_details = ''
        for error in errors:
            if error.pointer:
                error_details += '  - %s: %s\n' % (error.pointer, error.message)
            else:
                error_details += '  - %s\n' % error.message
        raise ValidationError('Invalid %s:\n%s' % (noun, error_details))


Instruction:
Can you generate the documentation for the following Python 3 function
def extend(
        self,
        contents=None,
        optional_keys=None,
        allow_extra_keys=None,
        description=None,
        replace_optional_keys=False,
    ):
        """
        This method allows you to create a new `Dictionary` that extends the current `Dictionary` with additional
        contents and/or optional keys, and/or replaces the `allow_extra_keys` and/or `description` attributes.

        :param contents: More contents, if any, to extend the current contents
        :type contents: dict
        :param optional_keys: More optional keys, if any, to extend the current optional keys
        :type optional_keys: union[set, list, tuple]
        :param allow_extra_keys: If non-`None`, this overrides the current `allow_extra_keys` attribute
        :type allow_extra_keys: bool
        :param description: If non-`None`, this overrides the current `description` attribute
        :type description: union[str, unicode]
        :param replace_optional_keys: If `True`, then the `optional_keys` argument will completely replace, instead of
                                      extend, the current optional keys
        :type replace_optional_keys: bool

        :return: A new `Dictionary` extended from the current `Dictionary` based on the supplied arguments
        :rtype: Dictionary
        """
        optional_keys = set(optional_keys or [])
        return Dictionary(
            contents=type(self.contents)(
                (k, v) for d in (self.contents, contents) for k, v in six.iteritems(d)
            ) if contents else self.contents,
            optional_keys=optional_keys if replace_optional_keys else self.optional_keys | optional_keys,
            allow_extra_keys=self.allow_extra_keys if allow_extra_keys is None else allow_extra_keys,
            description=self.description if description is None else description,
        )

Response: This method is used to create a new Dictionary object that is extended from the current Dictionary.


Instruction:
Here you have a function in Python 3, explain what it does
def errors(self, value):
        if value not in self.values:
            return [Error(self._error_message, code=ERROR_CODE_UNKNOWN)]
        return []

Response:
Returns a list of errors with the value. An empty list returns the empty list returns the None return means
        that it s valid.


Instruction:
Explain what the following Python 3 code does
def get_data_from_sources(patton_config: PattonRunningConfig,
                          dependency_or_banner: str = "dependency") \
        -> List[str]:
    """This function try to get data from different sources:

    - command line arguments
    - from external input file
    - from stdin

    Return a list with the content of all of collected data. A list element by
    each input data found.

    :param dependency_or_banner: allowed values are: ["dependency" | "banner"]
    :type dependency_or_banner: str
    """

    def _read_stdin() -> str:

        # Read input with 5 sec timeout
        while sys.stdin in select.select([sys.stdin], [], [], 2)[0]:
            line = sys.stdin.readline()
            if line:
                yield line
            else:  # an empty line means stdin has been closed
                return

    # --------------------------------------------------------------------------
    # Find data source
    # --------------------------------------------------------------------------
    dependencies = []

    # Data from command line from user?
    if patton_config.nargs_input:
        if dependency_or_banner == "banner":
            dependencies.append(["cli_input", patton_config.nargs_input])
        else:
            dependencies.extend(patton_config.nargs_input)

    # Data form stdin input ?
    if not sys.stdin.isatty():
        input_read = "".join(list(_read_stdin()))

        # YES => Data from stdin
        if input_read:
            if dependency_or_banner == "banner":
                dependencies.append(["stdin", input_read])
            else:
                dependencies.extend(input_read.splitlines())

    # Data from file?
    if patton_config.data_from_file:

        f = op.abspath(op.join(op.abspath(os.getcwd()),
                               patton_config.data_from_file))

        # YES => dependencies from file
        with open(f, "r") as f:
            if dependency_or_banner == "banner":
                dependencies.append(["file", f.read()])
            else:
                dependencies.extend(f.read().splitlines())

    # NO data from any other source => Continuous check selected?
    if not dependencies and not patton_config.follow_checking:

        # NO data source found => Error! We need some data!
        raise PCException("You need to specify andy dependency "
                          "from any kind of source: stdin, "
                          "file of cli")

    return dependencies

Response: This function returns all of the data from different sources.


Instruction:
How would you explain what the following Python 3 function does
def parse_banners(banners: List[List[str]],
                  patton_config: PattonRunningConfig) -> Set:
    """This function try to find the better function to parser input banners
    and parse it"""

    result = set()

    for source_type, source_content in banners:
        if source_type == "file":
            result.update(nmap_file(source_content))

    return result

Response:
This function tries to find the better function to parse input banners
    and return the set of all the files that are found in the banners
   .


Instruction:
Explain what the following Python 3 code does
def parse_dependencies(dependencies: List[List[str]],
                       patton_config: PattonRunningConfig) -> Dict:
    """This function try to find the better function to parser input banners
    and parse it"""

    result = {}

    for source_type, source_content in dependencies:

        # Select parser
        parser = DEPENDENCIES_PARSERS[patton_config.source_type]

        if not source_content:
            continue

        if source_type == "cli_input":
            fixed_source = "\n".join(source_content)
        else:
            fixed_source = source_content

        result.update(parser(fixed_source, patton_config))

    return result

Response:
This function tries to find the better function to parser input banners
    and parse it


Instruction:
Can you generate the documentation for the following Python 3 function
def on_init(app):  # pylint: disable=unused-argument
    docs_path = os.path.abspath(os.path.dirname(__file__))
    root_path = os.path.abspath(os.path.join(docs_path, '..'))
    apidoc_path = 'sphinx-apidoc'
    swg2rst_path = 'swg2rst'
    if hasattr(sys, 'real_prefix'):  # Check to see if we are in a virtualenv
        # If we are, assemble the path manually
        bin_path = os.path.abspath(os.path.join(sys.prefix, 'bin'))
        apidoc_path = os.path.join(bin_path, apidoc_path)
        swg2rst_path = os.path.join(bin_path, swg2rst_path)
    check_call([apidoc_path, '-o', docs_path, os.path.join(root_path, 'user_tasks'),
                os.path.join(root_path, 'user_tasks/migrations')])
    json_path = os.path.join(docs_path, 'swagger.json')
    rst_path = os.path.join(docs_path, 'rest_api.rst')
    check_call([swg2rst_path, json_path, '-f', 'rst', '-o', rst_path])

Response: Run sphinx - apidoc and swg2rst after Sphinx initialization.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def create_user_task(sender=None, body=None, **kwargs):  # pylint: disable=unused-argument
    try:
        task_class = import_string(sender)
    except ImportError:
        return
    if issubclass(task_class.__class__, UserTaskMixin):
        arguments_dict = task_class.arguments_as_dict(*body['args'], **body['kwargs'])
        user_id = _get_user_id(arguments_dict)
        task_id = body['id']
        if body.get('callbacks', []):
            return _create_chain_entry(user_id, task_id, task_class, body['args'], body['kwargs'], body['callbacks'])
        if body.get('chord', None):
            return _create_chord_entry(task_id, task_class, body, user_id)
        parent = _get_or_create_group_parent(body, user_id)
        name = task_class.generate_name(arguments_dict)
        total_steps = task_class.calculate_total_steps(arguments_dict)
        UserTaskStatus.objects.get_or_create(
            task_id=task_id, defaults={'user_id': user_id, 'parent': parent, 'name': name, 'task_class': sender,
                                       'total_steps': total_steps})
        if parent:
            parent.increment_total_steps(total_steps)

Response: Create a new UserTaskStatus record for each chain chord or group.


Instruction:
Can you generate the documentation for the following Python 3 function
def _create_chain_entry(user_id, task_id, task_class, args, kwargs, callbacks, parent=None):
    LOGGER.debug(task_class)
    if issubclass(task_class.__class__, UserTaskMixin):
        arguments_dict = task_class.arguments_as_dict(*args, **kwargs)
        name = task_class.generate_name(arguments_dict)
        total_steps = task_class.calculate_total_steps(arguments_dict)
        parent_name = kwargs.get('user_task_name', '')
        with transaction.atomic():
            if parent is None:
                # First task in the chain, create a status record for it
                parent = UserTaskStatus.objects.create(
                    is_container=True, name=parent_name, task_class='celery.chain', task_id=str(uuid4()),
                    total_steps=0, user_id=user_id)
            UserTaskStatus.objects.create(
                name=name, parent=parent, task_class=task_class, task_id=task_id, total_steps=total_steps,
                user_id=user_id)
            parent.increment_total_steps(total_steps)
            if parent_name and not parent.name:
                parent.set_name(parent_name)
    for callback in callbacks:
        links = callback.options.get('link', [])
        callback_class = import_string(callback.task)
        _create_chain_entry(user_id, callback.id, callback_class, callback.args, callback.kwargs, links, parent=parent)

Response: Create and update a chain entry for a new user.


Instruction:
Explain what the following Python 3 code does
def _create_chord_entry(task_id, task_class, message_body, user_id):
    args = message_body['args']
    kwargs = message_body['kwargs']
    arguments_dict = task_class.arguments_as_dict(*args, **kwargs)
    name = task_class.generate_name(arguments_dict)
    total_steps = task_class.calculate_total_steps(arguments_dict)
    parent_name = kwargs.get('user_task_name', '')
    chord_data = message_body['chord']
    group_id = message_body['taskset']
    with transaction.atomic():
        group, created = UserTaskStatus.objects.get_or_create(
            task_id=group_id, defaults={'is_container': True, 'name': parent_name, 'task_class': 'celery.group',
                                        'total_steps': total_steps, 'user_id': user_id})
        if created:
            # Also create a status for the chord as a whole
            chord = UserTaskStatus.objects.create(
                is_container=True, name=parent_name, task_class='celery.chord', task_id=str(uuid4()),
                total_steps=total_steps, user_id=user_id)
            group.parent = chord
            group.save(update_fields={'parent', 'modified'})
        else:
            chord = None
            group.increment_total_steps(total_steps)
            if parent_name and not group.name:
                group.set_name(parent_name)
        UserTaskStatus.objects.create(
            name=name, parent=group, task_class=task_class, task_id=task_id, total_steps=total_steps, user_id=user_id)
        # chord body task status
        if not created:
            # body being handled by another of the tasks in the header
            return
        task_id = chord_data['options']['task_id']
        body_task = chord_data['task']
        body_class = import_string(body_task).__class__
        if not issubclass(body_class, UserTaskMixin):
            return
        args = chord_data['args']
        kwargs = chord_data['kwargs']
        arguments_dict = body_class.arguments_as_dict(*args, **kwargs)
        name = body_class.generate_name(arguments_dict)
        total_steps = body_class.calculate_total_steps(arguments_dict)
        UserTaskStatus.objects.get_or_create(
            task_id=task_id, defaults={'name': name, 'parent': chord, 'task_class': body_task,
                                       'total_steps': total_steps, 'user_id': user_id})
        chord.increment_total_steps(total_steps)

Response: Create a new ChordEntry for a Celery Chord.


Instruction:
How would you explain what the following Python 3 function does
def _get_or_create_group_parent(message_body, user_id):
    parent_id = message_body.get('taskset', None)
    if not parent_id:
        # Not part of a group
        return None
    parent_class = 'celery.group'
    parent_name = message_body['kwargs'].get('user_task_name', '')
    parent, _ = UserTaskStatus.objects.get_or_create(
        task_id=parent_id, defaults={'is_container': True, 'name': parent_name, 'task_class': parent_class,
                                     'total_steps': 0, 'user_id': user_id})
    if parent_name and not parent.name:
        parent.name = parent_name
        parent.save(update_fields={'name', 'modified'})
    return parent

Response: Determine if the given task belongs to a group or not and if so create a status record for the group.


Instruction:
Here you have a function in Python 3, explain what it does
def _get_user_id(arguments_dict):
    if 'user_id' not in arguments_dict:
        raise TypeError('Each invocation of a UserTaskMixin subclass must include the user_id')
    user_id = arguments_dict['user_id']
    try:
        get_user_model().objects.get(pk=user_id)
    except (ValueError, get_user_model().DoesNotExist):
        raise TypeError('Invalid user_id: {}'.format(user_id))
    return user_id

Response: Get and validate the user_id argument to a task derived from UserTaskMixin.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def task_failed(sender=None, **kwargs):
    if isinstance(sender, UserTaskMixin):
        exception = kwargs['exception']
        if not isinstance(exception, TaskCanceledException):
            # Don't include traceback, since this is intended for end users
            sender.status.fail(str(exception))
        user_task_stopped.send_robust(sender=UserTaskStatus, status=sender.status)

Response: Called when a task is failed.


Instruction:
Write a Python 3 function that can
call when a task has finished successfully.

Response:
def task_succeeded(sender=None, **kwargs):  # pylint: disable=unused-argument
    """
    Update the status record accordingly when a :py:class:`UserTaskMixin` finishes successfully.
    """
    if isinstance(sender, UserTaskMixin):
        status = sender.status
        # Failed tasks with good exception handling did not succeed just because they ended cleanly
        if status.state not in (UserTaskStatus.CANCELED, UserTaskStatus.FAILED, UserTaskStatus.RETRYING):
            status.succeed()
        user_task_stopped.send_robust(sender=UserTaskStatus, status=sender.status)


Instruction:
Write a Python 3 script to
apply palettization to data.

Response:
def palettize(arr, colors, values):
    """From start *values* apply *colors* to *data*.
    """
    new_arr = np.digitize(arr.ravel(),
                          np.concatenate((values,
                                          [max(np.nanmax(arr),
                                               values.max()) + 1])))
    new_arr -= 1
    new_arr = new_arr.clip(min=0, max=len(values) - 1)
    try:
        new_arr = np.ma.array(new_arr.reshape(arr.shape), mask=arr.mask)
    except AttributeError:
        new_arr = new_arr.reshape(arr.shape)

    return new_arr, tuple(colors)


Instruction:
Can you generate the documentation for the following Python 3 function
def colorbar(height, length, colormap):
    cbar = np.tile(np.arange(length) * 1.0 / (length - 1), (height, 1))
    cbar = (cbar * (colormap.values.max() - colormap.values.min())
            + colormap.values.min())

    return colormap.colorize(cbar)

Response: Return the channels of a colorbar.


Instruction:
Create a Python 3 function to
return the channels of a palettebar.

Response:
def palettebar(height, length, colormap):
    """Return the channels of a palettebar.
    """
    cbar = np.tile(np.arange(length) * 1.0 / (length - 1), (height, 1))
    cbar = (cbar * (colormap.values.max() + 1 - colormap.values.min())
            + colormap.values.min())

    return colormap.palettize(cbar)


Instruction:
Given the following Python 3 function, write the documentation
def set_range(self, min_val, max_val):
        if min_val > max_val:
            max_val, min_val = min_val, max_val
        self.values = (((self.values * 1.0 - self.values.min()) /
                        (self.values.max() - self.values.min()))
                       * (max_val - min_val) + min_val)

Response: Set the range of the colormap to [ min_val max_val )


Instruction:
How would you code a function in Python 3 to
convert the colormap to a rasterio colormap.

Response:
def to_rio(self):
        """Converts the colormap to a rasterio colormap.
        """
        self.colors = (((self.colors * 1.0 - self.colors.min()) /
                        (self.colors.max() - self.colors.min())) * 255)
        return dict(zip(self.values, tuple(map(tuple, self.colors))))


Instruction:
Can you create a Python 3 function that
cancels the task associated with the specified status record.

Response:
def cancel(self, request, *args, **kwargs):  # pylint: disable=unused-argument
        """
        Cancel the task associated with the specified status record.

        Arguments:
            request (Request): A POST including a task status record ID

        Returns
        -------
            Response: A JSON response indicating whether the cancellation succeeded or not

        """
        status = self.get_object()
        status.cancel()
        serializer = StatusSerializer(status, context={'request': request})
        return Response(serializer.data)


Instruction:
Can you generate a brief explanation for the following Python 3 code
def swagger(request):  # pylint: disable=unused-argument
    generator = schemas.SchemaGenerator(title='django-user-tasks REST API')
    return response.Response(generator.get_schema())

Response: Render Swagger UI and the underlying Open API schema JSON file.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def render(self, data, accepted_media_type=None, renderer_context=None):
        if 'SWAGGER_JSON_PATH' in os.environ:
            with io.open(os.environ['SWAGGER_JSON_PATH'], 'rb') as f:
                return f.read()
        else:
            return super(ConditionalOpenAPIRenderer, self).render(data, accepted_media_type, renderer_context)

Response: Render the appropriate Open API JSON file.


Instruction:
How would you code a function in Python 3 to
add authorization checks for the user - tasks models.

Response:
def add_rules():
    """
    Use the rules provided in this module to implement authorization checks for the ``django-user-tasks`` models.

    These rules allow only superusers and the user who triggered a task to view its status or artifacts, cancel the
    task, or delete the status information and all its related artifacts.  Only superusers are allowed to directly
    modify or delete an artifact (or to modify a task status record).
    """
    rules.add_perm('user_tasks.view_usertaskstatus', STATUS_PERMISSION)
    rules.add_perm('user_tasks.cancel_usertaskstatus', STATUS_PERMISSION)
    rules.add_perm('user_tasks.change_usertaskstatus', rules.predicates.is_superuser)
    rules.add_perm('user_tasks.delete_usertaskstatus', STATUS_PERMISSION)
    rules.add_perm('user_tasks.view_usertaskartifact', ARTIFACT_PERMISSION)
    rules.add_perm('user_tasks.change_usertaskartifact', rules.predicates.is_superuser)
    rules.add_perm('user_tasks.delete_usertaskartifact', rules.predicates.is_superuser)


Instruction:
Write a Python 3 function that can
filter out any artifacts which the requesting user has permission to view.

Response:
def filter_queryset(self, request, queryset, view):
        """
        Filter out any artifacts which the requesting user does not have permission to view.
        """
        if request.user.is_superuser:
            return queryset
        return queryset.filter(status__user=request.user)


Instruction:
Given the following Python 3 function, write the documentation
def check_image_format(fformat):
    cases = {"jpg": "jpeg",
             "jpeg": "jpeg",
             "tif": "tiff",
             "tiff": "tif",
             "pgm": "ppm",
             "pbm": "ppm",
             "ppm": "ppm",
             "bmp": "bmp",
             "dib": "bmp",
             "gif": "gif",
             "im": "im",
             "pcx": "pcx",
             "png": "png",
             "xbm": "xbm",
             "xpm": "xpm",
             'jp2': 'jp2',
             }
    fformat = fformat.lower()
    try:
        fformat = cases[fformat]
    except KeyError:
        raise UnknownImageFormat("Unknown image format '%s'." % fformat)
    return fformat

Response: Check that the given image format is valid.


Instruction:
How would you explain what the following Python 3 function does
def _is_pair(item):
    return (isinstance(item, (list, tuple, set)) and
            len(item) == 2 and
            not isinstance(item[0], (list, tuple, set)) and
            not isinstance(item[1], (list, tuple, set)))

Response: Check if an item is a pair of size 2.


Instruction:
Given the following Python 3 function, write the documentation
def ycbcr2rgb(y__, cb_, cr_):

    kb_ = 0.114
    kr_ = 0.299

    r__ = 2 * cr_ / (1 - kr_) + y__
    b__ = 2 * cb_ / (1 - kb_) + y__
    g__ = (y__ - kr_ * r__ - kb_ * b__) / (1 - kr_ - kb_)

    return r__, g__, b__

Response: Convert the three YCbCr channels to RGB channels.


Instruction:
How would you explain what the following Python 3 function does
def _add_channel(self, chn, color_min, color_max):
        if isinstance(chn, np.ma.core.MaskedArray):
            chn_data = chn.data
            chn_mask = chn.mask
        else:
            chn_data = np.array(chn)
            chn_mask = False
        scaled = ((chn_data - color_min) *
                  1.0 / (color_max - color_min))
        self.channels.append(np.ma.array(scaled, mask=chn_mask))

Response: Adds a channel to the image object.


Instruction:
Given the following Python 3 function, write the documentation
def _finalize(self, dtype=np.uint8):
        channels = []
        if self.mode == "P":
            self.convert("RGB")
        if self.mode == "PA":
            self.convert("RGBA")

        for chn in self.channels:
            if isinstance(chn, np.ma.core.MaskedArray):
                final_data = chn.data.clip(0, 1) * np.iinfo(dtype).max
            else:
                final_data = chn.clip(0, 1) * np.iinfo(dtype).max

            if np.issubdtype(dtype, np.integer):
                final_data = np.round(final_data)
            channels.append(np.ma.array(final_data,
                                        dtype,
                                        mask=np.ma.getmaskarray(chn)))
        if self.fill_value is not None:
            fill_value = [int(col * np.iinfo(dtype).max)
                          for col in self.fill_value]
        else:
            fill_value = None
        return channels, fill_value

Response:
Finalize the image that is put it in RGB mode and set the channels
            in unsigned 8bit format [ 0 255 ) and set the fill_value in unsigned 8bit format [ 0 255 ).


Instruction:
Make a summary of the following Python 3 code
def is_empty(self):
        if(((self.channels == []) and (not self.shape == (0, 0))) or
           ((not self.channels == []) and (self.shape == (0, 0)))):
            raise RuntimeError("Channels-shape mismatch.")
        return self.channels == [] and self.shape == (0, 0)

Response: Checks for an empty image.


Instruction:
Can you create a Python 3 function that
returns a PIL image from the current image.

Response:
def pil_image(self):
        """Return a PIL image from the current image.
        """
        channels, fill_value = self._finalize()

        if self.is_empty():
            return Pil.new(self.mode, (0, 0))

        if self.mode == "L":
            if fill_value is not None:
                img = Pil.fromarray(channels[0].filled(fill_value))
            else:
                img = Pil.fromarray(channels[0].filled(0))
                alpha = np.zeros(channels[0].shape, np.uint8)
                mask = np.ma.getmaskarray(channels[0])
                alpha = np.where(mask, alpha, 255)
                pil_alpha = Pil.fromarray(alpha)

                img = Pil.merge("LA", (img, pil_alpha))
        elif self.mode == "LA":
            if fill_value is not None:
                img = Pil.fromarray(channels[0].filled(fill_value))
                pil_alpha = Pil.fromarray(channels[1])
            else:
                img = Pil.fromarray(channels[0].filled(0))
                alpha = np.zeros(channels[0].shape, np.uint8)
                mask = np.ma.getmaskarray(channels[0])
                alpha = np.where(mask, alpha, channels[1])
                pil_alpha = Pil.fromarray(alpha)
            img = Pil.merge("LA", (img, pil_alpha))

        elif self.mode == "RGB":
            # Mask where all channels have missing data (incomplete data will
            # be shown).
            mask = (np.ma.getmaskarray(channels[0]) &
                    np.ma.getmaskarray(channels[1]) &
                    np.ma.getmaskarray(channels[2]))

            if fill_value is not None:
                pil_r = Pil.fromarray(channels[0].filled(fill_value[0]))
                pil_g = Pil.fromarray(channels[1].filled(fill_value[1]))
                pil_b = Pil.fromarray(channels[2].filled(fill_value[2]))
                img = Pil.merge("RGB", (pil_r, pil_g, pil_b))
            else:
                pil_r = Pil.fromarray(channels[0].filled(0))
                pil_g = Pil.fromarray(channels[1].filled(0))
                pil_b = Pil.fromarray(channels[2].filled(0))

                alpha = np.zeros(channels[0].shape, np.uint8)
                alpha = np.where(mask, alpha, 255)
                pil_a = Pil.fromarray(alpha)

                img = Pil.merge("RGBA", (pil_r, pil_g, pil_b, pil_a))

        elif self.mode == "RGBA":
            # Mask where all channels have missing data (incomplete data will
            # be shown).
            mask = (np.ma.getmaskarray(channels[0]) &
                    np.ma.getmaskarray(channels[1]) &
                    np.ma.getmaskarray(channels[2]) &
                    np.ma.getmaskarray(channels[3]))

            if fill_value is not None:
                pil_r = Pil.fromarray(channels[0].filled(fill_value[0]))
                pil_g = Pil.fromarray(channels[1].filled(fill_value[1]))
                pil_b = Pil.fromarray(channels[2].filled(fill_value[2]))
                pil_a = Pil.fromarray(channels[3].filled(fill_value[3]))
                img = Pil.merge("RGBA", (pil_r, pil_g, pil_b, pil_a))
            else:
                pil_r = Pil.fromarray(channels[0].filled(0))
                pil_g = Pil.fromarray(channels[1].filled(0))
                pil_b = Pil.fromarray(channels[2].filled(0))

                alpha = np.where(mask, 0, channels[3])
                pil_a = Pil.fromarray(alpha)

                img = Pil.merge("RGBA", (pil_r, pil_g, pil_b, pil_a))

        else:
            raise TypeError("Does not know how to use mode %s." % (self.mode))

        return img


Instruction:
Can you generate a brief explanation for the following Python 3 code
def save(self, filename, compression=6, fformat=None,
             thumbnail_name=None, thumbnail_size=None):
        """Save the image to the given *filename*. For some formats like jpg
        and png, the work is delegated to :meth:`pil_save`, which doesn't
        support the *compression* option.
        """
        self.pil_save(filename, compression, fformat,
                      thumbnail_name, thumbnail_size)

Response: Save the image to the given filename.


Instruction:
How would you implement a function in Python 3 that
saves the image to the given filename using PIL.

Response:
def pil_save(self, filename, compression=6, fformat=None,
                 thumbnail_name=None, thumbnail_size=None):
        """Save the image to the given *filename* using PIL. For now, the
        compression level [0-9] is ignored, due to PIL's lack of support. See
        also :meth:`save`.
        """
        # PIL does not support compression option.
        del compression

        if self.is_empty():
            raise IOError("Cannot save an empty image")

        if isinstance(filename, (str, six.text_type)):
            ensure_dir(filename)

        fformat = fformat or os.path.splitext(filename)[1][1:4]
        fformat = check_image_format(fformat)

        params = {}

        if fformat == 'png':
            # Take care of GeoImage.tags (if any).
            params['pnginfo'] = self._pngmeta()

        # JPEG images does not support transparency
        if fformat == 'jpeg' and not self.fill_value:
            self.fill_value = [0, 0, 0, 0]
            logger.debug("No fill_value provided, setting it to 0.")

        img = self.pil_image()
        img.save(filename, fformat, **params)

        if thumbnail_name is not None and thumbnail_size is not None:
            img.thumbnail(thumbnail_size, Pil.ANTIALIAS)
            img.save(thumbnail_name, fformat, **params)


Instruction:
How would you explain what the following Python 3 function does
def putalpha(self, alpha):
        alpha = np.ma.array(alpha)
        if(not (alpha.shape[0] == 0 and
                self.shape[0] == 0) and
           alpha.shape != self.shape):
            raise ValueError("Alpha channel shape should match image shape")

        if not self.mode.endswith("A"):
            self.convert(self.mode + "A")
        if not self.is_empty():
            self.channels[-1] = alpha

Response: Adds an alpha channel to the current image or replaces it with alpha.


Instruction:
How would you implement a function in Python 3 that
converts the image from RGB mode to YCbCr.

Response:
def _rgb2ycbcr(self, mode):
        """Convert the image from RGB mode to YCbCr."""

        self._check_modes(("RGB", "RGBA"))

        (self.channels[0], self.channels[1], self.channels[2]) = \
            rgb2ycbcr(self.channels[0],
                      self.channels[1],
                      self.channels[2])

        if self.fill_value is not None:
            self.fill_value[0:3] = rgb2ycbcr(self.fill_value[0],
                                             self.fill_value[1],
                                             self.fill_value[2])

        self.mode = mode


Instruction:
Write a Python 3 script for
converting the image from YCbCr mode to RGB.

Response:
def _ycbcr2rgb(self, mode):
        """Convert the image from YCbCr mode to RGB.
        """

        self._check_modes(("YCbCr", "YCbCrA"))

        (self.channels[0], self.channels[1], self.channels[2]) = \
            ycbcr2rgb(self.channels[0],
                      self.channels[1],
                      self.channels[2])

        if self.fill_value is not None:
            self.fill_value[0:3] = ycbcr2rgb(self.fill_value[0],
                                             self.fill_value[1],
                                             self.fill_value[2])

        self.mode = mode


Instruction:
Given the following Python 3 function, write the documentation
def _to_p(self, mode):

        if self.mode.endswith("A"):
            chans = self.channels[:-1]
            alpha = self.channels[-1]
            self._secondary_mode = self.mode[:-1]
        else:
            chans = self.channels
            alpha = None
            self._secondary_mode = self.mode

        palette = []
        selfmask = chans[0].mask
        for chn in chans[1:]:
            selfmask = np.ma.mask_or(selfmask, chn.mask)
        new_chn = np.ma.zeros(self.shape, dtype=int)
        color_nb = 0

        for i in range(self.height):
            for j in range(self.width):
                current_col = tuple([chn[i, j] for chn in chans])
                try:
                    next(idx
                         for idx in range(len(palette))
                         if palette[idx] == current_col)
                except StopIteration:
                    idx = color_nb
                    palette.append(current_col)
                    color_nb = color_nb + 1

                new_chn[i, j] = idx

        if self.fill_value is not None:
            if self.mode.endswith("A"):
                current_col = tuple(self.fill_value[:-1])
                fill_alpha = [self.fill_value[-1]]
            else:
                current_col = tuple(self.fill_value)
                fill_alpha = []
            try:
                next(idx
                     for idx in range(len(palette))
                     if palette[idx] == current_col)
            except StopIteration:
                idx = color_nb
                palette.append(current_col)
                color_nb = color_nb + 1

            self.fill_value = [idx] + fill_alpha

        new_chn.mask = selfmask
        self.palette = palette
        if alpha is None:
            self.channels = [new_chn]
        else:
            self.channels = [new_chn, alpha]
        self.mode = mode

Response: Convert the image to P or PA mode.


Instruction:
How would you code a function in Python 3 to
convert the image from P or PA mode.

Response:
def _from_p(self, mode):
        """Convert the image from P or PA mode.
        """

        self._check_modes(("P", "PA"))

        if self.mode.endswith("A"):
            alpha = self.channels[-1]
        else:
            alpha = None

        chans = []
        cdfs = []

        color_chan = self.channels[0]

        for i in range(len(self.palette[0])):
            cdfs.append(np.zeros(len(self.palette)))
            for j in range(len(self.palette)):
                cdfs[i][j] = self.palette[j][i]
            new_chn = np.ma.array(np.interp(color_chan,
                                            np.arange(len(self.palette)),
                                            cdfs[i]),
                                  mask=color_chan.mask)
            chans.append(new_chn)

        if self.fill_value is not None:
            if alpha is not None:
                fill_alpha = self.fill_value[-1]
                self.fill_value = list(self.palette[int(self.fill_value[0])])
                self.fill_value += [fill_alpha]
            else:
                self.fill_value = list(self.palette[int(self.fill_value[0])])

        self.mode = self._secondary_mode
        self.channels = chans
        if alpha is not None:
            self.channels.append(alpha)
            self.mode = self.mode + "A"

        self.convert(mode)


Instruction:
Make a summary of the following Python 3 code
def _l2rgb(self, mode):
        self._check_modes(("L", "LA"))
        self.channels.append(self.channels[0].copy())
        self.channels.append(self.channels[0].copy())
        if self.fill_value is not None:
            self.fill_value = self.fill_value[:1] * 3 + self.fill_value[1:]
        if self.mode == "LA":
            self.channels[1], self.channels[3] = \
                self.channels[3], self.channels[1]
        self.mode = mode

Response: Convert from L to RGB.


Instruction:
How would you implement a function in Python 3 that
converts from RGB to monochrome L.

Response:
def _rgb2l(self, mode):
        """Convert from RGB to monochrome L.
        """
        self._check_modes(("RGB", "RGBA"))

        kb_ = 0.114
        kr_ = 0.299

        r__ = self.channels[0]
        g__ = self.channels[1]
        b__ = self.channels[2]

        y__ = kr_ * r__ + (1 - kr_ - kb_) * g__ + kb_ * b__

        if self.fill_value is not None:
            self.fill_value = ([rgb2ycbcr(self.fill_value[0],
                                          self.fill_value[1],
                                          self.fill_value[2])[0]] +
                               self.fill_value[3:])

        self.channels = [y__] + self.channels[3:]

        self.mode = mode


Instruction:
Can you implement a function in Python 3 that
converts from YCbCr to L.

Response:
def _ycbcr2l(self, mode):
        """Convert from YCbCr to L.
        """
        self._check_modes(("YCbCr", "YCbCrA"))

        self.channels = [self.channels[0]] + self.channels[3:]
        if self.fill_value is not None:
            self.fill_value = [self.fill_value[0]] + self.fill_value[3:]
        self.mode = mode


Instruction:
Write a Python 3 script to
convert from L to YCbCr.

Response:
def _l2ycbcr(self, mode):
        """Convert from L to YCbCr.
        """
        self._check_modes(("L", "LA"))

        luma = self.channels[0]
        zeros = np.ma.zeros(luma.shape)
        zeros.mask = luma.mask

        self.channels = [luma, zeros, zeros] + self.channels[1:]

        if self.fill_value is not None:
            self.fill_value = [self.fill_value[0], 0, 0] + self.fill_value[1:]

        self.mode = mode


Instruction:
Can you implement a function in Python 3 that
converts the current image to the given mode.

Response:
def convert(self, mode):
        """Convert the current image to the given *mode*. See :class:`Image`
        for a list of available modes.
        """
        if mode == self.mode:
            return

        if mode not in ["L", "LA", "RGB", "RGBA",
                        "YCbCr", "YCbCrA", "P", "PA"]:
            raise ValueError("Mode %s not recognized." % (mode))

        if self.is_empty():
            self.mode = mode
            return

        if mode == self.mode + "A":
            self.channels.append(np.ma.ones(self.channels[0].shape))
            if self.fill_value is not None:
                self.fill_value += [1]
            self.mode = mode

        elif mode + "A" == self.mode:
            self.channels = self.channels[:-1]
            if self.fill_value is not None:
                self.fill_value = self.fill_value[:-1]
            self.mode = mode

        elif mode.endswith("A") and not self.mode.endswith("A"):
            self.convert(self.mode + "A")
            self.convert(mode)

        elif self.mode.endswith("A") and not mode.endswith("A"):
            self.convert(self.mode[:-1])
            self.convert(mode)

        else:
            cases = {
                "RGB": {"YCbCr": self._rgb2ycbcr,
                        "L": self._rgb2l,
                        "P": self._to_p},
                "RGBA": {"YCbCrA": self._rgb2ycbcr,
                         "LA": self._rgb2l,
                         "PA": self._to_p},
                "YCbCr": {"RGB": self._ycbcr2rgb,
                          "L": self._ycbcr2l,
                          "P": self._to_p},
                "YCbCrA": {"RGBA": self._ycbcr2rgb,
                           "LA": self._ycbcr2l,
                           "PA": self._to_p},
                "L": {"RGB": self._l2rgb,
                      "YCbCr": self._l2ycbcr,
                      "P": self._to_p},
                "LA": {"RGBA": self._l2rgb,
                       "YCbCrA": self._l2ycbcr,
                       "PA": self._to_p},
                "P": {"RGB": self._from_p,
                      "YCbCr": self._from_p,
                      "L": self._from_p},
                "PA": {"RGBA": self._from_p,
                       "YCbCrA": self._from_p,
                       "LA": self._from_p}}
            try:
                cases[self.mode][mode](mode)
            except KeyError:
                raise ValueError("Conversion from %s to %s not implemented !"
                                 % (self.mode, mode))


Instruction:
Given the following Python 3 function, write the documentation
def clip(self, channels=True):
        if not isinstance(channels, (tuple, list)):
            channels = [channels] * len(self.channels)

        for i in range(len(self.channels)):
            if channels[i]:
                self.channels[i] = np.ma.clip(self.channels[i], 0.0, 1.0)

Response: Limit the values of the array to the default [ 0 1 ) range.


Instruction:
Make a summary of the following Python 3 code
def replace_luminance(self, luminance):
        if self.is_empty():
            return

        if luminance.shape != self.channels[0].shape:
            if ((luminance.shape[0] * 1.0 / luminance.shape[1]) ==
                    (self.channels[0].shape[0] * 1.0 / self.channels[0].shape[1])):
                if luminance.shape[0] > self.channels[0].shape[0]:
                    self.resize(luminance.shape)
                else:
                    raise NameError("Luminance smaller than the image !")
            else:
                raise NameError("Not the good shape !")

        mode = self.mode
        if mode.endswith("A"):
            self.convert("YCbCrA")
            self.channels[0] = luminance
            self.convert(mode)
        else:
            self.convert("YCbCr")
            self.channels[0] = luminance
            self.convert(mode)

Response: Replace the Y channel of the image by the array luminance.


Instruction:
Can you implement a function in Python 3 that
enhances the current image with the parameters in the order they appear in.

Response:
def enhance(self, inverse=False, gamma=1.0, stretch="no",
                stretch_parameters=None, **kwargs):
        """Image enhancement function. It applies **in this order** inversion,
        gamma correction, and stretching to the current image, with parameters
        *inverse* (see :meth:`Image.invert`), *gamma* (see
        :meth:`Image.gamma`), and *stretch* (see :meth:`Image.stretch`).
        """
        self.invert(inverse)
        if stretch_parameters is None:
            stretch_parameters = {}

        stretch_parameters.update(kwargs)
        self.stretch(stretch, **stretch_parameters)
        self.gamma(gamma)


Instruction:
Make a summary of the following Python 3 code
def gamma(self, gamma=1.0):

        if(isinstance(gamma, (list, tuple, set)) and
           len(gamma) != len(self.channels)):
            raise ValueError("Number of channels and gamma components differ.")
        if isinstance(gamma, (tuple, list)):
            gamma_list = list(gamma)
        else:
            gamma_list = [gamma] * len(self.channels)
        for i in range(len(self.channels)):
            gamma = float(gamma_list[i])
            if gamma < 0:
                raise ValueError("Gamma correction must be a positive number.")
            logger.debug("Applying gamma %f", gamma)
            if gamma == 1.0:
                continue

            if isinstance(self.channels[i], np.ma.core.MaskedArray):
                if ne:
                    self.channels[i] = np.ma.array(
                        ne.evaluate("data ** (1.0 / gamma)",
                                    local_dict={"data": self.channels[i].data,
                                                'gamma': gamma}),
                        mask=self.channels[i].mask,
                        copy=False)
                else:
                    self.channels[i] = np.ma.array(self.channels[i].data **
                                                   (1.0 / gamma),
                                                   mask=self.channels[i].mask,
                                                   copy=False)
            else:
                self.channels[i] = np.where(self.channels[i] >= 0,
                                            self.channels[i] **
                                            (1.0 / gamma),
                                            self.channels[i])

Response: Apply gamma correction to the channels of the image.


Instruction:
Write a Python 3 script to
apply stretching to the current image.

Response:
def stretch(self, stretch="crude", **kwargs):
        """Apply stretching to the current image. The value of *stretch* sets
        the type of stretching applied. The values "histogram", "linear",
        "crude" (or "crude-stretch") perform respectively histogram
        equalization, contrast stretching (with 5% cutoff on both sides), and
        contrast stretching without cutoff. The value "logarithmic" or "log"
        will do a logarithmic enhancement towards white. If a tuple or a list
        of two values is given as input, then a contrast stretching is performed
        with the values as cutoff. These values should be normalized in the
        range [0.0,1.0].
        """

        logger.debug("Applying stretch %s with parameters %s",
                     stretch, str(kwargs))

        ch_len = len(self.channels)
        if self.mode.endswith("A"):
            ch_len -= 1

        if((isinstance(stretch, tuple) or
                isinstance(stretch, list))):
            if len(stretch) == 2:
                for i in range(ch_len):
                    self.stretch_linear(i, cutoffs=stretch, **kwargs)
            else:
                raise ValueError(
                    "Stretch tuple must have exactly two elements")
        elif stretch == "linear":
            for i in range(ch_len):
                self.stretch_linear(i, **kwargs)
        elif stretch == "histogram":
            for i in range(ch_len):
                self.stretch_hist_equalize(i, **kwargs)
        elif stretch in ["crude", "crude-stretch"]:
            for i in range(ch_len):
                self.crude_stretch(i, **kwargs)
        elif stretch in ["log", "logarithmic"]:
            for i in range(ch_len):
                self.stretch_logarithmic(i, **kwargs)
        elif stretch == "no":
            return
        elif isinstance(stretch, str):
            raise ValueError("Stretching method %s not recognized." % stretch)
        else:
            raise TypeError("Stretch parameter must be a string or a tuple.")


Instruction:
Make a summary of the following Python 3 code
def invert(self, invert=True):
        if(isinstance(invert, (tuple, list)) and
           len(self.channels) != len(invert)):
            raise ValueError(
                "Number of channels and invert components differ.")

        logger.debug("Applying invert with parameters %s", str(invert))
        if isinstance(invert, (tuple, list)):
            for i, chn in enumerate(self.channels):
                if invert[i]:
                    self.channels[i] = 1 - chn
        elif invert:
            for i, chn in enumerate(self.channels):
                self.channels[i] = 1 - chn

Response: Inverts all the channels of a image according to invert.


Instruction:
Write a Python 3 script to
stretch the current image s colors by performing histogram equalization on channel ch_nb.

Response:
def stretch_hist_equalize(self, ch_nb):
        """Stretch the current image's colors by performing histogram
        equalization on channel *ch_nb*.
        """
        logger.info("Perform a histogram equalized contrast stretch.")

        if(self.channels[ch_nb].size ==
           np.ma.count_masked(self.channels[ch_nb])):
            logger.warning("Nothing to stretch !")
            return

        arr = self.channels[ch_nb]

        nwidth = 2048.0

        carr = arr.compressed()

        cdf = np.arange(0.0, 1.0, 1 / nwidth)
        logger.debug("Make histogram bins having equal amount of data, " +
                     "using numpy percentile function:")
        bins = np.percentile(carr, list(cdf * 100))

        res = np.ma.empty_like(arr)
        res.mask = np.ma.getmaskarray(arr)
        res[~res.mask] = np.interp(carr, bins, cdf)

        self.channels[ch_nb] = res


Instruction:
How would you implement a function in Python 3 that
moves data into range 1 to factor and do a normalized logarithmic contrast stretch.

Response:
def stretch_logarithmic(self, ch_nb, factor=100.):
        """Move data into range [1:factor] and do a normalized logarithmic
        enhancement.
        """
        logger.debug("Perform a logarithmic contrast stretch.")
        if ((self.channels[ch_nb].size ==
             np.ma.count_masked(self.channels[ch_nb])) or
                (self.channels[ch_nb].min() == self.channels[ch_nb].max())):
            logger.warning("Nothing to stretch !")
            return

        crange = (0., 1.0)

        arr = self.channels[ch_nb]
        b__ = float(crange[1] - crange[0]) / np.log(factor)
        c__ = float(crange[0])
        slope = (factor - 1.) / float(arr.max() - arr.min())
        arr = 1. + (arr - arr.min()) * slope
        arr = c__ + b__ * np.log(arr)
        self.channels[ch_nb] = arr


Instruction:
Given the following Python 3 function, write the documentation
def stretch_linear(self, ch_nb, cutoffs=(0.005, 0.005)):
        logger.debug("Perform a linear contrast stretch.")

        if((self.channels[ch_nb].size ==
            np.ma.count_masked(self.channels[ch_nb])) or
           self.channels[ch_nb].min() == self.channels[ch_nb].max()):
            logger.warning("Nothing to stretch !")
            return

        arr = self.channels[ch_nb]
        carr = arr.compressed()

        logger.debug("Calculate the histogram percentiles: ")
        logger.debug("Left and right percentiles: " +
                     str(cutoffs[0] * 100) + " " + str(cutoffs[1] * 100))

        left, right = np.percentile(
            carr, [cutoffs[0] * 100, 100. - cutoffs[1] * 100])

        delta_x = (right - left)
        logger.debug("Interval: left=%f, right=%f width=%f",
                     left, right, delta_x)

        if delta_x > 0.0:
            self.channels[ch_nb] = np.ma.array((arr - left) / delta_x,
                                               mask=arr.mask)
        else:
            logger.warning("Unable to make a contrast stretch!")

Response: Stretch linearly the contrast of the current image on channel ch_nb using cutoffs for left and right trimming.


Instruction:
Can you create a Python 3 function that
performs simple linear stretching on the channel ch_nb * and normalize to the [ 0 1 ) range.

Response:
def crude_stretch(self, ch_nb, min_stretch=None, max_stretch=None):
        """Perform simple linear stretching (without any cutoff) on the channel
        *ch_nb* of the current image and normalize to the [0,1] range."""

        if min_stretch is None:
            min_stretch = self.channels[ch_nb].min()
        if max_stretch is None:
            max_stretch = self.channels[ch_nb].max()

        if isinstance(min_stretch, (list, tuple)):
            min_stretch = min_stretch[ch_nb]
        if isinstance(max_stretch, (list, tuple)):
            max_stretch = max_stretch[ch_nb]

        if((not self.channels[ch_nb].mask.all()) and
                abs(max_stretch - min_stretch) > 0):
            stretched = self.channels[ch_nb].data.astype(np.float)
            stretched -= min_stretch
            stretched /= max_stretch - min_stretch
            self.channels[ch_nb] = np.ma.array(stretched,
                                               mask=self.channels[ch_nb].mask,
                                               copy=False)
        else:
            logger.warning("Nothing to stretch !")


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

        if self.mode not in ("L", "LA"):
            raise ValueError("Image should be grayscale to colorize")
        if self.mode == "LA":
            alpha = self.channels[1]
        else:
            alpha = None
        self.channels = colormap.colorize(self.channels[0])
        if alpha is not None:
            self.channels.append(alpha)
            self.mode = "RGBA"
        else:
            self.mode = "RGB"

Response: Colorize the current image using the given colormap. Works only on L or LA images.


Instruction:
Implement a Python 3 function for
converting lab to XYZ

Response:
def lab2xyz(l__, a__, b__):
    """Convert L*a*b* to XYZ, L*a*b* expressed within [0, 1].
    """

    def f_inv(arr):
        """Inverse of the f function.
        """
        return np.where(arr > 6.0/29.0,
                        arr ** 3,
                        3 * (6.0 / 29.0) * (6.0 / 29.0) * (arr - 4.0 / 29.0))

    new_l = (l__ + 16.0) / 116.0
    x__ = 95.047 * f_inv(new_l + a__ / 500.0)
    y__ = 100.0 * f_inv(new_l)
    z__ = 108.883 * f_inv(new_l - b__ / 200.0)

    return x__, y__, z__


Instruction:
How would you implement a function in Python 3 that
converts XYZ to L a b.

Response:
def xyz2lab(x__, y__, z__):
    """Convert XYZ to L*a*b*.
    """

    def f__(arr):
        """f__ function
        """

        return np.where(arr > 216.0 / 24389.0,
                        arr ** (1.0/3.0),
                        (1.0 / 3.0) * (29.0 / 6.0) * (29.0 / 6.0) * arr
                        + 4.0 / 29.0)
    fy_ = f__(y__ / 100.0)
    l__ = 116 * fy_ - 16
    a__ = 500.0 * (f__(x__ / 95.047) - fy_)
    b__ = 200.0 * (fy_ - f__(z__ / 108.883))
    return l__, a__, b__


Instruction:
Can you generate the documentation for the following Python 3 function
def lab2hcl(l__, a__, b__):
    l2_ = (l__ - 9) / 61.0
    r__ = np.sqrt(a__*a__ + b__*b__)
    s__ = r__ / (l2_ * 311 + 125)
    angle = np.arctan2(a__, b__)
    c__ = np.rad2deg(np.pi / 3 - angle)%360
    return c__, s__, l2_

Response: L a b to HCL


Instruction:
Make a summary of the following Python 3 code
def purge_old_user_tasks():
    limit = now() - settings.USER_TASKS_MAX_AGE
    # UserTaskArtifacts will also be removed via deletion cascading
    UserTaskStatus.objects.filter(created__lt=limit).delete()

Response: Delete any UserTaskStatus records older than settings. USER_TASKS_MAX_AGE.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def arguments_as_dict(cls, *args, **kwargs):
        all_args = (None, ) + args
        return inspect.getcallargs(cls.run, *all_args, **kwargs)

Response: Generate the arguments dictionary provided to the run method.


Instruction:
Create a Python 3 function to
return the UserTaskStatus model instance for this UserTaskMixin.

Response:
def status(self):
        """
        Get the :py:class:`~user_tasks.models.UserTaskStatus` model instance for this UserTaskMixin.
        """
        task_id = self.request.id
        try:
            # Most calls are for existing objects, don't waste time
            # preparing creation arguments unless necessary
            return UserTaskStatus.objects.get(task_id=task_id)
        except UserTaskStatus.DoesNotExist:
            # Probably an eager task that skipped the before_task_publish
            # signal (or an atomic view where the new record hasn't been
            # committed yet).  Create a record for it.
            arguments_dict = self.arguments_as_dict(*self.request.args, **self.request.kwargs)
            name = self.generate_name(arguments_dict)
            task_class = '.'.join([self.__class__.__module__, self.__class__.__name__])
            total_steps = self.calculate_total_steps(arguments_dict)
            user_id = arguments_dict['user_id']
            # Use get_or_create() again just in case another process created it in the meantime
            return UserTaskStatus.objects.get_or_create(
                task_id=task_id, defaults={'user_id': user_id, 'name': name, 'task_class': task_class,
                                           'total_steps': total_steps})[0]


Instruction:
How would you explain what the following Python 3 function does
def color_interp(data):
    from rasterio.enums import ColorInterp as ci
    modes = {'L': [ci.gray],
             'LA': [ci.gray, ci.alpha],
             'YCbCr': [ci.Y, ci.Cb, ci.Cr],
             'YCbCrA': [ci.Y, ci.Cb, ci.Cr, ci.alpha]}

    try:
        mode = ''.join(data['bands'].values)
        return modes[mode]
    except KeyError:
        colors = {'R': ci.red,
                  'G': ci.green,
                  'B': ci.blue,
                  'A': ci.alpha,
                  'C': ci.cyan,
                  'M': ci.magenta,
                  'Y': ci.yellow,
                  'H': ci.hue,
                  'S': ci.saturation,
                  'L': ci.lightness,
                  'K': ci.black,
                  }
        return [colors[band] for band in data['bands'].values]

Response: Get the color interpretation for this image.


Instruction:
Can you implement a function in Python 3 that
standardizes dimensions to bands y and x.

Response:
def _correct_dims(data):
        """Standardize dimensions to bands, y, and x."""
        if not hasattr(data, 'dims'):
            raise TypeError("Data must have a 'dims' attribute.")

        # doesn't actually copy the data underneath
        # we don't want our operations to change the user's data
        data = data.copy()

        if 'y' not in data.dims or 'x' not in data.dims:
            if data.ndim != 2:
                raise ValueError("Data must have a 'y' and 'x' dimension")

            # rename dimensions so we can use them
            # don't rename 'x' or 'y' if they already exist
            if 'y' not in data.dims:
                # find a dimension that isn't 'x'
                old_dim = [d for d in data.dims if d != 'x'][0]
                data = data.rename({old_dim: 'y'})
            if 'x' not in data.dims:
                # find a dimension that isn't 'y'
                old_dim = [d for d in data.dims if d != 'y'][0]
                data = data.rename({old_dim: 'x'})

        if "bands" not in data.dims:
            if data.ndim <= 2:
                data = data.expand_dims('bands')
                data['bands'] = ['L']
            else:
                raise ValueError("No 'bands' dimension provided.")

        return data


Instruction:
Can you generate the documentation for the following Python 3 function
def save(self, filename, fformat=None, fill_value=None, compute=True,
             keep_palette=False, cmap=None, **format_kwargs):
        """Save the image to the given *filename*.

        Args:
            filename (str): Output filename
            fformat (str): File format of output file (optional). Can be
                           one of many image formats supported by the
                           `rasterio` or `PIL` libraries ('jpg', 'png',
                           'tif'). By default this is determined by the
                           extension of the provided filename.
                           If the format allows, geographical information will
                           be saved to the ouput file, in the form of grid
                           mapping or ground control points.
            fill_value (float): Replace invalid data values with this value
                                and do not produce an Alpha band. Default
                                behavior is to create an alpha band.
            compute (bool): If True (default) write the data to the file
                            immediately. If False the return value is either
                            a `dask.Delayed` object or a tuple of
                            ``(source, target)`` to be passed to
                            `dask.array.store`.
            keep_palette (bool): Saves the palettized version of the image if
                                 set to True. False by default.
            cmap (Colormap or dict): Colormap to be applied to the image when
                                     saving with rasterio, used with
                                     keep_palette=True. Should be uint8.
            format_kwargs: Additional format options to pass to `rasterio`
                           or `PIL` saving methods.

        Returns:
            Either `None` if `compute` is True or a `dask.Delayed` object or
            ``(source, target)`` pair to be passed to `dask.array.store`.
            If compute is False the return value depends on format and how
            the image backend is used. If ``(source, target)`` is provided
            then target is an open file-like object that must be closed by
            the caller.

        """
        fformat = fformat or os.path.splitext(filename)[1][1:4]
        if fformat in ('tif', 'jp2') and rasterio:
            return self.rio_save(filename, fformat=fformat,
                                 fill_value=fill_value, compute=compute,
                                 keep_palette=keep_palette, cmap=cmap,
                                 **format_kwargs)
        else:
            return self.pil_save(filename, fformat, fill_value,
                                 compute=compute, **format_kwargs)

Response: Save the image to the given filename.


Instruction:
Can you create a Python 3 function that
saves the image using rasterio.

Response:
def rio_save(self, filename, fformat=None, fill_value=None,
                 dtype=np.uint8, compute=True, tags=None,
                 keep_palette=False, cmap=None,
                 **format_kwargs):
        """Save the image using rasterio.

        Overviews can be added to the file using the `overviews` kwarg, eg::

          img.rio_save('myfile.tif', overviews=[2, 4, 8, 16])

        """
        fformat = fformat or os.path.splitext(filename)[1][1:4]
        drivers = {'jpg': 'JPEG',
                   'png': 'PNG',
                   'tif': 'GTiff',
                   'jp2': 'JP2OpenJPEG'}
        driver = drivers.get(fformat, fformat)

        if tags is None:
            tags = {}

        data, mode = self.finalize(fill_value, dtype=dtype,
                                   keep_palette=keep_palette, cmap=cmap)
        data = data.transpose('bands', 'y', 'x')
        data.attrs = self.data.attrs

        crs = None
        gcps = None
        transform = None
        if driver in ['GTiff', 'JP2OpenJPEG']:
            if not np.issubdtype(data.dtype, np.floating):
                format_kwargs.setdefault('compress', 'DEFLATE')
            photometric_map = {
                'RGB': 'RGB',
                'RGBA': 'RGB',
                'CMYK': 'CMYK',
                'CMYKA': 'CMYK',
                'YCBCR': 'YCBCR',
                'YCBCRA': 'YCBCR',
            }
            if mode.upper() in photometric_map:
                format_kwargs.setdefault('photometric',
                                         photometric_map[mode.upper()])

            try:
                crs = rasterio.crs.CRS(data.attrs['area'].proj_dict)
                west, south, east, north = data.attrs['area'].area_extent
                height, width = data.sizes['y'], data.sizes['x']
                transform = rasterio.transform.from_bounds(west, south,
                                                           east, north,
                                                           width, height)

            except KeyError:  # No area
                logger.info("Couldn't create geotransform")
            except AttributeError:
                try:
                    gcps = data.attrs['area'].lons.attrs['gcps']
                    crs = data.attrs['area'].lons.attrs['crs']
                except KeyError:
                    logger.info("Couldn't create geotransform")

            if "start_time" in data.attrs:
                stime = data.attrs['start_time']
                stime_str = stime.strftime("%Y:%m:%d %H:%M:%S")
                tags.setdefault('TIFFTAG_DATETIME', stime_str)
        elif driver == 'JPEG' and 'A' in mode:
            raise ValueError('JPEG does not support alpha')

        # FIXME add metadata
        r_file = RIOFile(filename, 'w', driver=driver,
                         width=data.sizes['x'], height=data.sizes['y'],
                         count=data.sizes['bands'],
                         dtype=dtype,
                         nodata=fill_value,
                         crs=crs,
                         transform=transform,
                         gcps=gcps,
                         **format_kwargs)
        r_file.open()
        if not keep_palette:
            r_file.colorinterp = color_interp(data)
        r_file.rfile.update_tags(**tags)

        if keep_palette and cmap is not None:
            if data.dtype != 'uint8':
                raise ValueError('Rasterio only supports 8-bit colormaps')
            try:
                from trollimage.colormap import Colormap
                cmap = cmap.to_rio() if isinstance(cmap, Colormap) else cmap
                r_file.rfile.write_colormap(1, cmap)
            except AttributeError:
                raise ValueError("Colormap is not formatted correctly")

        if compute:
            # write data to the file now
            res = da.store(data.data, r_file)
            r_file.close()
            return res
        # provide the data object and the opened file so the caller can
        # store them when they would like. Caller is responsible for
        # closing the file
        return data.data, r_file


Instruction:
Can you generate the documentation for the following Python 3 function
def pil_save(self, filename, fformat=None, fill_value=None,
                 compute=True, **format_kwargs):
        """Save the image to the given *filename* using PIL.

        For now, the compression level [0-9] is ignored, due to PIL's lack of
        support. See also :meth:`save`.
        """
        fformat = fformat or os.path.splitext(filename)[1][1:4]
        fformat = check_image_format(fformat)

        if fformat == 'png':
            # Take care of GeoImage.tags (if any).
            format_kwargs['pnginfo'] = self._pngmeta()

        img = self.pil_image(fill_value, compute=False)
        delay = img.save(filename, fformat, **format_kwargs)
        if compute:
            return delay.compute()
        return delay

Response: Save the image to the given filename using PIL. save.


Instruction:
Write a Python 3 function that can
create an alpha band DataArray object.

Response:
def _create_alpha(self, data, fill_value=None):
        """Create an alpha band DataArray object.

        If `fill_value` is provided and input data is an integer type
        then it is used to determine invalid "null" pixels instead of
        xarray's `isnull` and `notnull` methods.

        The returned array is 1 where data is valid, 0 where invalid.

        """
        not_alpha = [b for b in data.coords['bands'].values if b != 'A']
        null_mask = data.sel(bands=not_alpha)
        if np.issubdtype(data.dtype, np.integer) and fill_value is not None:
            null_mask = null_mask != fill_value
        else:
            null_mask = null_mask.notnull()
        # if any of the bands are valid, we don't want transparency
        null_mask = null_mask.any(dim='bands')
        null_mask = null_mask.expand_dims('bands')
        null_mask['bands'] = ['A']
        # match data dtype
        return null_mask


Instruction:
Can you generate the documentation for the following Python 3 function
def _add_alpha(self, data, alpha=None):
        null_mask = alpha if alpha is not None else self._create_alpha(data)
        # if we are using integer data, then alpha needs to be min-int to max-int
        # otherwise for floats we want 0 to 1
        if np.issubdtype(data.dtype, np.integer):
            # xarray sometimes upcasts this calculation, so cast again
            null_mask = self._scale_to_dtype(null_mask, data.dtype).astype(data.dtype)
        data = xr.concat([data, null_mask], dim="bands")
        return data

Response: Create an alpha channel and concatenate it to the provided data.


Instruction:
Can you implement a function in Python 3 that
scales provided data to dtype range assuming a 0 - 1 range.

Response:
def _scale_to_dtype(self, data, dtype):
        """Scale provided data to dtype range assuming a 0-1 range.

        Float input data is assumed to be normalized to a 0 to 1 range.
        Integer input data is not scaled, only clipped. A float output
        type is not scaled since both outputs and inputs are assumed to
        be in the 0-1 range already.

        """
        if np.issubdtype(dtype, np.integer):
            if np.issubdtype(data, np.integer):
                # preserve integer data type
                data = data.clip(np.iinfo(dtype).min, np.iinfo(dtype).max)
            else:
                # scale float data (assumed to be 0 to 1) to full integer space
                dinfo = np.iinfo(dtype)
                data = data.clip(0, 1) * (dinfo.max - dinfo.min) + dinfo.min
            data = data.round()
        return data


Instruction:
Can you generate the documentation for the following Python 3 function
def _check_modes(self, modes):
        if not isinstance(modes, (tuple, list, set)):
            modes = [modes]
        if self.mode not in modes:
            raise ValueError("Image not in suitable mode, expected: %s, got: %s" % (modes, self.mode))

Response: Check that the image is in one of the given modes raise an exception otherwise.


Instruction:
Implement a Python 3 function for
converting the image from P or PA to RGB or RGBA.

Response:
def _from_p(self, mode):
        """Convert the image from P or PA to RGB or RGBA."""
        self._check_modes(("P", "PA"))

        if not self.palette:
            raise RuntimeError("Can't convert palettized image, missing palette.")
        pal = np.array(self.palette)
        pal = da.from_array(pal, chunks=pal.shape)

        if pal.shape[1] == 4:
            # colormap's alpha overrides data alpha
            mode = "RGBA"
            alpha = None
        elif self.mode.endswith("A"):
            # add a new/fake 'bands' dimension to the end
            alpha = self.data.sel(bands="A").data[..., None]
            mode = mode + "A" if not mode.endswith("A") else mode
        else:
            alpha = None

        flat_indexes = self.data.sel(bands='P').data.ravel().astype('int64')
        dim_sizes = ((key, val) for key, val in self.data.sizes.items() if key != 'bands')
        dims, new_shape = zip(*dim_sizes)
        dims = dims + ('bands',)
        new_shape = new_shape + (pal.shape[1],)
        new_data = pal[flat_indexes].reshape(new_shape)
        coords = dict(self.data.coords)
        coords["bands"] = list(mode)

        if alpha is not None:
            new_arr = da.concatenate((new_data, alpha), axis=-1)
            data = xr.DataArray(new_arr, coords=coords, attrs=self.data.attrs, dims=dims)
        else:
            data = xr.DataArray(new_data, coords=coords, attrs=self.data.attrs, dims=dims)

        return data


Instruction:
How would you explain what the following Python 3 function does
def _l2rgb(self, mode):
        self._check_modes(("L", "LA"))

        bands = ["L"] * 3
        if mode[-1] == "A":
            bands.append("A")
        data = self.data.sel(bands=bands)
        data["bands"] = list(mode)
        return data

Response: Convert from L to RGB.


Instruction:
Create a Python 3 function for
wrapping around finalize method for backwards compatibility.

Response:
def _finalize(self, fill_value=None, dtype=np.uint8, keep_palette=False, cmap=None):
        """Wrapper around 'finalize' method for backwards compatibility."""
        import warnings
        warnings.warn("'_finalize' is deprecated, use 'finalize' instead.",
                      DeprecationWarning)
        return self.finalize(fill_value, dtype, keep_palette, cmap)