Instruction:
Can you tell what is the following Python 3 function doing
def pattern_to_regex(cls, pattern):
		if isinstance(pattern, unicode):
			return_type = unicode
		elif isinstance(pattern, bytes):
			return_type = bytes
			pattern = pattern.decode(_BYTES_ENCODING)
		else:
			raise TypeError("pattern:{!r} is not a unicode or byte string.".format(pattern))

		pattern = pattern.strip()

		if pattern.startswith('#'):
			# A pattern starting with a hash ('#') serves as a comment
			# (neither includes nor excludes files). Escape the hash with a
			# back-slash to match a literal hash (i.e., '\#').
			regex = None
			include = None

		elif pattern == '/':
			# EDGE CASE: According to `git check-ignore` (v2.4.1), a single
			# '/' does not match any file.
			regex = None
			include = None

		elif pattern:

			if pattern.startswith('!'):
				# A pattern starting with an exclamation mark ('!') negates the
				# pattern (exclude instead of include). Escape the exclamation
				# mark with a back-slash to match a literal exclamation mark
				# (i.e., '\!').
				include = False
				# Remove leading exclamation mark.
				pattern = pattern[1:]
			else:
				include = True

			if pattern.startswith('\\'):
				# Remove leading back-slash escape for escaped hash ('#') or
				# exclamation mark ('!').
				pattern = pattern[1:]

			# Split pattern into segments.
			pattern_segs = pattern.split('/')

			# Normalize pattern to make processing easier.

			if not pattern_segs[0]:
				# A pattern beginning with a slash ('/') will only match paths
				# directly on the root directory instead of any descendant
				# paths. So, remove empty first segment to make pattern relative
				# to root.
				del pattern_segs[0]

			elif len(pattern_segs) == 1 or (len(pattern_segs) == 2 and not pattern_segs[1]):
				# A single pattern without a beginning slash ('/') will match
				# any descendant path. This is equivalent to "**/{pattern}". So,
				# prepend with double-asterisks to make pattern relative to
				# root.
				# EDGE CASE: This also holds for a single pattern with a
				# trailing slash (e.g. dir/).
				if pattern_segs[0] != '**':
					pattern_segs.insert(0, '**')

			else:
				# EDGE CASE: A pattern without a beginning slash ('/') but
				# contains at least one prepended directory (e.g.
				# "dir/{pattern}") should not match "**/dir/{pattern}",
				# according to `git check-ignore` (v2.4.1).
				pass

			if not pattern_segs[-1] and len(pattern_segs) > 1:
				# A pattern ending with a slash ('/') will match all descendant
				# paths if it is a directory but not if it is a regular file.
				# This is equivilent to "{pattern}/**". So, set last segment to
				# double asterisks to include all descendants.
				pattern_segs[-1] = '**'

			# Build regular expression from pattern.
			output = ['^']
			need_slash = False
			end = len(pattern_segs) - 1
			for i, seg in enumerate(pattern_segs):
				if seg == '**':
					if i == 0 and i == end:
						# A pattern consisting solely of double-asterisks ('**')
						# will match every path.
						output.append('.+')
					elif i == 0:
						# A normalized pattern beginning with double-asterisks
						# ('**') will match any leading path segments.
						output.append('(?:.+/)?')
						need_slash = False
					elif i == end:
						# A normalized pattern ending with double-asterisks ('**')
						# will match any trailing path segments.
						output.append('/.*')
					else:
						# A pattern with inner double-asterisks ('**') will match
						# multiple (or zero) inner path segments.
						output.append('(?:/.+)?')
						need_slash = True
				elif seg == '*':
					# Match single path segment.
					if need_slash:
						output.append('/')
					output.append('[^/]+')
					need_slash = True
				else:
					# Match segment glob pattern.
					if need_slash:
						output.append('/')
					output.append(cls._translate_segment_glob(seg))
					if i == end and include is True:
						# A pattern ending without a slash ('/') will match a file
						# or a directory (with paths underneath it). E.g., "foo"
						# matches "foo", "foo/bar", "foo/bar/baz", etc.
						# EDGE CASE: However, this does not hold for exclusion cases
						# according to `git check-ignore` (v2.4.1).
						output.append('(?:/.*)?')
					need_slash = True
			output.append('$')
			regex = ''.join(output)

		else:
			# A blank pattern is a null-operation (neither includes nor
			# excludes files).
			regex = None
			include = None

		if regex is not None and return_type is bytes:
			regex = regex.encode(_BYTES_ENCODING)

		return regex, include

Response: Convert a pattern into a regular expression.


Instruction:
Create a Python 3 function to
translate the glob pattern to a regular expression. This is used in the constructor to translate a path segment glob pattern to its corresponding regular expression. *pattern* (:class:`str`) is the glob pattern. Returns the regular expression (:class:`str`).

Response:
def _translate_segment_glob(pattern):
		"""
		Translates the glob pattern to a regular expression. This is used in
		the constructor to translate a path segment glob pattern to its
		corresponding regular expression.

		*pattern* (:class:`str`) is the glob pattern.

		Returns the regular expression (:class:`str`).
		"""
		# NOTE: This is derived from `fnmatch.translate()` and is similar to
		# the POSIX function `fnmatch()` with the `FNM_PATHNAME` flag set.

		escape = False
		regex = ''
		i, end = 0, len(pattern)
		while i < end:
			# Get next character.
			char = pattern[i]
			i += 1

			if escape:
				# Escape the character.
				escape = False
				regex += re.escape(char)

			elif char == '\\':
				# Escape character, escape next character.
				escape = True

			elif char == '*':
				# Multi-character wildcard. Match any string (except slashes),
				# including an empty string.
				regex += '[^/]*'

			elif char == '?':
				# Single-character wildcard. Match any single character (except
				# a slash).
				regex += '[^/]'

			elif char == '[':
				# Braket expression wildcard. Except for the beginning
				# exclamation mark, the whole braket expression can be used
				# directly as regex but we have to find where the expression
				# ends.
				# - "[][!]" matchs ']', '[' and '!'.
				# - "[]-]" matchs ']' and '-'.
				# - "[!]a-]" matchs any character except ']', 'a' and '-'.
				j = i
				# Pass brack expression negation.
				if j < end and pattern[j] == '!':
					j += 1
				# Pass first closing braket if it is at the beginning of the
				# expression.
				if j < end and pattern[j] == ']':
					j += 1
				# Find closing braket. Stop once we reach the end or find it.
				while j < end and pattern[j] != ']':
					j += 1

				if j < end:
					# Found end of braket expression. Increment j to be one past
					# the closing braket:
					#
					#  [...]
					#   ^   ^
					#   i   j
					#
					j += 1
					expr = '['

					if pattern[i] == '!':
						# Braket expression needs to be negated.
						expr += '^'
						i += 1
					elif pattern[i] == '^':
						# POSIX declares that the regex braket expression negation
						# "[^...]" is undefined in a glob pattern. Python's
						# `fnmatch.translate()` escapes the caret ('^') as a
						# literal. To maintain consistency with undefined behavior,
						# I am escaping the '^' as well.
						expr += '\\^'
						i += 1

					# Build regex braket expression. Escape slashes so they are
					# treated as literal slashes by regex as defined by POSIX.
					expr += pattern[i:j].replace('\\', '\\\\')

					# Add regex braket expression to regex result.
					regex += expr

					# Set i to one past the closing braket.
					i = j

				else:
					# Failed to find closing braket, treat opening braket as a
					# braket literal instead of as an expression.
					regex += '\\['

			else:
				# Regular character, escape it for regex.
				regex += re.escape(char)

		return regex


Instruction:
Here you have a function in Python 3, explain what it does
def pattern_to_regex(cls, *args, **kw):
		cls._deprecated()
		return super(GitIgnorePattern, cls).pattern_to_regex(*args, **kw)

Response: Override to add deprecation warning to GitIgnorePattern. pattern_to_regex.


Instruction:
Here you have a function in Python 3, explain what it does
def iter_tree(root, on_error=None, follow_links=None):
	if on_error is not None and not callable(on_error):
		raise TypeError("on_error:{!r} is not callable.".format(on_error))

	if follow_links is None:
		follow_links = True

	for file_rel in _iter_tree_next(os.path.abspath(root), '', {}, on_error, follow_links):
		yield file_rel

Response: Walks the specified directory for all files and yields the absolute paths to each file in the tree.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def _iter_tree_next(root_full, dir_rel, memo, on_error, follow_links):
	dir_full = os.path.join(root_full, dir_rel)
	dir_real = os.path.realpath(dir_full)

	# Remember each encountered ancestor directory and its canonical
	# (real) path. If a canonical path is encountered more than once,
	# recursion has occurred.
	if dir_real not in memo:
		memo[dir_real] = dir_rel
	else:
		raise RecursionError(real_path=dir_real, first_path=memo[dir_real], second_path=dir_rel)

	for node in os.listdir(dir_full):
		node_rel = os.path.join(dir_rel, node)
		node_full = os.path.join(root_full, node_rel)

		# Inspect child node.
		try:
			node_stat = os.lstat(node_full)
		except OSError as e:
			if on_error is not None:
				on_error(e)
			continue

		if stat.S_ISLNK(node_stat.st_mode):
			# Child node is a link, inspect the target node.
			is_link = True
			try:
				node_stat = os.stat(node_full)
			except OSError as e:
				if on_error is not None:
					on_error(e)
				continue
		else:
			is_link = False

		if stat.S_ISDIR(node_stat.st_mode) and (follow_links or not is_link):
			# Child node is a directory, recurse into it and yield its
			# decendant files.
			for file_rel in _iter_tree_next(root_full, node_rel, memo, on_error, follow_links):
				yield file_rel

		elif stat.S_ISREG(node_stat.st_mode):
			# Child node is a file, yield it.
			yield node_rel

	# NOTE: Make sure to remove the canonical (real) path of the directory
	# from the ancestors memo once we are done with it. This allows the
	# same directory to appear multiple times. If this is not done, the
	# second occurance of the directory will be incorrectly interpreted as
	# a recursion. See <https://github.com/cpburnz/python-path-specification/pull/7>.
	del memo[dir_real]

Response: Iterate the directory tree and return the next entry in the tree.


Instruction:
Create a Python 3 function to
match the file to the patterns. contains the patterns to use. contains the patterns to use. returns a boolean indicating if the file is matched.

Response:
def match_file(patterns, file):
	"""
	Matches the file to the patterns.

	*patterns* (:class:`~collections.abc.Iterable` of :class:`~pathspec.pattern.Pattern`)
	contains the patterns to use.

	*file* (:class:`str`) is the normalized file path to be matched
	against *patterns*.

	Returns :data:`True` if *file* matched; otherwise, :data:`False`.
	"""
	matched = False
	for pattern in patterns:
		if pattern.include is not None:
			if file in pattern.match((file,)):
				matched = pattern.include
	return matched


Instruction:
How would you implement a function in Python 3 that
matches the files to the patterns.

