Instruction:
Make a summary of the following Python 3 code
def text_entry(self, prompt, message=None, allow_blank=False, strip=True,
            rofi_args=None, **kwargs):
        """Prompt the user to enter a piece of text.

        Parameters
        ----------
        prompt: string
            Prompt to display to the user.
        message: string, optional
            Message to display under the entry line.
        allow_blank: Boolean
            Whether to allow blank entries.
        strip: Boolean
            Whether to strip leading and trailing whitespace from the entered
            value.

        Returns
        -------
        string, or None if the dialog was cancelled.

        """
        def text_validator(text):
            if strip:
                text = text.strip()
            if not allow_blank:
                if not text:
                    return None, "A value is required."

            return text, None

        return self.generic_entry(prompt, text_validator, message, rofi_args, **kwargs)

Response: Prompt the user to enter a piece of text.


Instruction:
How would you code a function in Python 3 to
prompt the user to enter an integer value.

Response:
def integer_entry(self, prompt, message=None, min=None, max=None, rofi_args=None, **kwargs):
        """Prompt the user to enter an integer.

        Parameters
        ----------
        prompt: string
            Prompt to display to the user.
        message: string, optional
            Message to display under the entry line.
        min, max: integer, optional
            Minimum and maximum values to allow. If None, no limit is imposed.

        Returns
        -------
        integer, or None if the dialog is cancelled.

        """
        # Sanity check.
        if (min is not None) and (max is not None) and not (max > min):
            raise ValueError("Maximum limit has to be more than the minimum limit.")

        def integer_validator(text):
            error = None

            # Attempt to convert to integer.
            try:
                value = int(text)
            except ValueError:
                return None, "Please enter an integer value."

            # Check its within limits.
            if (min is not None) and (value < min):
                return None, "The minimum allowable value is {0:d}.".format(min)
            if (max is not None) and (value > max):
                return None, "The maximum allowable value is {0:d}.".format(max)

            return value, None

        return self.generic_entry(prompt, integer_validator, message, rofi_args, **kwargs)


Instruction:
Can you create a Python 3 function that
prompts the user to enter a floating point number.

Response:
def float_entry(self, prompt, message=None, min=None, max=None, rofi_args=None, **kwargs):
        """Prompt the user to enter a floating point number.

        Parameters
        ----------
        prompt: string
            Prompt to display to the user.
        message: string, optional
            Message to display under the entry line.
        min, max: float, optional
            Minimum and maximum values to allow. If None, no limit is imposed.

        Returns
        -------
        float, or None if the dialog is cancelled.

        """
        # Sanity check.
        if (min is not None) and (max is not None) and not (max > min):
            raise ValueError("Maximum limit has to be more than the minimum limit.")

        def float_validator(text):
            error = None

            # Attempt to convert to float.
            try:
                value = float(text)
            except ValueError:
                return None, "Please enter a floating point value."

            # Check its within limits.
            if (min is not None) and (value < min):
                return None, "The minimum allowable value is {0}.".format(min)
            if (max is not None) and (value > max):
                return None, "The maximum allowable value is {0}.".format(max)

            return value, None

        return self.generic_entry(prompt, float_validator, message, rofi_args, **kwargs)


Instruction:
Make a summary of the following Python 3 code
def decimal_entry(self, prompt, message=None, min=None, max=None, rofi_args=None, **kwargs):
        # Sanity check.
        if (min is not None) and (max is not None) and not (max > min):
            raise ValueError("Maximum limit has to be more than the minimum limit.")

        def decimal_validator(text):
            error = None

            # Attempt to convert to decimal.
            try:
                value = Decimal(text)
            except InvalidOperation:
                return None, "Please enter a decimal value."

            # Check its within limits.
            if (min is not None) and (value < min):
                return None, "The minimum allowable value is {0}.".format(min)
            if (max is not None) and (value > max):
                return None, "The maximum allowable value is {0}.".format(max)

            return value, None

        return self.generic_entry(prompt, decimal_validator, message, rofi_args, **kwargs)

Response: Prompt the user to enter a decimal number.


Instruction:
How would you implement a function in Python 3 that
prompts the user to enter a date.

Response:
def date_entry(self, prompt, message=None, formats=['%x', '%d/%m/%Y'],
            show_example=False, rofi_args=None, **kwargs):
        """Prompt the user to enter a date.

        Parameters
        ----------
        prompt: string
            Prompt to display to the user.
        message: string, optional
            Message to display under the entry line.
        formats: list of strings, optional
            The formats that the user can enter dates in. These should be
            format strings as accepted by the datetime.datetime.strptime()
            function from the standard library. They are tried in order, and
            the first that returns a date object without error is selected.
            Note that the '%x' in the default list is the current locale's date
            representation.
        show_example: Boolean
            If True, today's date in the first format given is appended to the
            message.

        Returns
        -------
        datetime.date, or None if the dialog is cancelled.

        """
        def date_validator(text):
            # Try them in order.
            for format in formats:
                try:
                    dt = datetime.strptime(text, format)
                except ValueError:
                    continue
                else:
                    # This one worked; good enough for us.
                    return (dt.date(), None)

            # None of the formats worked.
            return (None, 'Please enter a valid date.')

        # Add an example to the message?
        if show_example:
            message = message or ""
            message += "Today's date in the correct format: " + datetime.now().strftime(formats[0])

        return self.generic_entry(prompt, date_validator, message, rofi_args, **kwargs)


Instruction:
Write a Python 3 script to
prompt the user to enter a time.

Response:
def time_entry(self, prompt, message=None, formats=['%X', '%H:%M', '%I:%M', '%H.%M',
        '%I.%M'], show_example=False, rofi_args=None, **kwargs):
        """Prompt the user to enter a time.

        Parameters
        ----------
        prompt: string
            Prompt to display to the user.
        message: string, optional
            Message to display under the entry line.
        formats: list of strings, optional
            The formats that the user can enter times in. These should be
            format strings as accepted by the datetime.datetime.strptime()
            function from the standard library. They are tried in order, and
            the first that returns a time object without error is selected.
            Note that the '%X' in the default list is the current locale's time
            representation.
        show_example: Boolean
            If True, the current time in the first format given is appended to
            the message.

        Returns
        -------
        datetime.time, or None if the dialog is cancelled.

        """
        def time_validator(text):
            # Try them in order.
            for format in formats:
                try:
                    dt = datetime.strptime(text, format)
                except ValueError:
                    continue
                else:
                    # This one worked; good enough for us.
                    return (dt.time(), None)

            # None of the formats worked.
            return (None, 'Please enter a valid time.')

        # Add an example to the message?
        if show_example:
            message = message or ""
            message += "Current time in the correct format: " + datetime.now().strftime(formats[0])

        return self.generic_entry(prompt, time_validator, message, rofi_args=None, **kwargs)


Instruction:
Make a summary of the following Python 3 code
def datetime_entry(self, prompt, message=None, formats=['%x %X'], show_example=False,
            rofi_args=None, **kwargs):
        """Prompt the user to enter a date and time.

        Parameters
        ----------
        prompt: string
            Prompt to display to the user.
        message: string, optional
            Message to display under the entry line.
        formats: list of strings, optional
            The formats that the user can enter the date and time in. These
            should be format strings as accepted by the
            datetime.datetime.strptime() function from the standard library.
            They are tried in order, and the first that returns a datetime
            object without error is selected.  Note that the '%x %X' in the
            default list is the current locale's date and time representation.
        show_example: Boolean
            If True, the current date and time in the first format given is appended to
            the message.

        Returns
        -------
        datetime.datetime, or None if the dialog is cancelled.

        """
        def datetime_validator(text):
            # Try them in order.
            for format in formats:
                try:
                    dt = datetime.strptime(text, format)
                except ValueError:
                    continue
                else:
                    # This one worked; good enough for us.
                    return (dt, None)

            # None of the formats worked.
            return (None, 'Please enter a valid date and time.')

        # Add an example to the message?
        if show_example:
            message = message or ""
            message += "Current date and time in the correct format: " + datetime.now().strftime(formats[0])

        return self.generic_entry(prompt, datetime_validator, message, rofi_args, **kwargs)

Response: Prompt the user to enter a date and time.


Instruction:
Implement a Python 3 function for
reporting an error and exit.

Response:
def exit_with_error(self, error, **kwargs):
        """Report an error and exit.

        This raises a SystemExit exception to ask the interpreter to quit.

        Parameters
        ----------
        error: string
            The error to report before quitting.

        """
        self.error(error, **kwargs)
        raise SystemExit(error)


Instruction:
How would you code a function in Python 3 to
format a key = value pair in a .

Response:
def format_kwarg(key, value):
    """
    Return a string of form:  "key=<value>"

    If 'value' is a string, we want it quoted. The goal is to make
    the string a named parameter in a method call.
    """
    translator = repr if isinstance(value, six.string_types) else six.text_type
    arg_value = translator(value)

    return '{0}={1}'.format(key, arg_value)


Instruction:
How would you explain what the following Python 3 function does
def format_arg(value):
    translator = repr if isinstance(value, six.string_types) else six.text_type
    return translator(value)

Response: Formats the value in a dataset.


Instruction:
Create a Python 3 function to
encode a non - ASCII string into a base64 - encoded version of the string.

Response:
def encode_non_ascii_string(string):
    """
    :param string:
        The string to be encoded
    :type string:
        unicode or str
    :return:
        The encoded string
    :rtype:
        str
    """
    encoded_string = string.encode('utf-8', 'replace')
    if six.PY3:
        encoded_string = encoded_string.decode()

    return encoded_string


Instruction:
Can you generate the documentation for the following Python 3 function
def genty_dataset(*args, **kwargs):
    datasets = _build_datasets(*args, **kwargs)

    def wrap(test_method):
        # Save the datasets in the test method. This data will be consumed
        # by the @genty decorator.
        if not hasattr(test_method, 'genty_datasets'):
            test_method.genty_datasets = OrderedDict()

        test_method.genty_datasets.update(datasets)

        return test_method
    return wrap

Response: Decorator for the genty_dataset method.


Instruction:
Can you write a function in Python 3 where it
builds the datasets into a dict where the keys are the name of the data set and the values are the data sets themselves.

Response:
def _build_datasets(*args, **kwargs):
    """Build the datasets into a dict, where the keys are the name of the
    data set and the values are the data sets themselves.

    :param args:
        Tuple of unnamed data sets.
    :type args:
        `tuple` of varies
    :param kwargs:
        Dict of pre-named data sets.
    :type kwargs:
        `dict` of `unicode` to varies
    :return:
        The dataset dict.
    :rtype:
        `dict`
    """
    datasets = OrderedDict()
    _add_arg_datasets(datasets, args)
    _add_kwarg_datasets(datasets, kwargs)
    return datasets


