Instruction:
Explain what the following Python 3 code does
def _findMessageBytes ( self, data ):

        # Sanity check. See the docstring for the method to see what it
        # does an why we need it.
        self.syncBuffer()

        # If the string '\n\n' does not exist, we don't even have the complete
        # header yet and we MUST exit.
        try:
            i = data.index ( '\n\n' )
        except ValueError:
            return ( 0, 0 )
        # If the string '\n\n' exists, then we have the entire header and can
        # check for the content-length header. If it exists, we can check
        # the length of the buffer for the number of bytes, else we check for
        # the existence of a null byte.

        # Pull out the header before we perform the regexp search. This
        # prevents us from matching (possibly malicious) strings in the
        # body.
        _hdr = self.buffer[:i]
        match = content_length_re.search ( _hdr )
        if match:
            # There was a content-length header, so read out the value.
            content_length = int ( match.groups()[0] )

            # THIS IS NO LONGER THE CASE IF WE REMOVE THE '\n\n' in
            # Frame.pack()

            # This is the content length of the body up until the null
            # byte, not the entire message. Note that this INCLUDES the 2
            # '\n\n' bytes inserted by the STOMP encoder after the body
            # (see the calculation of content_length in
            # StompEngine.callRemote()), so we only need to add 2 final bytes
            # for the footer.
            #
            #The message looks like:
            #
            #   <header>\n\n<body>\n\n\x00\n
            #           ^         ^^^^
            #          (i)         included in content_length!
            #
            # We have the location of the end of the header (i), so we
            # need to ensure that the message contains at least:
            #
            #     i + len ( '\n\n' ) + content_length + len ( '\x00\n' )
            #
            # Note that i is also the count of bytes in the header, because
            # of the fact that str.index() returns a 0-indexed value.
            req_len = i + len_sep + content_length + len_footer
            # log.msg ( "We have [%s] bytes and need [%s] bytes" %
            #           ( len ( data ), req_len, ) )
            if len ( data ) < req_len:
                # We don't have enough bytes in the buffer.
                return ( 0, 0 )
            else:
                # We have enough bytes in the buffer
                return ( req_len, i )
        else:
            # There was no content-length header, so just look for the
            # message terminator ('\x00\n' ).
            try:
                j = data.index ( '\x00\n' )
            except ValueError:
                return ( 0, 0 )
            # j points to the 0-indexed location of the null byte. However,
            # we need to add 1 (to turn it into a byte count) and 1 to take
            # account of the final '\n' character after the null byte.
            return ( j + 2, i )

Response: Find the bytes in the buffer that are in the message and return them.


Instruction:
How would you code a function in Python 3 to
synchronize the buffer with the contents of the STOMP command.

Response:
def syncBuffer( self ):
        """
        I detect and correct corruption in the buffer.

        Corruption in the buffer is defined as the following conditions
        both being true:

            1. The buffer contains at least one newline;
            2. The text until the first newline is not a STOMP command.

        In this case, we heuristically try to flush bits of the buffer until
        one of the following conditions becomes true:

            1. the buffer starts with a STOMP command;
            2. the buffer does not contain a newline.
            3. the buffer is empty;

        If the buffer is deemed corrupt, the first step is to flush the buffer
        up to and including the first occurrence of the string '\x00\n', which
        is likely to be a frame boundary.

        Note that this is not guaranteed to be a frame boundary, as a binary
        payload could contain the string '\x00\n'. That condition would get
        handled on the next loop iteration.

        If the string '\x00\n' does not occur, the entire buffer is cleared.
        An earlier version progressively removed strings until the next newline,
        but this gets complicated because the body could contain strings that
        look like STOMP commands.

        Note that we do not check "partial" strings to see if they *could*
        match a command; that would be too resource-intensive. In other words,
        a buffer containing the string 'BUNK' with no newline is clearly
        corrupt, but we sit and wait until the buffer contains a newline before
        attempting to see if it's a STOMP command.
        """
        while True:
            if not self.buffer:
                # Buffer is empty; no need to do anything.
                break
            m = command_re.match ( self.buffer )
            if m is None:
                # Buffer doesn't even contain a single newline, so we can't
                # determine whether it's corrupt or not. Assume it's OK.
                break
            cmd = m.groups()[0]
            if cmd in stomper.VALID_COMMANDS:
                # Good: the buffer starts with a command.
                break
            else:
                # Bad: the buffer starts with bunk, so strip it out. We first
                # try to strip to the first occurrence of '\x00\n', which
                # is likely to be a frame boundary, but if this fails, we
                # strip until the first newline.
                ( self.buffer, nsubs ) = sync_re.subn ( '', self.buffer )

                if nsubs:
                    # Good: we managed to strip something out, so restart the
                    # loop to see if things look better.
                    continue
                else:
                    # Bad: we failed to strip anything out, so kill the
                    # entire buffer. Since this resets the buffer to a
                    # known good state, we can break out of the loop.
                    self.buffer = ''
                    break


Instruction:
Can you generate a brief explanation for the following Python 3 code
def connected(self, msg):
        super(MyStomp, self).connected(msg)

        self.log.info("connected: session %s" % msg['headers']['session'])
        f = stomper.Frame()
        f.unpack(stomper.subscribe(DESTINATION))
        return f.pack()

Response: Called when a new session is established.


Instruction:
Can you write a function in Python 3 where it
calls when an entity is deleted.

Response:
def delete_entity_signal_handler(sender, instance, **kwargs):
    """
    Defines a signal handler for syncing an individual entity. Called when
    an entity is saved or deleted.
    """
    if instance.__class__ in entity_registry.entity_registry:
        Entity.all_objects.delete_for_obj(instance)


Instruction:
Write a Python 3 function for
defining a signal handler for saving an entity. Syncs the entity to the entity mirror table.

Response:
def save_entity_signal_handler(sender, instance, **kwargs):
    """
    Defines a signal handler for saving an entity. Syncs the entity to
    the entity mirror table.
    """
    if instance.__class__ in entity_registry.entity_registry:
        sync_entities(instance)

    if instance.__class__ in entity_registry.entity_watching:
        sync_entities_watching(instance)


Instruction:
Create a Python 3 function for
signaling handler for manytomany changed entity.

Response:
def m2m_changed_entity_signal_handler(sender, instance, action, **kwargs):
    """
    Defines a signal handler for a manytomany changed signal. Only listens for the
    post actions so that entities are synced once (rather than twice for a pre and post action).
    """
    if action == 'post_add' or action == 'post_remove' or action == 'post_clear':
        save_entity_signal_handler(sender, instance, **kwargs)


Instruction:
Given the following Python 3 function, write the documentation
def turn_off_syncing(for_post_save=True, for_post_delete=True, for_m2m_changed=True, for_post_bulk_operation=True):
    if for_post_save:
        post_save.disconnect(save_entity_signal_handler, dispatch_uid='save_entity_signal_handler')
    if for_post_delete:
        post_delete.disconnect(delete_entity_signal_handler, dispatch_uid='delete_entity_signal_handler')
    if for_m2m_changed:
        m2m_changed.disconnect(m2m_changed_entity_signal_handler, dispatch_uid='m2m_changed_entity_signal_handler')
    if for_post_bulk_operation:
        post_bulk_operation.disconnect(bulk_operation_signal_handler, dispatch_uid='bulk_operation_signal_handler')

Response: Turn off syncing entities.


Instruction:
Write a Python 3 script to
enable all of the signals for syncing entities.

Response:
def turn_on_syncing(for_post_save=True, for_post_delete=True, for_m2m_changed=True, for_post_bulk_operation=False):
    """
    Enables all of the signals for syncing entities. Everything is True by default, except for the post_bulk_operation
    signal. The reason for this is because when any bulk operation occurs on any mirrored entity model, it will
    result in every single entity being synced again. This is not a desired behavior by the majority of users, and
    should only be turned on explicitly.
    """
    if for_post_save:
        post_save.connect(save_entity_signal_handler, dispatch_uid='save_entity_signal_handler')
    if for_post_delete:
        post_delete.connect(delete_entity_signal_handler, dispatch_uid='delete_entity_signal_handler')
    if for_m2m_changed:
        m2m_changed.connect(m2m_changed_entity_signal_handler, dispatch_uid='m2m_changed_entity_signal_handler')
    if for_post_bulk_operation:
        post_bulk_operation.connect(bulk_operation_signal_handler, dispatch_uid='bulk_operation_signal_handler')


Instruction:
How would you explain what the following Python 3 function does
def add(self, value):
        # Raise TypeError if value is not hashable
        hash(value)

        self.redis.sadd(self.key, self._pickle(value))

Response: Add element value to the set.


Instruction:
Can you implement a function in Python 3 that
removes the element value from the set if it is present.

Response:
def discard(self, value):
        """Remove element *value* from the set if it is present."""
        # Raise TypeError if value is not hashable
        hash(value)

        self.redis.srem(self.key, self._pickle(value))


Instruction:
Create a Python 3 function to
return True if the set has no elements in common with other.

Response:
def isdisjoint(self, other):
        """
        Return ``True`` if the set has no elements in common with *other*.
        Sets are disjoint if and only if their intersection is the empty set.

        :param other: Any kind of iterable.
        :rtype: boolean
        """
        def isdisjoint_trans_pure(pipe):
            return not pipe.sinter(self.key, other.key)

        def isdisjoint_trans_mixed(pipe):
            self_values = set(self.__iter__(pipe))
            if use_redis:
                other_values = set(other.__iter__(pipe))
            else:
                other_values = set(other)

            return self_values.isdisjoint(other_values)

        if self._same_redis(other):
            return self._transaction(isdisjoint_trans_pure, other.key)
        if self._same_redis(other, RedisCollection):
            use_redis = True
            return self._transaction(isdisjoint_trans_mixed, other.key)

        use_redis = False
        return self._transaction(isdisjoint_trans_mixed)


Instruction:
How would you explain what the following Python 3 function does
def pop(self):
        result = self.redis.spop(self.key)
        if result is None:
            raise KeyError

        return self._unpickle(result)

Response: Removes and returns an arbitrary element from the set. Raises KeyError if the set is empty.


Instruction:
Can you create a Python 3 function that
returns a random k elements from the set.