Response:
def match_files(patterns, files):
	"""
	Matches the files to the patterns.

	*patterns* (:class:`~collections.abc.Iterable` of :class:`~pathspec.pattern.Pattern`)
	contains the patterns to use.

	*files* (:class:`~collections.abc.Iterable` of :class:`str`) contains
	the normalized file paths to be matched against *patterns*.

	Returns the matched files (:class:`set` of :class:`str`).
	"""
	all_files = files if isinstance(files, collection_type) else list(files)
	return_files = set()
	for pattern in patterns:
		if pattern.include is not None:
			result_files = pattern.match(all_files)
			if pattern.include:
				return_files.update(result_files)
			else:
				return_files.difference_update(result_files)
	return return_files


Instruction:
Can you generate a brief explanation for the following Python 3 code
def normalize_file(file, separators=None):
	# Normalize path separators.
	if separators is None:
		separators = NORMALIZE_PATH_SEPS
	norm_file = file
	for sep in separators:
		norm_file = norm_file.replace(sep, posixpath.sep)

	# Remove current directory prefix.
	if norm_file.startswith('./'):
		norm_file = norm_file[2:]

	return norm_file

Response: Normalizes the file path to use the POSIX path separator.


Instruction:
Can you create a Python 3 function that
normalizes the file paths to use the POSIX path separator.

Response:
def normalize_files(files, separators=None):
	"""
	Normalizes the file paths to use the POSIX path separator.

	*files* (:class:`~collections.abc.Iterable` of :class:`str`) contains
	the file paths to be normalized.

	*separators* (:class:`~collections.abc.Collection` of :class:`str`; or
	:data:`None`) optionally contains the path separators to normalize.
	See :func:`normalize_file` for more information.

	Returns a :class:`dict` mapping the each normalized file path (:class:`str`)
	to the original file path (:class:`str`)
	"""
	norm_files = {}
	for path in files:
		norm_files[normalize_file(path, separators=separators)] = path
	return norm_files


Instruction:
Can you create a Python 3 function that
registers a pattern factory.

Response:
def register_pattern(name, pattern_factory, override=None):
	"""
	Registers the specified pattern factory.

	*name* (:class:`str`) is the name to register the pattern factory
	under.

	*pattern_factory* (:class:`~collections.abc.Callable`) is used to
	compile patterns. It must accept an uncompiled pattern (:class:`str`)
	and return the compiled pattern (:class:`.Pattern`).

	*override* (:class:`bool` or :data:`None`) optionally is whether to
	allow overriding an already registered pattern under the same name
	(:data:`True`), instead of raising an :exc:`AlreadyRegisteredError`
	(:data:`False`). Default is :data:`None` for :data:`False`.
	"""
	if not isinstance(name, string_types):
		raise TypeError("name:{!r} is not a string.".format(name))
	if not callable(pattern_factory):
		raise TypeError("pattern_factory:{!r} is not callable.".format(pattern_factory))
	if name in _registered_patterns and not override:
		raise AlreadyRegisteredError(name, _registered_patterns[name])
	_registered_patterns[name] = pattern_factory


Instruction:
Create a Python 3 function to
return the error message.

Response:
def message(self):
		"""
		*message* (:class:`str`) is the error message.
		"""
		return "Real path {real!r} was encountered at {first!r} and then {second!r}.".format(
			real=self.real_path,
			first=self.first_path,
			second=self.second_path,
		)


Instruction:
Can you implement a function in Python 3 that
matches this pattern against the specified files.

Response:
def match(self, files):
		"""
		Matches this pattern against the specified files.

		*files* (:class:`~collections.abc.Iterable` of :class:`str`) contains
		each file relative to the root directory (e.g., ``"relative/path/to/file"``).

		Returns an :class:`~collections.abc.Iterable` yielding each matched
		file path (:class:`str`).
		"""
		raise NotImplementedError("{}.{} must override match().".format(self.__class__.__module__, self.__class__.__name__))


Instruction:
Create a Python 3 function to
match this pattern against the specified files.

Response:
def match(self, files):
		"""
		Matches this pattern against the specified files.

		*files* (:class:`~collections.abc.Iterable` of :class:`str`)
		contains each file relative to the root directory (e.g., "relative/path/to/file").

		Returns an :class:`~collections.abc.Iterable` yielding each matched
		file path (:class:`str`).
		"""
		if self.include is not None:
			for path in files:
				if self.regex.match(path) is not None:
					yield path


Instruction:
How would you code a function in Python 3 to
convert a User to a cached instance representation.

Response:
def user_default_serializer(self, obj):
        """Convert a User to a cached instance representation."""
        if not obj:
            return None
        self.user_default_add_related_pks(obj)
        return dict((
            ('id', obj.id),
            ('username', obj.username),
            self.field_to_json('DateTime', 'date_joined', obj.date_joined),
            self.field_to_json(
                'PKList', 'votes', model=Choice, pks=obj._votes_pks),
        ))


Instruction:
Here you have a function in Python 3, explain what it does
def user_default_loader(self, pk):
        try:
            obj = User.objects.get(pk=pk)
        except User.DoesNotExist:
            return None
        else:
            self.user_default_add_related_pks(obj)
            return obj

Response: Load a User from the database.


Instruction:
Here you have a function in Python 3, explain what it does
def user_default_add_related_pks(self, obj):
        if not hasattr(obj, '_votes_pks'):
            obj._votes_pks = list(obj.votes.values_list('pk', flat=True))

Response: Add related primary keys to a User instance.


Instruction:
Create a Python 3 function for
invalidating cached items when the Group changes.

Response:
def group_default_invalidator(self, obj):
        """Invalidated cached items when the Group changes."""
        user_pks = User.objects.values_list('pk', flat=True)
        return [('User', pk, False) for pk in user_pks]


Instruction:
Make a summary of the following Python 3 code
def question_default_serializer(self, obj):
        if not obj:
            return None
        self.question_default_add_related_pks(obj)
        return dict((
            ('id', obj.id),
            ('question_text', obj.question_text),
            self.field_to_json('DateTime', 'pub_date', obj.pub_date),
            self.field_to_json(
                'PKList', 'choices', model=Choice, pks=obj._choice_pks),
        ))

Response: Convert a Question to a cached instance representation.


Instruction:
How would you code a function in Python 3 to
load a Question from the database.

Response:
def question_default_loader(self, pk):
        """Load a Question from the database."""
        try:
            obj = Question.objects.get(pk=pk)
        except Question.DoesNotExist:
            return None
        else:
            self.question_default_add_related_pks(obj)
            return obj


Instruction:
Given the following Python 3 function, write the documentation
def question_default_add_related_pks(self, obj):
        if not hasattr(obj, '_choice_pks'):
            obj._choice_pks = list(obj.choices.values_list('pk', flat=True))

Response: Add related primary keys to a Question instance.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def choice_default_serializer(self, obj):
        if not obj:
            return None
        self.choice_default_add_related_pks(obj)
        return dict((
            ('id', obj.id),
            ('choice_text', obj.choice_text),
            self.field_to_json(
                'PK', 'question', model=Question, pk=obj.question_id),
            self.field_to_json(
                'PKList', 'voters', model=User, pks=obj._voter_pks)
        ))

Response: Convert a Choice to a cached instance representation.


Instruction:
Write a Python 3 script for
loading a Choice from the database.

Response:
def choice_default_loader(self, pk):
        """Load a Choice from the database."""
        try:
            obj = Choice.objects.get(pk=pk)
        except Choice.DoesNotExist:
            return None
        else:
            self.choice_default_add_related_pks(obj)
            return obj


Instruction:
Can you tell what is the following Python 3 function doing
def choice_default_add_related_pks(self, obj):
        if not hasattr(obj, '_voter_pks'):
            obj._voter_pks = obj.voters.values_list('pk', flat=True)

Response: Add related primary keys to a Choice instance.


Instruction:
Explain what the following Python 3 code does
def choice_default_invalidator(self, obj):
        invalid = [('Question', obj.question_id, True)]
        for pk in obj.voters.values_list('pk', flat=True):
            invalid.append(('User', pk, False))
        return invalid

Response: Invalidated cached items when the Choice changes.


Instruction:
Write a Python 3 function that can
get the Django cache interface.

Response:
def cache(self):
        """Get the Django cache interface.

        This allows disabling the cache with
        settings.USE_DRF_INSTANCE_CACHE=False.  It also delays import so that
        Django Debug Toolbar will record cache requests.
        """
        if not self._cache:
            use_cache = getattr(settings, 'USE_DRF_INSTANCE_CACHE', True)
            if use_cache:
                from django.core.cache import cache
                self._cache = cache
        return self._cache


Instruction:
Implement a Python 3 function for
deleting all versions of a cached instance.

Response:
def delete_all_versions(self, model_name, obj_pk):
        """Delete all versions of a cached instance."""
        if self.cache:
            for version in self.versions:
                key = self.key_for(version, model_name, obj_pk)
                self.cache.delete(key)


Instruction:
Create a Python 3 function to
return the model - specific caching function.

Response:
def model_function(self, model_name, version, func_name):
        """Return the model-specific caching function."""
        assert func_name in ('serializer', 'loader', 'invalidator')
        name = "%s_%s_%s" % (model_name.lower(), version, func_name)
        return getattr(self, name)


Instruction:
How would you code a function in Python 3 to
return the field function.

Response:
def field_function(self, type_code, func_name):
        """Return the field function."""
        assert func_name in ('to_json', 'from_json')
        name = "field_%s_%s" % (type_code.lower(), func_name)
        return getattr(self, name)


Instruction:
Can you generate the documentation for the following Python 3 function
def field_to_json(self, type_code, key, *args, **kwargs):
        assert ':' not in key
        to_json = self.field_function(type_code, 'to_json')
        key_and_type = "%s:%s" % (key, type_code)
        json_value = to_json(*args, **kwargs)
        return key_and_type, json_value

Response: Convert a field to a JSON - serializable representation.


Instruction:
Implement a Python 3 function for
converting a JSON - serializable representation back to a field.

Response:
def field_from_json(self, key_and_type, json_value):
        """Convert a JSON-serializable representation back to a field."""
        assert ':' in key_and_type
        key, type_code = key_and_type.split(':', 1)
        from_json = self.field_function(type_code, 'from_json')
        value = from_json(json_value)
        return key, value


Instruction:
How would you code a function in Python 3 to
get the cached native representation for one or more objects.