Instruction:
Implement a function in Python 3 to
add data sets of the given args to the given datasets.

Response:
def _add_arg_datasets(datasets, args):
    """Add data sets of the given args.

    :param datasets:
        The dict where to accumulate data sets.
    :type datasets:
        `dict`
    :param args:
        Tuple of unnamed data sets.
    :type args:
        `tuple` of varies
    """
    for dataset in args:
        # turn a value into a 1-tuple.
        if not isinstance(dataset, (tuple, GentyArgs)):
            dataset = (dataset,)

        # Create a test_name_suffix - basically the parameter list
        if isinstance(dataset, GentyArgs):
            dataset_strings = dataset     # GentyArgs supports iteration
        else:
            dataset_strings = [format_arg(data) for data in dataset]
        test_method_suffix = ", ".join(dataset_strings)

        datasets[test_method_suffix] = dataset


Instruction:
Create a Python 3 function to
add data sets of the given kwargs to the given datasets.

Response:
def _add_kwarg_datasets(datasets, kwargs):
    """Add data sets of the given kwargs.

    :param datasets:
        The dict where to accumulate data sets.
    :type datasets:
        `dict`
    :param kwargs:
        Dict of pre-named data sets.
    :type kwargs:
        `dict` of `unicode` to varies
    """
    for test_method_suffix, dataset in six.iteritems(kwargs):
        datasets[test_method_suffix] = dataset


Instruction:
Explain what the following Python 3 code does
def dedent(s):
    head, _, tail = s.partition('\n')
    dedented_tail = textwrap.dedent(tail)
    result = "{head}\n{tail}".format(
        head=head,
        tail=dedented_tail)
    return result

Response: Removes the hanging dedent from all the first line of a string.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def top_level_doc(self):
        return self._doc_template.format(
            available_commands='\n  '.join(sorted(self._commands)),
            program=self.program)

Response: The top - level documentation string for the program.


Instruction:
Here you have a function in Python 3, explain what it does
def command(self, name=None):
        def decorator(f):
            self.add_command(f, name)
            return f
        return decorator

Response: A decorator to add subcommands.


Instruction:
Can you create a Python 3 function that
adds a subcommand handler which invokes handler.

Response:
def add_command(self, handler, name=None):
        """Add a subcommand `name` which invokes `handler`.
        """
        if name is None:
            name = docstring_to_subcommand(handler.__doc__)

        # TODO: Prevent overwriting 'help'?
        self._commands[name] = handler


Instruction:
How would you implement a function in Python 3 that
creates variations of the word based on letter combinations like oo ou etc.

Response:
def variations(word):
    """Create variations of the word based on letter combinations like oo,
sh, etc."""

    if len(word) == 1:
        return [[word[0]]]
    elif word == 'aa':
        return [['A']]
    elif word == 'ee':
        return [['i']]
    elif word == 'ei':
        return [['ei']]
    elif word in ['oo', 'ou']:
        return [['u']]
    elif word == 'kha':
        return [['kha'], ['kh', 'a']]
    elif word in ['kh', 'gh', 'ch', 'sh', 'zh', 'ck']:
        return [[word]]
    elif word in ["'ee", "'ei"]:
        return [["'i"]]
    elif word in ["'oo", "'ou"]:
        return [["'u"]]
    elif word in ["a'", "e'", "o'", "i'", "u'", "A'"]:
        return [[word[0] + "'"]]
    elif word in ["'a", "'e", "'o", "'i", "'u", "'A"]:
        return [["'" + word[1]]]
    elif len(word) == 2 and word[0] == word[1]:
        return [[word[0]]]

    if word[:2] == 'aa':
        return [['A'] + i for i in variations(word[2:])]
    elif word[:2] == 'ee':
        return [['i'] + i for i in variations(word[2:])]
    elif word[:2] in ['oo', 'ou']:
        return [['u'] + i for i in variations(word[2:])]
    elif word[:3] == 'kha':
        return \
            [['kha'] + i for i in variations(word[3:])] + \
            [['kh', 'a'] + i for i in variations(word[3:])] + \
            [['k', 'h', 'a'] + i for i in variations(word[3:])]
    elif word[:2] in ['kh', 'gh', 'ch', 'sh', 'zh', 'ck']:
        return \
            [[word[:2]] + i for i in variations(word[2:])] + \
            [[word[0]] + i for i in variations(word[1:])]
    elif word[:2] in ["a'", "e'", "o'", "i'", "u'", "A'"]:
        return [[word[:2]] + i for i in variations(word[2:])]
    elif word[:3] in ["'ee", "'ei"]:
        return [["'i"] + i for i in variations(word[3:])]
    elif word[:3] in ["'oo", "'ou"]:
        return [["'u"] + i for i in variations(word[3:])]
    elif word[:2] in ["'a", "'e", "'o", "'i", "'u", "'A"]:
        return [[word[:2]] + i for i in variations(word[2:])]
    elif len(word) >= 2 and word[0] == word[1]:
        return [[word[0]] + i for i in variations(word[2:])]
    else:
        return [[word[0]] + i for i in variations(word[1:])]


Instruction:
Explain what the following Python 3 code does
def f2p_word(word, max_word_size=15, cutoff=3):

    original_word = word
    word = word.lower()

    c = dictionary.get(word)
    if c:
        return [(c, 1.0)]

    if word == '':
        return []
    elif len(word) > max_word_size:
        return [(original_word, 1.0)]

    results = []
    for w in variations(word):
        results.extend(f2p_word_internal(w, original_word))

    # sort results based on the confidence value
    results.sort(key=lambda r: r[1], reverse=True)

    # return the top three results in order to cut down on the number
    # of possibilities.
    return results[:cutoff]

Response: Convert a single word from Finglish to Persian.


Instruction:
Write a Python 3 script for
converting a phrase from Finglish to Persian.

Response:
def f2p_list(phrase, max_word_size=15, cutoff=3):
    """Convert a phrase from Finglish to Persian.

    phrase: The phrase to convert.

    max_word_size: Maximum size of the words to consider. Words larger
    than this will be kept unchanged.

    cutoff: The cut-off point. For each word, there could be many
    possibilities. By default 3 of these possibilities are considered
    for each word. This number can be changed by this argument.

    Returns a list of lists, each sub-list contains a number of
    possibilities for each word as a pair of (word, confidence)
    values.

    """

    # split the phrase into words
    results = [w for w in sep_regex.split(phrase) if w]

    # return an empty list if no words
    if results == []:
        return []

    # convert each word separately
    results = [f2p_word(w, max_word_size, cutoff) for w in results]

    return results


Instruction:
How would you code a function in Python 3 to
convert a Finglish phrase to the most probable Persian phrase.

Response:
def f2p(phrase, max_word_size=15, cutoff=3):
    """Convert a Finglish phrase to the most probable Persian phrase.

    """

    results = f2p_list(phrase, max_word_size, cutoff)
    return ' '.join(i[0][0] for i in results)


Instruction:
Implement a Python 3 function for
trying to get the version of the named distribution returs None on failure

Response:
def distribution_version(name):
    """try to get the version of the named distribution,
    returs None on failure"""
    from pkg_resources import get_distribution, DistributionNotFound
    try:
        dist = get_distribution(name)
    except DistributionNotFound:
        pass
    else:
        return dist.version


Instruction:
Create a Python 3 function for
initializing given package from the export definitions.

Response:
def initpkg(pkgname, exportdefs, attr=None, eager=False):
    """ initialize given package from the export definitions. """
    attr = attr or {}
    oldmod = sys.modules.get(pkgname)
    d = {}
    f = getattr(oldmod, '__file__', None)
    if f:
        f = _py_abspath(f)
    d['__file__'] = f
    if hasattr(oldmod, '__version__'):
        d['__version__'] = oldmod.__version__
    if hasattr(oldmod, '__loader__'):
        d['__loader__'] = oldmod.__loader__
    if hasattr(oldmod, '__path__'):
        d['__path__'] = [_py_abspath(p) for p in oldmod.__path__]
    if hasattr(oldmod, '__package__'):
        d['__package__'] = oldmod.__package__
    if '__doc__' not in exportdefs and getattr(oldmod, '__doc__', None):
        d['__doc__'] = oldmod.__doc__
    d.update(attr)
    if hasattr(oldmod, "__dict__"):
        oldmod.__dict__.update(d)
    mod = ApiModule(pkgname, exportdefs, implprefix=pkgname, attr=d)
    sys.modules[pkgname] = mod
    # eagerload in bypthon to avoid their monkeypatching breaking packages
    if 'bpython' in sys.modules or eager:
        for module in list(sys.modules.values()):
            if isinstance(module, ApiModule):
                module.__dict__


Instruction:
Here you have a function in Python 3, explain what it does
def importobj(modpath, attrname):
    module = __import__(modpath, None, None, ['__doc__'])
    if not attrname:
        return module

    retval = module
    names = attrname.split(".")
    for x in names:
        retval = getattr(retval, x)
    return retval

Response: imports a module then resolves the attrname on it


Instruction:
Can you tell what is the following Python 3 function doing
def _request(self, http_method, relative_url='', **kwargs):
        # It could be possible to call api.resource.get('/index')
        # but it would be non-intuitive that the path would resolve
        # to root of domain
        relative_url = self._remove_leading_slash(relative_url)

        # Add default kwargs with possible custom kwargs returned by
        # before_request
        new_kwargs = self.default_kwargs().copy()
        custom_kwargs = self.before_request(
            http_method,
            relative_url,
            kwargs.copy()
        )
        new_kwargs.update(custom_kwargs)

        response = requests.request(
            http_method,
            self._join_url(relative_url),
            **new_kwargs
        )

        return self.after_request(response)

Response: Does actual HTTP request using requests library.


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

        return Url(
            urljoin(self._base_url, relative_url),
            **self._default_kwargs
        )

Response: Create new Url which points to new url.


Instruction:
How would you explain what the following Python 3 function does
def get_permissions(self, role):
        target_role = AuthGroup.objects(role=role, creator=self.client).first()
        if not target_role:
            return '[]'
        targets = AuthPermission.objects(groups=target_role, creator=self.client).only('name')
        return json.loads(targets.to_json())

Response: gets permissions of role