Response:
def random_sample(self, k=1):
        """
        Return a *k* length list of unique elements chosen from the Set.
        Elements are not removed. Similar to :func:`random.sample` function
        from standard library.

        :param k: Size of the sample, defaults to 1.
        :rtype: :class:`list`

        """
        # k == 0: no work to do
        if k == 0:
            results = []
        # k == 1: same behavior on all versions of Redis
        elif k == 1:
            results = [self.redis.srandmember(self.key)]
        # k != 1, Redis version >= 2.6: compute in Redis
        else:
            results = self.redis.srandmember(self.key, k)

        return [self._unpickle(x) for x in results]


Instruction:
Write a Python 3 function for
removing the element value from the set. Raises KeyError if the key is not contained in the set.

Response:
def remove(self, value):
        """
        Remove element *value* from the set. Raises :exc:`KeyError` if it
        is not contained in the set.
        """
        # Raise TypeError if value is not hashable
        hash(value)

        result = self.redis.srem(self.key, self._pickle(value))
        if not result:
            raise KeyError(value)


Instruction:
Can you generate a brief explanation for the following Python 3 code
def scan_elements(self):
        for x in self.redis.sscan_iter(self.key):
            yield self._unpickle(x)

Response: Yields each of the elements from the collection without pulling them into memory.


Instruction:
How would you implement a function in Python 3 that
updates the set keeping only elements found in it and all others.

Response:
def intersection_update(self, *others):
        """
        Update the set, keeping only elements found in it and all *others*.

        :param others: Iterables, each one as a single positional argument.
        :rtype: None

        .. note::
            The same behavior as at :func:`difference_update` applies.
        """
        return self._op_update_helper(
            tuple(others), operator.and_, 'sinterstore', update=True
        )


Instruction:
Create a Python 3 function for
updating the set with the elements from all others.

Response:
def update(self, *others):
        """
        Update the set, adding elements from all *others*.

        :param others: Iterables, each one as a single positional argument.
        :rtype: None

        .. note::
            If all *others* are :class:`Set` instances, the operation
            is performed completely in Redis. Otherwise, values are retrieved
            from Redis and the operation is performed in Python.
        """
        return self._op_update_helper(
            tuple(others), operator.or_, 'sunionstore', update=True
        )


Instruction:
Can you generate the documentation for the following Python 3 function
def difference_update(self, *others):
        return self._op_update_helper(
            tuple(others), operator.sub, 'sdiffstore', update=True
        )

Response: Update the set removing elements found in others.


Instruction:
Write a Python 3 function for
discarding a key from the collection.

Response:
def discard_member(self, member, pipe=None):
        """
        Remove *member* from the collection, unconditionally.
        """
        pipe = self.redis if pipe is None else pipe
        pipe.zrem(self.key, self._pickle(member))


Instruction:
Write a Python 3 function for
yielding each member of the set in the collection without pulling them all into memory.

Response:
def scan_items(self):
        """
        Yield each of the ``(member, score)`` tuples from the collection,
        without pulling them all into memory.

        .. warning::
            This method may return the same (member, score) tuple multiple
            times.
            See the `Redis SCAN documentation
            <http://redis.io/commands/scan#scan-guarantees>`_ for details.
        """
        for m, s in self.redis.zscan_iter(self.key):
            yield self._unpickle(m), s


Instruction:
Can you generate a brief explanation for the following Python 3 code
def update(self, other):
        def update_trans(pipe):
            other_items = method(pipe=pipe) if use_redis else method()

            pipe.multi()
            for member, score in other_items:
                pipe.zadd(self.key, {self._pickle(member): float(score)})

        watches = []
        if self._same_redis(other, RedisCollection):
            use_redis = True
            watches.append(other.key)
        else:
            use_redis = False

        if hasattr(other, 'items'):
            method = other.items
        elif hasattr(other, '__iter__'):
            method = other.__iter__

        self._transaction(update_trans, *watches)

Response:
Update the collection with items from other. Accepts other
        instance dictionaries mapping members to
            numeric scores or sequences of tuples of member score.


Instruction:
Can you tell what is the following Python 3 function doing
def count_between(self, min_score=None, max_score=None):
        min_score = float('-inf') if min_score is None else float(min_score)
        max_score = float('inf') if max_score is None else float(max_score)

        return self.redis.zcount(self.key, min_score, max_score)