Response:
def get_instances(self, object_specs, version=None):
        """Get the cached native representation for one or more objects.

        Keyword arguments:
        object_specs - A sequence of triples (model name, pk, obj):
        - model name - the name of the model
        - pk - the primary key of the instance
        - obj - the instance, or None to load it
        version - The cache version to use, or None for default

        To get the 'new object' representation, set pk and obj to None

        Return is a dictionary:
        key - (model name, pk)
        value - (native representation, pk, object or None)
        """
        ret = dict()
        spec_keys = set()
        cache_keys = []
        version = version or self.default_version

        # Construct all the cache keys to fetch
        for model_name, obj_pk, obj in object_specs:
            assert model_name
            assert obj_pk

            # Get cache keys to fetch
            obj_key = self.key_for(version, model_name, obj_pk)
            spec_keys.add((model_name, obj_pk, obj, obj_key))
            cache_keys.append(obj_key)

        # Fetch the cache keys
        if cache_keys and self.cache:
            cache_vals = self.cache.get_many(cache_keys)
        else:
            cache_vals = {}

        # Use cached representations, or recreate
        cache_to_set = {}
        for model_name, obj_pk, obj, obj_key in spec_keys:

            # Load cached objects
            obj_val = cache_vals.get(obj_key)
            obj_native = json.loads(obj_val) if obj_val else None

            # Invalid or not set - load from database
            if not obj_native:
                if not obj:
                    loader = self.model_function(model_name, version, 'loader')
                    obj = loader(obj_pk)
                serializer = self.model_function(
                    model_name, version, 'serializer')
                obj_native = serializer(obj) or {}
                if obj_native:
                    cache_to_set[obj_key] = json.dumps(obj_native)

            # Get fields to convert
            keys = [key for key in obj_native.keys() if ':' in key]
            for key in keys:
                json_value = obj_native.pop(key)
                name, value = self.field_from_json(key, json_value)
                assert name not in obj_native
                obj_native[name] = value

            if obj_native:
                ret[(model_name, obj_pk)] = (obj_native, obj_key, obj)

        # Save any new cached representations
        if cache_to_set and self.cache:
            self.cache.set_many(cache_to_set)

        return ret


Instruction:
Can you tell what is the following Python 3 function doing
def update_instance(
            self, model_name, pk, instance=None, version=None,
            update_only=False):
        """Create or update a cached instance.

        Keyword arguments are:
        model_name - The name of the model
        pk - The primary key of the instance
        instance - The Django model instance, or None to load it
        versions - Version to update, or None for all
        update_only - If False (default), then missing cache entries will be
            populated and will cause follow-on invalidation.  If True, then
            only entries already in the cache will be updated and cause
            follow-on invalidation.

        Return is a list of tuples (model name, pk, immediate) that also needs
        to be updated.
        """
        versions = [version] if version else self.versions
        invalid = []
        for version in versions:
            serializer = self.model_function(model_name, version, 'serializer')
            loader = self.model_function(model_name, version, 'loader')
            invalidator = self.model_function(
                model_name, version, 'invalidator')
            if serializer is None and loader is None and invalidator is None:
                continue

            if self.cache is None:
                continue

            # Try to load the instance
            if not instance:
                instance = loader(pk)

            if serializer:
                # Get current value, if in cache
                key = self.key_for(version, model_name, pk)
                current_raw = self.cache.get(key)
                current = json.loads(current_raw) if current_raw else None

                # Get new value
                if update_only and current_raw is None:
                    new = None
                else:
                    new = serializer(instance)
                deleted = not instance

                # If cache is invalid, update cache
                invalidate = (current != new) or deleted
                if invalidate:
                    if deleted:
                        self.cache.delete(key)
                    else:
                        self.cache.set(key, json.dumps(new))
            else:
                invalidate = True

            # Invalidate upstream caches
            if instance and invalidate:
                for upstream in invalidator(instance):
                    if isinstance(upstream, str):
                        self.cache.delete(upstream)
                    else:
                        m, i, immediate = upstream
                        if immediate:
                            invalidate_key = self.key_for(version, m, i)
                            self.cache.delete(invalidate_key)
                        invalid.append((m, i, version))
        return invalid

Response: Create or update a cached instance.


Instruction:
Here you have a function in Python 3, explain what it does
def field_date_to_json(self, day):
        if isinstance(day, six.string_types):
            day = parse_date(day)
        return [day.year, day.month, day.day] if day else None

Response: Convert a date triple to a date triple.


Instruction:
Can you create a Python 3 function that
converts a UTC timestamp to a UTC datetime.

Response:
def field_datetime_from_json(self, json_val):
        """Convert a UTC timestamp to a UTC datetime."""
        if type(json_val) == int:
            seconds = int(json_val)
            dt = datetime.fromtimestamp(seconds, utc)
        elif json_val is None:
            dt = None
        else:
            seconds, microseconds = [int(x) for x in json_val.split('.')]
            dt = datetime.fromtimestamp(seconds, utc)
            dt += timedelta(microseconds=microseconds)
        return dt


Instruction:
Can you generate the documentation for the following Python 3 function
def field_datetime_to_json(self, dt):
        if isinstance(dt, six.string_types):
            dt = parse_datetime(dt)
        if not dt:
            return None
        ts = timegm(dt.utctimetuple())
        if dt.microsecond:
            return "{0}.{1:0>6d}".format(ts, dt.microsecond)
        else:
            return ts

Response: Convert a datetime to a UTC timestamp w / microsecond resolution.


Instruction:
Can you write a function in Python 3 where it
converts json_val to a timedelta object.

Response:
def field_timedelta_from_json(self, json_val):
        """Convert json_val to a timedelta object.

        json_val contains total number of seconds in the timedelta.
        If json_val is a string it will be converted to a float.
        """
        if isinstance(json_val, str):
            return timedelta(seconds=float(json_val))
        elif json_val is None:
            return None
        else:
            return timedelta(seconds=json_val)


Instruction:
Can you implement a function in Python 3 that
converts timedelta to value containing total number of seconds.

Response:
def field_timedelta_to_json(self, td):
        """Convert timedelta to value containing total number of seconds.

        If there are fractions of a second the return value will be a
        string, otherwise it will be an int.
        """
        if isinstance(td, six.string_types):
            td = parse_duration(td)
        if not td:
            return None
        if td.microseconds > 0:
            return str(td.total_seconds())
        else:
            return int(td.total_seconds())


Instruction:
How would you implement a function in Python 3 that
loads a PkOnlyQueryset from a JSON dict.

Response:
def field_pklist_from_json(self, data):
        """Load a PkOnlyQueryset from a JSON dict.

        This uses the same format as cached_queryset_from_json
        """
        model = get_model(data['app'], data['model'])
        return PkOnlyQueryset(self, model, data['pks'])


Instruction:
Write a Python 3 function that can
convert a list of primary keys to a JSON dict.

Response:
def field_pklist_to_json(self, model, pks):
        """Convert a list of primary keys to a JSON dict.

        This uses the same format as cached_queryset_to_json
        """
        app_label = model._meta.app_label
        model_name = model._meta.model_name
        return {
            'app': app_label,
            'model': model_name,
            'pks': list(pks),
        }


Instruction:
Write a Python 3 function for
loading a PkOnlyModel from a JSON dict.

Response:
def field_pk_from_json(self, data):
        """Load a PkOnlyModel from a JSON dict."""
        model = get_model(data['app'], data['model'])
        return PkOnlyModel(self, model, data['pk'])


Instruction:
Can you create a Python 3 function that
converts a primary key to a JSON dict.

Response:
def field_pk_to_json(self, model, pk):
        """Convert a primary key to a JSON dict."""
        app_label = model._meta.app_label
        model_name = model._meta.model_name
        return {
            'app': app_label,
            'model': model_name,
            'pk': pk,
        }


Instruction:
Explain what the following Python 3 code does
def choice_voters_changed_update_cache(
        sender, instance, action, reverse, model, pk_set, **kwargs):
    """Update cache when choice.voters changes."""
    if action not in ('post_add', 'post_remove', 'post_clear'):
        # post_clear is not handled, because clear is called in
        # django.db.models.fields.related.ReverseManyRelatedObjects.__set__
        # before setting the new order
        return

    if model == User:
        assert type(instance) == Choice
        choices = [instance]
        if pk_set:
            users = list(User.objects.filter(pk__in=pk_set))
        else:
            users = []
    else:
        if pk_set:
            choices = list(Choice.objects.filter(pk__in=pk_set))
        else:
            choices = []
        users = [instance]

    from .tasks import update_cache_for_instance
    for choice in choices:
        update_cache_for_instance('Choice', choice.pk, choice)
    for user in users:
        update_cache_for_instance('User', user.pk, user)

Response: Update cache when choice. voters changes.


Instruction:
Can you generate the documentation for the following Python 3 function
def post_delete_update_cache(sender, instance, **kwargs):
    name = sender.__name__
    if name in cached_model_names:
        from .tasks import update_cache_for_instance
        update_cache_for_instance(name, instance.pk, instance)

Response: Update the cache when an instance is deleted.


Instruction:
Implement a function in Python 3 to
update the cache when an instance is created or modified.

Response:
def post_save_update_cache(sender, instance, created, raw, **kwargs):
    """Update the cache when an instance is created or modified."""
    if raw:
        return
    name = sender.__name__
    if name in cached_model_names:
        delay_cache = getattr(instance, '_delay_cache', False)
        if not delay_cache:
            from .tasks import update_cache_for_instance
            update_cache_for_instance(name, instance.pk, instance)


Instruction:
Create a Python 3 function for
getting the queryset for the action.

Response:
def get_queryset(self):
        """Get the queryset for the action.

        If action is read action, return a CachedQueryset
        Otherwise, return a Django queryset
        """
        queryset = super(CachedViewMixin, self).get_queryset()
        if self.action in ('list', 'retrieve'):
            return CachedQueryset(self.get_queryset_cache(), queryset=queryset)
        else:
            return queryset


Instruction:
How would you code a function in Python 3 to
return the object that is displaying.

Response:
def get_object(self, queryset=None):
        """
        Return the object the view is displaying.

        Same as rest_framework.generics.GenericAPIView, but:
        - Failed assertions instead of deprecations
        """
        # Determine the base queryset to use.
        assert queryset is None, "Passing a queryset is disabled"
        queryset = self.filter_queryset(self.get_queryset())

        # Perform the lookup filtering.
        lookup_url_kwarg = self.lookup_url_kwarg or self.lookup_field
        lookup = self.kwargs.get(lookup_url_kwarg, None)
        assert lookup is not None, "Other lookup methods are disabled"
        filter_kwargs = {self.lookup_field: lookup}
        obj = self.get_object_or_404(queryset, **filter_kwargs)

        # May raise a permission denied
        self.check_object_permissions(self.request, obj)

        return obj


Instruction:
How would you implement a function in Python 3 that
returns an object or raise a 404.

Response:
def get_object_or_404(self, queryset, *filter_args, **filter_kwargs):
        """Return an object or raise a 404.

        Same as Django's standard shortcut, but make sure to raise 404
        if the filter_kwargs don't match the required types.
        """
        if isinstance(queryset, CachedQueryset):
            try:
                return queryset.get(*filter_args, **filter_kwargs)
            except queryset.model.DoesNotExist:
                raise Http404(
                    'No %s matches the given query.' % queryset.model)
        else:
            return get_object_or_404(queryset, *filter_args, **filter_kwargs)


Instruction:
How would you implement a function in Python 3 that
resolves the object. This returns default if present otherwise raises a TypeError.