Instruction:
How would you explain what the following Python 3 function does
def get_user_permissions(self, user):
        memberShipRecords = AuthMembership.objects(creator=self.client, user=user).only('groups')
        results = []
        for each in memberShipRecords:
            for group in each.groups:
                targetPermissionRecords = AuthPermission.objects(creator=self.client,
                                            groups=group).only('name')

                for each_permission in targetPermissionRecords:
                    results.append({'name':each_permission.name})
        return results

Response: get permissions of a user


Instruction:
Can you tell what is the following Python 3 function doing
def get_user_roles(self, user):
        memberShipRecords = AuthMembership.objects(creator=self.client, user=user).only('groups')
        results = []
        for each in memberShipRecords:
            for group in each.groups:
                results.append({'role':group.role})
        return results

Response: get permissions of a user


Instruction:
Can you generate the documentation for the following Python 3 function
def get_role_members(self, role):
        targetRoleDb = AuthGroup.objects(creator=self.client, role=role)
        members = AuthMembership.objects(groups__in=targetRoleDb).only('user')
        return json.loads(members.to_json())

Response: get permissions of a user


Instruction:
How would you explain what the following Python 3 function does
def get_role(self, role):
        role = AuthGroup.objects(role=role, creator=self.client).first()
        return role

Response: Returns a role object


Instruction:
Given the following Python 3 function, write the documentation
def add_role(self, role, description=None):
        new_group = AuthGroup(role=role, creator=self.client)
        try:
            new_group.save()
            return True
        except NotUniqueError:
            return False

Response: Adds a role to the group


Instruction:
Make a summary of the following Python 3 code
def add_membership(self, user, role):
        targetGroup = AuthGroup.objects(role=role, creator=self.client).first()
        if not targetGroup:
            return False

        target = AuthMembership.objects(user=user, creator=self.client).first()
        if not target:
            target = AuthMembership(user=user, creator=self.client)

        if not role in [i.role for i in target.groups]:
            target.groups.append(targetGroup)
            target.save()
        return True

Response: add a user to a group


Instruction:
Can you generate a brief explanation for the following Python 3 code
def del_membership(self, user, role):
        if not self.has_membership(user, role):
            return True
        targetRecord = AuthMembership.objects(creator=self.client, user=user).first()
        if not targetRecord:
            return True
        for group in targetRecord.groups:
            if group.role==role:
                targetRecord.groups.remove(group)
        targetRecord.save()
        return True

Response: delete a user from a group


Instruction:
Implement a function in Python 3 to
check if user is member of a group

Response:
def has_membership(self, user, role):
        """ checks if user is member of a group"""
        targetRecord = AuthMembership.objects(creator=self.client, user=user).first()
        if targetRecord:
            return role in [i.role for i in targetRecord.groups]
        return False


Instruction:
Explain what the following Python 3 code does
def add_permission(self, role, name):
        if self.has_permission(role, name):
            return True
        targetGroup = AuthGroup.objects(role=role, creator=self.client).first()
        if not targetGroup:
            return False
        # Create or update
        permission = AuthPermission.objects(name=name).update(
                add_to_set__groups=[targetGroup], creator=self.client, upsert=True
        )
        return True

Response: authorize a group for something


Instruction:
Given the following Python 3 function, write the documentation
def del_permission(self, role, name):
        if not self.has_permission(role, name):
            return True
        targetGroup = AuthGroup.objects(role=role, creator=self.client).first()
        target = AuthPermission.objects(groups=targetGroup, name=name, creator=self.client).first()
        if not target:
            return True
        target.delete()
        return True

Response: revoke authorization of a group


Instruction:
Can you tell what is the following Python 3 function doing
def user_has_permission(self, user, name):
        targetRecord = AuthMembership.objects(creator=self.client, user=user).first()
        if not targetRecord:
            return False
        for group in targetRecord.groups:
            if self.has_permission(group.role, name):
                return True
        return False

Response: verify user has permission


Instruction:
Explain what the following Python 3 code does
def bump_version(version, bump='patch'):
    try:
        parts = map(int, version.split('.'))
    except ValueError:
        fail('Current version is not numeric')

    if bump == 'patch':
        parts[2] += 1
    elif bump == 'minor':
        parts[1] += 1
        parts[2] = 0
    elif bump == 'major':
        parts[0] +=1
        parts[1] = 0
        parts[2] = 0

    return '.'.join(map(str, parts))

Response: Bump the current version of the current language.


Instruction:
Write a Python 3 script for
signaling decorator to allow use of callback functions as class decorators.

Response:
def handler(event):
    """Signal decorator to allow use of callback functions as class decorators."""
    def decorator(fn):
        def apply(cls):
            event.connect(fn, sender=cls)
            return cls

        fn.apply = apply
        return fn
    return decorator


Instruction:
Write a Python 3 function that can
dump all valid jsons This is the latest after hook

Response:
def stringify(req, resp):
    """
    dumps all valid jsons
    This is the latest after hook
    """
    if isinstance(resp.body, dict):
        try:
            resp.body = json.dumps(resp.body)
        except(nameError):
            resp.status = falcon.HTTP_500


Instruction:
Given the following Python 3 function, write the documentation
def process_response(self, req, resp, resource):
        if isinstance(resp.body, dict):
            try:
                resp.body = json.dumps(resp.body)
            except(nameError):
                resp.status = falcon.HTTP_500

Response: Post - processing of the response.


Instruction:
Can you create a Python 3 function that
runs the given command.

Response:
def run(command=None, *arguments):
    """
    Run the given command.

    Parameters:
    :param command: A string describing a command.
    :param arguments: A list of strings describing arguments to the command.
    """

    if command is None:
        sys.exit('django-shortcuts: No argument was supplied, please specify one.')

    if command in ALIASES:
        command = ALIASES[command]

    if command == 'startproject':
        return call('django-admin.py startproject %s' % ' '.join(arguments), shell=True)

    script_path = os.getcwd()
    while not os.path.exists(os.path.join(script_path, 'manage.py')):
        base_dir = os.path.dirname(script_path)
        if base_dir != script_path:
            script_path = base_dir
        else:
            sys.exit('django-shortcuts: No \'manage.py\' script found in this directory or its parents.')

    return call('%(python)s %(script_path)s %(command)s %(arguments)s' % {
        'python': sys.executable,
        'script_path': os.path.join(script_path, 'manage.py'),
        'command': command or '',
        'arguments': ' '.join(arguments)
    }, shell=True)


Instruction:
Here you have a function in Python 3, explain what it does
def instantiate(self, scope, args, interp):
        param_instances = []

        BYREF = "byref"

        # TODO are default values for function parameters allowed in 010?
        for param_name, param_cls in self._params:
            # we don't instantiate a copy of byref params
            if getattr(param_cls, "byref", False):
                param_instances.append(BYREF)
            else:
                field = param_cls()
                field._pfp__name = param_name
                param_instances.append(field)

        if len(args) != len(param_instances):
            raise errors.InvalidArguments(
                self._coords,
                [x.__class__.__name__ for x in args],
                [x.__class__.__name__ for x in param_instances]
            )

        # TODO type checking on provided types

        for x in six.moves.range(len(args)):
            param = param_instances[x]

            # arrays are simply passed through into the function. We shouldn't
            # have to worry about frozenness/unfrozenness at this point
            if param is BYREF or isinstance(param, pfp.fields.Array):
                param = args[x]
                param_instances[x] = param
                scope.add_local(self._params[x][0], param)
            else:
                param._pfp__set_value(args[x])
                scope.add_local(param._pfp__name, param)
            param._pfp__interp = interp

        return ParamList(param_instances)

Response: Create a ParamList instance for actual interpretation of the parameters.


Instruction:
Make a summary of the following Python 3 code
def load_experiments(folders):
    '''load_experiments
    a wrapper for load_experiment to read multiple experiments
    :param experiment_folders: a list of experiment folders to load, full paths
    '''
    experiments = []
    if isinstance(folders,str):
        folders = [experiment_folders]
    for folder in folders:
        exp = load_experiment(folder)
        experiments.append(exp)
    return experiments

Response:
load_experiments
    a wrapper for load_experiment to read multiple experiments


Instruction:
Can you generate a brief explanation for the following Python 3 code
def load_experiment(folder, return_path=False):
    '''load_experiment:
    reads in the config.json for a folder, returns None if not found.
    :param folder: full path to experiment folder
    :param return_path: if True, don't load the config.json, but return it
    '''
    fullpath = os.path.abspath(folder)
    config = "%s/config.json" %(fullpath)
    if not os.path.exists(config):
        bot.error("config.json could not be found in %s" %(folder))
        config = None
    if return_path is False and config is not None:
        config = read_json(config)
    return config

Response: load_experiment reads in the config. json for a folder returns None if not found.


Instruction:
Given the following Python 3 function, write the documentation
def get_selection(available, selection, base='/scif/apps'):
    '''we compare the basename (the exp_id) of the selection and available,
       regardless of parent directories'''

    if isinstance(selection, str):
        selection = selection.split(',')

    available = [os.path.basename(x) for x in available]
    selection = [os.path.basename(x) for x in selection]
    finalset = [x for x in selection if x in available]
    if len(finalset) == 0:
        bot.warning("No user experiments selected, providing all %s" %(len(available)))
        finalset = available
    return ["%s/%s" %(base,x) for x in finalset]

Response:
we compare the basename of the exp_id of the selection and available and
       regardless of parent directories


Instruction:
Can you generate the documentation for the following Python 3 function
def validate(folder=None, cleanup=False):
    '''validate
    :param folder: full path to experiment folder with config.json. If path begins
                   with https, we assume to be starting from a repository.
    '''
    from expfactory.validator import ExperimentValidator
    cli = ExperimentValidator()
    return cli.validate(folder, cleanup=cleanup)

Response:
validate
    :param folder: full path to experiment folder with config.json. If path begins
                   with https, we assume to be starting from a repository.


Instruction:
Explain what the following Python 3 code does
def get_library(lookup=True, key='exp_id'):
    ''' return the raw library, without parsing'''
    library = None
    response = requests.get(EXPFACTORY_LIBRARY)
    if response.status_code == 200:
        library = response.json()
        if lookup is True:
            return make_lookup(library,key=key)
    return library

Response: return the raw library without parsing


Instruction:
Given the following Python 3 function, write the documentation
def int3(params, ctxt, scope, stream, coord, interp):
    if interp._no_debug:
        return

    if interp._int3:
        interp.debugger = PfpDbg(interp)
        interp.debugger.cmdloop()