Response: Returns the number of members whose score is between min_score and max_score ( inclusive.


Instruction:
Can you implement a function in Python 3 that
removes members from the cache that are in the given range between the given scores and the given min and max scores.

Response:
def discard_between(
        self,
        min_rank=None,
        max_rank=None,
        min_score=None,
        max_score=None,
    ):
        """
        Remove members whose ranking is between *min_rank* and *max_rank*
        OR whose score is between *min_score* and *max_score* (both ranges
        inclusive). If no bounds are specified, no members will be removed.
        """
        no_ranks = (min_rank is None) and (max_rank is None)
        no_scores = (min_score is None) and (max_score is None)

        # Default scope: nothing
        if no_ranks and no_scores:
            return

        # Scope widens to given score range
        if no_ranks and (not no_scores):
            return self.discard_by_score(min_score, max_score)

        # Scope widens to given rank range
        if (not no_ranks) and no_scores:
            return self.discard_by_rank(min_rank, max_rank)

        # Scope widens to score range and then rank range
        with self.redis.pipeline() as pipe:
            self.discard_by_score(min_score, max_score, pipe)
            self.discard_by_rank(min_rank, max_rank, pipe)
            pipe.execute()


Instruction:
Given the following Python 3 function, write the documentation
def get_score(self, member, default=None, pipe=None):
        pipe = self.redis if pipe is None else pipe
        score = pipe.zscore(self.key, self._pickle(member))

        if (score is None) and (default is not None):
            score = float(default)

        return score

Response: Get the score of a member in the available set.


Instruction:
Create a Python 3 function for
getting or set the score of a member in the collection.

Response:
def get_or_set_score(self, member, default=0):
        """
        If *member* is in the collection, return its value. If not, store it
        with a score of *default* and return *default*. *default* defaults to
        0.
        """
        default = float(default)

        def get_or_set_score_trans(pipe):
            pickled_member = self._pickle(member)
            score = pipe.zscore(self.key, pickled_member)

            if score is None:
                pipe.zadd(self.key, {self._pickle(member): default})
                return default

            return score

        return self._transaction(get_or_set_score_trans)


Instruction:
Write a Python 3 function that can
get the rank of a member in the collection.

Response:
def get_rank(self, member, reverse=False, pipe=None):
        """
        Return the rank of *member* in the collection.
        By default, the member with the lowest score has rank 0.
        If *reverse* is ``True``, the member with the highest score has rank 0.
        """
        pipe = self.redis if pipe is None else pipe
        method = getattr(pipe, 'zrevrank' if reverse else 'zrank')
        rank = method(self.key, self._pickle(member))

        return rank


Instruction:
Can you create a Python 3 function that
increments the score of a member in the record store by amount.

Response:
def increment_score(self, member, amount=1):
        """
        Adjust the score of *member* by *amount*. If *member* is not in the
        collection it will be stored with a score of *amount*.
        """
        return self.redis.zincrby(
            self.key, float(amount), self._pickle(member)
        )


Instruction:
Create a Python 3 function for
returning a list of items in the cache.

Response:
def items(
        self,
        min_rank=None,
        max_rank=None,
        min_score=None,
        max_score=None,
        reverse=False,
        pipe=None,
    ):
        """
        Return a list of ``(member, score)`` tuples whose ranking is between
        *min_rank* and *max_rank* AND whose score is between *min_score* and
        *max_score* (both ranges inclusive). If no bounds are specified, all
        items will be returned.
        """
        pipe = self.redis if pipe is None else pipe

        no_ranks = (min_rank is None) and (max_rank is None)
        no_scores = (min_score is None) and (max_score is None)

        # Default scope: everything
        if no_ranks and no_scores:
            ret = self.items_by_score(min_score, max_score, reverse, pipe)
        # Scope narrows to given score range
        elif no_ranks and (not no_scores):
            ret = self.items_by_score(min_score, max_score, reverse, pipe)
        # Scope narrows to given rank range
        elif (not no_ranks) and no_scores:
            ret = self.items_by_rank(min_rank, max_rank, reverse, pipe)
        # Scope narrows twice - once by rank and once by score
        else:
            results = self.items_by_rank(min_rank, max_rank, reverse, pipe)
            ret = []
            for member, score in results:
                if (min_score is not None) and (score < min_score):
                    continue
                if (max_score is not None) and (score > max_score):
                    continue
                ret.append((member, score))

        return ret


Instruction:
How would you code a function in Python 3 to
set the score of member to score.

Response:
def set_score(self, member, score, pipe=None):
        """
        Set the score of *member* to *score*.
        """
        pipe = self.redis if pipe is None else pipe
        pipe.zadd(self.key, {self._pickle(member): float(score)})


Instruction:
Write a Python 3 function for
returning the great circle distance between two sets of locations.

Response:
def distance_between(self, place_1, place_2, unit='km'):
        """
        Return the great-circle distance between *place_1* and *place_2*,
        in the *unit* specified.

        The default unit is ``'km'``, but ``'m'``, ``'mi'``, and ``'ft'`` can
        also be specified.
        """
        pickled_place_1 = self._pickle(place_1)
        pickled_place_2 = self._pickle(place_2)
        try:
            return self.redis.geodist(
                self.key, pickled_place_1, pickled_place_2, unit=unit
            )
        except TypeError:
            return None


Instruction:
Write a Python 3 function for
getting the Geohash of place.

Response:
def get_hash(self, place):
        """
        Return the Geohash of *place*.
        If it's not present in the collection, ``None`` will be returned
        instead.
        """
        pickled_place = self._pickle(place)
        try:
            return self.redis.geohash(self.key, pickled_place)[0]
        except (AttributeError, TypeError):
            return None


Instruction:
Can you tell what is the following Python 3 function doing
def get_location(self, place):
        pickled_place = self._pickle(place)
        try:
            longitude, latitude = self.redis.geopos(self.key, pickled_place)[0]
        except (AttributeError, TypeError):
            return None

        return {'latitude': latitude, 'longitude': longitude}

Response:
Return a dict with the coordinates *place*. The keys are
        latitude and longitude.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def places_within_radius(
        self, place=None, latitude=None, longitude=None, radius=0, **kwargs
    ):
        """
        Return descriptions of the places stored in the collection that are
        within the circle specified by the given location and radius.
        A list of dicts will be returned.

        The center of the circle can be specified by the identifier of another
        place in the collection with the *place* keyword argument.
        Or, it can be specified by using both the *latitude* and *longitude*
        keyword arguments.

        By default the *radius* is given in kilometers, but you may also set
        the *unit* keyword argument to ``'m'``, ``'mi'``, or ``'ft'``.

        Limit the number of results returned with the *count* keyword argument.

        Change the sorted order by setting the *sort* keyword argument to
        ``b'DESC'``.
        """
        kwargs['withdist'] = True
        kwargs['withcoord'] = True
        kwargs['withhash'] = False
        kwargs.setdefault('sort', 'ASC')
        unit = kwargs.setdefault('unit', 'km')

        # Make the query
        if place is not None:
            response = self.redis.georadiusbymember(
                self.key, self._pickle(place), radius, **kwargs
            )
        elif (latitude is not None) and (longitude is not None):
            response = self.redis.georadius(
                self.key, longitude, latitude, radius, **kwargs
            )
        else:
            raise ValueError(
                'Must specify place, or both latitude and longitude'
            )

        # Assemble the result
        ret = []
        for item in response:
            ret.append(
                {
                    'place': self._unpickle(item[0]),
                    'distance': item[1],
                    'unit': unit,
                    'latitude': item[2][1],
                    'longitude': item[2][0],
                }
            )

        return ret

Response: Returns a list of dictionaries describing the places stored in the collection that are within the given radius.


Instruction:
Make a summary of the following Python 3 code
def set_location(self, place, latitude, longitude, pipe=None):
        pipe = self.redis if pipe is None else pipe
        pipe.geoadd(self.key, longitude, latitude, self._pickle(place))

Response: Set the location of the entry in the cache.


Instruction:
Can you tell what is the following Python 3 function doing
def update(self, other):
        # other is another Sorted Set
        def update_sortedset_trans(pipe):
            items = other._data(pipe=pipe) if use_redis else other._data()

            pipe.multi()
            for member, score in items:
                pipe.zadd(self.key, {self._pickle(member): float(score)})

        # other is dict-like
        def update_mapping_trans(pipe):
            items = other.items(pipe=pipe) if use_redis else other.items()

            pipe.multi()
            for place, value in items:
                self.set_location(
                    place, value['latitude'], value['longitude'], pipe=pipe
                )

        # other is a list of tuples
        def update_tuples_trans(pipe):
            items = (
                other.__iter__(pipe=pipe) if use_redis else other.__iter__()
            )

            pipe.multi()
            for place, latitude, longitude in items:
                self.set_location(place, latitude, longitude, pipe=pipe)

        watches = []
        if self._same_redis(other, RedisCollection):
            use_redis = True
            watches.append(other.key)
        else:
            use_redis = False

        if isinstance(other, SortedSetBase):
            func = update_sortedset_trans
        elif hasattr(other, 'items'):
            func = update_mapping_trans
        elif hasattr(other, '__iter__'):
            func = update_tuples_trans

        self._transaction(func, *watches)

Response:
Update the collection with items from other. Accepts other : class : GeoDB instance or list of dictionaries mapping places to
           .


Instruction:
How would you code a function in Python 3 to
create a new collection with the same items and maxsize with the given key.

Response:
def copy(self, key=None):
        """
        Creates another collection with the same items and maxsize with
        the given *key*.
        """
        other = self.__class__(
            maxsize=self.maxsize, redis=self.persistence.redis, key=key
        )
        other.update(self)

        return other


Instruction:
Can you implement a function in Python 3 that
creates a new collection with keys from seq and values set to value.

Response:
def fromkeys(cls, seq, value=None, **kwargs):
        """
        Create a new collection with keys from *seq* and values set to
        *value*. The keyword arguments are passed to the persistent ``Dict``.
        """
        other = cls(**kwargs)
        other.update(((key, value) for key in seq))

        return other


Instruction:
Write a Python 3 function for
synchronizing the items from the local cache to the persistent Dict.

Response:
def sync(self, clear_cache=False):
        """
        Copy items from the local cache to the persistent Dict.
        If *clear_cache* is ``True``, clear out the local cache after
        pushing its items to Redis.
        """
        self.persistence.update(self)

        if clear_cache:
            self.cache.clear()


Instruction:
Given the following Python 3 function, write the documentation
def _data(self, pipe=None):
        pipe = self.redis if pipe is None else pipe
        return [self._unpickle(v) for v in pipe.lrange(self.key, 0, -1)]

Response: Return a list of all values from Redis


Instruction:
Make a summary of the following Python 3 code
def append(self, value):
        len_self = self.redis.rpush(self.key, self._pickle(value))

        if self.writeback:
            self.cache[len_self - 1] = value

Response: Insert value at the end of this collection.


Instruction:
Make a summary of the following Python 3 code
def copy(self, key=None):
        other = self.__class__(
            redis=self.redis, key=key, writeback=self.writeback
        )
        other.extend(self)

        return other

Response: Return a new collection with the same items as this one.


Instruction:
Explain what the following Python 3 code does
def extend(self, other):
        def extend_trans(pipe):
            values = list(other.__iter__(pipe)) if use_redis else other
            len_self = pipe.rpush(self.key, *(self._pickle(v) for v in values))
            if self.writeback:
                for i, v in enumerate(values, len_self - len(values)):
                    self.cache[i] = v

        if self._same_redis(other, RedisCollection):
            use_redis = True
            self._transaction(extend_trans, other.key)
        else:
            use_redis = False
            self._transaction(extend_trans)

Response: Adds the values from the iterable other to the end of this collection.


Instruction:
Write a Python 3 script for
returning the index of the first occurence of value.

Response:
def index(self, value, start=None, stop=None):
        """
        Return the index of the first occurence of *value*.
        If *start* or *stop* are provided, return the smallest
        index such that ``s[index] == value`` and ``start <= index < stop``.
        """
        def index_trans(pipe):
            len_self, normal_start = self._normalize_index(start or 0, pipe)
            __, normal_stop = self._normalize_index(stop or len_self, pipe)
            for i, v in enumerate(self.__iter__(pipe=pipe)):
                if v == value:
                    if i < normal_start:
                        continue
                    if i >= normal_stop:
                        break
                    return i
            raise ValueError

        return self._transaction(index_trans)


Instruction:
Write a Python 3 script for
inserting a new entry into the collection at the specified index.

Response:
def insert(self, index, value):
        """
        Insert *value* into the collection at *index*.
        """
        if index == 0:
            return self._insert_left(value)

        def insert_middle_trans(pipe):
            self._insert_middle(index, value, pipe=pipe)

        return self._transaction(insert_middle_trans)


Instruction:
Can you tell what is the following Python 3 function doing
def pop(self, index=-1):
        if index == 0:
            return self._pop_left()
        elif index == -1:
            return self._pop_right()
        else:
            return self._pop_middle(index)

Response: Remove the value at index from the collection and return it.


Instruction:
Implement a function in Python 3 to
remove the first occurence of value.

Response:
def remove(self, value):
        """Remove the first occurence of *value*."""
        def remove_trans(pipe):
            # If we're caching, we'll need to synchronize before removing.
            if self.writeback:
                self._sync_helper(pipe)

            delete_count = pipe.lrem(self.key, 1, self._pickle(value))
            if delete_count == 0:
                raise ValueError

        self._transaction(remove_trans)


Instruction:
Create a Python 3 function for
reversing the items of this collection in place.

Response:
def reverse(self):
        """
        Reverses the items of this collection "in place" (only two values are
        retrieved from Redis at a time).
        """
        def reverse_trans(pipe):
            if self.writeback:
                self._sync_helper(pipe)

            n = self.__len__(pipe)
            for i in range(n // 2):
                left = pipe.lindex(self.key, i)
                right = pipe.lindex(self.key, n - i - 1)
                pipe.lset(self.key, i, right)
                pipe.lset(self.key, n - i - 1, left)

        self._transaction(reverse_trans)


Instruction:
Given the following Python 3 function, write the documentation
def sort(self, key=None, reverse=False):
        def sort_trans(pipe):
            values = list(self.__iter__(pipe))
            values.sort(key=key, reverse=reverse)

            pipe.multi()
            pipe.delete(self.key)
            pipe.rpush(self.key, *(self._pickle(v) for v in values))

            if self.writeback:
                self.cache = {}

        return self._transaction(sort_trans)

Response:
Sort the items of this collection according to the optional callable
            key.


Instruction:
Can you create a Python 3 function that
adds value to the right side of the collection.

Response:
def append(self, value):
        """Add *value* to the right side of the collection."""
        def append_trans(pipe):
            self._append_helper(value, pipe)

        self._transaction(append_trans)


Instruction:
Create a Python 3 function for
adding value to the left side of the collection.

Response:
def appendleft(self, value):
        """Add *value* to the left side of the collection."""
        def appendleft_trans(pipe):
            self._appendleft_helper(value, pipe)

        self._transaction(appendleft_trans)


Instruction:
Can you generate a brief explanation for the following Python 3 code
def copy(self, key=None):
        other = self.__class__(
            self.__iter__(),
            self.maxlen,
            redis=self.redis,
            key=key,
            writeback=self.writeback,
        )

        return other

Response: Return a new collection with the same items as this one.


Instruction:
Write a Python 3 function for
extending the right side of the collection by appending values from the iterable other.

Response:
def extend(self, other):
        """
        Extend the right side of the the collection by appending values from
        the iterable *other*.
        """
        def extend_trans(pipe):
            values = list(other.__iter__(pipe)) if use_redis else other
            for v in values:
                self._append_helper(v, pipe)

        if self._same_redis(other, RedisCollection):
            use_redis = True
            self._transaction(extend_trans, other.key)
        else:
            use_redis = False
            self._transaction(extend_trans)


Instruction:
How would you code a function in Python 3 to
extend the left side of the collection by appending values from the iterable other.

Response:
def extendleft(self, other):
        """
        Extend the left side of the the collection by appending values from
        the iterable *other*. Note that the appends will reverse the order
        of the given values.
        """
        def extendleft_trans(pipe):
            values = list(other.__iter__(pipe)) if use_redis else other
            for v in values:
                self._appendleft_helper(v, pipe)

        if self._same_redis(other, RedisCollection):
            use_redis = True
            self._transaction(extendleft_trans, other.key)
        else:
            use_redis = False
            self._transaction(extendleft_trans)


Instruction:
Can you tell what is the following Python 3 function doing
def insert(self, index, value):
        def insert_trans(pipe):
            len_self = self.__len__(pipe)
            if (self.maxlen is not None) and (len_self >= self.maxlen):
                raise IndexError

            if index == 0:
                self._insert_left(value, pipe)
            else:
                self._insert_middle(index, value, pipe=pipe)

        self._transaction(insert_trans)

Response: Insert value into the collection at index.


Instruction:
Write a Python 3 script for
rotating the deque n steps to the right.

Response:
def rotate(self, n=1):
        """
        Rotate the deque n steps to the right.
        If n is negative, rotate to the left.
        """
        # No work to do for a 0-step rotate
        if n == 0:
            return

        def rotate_trans(pipe):
            # Synchronize the cache before rotating
            if self.writeback:
                self._sync_helper(pipe)

            # Rotating len(self) times has no effect.
            len_self = self.__len__(pipe)
            steps = abs_n % len_self

            # When n is positive we can use the built-in Redis command
            if forward:
                pipe.multi()
                for __ in range(steps):
                    pipe.rpoplpush(self.key, self.key)
            # When n is negative we must use Python
            else:
                for __ in range(steps):
                    pickled_value = pipe.lpop(self.key)
                    pipe.rpush(self.key, pickled_value)

        forward = n >= 0
        abs_n = abs(n)
        self._transaction(rotate_trans)


Instruction:
Here you have a function in Python 3, explain what it does
def get_entities_by_kind(membership_cache=None, is_active=True):
    # Accept an existing cache or build a new one
    if membership_cache is None:
        membership_cache = EntityGroup.objects.get_membership_cache(is_active=is_active)

    entities_by_kind = {}
    kinds_with_all = set()
    kinds_with_supers = set()
    super_ids = set()

    # Loop over each group
    for group_id, memberships in membership_cache.items():

        # Look at each membership
        for entity_id, entity_kind_id in memberships:

            # Only care about memberships with entity kind
            if entity_kind_id:

                # Make sure a dict exists for this kind
                entities_by_kind.setdefault(entity_kind_id, {})

                # Check if this is all entities of a kind under a specific entity
                if entity_id:
                    entities_by_kind[entity_kind_id][entity_id] = []
                    kinds_with_supers.add(entity_kind_id)
                    super_ids.add(entity_id)
                else:
                    # This is all entities of this kind
                    entities_by_kind[entity_kind_id]['all'] = []
                    kinds_with_all.add(entity_kind_id)

    # Get entities for 'all'
    all_entities_for_types = Entity.objects.filter(
        entity_kind_id__in=kinds_with_all
    ).values_list('id', 'entity_kind_id')

    # Add entity ids to entity kind's all list
    for id, entity_kind_id in all_entities_for_types:
        entities_by_kind[entity_kind_id]['all'].append(id)

    # Get relationships
    relationships = EntityRelationship.objects.filter(
        super_entity_id__in=super_ids,
        sub_entity__entity_kind_id__in=kinds_with_supers
    ).values_list(
        'super_entity_id', 'sub_entity_id', 'sub_entity__entity_kind_id'
    )

    # Add entity ids to each super entity's list
    for super_entity_id, sub_entity_id, sub_entity__entity_kind_id in relationships:
        entities_by_kind[sub_entity__entity_kind_id].setdefault(super_entity_id, [])
        entities_by_kind[sub_entity__entity_kind_id][super_entity_id].append(sub_entity_id)

    return entities_by_kind

Response: Returns a dict with keys of entity kinds and values are lists of Entity objects.


Instruction:
Create a Python 3 function to
give a list of super entities return the entities that have those as a subset of their super entities.

Response:
def is_sub_to_all(self, *super_entities):
        """
        Given a list of super entities, return the entities that have those as a subset of their super entities.
        """
        if super_entities:
            if len(super_entities) == 1:
                # Optimize for the case of just one super entity since this is a much less intensive query
                has_subset = EntityRelationship.objects.filter(
                    super_entity=super_entities[0]).values_list('sub_entity', flat=True)
            else:
                # Get a list of entities that have super entities with all types
                has_subset = EntityRelationship.objects.filter(
                    super_entity__in=super_entities).values('sub_entity').annotate(Count('super_entity')).filter(
                    super_entity__count=len(set(super_entities))).values_list('sub_entity', flat=True)

            return self.filter(id__in=has_subset)
        else:
            return self


Instruction:
How would you implement a function in Python 3 that
returns the entities that have super entities that interset with those provided.

Response:
def is_sub_to_any(self, *super_entities):
        """
        Given a list of super entities, return the entities that have super entities that interset with those provided.
        """
        if super_entities:
            return self.filter(id__in=EntityRelationship.objects.filter(
                super_entity__in=super_entities).values_list('sub_entity', flat=True))
        else:
            return self


Instruction:
Given the following Python 3 function, write the documentation
def is_sub_to_all_kinds(self, *super_entity_kinds):
        if super_entity_kinds:
            if len(super_entity_kinds) == 1:
                # Optimize for the case of just one
                has_subset = EntityRelationship.objects.filter(
                    super_entity__entity_kind=super_entity_kinds[0]).values_list('sub_entity', flat=True)
            else:
                # Get a list of entities that have super entities with all types
                has_subset = EntityRelationship.objects.filter(
                    super_entity__entity_kind__in=super_entity_kinds).values('sub_entity').annotate(
                    Count('super_entity')).filter(super_entity__count=len(set(super_entity_kinds))).values_list(
                    'sub_entity', flat=True)

            return self.filter(pk__in=has_subset)
        else:
            return self

Response: Returns a new queryset with only the superentites of the given entity_kinds.


Instruction:
Here you have a function in Python 3, explain what it does
def is_sub_to_any_kind(self, *super_entity_kinds):
        if super_entity_kinds:
            # get the pks of the desired subs from the relationships table
            if len(super_entity_kinds) == 1:
                entity_pks = EntityRelationship.objects.filter(
                    super_entity__entity_kind=super_entity_kinds[0]
                ).select_related('entity_kind', 'sub_entity').values_list('sub_entity', flat=True)
            else:
                entity_pks = EntityRelationship.objects.filter(
                    super_entity__entity_kind__in=super_entity_kinds
                ).select_related('entity_kind', 'sub_entity').values_list('sub_entity', flat=True)
            # return a queryset limited to only those pks
            return self.filter(pk__in=entity_pks)
        else:
            return self

Response: Return a queryset of all entities that have super_entities of any of the specified kinds.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def cache_relationships(self, cache_super=True, cache_sub=True):
        relationships_to_cache = compress(
            ['super_relationships__super_entity', 'sub_relationships__sub_entity'], [cache_super, cache_sub])
        return self.prefetch_related(*relationships_to_cache)

Response: Caches the super and sub relationships by doing a prefetch_related.


Instruction:
How would you implement a function in Python 3 that
gives a saved entity model object return the associated entity.

Response:
def get_for_obj(self, entity_model_obj):
        """
        Given a saved entity model object, return the associated entity.
        """
        return self.get(entity_type=ContentType.objects.get_for_model(
            entity_model_obj, for_concrete_model=False), entity_id=entity_model_obj.id)


Instruction:
Make a summary of the following Python 3 code
def delete_for_obj(self, entity_model_obj):
        return self.filter(
            entity_type=ContentType.objects.get_for_model(
                entity_model_obj, for_concrete_model=False), entity_id=entity_model_obj.id).delete(
            force=True)

Response: Delete the entities associated with a model object.


Instruction:
Can you tell what is the following Python 3 function doing
def cache_relationships(self, cache_super=True, cache_sub=True):
        return self.get_queryset().cache_relationships(cache_super=cache_super, cache_sub=cache_sub)

Response: Caches the super and sub relationships by doing a prefetch_related.


Instruction:
Make a summary of the following Python 3 code
def get_membership_cache(self, group_ids=None, is_active=True):
        membership_queryset = EntityGroupMembership.objects.filter(
            Q(entity__isnull=True) | (Q(entity__isnull=False) & Q(entity__is_active=is_active))
        )
        if is_active is None:
            membership_queryset = EntityGroupMembership.objects.all()

        if group_ids:
            membership_queryset = membership_queryset.filter(entity_group_id__in=group_ids)

        membership_queryset = membership_queryset.values_list('entity_group_id', 'entity_id', 'sub_entity_kind_id')

        # Iterate over the query results and build the cache dict
        membership_cache = {}
        for entity_group_id, entity_id, sub_entity_kind_id in membership_queryset:
            membership_cache.setdefault(entity_group_id, [])
            membership_cache[entity_group_id].append([entity_id, sub_entity_kind_id])

        return membership_cache

Response: Builds a dict cache with the group membership info.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def all_entities(self, is_active=True):
        return self.get_all_entities(return_models=True, is_active=is_active)

Response: Return all the entities in the group.


Instruction:
Given the following Python 3 function, write the documentation
def get_all_entities(self, membership_cache=None, entities_by_kind=None, return_models=False, is_active=True):
        # If cache args were not passed, generate the cache
        if membership_cache is None:
            membership_cache = EntityGroup.objects.get_membership_cache([self.id], is_active=is_active)

        if entities_by_kind is None:
            entities_by_kind = entities_by_kind or get_entities_by_kind(membership_cache=membership_cache)

        # Build set of all entity ids for this group
        entity_ids = set()

        # This group does have entities
        if membership_cache.get(self.id):

            # Loop over each membership in this group
            for entity_id, entity_kind_id in membership_cache[self.id]:
                if entity_id:
                    if entity_kind_id:
                        # All sub entities of this kind under this entity
                        entity_ids.update(entities_by_kind[entity_kind_id][entity_id])
                    else:
                        # Individual entity
                        entity_ids.add(entity_id)
                else:
                    # All entities of this kind
                    entity_ids.update(entities_by_kind[entity_kind_id]['all'])

        # Check if a queryset needs to be returned
        if return_models:
            return Entity.objects.filter(id__in=entity_ids)

        return entity_ids

Response: Returns a list of all entity ids in this group or optionally returns a queryset for all entity models.


Instruction:
Can you tell what is the following Python 3 function doing
def add_entity(self, entity, sub_entity_kind=None):
        membership = EntityGroupMembership.objects.create(
            entity_group=self,
            entity=entity,
            sub_entity_kind=sub_entity_kind,
        )
        return membership

Response: Adds an entity or sub - entity group to this EntityGroup.


Instruction:
Explain what the following Python 3 code does
def bulk_add_entities(self, entities_and_kinds):
        memberships = [EntityGroupMembership(
            entity_group=self,
            entity=entity,
            sub_entity_kind=sub_entity_kind,
        ) for entity, sub_entity_kind in entities_and_kinds]
        created = EntityGroupMembership.objects.bulk_create(memberships)
        return created

Response: Bulk add many entities and sub - entity groups to this EntityGroup.


Instruction:
Can you tell what is the following Python 3 function doing
def remove_entity(self, entity, sub_entity_kind=None):
        EntityGroupMembership.objects.get(
            entity_group=self,
            entity=entity,
            sub_entity_kind=sub_entity_kind,
        ).delete()

Response: Removes an entity or sub - entity group from this EntityGroup.


Instruction:
How would you implement a function in Python 3 that
bulks remove entities and sub - entity groups to this EntityGroup.

Response:
def bulk_remove_entities(self, entities_and_kinds):
        """
        Remove many entities and sub-entity groups to this EntityGroup.

        :type entities_and_kinds: List of (Entity, EntityKind) pairs.
        :param entities_and_kinds: A list of entity, entity-kind pairs
            to remove from the group. In the pairs, the entity-kind
            can be ``None``, to add a single entity, or some entity
            kind to add all sub-entities of that kind.
        """
        criteria = [
            Q(entity=entity, sub_entity_kind=entity_kind)
            for entity, entity_kind in entities_and_kinds
        ]
        criteria = reduce(lambda q1, q2: q1 | q2, criteria, Q())
        EntityGroupMembership.objects.filter(
            criteria, entity_group=self).delete()


Instruction:
Write a Python 3 function that can
bulk overwrite the given entities and sub - entity groups.

Response:
def bulk_overwrite(self, entities_and_kinds):
        """
        Update the group to the given entities and sub-entity groups.

        After this operation, the only members of this EntityGroup
        will be the given entities, and sub-entity groups.

        :type entities_and_kinds: List of (Entity, EntityKind) pairs.
        :param entities_and_kinds: A list of entity, entity-kind pairs
            to set to the EntityGroup. In the pairs the entity-kind
            can be ``None``, to add a single entity, or some entity
            kind to add all sub-entities of that kind.
        """
        EntityGroupMembership.objects.filter(entity_group=self).delete()
        return self.bulk_add_entities(entities_and_kinds)


Instruction:
Write a Python 3 script to
set the slug for each Work in the DB.

Response:
def set_slug(apps, schema_editor, class_name):
    """
    Create a slug for each Work already in the DB.
    """
    Cls = apps.get_model('spectator_events', class_name)

    for obj in Cls.objects.all():
        obj.slug = generate_slug(obj.pk)
        obj.save(update_fields=['slug'])


Instruction:
Explain what the following Python 3 code does
def get_kind_name_plural(kind):
        "e.g. 'Gigs' or 'Movies'."
        if kind in ['comedy', 'cinema', 'dance', 'theatre']:
            return kind.title()
        elif kind == 'museum':
            return 'Galleries/Museums'
        else:
            return '{}s'.format(Event.get_kind_name(kind))

Response: e. g. Gigs or Movies.


Instruction:
Make a summary of the following Python 3 code
def get_kinds_data():
        kinds = {k:{'name':v} for k,v in Event.KIND_CHOICES}
        for k,data in kinds.items():
            kinds[k]['slug'] = Event.KIND_SLUGS[k]
            kinds[k]['name_plural'] = Event.get_kind_name_plural(k)
        return kinds

Response: Returns a dict of all the data about the kinds of the log entries. e. g. Gigs and Gigs are listed in Event. KIND_SLUGS and Event. KIND_NAME_PLURAL.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def get_list_url(self, kind_slug=None):
        if kind_slug is None:
            kind_slug = self.KIND_SLUGS[self.kind]
        return reverse('spectator:events:work_list',
                                            kwargs={'kind_slug': kind_slug})

Response: Get the list URL for this Work.


Instruction:
How would you implement a function in Python 3 that
converts descriptor and rows to Pandas DataFrame.

Response:
def convert_descriptor_and_rows(self, descriptor, rows):
        """Convert descriptor and rows to Pandas
        """

        # Prepare
        primary_key = None
        schema = tableschema.Schema(descriptor)
        if len(schema.primary_key) == 1:
            primary_key = schema.primary_key[0]
        elif len(schema.primary_key) > 1:
            message = 'Multi-column primary keys are not supported'
            raise tableschema.exceptions.StorageError(message)

        # Get data/index
        data_rows = []
        index_rows = []
        jtstypes_map = {}
        for row in rows:
            values = []
            index = None
            for field, value in zip(schema.fields, row):
                try:
                    if isinstance(value, float) and np.isnan(value):
                        value = None
                    if value and field.type == 'integer':
                        value = int(value)
                    value = field.cast_value(value)
                except tableschema.exceptions.CastError:
                    value = json.loads(value)
                # http://pandas.pydata.org/pandas-docs/stable/gotchas.html#support-for-integer-na
                if value is None and field.type in ('number', 'integer'):
                    jtstypes_map[field.name] = 'number'
                    value = np.NaN
                if field.name == primary_key:
                    index = value
                else:
                    values.append(value)
            data_rows.append(tuple(values))
            index_rows.append(index)

        # Get dtypes
        dtypes = []
        for field in schema.fields:
            if field.name != primary_key:
                field_name = field.name
                if six.PY2:
                    field_name = field.name.encode('utf-8')
                dtype = self.convert_type(jtstypes_map.get(field.name, field.type))
                dtypes.append((field_name, dtype))

        # Create dataframe
        index = None
        columns = schema.headers
        array = np.array(data_rows, dtype=dtypes)
        if primary_key:
            index_field = schema.get_field(primary_key)
            index_dtype = self.convert_type(index_field.type)
            index_class = pd.Index
            if index_field.type in ['datetime', 'date']:
                index_class = pd.DatetimeIndex
            index = index_class(index_rows, name=primary_key, dtype=index_dtype)
            columns = filter(lambda column: column != primary_key, schema.headers)
        dataframe = pd.DataFrame(array, index=index, columns=columns)

        return dataframe


Instruction:
Can you implement a function in Python 3 that
converts type to Pandas

Response:
def convert_type(self, type):
        """Convert type to Pandas
        """

        # Mapping
        mapping = {
            'any': np.dtype('O'),
            'array': np.dtype(list),
            'boolean': np.dtype(bool),
            'date': np.dtype('O'),
            'datetime': np.dtype('datetime64[ns]'),
            'duration': np.dtype('O'),
            'geojson': np.dtype('O'),
            'geopoint': np.dtype('O'),
            'integer': np.dtype(int),
            'number': np.dtype(float),
            'object': np.dtype(dict),
            'string': np.dtype('O'),
            'time': np.dtype('O'),
            'year': np.dtype(int),
            'yearmonth': np.dtype('O'),
        }

        # Get type
        if type not in mapping:
            message = 'Type "%s" is not supported' % type
            raise tableschema.exceptions.StorageError(message)

        return mapping[type]


Instruction:
Can you create a Python 3 function that
restores descriptor from Pandas

Response:
def restore_descriptor(self, dataframe):
        """Restore descriptor from Pandas
        """

        # Prepare
        fields = []
        primary_key = None

        # Primary key
        if dataframe.index.name:
            field_type = self.restore_type(dataframe.index.dtype)
            field = {
                'name': dataframe.index.name,
                'type': field_type,
                'constraints': {'required': True},
            }
            fields.append(field)
            primary_key = dataframe.index.name

        # Fields
        for column, dtype in dataframe.dtypes.iteritems():
            sample = dataframe[column].iloc[0] if len(dataframe) else None
            field_type = self.restore_type(dtype, sample=sample)
            field = {'name': column, 'type': field_type}
            # TODO: provide better required indication
            # if dataframe[column].isnull().sum() == 0:
            #     field['constraints'] = {'required': True}
            fields.append(field)

        # Descriptor
        descriptor = {}
        descriptor['fields'] = fields
        if primary_key:
            descriptor['primaryKey'] = primary_key

        return descriptor


Instruction:
Explain what the following Python 3 code does
def restore_row(self, row, schema, pk):
        result = []
        for field in schema.fields:
            if schema.primary_key and schema.primary_key[0] == field.name:
                if field.type == 'number' and np.isnan(pk):
                    pk = None
                if pk and field.type == 'integer':
                    pk = int(pk)
                result.append(field.cast_value(pk))
            else:
                value = row[field.name]
                if field.type == 'number' and np.isnan(value):
                    value = None
                if value and field.type == 'integer':
                    value = int(value)
                elif field.type == 'datetime':
                    value = value.to_pydatetime()
                result.append(field.cast_value(value))
        return result

Response: Restore row from Pandas


Instruction:
Given the following Python 3 function, write the documentation
def restore_type(self, dtype, sample=None):

        # Pandas types
        if pdc.is_bool_dtype(dtype):
            return 'boolean'
        elif pdc.is_datetime64_any_dtype(dtype):
            return 'datetime'
        elif pdc.is_integer_dtype(dtype):
            return 'integer'
        elif pdc.is_numeric_dtype(dtype):
            return 'number'

        # Python types
        if sample is not None:
            if isinstance(sample, (list, tuple)):
                return 'array'
            elif isinstance(sample, datetime.date):
                return 'date'
            elif isinstance(sample, isodate.Duration):
                return 'duration'
            elif isinstance(sample, dict):
                return 'object'
            elif isinstance(sample, six.string_types):
                return 'string'
            elif isinstance(sample, datetime.time):
                return 'time'

        return 'string'

Response: Restore type from Pandas


Instruction:
Write a Python 3 function that can
return a dict that can be used to display a link to the object s Admin page.

Response:
def change_object_link_card(obj, perms):
    """
    If the user has permission to change `obj`, show a link to its Admin page.
    obj -- An object like Movie, Play, ClassicalWork, Publication, etc.
    perms -- The `perms` object that it's the template.
    """
    # eg: 'movie' or 'classicalwork':
    name = obj.__class__.__name__.lower()
    permission = 'spectator.can_edit_{}'.format(name)
    # eg: 'admin:events_classicalwork_change':
    change_url_name = 'admin:{}_{}_change'.format(obj._meta.app_label, name)

    return {
        'display_link': (permission in perms),
        'change_url': reverse(change_url_name, args=[obj.id])
    }


Instruction:
How would you code a function in Python 3 to
return an HTML link to the supplied URL, but only using the domain as the text. Strips 'www.' from the start of the domain, if present. e.g. if `my_url` is 'http://www.example.org/foo/' then: {{ my_url|domain_urlize }} returns: example.org

Response:
def domain_urlize(value):
    """
    Returns an HTML link to the supplied URL, but only using the domain as the
    text. Strips 'www.' from the start of the domain, if present.

    e.g. if `my_url` is 'http://www.example.org/foo/' then:

        {{ my_url|domain_urlize }}

    returns:
        example.org
    """
    parsed_uri = urlparse(value)
    domain = '{uri.netloc}'.format(uri=parsed_uri)

    if domain.startswith('www.'):
        domain = domain[4:]

    return format_html('{}',
            value,
            domain
        )


Instruction:
Can you generate the documentation for the following Python 3 function
def current_url_name(context):
    url_name = False
    if context.request.resolver_match:
        url_name = "{}:{}".format(
                                context.request.resolver_match.namespace,
                                context.request.resolver_match.url_name
                            )
    return url_name

Response: Returns the name of the current URL namespaced or False.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def query_string(context, key, value):
    try:
        request = context['request']
        args = request.GET.copy()
    except KeyError:
        args = QueryDict('').copy()
    args[key] = value
    return args.urlencode()

Response: Returns a query string for a URL.


Instruction:
Make a summary of the following Python 3 code
def most_read_creators_card(num=10):
    if spectator_apps.is_enabled('reading'):

        object_list = most_read_creators(num=num)

        object_list = chartify(object_list, 'num_readings', cutoff=1)

        return {
            'card_title': 'Most read authors',
            'score_attr': 'num_readings',
            'object_list': object_list,
        }

Response: Displays a card showing the most Readings of Creators who have the most Readings associated with their Publications.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def most_visited_venues_card(num=10):
    if spectator_apps.is_enabled('events'):

        object_list = most_visited_venues(num=num)

        object_list = chartify(object_list, 'num_visits', cutoff=1)

        return {
            'card_title': 'Most visited venues',
            'score_attr': 'num_visits',
            'object_list': object_list,
        }

Response: Displays a card showing the most Visited Venues.


Instruction:
Given the following Python 3 function, write the documentation
def get_entity(package, entity):
    init_py = open(os.path.join(package, '__init__.py')).read()
    find = "__%s__ = ['\"]([^'\"]+)['\"]" % entity
    return re.search(find, init_py).group(1)

Response: get_entity returns the value in


Instruction:
Implement a function in Python 3 to
reduce the number of queries and speed things up.

Response:
def get_queryset(self):
        "Reduce the number of queries and speed things up."
        qs = super().get_queryset()

        qs = qs.select_related('publication__series') \
                .prefetch_related('publication__roles__creator')

        return qs


Instruction:
Can you generate the documentation for the following Python 3 function
def set_slug(apps, schema_editor):
    Creator = apps.get_model('spectator_core', 'Creator')

    for c in Creator.objects.all():
        c.slug = generate_slug(c.pk)
        c.save(update_fields=['slug'])

Response: Create a slug for each Creator already in the DB.


Instruction:
Write a Python 3 function that can
copy the ClassicalWork and DancePiece data to use the new through models.

Response:
def forwards(apps, schema_editor):
    """
    Copy the ClassicalWork and DancePiece data to use the new through models.
    """
    Event = apps.get_model('spectator_events', 'Event')
    ClassicalWorkSelection = apps.get_model(
                                'spectator_events', 'ClassicalWorkSelection')
    DancePieceSelection = apps.get_model(
                                'spectator_events', 'DancePieceSelection')

    for event in Event.objects.all():

        for work in event.classicalworks.all():
            selection = ClassicalWorkSelection(
                            classical_work=work,
                            event=event)
            selection.save()

        for piece in event.dancepieces.all():
            selection = DancePieceSelection(
                            dance_piece=piece,
                            event=event)
            selection.save()


Instruction:
Here you have a function in Python 3, explain what it does
def forwards(apps, schema_editor):
    Event = apps.get_model('spectator_events', 'Event')

    for event in Event.objects.all():
        if event.venue is not None:
            event.venue_name = event.venue.name
            event.save()

Response: Set the venue_name field of all Events that have a Venue.


Instruction:
How would you explain what the following Python 3 function does
def forwards(apps, schema_editor):
    Event = apps.get_model('spectator_events', 'Event')

    for ev in Event.objects.filter(kind='exhibition'):
        ev.kind = 'museum'
        ev.save()

Response: Migrate all exhibition Events to the new museum Event kind.


Instruction:
Can you generate the documentation for the following Python 3 function
def truncate_string(text, strip_html=True, chars=255, truncate='…', at_word_boundary=False):
    if strip_html:
        text = strip_tags(text)
    text = text.replace('\n', ' ').replace('\r', '')
    text = ' '.join(text.split())
    if at_word_boundary:
        if len(text) > chars:
            text = text[:chars].rsplit(' ', 1)[0] + truncate
    else:
        text = Truncator(text).chars(chars, html=False, truncate=truncate)
    return text

Response: Truncate a string to a certain length.


Instruction:
Given the following Python 3 function, write the documentation
def chartify(qs, score_field, cutoff=0, ensure_chartiness=True):
    chart = []
    position = 0
    prev_obj = None

    for counter, obj in enumerate(qs):
        score = getattr(obj, score_field)

        if score != getattr(prev_obj, score_field, None):
            position = counter + 1

        if cutoff is None or score > cutoff:
            obj.chart_position = position
            chart.append(obj)

        prev_obj = obj

    if ensure_chartiness and len(chart) > 0:
        if getattr(chart[0], score_field) == getattr(chart[-1], score_field):
            chart = []

    return chart

Response: Given a QuerySet it will go through and add a chart_position property to each object returning a list of the objects that are adjacent to the given score field. If the object is not adjacent to the given score the list will be empty.


Instruction:
Write a Python 3 script to
return a QuerySet of all the Venues that have been held there.

Response:
def by_visits(self, event_kind=None):
        """
        Gets Venues in order of how many Events have been held there.
        Adds a `num_visits` field to each one.

        event_kind filters by kind of Event, e.g. 'theatre', 'cinema', etc.
        """
        qs = self.get_queryset()

        if event_kind is not None:
            qs = qs.filter(event__kind=event_kind)

        qs = qs.annotate(num_visits=Count('event')) \
                .order_by('-num_visits', 'name_sort')

        return qs


Instruction:
Write a Python 3 function for
returning a QuerySet of all Works in order of how many times they have been attached to a specific Entry.

Response:
def by_views(self, kind=None):
        """
        Gets Works in order of how many times they've been attached to
        Events.

        kind is the kind of Work, e.g. 'play', 'movie', etc.
        """
        qs = self.get_queryset()

        if kind is not None:
            qs = qs.filter(kind=kind)

        qs = qs.annotate(num_views=Count('event')) \
                .order_by('-num_views', 'title_sort')

        return qs


Instruction:
How would you code a function in Python 3 to
make a naturalized version of a general string, not a person's name. e.g., title of a book, a band's name, etc. string -- a lowercase string.

Response:
def naturalize_thing(self, string):
        """
        Make a naturalized version of a general string, not a person's name.
        e.g., title of a book, a band's name, etc.

        string -- a lowercase string.
        """

        # Things we want to move to the back of the string:
        articles = [
                        'a', 'an', 'the',
                        'un', 'une', 'le', 'la', 'les', "l'", "l’",
                        'ein', 'eine', 'der', 'die', 'das',
                        'una', 'el', 'los', 'las',
                    ]

        sort_string = string
        parts = string.split(' ')

        if len(parts) > 1 and parts[0] in articles:
            if parts[0] != parts[1]:
                # Don't do this if the name is 'The The' or 'La La Land'.
                # Makes 'long blondes, the':
                sort_string = '{}, {}'.format(' '.join(parts[1:]), parts[0])

        sort_string = self._naturalize_numbers(sort_string)

        return sort_string


Instruction:
How would you implement a function in Python 3 that
attempts to make a version of the string that has the surname, if any, at the start. 'John, Brown' to 'Brown, John' 'Sir John Brown Jr' to 'Brown, Sir John Jr' 'Prince' to 'Prince' string -- The string to change.

Response:
def naturalize_person(self, string):
        """
        Attempt to make a version of the string that has the surname, if any,
        at the start.

        'John, Brown' to 'Brown, John'
        'Sir John Brown Jr' to 'Brown, Sir John Jr'
        'Prince' to 'Prince'

        string -- The string to change.
        """
        suffixes = [
                    'Jr', 'Jr.', 'Sr', 'Sr.',
                    'I', 'II', 'III', 'IV', 'V',
                    ]
        # Add lowercase versions:
        suffixes = suffixes + [s.lower() for s in suffixes]

        # If a name has a capitalised particle in we use that to sort.
        # So 'Le Carre, John' but 'Carre, John le'.
        particles = [
                    'Le', 'La',
                    'Von', 'Van',
                    'Du', 'De',
                    ]

        surname = '' # Smith
        names = ''   # Fred James
        suffix = ''  # Jr

        sort_string = string
        parts = string.split(' ')

        if parts[-1] in suffixes:
            # Remove suffixes entirely, as we'll add them back on the end.
            suffix = parts[-1]
            parts = parts[0:-1] # Remove suffix from parts
            sort_string = ' '.join(parts)

        if len(parts) > 1:

            if parts[-2] in particles:
                # From ['Alan', 'Barry', 'Le', 'Carré']
                # to   ['Alan', 'Barry', 'Le Carré']:
                parts = parts[0:-2] + [ ' '.join(parts[-2:]) ]

            # From 'David Foster Wallace' to 'Wallace, David Foster':
            sort_string = '{}, {}'.format(parts[-1], ' '.join(parts[:-1]))

        if suffix:
            # Add it back on.
            sort_string = '{} {}'.format(sort_string, suffix)

        # In case this name has any numbers in it.
        sort_string = self._naturalize_numbers(sort_string)

        return sort_string


Instruction:
Implement a Python 3 function for
taking a string and replaces any zero - padded numbers into very zero - padded numbers.

Response:
def _naturalize_numbers(self, string):
        """
        Makes any integers into very zero-padded numbers.
        e.g. '1' becomes '00000001'.
        """

        def naturalize_int_match(match):
            return '%08d' % (int(match.group(0)),)

        string = re.sub(r'\d+', naturalize_int_match, string)

        return string


Instruction:
Write a Python 3 function that can
return a list of dicts that are lists of dicts with counts for each year of reading.

Response:
def annual_reading_counts(kind='all'):
    """
    Returns a list of dicts, one per year of reading. In year order.
    Each dict is like this (if kind is 'all'):

        {'year':        datetime.date(2003, 1, 1),
         'book':        12,    # only included if kind is 'all' or 'book'
         'periodical':  18,    # only included if kind is 'all' or 'periodical'
         'total':       30,    # only included if kind is 'all'
         }

    We use the end_date of a Reading to count when that thing was read.

    kind is one of 'book', 'periodical' or 'all', for both.
    """
    if kind == 'all':
        kinds = ['book', 'periodical']
    else:
        kinds = [kind]

    # This will have keys of years (strings) and dicts of data:
    # {
    #   '2003': {'books': 12, 'periodicals': 18},
    # }
    counts = OrderedDict()

    for k in kinds:
        qs = Reading.objects.exclude(end_date__isnull=True) \
                            .filter(publication__kind=k) \
                            .annotate(year=TruncYear('end_date')) \
                            .values('year') \
                            .annotate(count=Count('id')) \
                            .order_by('year')

        for year_data in qs:
            year_str = year_data['year'].strftime('%Y')
            if not year_str in counts:
                counts[year_str] = {
                    'year': year_data['year'],
                }

            counts[year_str][k] = year_data['count']

    # Now translate counts into our final list, with totals, and 0s for kinds
    # when they have no Readings for that year.
    counts_list = []

    for year_str, data in counts.items():
        year_data = {
            'year': data['year'],
        }
        if kind == 'all':
            year_data['total'] = 0

        for k in kinds:
            if k in data:
                year_data[k] = data[k]
                if kind == 'all':
                    year_data['total'] += data[k]
            else:
                year_data[k] = 0

        counts_list.append(year_data)

    return counts_list


Instruction:
Can you generate the documentation for the following Python 3 function
def lookups(self, request, model_admin):
        list_of_countries = []

        # We don't need the country_count but we need to annotate them in order
        # to group the results.
        qs = Venue.objects.exclude(country='') \
                            .values('country') \
                            .annotate(country_count=Count('country')) \
                            .order_by('country')
        for obj in qs:
            country = obj['country']
            list_of_countries.append(
                (country, Venue.COUNTRIES[country])
            )

        return sorted(list_of_countries, key=lambda c: c[1])

Response: Returns a list of tuples like Australia GB UK and USA.


Instruction:
Can you generate the documentation for the following Python 3 function
def queryset(self, request, queryset):
        if self.value():
            return queryset.filter(country=self.value())
        else:
            return queryset

Response:
Returns the filtered queryset based on the value
        provided in the query string and retrievable via the self. value property.


Instruction:
Implement a function in Python 3 to
copy data from the old Event. movie and Event. play ManyToManyFields into the new Event. movies and Event. plays ManyToManyFields.

Response:
def forward(apps, schema_editor):
    """
    Copying data from the old `Event.movie` and `Event.play` ForeignKey fields
    into the new `Event.movies` and `Event.plays` ManyToManyFields.
    """

    Event = apps.get_model('spectator_events', 'Event')
    MovieSelection = apps.get_model('spectator_events', 'MovieSelection')
    PlaySelection = apps.get_model('spectator_events', 'PlaySelection')

    for event in Event.objects.all():
        if event.movie is not None:
            selection = MovieSelection(event=event, movie=event.movie)
            selection.save()

        if event.play is not None:
            selection = PlaySelection(event=event, play=event.play)
            selection.save()


Instruction:
Write a Python 3 function that can
create a slug for each Event already in the DB.

Response:
def set_slug(apps, schema_editor):
    """
    Create a slug for each Event already in the DB.
    """
    Event = apps.get_model('spectator_events', 'Event')

    for e in Event.objects.all():
        e.slug = generate_slug(e.pk)
        e.save(update_fields=['slug'])


Instruction:
How would you implement a function in Python 3 that
returns a standard page instance with custom digg - specific page ranges attached.

Response:
def page(self, number, *args, **kwargs):
        """Return a standard ``Page`` instance with custom, digg-specific
        page ranges attached.
        """

        page = super().page(number, *args, **kwargs)
        number = int(number) # we know this will work

        # easier access
        num_pages, body, tail, padding, margin = \
            self.num_pages, self.body, self.tail, self.padding, self.margin

        # put active page in middle of main range
        main_range = list(map(int, [
            math.floor(number-body/2.0)+1,  # +1 = shift odd body to right
            math.floor(number+body/2.0)]))
        # adjust bounds
        if main_range[0] < 1:
            main_range = list(map(abs(main_range[0]-1).__add__, main_range))
        if main_range[1] > num_pages:
            main_range = list(map((num_pages-main_range[1]).__add__, main_range))

        # Determine leading and trailing ranges; if possible and appropriate,
        # combine them with the main range, in which case the resulting main
        # block might end up considerable larger than requested. While we
        # can't guarantee the exact size in those cases, we can at least try
        # to come as close as possible: we can reduce the other boundary to
        # max padding, instead of using half the body size, which would
        # otherwise be the case. If the padding is large enough, this will
        # of course have no effect.
        # Example:
        #     total pages=100, page=4, body=5, (default padding=2)
        #     1 2 3 [4] 5 6 ... 99 100
        #     total pages=100, page=4, body=5, padding=1
        #     1 2 3 [4] 5 ... 99 100
        # If it were not for this adjustment, both cases would result in the
        # first output, regardless of the padding value.
        if main_range[0] <= tail+margin:
            leading = []
            main_range = [1, max(body, min(number+padding, main_range[1]))]
            main_range[0] = 1
        else:
            leading = list(range(1, tail+1))
        # basically same for trailing range, but not in ``left_align`` mode
        if self.align_left:
            trailing = []
        else:
            if main_range[1] >= num_pages-(tail+margin)+1:
                trailing = []
                if not leading:
                    # ... but handle the special case of neither leading nor
                    # trailing ranges; otherwise, we would now modify the
                    # main range low bound, which we just set in the previous
                    # section, again.
                    main_range = [1, num_pages]
                else:
                    main_range = [min(num_pages-body+1, max(number-padding, main_range[0])), num_pages]
            else:
                trailing = list(range(num_pages-tail+1, num_pages+1))

        # finally, normalize values that are out of bound; this basically
        # fixes all the things the above code screwed up in the simple case
        # of few enough pages where one range would suffice.
        main_range = [max(main_range[0], 1), min(main_range[1], num_pages)]

        # make the result of our calculations available as custom ranges
        # on the ``Page`` instance.
        page.main_range = list(range(main_range[0], main_range[1]+1))
        page.leading_range = leading
        page.trailing_range = trailing
        page.page_range = reduce(lambda x, y: x+((x and y) and [False])+y,
            [page.leading_range, page.main_range, page.trailing_range])

        page.__class__ = DiggPage
        return page


Instruction:
Here you have a function in Python 3, explain what it does
def version():
    namespace = {}
    with open(os.path.join('mrcfile', 'version.py')) as f:
        exec(f.read(), namespace)
    return namespace['__version__']

Response: Get the version number without importing the mrcfile package.


Instruction:
Here you have a function in Python 3, explain what it does
def get_event_counts(self):
        counts = {'all': Event.objects.count(),}

        for k,v in Event.KIND_CHOICES:
            # e.g. 'movie_count':
            counts[k] = Event.objects.filter(kind=k).count()

        return {'counts': counts,}

Response: Returns a dict of event counts.


Instruction:
Can you tell what is the following Python 3 function doing
def get_event_kind(self):
        slug = self.kwargs.get('kind_slug', None)
        if slug is None:
            return None  # Front page; showing all Event kinds.
        else:
            slugs_to_kinds = {v:k for k,v in Event.KIND_SLUGS.items()}
            return slugs_to_kinds.get(slug, None)

Response: Returns the event kind from the kind_slug.


Instruction:
How would you code a function in Python 3 to
restrict to a single kind of event if any and include Venue data.

Response:
def get_queryset(self):
        "Restrict to a single kind of event, if any, and include Venue data."
        qs = super().get_queryset()

        kind = self.get_event_kind()
        if kind is not None:
            qs = qs.filter(kind=kind)

        qs = qs.select_related('venue')

        return qs


Instruction:
Can you tell what is the following Python 3 function doing
def get_work_kind(self):
        slugs_to_kinds = {v:k for k,v in Work.KIND_SLUGS.items()}
        return slugs_to_kinds.get(self.kind_slug, None)

Response: Get the work kind from the kind_slug.


Instruction:
Can you generate the documentation for the following Python 3 function
def get_countries(self):
        qs = Venue.objects.values('country') \
                                    .exclude(country='') \
                                    .distinct() \
                                    .order_by('country')

        countries = []

        for c in qs:
            countries.append({
                'code': c['country'],
                'name': Venue.get_country_name(c['country'])
            })

        return sorted(countries, key=lambda k: k['name'])

Response:
Returns a list of dicts one per country that has at least one Venue
        in it.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def annual_event_counts(kind='all'):
    qs = Event.objects

    if kind != 'all':
        qs = qs.filter(kind=kind)

    qs = qs.annotate(year=TruncYear('date')) \
            .values('year') \
            .annotate(total=Count('id')) \
            .order_by('year')

    return qs

Response: Returns a QuerySet of dicts with the keys year total and the values of the year that are annual events.


Instruction:
Explain what the following Python 3 code does
def annual_event_counts_card(kind='all', current_year=None):
    if kind == 'all':
        card_title = 'Events per year'
    else:
        card_title = '{} per year'.format(Event.get_kind_name_plural(kind))

    return {
            'card_title': card_title,
            'kind': kind,
            'years': annual_event_counts(kind=kind),
            'current_year': current_year
            }

Response: A simple card showing the number of events per year.


Instruction:
Can you write a function in Python 3 where it
renders a date as a date and display it in a time tag.

Response:
def display_date(d):
    """
    Render a date/datetime (d) as a date, using the SPECTATOR_DATE_FORMAT
    setting. Wrap the output in a <time> tag.

    Time tags: http://www.brucelawson.co.uk/2012/best-of-time/
    """
    stamp = d.strftime('%Y-%m-%d')
    visible_date = d.strftime(app_settings.DATE_FORMAT)

    return format_html('<time datetime="%(stamp)s">%(visible)s</time>' % {
                'stamp': stamp,
                'visible': visible_date
            })


Instruction:
Create a Python 3 function to
display the tabs to different event_list pages. `counts` is a dict of number of events for each kind, like: {'all': 30, 'gig': 12, 'movie': 18,} `current_kind` is the event kind that's active, if any. e.g. 'gig', 'movie', etc. `page_number` is the current page of this kind of events we're on.

Response:
def event_list_tabs(counts, current_kind, page_number=1):
    """
    Displays the tabs to different event_list pages.

    `counts` is a dict of number of events for each kind, like:
        {'all': 30, 'gig': 12, 'movie': 18,}

    `current_kind` is the event kind that's active, if any. e.g. 'gig',
        'movie', etc.

    `page_number` is the current page of this kind of events we're on.
    """
    return {
            'counts': counts,
            'current_kind': current_kind,
            'page_number': page_number,
            # A list of all the kinds we might show tabs for, like
            # ['gig', 'movie', 'play', ...]
            'event_kinds': Event.get_kinds(),
            # A dict of data about each kind, keyed by kind ('gig') including
            # data about 'name', 'name_plural' and 'slug':
            'event_kinds_data': Event.get_kinds_data(),
        }


Instruction:
Implement a function in Python 3 to
display the events that happened on the supplied date.

Response:
def day_events_card(date):
    """
    Displays Events that happened on the supplied date.
    `date` is a date object.
    """
    d = date.strftime(app_settings.DATE_FORMAT)
    card_title = 'Events on {}'.format(d)
    return {
            'card_title': card_title,
            'event_list': day_events(date=date),
            }


Instruction:
Can you generate the documentation for the following Python 3 function
def most_seen_creators_card(event_kind=None, num=10):
    object_list = most_seen_creators(event_kind=event_kind, num=num)

    object_list = chartify(object_list, 'num_events', cutoff=1)

    return {
        'card_title': 'Most seen people/groups',
        'score_attr': 'num_events',
        'object_list': object_list,
    }

Response: Displays a card showing the most seen Creators.


Instruction:
Implement a Python 3 function for
returning a QuerySet of Creators that are associated with the most Works.

Response:
def most_seen_creators_by_works(work_kind=None, role_name=None, num=10):
    """
    Returns a QuerySet of the Creators that are associated with the most Works.
    """
    return Creator.objects.by_works(kind=work_kind, role_name=role_name)[:num]


Instruction:
Create a Python 3 function to
display a card showing the Creators that are associated with the most Works.

Response:
def most_seen_creators_by_works_card(work_kind=None, role_name=None, num=10):
    """
    Displays a card showing the Creators that are associated with the most Works.

    e.g.:

      {% most_seen_creators_by_works_card work_kind='movie' role_name='Director' num=5 %}
    """
    object_list = most_seen_creators_by_works(
                            work_kind=work_kind, role_name=role_name, num=num)

    object_list = chartify(object_list, 'num_works', cutoff=1)

    # Attempt to create a sensible card title...

    if role_name:
        # Yes, this pluralization is going to break at some point:
        creators_name = '{}s'.format(role_name.capitalize())
    else:
        creators_name = 'People/groups'

    if work_kind:
        works_name = Work.get_kind_name_plural(work_kind).lower()
    else:
        works_name = 'works'

    card_title = '{} with most {}'.format(creators_name, works_name)

    return {
        'card_title': card_title,
        'score_attr': 'num_works',
        'object_list': object_list,
    }


Instruction:
Can you tell what is the following Python 3 function doing
def most_seen_works_card(kind=None, num=10):
    object_list = most_seen_works(kind=kind, num=num)

    object_list = chartify(object_list, 'num_views', cutoff=1)

    if kind:
        card_title = 'Most seen {}'.format(
                                    Work.get_kind_name_plural(kind).lower())
    else:
        card_title = 'Most seen works'

    return {
        'card_title': card_title,
        'score_attr': 'num_views',
        'object_list': object_list,
        'name_attr': 'title',
        'use_cite': True,
    }

Response: Displays a card showing the Works that are associated with the most Events.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def _generate_slug(self, value):
        alphabet = app_settings.SLUG_ALPHABET
        salt = app_settings.SLUG_SALT

        hashids = Hashids(alphabet=alphabet, salt=salt, min_length=5)

        return hashids.encode(value)

Response: Generates a slug using a Hashid of value.


Instruction:
Explain what the following Python 3 code does
def create(self, bucket, descriptor, force=False):

        # Make lists
        buckets = bucket
        if isinstance(bucket, six.string_types):
            buckets = [bucket]
        descriptors = descriptor
        if isinstance(descriptor, dict):
            descriptors = [descriptor]

        # Check buckets for existence
        for bucket in buckets:
            if bucket in self.buckets:
                if not force:
                    message = 'Bucket "%s" already exists' % bucket
                    raise tableschema.exceptions.StorageError(message)
                self.delete(bucket)

        # Define dataframes
        for bucket, descriptor in zip(buckets, descriptors):
            tableschema.validate(descriptor)
            self.__descriptors[bucket] = descriptor
            self.__dataframes[bucket] = pd.DataFrame()

Response: Create a new object in the storage.


Instruction:
Can you generate the documentation for the following Python 3 function
def delete(self, bucket=None, ignore=False):

        # Make lists
        buckets = bucket
        if isinstance(bucket, six.string_types):
            buckets = [bucket]
        elif bucket is None:
            buckets = reversed(self.buckets)

        # Iterate over buckets
        for bucket in buckets:

            # Non existent bucket
            if bucket not in self.buckets:
                if not ignore:
                    message = 'Bucket "%s" doesn\'t exist' % bucket
                    raise tableschema.exceptions.StorageError(message)
                return

            # Remove from descriptors
            if bucket in self.__descriptors:
                del self.__descriptors[bucket]

            # Remove from dataframes
            if bucket in self.__dataframes:
                del self.__dataframes[bucket]

Response: Delete the object from the database.


Instruction:
How would you code a function in Python 3 to
get or set the descriptor for a given bucket.

Response:
def describe(self, bucket, descriptor=None):
        """https://github.com/frictionlessdata/tableschema-pandas-py#storage
        """

        # Set descriptor
        if descriptor is not None:
            self.__descriptors[bucket] = descriptor

        # Get descriptor
        else:
            descriptor = self.__descriptors.get(bucket)
            if descriptor is None:
                dataframe = self.__dataframes[bucket]
                descriptor = self.__mapper.restore_descriptor(dataframe)

        return descriptor


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

        # Check existense
        if bucket not in self.buckets:
            message = 'Bucket "%s" doesn\'t exist.' % bucket
            raise tableschema.exceptions.StorageError(message)

        # Prepare
        descriptor = self.describe(bucket)
        schema = tableschema.Schema(descriptor)

        # Yield rows
        for pk, row in self.__dataframes[bucket].iterrows():
            row = self.__mapper.restore_row(row, schema=schema, pk=pk)
            yield row

Response: Iterate over the items in the specified bucket.


Instruction:
Write a Python 3 function that can
write the rows to the DataFrame.

Response:
def write(self, bucket, rows):
        """https://github.com/frictionlessdata/tableschema-pandas-py#storage
        """

        # Prepare
        descriptor = self.describe(bucket)
        new_data_frame = self.__mapper.convert_descriptor_and_rows(descriptor, rows)

        # Just set new DataFrame if current is empty
        if self.__dataframes[bucket].size == 0:
            self.__dataframes[bucket] = new_data_frame

        # Append new data frame to the old one setting new data frame
        # containing data from both old and new data frames
        else:
            self.__dataframes[bucket] = pd.concat([
                self.__dataframes[bucket],
                new_data_frame,
            ])


Instruction:
Make a summary of the following Python 3 code
def forwards(apps, schema_editor):
    Movie = apps.get_model('spectator_events', 'Movie')
    Work = apps.get_model('spectator_events', 'Work')
    WorkRole = apps.get_model('spectator_events', 'WorkRole')
    WorkSelection = apps.get_model('spectator_events', 'WorkSelection')

    for m in Movie.objects.all():

        work = Work.objects.create(
            kind='movie',
            title=m.title,
            title_sort=m.title_sort,
            year=m.year,
            imdb_id=m.imdb_id
        )

        for role in m.roles.all():
            WorkRole.objects.create(
                creator=role.creator,
                work=work,
                role_name=role.role_name,
                role_order=role.role_order
            )

        for selection in m.events.all():
            WorkSelection.objects.create(
                event=selection.event,
                work=work,
                order=selection.order
            )

        m.delete()

Response:
Change all Movie objects into Work objects and their associated
Addon data into WorkRole and WorkSelection models then delete the Movie.


Instruction:
Make a summary of the following Python 3 code
def paginate_queryset(self, queryset, page_size):
        paginator = self.get_paginator(
            queryset,
            page_size,
            orphans = self.get_paginate_orphans(),
            allow_empty_first_page = self.get_allow_empty(),
            body    = self.paginator_body,
            margin  = self.paginator_margin,
            padding = self.paginator_padding,
            tail    = self.paginator_tail,
        )
        page_kwarg = self.page_kwarg
        page = self.kwargs.get(page_kwarg) or self.request.GET.get(page_kwarg) or 1
        try:
            page_number = int(page)
        except ValueError:
            if page == 'last':
                page_number = paginator.num_pages
            else:
                raise Http404(_("Page is not 'last', nor can it be converted to an int."))
        try:
            page = paginator.page(page_number, softlimit=False)
            return (paginator, page, page.object_list, page.has_other_pages())
        except InvalidPage as e:
            raise Http404(_('Invalid page (%(page_number)s): %(message)s') % {
                'page_number': page_number,
                'message': str(e)
            })

Response: Paginate the queryset and return a tuple of tuples containing the paginator and the list of objects that are returned.


Instruction:
Given the following Python 3 function, write the documentation
def annual_reading_counts_card(kind='all', current_year=None):
    if kind == 'book':
        card_title = 'Books per year'
    elif kind == 'periodical':
        card_title = 'Periodicals per year'
    else:
        card_title = 'Reading per year'

    return {
            'card_title': card_title,
            'kind': kind,
            'years': utils.annual_reading_counts(kind),
            'current_year': current_year
            }

Response: Returns a dict with the information about the annual reading counts of the current year.