Response:
def r(self, **kwargs):
        """
        Resolve the object.

        This returns default (if present) or fails on an Empty.
        """
        # by using kwargs we ensure that usage of positional arguments, as if
        # this object were another kind of function, will fail-fast and raise
        # a TypeError
        if 'default' in kwargs:
            default = kwargs.pop('default')
            if kwargs:
                raise TypeError(
                    "Unexpected argument: {}".format(repr(next(iter(kwargs))))
                )
            return default
        else:
            raise JSaneException(
                "Key does not exist: {}".format(repr(self._key_name))
            )


Instruction:
How would you code a function in Python 3 to
resolve the object. This will always succeed, since, if a lookup fails, an Empty instance will be returned farther upstream.

Response:
def r(self, **kwargs):
        """
        Resolve the object.

        This will always succeed, since, if a lookup fails, an Empty
        instance will be returned farther upstream.
        """
        # by using kwargs we ensure that usage of positional arguments, as if
        # this object were another kind of function, will fail-fast and raise
        # a TypeError
        kwargs.pop('default', None)
        if kwargs:
            raise TypeError(
                "Unexpected argument: {}".format(repr(next(iter(kwargs))))
            )
        return self._obj


Instruction:
Write a Python 3 function for
updating the cache for an instance with cascading updates.

Response:
def update_cache_for_instance(
        model_name, instance_pk, instance=None, version=None):
    """Update the cache for an instance, with cascading updates."""
    cache = SampleCache()
    invalid = cache.update_instance(model_name, instance_pk, instance, version)
    for invalid_name, invalid_pk, invalid_version in invalid:
        update_cache_for_instance.delay(
            invalid_name, invalid_pk, version=invalid_version)


Instruction:
Implement a function in Python 3 to
return the primary keys as a list.

Response:
def values_list(self, *args, **kwargs):
        """Return the primary keys as a list.

        The only valid call is values_list('pk', flat=True)
        """
        flat = kwargs.pop('flat', False)
        assert flat is True
        assert len(args) == 1
        assert args[0] == self.model._meta.pk.name
        return self.pks


Instruction:
Here you have a function in Python 3, explain what it does
def count(self):
        if self._primary_keys is None:
            return self.queryset.count()
        else:
            return len(self.pks)

Response: Return a count of instances.


Instruction:
Can you create a Python 3 function that
filters the base queryset.

Response:
def filter(self, **kwargs):
        """Filter the base queryset."""
        assert not self._primary_keys
        self.queryset = self.queryset.filter(**kwargs)
        return self


Instruction:
Explain what the following Python 3 code does
def get(self, *args, **kwargs):
        assert not args
        assert list(kwargs.keys()) == ['pk']
        pk = kwargs['pk']
        model_name = self.model.__name__
        object_spec = (model_name, pk, None)
        instances = self.cache.get_instances((object_spec,))
        try:
            model_data = instances[(model_name, pk)][0]
        except KeyError:
            raise self.model.DoesNotExist(
                "No match for %r with args %r, kwargs %r" %
                (self.model, args, kwargs))
        else:
            return CachedModel(self.model, model_data)

Response: Return the single item from the filtered queryset.


Instruction:
How would you code a function in Python 3 to
load all constant generators from settings. WEBPACK_CONSTANT_PROCESSORS and concat their values.

Response:
def collect(cls):
        """ Load all constant generators from settings.WEBPACK_CONSTANT_PROCESSORS
            and concat their values.
        """
        constants = {}

        for method_path in WebpackConstants.get_constant_processors():
            method = import_string(method_path)

            if not callable(method):
                raise ImproperlyConfigured('Constant processor "%s" is not callable' % method_path)

            result = method(constants)

            if isinstance(result, dict):
                constants.update(result)

        return constants


Instruction:
Can you implement a function in Python 3 that
validates the phone number.

Response:
def phonenumber_validation(data):
    """ Validates phonenumber

    Similar to phonenumber_field.validators.validate_international_phonenumber() but uses a different message if the
    country prefix is absent.
    """
    from phonenumber_field.phonenumber import to_python
    phone_number = to_python(data)
    if not phone_number:
        return data
    elif not phone_number.country_code:
        raise serializers.ValidationError(_("Phone number needs to include valid country code (E.g +37255555555)."))
    elif not phone_number.is_valid():
        raise serializers.ValidationError(_('The phone number entered is not valid.'))

    return data


Instruction:
Write a Python 3 script for
creating Django translation catalogue for locale.

Response:
def get_catalog(self, locale):
        """Create Django translation catalogue for `locale`."""
        with translation.override(locale):
            translation_engine = DjangoTranslation(locale, domain=self.domain, localedirs=self.paths)

            trans_cat = translation_engine._catalog
            trans_fallback_cat = translation_engine._fallback._catalog if translation_engine._fallback else {}

            return trans_cat, trans_fallback_cat


Instruction:
Here you have a function in Python 3, explain what it does
def get_paths(cls, packages):
        allowable_packages = dict((app_config.name, app_config) for app_config in apps.get_app_configs())
        app_configs = [allowable_packages[p] for p in packages if p in allowable_packages]
        # paths of requested packages
        return [os.path.join(app.path, 'locale') for app in app_configs]

Response: Create list of matching packages for translation engine.


Instruction:
Explain what the following Python 3 code does
def get_catalogue_header_value(cls, catalog, key):
        header_value = None
        if '' in catalog:
            for line in catalog[''].split('\n'):
                if line.startswith('%s:' % key):
                    header_value = line.split(':', 1)[1].strip()

        return header_value

Response: Get. po header value.


Instruction:
Write a Python 3 function for
returning the number of plurals for this catalog language.

Response:
def _num_plurals(self, catalogue):
        """
        Return the number of plurals for this catalog language, or 2 if no
        plural string is available.
        """
        match = re.search(r'nplurals=\s*(\d+)', self.get_plural(catalogue) or '')
        if match:
            return int(match.groups()[0])
        return 2


Instruction:
How would you implement a function in Python 3 that
populates header with correct data from top - most locale file.

Response:
def make_header(self, locale, catalog):
        """Populate header with correct data from top-most locale file."""
        return {
            "po-revision-date": self.get_catalogue_header_value(catalog, 'PO-Revision-Date'),
            "mime-version": self.get_catalogue_header_value(catalog, 'MIME-Version'),
            "last-translator": 'Automatic <hi@thorgate.eu>',
            "x-generator": "Python",
            "language": self.get_catalogue_header_value(catalog, 'Language') or locale,
            "lang": locale,
            "content-transfer-encoding": self.get_catalogue_header_value(catalog, 'Content-Transfer-Encoding'),
            "project-id-version": self.get_catalogue_header_value(catalog, 'Project-Id-Version'),
            "pot-creation-date": self.get_catalogue_header_value(catalog, 'POT-Creation-Date'),
            "domain": self.domain,
            "report-msgid-bugs-to": self.get_catalogue_header_value(catalog, 'Report-Msgid-Bugs-To'),
            "content-type": self.get_catalogue_header_value(catalog, 'Content-Type'),
            "plural-forms": self.get_plural(catalog),
            "language-team": self.get_catalogue_header_value(catalog, 'Language-Team')
        }


Instruction:
Here you have a function in Python 3, explain what it does
def collect_translations(self):
        languages = {}
        locale_data = {}

        for language_code, label in settings.LANGUAGES:
            languages[language_code] = '%s' % label

            # Create django translation engine for `language_code`
            trans_cat, trans_fallback_cat = self.get_catalog(language_code)

            # Add the meta object
            locale_data[language_code] = {}
            locale_data[language_code][""] = self.make_header(language_code, trans_cat)
            num_plurals = self._num_plurals(trans_cat)

            # Next code is largely taken from Django@master (01.10.2017) from `django.views.i18n JavaScriptCatalogue`
            pdict = {}
            seen_keys = set()

            for key, value in itertools.chain(six.iteritems(trans_cat), six.iteritems(trans_fallback_cat)):
                if key == '' or key in seen_keys:
                    continue

                if isinstance(key, six.string_types):
                    locale_data[language_code][key] = [value]

                elif isinstance(key, tuple):
                    msgid, cnt = key
                    pdict.setdefault(msgid, {})[cnt] = value

                else:
                    raise TypeError(key)
                seen_keys.add(key)

            for k, v in pdict.items():
                locale_data[language_code][k] = [v.get(i, '') for i in range(num_plurals)]

        for key, value in locale_data.items():
            locale_data[key] = json.dumps(value)

        return languages, locale_data

Response: Collect all domain translations and return a tuple of languages and locale_data


Instruction:
Explain what the following Python 3 code does
def get_endpoint_obj(client, endpoint, object_id):
    ''' Tiny helper function that gets used all over the place to join the object ID to the endpoint and run a GET request, returning the result '''
    endpoint = '/'.join([endpoint, str(object_id)])
    return client.authenticated_request(endpoint).json()

Response: Tiny helper function that gets used all over the place to join the object ID to the endpoint and run a GET request


Instruction:
Make a summary of the following Python 3 code
def update_endpoint_obj(client, endpoint, object_id, revision, data):
    '''
    Helper method to ease the repetitiveness of updating an... SO VERY DRY

    (That's a doubly-effective pun becuase my predecessor - https://github.com/bsmt/wunderpy - found maintaing a Python Wunderlist API to be "as tedious and boring as a liberal arts school poetry slam")
    '''
    data['revision'] = int(revision)
    endpoint = '/'.join([endpoint, str(object_id)])
    return client.authenticated_request(endpoint, 'PATCH', data=data).json()

Response: Update an object in an endpoint


Instruction:
Here you have a function in Python 3, explain what it does
def _validate_response(self, method, response):
        ''' Helper method to validate the given to a Wunderlist API request is as expected '''
        # TODO Fill this out using the error codes here: https://developer.wunderlist.com/documentation/concepts/formats
        # The expected results can change based on API version, so validate this here
        if self.api_version:
            if response.status_code >= 400:
                raise ValueError('{} {}'.format(response.status_code, str(response.json())))
            if method == 'GET':
                assert response.status_code == 200
            elif method == 'POST':
                assert response.status_code == 201
            elif method == 'PATCH':
                assert response.status_code == 200
            elif method == 'DELETE':
                assert response.status_code == 204

Response: Helper method to validate the response to a Wunderlist API request is as expected


Instruction:
Make a summary of the following Python 3 code
def request(self, endpoint, method='GET', headers=None, params=None, data=None):
        '''
        Send a request to the given Wunderlist API endpoint

        Params:
        endpoint -- API endpoint to send request to

        Keyword Args:
        headers -- headers to add to the request
        method -- GET, PUT, PATCH, DELETE, etc.
        params -- parameters to encode in the request
        data -- data to send with the request
        '''
        if not headers:
            headers = {}
        if method in ['POST', 'PATCH', 'PUT']:
            headers['Content-Type'] = 'application/json'
        url = '/'.join([self.api_url, 'v' + self.api_version, endpoint])
        data = json.dumps(data) if data else None
        try:
            response = requests.request(method=method, url=url, params=params, headers=headers, data=data)
        # TODO Does recreating the exception classes 'requests' use suck? Yes, but it sucks more to expose the underlying library I use
        except requests.exceptions.Timeout as e:
            raise wp_exceptions.TimeoutError(e)
        except requests.exceptions.ConnectionError as e:
            raise wp_exceptions.ConnectionError(e)
        self._validate_response(method, response)
        return response