Response: Int3 is a wrapper around the Int2 function in the interpreter.


Instruction:
Explain what the following Python 3 code does
def initdb(self):
        '''initdb will check for writability of the data folder, meaning
           that it is bound to the local machine. If the folder isn't bound,
           expfactory runs in demo mode (not saving data)
        '''

        self.database = EXPFACTORY_DATABASE
        bot.info("DATABASE: %s" %self.database)

        # Supported database options
        valid = ('sqlite', 'postgres', 'mysql', 'filesystem')
        if not self.database.startswith(valid):
            bot.warning('%s is not yet a supported type, saving to filesystem.' % self.database)
            self.database = 'filesystem'

        # Add functions specific to database type
        self.init_db() # uses url in self.database

        bot.log("Data base: %s" % self.database)

Response: initdb will check for writability of the data folder and meaning that it is bound to the local machine.


Instruction:
Make a summary of the following Python 3 code
def setup(self):
        ''' obtain database and filesystem preferences from defaults,
            and compare with selection in container.
        '''

        self.selection = EXPFACTORY_EXPERIMENTS
        self.ordered = len(EXPFACTORY_EXPERIMENTS) > 0
        self.data_base = EXPFACTORY_DATA
        self.study_id = EXPFACTORY_SUBID
        self.base = EXPFACTORY_BASE
        self.randomize = EXPFACTORY_RANDOMIZE
        self.headless = EXPFACTORY_HEADLESS

        # Generate variables, if they exist
        self.vars = generate_runtime_vars() or None

        available = get_experiments("%s" % self.base)
        self.experiments = get_selection(available, self.selection)
        self.logger.debug(self.experiments)
        self.lookup = make_lookup(self.experiments)
        final = "\n".join(list(self.lookup.keys()))

        bot.log("Headless mode: %s" % self.headless)
        bot.log("User has selected: %s" % self.selection)
        bot.log("Experiments Available: %s" %"\n".join(available))
        bot.log("Randomize: %s" % self.randomize)
        bot.log("Final Set \n%s" % final)

Response: setup the internal variables and database preferences


Instruction:
Can you generate a brief explanation for the following Python 3 code
def get_next(self, session):
        '''return the name of the next experiment, depending on the user's
           choice to randomize. We don't remove any experiments here, that is
           done on finish, in the case the user doesn't submit data (and
           thus finish). A return of None means the user has completed the
           battery of experiments.
        '''
        next = None
        experiments = session.get('experiments', [])
        if len(experiments) > 0:
            if app.randomize is True:
                next = random.choice(range(0,len(experiments)))
                next = experiments[next]
            else:
                next = experiments[0]
        return next

Response:
return the name of the next experiment depending on the user s is
           choice to randomize.


Instruction:
Write a Python 3 function that can
remove an experiment from the list after completion.

Response:
def finish_experiment(self, session, exp_id):
        '''remove an experiment from the list after completion.
        '''
        self.logger.debug('Finishing %s' %exp_id)
        experiments = session.get('experiments', [])
        experiments = [x for x in experiments if x != exp_id]
        session['experiments'] = experiments
        return experiments


Instruction:
Given the following Python 3 function, write the documentation
def find_subdirectories(basepath):
    '''
    Return directories (and sub) starting from a base
    '''
    directories = []
    for root, dirnames, filenames in os.walk(basepath):
        new_directories = [d for d in dirnames if d not in directories]
        directories = directories + new_directories
    return directories

Response: Return directories and sub directories starting from a basepath


Instruction:
Write a Python 3 script for
finding all directories in a user s directory tree.

Response:
def find_directories(root,fullpath=True):
    '''
    Return directories at one level specified by user
    (not recursive)
    '''
    directories = []
    for item in os.listdir(root):
        # Don't include hidden directories
        if not re.match("^[.]",item):
            if os.path.isdir(os.path.join(root, item)):
                if fullpath:
                    directories.append(os.path.abspath(os.path.join(root, item)))
                else:
                    directories.append(item)
    return directories


Instruction:
Write a Python 3 script to
copy a directory recursively.

Response:
def copy_directory(src, dest, force=False):
    ''' Copy an entire directory recursively
    '''
    if os.path.exists(dest) and force is True:
        shutil.rmtree(dest)

    try:
        shutil.copytree(src, dest)
    except OSError as e:
        # If the error was caused because the source wasn't a directory
        if e.errno == errno.ENOTDIR:
            shutil.copy(src, dest)
        else:
            bot.error('Directory not copied. Error: %s' % e)
            sys.exit(1)


Instruction:
Can you generate a brief explanation for the following Python 3 code
def clone(url, tmpdir=None):
    '''clone a repository from Github'''
    if tmpdir is None:
        tmpdir = tempfile.mkdtemp()
    name = os.path.basename(url).replace('.git', '')
    dest = '%s/%s' %(tmpdir,name)
    return_code = os.system('git clone %s %s' %(url,dest))
    if return_code == 0:
        return dest
    bot.error('Error cloning repo.')
    sys.exit(return_code)

Response: clone a repository from Github


Instruction:
Explain what the following Python 3 code does
def run_command(cmd):
    '''run_command uses subprocess to send a command to the terminal.
    :param cmd: the command to send, should be a list for subprocess
    '''
    output = Popen(cmd,stderr=STDOUT,stdout=PIPE)
    t = output.communicate()[0],output.returncode
    output = {'message':t[0],
              'return_code':t[1]}

    return output

Response: run_command uses subprocess to send a command to the terminal.


Instruction:
Explain what the following Python 3 code does
def get_template(name, base=None):
    '''read in and return a template file
    '''
    # If the file doesn't exist, assume relative to base
    template_file = name
    if not os.path.exists(template_file):
        if base is None:
            base = get_templatedir()
        template_file = "%s/%s" %(base, name)

    # Then try again, if it still doesn't exist, bad name
    if os.path.exists(template_file):
        with open(template_file,"r") as filey:
            template = "".join(filey.readlines())
        return template
    bot.error("%s does not exist." %template_file)

Response: read in and return a template file


Instruction:
Write a Python 3 function for
making a substitution for a template_tag in a template

Response:
def sub_template(template,template_tag,substitution):
    '''make a substitution for a template_tag in a template
    '''
    template = template.replace(template_tag,substitution)
    return template


Instruction:
Can you generate the documentation for the following Python 3 function
def get_post_fields(request):
    '''parse through a request, and return fields from post in a dictionary
    '''
    fields = dict()
    for field,value in request.form.items():
        fields[field] = value
    return fields

Response: parse through a request and return fields from post in a dictionary


Instruction:
Here you have a function in Python 3, explain what it does
def parse(
        data            = None,
        template        = None,
        data_file       = None,
        template_file   = None,
        interp          = None,
        debug           = False,
        predefines      = True,
        int3            = True,
        keep_successful = False,
        printf          = True,
    ):
    """Parse the data stream using the supplied template. The data stream
    WILL NOT be automatically closed.

    :data: Input data, can be either a string or a file-like object (StringIO, file, etc)
    :template: template contents (str)
    :data_file: PATH to the data to be used as the input stream
    :template_file: template file path
    :interp: the interpretor to be used (a default one will be created if ``None``)
    :debug: if debug information should be printed while interpreting the template (false)
    :predefines: if built-in type information should be inserted (true)
    :int3: if debugger breaks are allowed while interpreting the template (true)
    :keep_successful: return any succesfully parsed data instead of raising an error. If an error occurred and ``keep_successful`` is True, then ``_pfp__error`` will be contain the exception object
    :printf: if ``False``, all calls to ``Printf`` (:any:`pfp.native.compat_interface.Printf`) will be noops. (default=``True``)
    :returns: pfp DOM
    """
    if data is None and data_file is None:
        raise Exception("No input data was specified")

    if data is not None and data_file is not None:
        raise Exception("Only one input data may be specified")

    if isinstance(data, six.string_types):
        data = six.StringIO(data)

    if data_file is not None:
        data = open(os.path.expanduser(data_file), "rb")

    if template is None and template_file is None:
        raise Exception("No template specified!")

    if template is not None and template_file is not None:
        raise Exception("Only one template may be specified!")

    orig_filename = "string"
    if template_file is not None:
        orig_filename = template_file
        try:
            with open(os.path.expanduser(template_file), "r") as f:
                template = f.read()
        except Exception as e:
            raise Exception("Could not open template file '{}'".format(template_file))

    # the user may specify their own instance of PfpInterp to be
    # used
    if interp is None:
        interp = pfp.interp.PfpInterp(
            debug  = debug,
            parser = PARSER,
            int3   = int3,
        )

    # so we can consume single bits at a time
    data = BitwrappedStream(data)

    dom = interp.parse(
        data,
        template,
        predefines      = predefines,
        orig_filename   = orig_filename,
        keep_successful = keep_successful,
        printf          = printf,
    )

    # close the data stream if a data_file was specified
    if data_file is not None:
        data.close()

    return dom

Response: Parse the data stream using the supplied template.


Instruction:
Can you tell what is the following Python 3 function doing
def Checksum(params, ctxt, scope, stream, coord):
    checksum_types = {
        0: "CHECKSUM_BYTE", # Treats the file as a set of unsigned bytes
        1: "CHECKSUM_SHORT_LE", # Treats the file as a set of unsigned little-endian shorts
        2: "CHECKSUM_SHORT_BE", # Treats the file as a set of unsigned big-endian shorts
        3: "CHECKSUM_INT_LE", # Treats the file as a set of unsigned little-endian ints
        4: "CHECKSUM_INT_BE", # Treats the file as a set of unsigned big-endian ints
        5: "CHECKSUM_INT64_LE", # Treats the file as a set of unsigned little-endian int64s
        6: "CHECKSUM_INT64_BE", # Treats the file as a set of unsigned big-endian int64s
        7: "CHECKSUM_SUM8", # Same as CHECKSUM_BYTE except result output as 8-bits
        8: "CHECKSUM_SUM16", # Same as CHECKSUM_BYTE except result output as 16-bits
        9: "CHECKSUM_SUM32", # Same as CHECKSUM_BYTE except result output as 32-bits
        10: "CHECKSUM_SUM64", # Same as CHECKSUM_BYTE
        11: "CHECKSUM_CRC16",
        12: "CHECKSUM_CRCCCITT",
        13: _crc32,
        14: _checksum_Adler32
    }

    if len(params) < 1:
        raise errors.InvalidArguments(coord, "at least 1 argument", "{} args".format(len(params)))

    alg = PYVAL(params[0])
    if alg not in checksum_types:
        raise errors.InvalidArguments(coord, "checksum alg must be one of (0-14)", "{}".format(alg))

    start = 0
    if len(params) > 1:
        start = PYVAL(params[1])

    size = 0
    if len(params) > 2:
        size = PYVAL(params[2])

    crc_poly = -1
    if len(params) > 3:
        crc_poly = PYVAL(params[3])

    crc_init = -1
    if len(params) > 4:
        crc_init = PYVAL(params[4])

    stream_pos = stream.tell()

    if start + size == 0:
        stream.seek(0, 0)
        data = stream.read()
    else:
        stream.seek(start, 0)
        data = stream.read(size)

    try:
        return checksum_types[alg](data, crc_init, crc_poly)

    finally:
        # yes, this does execute even though a return statement
        # exists within the try
        stream.seek(stream_pos, 0)