Response: Send a request to the given Wunderlist API endpoint.


Instruction:
Given the following Python 3 function, write the documentation
def get_access_token(self, code, client_id, client_secret):
        '''
        Exchange a temporary code for an access token allowing access to a user's account

        See https://developer.wunderlist.com/documentation/concepts/authorization for more info
        '''
        headers = {
                'Content-Type' : 'application/json'
                }
        data = {
                'client_id' : client_id,
                'client_secret' : client_secret,
                'code' : code,
                }
        str_data = json.dumps(data)
        response = requests.request(method='POST', url=ACCESS_TOKEN_URL, headers=headers, data=str_data)
        status_code = response.status_code
        if status_code != 200:
            raise ValueError("{} -- {}".format(status_code, response.json()))
        return body['access_token']

Response: Get an access token for a user


Instruction:
Implement a Python 3 function for
sending a request to the given Wunderlist API endpoint with X - Access - Token and X - Client - ID headers and ensure the response code is as expected

Response:
def authenticated_request(self, endpoint, method='GET', params=None, data=None):
        '''
        Send a request to the given Wunderlist API with 'X-Access-Token' and 'X-Client-ID' headers and ensure the response code is as expected given the request type

        Params:
        endpoint -- API endpoint to send request to

        Keyword Args:
        method -- GET, PUT, PATCH, DELETE, etc.
        params -- parameters to encode in the request
        data -- data to send with the request
        '''
        headers = {
                'X-Access-Token' : self.access_token,
                'X-Client-ID' : self.client_id
                }
        return self.api.request(endpoint, method=method, headers=headers, params=params, data=data)


Instruction:
Can you generate a brief explanation for the following Python 3 code
def update_list(self, list_id, revision, title=None, public=None):
        ''' Updates the list with the given ID to have the given title and public flag '''
        return lists_endpoint.update_list(self, list_id, revision, title=title, public=public)

Response: Updates the list with the given ID to have the given title and public flag.


Instruction:
Write a Python 3 script to
get the list of tasks for the given ID filtered by the given completion flag

Response:
def get_tasks(self, list_id, completed=False):
        ''' Gets tasks for the list with the given ID, filtered by the given completion flag '''
        return tasks_endpoint.get_tasks(self, list_id, completed=completed)


Instruction:
Can you generate a brief explanation for the following Python 3 code
def create_task(self, list_id, title, assignee_id=None, completed=None, recurrence_type=None, recurrence_count=None, due_date=None, starred=None):
        ''' Creates a new task with the given information in the list with the given ID '''
        return tasks_endpoint.create_task(self, list_id, title, assignee_id=assignee_id, completed=completed, recurrence_type=recurrence_type, recurrence_count=recurrence_count, due_date=due_date, starred=starred)

Response: Creates a new task with the given information in the given ID


Instruction:
Can you generate the documentation for the following Python 3 function
def update_task(self, task_id, revision, title=None, assignee_id=None, completed=None, recurrence_type=None, recurrence_count=None, due_date=None, starred=None, remove=None):
        '''
        Updates the task with the given ID to have the given information

        NOTE: The 'remove' parameter is an optional list of parameters to remove from the given task, e.g. ['due_date']
        '''
        return tasks_endpoint.update_task(self, task_id, revision, title=title, assignee_id=assignee_id, completed=completed, recurrence_type=recurrence_type, recurrence_count=recurrence_count, due_date=due_date, starred=starred, remove=remove)

Response: Updates the task with the given ID to have the given information


Instruction:
Given the following Python 3 function, write the documentation
def update_note(self, note_id, revision, content):
        ''' Updates the note with the given ID to have the given content '''
        return notes_endpoint.update_note(self, note_id, revision, content)

Response: Updates the note with the given ID to have the given content.


Instruction:
Here you have a function in Python 3, explain what it does
def get_task_subtasks(self, task_id, completed=False):
        ''' Gets subtasks for task with given ID '''
        return subtasks_endpoint.get_task_subtasks(self, task_id, completed=completed)

Response: Gets the subtasks for the given task with given ID


Instruction:
Can you tell what is the following Python 3 function doing
def get_list_subtasks(self, list_id, completed=False):
        ''' Gets subtasks for the list with given ID '''
        return subtasks_endpoint.get_list_subtasks(self, list_id, completed=completed)

Response: Gets the list s subtasks for the given ID


Instruction:
How would you implement a function in Python 3 that
creates a new subtask with the given title under the task with the given ID

Response:
def create_subtask(self, task_id, title, completed=False):
        '''
        Creates a subtask with the given title under the task with the given ID

        Return:
        Newly-created subtask
        '''
        return subtasks_endpoint.create_subtask(self, task_id, title, completed=completed)


Instruction:
Explain what the following Python 3 code does
def update_subtask(self, subtask_id, revision, title=None, completed=None):
        '''
        Updates the subtask with the given ID

        See https://developer.wunderlist.com/documentation/endpoints/subtask for detailed parameter information

        Returns:
        Subtask with given ID with properties and revision updated
        '''
        return subtasks_endpoint.update_subtask(self, subtask_id, revision, title=title, completed=completed)

Response: Updates the subtask with the given ID with properties and revision


Instruction:
How would you explain what the following Python 3 function does
def update_list_positions_obj(self, positions_obj_id, revision, values):
        '''
        Updates the ordering of lists to have the given value. The given ID and revision should match the singleton object defining how lists are laid out.

        See https://developer.wunderlist.com/documentation/endpoints/positions for more info

        Return:
        The updated ListPositionsObj-mapped object defining the order of list layout
        '''
        return positions_endpoints.update_list_positions_obj(self, positions_obj_id, revision, values)

Response: Updates the ordering of lists to have the given value.


Instruction:
Can you tell what is the following Python 3 function doing
def update_task_positions_obj(self, positions_obj_id, revision, values):
        '''
        Updates the ordering of tasks in the positions object with the given ID to the ordering in the given values.

        See https://developer.wunderlist.com/documentation/endpoints/positions for more info

        Return:
        The updated TaskPositionsObj-mapped object defining the order of list layout
        '''
        return positions_endpoints.update_task_positions_obj(self, positions_obj_id, revision, values)

Response: Updates the ordering of tasks in the given positions object with the given ID to the given values.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def update_subtask_positions_obj(self, positions_obj_id, revision, values):
        '''
        Updates the ordering of subtasks in the positions object with the given ID to the ordering in the given values.

        See https://developer.wunderlist.com/documentation/endpoints/positions for more info

        Return:
        The updated SubtaskPositionsObj-mapped object defining the order of list layout
        '''
        return positions_endpoints.update_subtask_positions_obj(self, positions_obj_id, revision, values)

Response: Updates the ordering of subtasks in the positions object with the given ID to the given values.


Instruction:
Create a Python 3 function for
checking that the given date string conforms to the given API s date format specification.

Response:
def _check_date_format(date, api):
    ''' Checks that the given date string conforms to the given API's date format specification '''
    try:
        datetime.datetime.strptime(date, api.DATE_FORMAT)
    except ValueError:
        raise ValueError("Date '{}' does not conform to API format: {}".format(date, api.DATE_FORMAT))


Instruction:
Given the following Python 3 function, write the documentation
def get_tasks(client, list_id, completed=False):
    ''' Gets un/completed tasks for the given list ID '''
    params = {
            'list_id' : str(list_id),
            'completed' : completed
            }
    response = client.authenticated_request(client.api.Endpoints.TASKS, params=params)
    return response.json()

Response: Gets un / completed tasks for the given list ID


Instruction:
How would you explain what the following Python 3 function does
def get_task(client, task_id):
    ''' Gets task information for the given ID '''
    endpoint = '/'.join([client.api.Endpoints.TASKS, str(task_id)])
    response = client.authenticated_request(endpoint)
    return response.json()

Response: Gets the task information for the given ID


Instruction:
Can you create a Python 3 function that
creates a task in the given list.

Response:
def create_task(client, list_id, title, assignee_id=None, completed=None, recurrence_type=None, recurrence_count=None, due_date=None, starred=None):
    '''
    Creates a task in the given list

    See https://developer.wunderlist.com/documentation/endpoints/task for detailed parameter information
    '''
    _check_title_length(title, client.api)
    if (recurrence_type is None and recurrence_count is not None) or (recurrence_type is not None and recurrence_count is None):
        raise ValueError("recurrence_type and recurrence_count are required are required together")
    if due_date is not None:
        _check_date_format(due_date, client.api)
    data = {
            'list_id' : int(list_id) if list_id else None,
            'title' : title,
            'assignee_id' : int(assignee_id) if assignee_id else None,
            'completed' : completed,
            'recurrence_type' : recurrence_type,
            'recurrence_count' : int(recurrence_count) if recurrence_count else None,
            'due_date' : due_date,
            'starred' : starred,
            }
    data = { key: value for key, value in data.items() if value is not None }
    response = client.authenticated_request(client.api.Endpoints.TASKS, 'POST', data=data)
    return response.json()


Instruction:
Can you generate a brief explanation for the following Python 3 code
def update_task(client, task_id, revision, title=None, assignee_id=None, completed=None, recurrence_type=None, recurrence_count=None, due_date=None, starred=None, remove=None):
    '''
    Updates the task with the given ID

    See https://developer.wunderlist.com/documentation/endpoints/task for detailed parameter information
    '''
    if title is not None:
        _check_title_length(title, client.api)
    if (recurrence_type is None and recurrence_count is not None) or (recurrence_type is not None and recurrence_count is None):
        raise ValueError("recurrence_type and recurrence_count are required are required together")
    if due_date is not None:
        _check_date_format(due_date, client.api)
    data = {
            'revision' : int(revision),
            'title' : title,
            'assignee_id' : int(assignee_id) if assignee_id else None,
            'completed' : completed,
            'recurrence_type' : recurrence_type,
            'recurrence_count' : int(recurrence_count) if recurrence_count else None,
            'due_date' : due_date,
            'starred' : starred,
            'remove' : remove,
            }
    data = { key: value for key, value in data.items() if value is not None }
    endpoint = '/'.join([client.api.Endpoints.TASKS, str(task_id)])
    response = client.authenticated_request(endpoint, 'PATCH', data=data)
    return response.json()

Response: Updates the task with the given ID.


Instruction:
Implement a Python 3 function for
checking the given title against the given API specifications to ensure it s short enough.

Response:
def _check_title_length(title, api):
    ''' Checks the given title against the given API specifications to ensure it's short enough '''
    if len(title) > api.MAX_LIST_TITLE_LENGTH:
        raise ValueError("Title cannot be longer than {} characters".format(api.MAX_TASK_TITLE_LENGTH))


Instruction:
Create a Python 3 function to
get all the client s lists

Response:
def get_lists(client):
    ''' Gets all the client's lists '''
    response = client.authenticated_request(client.api.Endpoints.LISTS)
    return response.json()


Instruction:
Make a summary of the following Python 3 code
def get_list(client, list_id):
    ''' Gets the given list '''
    endpoint = '/'.join([client.api.Endpoints.LISTS, str(list_id)])
    response = client.authenticated_request(endpoint)
    return response.json()

Response: Gets the given list


Instruction:
Implement a function in Python 3 to
create a new list with the given title

Response:
def create_list(client, title):
    ''' Creates a new list with the given title '''
    _check_title_length(title, client.api)
    data = {
            'title' : title,
            }
    response = client.authenticated_request(client.api.Endpoints.LISTS, method='POST', data=data)
    return response.json()


Instruction:
Here you have a function in Python 3, explain what it does
def update_list(client, list_id, revision, title=None, public=None):
    '''
    Updates the list with the given ID to have the given properties

    See https://developer.wunderlist.com/documentation/endpoints/list for detailed parameter information
    '''
    if title is not None:
        _check_title_length(title, client.api)
    data = {
            'revision' : revision,
            'title' : title,
            'public' : public,
            }
    data = { key: value for key, value in data.items() if value is not None }
    endpoint = '/'.join([client.api.Endpoints.LISTS, str(list_id)])
    response = client.authenticated_request(endpoint, 'PATCH', data=data)
    return response.json()

Response: Updates the list with the given ID to have the given properties.


Instruction:
Implement a Python 3 function for
getting the object that defines how lists are ordered

Response:
def get_list_positions_obj(client, positions_obj_id):
    '''
    Gets the object that defines how lists are ordered (there will always be only one of these)

    See https://developer.wunderlist.com/documentation/endpoints/positions for more info

    Return:
    A ListPositionsObj-mapped object defining the order of list layout
    '''
    return endpoint_helpers.get_endpoint_obj(client, client.api.Endpoints.LIST_POSITIONS, positions_obj_id)


Instruction:
Can you generate the documentation for the following Python 3 function
def update_list_positions_obj(client, positions_obj_id, revision, values):
    '''
    Updates the ordering of lists to have the given value. The given ID and revision should match the singleton object defining how lists are laid out.

    See https://developer.wunderlist.com/documentation/endpoints/positions for more info

    Return:
    The updated ListPositionsObj-mapped object defining the order of list layout
    '''
    return _update_positions_obj(client, client.api.Endpoints.LIST_POSITIONS, positions_obj_id, revision, values)

Response: Updates the ordering of lists to have the given value.


Instruction:
How would you explain what the following Python 3 function does
def get_task_positions_objs(client, list_id):
    '''
    Gets a list containing the object that encapsulates information about the order lists are laid out in. This list will always contain exactly one object.

    See https://developer.wunderlist.com/documentation/endpoints/positions for more info

    Return:
    A list containing a single ListPositionsObj-mapped object
    '''
    params = {
            'list_id' : int(list_id)
            }
    response = client.authenticated_request(client.api.Endpoints.TASK_POSITIONS, params=params)
    return response.json()

Response: Gets a list containing the object that encapsulates information about the order lists are laid out in.


Instruction:
Can you write a function in Python 3 where it
gets all subtask positions objects for the tasks within a given list.

Response:
def get_list_subtask_positions_objs(client, list_id):
    '''
    Gets all subtask positions objects for the tasks within a given list. This is a convenience method so you don't have to get all the list's tasks before getting subtasks, though I can't fathom how mass subtask reordering is useful.

    Returns:
    List of SubtaskPositionsObj-mapped objects representing the order of subtasks for the tasks within the given list
    '''
    params = {
            'list_id' : int(list_id)
            }
    response = client.authenticated_request(client.api.Endpoints.SUBTASK_POSITIONS, params=params)
    return response.json()


Instruction:
Can you create a Python 3 function that
checks the given title against the given API specifications to ensure it s short enough.

Response:
def _check_title_length(title, api):
    ''' Checks the given title against the given API specifications to ensure it's short enough '''
    if len(title) > api.MAX_SUBTASK_TITLE_LENGTH:
        raise ValueError("Title cannot be longer than {} characters".format(api.MAX_SUBTASK_TITLE_LENGTH))


Instruction:
Can you tell what is the following Python 3 function doing
def get_task_subtasks(client, task_id, completed=False):
    ''' Gets subtasks for task with given ID '''
    params = {
            'task_id' : int(task_id),
            'completed' : completed,
            }
    response = client.authenticated_request(client.api.Endpoints.SUBTASKS, params=params)
    return response.json()

Response: Gets the subtasks for a task with given ID


Instruction:
Can you create a Python 3 function that
gets the subtasks for the list with given ID

Response:
def get_list_subtasks(client, list_id, completed=False):
    ''' Gets subtasks for the list with given ID '''
    params = {
            'list_id' : int(list_id),
            'completed' : completed,
            }
    response = client.authenticated_request(client.api.Endpoints.SUBTASKS, params=params)
    return response.json()


Instruction:
Explain what the following Python 3 code does
def get_subtask(client, subtask_id):
    ''' Gets the subtask with the given ID '''
    endpoint = '/'.join([client.api.Endpoints.SUBTASKS, str(subtask_id)])
    response = client.authenticated_request(endpoint)
    return response.json()

Response: Gets the subtask with the given ID


Instruction:
Write a Python 3 script for
creating a subtask under the task with the given title under the task with the given ID

Response:
def create_subtask(client, task_id, title, completed=False):
    ''' Creates a subtask with the given title under the task with the given ID '''
    _check_title_length(title, client.api)
    data = {
            'task_id' : int(task_id) if task_id else None,
            'title' : title,
            'completed' : completed,
            }
    data = { key: value for key, value in data.items() if value is not None }
    response = client.authenticated_request(client.api.Endpoints.SUBTASKS, 'POST', data=data)
    return response.json()


Instruction:
Given the following Python 3 function, write the documentation
def update_subtask(client, subtask_id, revision, title=None, completed=None):
    '''
    Updates the subtask with the given ID

    See https://developer.wunderlist.com/documentation/endpoints/subtask for detailed parameter information
    '''
    if title is not None:
        _check_title_length(title, client.api)
    data = {
            'revision' : int(revision),
            'title' : title,
            'completed' : completed,
            }
    data = { key: value for key, value in data.items() if value is not None }
    endpoint = '/'.join([client.api.Endpoints.SUBTASKS, str(subtask_id)])
    response = client.authenticated_request(endpoint, 'PATCH', data=data)
    return response.json()

Response:
Updates the subtask with the given ID
WorkItem.


Instruction:
Explain what the following Python 3 code does
def delete_subtask(client, subtask_id, revision):
    ''' Deletes the subtask with the given ID provided the given revision equals the revision the server has '''
    params = {
            'revision' : int(revision),
            }
    endpoint = '/'.join([client.api.Endpoints.SUBTASKS, str(subtask_id)])
    client.authenticated_request(endpoint, 'DELETE', params=params)

Response: Deletes the subtask with the given ID provided the given revision equals the revision of the server has.


Instruction:
Can you tell what is the following Python 3 function doing
def wait(animation='elipses', text='', speed=0.2):
    def decorator(func):
        func.animation = animation
        func.speed = speed
        func.text = text

        @wraps(func)
        def wrapper(*args, **kwargs):
            animation = func.animation
            text = func.text
            if not isinstance(animation, (list, tuple)) and \
                    not hasattr(animations, animation):
                text = animation if text == '' else text
                animation = 'elipses'
            wait = Wait(animation=animation, text=text, speed=func.speed)
            wait.start()
            try:
                ret = func(*args, **kwargs)
            finally:
                wait.stop()
            sys.stdout.write('\n')
            return ret
        return wrapper
    return decorator

Response: Decorator for adding wait animation to long running functions.


Instruction:
How would you explain what the following Python 3 function does
def merge(tup):
    if not all(tuple(ts.shape[1:] == tup[0].shape[1:] for ts in tup[1:])):
        raise ValueError('Timeseries to merge must have compatible shapes')
    indices = np.vstack(tuple(ts.tspan for ts in tup)).argsort()
    return np.vstack((tup))[indices]

Response: Merge several Timeseries into a single timeseries with the same shape except for axis 0.


Instruction:
Can you generate the documentation for the following Python 3 function
def add_analyses(cls, source):
        if isinstance(source, types.FunctionType):
            _add_single_method(source.__name__, source)
        else:
            if isinstance(source, types.ModuleType):
                mod = source
            elif isinstance(source, types.StringTypes):
                import os
                import imp
                path = os.path.abspath(source)
                if os.path.isfile(path) and path[-3:] == '.py':
                    dir, file = os.path.split(path)
                    name = file[:-3]
                    module_info = imp.find_module(name, [dir])
                    mod = imp.load_module('nsim.' + name, *module_info)
                elif (os.path.isdir(path) and
                        '__init__.py' in os.listdir(path)):
                    module_info = imp.find_module('__init__', [path])
                    name = os.path.basename(path)
                    mod = imp.load_module('nsim.' + name, *module_info)
                else:
                    raise Error('"%s" is not a file or directory' % source)
            else:
                raise ValueError('`source` argument not a function or module')
            for name, obj in mod.__dict__.items():
                if name[0] != '_' and isinstance(obj, types.FunctionType):
                    cls._add_single_method(name, obj)

Response: Dynamically add new analysis methods to the Timeseries class.


Instruction:
How would you explain what the following Python 3 function does
def absolute(self):
        return Timeseries(np.absolute(self), self.tspan, self.labels)

Response: Calculate the absolute value element - wise.


Instruction:
Write a Python 3 script for
returning the angle of the complex argument.

Response:
def angle(self, deg=False):
        """Return the angle of the complex argument.

        Args:
          deg (bool, optional):
            Return angle in degrees if True, radians if False (default).

        Returns:
          angle (Timeseries):
            The counterclockwise angle from the positive real axis on
            the complex plane, with dtype as numpy.float64.
        """
        if self.dtype.str[1] != 'c':
            warnings.warn('angle() is intended for complex-valued timeseries',
                          RuntimeWarning, 1)
        return Timeseries(np.angle(self, deg=deg), self.tspan, self.labels)


Instruction:
Make a summary of the following Python 3 code
def swapaxes(self, axis1, axis2):
        if self.ndim <=1 or axis1 == axis2:
            return self
        ar = np.asarray(self).swapaxes(axis1, axis2)
        if axis1 != 0 and axis2 != 0:
            # then axis 0 is unaffected by the swap
            labels = self.labels[:]
            labels[axis1], labels[axis2] = labels[axis2], labels[axis1]
            return Timeseries(ar, self.tspan, labels)
        return ar

Response: Interchange two axes of a Timeseries.


Instruction:
Write a Python 3 script to
permute the dimensions of a Timeseries.

Response:
def transpose(self, *axes):
        """Permute the dimensions of a Timeseries."""
        if self.ndim <= 1:
            return self
        ar = np.asarray(self).transpose(*axes)
        if axes[0] != 0:
            # then axis 0 is unaffected by the transposition
            newlabels = [self.labels[ax] for ax in axes]
            return Timeseries(ar, self.tspan, newlabels)
        else:
            return ar


Instruction:
Create a Python 3 function to
merge another timeseries with this one returning a new one whose time points are the same.