Response: This function runs a simple checksum on a file and returns the result as an int64.


Instruction:
Can you tell what is the following Python 3 function doing
def FindFirst(params, ctxt, scope, stream, coord, interp):
    global FIND_MATCHES_ITER
    FIND_MATCHES_ITER = _find_helper(params, ctxt, scope, stream, coord, interp)

    try:
        first = six.next(FIND_MATCHES_ITER)
        return first.start() + FIND_MATCHES_START_OFFSET
    except StopIteration as e:
        return -1

Response:
This function is identical to the FindAll function except that the return value is the position of the first occurrence of the target
   .


Instruction:
Can you generate the documentation for the following Python 3 function
def FindNext(params, ctxt, scope, stream, coord):
    if FIND_MATCHES_ITER is None:
        raise errors.InvalidState()

    direction = 1
    if len(params) > 0:
        direction = PYVAL(params[0])

    if direction != 1:
        # TODO maybe instead of storing the iterator in FIND_MATCHES_ITER,
        # we should go ahead and find _all the matches in the file and store them
        # in a list, keeping track of the idx of the current match.
        #
        # This would be highly inefficient on large files though.
        raise NotImplementedError("Reverse searching is not yet implemented")

    try:
        next_match = six.next(FIND_MATCHES_ITER)
        return next_match.start() + FIND_MATCHES_START_OFFSET
    except StopIteration as e:
        return -1

Response: This function returns the position of the next occurrence of the target value specified with the FindFirst function.


Instruction:
Explain what the following Python 3 code does
def generate_subid(self, token=None):
    '''assumes a flat (file system) database, organized by experiment id, and
       subject id, with data (json) organized by subject identifier
    '''

    # Not headless auto-increments
    if not token:
        token = str(uuid.uuid4())

    # Headless doesn't use any folder_id, just generated token folder
    return "%s/%s" % (self.study_id, token)

Response: generate a unique id for the current object


Instruction:
Given the following Python 3 function, write the documentation
def list_users(self):
    '''list users, each associated with a filesystem folder
    '''
    folders = glob('%s/*' %(self.database))
    folders.sort()
    return [self.print_user(x) for x in folders]

Response: list users each associated with a filesystem folder


Instruction:
Write a Python 3 function for
printing a filesystem database user

Response:
def print_user(self, user):
    '''print a filesystem database user. A "database" folder that might end with
       the participant status (e.g. _finished) is extracted to print in format

       [folder]                        [identifier][studyid]
       /scif/data/expfactory/xxxx-xxxx   xxxx-xxxx[studyid]

    '''
    status = "active"

    if user.endswith('_finished'):
        status = "finished"

    elif user.endswith('_revoked'):
        status = "revoked"

    subid = os.path.basename(user)
    for ext in ['_revoked','_finished']:
        subid = subid.replace(ext, '')

    subid = '%s\t%s[%s]' %(user, subid, status)
    print(subid)
    return subid


Instruction:
Implement a Python 3 function for
generating a new user on the filesystem

Response:
def generate_user(self, subid=None):
    '''generate a new user on the filesystem, still session based so we
       create a new identifier. This function is called from the users new
       entrypoint, and it assumes we want a user generated with a token.
       since we don't have a database proper, we write the folder name to
       the filesystem
    '''
    # Only generate token if subid being created
    if subid is None:
        token = str(uuid.uuid4())
        subid = self.generate_subid(token=token)

    if os.path.exists(self.data_base):    # /scif/data
        data_base = "%s/%s" %(self.data_base, subid)
        # expfactory/00001
        if not os.path.exists(data_base):
            mkdir_p(data_base)

    return data_base


Instruction:
Write a Python 3 script for
finishing user and return the path to the finished file

Response:
def finish_user(self, subid, ext='finished'):
    '''finish user will append "finished" (or other) to the data folder when
       the user has completed (or been revoked from) the battery.
       For headless, this means that the session is ended and the token
       will not work again to rewrite the result. If the user needs to update
       or redo an experiment, this can be done with a new session. Note that if
       this function is called internally by the application at experiment
       finish, the subid includes a study id (e.g., expfactory/xxxx-xxxx)
       but if called by the user, it may not (e.g., xxxx-xxxx). We check
       for this to ensure it works in both places.
    '''
    if os.path.exists(self.data_base):    # /scif/data

        # Only relevant to filesystem save - the studyid is the top folder
        if subid.startswith(self.study_id):
            data_base = "%s/%s" %(self.data_base, subid)
        else:
            data_base = "%s/%s/%s" %(self.data_base,
                                     self.study_id,
                                     subid)

        # The renamed file will be here
        finished = "%s_%s" % (data_base, ext)

        # Participant already finished
        if os.path.exists(finished):
            self.logger.warning('[%s] is already finished: %s' % (subid, data_base))

        # Exists and can finish
        elif os.path.exists(data_base):
            os.rename(data_base, finished)

        # Not finished, doesn't exist
        else:
            finished = None
            self.logger.warning('%s does not exist, cannot finish. %s' % (data_base, subid))

    return finished


Instruction:
How would you implement a function in Python 3 that
restarts user will remove any "finished" or "revoked" extensions from the user folder to restart the session. This command always comes from the client users function, so we know subid does not start with the study identifer first

Response:
def restart_user(self, subid):
    '''restart user will remove any "finished" or "revoked" extensions from
    the user folder to restart the session. This command always comes from
    the client users function, so we know subid does not start with the
    study identifer first
    '''
    if os.path.exists(self.data_base): # /scif/data/<study_id>
        data_base = "%s/%s" %(self.data_base, subid)
        for ext in ['revoked','finished']:
            folder = "%s_%s" % (data_base, ext)
            if os.path.exists(folder):
                os.rename(folder, data_base)
                self.logger.info('Restarting %s, folder is %s.' % (subid, data_base))

        self.logger.warning('%s does not have revoked or finished folder, no changes necessary.' % (subid))
        return data_base

    self.logger.warning('%s does not exist, cannot restart. %s' % (self.database, subid))


Instruction:
Explain what the following Python 3 code does
def validate_token(self, token):
    '''retrieve a subject based on a token. Valid means we return a participant
       invalid means we return None
    '''
    # A token that is finished or revoked is not valid
    subid = None
    if not token.endswith(('finished','revoked')):
        subid = self.generate_subid(token=token)
        data_base = "%s/%s" %(self.data_base, subid)
        if not os.path.exists(data_base):
            subid = None
    return subid

Response:
retrieve a subject based on a token. Valid means we return a participant
       invalid means we return None


Instruction:
Write a Python 3 script for
refreshing or generate a new token for a user.

Response:
def refresh_token(self, subid):
    '''refresh or generate a new token for a user. If the user is finished,
       this will also make the folder available again for using.'''
    if os.path.exists(self.data_base):    # /scif/data
        data_base = "%s/%s" %(self.data_base, subid)
        if os.path.exists(data_base):
            refreshed = "%s/%s" %(self.database, str(uuid.uuid4()))
            os.rename(data_base, refreshed)
            return refreshed
        self.logger.warning('%s does not exist, cannot rename %s' % (data_base, subid))
    else:
        self.logger.warning('%s does not exist, cannot rename %s' % (self.database, subid))


Instruction:
Here you have a function in Python 3, explain what it does
def save_data(self, session, exp_id, content):
    '''save data will obtain the current subid from the session, and save it
       depending on the database type. Currently we just support flat files'''

    subid = session.get('subid')

    # We only attempt save if there is a subject id, set at start
    data_file = None
    if subid is not None:

        data_base = "%s/%s" %(self.data_base, subid)

        # If not running in headless, ensure path exists
        if not self.headless and not os.path.exists(data_base):
            mkdir_p(data_base)

        # Conditions for saving:
        do_save = False

        # If headless with token pre-generated OR not headless
        if self.headless and os.path.exists(data_base) or not self.headless:
            do_save = True
        if data_base.endswith(('revoked','finished')):
            do_save = False

        # If headless with token pre-generated OR not headless
        if do_save is True:
            data_file = "%s/%s-results.json" %(data_base, exp_id)
            if os.path.exists(data_file):
                self.logger.warning('%s exists, and is being overwritten.' %data_file)
            write_json(content, data_file)

    return data_file

Response: save data will obtain the current subid from the session and save it as json


Instruction:
Write a Python 3 function for
using as a decorator to add the decorated function to the pfp interpreter so that it can be used from within scripts. :param str name: The name of the function as it will be exposed in template scripts. :param pfp.fields.Field ret: The return type of the function (a class) :param pfp.interp.PfpInterp interp: The specific interpreter to add the function to :param bool send_interp: If the current interpreter should be passed to the function. Examples: The example below defines a ``Sum`` function that will return the sum of all parameters passed to the function: :: from pfp.fields import PYVAL @native(name="Sum", ret=pfp.fields.Int64) def sum_numbers(params, ctxt, scope, stream, coord): res = 0 for param in params: res += PYVAL(param) return res The code below is the code for the :any:`Int3 <pfp.native.dbg.int3>` function. Notice that it requires that the interpreter be sent as a parameter: :: @native(name="Int3", ret=pfp.fields.Void, send_interp=True) def int3(params, ctxt, scope, stream, coord, interp): if interp._no_debug: return if interp._int3: interp.debugger = PfpDbg(interp) interp.debugger.cmdloop()