Response:
def merge(self, ts):
        """Merge another timeseries with this one
        Arguments:
          ts (Timeseries): The two timeseries being merged must have the
            same shape except for axis 0.
        Returns:
          Resulting merged timeseries which can have duplicate time points.
        """
        if ts.shape[1:] != self.shape[1:]:
            raise ValueError('Timeseries to merge must have compatible shapes')
        indices = np.vstack((self.tspan, ts.tspan)).argsort()
        return np.vstack((self, ts))[indices]


Instruction:
Can you generate a brief explanation for the following Python 3 code
def expand_dims(self, axis):
        if axis == -1:
            axis = self.ndim
        array = np.expand_dims(self, axis)
        if axis == 0:
            # prepended an axis: no longer a Timeseries
            return array
        else:
            new_labels = self.labels.insert(axis, None)
            return Timeseries(array, self.tspan, new_labels)

Response: Returns a new array with the same shape as self.


Instruction:
Here you have a function in Python 3, explain what it does
def concatenate(self, tup, axis=0):
        if not isinstance(tup, Sequence):
            tup = (tup,)
        if tup is (None,) or len(tup) is 0:
            return self
        tup = (self,) + tuple(tup)
        new_array = np.concatenate(tup, axis)
        if not all(hasattr(ts, 'tspan') and
                   hasattr(ts, 'labels') for ts in tup):
            return new_array
        if axis == 0:
            starts = [ts.tspan[0] for ts in tup]
            ends = [ts.tspan[-1] for ts in tup]
            if not all(starts[i] > ends[i-1] for i in range(1, len(starts))):
                # series being joined are not ordered in time. not Timeseries
                return new_array
            else:
                new_tspan = np.concatenate([ts.tspan for ts in tup])
        else:
            new_tspan = self.tspan
        new_labels = [None]
        for ax in range(1, new_array.ndim):
            if ax == axis:
                axislabels = []
                for ts in tup:
                    if ts.labels[axis] is None:
                        axislabels.extend('' * ts.shape[axis])
                    else:
                        axislabels.extend(ts.labels[axis])
                if all(lab == '' for lab in axislabels):
                    new_labels.append(None)
                else:
                    new_labels.append(axislabels)
            else:
                # non-concatenation axis
                axlabels = tup[0].labels[ax]
                if not all(ts.labels[ax] == axlabels for ts in tup[1:]):
                    # series to be joined do not agree on labels for this axis
                    axlabels = None
                new_labels.append(axlabels)
        return self.__new__(self.__class__, new_array, new_tspan, new_labels)

Response: Returns a new array with the elements of tup joined along the specified axis.


Instruction:
Given the following Python 3 function, write the documentation
def split(self, indices_or_sections, axis=0):
        if not isinstance(indices_or_sections, numbers.Integral):
            raise Error('splitting by array of indices is not yet implemented')
        n = indices_or_sections
        if self.shape[axis] % n != 0:
            raise ValueError("Array split doesn't result in an equal division")
        step = self.shape[axis] / n
        pieces = []
        start = 0
        while start < self.shape[axis]:
            stop = start + step
            ix = [slice(None)] * self.ndim
            ix[axis] = slice(start, stop)
            ix = tuple(ix)
            pieces.append(self[ix])
            start += step
        return pieces

Response: Split a timeseries into multiple sub - timeseries.


Instruction:
Can you generate the documentation for the following Python 3 function
def plot(dts, title=None, points=None, show=True):
    if points is not None and len(dts.tspan) > points:
        # then downsample  (TODO: use interpolation)
        ix = np.linspace(0, len(dts.tspan) - 1, points).astype(np.int64)
        dts = dts[ix, ...]
    ts = distob.gather(dts)
    return ts.plot(title, show)

Response: Plot a distributed timeseries.


Instruction:
Can you generate the documentation for the following Python 3 function
def phase_histogram(dts, times=None, nbins=30, colormap=mpl.cm.Blues):
    if times is None:
        times = np.linspace(dts.tspan[0], dts.tspan[-1], num=4)
    elif isinstance(times, numbers.Number):
        times = np.array([times], dtype=np.float64)
    indices = distob.gather(dts.tspan.searchsorted(times))
    if indices[-1] == len(dts.tspan):
        indices[-1] -= 1
    nplots = len(indices)
    fig = plt.figure()
    n = np.zeros((nbins, nplots))
    for i in range(nplots):
        index = indices[i]
        time = dts.tspan[index]
        phases = distob.gather(dts.mod2pi()[index, 0, :])
        ax = fig.add_subplot(1, nplots, i + 1, projection='polar')
        n[:,i], bins, patches = ax.hist(phases, nbins, (-np.pi, np.pi),
                                        density=True, histtype='bar')
        ax.set_title('time = %d s' % time)
        ax.set_xticklabels(['0', r'$\frac{\pi}{4}$', r'$\frac{\pi}{2}$',
                            r'$\frac{3\pi}{4}$', r'$\pi$', r'$\frac{-3\pi}{4}$',
                            r'$\frac{-\pi}{2}$', r'$\frac{-\pi}{4}$'])
    nmin, nmax = n.min(), n.max()
    #TODO should make a custom colormap instead of reducing color dynamic range:
    norm = mpl.colors.Normalize(1.2*nmin - 0.2*nmax,
                                0.6*nmin + 0.4*nmax, clip=True)
    for i in range(nplots):
        ax = fig.get_axes()[i]
        ax.set_ylim(0, nmax)
        for this_n, thispatch in zip(n[:,i], ax.patches):
            color = colormap(norm(this_n))
            thispatch.set_facecolor(color)
            thispatch.set_edgecolor(color)
    fig.show()

Response: Plot a polar histogram of a phase variable s probability distribution.


Instruction:
Can you implement a function in Python 3 that
plots Welch estimate of power spectral density using nperseg samples per segment with noverlap samples overlap and Hamming window.

Response:
def psd(ts, nperseg=1500, noverlap=1200, plot=True):
    """plot Welch estimate of power spectral density, using nperseg samples per
    segment, with noverlap samples overlap and Hamming window."""
    ts = ts.squeeze()
    if ts.ndim is 1:
        ts = ts.reshape((-1, 1))
    fs = (len(ts) - 1.0) / (ts.tspan[-1] - ts.tspan[0])
    window = signal.hamming(nperseg, sym=False)
    nfft = max(256, 2**np.int(np.log2(nperseg) + 1))
    freqs, pxx = signal.welch(ts, fs, window, nperseg, noverlap, nfft,
                              detrend='linear', axis=0)
    # Discard estimates for freq bins that are too low for the window size.
    # (require two full cycles to fit within the window)
    index = np.nonzero(freqs >= 2.0*fs/nperseg)[0][0]
    if index > 0:
        freqs = freqs[index:]
        pxx = pxx[index:]
    # Discard estimate for last freq bin as too high for Nyquist frequency:
    freqs = freqs[:-1]
    pxx = pxx[:-1]
    if plot is True:
        _plot_psd(ts, freqs, pxx)
    return freqs, pxx


Instruction:
Create a Python 3 function to
forward - backward butterworth low - pass filter

Response:
def lowpass(ts, cutoff_hz, order=3):
    """forward-backward butterworth low-pass filter"""
    orig_ndim = ts.ndim
    if ts.ndim is 1:
        ts = ts[:, np.newaxis]
    channels = ts.shape[1]
    fs = (len(ts) - 1.0) / (ts.tspan[-1] - ts.tspan[0])
    nyq = 0.5 * fs
    cutoff = cutoff_hz/nyq
    b, a = signal.butter(order, cutoff, btype='low')
    if not np.all(np.abs(np.roots(a)) < 1.0):
        raise ValueError('Filter will not be stable with these values.')
    dtype = ts.dtype
    output = np.zeros((len(ts), channels), dtype)
    for i in range(channels):
        output[:, i] = signal.filtfilt(b, a, ts[:, i])
    if orig_ndim is 1:
        output = output[:, 0]
    return Timeseries(output, ts.tspan, labels=ts.labels)


Instruction:
How would you explain what the following Python 3 function does
def bandpass(ts, low_hz, high_hz, order=3):
    orig_ndim = ts.ndim
    if ts.ndim is 1:
        ts = ts[:, np.newaxis]
    channels = ts.shape[1]
    fs = (len(ts) - 1.0) / (ts.tspan[-1] - ts.tspan[0])
    nyq = 0.5 * fs
    low = low_hz/nyq
    high = high_hz/nyq
    b, a = signal.butter(order, [low, high], btype='band')
    if not np.all(np.abs(np.roots(a)) < 1.0):
        raise ValueError('Filter will not be stable with these values.')
    dtype = ts.dtype
    output = np.zeros((len(ts), channels), dtype)
    for i in range(channels):
        output[:, i] = signal.filtfilt(b, a, ts[:, i])
    if orig_ndim is 1:
        output = output[:, 0]
    return Timeseries(output, ts.tspan, labels=ts.labels)

Response: forward - backward butterworth band - pass filter


Instruction:
How would you explain what the following Python 3 function does
def notch(ts, freq_hz, bandwidth_hz=1.0):
    orig_ndim = ts.ndim
    if ts.ndim is 1:
        ts = ts[:, np.newaxis]
    channels = ts.shape[1]
    fs = (len(ts) - 1.0) / (ts.tspan[-1] - ts.tspan[0])
    nyq = 0.5 * fs
    freq = freq_hz/nyq
    bandwidth = bandwidth_hz/nyq
    R = 1.0 - 3.0*(bandwidth/2.0)
    K = ((1.0 - 2.0*R*np.cos(np.pi*freq) + R**2) /
         (2.0 - 2.0*np.cos(np.pi*freq)))
    b, a = np.zeros(3), np.zeros(3)
    a[0] = 1.0
    a[1] = -2.0*R*np.cos(np.pi*freq)
    a[2] = R**2
    b[0] = K
    b[1] = -2*K*np.cos(np.pi*freq)
    b[2] = K
    if not np.all(np.abs(np.roots(a)) < 1.0):
        raise ValueError('Filter will not be stable with these values.')
    dtype = ts.dtype
    output = np.zeros((len(ts), channels), dtype)
    for i in range(channels):
        output[:, i] = signal.filtfilt(b, a, ts[:, i])
    if orig_ndim is 1:
        output = output[:, 0]
    return Timeseries(output, ts.tspan, labels=ts.labels)

Response: notch filter to remove a particular frequency


Instruction:
Can you generate a brief explanation for the following Python 3 code
def hilbert(ts):
    output = signal.hilbert(signal.detrend(ts, axis=0), axis=0)
    return Timeseries(output, ts.tspan, labels=ts.labels)

Response: Analytic signal using the Hilbert transform


Instruction:
Make a summary of the following Python 3 code
def hilbert_amplitude(ts):
    output = np.abs(signal.hilbert(signal.detrend(ts, axis=0), axis=0))
    return Timeseries(output, ts.tspan, labels=ts.labels)

Response: Amplitude of the analytic signal using the Hilbert transform


Instruction:
How would you explain what the following Python 3 function does
def hilbert_phase(ts):
    output = np.angle(signal.hilbert(signal.detrend(ts, axis=0), axis=0))
    return Timeseries(output, ts.tspan, labels=ts.labels)

Response: Phase of the analytic signal using the Hilbert transform


Instruction:
Explain what the following Python 3 code does
def cwt_distributed(ts, freqs=np.logspace(0, 2), wavelet=cwtmorlet, plot=True):
    if ts.ndim is 1 or ts.shape[1] is 1:
        return cwt(ts, freqs, wavelet, plot)
    import distob
    vcwt = distob.vectorize(cwt)
    coefs = vcwt(ts, freqs, wavelet, plot=False)
    if plot:
        _plot_cwt(ts, coefs, freqs)
    return coefs

Response: Continuous wavelet transform using distributed computation.


Instruction:
Can you write a function in Python 3 where it
plots time resolved power spectral density from cwt results.

Response:
def _plot_cwt(ts, coefs, freqs, tsize=1024, fsize=512):
    """Plot time resolved power spectral density from cwt results
    Args:
      ts: the original Timeseries
      coefs:  continuous wavelet transform coefficients as calculated by cwt()
      freqs: list of frequencies (in Hz) corresponding to coefs.
      tsize, fsize: size of the plot (time axis and frequency axis, in pixels)
    """
    import matplotlib.style
    import matplotlib as mpl
    mpl.style.use('classic')
    import matplotlib.pyplot as plt
    from scipy import interpolate
    channels = ts.shape[1]
    fig = plt.figure()
    for i in range(channels):
        rect = (0.1, 0.85*(channels - i - 1)/channels + 0.1,
                0.8, 0.85/channels)
        ax = fig.add_axes(rect)
        logpowers = np.log((coefs[:, :, i] * coefs[:, :, i].conj()).real)
        tmin, tmax = ts.tspan[0], ts.tspan[-1]
        fmin, fmax = freqs[0], freqs[-1]
        tgrid, fgrid = np.mgrid[tmin:tmax:tsize*1j, fmin:fmax:fsize*1j]
        gd = interpolate.interpn((ts.tspan, freqs), logpowers,
                                 (tgrid, fgrid)).T
        ax.imshow(gd, cmap='gnuplot2', aspect='auto', origin='lower',
                   extent=(tmin, tmax, fmin, fmax))
        ax.set_ylabel('freq (Hz)')
    fig.axes[0].set_title(u'log(power spectral density)')
    fig.axes[channels - 1].set_xlabel('time (s)')
    fig.show()


Instruction:
Can you generate the documentation for the following Python 3 function
def first_return_times(dts, c=None, d=0.0):
    if c is None:
        c = dts.mean()
    vmrt = distob.vectorize(analyses1.first_return_times)
    all_intervals = vmrt(dts, c, d)
    if hasattr(type(all_intervals), '__array_interface__'):
        return np.ravel(all_intervals)
    else:
        return np.hstack([distob.gather(ilist) for ilist in all_intervals])

Response: For an ensemble of time series return the set of all time intervals between successive returns to value c for all instances in the ensemble.


Instruction:
Make a summary of the following Python 3 code
def variability_fp(ts, freqs=None, ncycles=6, plot=True):
    if ts.ndim <= 2:
        return analyses1.variability_fp(ts, freqs, ncycles, plot)
    else:
        return distob.vectorize(analyses1.variability_fp)(
                ts, freqs, ncycles, plot)

Response:
Example variability function.
    Gives two continuous, time-resolved measures of the variability of a
    time series, ranging between -1 and 1.
    The two measures are based on variance of the centroid frequency and
    variance of the height of the spectral peak, respectively.
    (Centroid frequency meaning the power-weighted average frequency)
    These measures are calculated over sliding time windows of variable size.
    See also: Blenkinsop et al. (2012) The dynamic evolution of focal-onset
              epilepsies - combining theoretical and clinical observations
    Args:
      ts  Timeseries of m variables, shape (n, m). Assumed constant timestep.
      freqs   (optional) List of frequencies to examine. If None, defaults to
              50 frequency bands ranging 1Hz to 60Hz, logarithmically spaced.
      ncycles  Window size, in number of cycles of the centroid frequency.
      plot  bool  Whether to display the output

    Returns:
      variability   Timeseries of shape (n, m, 2)
                    variability[:, :, 0] gives a measure of variability
                    between -1 and 1 based on variance of centroid frequency.
                    variability[:, :, 1] gives a measure of variability
                    between -1 and 1 based on variance of maximum power.


Instruction:
Can you create a Python 3 function that
identifies stationary epochs within a time series.

Response:
def epochs(ts, variability=None, threshold=0.0, minlength=1.0, plot=True):
    """Identify "stationary" epochs within a time series, based on a
    continuous measure of variability.
    Epochs are defined to contain the points of minimal variability, and to
    extend as wide as possible with variability not exceeding the threshold.

    Args:
      ts  Timeseries of m variables, shape (n, m).
      variability  (optional) Timeseries of shape (n, m, q),  giving q scalar
                   measures of the variability of timeseries `ts` near each
                   point in time. (if None, we will use variability_fp())
                   Epochs require the mean of these to be below the threshold.
      threshold   The maximum variability permitted in stationary epochs.
      minlength   Shortest acceptable epoch length (in seconds)
      plot  bool  Whether to display the output

    Returns: (variability, allchannels_epochs)
      variability: as above
      allchannels_epochs: (list of) list of tuples
      For each variable, a list of tuples (start, end) that give the
      starting and ending indices of stationary epochs.
      (epochs are inclusive of start point but not the end point)
    """
    if ts.ndim <= 2:
        return analyses1.epochs_distributed(
                ts, variability, threshold, minlength, plot)
    else:
        return distob.vectorize(analyses1.epochs)(
                ts, variability, threshold, minlength, plot)


Instruction:
Create a Python 3 function to
identify epochs within a multivariate time series where at least a certain proportion of channels are stationary.

Response:
def epochs_joint(ts, variability=None, threshold=0.0, minlength=1.0,
                 proportion=0.75, plot=True):
    """Identify epochs within a multivariate time series where at least a
    certain proportion of channels are "stationary", based on a previously
    computed variability measure.

    (Note: This requires an IPython cluster to be started first,
     e.g. on a workstation type 'ipcluster start')

    Args:
      ts  Timeseries of m variables, shape (n, m).
      variability  (optional) Timeseries of shape (n, m),  giving a scalar
                   measure of the variability of timeseries `ts` near each
                   point in time. (if None, we will use variability_fp())
      threshold   The maximum variability permitted in stationary epochs.
      minlength   Shortest acceptable epoch length (in seconds)
      proportion  Require at least this fraction of channels to be "stationary"
      plot  bool  Whether to display the output

    Returns: (variability, joint_epochs)
      joint_epochs: list of tuples
      A list of tuples (start, end) that give the starting and ending indices
      of time epochs that are stationary for at least `proportion` of channels.
      (epochs are inclusive of start point but not the end point)
    """
    if ts.ndim <= 2:
        return analyses1.epochs_joint(
                ts, variability, threshold, minlength, plot)
    else:
        return distob.vectorize(analyses1.epochs_joint)(
                ts, variability, threshold, minlength, plot)


Instruction:
Explain what the following Python 3 code does
def order_param(dts, axis=2):
    return np.abs(np.exp(1.0j * dts).mean(axis=axis))

Response: Order parameter of phase synchronization


Instruction:
Can you generate the documentation for the following Python 3 function
def G(self, v, t):
        ret = np.zeros((8, 1))
        ret[4,0] = self.ke1 * self.He1 * self.u_sdev
        ret[5,0] = self.ke2 * self.He2 * self.p_sdev
        return ret

Response:
Aburn2012 equations right hand side noise term
 ArcGIS


Instruction:
Can you create a Python 3 function that
computes the Hurst exponent of X.

Response:
def hurst(X):
    """ Compute the Hurst exponent of X. If the output H=0.5,the behavior
    of the time-series is similar to random walk. If H<0.5, the time-series
    cover less "distance" than a random walk, vice verse.

    Parameters
    ----------

    X

        list

        a time series

    Returns
    -------
    H

        float

        Hurst exponent

    Notes
    --------
    Author of this function is Xin Liu

    Examples
    --------

    >>> import pyeeg
    >>> from numpy.random import randn
    >>> a = randn(4096)
    >>> pyeeg.hurst(a)
    0.5057444

    """
    X = numpy.array(X)
    N = X.size
    T = numpy.arange(1, N + 1)
    Y = numpy.cumsum(X)
    Ave_T = Y / T

    S_T = numpy.zeros(N)
    R_T = numpy.zeros(N)

    for i in range(N):
        S_T[i] = numpy.std(X[:i + 1])
        X_T = Y - T * Ave_T[i]
        R_T[i] = numpy.ptp(X_T[:i + 1])

    R_S = R_T / S_T
    R_S = numpy.log(R_S)[1:]
    n = numpy.log(T)[1:]
    A = numpy.column_stack((n, numpy.ones(n.size)))
    [m, c] = numpy.linalg.lstsq(A, R_S)[0]
    H = m
    return H


Instruction:
Explain what the following Python 3 code does
def embed_seq(X, Tau, D):
    shape = (X.size - Tau * (D - 1), D)
    strides = (X.itemsize, Tau * X.itemsize)
    return numpy.lib.stride_tricks.as_strided(X, shape=shape, strides=strides)

Response:
Build a set of embedding sequences from given time series X with lag Tau
    and embedding dimension D.


Instruction:
Implement a function in Python 3 to
compute the power of each frequency bin specified by Band from FFT result of X.

Response:
def bin_power(X, Band, Fs):
    """Compute power in each frequency bin specified by Band from FFT result of
    X. By default, X is a real signal.

    Note
    -----
    A real signal can be synthesized, thus not real.

    Parameters
    -----------

    Band
        list

        boundary frequencies (in Hz) of bins. They can be unequal bins, e.g.
        [0.5,4,7,12,30] which are delta, theta, alpha and beta respectively.
        You can also use range() function of Python to generate equal bins and
        pass the generated list to this function.

        Each element of Band is a physical frequency and shall not exceed the
        Nyquist frequency, i.e., half of sampling frequency.

     X
        list

        a 1-D real time series.

    Fs
        integer

        the sampling rate in physical frequency

    Returns
    -------

    Power
        list

        spectral power in each frequency bin.

    Power_ratio
        list

        spectral power in each frequency bin normalized by total power in ALL
        frequency bins.

    """

    C = numpy.fft.fft(X)
    C = abs(C)
    Power = numpy.zeros(len(Band) - 1)
    for Freq_Index in range(0, len(Band) - 1):
        Freq = float(Band[Freq_Index])
        Next_Freq = float(Band[Freq_Index + 1])
        Power[Freq_Index] = sum(
            C[numpy.floor(
                Freq / Fs * len(X)
            ): numpy.floor(Next_Freq / Fs * len(X))]
        )
    Power_Ratio = Power / sum(Power)
    return Power, Power_Ratio