Response:
def native(name, ret, interp=None, send_interp=False):
    """Used as a decorator to add the decorated function to the
    pfp interpreter so that it can be used from within scripts.

    :param str name: The name of the function as it will be exposed in template scripts.
    :param pfp.fields.Field ret: The return type of the function (a class)
    :param pfp.interp.PfpInterp interp: The specific interpreter to add the function to
    :param bool send_interp: If the current interpreter should be passed to the function.

    Examples:

        The example below defines a ``Sum`` function that will return the sum of
        all parameters passed to the function: ::

            from pfp.fields import PYVAL

            @native(name="Sum", ret=pfp.fields.Int64)
            def sum_numbers(params, ctxt, scope, stream, coord):
                res = 0
                for param in params:
                    res += PYVAL(param)
                return res

        The code below is the code for the :any:`Int3 <pfp.native.dbg.int3>` function. Notice that it
        requires that the interpreter be sent as a parameter: ::

            @native(name="Int3", ret=pfp.fields.Void, send_interp=True)
            def int3(params, ctxt, scope, stream, coord, interp):
                if interp._no_debug:
                    return

                if interp._int3:
                    interp.debugger = PfpDbg(interp)
                    interp.debugger.cmdloop()
    """
    def native_decorator(func):
        @functools.wraps(func)
        def native_wrapper(*args, **kwargs):
            return func(*args, **kwargs)

        pfp.interp.PfpInterp.add_native(name, func, ret, interp=interp, send_interp=send_interp)
        return native_wrapper
    return native_decorator


Instruction:
Given the following Python 3 function, write the documentation
def do_peek(self, args):
        s = self._interp._stream
        # make a copy of it
        pos = s.tell()
        saved_bits = collections.deque(s._bits)
        data = s.read(0x10)
        s.seek(pos, 0)
        s._bits = saved_bits

        parts = ["{:02x}".format(ord(data[x:x+1])) for x in range(len(data))]
        if len(parts) != 0x10:
            parts += ["  "] * (0x10 - len(parts))
        hex_line = " ".join(parts)

        res = utils.binary("")
        for x in range(len(data)):
            char = data[x:x+1]
            val = ord(char)
            if 0x20 <= val <= 0x7e:
                res += char
            else:
                res += utils.binary(".")

        if len(res) < 0x10:
            res += utils.binary(" " * (0x10 - len(res)))

        res = "{} {}".format(hex_line, utils.string(res))
        if len(saved_bits) > 0:
            reverse_bits = reversed(list(saved_bits))
            print("bits: {}".format(" ".join(str(x) for x in reverse_bits)))
        print(res)

Response: Peek at the next 16 hex bytes in the input stream::


Instruction:
Explain what the following Python 3 code does
def do_next(self, args):
        self._do_print_from_last_cmd = True
        self._interp.step_over()
        return True

Response: Step over the next statement in the log


Instruction:
Make a summary of the following Python 3 code
def do_step(self, args):
        self._do_print_from_last_cmd = True
        self._interp.step_into()
        return True

Response: Step into the next statement


Instruction:
Write a Python 3 function that can
evaluate the user - supplied statement.

Response:
def do_eval(self, args):
        """Eval the user-supplied statement. Note that you can do anything with
        this command that you can do in a template.

        The resulting value of your statement will be displayed.
        """
        try:
            res = self._interp.eval(args)
            if res is not None:
                if hasattr(res, "_pfp__show"):
                    print(res._pfp__show())
                else:
                    print(repr(res))
        except errors.UnresolvedID as e:
            print("ERROR: " + e.message)
        except Exception as e:
            raise
            print("ERROR: " + e.message)

        return False


Instruction:
Can you generate the documentation for the following Python 3 function
def do_show(self, args):
        args = args.strip()

        to_show = self._interp._root
        if args != "":
            try:
                to_show = self._interp.eval(args)
            except Exception as e:
                print("ERROR: " + e.message)
                return False

        if hasattr(to_show, "_pfp__show"):
            print(to_show._pfp__show())
        else:
            print(repr(to_show))

Response: Show the current structure of __root or show the result of the expression.


Instruction:
Can you generate the documentation for the following Python 3 function
def validate(self, url):
        ''' takes in a Github repository for validation of preview and
            runtime (and possibly tests passing?
        '''

        # Preview must provide the live URL of the repository
        if not url.startswith('http') or not 'github' in url:
            bot.error('Test of preview must be given a Github repostitory.')
            return False

        if not self._validate_preview(url):
            return False

        return True

Response: Validate the URL of a Github repository and return True if validation passes False otherwise


Instruction:
Make a summary of the following Python 3 code
def mask_dict_password(dictionary, secret='***'):
    d = dictionary.copy()
    for k in d:
        if 'password' in k:
            d[k] = secret
    return d

Response: Replace passwords with a secret in a dictionary.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def save():
    '''save is a view to save data. We might want to adjust this to allow for
       updating saved data, but given single file is just one post for now
    '''
    if request.method == 'POST':
        exp_id = session.get('exp_id')
        app.logger.debug('Saving data for %s' %exp_id)

        fields = get_post_fields(request)
        result_file = app.save_data(session=session, content=fields, exp_id=exp_id)

        experiments = app.finish_experiment(session, exp_id)
        app.logger.info('Finished %s, %s remaining.' % (exp_id, len(experiments)))

        # Note, this doesn't seem to be enough to trigger ajax success
        return json.dumps({'success':True}), 200, {'ContentType':'application/json'}
    return json.dumps({'success':False}), 403, {'ContentType':'application/json'}

Response:
save is a view to save data. We need to adjust this to allow for
       updating saved data but we need to adjust this to allow for
       updating saved data but we need to adjust this to allow for
       updating saved data


Instruction:
Can you generate a brief explanation for the following Python 3 code
def save_data(self,session, exp_id, content):
    '''save data will obtain the current subid from the session, and save it
       depending on the database type.'''
    from expfactory.database.models import (
        Participant,
        Result
    )
    subid = session.get('subid')
    bot.info('Saving data for subid %s' % subid)

    # We only attempt save if there is a subject id, set at start
    if subid is not None:
        p = Participant.query.filter(Participant.id == subid).first() # better query here

        # Preference is to save data under 'data', otherwise do all of it
        if "data" in content:
            content = content['data']

        if isinstance(content,dict):
            content = json.dumps(content)

        result = Result(data=content,
                        exp_id=exp_id,
                        participant_id=p.id) # check if changes from str/int
        self.session.add(result)
        p.results.append(result)
        self.session.commit()

        bot.info("Participant: %s" %p)
        bot.info("Result: %s" %result)

Response: save data for the current subject


Instruction:
Create a Python 3 function for
initializing the database, with the default database path or custom of the format sqlite:////scif/data/expfactory.db

Response:
def init_db(self):
    '''initialize the database, with the default database path or custom of
       the format sqlite:////scif/data/expfactory.db

    '''

    # Database Setup, use default if uri not provided
    if self.database == 'sqlite':
        db_path = os.path.join(EXPFACTORY_DATA, '%s.db' % EXPFACTORY_SUBID)
        self.database = 'sqlite:///%s' % db_path

    bot.info("Database located at %s" % self.database)
    self.engine = create_engine(self.database, convert_unicode=True)
    self.session = scoped_session(sessionmaker(autocommit=False,
                                               autoflush=False,
                                               bind=self.engine))

    Base.query = self.session.query_property()

    # import all modules here that might define models so that
    # they will be registered properly on the metadata.  Otherwise
    # you will have to import them first before calling init_db()
    import expfactory.database.models
    Base.metadata.create_all(bind=self.engine)
    self.Base = Base


Instruction:
Here you have a function in Python 3, explain what it does
def reserve_bits(self, num_bits, stream):
        padded = self.interp.get_bitfield_padded()
        num_bits = PYVAL(num_bits)

        if padded:
            num_bits = PYVAL(num_bits)
            if num_bits + self.reserved_bits > self.max_bits:
                return False

        # if unpadded, always allow it
        if not padded:
            if self._cls_bits is None:
                self._cls_bits = []

            # reserve bits will only be called just prior to reading the bits,
            # so check to see if we have enough bits in self._cls_bits, else
            # read what's missing
            diff = len(self._cls_bits) - num_bits
            if diff < 0:
                self._cls_bits += stream.read_bits(-diff)

        self.reserved_bits += num_bits
        return True

Response:
Used to reserve num_bits amount of bits in the track
           .


Instruction:
How would you code a function in Python 3 to
read num_bits bits from the given stream.

Response:
def read_bits(self, stream, num_bits, padded, left_right, endian):
        """Return ``num_bits`` bits, taking into account endianness and
        left-right bit directions
        """
        if self._cls_bits is None and padded:
            raw_bits = stream.read_bits(self.cls.width*8)
            self._cls_bits = self._endian_transform(raw_bits, endian)

        if self._cls_bits is not None:
            if num_bits > len(self._cls_bits):
                raise errors.PfpError("BitfieldRW reached invalid state")

            if left_right:
                res = self._cls_bits[:num_bits]
                self._cls_bits = self._cls_bits[num_bits:]
            else:
                res = self._cls_bits[-num_bits:]
                self._cls_bits = self._cls_bits[:-num_bits]

            return res

        else:
            return stream.read_bits(num_bits)


Instruction:
Write a Python 3 function for
writing the bits to the stream.

Response:
def write_bits(self, stream, raw_bits, padded, left_right, endian):
        """Write the bits. Once the size of the written bits is equal
        to the number of the reserved bits, flush it to the stream
        """
        if padded:
            if left_right:
                self._write_bits += raw_bits
            else:
                self._write_bits = raw_bits + self._write_bits

            if len(self._write_bits) == self.reserved_bits:
                bits = self._endian_transform(self._write_bits, endian)

                # if it's padded, and all of the bits in the field weren't used,
                # we need to flush out the unused bits
                # TODO should we save the value of the unused bits so the data that
                # is written out matches exactly what was read?
                if self.reserved_bits < self.cls.width * 8:
                    filler = [0] * ((self.cls.width * 8) - self.reserved_bits)
                    if left_right:
                        bits += filler
                    else:
                        bits = filler + bits

                stream.write_bits(bits)
                self._write_bits = []

        else:
            # if an unpadded field ended up using the same BitfieldRW and
            # as a previous padded field, there will be unwritten bits left in
            # self._write_bits. These need to be flushed out as well
            if len(self._write_bits) > 0:
                stream.write_bits(self._write_bits)
                self._write_bits = []

            stream.write_bits(raw_bits)


Instruction:
How would you explain what the following Python 3 function does
def _pfp__snapshot(self, recurse=True):
        if hasattr(self, "_pfp__value"):
            self._pfp__snapshot_value = self._pfp__value

Response: Save off the current value of the field


Instruction:
Create a Python 3 function to
process the metadata once the entire struct has been declared.

Response:
def _pfp__process_metadata(self):
        """Process the metadata once the entire struct has been
        declared.
        """
        if self._pfp__metadata_processor is None:
            return

        metadata_info = self._pfp__metadata_processor()
        if isinstance(metadata_info, list):
            for metadata in metadata_info:
                if metadata["type"] == "watch":
                    self._pfp__set_watch(
                        metadata["watch_fields"],
                        metadata["update_func"],
                        *metadata["func_call_info"]
                    )

                elif metadata["type"] == "packed":
                    del metadata["type"]
                    self._pfp__set_packer(**metadata)
                    if self._pfp__can_unpack():
                        self._pfp__unpack_data(self.raw_data)


Instruction:
Can you tell what is the following Python 3 function doing
def _pfp__watch(self, watcher):
        if self._pfp__parent is not None and isinstance(self._pfp__parent, Union):
            self._pfp__parent._pfp__watch(watcher)
        else:
            self._pfp__watchers.append(watcher)

Response: Add the watcher to the list of fields that are watching this field


Instruction:
Given the following Python 3 function, write the documentation
def _pfp__set_watch(self, watch_fields, update_func, *func_call_info):
        self._pfp__watch_fields = watch_fields

        for watch_field in watch_fields:
            watch_field._pfp__watch(self)
        self._pfp__update_func = update_func
        self._pfp__update_func_call_info = func_call_info

Response: Subscribe to update events on each field in watch_fields using update_func to update self s value when watch_field changes


Instruction:
Can you generate a brief explanation for the following Python 3 code
def _pfp__set_packer(self, pack_type, packer=None, pack=None, unpack=None, func_call_info=None):
        self._pfp__pack_type = pack_type
        self._pfp__unpack = unpack
        self._pfp__pack = pack
        self._pfp__packer = packer
        self._pfp__pack_func_call_info = func_call_info

Response:
Set the packer and unpack functions for this field as
       .


Instruction:
Make a summary of the following Python 3 code
def _pfp__pack_data(self):
        if self._pfp__pack_type is None:
            return

        tmp_stream = six.BytesIO()
        self._._pfp__build(bitwrap.BitwrappedStream(tmp_stream))
        raw_data = tmp_stream.getvalue()

        unpack_func = self._pfp__packer
        unpack_args = []
        if self._pfp__packer is not None:
            unpack_func = self._pfp__packer
            unpack_args = [true(), raw_data]
        elif self._pfp__pack is not None:
            unpack_func = self._pfp__pack
            unpack_args = [raw_data]

        # does not need to be converted to a char array
        if not isinstance(unpack_func, functions.NativeFunction):
            io_stream = bitwrap.BitwrappedStream(six.BytesIO(raw_data))
            unpack_args[-1] = Array(len(raw_data), Char, io_stream)

        res = unpack_func.call(unpack_args, *self._pfp__pack_func_call_info, no_cast=True)
        if isinstance(res, Array):
            res = res._pfp__build()

        io_stream = six.BytesIO(res)
        tmp_stream = bitwrap.BitwrappedStream(io_stream)

        self._pfp__no_unpack = True
        self._pfp__parse(tmp_stream)
        self._pfp__no_unpack = False

Response: Pack the nested field containing the data


Instruction:
Explain what the following Python 3 code does
def _pfp__unpack_data(self, raw_data):
        if self._pfp__pack_type is None:
            return
        if self._pfp__no_unpack:
            return

        unpack_func = self._pfp__packer
        unpack_args = []
        if self._pfp__packer is not None:
            unpack_func = self._pfp__packer
            unpack_args = [false(), raw_data]

        elif self._pfp__unpack is not None:
            unpack_func = self._pfp__unpack
            unpack_args = [raw_data]

        # does not need to be converted to a char array
        if not isinstance(unpack_func, functions.NativeFunction):
            io_stream = bitwrap.BitwrappedStream(six.BytesIO(raw_data))
            unpack_args[-1] = Array(len(raw_data), Char, io_stream)

        res = unpack_func.call(unpack_args, *self._pfp__pack_func_call_info, no_cast=True)
        if isinstance(res, Array):
            res = res._pfp__build()

        io_stream = six.BytesIO(res)
        tmp_stream = bitwrap.BitwrappedStream(io_stream)

        tmp_stream.padded = self._pfp__interp.get_bitfield_padded()

        self._ = self._pfp__parsed_packed = self._pfp__pack_type(tmp_stream)

        self._._pfp__watch(self)

Response: Parses the raw data into a set of attributes.


Instruction:
Write a Python 3 script for
handling the watched field that was updated

Response:
def _pfp__handle_updated(self, watched_field):
        """Handle the watched field that was updated
        """
        self._pfp__no_notify = True

        # nested data has been changed, so rebuild the
        # nested data to update the field
        # TODO a global setting to determine this behavior?
        # could slow things down a bit for large nested structures

        # notice the use of _is_ here - 'is' != '=='. '==' uses
        # the __eq__ operator, while is compares id(object) results
        if watched_field is self._:
            self._pfp__pack_data()
        elif self._pfp__update_func is not None:
            self._pfp__update_func.call(
                [self] + self._pfp__watch_fields,
                *self._pfp__update_func_call_info
            )

        self._pfp__no_notify = False


Instruction:
Given the following Python 3 function, write the documentation
def _pfp__width(self):
        raw_output = six.BytesIO()
        output = bitwrap.BitwrappedStream(raw_output)
        self._pfp__build(output)
        output.flush()
        return len(raw_output.getvalue())

Response: Return the width of the field


Instruction:
Can you generate the documentation for the following Python 3 function
def _pfp__set_value(self, new_val):
        if self._pfp__frozen:
            raise errors.UnmodifiableConst()
        self._pfp__value = self._pfp__get_root_value(new_val)
        self._pfp__notify_parent()

Response: Set the new value if type checking is passes potentially


Instruction:
Can you tell what is the following Python 3 function doing
def _pfp__snapshot(self, recurse=True):
        super(Struct, self)._pfp__snapshot(recurse=recurse)

        if recurse:
            for child in self._pfp__children:
                child._pfp__snapshot(recurse=recurse)

Response: Save off the current value of the field


Instruction:
Write a Python 3 script to
restore the snapshotted value without triggering any events.

Response:
def _pfp__restore_snapshot(self, recurse=True):
        """Restore the snapshotted value without triggering any events
        """
        super(Struct, self)._pfp__restore_snapshot(recurse=recurse)

        if recurse:
            for child in self._pfp__children:
                child._pfp__restore_snapshot(recurse=recurse)


Instruction:
Create a Python 3 function to
initialize the struct. Value should be an array of fields one each for each struct member.

Response:
def _pfp__set_value(self, value):
        """Initialize the struct. Value should be an array of
        fields, one each for each struct member.

        :value: An array of fields to initialize the struct with
        :returns: None
        """
        if self._pfp__frozen:
            raise errors.UnmodifiableConst()
        if len(value) != len(self._pfp__children):
            raise errors.PfpError("struct initialization has wrong number of members")

        for x in six.moves.range(len(self._pfp__children)):
            self._pfp__children[x]._pfp__set_value(value[x])


Instruction:
How would you explain what the following Python 3 function does
def _pfp__add_child(self, name, child, stream=None, overwrite=False):
        if not overwrite and self._pfp__is_non_consecutive_duplicate(name, child):
            return self._pfp__handle_non_consecutive_duplicate(name, child)
        elif not overwrite and name in self._pfp__children_map:
            return self._pfp__handle_implicit_array(name, child)
        else:
            child._pfp__parent = self
            self._pfp__children.append(child)
            child._pfp__name = name
            self._pfp__children_map[name] = child
            return child

Response: Add a child to the Struct field.


Instruction:
How would you explain what the following Python 3 function does
def _pfp__handle_non_consecutive_duplicate(self, name, child, insert=True):
        if name in self._pfp__children_map:
            previous_child = self._pfp__children_map[name]

            # DO NOT cause __eq__ to be called, we want to test actual objects, not comparison
            # operators
            if previous_child is not child:
                self._pfp__handle_non_consecutive_duplicate(name, previous_child, insert=False)
                del self._pfp__children_map[name]

        next_suffix = self._pfp__name_collisions.setdefault(name, 0)
        new_name = "{}_{}".format(name, next_suffix)
        child._pfp__name = new_name
        self._pfp__name_collisions[name] = next_suffix + 1
        self._pfp__children_map[new_name] = child
        child._pfp__parent = self

        if insert:
            self._pfp__children.append(child)

        return child

Response: This method handles a non - consecutive duplicate of a new child and potentially one already existing child.


Instruction:
How would you implement a function in Python 3 that
returns True if the child is a non - consecutive duplicate of the named field.

Response:
def _pfp__is_non_consecutive_duplicate(self, name, child):
        """Return True/False if the child is a non-consecutive duplicately named
        field. Consecutive duplicately-named fields are stored in an implicit array,
        non-consecutive duplicately named fields have a numeric suffix appended to their name"""

        if len(self._pfp__children) == 0:
            return False

        # it should be an implicit array
        if self._pfp__children[-1]._pfp__name == name:
            return False

        # if it's elsewhere in the children name map OR a collision sequence has already been
        # started for this name, it should have a numeric suffix
        # appended
        elif name in self._pfp__children_map or name in self._pfp__name_collisions:
            return True

        # else, no collision
        return False


Instruction:
Can you generate the documentation for the following Python 3 function
def _pfp__handle_implicit_array(self, name, child):
        existing_child = self._pfp__children_map[name]
        if isinstance(existing_child, Array):
            # I don't think we should check this
            #
            #if existing_child.field_cls != child.__class__:
            #    raise errors.PfpError("implicit arrays must be sequential!")
            existing_child.append(child)
            return existing_child
        else:
            cls = child._pfp__class if hasattr(child, "_pfp__class") else child.__class__
            ary = Array(0, cls)
            # since the array starts with the first item
            ary._pfp__offset = existing_child._pfp__offset
            ary._pfp__parent = self
            ary._pfp__name = name
            ary.implicit = True
            ary.append(existing_child)
            ary.append(child)

            exist_idx = -1
            for idx,child in enumerate(self._pfp__children):
                if child is existing_child:
                    exist_idx = idx
                    break

            self._pfp__children[exist_idx] = ary
            self._pfp__children_map[name] = ary
            return ary

Response: Handle inserting implicit array elements.


Instruction:
Explain what the following Python 3 code does
def _pfp__parse(self, stream, save_offset=False):
        if save_offset:
            self._pfp__offset = stream.tell()

        res = 0
        for child in self._pfp__children:
            res += child._pfp__parse(stream, save_offset)
        return res

Response: Parse the incoming stream containing the n - bit tag and return the number of bytes parsed.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def _pfp__build(self, stream=None, save_offset=False):
        if save_offset and stream is not None:
            self._pfp__offset = stream.tell()

        # returns either num bytes written or total data
        res = utils.binary("") if stream is None else 0

        # iterate IN ORDER
        for child in self._pfp__children:
            child_res = child._pfp__build(stream, save_offset)
            res += child_res

        return res

Response: Builds the field and writes the result into the stream


Instruction:
Implement a Python 3 function for
showing the contents of the struct

Response:
def _pfp__show(self, level=0, include_offset=False):
        """Show the contents of the struct
        """
        res = []
        res.append("{}{} {{".format(
            "{:04x} ".format(self._pfp__offset) if include_offset else "",
            self._pfp__show_name
        ))
        for child in self._pfp__children:
            res.append("{}{}{:10s} = {}".format(
                "    "*(level+1),
                "{:04x} ".format(child._pfp__offset) if include_offset else "",
                child._pfp__name,
                child._pfp__show(level+1, include_offset)
            ))
        res.append("{}}}".format("    "*level))
        return "\n".join(res)


Instruction:
Can you create a Python 3 function that
adds a child to the Union field

Response:
def _pfp__add_child(self, name, child, stream=None):
        """Add a child to the Union field

        :name: The name of the child
        :child: A :class:`.Field` instance
        :returns: The resulting field
        """
        res = super(Union, self)._pfp__add_child(name, child)
        self._pfp__buff.seek(0, 0)
        child._pfp__build(stream=self._pfp__buff)
        size = len(self._pfp__buff.getvalue())
        self._pfp__buff.seek(0, 0)

        if stream is not None:
            curr_pos = stream.tell()
            stream.seek(curr_pos-size, 0)

        return res


Instruction:
Implement a Python 3 function for
handling a child with an updated value

Response:
def _pfp__notify_update(self, child=None):
        """Handle a child with an updated value
        """
        if getattr(self, "_pfp__union_update_other_children", True):
            self._pfp__union_update_other_children = False

            new_data = child._pfp__build()
            new_stream =  bitwrap.BitwrappedStream(six.BytesIO(new_data))
            for other_child in self._pfp__children:
                if other_child is child:
                    continue

                if isinstance(other_child, Array) and other_child.is_stringable():
                    other_child._pfp__set_value(new_data)
                else:
                    other_child._pfp__parse(new_stream)
                new_stream.seek(0)

            self._pfp__no_update_other_children = True

        super(Union, self)._pfp__notify_update(child=child)


Instruction:
Here you have a function in Python 3, explain what it does
def _pfp__parse(self, stream, save_offset=False):
        if save_offset:
            self._pfp__offset = stream.tell()

        max_res = 0
        for child in self._pfp__children:
            child_res = child._pfp__parse(stream, save_offset)
            if child_res > max_res:
                max_res = child_res

            # rewind the stream
            stream.seek(child_res, -1)
        self._pfp__size = max_res

        self._pfp__buff = six.BytesIO(stream.read(self._pfp__size))
        return max_res

Response: Parse the incoming stream containing the current set of entries.


Instruction:
Can you generate the documentation for the following Python 3 function
def _pfp__build(self, stream=None, save_offset=False):
        max_size = -1
        if stream is None:
            core_stream = six.BytesIO()
            new_stream = bitwrap.BitwrappedStream(core_stream)
        else:
            new_stream = stream

        for child in self._pfp__children:
            curr_pos = new_stream.tell()
            child._pfp__build(new_stream, save_offset)
            size = new_stream.tell() - curr_pos
            new_stream.seek(-size, 1)

            if size > max_size:
                max_size = size

        new_stream.seek(max_size, 1)

        if stream is None:
            return core_stream.getvalue()
        else:
            return max_size

Response: Builds the union and writes the result into the stream.


Instruction:
Explain what the following Python 3 code does
def _pfp__parse(self, stream, save_offset=False):
        if save_offset:
            self._pfp__offset = stream.tell()

        if self.bitsize is None:
            raw_data = stream.read(self.width)
            data = utils.binary(raw_data)

        else:
            bits = self.bitfield_rw.read_bits(stream, self.bitsize, self.bitfield_padded, self.bitfield_left_right, self.endian)
            width_diff = self.width  - (len(bits)//8) - 1
            bits_diff = 8 - (len(bits) % 8)

            padding = [0] * (width_diff * 8 + bits_diff)

            bits = padding + bits

            data = bitwrap.bits_to_bytes(bits)
            if self.endian == LITTLE_ENDIAN:
                # reverse the data
                data = data[::-1]

        if len(data) < self.width:
            raise errors.PrematureEOF()

        self._pfp__data = data
        self._pfp__value = struct.unpack(
            "{}{}".format(self.endian, self.format),
            data
        )[0]

        return self.width

Response: Parse the data for the numeric field.


Instruction:
Explain what the following Python 3 code does
def _pfp__build(self, stream=None, save_offset=False):
        if stream is not None and save_offset:
            self._pfp__offset = stream.tell()

        if self.bitsize is None:
            data = struct.pack(
                "{}{}".format(self.endian, self.format),
                self._pfp__value
            )
            if stream is not None:
                stream.write(data)
                return len(data)
            else:
                return data
        else:
            data = struct.pack(
                "{}{}".format(BIG_ENDIAN, self.format),
                self._pfp__value
            )

            num_bytes = int(math.ceil(self.bitsize / 8.0))
            bit_data = data[-num_bytes:]

            raw_bits = bitwrap.bytes_to_bits(bit_data)
            bits = raw_bits[-self.bitsize:]

            if stream is not None:
                self.bitfield_rw.write_bits(stream, bits, self.bitfield_padded, self.bitfield_left_right, self.endian)
                return len(bits) // 8
            else:
                # TODO this can't be right....
                return bits

Response: Builds the field and writes the result into the stream


Instruction:
Given the following Python 3 function, write the documentation
def _dom_class(self, obj1, obj2):
        if isinstance(obj1, Double) or isinstance(obj2, Double):
            return Double
        if isinstance(obj1, Float) or isinstance(obj2, Float):
            return Float

Response: Returns the dominating numeric class between the two objects.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def _pfp__set_value(self, new_val):
        if self._pfp__frozen:
            raise errors.UnmodifiableConst()

        if isinstance(new_val, IntBase):
            # will automatically convert correctly between ints of
            # different sizes, unsigned/signed, etc
            raw = new_val._pfp__build()
            while len(raw) < self.width:
                if self.endian == BIG_ENDIAN:
                    raw = b"\x00" + raw
                else:
                    raw += b"\x00"

            while len(raw) > self.width:
                if self.endian == BIG_ENDIAN:
                    raw = raw[1:]
                else:
                    raw = raw[:-1]

            self._pfp__parse(six.BytesIO(raw))
        else:
            mask = 1 << (8*self.width)

            if self.signed:
                max_val = (mask//2)-1
                min_val = -(mask//2)
            else:
                max_val = mask-1
                min_val = 0

            if new_val < min_val:
                new_val += -(min_val)
                new_val &= (mask-1)
                new_val -= -(min_val)
            elif new_val > max_val:
                new_val &= (mask-1)

            self._pfp__value = new_val

        self._pfp__notify_parent()

Response: Set the value of the internal field.


Instruction:
Write a Python 3 script to
parse the IO stream for this enum

Response:
def _pfp__parse(self, stream, save_offset=False):
        """Parse the IO stream for this enum

        :stream: An IO stream that can be read from
        :returns: The number of bytes parsed
        """
        res = super(Enum, self)._pfp__parse(stream, save_offset)

        if self._pfp__value in self.enum_vals:
            self.enum_name = self.enum_vals[self._pfp__value]
        else:
            self.enum_name = "?? UNK_ENUM ??"

        return res


Instruction:
Can you write a function in Python 3 where it
saves off the current value of the field

Response:
def _pfp__snapshot(self, recurse=True):
        """Save off the current value of the field
        """
        super(Array, self)._pfp__snapshot(recurse=recurse)
        self.snapshot_raw_data = self.raw_data

        if recurse:
            for item in self.items:
                item._pfp__snapshot(recurse=recurse)


Instruction:
Make a summary of the following Python 3 code
def _pfp__set_value(self, new_val):
        if not isinstance(new_val, Field):
            new_val = utils.binary(utils.string_escape(new_val))
        super(String, self)._pfp__set_value(new_val)

Response: Set the value of the String.


Instruction:
Write a Python 3 function that can
read from the input stream until the string is null - terminated.

Response:
def _pfp__parse(self, stream, save_offset=False):
        """Read from the stream until the string is null-terminated

        :stream: The input stream
        :returns: None

        """
        if save_offset:
            self._pfp__offset = stream.tell()

        res = utils.binary("")
        while True:
            byte = utils.binary(stream.read(self.read_size))
            if len(byte) < self.read_size:
                raise errors.PrematureEOF()
            # note that the null terminator must be added back when
            # built again!
            if byte == self.terminator:
                break
            res += byte
        self._pfp__value = res


Instruction:
Here you have a function in Python 3, explain what it does
def _pfp__build(self, stream=None, save_offset=False):
        if stream is not None and save_offset:
            self._pfp__offset = stream.tell()

        data = self._pfp__value + utils.binary("\x00")
        if stream is None:
            return data
        else:
            stream.write(data)
            return len(data)

Response: Builds the String field


Instruction:
Write a Python 3 script for
printing a format string to stdout.

Response:
def Printf(params, ctxt, scope, stream, coord, interp):
    """Prints format string to stdout

    :params: TODO
    :returns: TODO

    """
    if len(params) == 1:
        if interp._printf:
            sys.stdout.write(PYSTR(params[0]))
        return len(PYSTR(params[0]))

    parts = []
    for part in params[1:]:
        if isinstance(part, pfp.fields.Array) or isinstance(part, pfp.fields.String):
            parts.append(PYSTR(part))
        else:
            parts.append(PYVAL(part))

    to_print = PYSTR(params[0]) % tuple(parts)
    res = len(to_print)

    if interp._printf:
        sys.stdout.write(to_print)
        sys.stdout.flush()
    return res