Instruction:
Create a Python 3 function for
topping - Down Time - ratio Trajectory Compression Algorithm

Response:
def td_tr(points, dist_threshold):
    """ Top-Down Time-Ratio Trajectory Compression Algorithm

    Detailed in https://www.itc.nl/library/Papers_2003/peer_ref_conf/meratnia_new.pdf

    Args:
        points (:obj:`list` of :obj:`Point`): trajectory or part of it
        dist_threshold (float): max distance error, in meters
    Returns:
        :obj:`list` of :obj:`Point`, compressed trajectory
    """
    if len(points) <= 2:
        return points
    else:
        max_dist_threshold = 0
        found_index = 0
        delta_e = time_dist(points[-1], points[0]) * I_3600
        d_lat = points[-1].lat - points[0].lat
        d_lon = points[-1].lon - points[0].lon

        for i in range(1, len(points)-1):
            delta_i = time_dist(points[i], points[0]) * I_3600

            di_de = delta_i / delta_e
            point = Point(
                points[0].lat + d_lat * di_de,
                points[0].lon + d_lon * di_de,
                None
            )

            dist = loc_dist(points[i], point)
            if dist > max_dist_threshold:
                max_dist_threshold = dist
                found_index = i

        if max_dist_threshold > dist_threshold:
            one = td_tr(points[:found_index], dist_threshold)
            two = td_tr(points[found_index:], dist_threshold)
            one.extend(two)
            return one
        else:
            return [points[0], points[-1]]


Instruction:
How would you explain what the following Python 3 function does
def spt(points, max_dist_error, max_speed_error):
    if len(points) <= 2:
        return points
    else:
        is_error = False
        e = 1
        while e < len(points) and not is_error:
            i = 1
            while i < e and not is_error:
                delta_e = time_dist(points[e], points[0]) * I_3600
                delta_i = time_dist(points[i], points[0]) * I_3600

                di_de = 0
                if delta_e != 0:
                    di_de = delta_i / delta_e
                d_lat = points[e].lat - points[0].lat
                d_lon = points[e].lon - points[0].lon
                point = Point(
                    points[0].lat + d_lat * di_de,
                    points[0].lon + d_lon * di_de,
                    None
                )

                dt1 = time_dist(points[i], points[i-1])
                if dt1 == 0:
                    dt1 = 0.000000001
                dt2 = time_dist(points[i+1], points[i])
                if dt2 == 0:
                    dt2 = 0.000000001

                v_i_1 = loc_dist(points[i], points[i-1]) / dt1
                v_i = loc_dist(points[i+1], points[i]) / dt2

                if loc_dist(points[i], point) > max_dist_error or abs(v_i - v_i_1) > max_speed_error:
                    is_error = True
                else:
                    i = i + 1
            if is_error:
                return [points[0]] + spt(points[i:len(points)], max_dist_error, max_speed_error)
            e = e + 1
        if not is_error:
            return [points[0], points[len(points)-1]]

Response: A function that returns a list of points that are in the order of distance from the first point to the second point.


Instruction:
Make a summary of the following Python 3 code
def generate_name(self, name_format=DEFAULT_FILE_NAME_FORMAT):
        if len(self.segments) > 0:
            return self.segments[0].points[0].time.strftime(name_format) + ".gpx"
        else:
            return "EmptyTrack"

Response: Generates a name for the track based on the start time of the first point of the track.


Instruction:
Here you have a function in Python 3, explain what it does
def smooth(self, strategy, noise):
        print noise
        for segment in self.segments:
            segment.smooth(noise, strategy)
        return self

Response:
In - place smoothing of segments
           .


Instruction:
How would you explain what the following Python 3 function does
def infer_transportation_modes(self, dt_threshold=10):
        self.segments = [
            segment.infer_transportation_mode(dt_threshold=dt_threshold)
            for segment in self.segments
            ]
        return self

Response: In - place transportation inferring of segments


Instruction:
Can you generate a brief explanation for the following Python 3 code
def infer_location(
            self,
            location_query,
            max_distance,
            google_key,
            foursquare_client_id,
            foursquare_client_secret,
            limit
        ):
        """In-place location inferring of segments

        Returns:
            This track
        """
        self.segments = [
            segment.infer_location(
                location_query,
                max_distance,
                google_key,
                foursquare_client_id,
                foursquare_client_secret,
                limit
            )
            for segment in self.segments
            ]
        return self

Response:
In - place location inferring of segments
           .


Instruction:
Write a Python 3 function for
converting a track to a JSON serializable format

Response:
def to_json(self):
        """Converts track to a JSON serializable format

        Returns:
            Map with the name, and segments of the track.
        """
        return {
            'name': self.name,
            'segments': [segment.to_json() for segment in self.segments],
            'meta': self.meta
            }


Instruction:
Implement a function in Python 3 to
merge another track with this one and returns the new segment with the new one.

Response:
def merge_and_fit(self, track, pairings):
        """ Merges another track with this one, ordering the points based on a
            distance heuristic

        Args:
            track (:obj:`Track`): Track to merge with
            pairings
        Returns:
            :obj:`Segment`: self
        """

        for (self_seg_index, track_seg_index, _) in pairings:
            self_s = self.segments[self_seg_index]
            ss_start = self_s.points[0]
            track_s = track.segments[track_seg_index]
            tt_start = track_s.points[0]
            tt_end = track_s.points[-1]

            d_start = ss_start.distance(tt_start)
            d_end = ss_start.distance(tt_end)

            if d_start > d_end:
                track_s = track_s.copy()
                track_s.points = list(reversed(track_s.points))

            self_s.merge_and_fit(track_s)
        return self


Instruction:
Write a Python 3 script for
getting the index of the closest point in that segment and returns the segment id and point index.

Response:
def get_point_index(self, point):
        """ Gets of the closest first point

        Args:
            point (:obj:`Point`)
        Returns:
            (int, int): Segment id and point index in that segment
        """
        for i, segment in enumerate(self.segments):
            idx = segment.getPointIndex(point)
            if idx != -1:
                return i, idx
        return -1, -1


Instruction:
Can you implement a function in Python 3 that
gets the bounds of the segment holding the current entry.

Response:
def bounds(self, thr=0):
        """ Gets the bounds of this segment

        Returns:
            (float, float, float, float): Bounds, with min latitude, min longitude,
                max latitude and max longitude
        """
        min_lat = float("inf")
        min_lon = float("inf")
        max_lat = -float("inf")
        max_lon = -float("inf")
        for segment in self.segments:
            milat, milon, malat, malon = segment.bounds(thr=thr)
            min_lat = min(milat, min_lat)
            min_lon = min(milon, min_lon)
            max_lat = max(malat, max_lat)
            max_lon = max(malon, max_lon)
        return min_lat, min_lon, max_lat, max_lon


Instruction:
Can you tell what is the following Python 3 function doing
def similarity(self, track):
        idx = index.Index()
        i = 0
        for i, segment in enumerate(self.segments):
            idx.insert(i, segment.bounds(), obj=segment)

        final_siml = []
        final_diff = []
        for i, segment in enumerate(track.segments):
            query = idx.intersection(segment.bounds(), objects=True)

            res_siml = []
            res_diff = []
            for result in query:
                siml, diff = segment_similarity(segment, result.object)
                res_siml.append(siml)
                res_diff.append((result.id, i, diff))

            if len(res_siml) > 0:
                final_siml.append(max(res_siml))
                final_diff.append(res_diff[np.argmax(res_siml)])
            else:
                final_siml.append(0)
                final_diff.append([])

        return np.mean(final_siml), final_diff

Response: Compares two tracks based on their topology and returns the global similarity between the two tracks.


Instruction:
How would you explain what the following Python 3 function does
def to_gpx(self):
        gpx_segments = []
        for segment in self.segments:
            gpx_points = []
            for point in segment.points:
                time = ''
                if point.time:
                    iso_time = point.time.isoformat().split('.')[0]
                    time = '<time>%s</time>' % iso_time
                gpx_points.append(
                    u'<trkpt lat="%f" lon="%f">%s</trkpt>' % (point.lat, point.lon, time)
                )
            points = u'\n\t\t\t'.join(gpx_points)
            gpx_segments.append(u'\t\t<trkseg>\n\t\t\t%s\n\t\t</trkseg>' % points)
        segments = u'\t\n'.join(gpx_segments)
        content = [
            u'<?xml version="1.0" encoding="UTF-8"?>',
            u'<gpx xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.topografix.com/GPX/1/0" xsi:schemaLocation="http://www.topografix.com/GPX/1/0 http://www.topografix.com/GPX/1/0/gpx.xsd" version="1.0" creator="GatherMySteps">',
            u'\t<trk>',
            segments,
            u'\t</trk>',
            u'</gpx>'
        ]

        return u'\n'.join(content)

Response: Converts the track to a GPX format


Instruction:
How would you code a function in Python 3 to
set the timezone of the entire track

Response:
def timezone(self, timezone=0):
        """ Sets the timezone of the entire track

        Args:
            timezone (int): Timezone hour delta

        """
        tz_dt = timedelta(hours=timezone)
        for segment in self.segments:
            for point in segment.points:
                point.time = point.time + tz_dt
        return self


Instruction:
Write a Python 3 script for
converting the track to LIFE format

Response:
def to_life(self):
        """Converts track to LIFE format
        """
        buff = "--%s\n" % self.segments[0].points[0].time.strftime("%Y_%m_%d")
        # buff += "--" + day
        # buff += "UTC+s" # if needed

        def military_time(time):
            """ Converts time to military time

            Args:
                time (:obj:`datetime.datetime`)
            Returns:
                str: Time in the format 1245 (12 hours and 45 minutes)
            """
            return time.strftime("%H%M")

        def stay(buff, start, end, place):
            """ Creates a stay representation

            Args:
                start (:obj:`datetime.datetime` or str)
                end (:obj:`datetime.datetime` or str)
                place (:obj:`Location`)
            Returns:
                str
            """
            if not isinstance(start, str):
                start = military_time(start)
            if not isinstance(end, str):
                end = military_time(end)

            return "%s\n%s-%s: %s" % (buff, start, end, place.label)

        def trip(buff, segment):
            """ Creates a trip representation

            Args:
                buff (str): buffer
                segment (:obj:`Segment`)
            Returns:
                str: buffer and trip representation
            """
            trip = "%s-%s: %s -> %s" % (
                military_time(segment.points[0].time),
                military_time(segment.points[-1].time),
                segment.location_from.label,
                segment.location_to.label
            )

            t_modes = segment.transportation_modes
            if len(t_modes) == 1:
                trip = "%s [%s]" % (trip, t_modes[0]['label'])
            elif len(t_modes) > 1:
                modes = []
                for mode in t_modes:
                    trip_from = military_time(segment.points[mode['from']].time)
                    trip_to = military_time(segment.points[mode['to']].time)
                    modes.append("    %s-%s: [%s]" % (trip_from, trip_to, mode['label']))
                trip = "%s\n%s" % (trip, "\n".join(modes))

            return "%s\n%s" % (buff, trip)

        last = len(self.segments) - 1
        for i, segment in enumerate(self.segments):
            if i == 0:
                buff = stay(
                    buff,
                    "0000",
                    military_time(segment.points[0].time),
                    segment.location_from
                )
            buff = trip(buff, segment)
            if i is last:
                buff = stay(
                    buff,
                    military_time(segment.points[-1].time),
                    "2359",
                    segment.location_to
                )
            else:
                next_seg = self.segments[i+1]
                buff = stay(
                    buff,
                    military_time(segment.points[-1].time),
                    military_time(next_seg.points[0].time),
                    segment.location_to
                )

        return buff


Instruction:
Make a summary of the following Python 3 code
def from_gpx(file_path):
        gpx = gpxpy.parse(open(file_path, 'r'))
        file_name = basename(file_path)

        tracks = []
        for i, track in enumerate(gpx.tracks):
            segments = []
            for segment in track.segments:
                segments.append(Segment.from_gpx(segment))

            if len(gpx.tracks) > 1:
                name = file_name + "_" + str(i)
            else:
                name = file_name
            tracks.append(Track(name, segments))

        return tracks

Response: Creates a list of Tracks from a GPX file.


Instruction:
Explain what the following Python 3 code does
def from_json(json):
        segments = [Segment.from_json(s) for s in json['segments']]
        return Track(json['name'], segments).compute_metrics()

Response: Creates a Track instance from a JSON file.


Instruction:
Can you generate the documentation for the following Python 3 function
def normalize(p):
    l = math.sqrt(p[0]**2 + p[1]**2)
    return [0.0, 0.0] if l == 0 else [p[0]/l, p[1]/l]

Response: Normalizes a point to a vector


Instruction:
Write a Python 3 script for
creating a line from two points p1 and p2.

Response:
def line(p1, p2):
    """Creates a line from two points

    From http://stackoverflow.com/a/20679579

    Args:
        p1 ([float, float]): x and y coordinates
        p2 ([float, float]): x and y coordinates
    Returns:
        (float, float, float): x, y and _
    """
    A = (p1[1] - p2[1])
    B = (p2[0] - p1[0])
    C = (p1[0]*p2[1] - p2[0]*p1[1])
    return A, B, -C


Instruction:
Here you have a function in Python 3, explain what it does
def intersection(L1, L2):
    D = L1[0] * L2[1] - L1[1] * L2[0]
    Dx = L1[2] * L2[1] - L1[1] * L2[2]
    Dy = L1[0] * L2[2] - L1[2] * L2[0]
    if D != 0:
        x = Dx / D
        y = Dy / D
        return x, y
    else:
        return False

Response: Intersects two line segments L1 and L2 Returns x y of intersection


Instruction:
Can you generate the documentation for the following Python 3 function
def closest_point(a, b, p):
    ap = [p[0]-a[0], p[1]-a[1]]
    ab = [b[0]-a[0], b[1]-a[1]]
    mag = float(ab[0]**2 + ab[1]**2)
    proj = dot(ap, ab)
    if mag ==0 :
        dist = 0
    else:
        dist = proj / mag
    if dist < 0:
        return [a[0], a[1]]
    elif dist > 1:
        return [b[0], b[1]]
    else:
        return [a[0] + ab[0] * dist, a[1] + ab[1] * dist]

Response: Finds the closest point in a line segment in a line segment.


Instruction:
Can you write a function in Python 3 where it
computes the distance similarity between a line segment and a point.

Response:
def distance_similarity(a, b, p, T=CLOSE_DISTANCE_THRESHOLD):
    """Computes the distance similarity between a line segment
    and a point

    Args:
        a ([float, float]): x and y coordinates. Line start
        b ([float, float]): x and y coordinates. Line end
        p ([float, float]): x and y coordinates. Point to compute the distance
    Returns:
        float: between 0 and 1. Where 1 is very similar and 0 is completely different
    """
    d = distance_to_line(a, b, p)
    r = (-1/float(T)) * abs(d) + 1

    return r if r > 0 else 0


Instruction:
Given the following Python 3 function, write the documentation
def line_distance_similarity(p1a, p1b, p2a, p2b, T=CLOSE_DISTANCE_THRESHOLD):
    d1 = distance_similarity(p1a, p1b, p2a, T=T)
    d2 = distance_similarity(p1a, p1b, p2b, T=T)
    return abs(d1 + d2) * 0.5

Response: Line distance similarity between two line segments p1a and p2a and p2b.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def line_similarity(p1a, p1b, p2a, p2b, T=CLOSE_DISTANCE_THRESHOLD):
    d = line_distance_similarity(p1a, p1b, p2a, p2b, T=T)
    a = abs(angle_similarity(normalize(line(p1a, p1b)), normalize(line(p2a, p2b))))
    return d * a

Response: Similarity between two lines p1a and p2a.


Instruction:
How would you explain what the following Python 3 function does
def bounding_box_from(points, i, i1, thr):
    pi = points[i]
    pi1 = points[i1]

    min_lat = min(pi.lat, pi1.lat)
    min_lon = min(pi.lon, pi1.lon)
    max_lat = max(pi.lat, pi1.lat)
    max_lon = max(pi.lon, pi1.lon)

    return min_lat-thr, min_lon-thr, max_lat+thr, max_lon+thr

Response: Creates a bounding box for a line segment in the array.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def segment_similarity(A, B, T=CLOSE_DISTANCE_THRESHOLD):
    l_a = len(A.points)
    l_b = len(B.points)

    idx = index.Index()
    dex = 0
    for i in range(l_a-1):
        idx.insert(dex, bounding_box_from(A.points, i, i+1, T), obj=[A.points[i], A.points[i+1]])
        dex = dex + 1

    prox_acc = []

    for i in range(l_b-1):
        ti = B.points[i].gen2arr()
        ti1 = B.points[i+1].gen2arr()
        bb = bounding_box_from(B.points, i, i+1, T)
        intersects = idx.intersection(bb, objects=True)
        n_prox = []
        i_prox = 0
        a = 0
        for x in intersects:
            a = a + 1
            pi = x.object[0].gen2arr()
            pi1 = x.object[1].gen2arr()
            prox = line_similarity(ti, ti1, pi, pi1, T)
            i_prox = i_prox + prox
            n_prox.append(prox)

        if a != 0:
            prox_acc.append(i_prox / a)
            # prox_acc.append(max(n_prox))
        else:
            prox_acc.append(0)

    return np.mean(prox_acc), prox_acc

Response: Computes the similarity between two segmentsA and B.


Instruction:
Write a Python 3 function that can
take two line segments and sorts all their points and returns a list of ordered segment points

Response:
def sort_segment_points(Aps, Bps):
    """Takes two line segments and sorts all their points,
    so that they form a continuous path

    Args:
        Aps: Array of tracktotrip.Point
        Bps: Array of tracktotrip.Point
    Returns:
        Array with points ordered
    """
    mid = []
    j = 0
    mid.append(Aps[0])
    for i in range(len(Aps)-1):
        dist = distance_tt_point(Aps[i], Aps[i+1])
        for m in range(j, len(Bps)):
            distm = distance_tt_point(Aps[i], Bps[m])
            if dist > distm:
                direction = dot(normalize(line(Aps[i].gen2arr(), Aps[i+1].gen2arr())), normalize(Bps[m].gen2arr()))
                if direction > 0:
                    j = m + 1
                    mid.append(Bps[m])
                    break

        mid.append(Aps[i+1])
    for m in range(j, len(Bps)):
        mid.append(Bps[m])
    return mid


Instruction:
Explain what the following Python 3 code does
def distance(latitude_1, longitude_1, elevation_1, latitude_2, longitude_2, elevation_2,
             haversine=None):
    """ Distance between two points """

    # If points too distant -- compute haversine distance:
    if haversine or (abs(latitude_1 - latitude_2) > .2 or abs(longitude_1 - longitude_2) > .2):
        return haversine_distance(latitude_1, longitude_1, latitude_2, longitude_2)

    coef = math.cos(latitude_1 / 180. * math.pi)
    #pylint: disable=invalid-name
    x = latitude_1 - latitude_2
    y = (longitude_1 - longitude_2) * coef

    distance_2d = math.sqrt(x * x + y * y) * ONE_DEGREE

    if elevation_1 is None or elevation_2 is None or elevation_1 == elevation_2:
        return distance_2d

    return math.sqrt(distance_2d ** 2 + (elevation_1 - elevation_2) ** 2)

Response: Compute distance between two points


Instruction:
Can you generate the documentation for the following Python 3 function
def distance(self, other):
        return distance(self.lat, self.lon, None, other.lat, other.lon, None)

Response: Distance between two points in km


Instruction:
How would you implement a function in Python 3 that
computes the metrics of this point and updates the dt vel and acc attributes.

Response:
def compute_metrics(self, previous):
        """ Computes the metrics of this point

        Computes and updates the dt, vel and acc attributes.

        Args:
            previous (:obj:`Point`): Point before
        Returns:
            :obj:`Point`: Self
        """
        delta_t = self.time_difference(previous)
        delta_x = self.distance(previous)
        vel = 0
        delta_v = 0
        acc = 0
        if delta_t != 0:
            vel = delta_x/delta_t
            delta_v = vel - previous.vel
            acc = delta_v/delta_t

        self.dt = delta_t
        self.dx = delta_x
        self.acc = acc
        self.vel = vel
        return self


Instruction:
Create a Python 3 function to
create a point from a GPX representation of a point.

Response:
def from_gpx(gpx_track_point):
        """ Creates a point from GPX representation

        Arguments:
            gpx_track_point (:obj:`gpxpy.GPXTrackPoint`)
        Returns:
            :obj:`Point`
        """
        return Point(
            lat=gpx_track_point.latitude,
            lon=gpx_track_point.longitude,
            time=gpx_track_point.time
        )


Instruction:
Given the following Python 3 function, write the documentation
def to_json(self):
        return {
            'lat': self.lat,
            'lon': self.lon,
            'time': self.time.isoformat() if self.time is not None else None
        }

Response: Returns a JSON serializable representation of this instance.


Instruction:
How would you code a function in Python 3 to
create a Point instance from a JSON representation of a single object.

Response:
def from_json(json):
        """ Creates Point instance from JSON representation

        Args:
            json (:obj:`dict`): Must have at least the following keys: lat (float), lon (float),
                time (string in iso format). Example,
                {
                    "lat": 9.3470298,
                    "lon": 3.79274,
                    "time": "2016-07-15T15:27:53.574110"
                }
            json: map representation of Point instance
        Returns:
            :obj:`Point`
        """
        return Point(
            lat=json['lat'],
            lon=json['lon'],
            time=isostr_to_datetime(json['time'])
        )


Instruction:
Can you generate the documentation for the following Python 3 function
def compute_centroid(points):
    lats = [p[1] for p in points]
    lons = [p[0] for p in points]
    return Point(np.mean(lats), np.mean(lons), None)

Response: Computes the centroid of a set of points.


Instruction:
Can you implement a function in Python 3 that
updates the centroid of a location cluster with another point.

Response:
def update_location_centroid(point, cluster, max_distance, min_samples):
    """ Updates the centroid of a location cluster with another point

    Args:
        point (:obj:`Point`): Point to add to the cluster
        cluster (:obj:`list` of :obj:`Point`): Location cluster
        max_distance (float): Max neighbour distance
        min_samples (int): Minimum number of samples
    Returns:
        (:obj:`Point`, :obj:`list` of :obj:`Point`): Tuple with the location centroid
            and new point cluster (given cluster + given point)
    """
    cluster.append(point)
    points = [p.gen2arr() for p in cluster]

    # Estimates the epsilon
    eps = estimate_meters_to_deg(max_distance, precision=6)

    p_cluster = DBSCAN(eps=eps, min_samples=min_samples)
    p_cluster.fit(points)

    clusters = {}
    for i, label in enumerate(p_cluster.labels_):
        if label in clusters.keys():
            clusters[label].append(points[i])
        else:
            clusters[label] = [points[i]]

    centroids = []
    biggest_centroid_l = -float("inf")
    biggest_centroid = None

    for label, n_cluster in clusters.items():
        centroid = compute_centroid(n_cluster)
        centroids.append(centroid)

        if label >= 0 and len(n_cluster) >= biggest_centroid_l:
            biggest_centroid_l = len(n_cluster)
            biggest_centroid = centroid

    if biggest_centroid is None:
        biggest_centroid = compute_centroid(points)

    return biggest_centroid, cluster


Instruction:
Here you have a function in Python 3, explain what it does
def query_foursquare(point, max_distance, client_id, client_secret):
    if not client_id:
        return []
    if not client_secret:
        return []

    if from_cache(FS_CACHE, point, max_distance):
        return from_cache(FS_CACHE, point, max_distance)

    url = FOURSQUARE_URL % (client_id, client_secret, point.lat, point.lon, max_distance)
    req = requests.get(url)

    if req.status_code != 200:
        return []
    response = req.json()

    result = []
    venues = response['response']['venues']

    for venue in venues:
        name = venue['name']
        distance = venue['location']['distance']
        categories = [c['shortName'] for c in venue['categories']]
        result.append({
            'label': name,
            'distance': distance,
            'types': categories,
            'suggestion_type': 'FOURSQUARE'
        })

    # final_results = sorted(result, key=lambda elm: elm['distance'])
    foursquare_insert_cache(point, result)
    return result

Response: Queries Squarespace API for a location.


Instruction:
Can you write a function in Python 3 where it
queries google maps API for a location

Response:
def query_google(point, max_distance, key):
    """ Queries google maps API for a location

    Args:
        point (:obj:`Point`): Point location to query
        max_distance (float): Search radius, in meters
        key (str): Valid google maps api key
    Returns:
        :obj:`list` of :obj:`dict`: List of locations with the following format:
            {
                'label': 'Coffee house',
                'types': 'Commerce',
                'suggestion_type': 'GOOGLE'
            }
    """
    if not key:
        return []

    if from_cache(GG_CACHE, point, max_distance):
        return from_cache(GG_CACHE, point, max_distance)

    req = requests.get(GOOGLE_PLACES_URL % (
        point.lat,
        point.lon,
        max_distance,
        key
    ))

    if req.status_code != 200:
        return []
    response = req.json()
    results = response['results']
    # l = len(results)
    final_results = []
    for local in results:
        final_results.append({
            'label': local['name'],
            'distance': Point(local['geometry']['location']['lat'], local['geometry']['location']['lng'], None).distance(point),
            # 'rank': (l-i)/float(l),
            'types': local['types'],
            'suggestion_type': 'GOOGLE'
            })

    google_insert_cache(point, final_results)
    return final_results


Instruction:
Can you generate a brief explanation for the following Python 3 code
def infer_location(
        point,
        location_query,
        max_distance,
        google_key,
        foursquare_client_id,
        foursquare_client_secret,
        limit
    ):
    """ Infers the semantic location of a (point) place.

    Args:
        points (:obj:`Point`): Point location to infer
        location_query: Function with signature, (:obj:`Point`, int) -> (str, :obj:`Point`, ...)
        max_distance (float): Max distance to a position, in meters
        google_key (str): Valid google maps api key
        foursquare_client_id (str): Valid Foursquare client id
        foursquare_client_secret (str): Valid Foursquare client secret
        limit (int): Results limit
    Returns:
        :obj:`Location`: with top match, and alternatives
    """
    locations = []

    if location_query is not None:
        queried_locations = location_query(point, max_distance)
        for (label, centroid, _) in queried_locations:
            locations.append({
                'label': unicode(label, 'utf-8'),
                'distance': centroid.distance(point),
                # 'centroid': centroid,
                'suggestion_type': 'KB'
                })

    api_locations = []
    if len(locations) <= limit:
        if google_key:
            google_locs = query_google(point, max_distance, google_key)
            api_locations.extend(google_locs)
        if foursquare_client_id and foursquare_client_secret:
            foursquare_locs = query_foursquare(
                point,
                max_distance,
                foursquare_client_id,
                foursquare_client_secret
            )
            api_locations.extend(foursquare_locs)

    if len(locations) > 0 or len(api_locations) > 0:
        locations = sorted(locations, key=lambda d: d['distance'])
        api_locations = sorted(api_locations, key=lambda d: d['distance'])
        locations = (locations + api_locations)[:limit]
        return Location(locations[0]['label'], point, locations)
    else:
        return Location('#?', point, [])

Response: Infers the semantic location of a point.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def estimate_meters_to_deg(meters, precision=PRECISION_PERSON):
    line = PRECISION_TABLE[precision]
    dec = 1/float(10 ** precision)
    return meters / line[3] * dec

Response: Meters to degrees estimation


Instruction:
Can you generate a brief explanation for the following Python 3 code
def isostr_to_datetime(dt_str):
    if len(dt_str) <= 20:
        return datetime.datetime.strptime(dt_str, "%Y-%m-%dT%H:%M:%SZ")
    else:
        dt_str = dt_str.split(".")
        return isostr_to_datetime("%sZ" % dt_str[0])

Response: Converts an ISO formated text string into a datetime object.


Instruction:
Here you have a function in Python 3, explain what it does
def pairwise(iterable):
    "s -> (s0,s1), (s1,s2), (s2, s3), ..."
    now, nxt = tee(iterable)
    next(nxt, None)
    return izip(now, nxt)

Response: s -> s0 s1 s2 s3...


Instruction:
Create a Python 3 function to
learn new labels, this method is intended for internal use Args: labels (:obj:`list` of :obj:`str`): Labels to learn

Response:
def __learn_labels(self, labels):
        """ Learns new labels, this method is intended for internal use

        Args:
            labels (:obj:`list` of :obj:`str`): Labels to learn
        """
        if self.feature_length > 0:
            result = list(self.labels.classes_)
        else:
            result = []

        for label in labels:
            result.append(label)
        self.labels.fit(result)


Instruction:
Implement a function in Python 3 to
learn the classifier with the given features and labels.

Response:
def learn(self, features, labels):
        """ Fits the classifier

        If it's state is empty, the classifier is fitted, if not
        the classifier is partially fitted.
        See sklearn's SGDClassifier fit and partial_fit methods.

        Args:
            features (:obj:`list` of :obj:`list` of :obj:`float`)
            labels (:obj:`list` of :obj:`str`): Labels for each set of features.
                New features are learnt.
        """
        labels = np.ravel(labels)
        self.__learn_labels(labels)
        if len(labels) == 0:
            return

        labels = self.labels.transform(labels)
        if self.feature_length > 0 and hasattr(self.clf, 'partial_fit'):
            # FIXME? check docs, may need to pass class=[...]
            self.clf = self.clf.partial_fit(features, labels)
        else:
            self.clf = self.clf.fit(features, labels)
            self.feature_length = len(features[0])


Instruction:
Implement a function in Python 3 to
predict the probability of each feature in the set of classes.

Response:
def predict(self, features, verbose=False):
        """ Probability estimates of each feature

        See sklearn's SGDClassifier predict and predict_proba methods.

        Args:
            features (:obj:`list` of :obj:`list` of :obj:`float`)
            verbose: Boolean, optional. If true returns an array where each
                element is a dictionary, where keys are labels and values are
                the respective probabilities. Defaults to False.
        Returns:
            Array of array of numbers, or array of dictionaries if verbose i
            True
        """
        probs = self.clf.predict_proba(features)
        if verbose:
            labels = self.labels.classes_
            res = []
            for prob in probs:
                vals = {}
                for i, val in enumerate(prob):
                    label = labels[i]
                    vals[label] = val
                res.append(vals)
            return res
        else:
            return probs


Instruction:
Explain what the following Python 3 code does
def file_adapter(file_or_path):
    if is_file(file_or_path):
        file_obj = file_or_path
    else:
        file_obj = open(file_or_path, 'rb')
    yield file_obj
    file_obj.close()

Response: Context manager that works similar to open but also accepts already openned file - like objects.


Instruction:
Implement a Python 3 function for
loading source from 3 csv files.

Response:
def source_loader(self, source_paths, create_missing_tables=True):
        """Load source from 3 csv files.

        First file should contain global settings:

        * ``native_lagnauge,languages`` header on first row
        * appropriate values on following rows

        Example::

            native_lagnauge,languages
            ru,ru
              ,en

        Second file should contain templates:

        * ``template_name,probability,genders,template`` header on first row
        * appropriate values on following rows (separate values with semicolon ";" in template column)

        Example::

            template_name,probability,genders,template
            male_1,5,m,prefixes;male_suffixes
            baby_1,1,m;f,prefixes;descriptive

        Third file should contain tables with values for template slugs in all languages:

        * first row should contain slugs with language code after colon for each
        * appropriate values on following rows. Multiple forms may be specified using semicolon as separator

        Example::

            prefixes:ru,prefixes:en,male_suffixes:ru,male_suffixes:en,descriptive:ru,descriptive:en
            Бж,Bzh,пра,pra,быстряк;быстряку,fasty
            дон;дону,don,Иван;Ивану,Ivan,Иванов;Иванову,Ivanov

        Note: you may use slugs without ":lang_code" suffix in csv header of tables file. Such headers will be treated as headers for native language

        If tables are missing for some slug then it is automatically created with values equeal to slug itself.
        So you may use some slugs without specifying tables data for them. Example for apostrophe and space:

            male_1,5,m,prefixes;';male_suffixes
            male_full,5,m,first_name; ;last_name

        """
        if not isinstance(source_paths, Iterable) or len(source_paths) < 3:
            raise TypeError('FromCSVTablesGenerator.source_loader accepts list of 3 paths as argument. Got `%s` instead' % source_paths)
        self.native_language = ''
        self.languages = []
        self.templates = []
        self.tables = {}

        self.load_settings(source_paths[0])
        template_slugs = self.load_templates(source_paths[1])
        self.load_tables(source_paths[2])

        if create_missing_tables:
            self.create_missing_tables(template_slugs)

        self.full_forms_for_languages = set()


Instruction:
Write a Python 3 function that can
load image from URL and preprocess for Resnet.

Response:
def loader():
    """Load image from URL, and preprocess for Resnet."""
    url = request.args.get('url')  # read image URL as a request URL param
    response = requests.get(url)  # make request to static image file
    return response.content


Instruction:
How would you implement a function in Python 3 that
maps prediction tensor to labels.

Response:
def postprocessor(prediction):
    """Map prediction tensor to labels."""
    prediction = prediction.data.numpy()[0]
    top_predictions = prediction.argsort()[-3:][::-1]
    return [labels[prediction] for prediction in top_predictions]


Instruction:
How would you code a function in Python 3 to
get a logger with the specified name.

Response:
def get_logger(name):
    """Get a logger with the specified name."""
    logger = logging.getLogger(name)
    logger.setLevel(getenv('LOGLEVEL', 'INFO'))
    return logger


Instruction:
Write a Python 3 function that can
ensure data is serializable.

Response:
def make_serializable(data):
    """Ensure data is serializable."""
    if is_serializable(data):
        return data

    # if numpy array convert to list
    try:
        return data.tolist()
    except AttributeError:
        pass
    except Exception as e:
        logger.debug('{} exception ({}): {}'.format(type(e).__name__, e, data))

    # try serializing each child element
    if isinstance(data, dict):
        return {key: make_serializable(value) for key, value in data.items()}
    try:
        return [make_serializable(element) for element in data]
    except TypeError:  # not iterable
        pass
    except Exception:
        logger.debug('Could not serialize {}; converting to string'.format(data))

    # last resort: convert to string
    return str(data)


Instruction:
Write a Python 3 script for
loading data from JSON request and convert to numpy array.

Response:
def json_numpy_loader():
    """Load data from JSON request and convert to numpy array."""
    data = request.get_json()
    logger.debug('Received JSON data of length {:,}'.format(len(data)))
    return data


Instruction:
Can you generate a brief explanation for the following Python 3 code
def get_bytes_to_image_callback(image_dims=(224, 224)):
    from keras.preprocessing import image
    import numpy as np
    from PIL import Image
    from io import BytesIO

    def preprocess_image_bytes(data_bytes):
        """Process image bytes for ImageNet."""
        try:
            img = Image.open(BytesIO(data_bytes))  # open image
        except OSError as e:
            raise ValueError('Please provide a raw image')
        img = img.resize(image_dims, Image.ANTIALIAS)  # model requires 224x224 pixels
        x = image.img_to_array(img)  # convert image to numpy array
        x = np.expand_dims(x, axis=0)  # model expects dim 0 to be iterable across images
        return x
    return preprocess_image_bytes

Response: Return a callback to process image bytes for ImageNet.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def exception_log_and_respond(exception, logger, message, status_code):
    logger.error(message, exc_info=True)
    return make_response(
        message,
        status_code,
        dict(exception_type=type(exception).__name__, exception_message=str(exception)),
    )

Response: Log an error and send a jsonified response.


Instruction:
Implement a function in Python 3 to
make a jsonified response with specified message and status code.

Response:
def make_response(message, status_code, details=None):
    """Make a jsonified response with specified message and status code."""
    response_body = dict(message=message)
    if details:
        response_body['details'] = details
    response = jsonify(response_body)
    response.status_code = status_code
    return response


Instruction:
Write a Python 3 script for
creating an endpoint to serve predictions from a specific object.

Response:
def _create_prediction_endpoint(
            self,
            to_numpy=True,
            data_loader=json_numpy_loader,
            preprocessor=lambda x: x,
            input_validation=lambda data: (True, None),
            postprocessor=lambda x: x,
            make_serializable_post=True):
        """Create an endpoint to serve predictions.

        Arguments:
            - input_validation (fn): takes a numpy array as input;
                returns True if validation passes and False otherwise
            - data_loader (fn): reads flask request and returns data preprocessed to be
                used in the `predict` method
            - postprocessor (fn): transforms the predictions from the `predict` method
        """
        # copy instance variables to local scope for resource class
        predict = self.predict
        logger = self.app.logger

        # create restful resource
        class Predictions(Resource):
            @staticmethod
            def post():
                # read data from API request
                try:
                    data = data_loader()
                except Exception as e:
                    return exception_log_and_respond(e, logger, 'Unable to fetch data', 400)

                try:
                    if hasattr(preprocessor, '__iter__'):
                        for preprocessor_step in preprocessor:
                            data = preprocessor_step(data)
                    else:
                        data = preprocessor(data)  # preprocess data
                    data = np.array(data) if to_numpy else data  # convert to numpy
                except Exception as e:
                    return exception_log_and_respond(e, logger, 'Could not preprocess data', 400)

                # sanity check using user defined callback (default is no check)
                validation_pass, validation_reason = input_validation(data)
                if not validation_pass:
                    # if validation fails, log the reason code, log the data, and send a 400 response
                    validation_message = 'Input validation failed with reason: {}'.format(validation_reason)
                    logger.error(validation_message)
                    logger.debug('Data: {}'.format(data))
                    return make_response(validation_message, 400)

                try:
                    prediction = predict(data)
                except Exception as e:
                    # log exception and return the message in a 500 response
                    logger.debug('Data: {}'.format(data))
                    return exception_log_and_respond(e, logger, 'Unable to make prediction', 500)
                logger.debug(prediction)
                try:
                    # preprocess data
                    if hasattr(postprocessor, '__iter__'):
                        for postprocessor_step in postprocessor:
                            prediction = postprocessor_step(prediction)
                    else:
                        prediction = postprocessor(prediction)

                    # cast to serializable types
                    if make_serializable_post:
                        return make_serializable(prediction)
                    else:
                        return prediction

                except Exception as e:
                    return exception_log_and_respond(e, logger, 'Postprocessing failed', 500)

        # map resource to endpoint
        self.api.add_resource(Predictions, '/predictions')


Instruction:
Implement a Python 3 function for
creating an endpoint to serve the info data for the given name.

Response:
def create_info_endpoint(self, name, data):
        """Create an endpoint to serve info GET requests."""
        # make sure data is serializable
        data = make_serializable(data)

        # create generic restful resource to serve static JSON data
        class InfoBase(Resource):
            @staticmethod
            def get():
                return data

        def info_factory(name):
            """Return an Info derivative resource."""
            class NewClass(InfoBase):
                pass
            NewClass.__name__ = "{}_{}".format(name, InfoBase.__name__)
            return NewClass

        path = '/info/{}'.format(name)
        self.api.add_resource(info_factory(name), path)
        logger.info('Regestered informational resource to {} (available via GET)'.format(path))
        logger.debug('Endpoint {} will now serve the following static data:\n{}'.format(path, data))


Instruction:
Write a Python 3 script for
creating an endpoint to serve the model info.

Response:
def _create_model_info_endpoint(self, path='/info/model'):
        """Create an endpoint to serve info GET requests."""
        model = self.model

        # parse model details
        model_details = {}
        for key, value in model.__dict__.items():
            model_details[key] = make_serializable(value)

        # create generic restful resource to serve model information as JSON
        class ModelInfo(Resource):
            @staticmethod
            def get():
                return model_details

        self.api.add_resource(ModelInfo, path)
        self.app.logger.info('Regestered informational resource to {} (available via GET)'.format(path))
        self.app.logger.debug('Endpoint {} will now serve the following static data:\n{}'.format(path, model_details))


Instruction:
Write a Python 3 function for
serving predictions as an API endpoint.

Response:
def serve(self, host='127.0.0.1', port=5000):
        """Serve predictions as an API endpoint."""
        from meinheld import server, middleware
        # self.app.run(host=host, port=port)
        server.listen((host, port))
        server.run(middleware.WebSocketMiddleware(self.app))


Instruction:
Can you generate the documentation for the following Python 3 function
def get_model(input_dim):
    model = Sequential()
    model.add(Dense(100, input_dim=input_dim, activation='sigmoid'))
    model.add(Dense(1))
    model.compile(loss='mean_squared_error', optimizer='SGD')
    return model

Response: Create and compile a simple model.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def validator(input_data):
    global data
    # check num dims
    if input_data.ndim != 2:
        return False, 'Data should have two dimensions.'
    # check number of columns
    if input_data.shape[1] != data.data.shape[1]:
        reason = '{} features required, {} features provided'.format(
            data.data.shape[1], input_data.shape[1])
        return False, reason
    # validation passed
    return True, None

Response: Simple model input validator.


Instruction:
Explain what the following Python 3 code does
def read_chd_header(chd_file):

    with open(chd_file, "rb") as f:
        header = {
            "cinefileheader": cine.CINEFILEHEADER(),
            "bitmapinfoheader": cine.BITMAPINFOHEADER(),
            "setup": cine.SETUP(),
        }
        f.readinto(header["cinefileheader"])
        f.readinto(header["bitmapinfoheader"])
        f.readinto(header["setup"])

    return header

Response: read the. chd header file created when Vision Research software saves the images in a file format other than. cine


Instruction:
Given the following Python 3 function, write the documentation
def fetch_list(version=None):

    if version is None:
        versions = short_versions
    else:
        versions = [get_canonical_version(version)]

    for version in versions:

        url = "http://docs.python.org/{}/objects.inv".format(version)

        modules = sorted(
            list(
                fetch_inventory(DummyApp(), "", url).get("py:module").keys()
            )
        )

        with open(os.path.join(list_dir, "{}.txt".format(version)), "w") as f:
            for module in modules:
                f.write(module)
                f.write("\n")

Response: Fetches the list of modules from the given version of Python and writes them to file.


Instruction:
Write a Python 3 function that can
give a version return a list of names of the Python Standard Libraries for that version.

Response:
def stdlib_list(version=None):
    """
    Given a ``version``, return a ``list`` of names of the Python Standard
    Libraries for that version. These names are obtained from the Sphinx inventory
    file (used in :py:mod:`sphinx.ext.intersphinx`).

    :param str|None version: The version (as a string) whose list of libraries you want
    (one of ``"2.6"``, ``"2.7"``, ``"3.2"``, ``"3.3"``, ``"3.4"``, or ``"3.5"``).
    If not specified, the current version of Python will be used.

    :return: A list of standard libraries from the specified version of Python
    :rtype: list
    """

    version = get_canonical_version(version) if version is not None else '.'.join(
        str(x) for x in sys.version_info[:2])

    module_list_file = os.path.join(list_dir, "{}.txt".format(version))

    with open(module_list_file) as f:
        result = [y for y in [x.strip() for x in f.readlines()] if y]

    return result


Instruction:
Can you generate the documentation for the following Python 3 function
def autohash(include=None,                # type: Union[str, Tuple[str]]
             exclude=None,                # type: Union[str, Tuple[str]]
             only_constructor_args=False,  # type: bool
             only_public_fields=False,     # type: bool
             cls=DECORATED
             ):
    """
    A decorator to makes objects of the class implement __hash__, so that they can be used correctly for example in
    sets.

    Parameters allow to customize the list of attributes that are taken into account in the hash.

    :param include: a tuple of explicit attribute names to include (None means all)
    :param exclude: a tuple of explicit attribute names to exclude. In such case, include should be None.
    :param only_constructor_args: if False (default), all fields will be included in the hash, even if they are defined
        in the constructor or dynamically. If True, only constructor arguments will be included in the hash, not any
        other field that would be created in the constructor or dynamically. Please note that this behaviour is the
        opposite from @autodict.
    :param only_public_fields: this parameter is only used when only_constructor_args is set to False. If
        only_public_fields is set to False (default), all fields are used in the hash. Otherwise, class-private fields
        will not be taken into account in the hash. Please note that this behaviour is the opposite from @autodict.
    :return:
    """

    return autohash_decorate(cls, include=include, exclude=exclude, only_constructor_args=only_constructor_args,
                             only_public_fields=only_public_fields)

Response: A function that automatically generates objects of the given class based on the given include and exclude parameters.


Instruction:
Implement a function in Python 3 to
execute autohash on a class.

Response:
def _execute_autohash_on_class(object_type,                  # type: Type[T]
                               include=None,                 # type: Union[str, Tuple[str]]
                               exclude=None,                 # type: Union[str, Tuple[str]]
                               only_constructor_args=False,  # type: bool
                               only_public_fields=False,     # type: bool
                               ):
    """
    A decorator to make objects of the class implement __hash__, so that they can be used correctly for example in
    sets.

    Parameters allow to customize the list of attributes that are taken into account in the hash.

    :param object_type: the class on which to execute.
    :param include: a tuple of explicit attribute names to include (None means all)
    :param exclude: a tuple of explicit attribute names to exclude. In such case, include should be None.
    :param only_constructor_args: if False (default), all fields will be included in the hash, even if they are defined
    in the constructor or dynamically. If True, only constructor arguments will be included in the hash, not any other
    field that would be created in the constructor or dynamically. Please note that this behaviour is the opposite from
    @autodict.
    :param only_public_fields: this parameter is only used when only_constructor_args is set to False. If
    only_public_fields is set to False (default), all fields are used in the hash. Otherwise, class-private fields will
    not be taken into account in the hash. Please note that this behaviour is the opposite from @autodict.
    :return:
    """
    # First check parameters
    validate_include_exclude(include, exclude)

    # Override hash method if not already implemented
    if not method_already_there(object_type, '__hash__'):
        if only_constructor_args:
            # a. Find the __init__ constructor signature
            constructor = get_constructor(object_type, allow_inheritance=True)
            s = signature(constructor)

            # b. Collect all attributes that are not 'self' and are included and not excluded
            added = []
            # we assume that the order of attributes will always be the same here....
            for attr_name in s.parameters.keys():
                if is_attr_selected(attr_name, include=include, exclude=exclude):
                    added.append(attr_name)

            # c. Finally build the method
            def __hash__(self):
                """
                Generated by @autohash.
                Implements the __hash__ method by hashing a tuple of selected attributes
                :param self:
                :return:
                """
                # note: we prepend a unique hash for the class  > NO, it is more intuitive to not do that.
                # return hash(tuple([type(self)] + [getattr(self, att_name) for att_name in added]))
                return hash(tuple(getattr(self, att_name) for att_name in added))

        else:
            # ** all dynamic fields are allowed
            if include is None and exclude is None and not only_public_fields:

                # easy: all of vars values is included in the hash
                def __hash__(self):
                    """
                    Generated by @autohash.
                    Implements the __hash__ method by hashing vars(self).values()
                    :param self:
                    :return:
                    """
                    # note: we prepend a unique hash for the class  > NO, it is more intuitive to not do that.
                    # return hash(tuple([type(self)] + list(vars(self).values())))
                    return hash(tuple(vars(self).values()))

            else:
                # harder: dynamic filters
                # private_name_prefix = '_' + object_type.__name__ + '_'
                private_name_prefix = '_'

                def __hash__(self):
                    """
                    Generated by @autohash.
                    Implements the __hash__ method by hashing the tuple of included/not excluded field values, possibly
                    not including the private fields if `only_public_fields` was set to True

                    :param self:
                    :return:
                    """
                    # note: we prepend a unique hash for the class > NO, it is more intuitive to not do that.
                    # to_hash = [type(self)]
                    to_hash = []

                    for att_name, att_value in vars(self).items():
                        att_name = possibly_replace_with_property_name(self.__class__, att_name)
                        if is_attr_selected(att_name, include=include, exclude=exclude):
                            if not only_public_fields \
                                    or (only_public_fields and not att_name.startswith(private_name_prefix)):
                                to_hash.append(att_value)

                    return hash(tuple(to_hash))

        # now set the method on the class
        object_type.__hash__ = __hash__

    return


Instruction:
Can you generate a brief explanation for the following Python 3 code
def autodict(include=None,                # type: Union[str, Tuple[str]]
             exclude=None,                # type: Union[str, Tuple[str]]
             only_constructor_args=True,  # type: bool
             only_public_fields=True,     # type: bool
             cls=DECORATED
             ):
    """
    A decorator to makes objects of the class behave like a read-only `dict`. It does several things:
    * it adds collections.Mapping to the list of parent classes (i.e. to the class' `__bases__`)
    * it generates `__len__`, `__iter__` and `__getitem__` in order for the appropriate fields to be exposed in the dict
    view.
    * it adds a static from_dict method to build objects from dicts (only if only_constructor_args=True)
    * it overrides eq method if not already implemented
    * it overrides str and repr method if not already implemented

    Parameters allow to customize the list of fields that will be visible.

    :param include: a tuple of explicit attribute names to include (None means all)
    :param exclude: a tuple of explicit attribute names to exclude. In such case, include should be None.
    :param only_constructor_args: if True (default), only constructor arguments will be exposed through the dictionary
        view, not any other field that would be created in the constructor or dynamically. This makes it very convenient
        to use in combination with @autoargs. If set to False, the dictionary is a direct view of public object fields.
    :param only_public_fields: this parameter is only used when only_constructor_args is set to False. If
        only_public_fields is set to False, all fields are visible. Otherwise (default), class-private fields will be
        hidden
    :return:
    """
    return autodict_decorate(cls, include=include, exclude=exclude, only_constructor_args=only_constructor_args,
                             only_public_fields=only_public_fields)

Response: A class decorator that creates a dictionary of the given class.


Instruction:
Make a summary of the following Python 3 code
def autodict_decorate(cls,                         # type: Type[T]
                      include=None,                # type: Union[str, Tuple[str]]
                      exclude=None,                # type: Union[str, Tuple[str]]
                      only_constructor_args=True,  # type: bool
                      only_public_fields=True      # type: bool
                      ):
    # type: (...) -> Type[T]
    """
    To automatically generate the appropriate methods so that objects of this class behave like a `dict`,
    manually, without using @autodict decorator.

    :param cls: the class on which to execute. Note that it won't be wrapped.
    :param include: a tuple of explicit attribute names to include (None means all)
    :param exclude: a tuple of explicit attribute names to exclude. In such case, include should be None.
    :param only_constructor_args: if True (default), only constructor arguments will be exposed through the dictionary
    view, not any other field that would be created in the constructor or dynamically. This makes it very convenient
    to use in combination with @autoargs. If set to False, the dictionary is a direct view of public object fields.
    :param only_public_fields: this parameter is only used when only_constructor_args is set to False. If
    only_public_fields is set to False, all fields are visible. Otherwise (default), class-private fields will be hidden
    :return:
    """

    # first check that we do not conflict with other known decorators
    _check_known_decorators(cls, '@autodict')

    # perform the class mod
    _execute_autodict_on_class(cls, include=include, exclude=exclude, only_constructor_args=only_constructor_args,
                               only_public_fields=only_public_fields)

    return cls

Response: A decorator that automatically generates the appropriate methods for a dictionary object.


Instruction:
Implement a Python 3 function for
using to decorate a function as an overridden dictionary method (such as __iter__), without using the @autodict_override annotation. :param func: the function on which to execute. Note that it won't be wrapped but simply annotated. :return:

Response:
def autodict_override_decorate(func  # type: Callable
                               ):
    # type: (...) -> Callable
    """
    Used to decorate a function as an overridden dictionary method (such as __iter__), without using the
    @autodict_override annotation.

    :param func: the function on which to execute. Note that it won't be wrapped but simply annotated.
    :return:
    """

    if func.__name__ not in {Mapping.__iter__.__name__, Mapping.__getitem__.__name__, Mapping.__len__.__name__}:
        raise ValueError('@autodict_override can only be used on one of the three Mapping methods __iter__,'
                         '__getitem__ and __len__. Found: ' + func.__name__)

    # Simply annotate the function
    if hasattr(func, __AUTODICT_OVERRIDE_ANNOTATION):
        raise DuplicateOverrideError('Function is overridden twice : ' + func.__name__)
    else:
        setattr(func, __AUTODICT_OVERRIDE_ANNOTATION, True)

    return func


Instruction:
Given the following Python 3 function, write the documentation
def map_values(f, D):
    '''Map each value in the dictionary D to f(value).'''
    return { key:f(val) for key,val in D.iteritems() }

Response: Map each value in the dictionary D to f.


Instruction:
How would you implement a function in Python 3 that
produces a representation using the default repr regardless of whether the object provides an implementation of its own.

Response:
def raw_repr(obj):
    '''Produce a representation using the default repr() regardless of
    whether the object provides an implementation of its own.'''
    if isproxy(obj):
        return '<%s with prime_id=%d>' % (obj.__class__.__name__, obj.prime_id)
    else:
        return repr(obj)


Instruction:
Explain what the following Python 3 code does
def _load_module(module_name, path):
    '''A helper function invoked on the server to tell it to import a module.'''
    # TODO: handle the case that the module is already loaded
    try:
        # First try to find a non-builtin, non-frozen, non-special
        # module using the client's search path
        fd, filename, info = imp.find_module(module_name, path)
    except ImportError:
        # The above will fail for builtin, frozen, or special
        # modules. We search for those now...
        fd, filename, info = imp.find_module(module_name)

    # Now import the module given the info found above
    try:
        return imp.load_module(module_name, fd, filename, info)
    finally:
        if fd is not None:
            fd.close()

Response: A helper function invoked on the server to tell it to import a module.


Instruction:
Here you have a function in Python 3, explain what it does
def byvalue(proxy):
    '''Return a copy of the underlying object for which the argument
    is a proxy.'''
    assert isinstance(proxy, Proxy)
    return proxy.client.execute(ByValueDelegate(proxy))

Response:
Return a copy of the underlying object for which the argument
    is a proxy.


Instruction:
How would you explain what the following Python 3 function does
def import_isolated(module_name, fromlist=[], level=-1, path=None):
    '''Import an module into an isolated context as if with
    "__import__('module_name')"'''
    sys.modules[module_name] = load_module(module_name, path=path)
    return __import__(module_name, fromlist=fromlist, level=level)

Response:
Import an isolated module into an isolated context as if with
    "__import__('module_name')"


Instruction:
Can you generate a brief explanation for the following Python 3 code
def state(self, state):
        '''Change the state of the client. This is one of the values
        defined in ClientStates.'''
        logger.debug('client changing to state=%s', ClientState.Names[state])
        self._state = state

Response:
Change the state of the client. This is one of the values
        defined in ClientStates.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def _read_result(self, num_retries):
        '''Read an object from a channel, possibly retrying if the attempt
        is interrupted by a signal from the operating system.'''
        for i in range(num_retries):
            self._assert_alive()
            try:
                return self._result_channel.get()
            except IOError as ex:
                if ex.errno == 4:
                    # errno=4 corresponds to "System call interrupted",
                    # which means a signal was recieved before any data
                    # was sent. For now I think it's safe to ignore this
                    # and continue.
                    logger.exception('attempt to read from channel was interrupted by something')
                    sys.exc_clear()
                else:
                    # Something else went wrong - raise the exception as usual
                    raise ex

        raise ChannelError('failed to read from channel after %d retries' % num_retries)

Response:
Read an object from a channel possibly retrying if the attempt
        is interrupted by a signal from the operating system.


Instruction:
Explain what the following Python 3 code does
def terminate(self):
        '''Stop the server process and change our state to TERMINATING. Only valid if state=READY.'''
        logger.debug('client.terminate() called (state=%s)', self.strstate)
        if self.state == ClientState.WAITING_FOR_RESULT:
            raise ClientStateError('terimate() called while state='+self.strstate)
        if self.state == ClientState.TERMINATING:
            raise ClientStateError('terimate() called while state='+self.strstate)
        elif self.state in ClientState.TerminatedSet:
            assert not self._server_process.is_alive()
            return
        elif self.state == ClientState.READY:
            # Check that the process itself is still alive
            self._assert_alive()

            # Make sure the SIGCHLD signal handler doesn't throw any exceptions
            self.state = ClientState.TERMINATING

            # Do not call execute() because that function will check
            # whether the process is alive and throw an exception if not
            # TODO: can the queue itself throw exceptions?
            self._delegate_channel.put(FunctionCallDelegate(_raise_terminate))

            # Wait for acknowledgement
            try:
                self._read_result(num_retries=5)
            except ProcessTerminationError as ex:
                pass
            except ChannelError as ex:
                # Was interrupted five times in a row! Ignore for now
                logger.debug('client failed to read sentinel from channel after 5 retries - will terminate anyway')

            self.state = ClientState.TERMINATED_CLEANLY

Response: Stop the server process and change our state to TERMINATING. Only valid if state = READY.


Instruction:
Write a Python 3 script for
terminating this client if it has not already terminated.

Response:
def cleanup(self):
        '''Terminate this client if it has not already terminated.'''
        if self.state == ClientState.WAITING_FOR_RESULT:
            # There is an ongoing call to execute()
            # Not sure what to do here
            logger.warn('cleanup() called while state is WAITING_FOR_RESULT: ignoring')
        elif self.state == ClientState.TERMINATING:
            # terminate() has been called but we have not recieved SIGCHLD yet
            # Not sure what to do here
            logger.warn('cleanup() called while state is TERMINATING: ignoring')
        elif self.state in ClientState.TerminatedSet:
            # We have already terminated
            # TODO: should we deal with TERMINATED_ASYNC in some special way?
            logger.debug('cleanup() called while state is TERMINATING: nothing needs to be done')
        else:
            logger.debug('cleanup() called while state is %s: attempting to terminate',
                          self.strstate)
            try:
                self.terminate()
            except ProcessTerminationError as ex:
                # Terminate can throw a ProcessTerminationError if the
                # process terminated at some point between the last
                # execute() and the call to terminate()
                # For now we just ignore this.
                pass


Instruction:
Here you have a function in Python 3, explain what it does
def start(self):
        '''Create a process in which the isolated code will be run.'''
        assert self._client is None

        logger.debug('IsolationContext[%d] starting', id(self))

        # Create the queues
        request_queue = multiprocessing.Queue()
        response_queue = multiprocessing.Queue()

        # Launch the server process
        server = Server(request_queue, response_queue)  # Do not keep a reference to this object!
        server_process = multiprocessing.Process(target=server.loop)
        server_process.start()

        # Create a client to talk to the server
        self._client = Client(server_process, request_queue, response_queue)

Response: Create a process in which the isolated code will be run.


Instruction:
Write a Python 3 script to
import a module into this isolation context and return a proxy for it.

Response:
def load_module(self, module_name, path=None):
        '''Import a module into this isolation context and return a proxy for it.'''
        self.ensure_started()
        if path is None:
            path = sys.path
        mod = self.client.call(_load_module, module_name, path)
        mod.__isolation_context__ = self
        return mod


Instruction:
Write a Python 3 function for
downloading the badge corresponding to the provided success percentage from the shields. io.

Response:
def download_badge(test_stats,                  # type: TestStats
                   dest_folder='reports/junit'  # type: str
                   ):
    """
    Downloads the badge corresponding to the provided success percentage, from https://img.shields.io.

    :param test_stats:
    :param dest_folder:
    :return:
    """
    if not path.exists(dest_folder):
        makedirs(dest_folder)  # , exist_ok=True) not python 2 compliant

    if test_stats.success_percentage < 50:
        color = 'red'
    elif test_stats.success_percentage < 75:
        color = 'orange'
    elif test_stats.success_percentage < 90:
        color = 'green'
    else:
        color = 'brightgreen'

    left_txt = "tests"
    # right_txt = "%s%%" % test_stats.success_percentage
    right_txt = "%s/%s" % (test_stats.success, test_stats.runned)
    url = 'https://img.shields.io/badge/%s-%s-%s.svg' % (left_txt, quote_plus(right_txt), color)

    dest_file = path.join(dest_folder, 'junit-badge.svg')

    print('Generating junit badge from : ' + url)
    response = requests.get(url, stream=True)
    with open(dest_file, 'wb') as out_file:
        response.raw.decode_content = True
        shutil.copyfileobj(response.raw, out_file)
    del response


Instruction:
Can you tell what is the following Python 3 function doing
def autoprops_decorate(cls,           # type: Type[T]
                       include=None,  # type: Union[str, Tuple[str]]
                       exclude=None   # type: Union[str, Tuple[str]]
                       ):
    # type: (...) -> Type[T]
    """
    To automatically generate all properties getters and setters from the class constructor manually, without using
    @autoprops decorator.
    * if a @contract annotation exist on the __init__ method, mentioning a contract for a given parameter, the
    parameter contract will be added on the generated setter method
    * The user may override the generated getter and/or setter by creating them explicitly in the class and annotating
    them with @getter_override or @setter_override. Note that the contract will still be dynamically added on the
    setter, even if the setter already has one (in such case a `UserWarning` will be issued)

    :param cls: the class on which to execute. Note that it won't be wrapped.
    :param include: a tuple of explicit attribute names to include (None means all)
    :param exclude: a tuple of explicit attribute names to exclude. In such case, include should be None.
    :return:
    """

    # first check that we do not conflict with other known decorators
    _check_known_decorators(cls, '@autoprops')

    # perform the class mod
    _execute_autoprops_on_class(cls, include=include, exclude=exclude)

    # TODO better create a wrapper than modify the class? Probably not
    # class Autoprops_Wrapper(object):
    #     def __init__(self, *args, **kwargs):
    #         self.wrapped = cls(*args, **kwargs)
    #
    # return Autoprops_Wrapper

    return cls

Response: Decorator to automatically generate all properties getters and setters from the class constructor.


Instruction:
How would you implement a function in Python 3 that
executes autoprops on the object_type.

Response:
def _execute_autoprops_on_class(object_type,   # type: Type[T]
                                include=None,  # type: Union[str, Tuple[str]]
                                exclude=None   # type: Union[str, Tuple[str]]
                                ):
    """
    This method will automatically add one getter and one setter for each constructor argument, except for those
    overridden using autoprops_override_decorate(), @getter_override or @setter_override.
    It will add a @contract on top of all setters (generated or overridden, if they don't already have one)

    :param object_type: the class on which to execute.
    :param include: a tuple of explicit attribute names to include (None means all)
    :param exclude: a tuple of explicit attribute names to exclude. In such case, include should be None.
    :return:
    """
    # 0. first check parameters
    validate_include_exclude(include, exclude)

    # 1. Find the __init__ constructor signature and possible pycontracts @contract
    constructor = get_constructor(object_type, allow_inheritance=True)
    s = signature(constructor)

    # option a) pycontracts
    contracts_dict = constructor.__contracts__ if hasattr(constructor, '__contracts__') else {}
    # option b) valid8
    validators_dict = constructor.__validators__ if hasattr(constructor, '__validators__') else {}

    # 2. For each attribute that is not 'self' and is included and not excluded, add the property
    added = []
    for attr_name in s.parameters.keys():
        if is_attr_selected(attr_name, include=include, exclude=exclude):
            added.append(attr_name)

            # pycontract
            if attr_name in contracts_dict.keys():
                pycontract = contracts_dict[attr_name]
            else:
                pycontract = None

            # valid8 validators: create copies, because we will modify them (changing the validated function ref)
            if attr_name in validators_dict.keys():
                validators = [copy(v) for v in validators_dict[attr_name]]
            else:
                validators = None

            _add_property(object_type, s.parameters[attr_name], pycontract=pycontract, validators=validators)

    # 3. Finally check that there is no overridden setter or getter that does not correspond to an attribute
    extra_overrides = getmembers(object_type, predicate=(lambda fun: callable(fun) and
                                                                     (hasattr(fun, __GETTER_OVERRIDE_ANNOTATION)
                                                                      and getattr(fun, __GETTER_OVERRIDE_ANNOTATION) not in added)
                                                                      or
                                                                     (hasattr(fun, __SETTER_OVERRIDE_ANNOTATION))
                                                                      and getattr(fun, __SETTER_OVERRIDE_ANNOTATION) not in added)
                                 )
    if len(extra_overrides) > 0:
        raise AttributeError('Attribute named \'' + extra_overrides[0][0] + '\' was not found in constructor signature.'
                             'Therefore its getter/setter can not be overridden by function '
                             + extra_overrides[0][1].__qualname__)


Instruction:
Can you tell what is the following Python 3 function doing
def _add_property(object_type,      # type: Type[T]
                  parameter,        # type: Parameter
                  pycontract=None,  # type: Any
                  validators=None   # type: Any
                  ):
    """
    A method to dynamically add a property to a class with the optional given pycontract or validators.
    If the property getter and/or setter have been overridden, it is taken into account too.

    :param object_type: the class on which to execute.
    :param parameter:
    :param pycontract:
    :param validators:
    :return:
    """
    property_name = parameter.name

    # 1. create the private field name , e.g. '_foobar'
    private_property_name = '_' + property_name

    # 2. property getter (@property) - create or use overridden
    getter_fun = _get_getter_fun(object_type, parameter, private_property_name)

    # 3. property setter (@property_name.setter) - create or use overridden
    setter_fun, var_name = _get_setter_fun(object_type, parameter, private_property_name)

    # 4. add the contract to the setter, if any
    setter_fun_with_possible_contract = setter_fun
    if pycontract is not None:
        setter_fun_with_possible_contract = _add_contract_to_setter(setter_fun, var_name, pycontract,
                                                                    property_name)
    elif validators is not None:
        setter_fun_with_possible_contract = _add_validators_to_setter(setter_fun, var_name, validators,
                                                                      property_name)

    # 5. change the function name to make it look nice
    setter_fun_with_possible_contract.__name__ = property_name
    setter_fun_with_possible_contract.__module__ = object_type.__module__
    setter_fun_with_possible_contract.__qualname__ = object_type.__name__ + '.' + property_name
    # __annotations__
    # __doc__
    # __dict__

    # 6. Finally add the property to the class
    # WARNING : property_obj.setter(f) does absolutely nothing :) > we have to assign the result
    # setattr(object_type, property_name, property_obj.setter(f))
    new_prop = property(fget=getter_fun, fset=setter_fun_with_possible_contract)

    # # specific for enforce: here we might wrap the overriden property setter on which enforce has already written
    # # something.
    # if hasattr(setter_fun_with_possible_contract, '__enforcer__'):
    #     new_prop.__enforcer__ = setter_fun_with_possible_contract.__enforcer__
    # DESIGN DECISION > although this would probably work, it is probably better to 'force' users to always use the
    # @autoprops annotation BEFORE any other annotation. This is now done in autoprops_decorate

    setattr(object_type, property_name, new_prop)

Response: A method to dynamically add a property to a class.


Instruction:
How would you code a function in Python 3 to
return a function that can be used as a predicate in get_members that returns true if the function has the correct annotation with value.

Response:
def _has_annotation(annotation, value):
    """ Returns a function that can be used as a predicate in get_members, that  """

    def matches_property_name(fun):
        """ return true if fun is a callable that has the correct annotation with value """
        return callable(fun) and hasattr(fun, annotation) \
               and getattr(fun, annotation) is value
    return matches_property_name


Instruction:
How would you explain what the following Python 3 function does
def _get_getter_fun(object_type,           # type: Type
                    parameter,             # type: Parameter
                    private_property_name  # type: str
                    ):
    """
    Utility method to find the overridden getter function for a given property, or generate a new one

    :param object_type:
    :param property_name:
    :param private_property_name:
    :return:
    """

    property_name = parameter.name

    # -- check overridden getter for this property name
    overridden_getters = getmembers(object_type, predicate=_has_annotation(__GETTER_OVERRIDE_ANNOTATION, property_name))

    if len(overridden_getters) > 0:
        if len(overridden_getters) > 1:
            raise DuplicateOverrideError('Getter is overridden more than once for attribute name : ' + property_name)

        # --use the overridden getter
        getter_fun = overridden_getters[0][1]

        # --check its signature
        s = signature(getter_fun)
        if not ('self' in s.parameters.keys() and len(s.parameters.keys()) == 1):
            raise IllegalGetterSignatureException('overridden getter must only have a self parameter, found ' +
                                                  str(len(s.parameters.items()) - 1) + ' for function ' + str(
                getter_fun.__qualname__))

        # --use the overridden getter ?
        property_obj = property(getter_fun)
    else:
        # -- generate the getter :
        def autoprops_generated_getter(self):
            return getattr(self, private_property_name)

        # -- use the generated getter
        getter_fun = autoprops_generated_getter

        try:
            annotations = getter_fun.__annotations__
        except AttributeError:
            # python 2
            pass
        else:
            annotations['return'] = parameter.annotation  # add type hint to output declaration

    return getter_fun

Response: Returns the overridden getter function for a given property.


Instruction:
Can you tell what is the following Python 3 function doing
def _get_setter_fun(object_type,           # type: Type
                    parameter,             # type: Parameter
                    private_property_name  # type: str
                    ):
    """
    Utility method to find the overridden setter function for a given property, or generate a new one

    :param object_type:
    :param property_name:
    :param property_type:
    :param private_property_name:
    :return:
    """
    # the property will have the same name than the constructor argument
    property_name = parameter.name

    overridden_setters = getmembers(object_type, _has_annotation(__SETTER_OVERRIDE_ANNOTATION, property_name))

    if len(overridden_setters) > 0:
        # --check that we only have one
        if len(overridden_setters) > 1:
            raise DuplicateOverrideError('Setter is overridden more than once for attribute name : %s' % property_name)

        # --use the overridden setter
        setter_fun = overridden_setters[0][1]

        try:
            # python 2
            setter_fun = setter_fun.im_func
        except AttributeError:
            pass

        # --find the parameter name and check the signature
        s = signature(setter_fun)
        p = [attribute_name for attribute_name, param in s.parameters.items() if attribute_name is not 'self']
        if len(p) != 1:
            try:
                qname = setter_fun.__qualname__
            except AttributeError:
                qname = setter_fun.__name__
            raise IllegalSetterSignatureException('overridden setter must have only 1 non-self argument, found ' +
                                                  '%s for function %s'
                                                  '' % (len(s.parameters.items()) - 1, qname))
        var_name = p[0]

    else:
        # --create the setter, equivalent of:
        # ** Dynamically compile a wrapper with correct argument name **
        sig = Signature(parameters=[Parameter('self', kind=Parameter.POSITIONAL_OR_KEYWORD), parameter])

        @with_signature(sig)
        def autoprops_generated_setter(self, **kwargs):
            setattr(self, private_property_name, kwargs.popitem()[1])

        setter_fun = autoprops_generated_setter
        var_name = property_name

    return setter_fun, var_name

Response: Returns the overridden setter function for a given property.


Instruction:
Can you generate the documentation for the following Python 3 function
def getter_override(attribute=None,  # type: str
                    f=DECORATED
                    ):
    """
    A decorator to indicate an overridden getter for a given attribute. If the attribute name is None, the function name
    will be used as the attribute name.

    :param attribute: the attribute name for which the decorated function is an overridden getter
    :return:
    """
    return autoprops_override_decorate(f, attribute=attribute, is_getter=True)

Response: A decorator to indicate an overridden getter for a given attribute.


Instruction:
Can you generate the documentation for the following Python 3 function
def setter_override(attribute=None,  # type: str
                    f=DECORATED
                    ):
    """
    A decorator to indicate an overridden setter for a given attribute. If the attribute name is None, the function name
     will be used as the attribute name. The @contract will still be dynamically added.

    :param attribute: the attribute name for which the decorated function is an overridden setter
    :return:
    """
    return autoprops_override_decorate(f, attribute=attribute, is_getter=False)

Response: A decorator to indicate an overridden setter for a given attribute.


Instruction:
Create a Python 3 function to
use to decorate a function as an overridden getter or setter, without using the @getter_override or @setter_override annotations. If the overridden setter has no @contract, the contract will still be dynamically added. Note: this should be executed BEFORE @autoprops or autoprops_decorate(). :param func: the function on which to execute. Note that it won't be wrapped but simply annotated. :param attribute: the attribute name. If None, the function name will be used :param is_getter: True for a getter override, False for a setter override. :return:

Response:
def autoprops_override_decorate(func,            # type: Callable
                                attribute=None,  # type: str
                                is_getter=True   # type: bool
                                ):
    # type: (...) -> Callable
    """
    Used to decorate a function as an overridden getter or setter, without using the @getter_override or
    @setter_override annotations. If the overridden setter has no @contract, the contract will still be
     dynamically added. Note: this should be executed BEFORE @autoprops or autoprops_decorate().

    :param func: the function on which to execute. Note that it won't be wrapped but simply annotated.
    :param attribute: the attribute name. If None, the function name will be used
    :param is_getter: True for a getter override, False for a setter override.
    :return:
    """

    # Simply annotate the fact that this is a function
    attr_name = attribute or func.__name__
    if is_getter:
        if hasattr(func, __GETTER_OVERRIDE_ANNOTATION):
            raise DuplicateOverrideError('Getter is overridden twice for attribute name : ' + attr_name)
        else:
            # func.__getter_override__ = attr_name
            setattr(func, __GETTER_OVERRIDE_ANNOTATION, attr_name)
    else:
        if hasattr(func, __SETTER_OVERRIDE_ANNOTATION):
            raise DuplicateOverrideError('Setter is overridden twice for attribute name : ' + attr_name)
        else:
            # func.__setter_override__ = attr_name
            setattr(func, __SETTER_OVERRIDE_ANNOTATION, attr_name)

    return func


Instruction:
Can you tell what is the following Python 3 function doing
def create_or_update_release(user, pwd, secret, repo_slug, changelog_file, doc_url, data_file, tag):
    # 1- AUTHENTICATION
    if user is not None and secret is None:
        # using username and password
        # validate('user', user, instance_of=str)
        assert isinstance(user, str)
        # validate('pwd', pwd, instance_of=str)
        assert isinstance(pwd, str)
        g = Github(user, pwd)
    elif user is None and secret is not None:
        # or using an access token
        # validate('secret', secret, instance_of=str)
        assert isinstance(secret, str)
        g = Github(secret)
    else:
        raise ValueError("You should either provide username/password OR an access token")
    click.echo("Logged in as {user_name}".format(user_name=g.get_user()))

    # 2- CHANGELOG VALIDATION
    regex_pattern = "[\s\S]*[\n][#]+[\s]*(?P<title>[\S ]*%s[\S ]*)[\n]+?(?P<body>[\s\S]*?)[\n]*?(\n#|$)" % re.escape(tag)
    changelog_section = re.compile(regex_pattern)
    if changelog_file is not None:
        # validate('changelog_file', changelog_file, custom=os.path.exists,
        #          help_msg="changelog file should be a valid file path")
        assert os.path.exists(changelog_file), "changelog file should be a valid file path"
        with open(changelog_file) as f:
            contents = f.read()

        match = changelog_section.match(contents).groupdict()
        if match is None or len(match) != 2:
            raise ValueError("Unable to find changelog section matching regexp pattern in changelog file.")
        else:
            title = match['title']
            message = match['body']
    else:
        title = tag
        message = ''

    # append footer if doc url is provided
    message += "\n\nSee [documentation page](%s) for details." % doc_url

    # 3- REPOSITORY EXPLORATION
    # validate('repo_slug', repo_slug, instance_of=str, min_len=1, help_msg="repo_slug should be a non-empty string")
    assert isinstance(repo_slug, str) and len(repo_slug) > 0, "repo_slug should be a non-empty string"
    repo = g.get_repo(repo_slug)

    # -- Is there a tag with that name ?
    try:
        tag_ref = repo.get_git_ref("tags/" + tag)
    except UnknownObjectException:
        raise ValueError("No tag with name %s exists in repository %s" % (tag, repo.name))

    # -- Is there already a release with that tag name ?
    click.echo("Checking if release %s already exists in repository %s" % (tag, repo.name))
    try:
        release = repo.get_release(tag)
        if release is not None:
            raise ValueError("Release %s already exists in repository %s. Please set overwrite to True if you wish to "
                             "update the release (Not yet supported)" % (tag, repo.name))
    except UnknownObjectException:
        # Release does not exist: we can safely create it.
        click.echo("Creating release %s on repo: %s" % (tag, repo.name))
        click.echo("Release title: '%s'" % title)
        click.echo("Release message:\n--\n%s\n--\n" % message)
        repo.create_git_release(tag=tag, name=title,
                                message=message,
                                draft=False, prerelease=False)

        # add the asset file if needed
        if data_file is not None:
            release = None
            while release is None:
                release = repo.get_release(tag)
            release.upload_asset(path=data_file, label=path.split(data_file)[1], content_type="application/gzip")

Response: Creates or updates a release corresponding to git tag <TAG.


Instruction:
Given the following Python 3 function, write the documentation
def validate_include_exclude(include, exclude):
    if include is not None and exclude is not None:
        raise ValueError("Only one of 'include' or 'exclude' argument should be provided.")
    validate('include', include, instance_of=(str, Sequence), enforce_not_none=False)
    validate('exclude', exclude, instance_of=(str, Sequence), enforce_not_none=False)

Response: Common validator for include and exclude arguments


Instruction:
Make a summary of the following Python 3 code
def is_attr_selected(attr_name,     # type: str
                     include=None,  # type: Union[str, Tuple[str]]
                     exclude=None   # type: Union[str, Tuple[str]]
                     ):
    """decide whether an action has to be performed on the attribute or not, based on its name"""

    if include is not None and exclude is not None:
        raise ValueError('Only one of \'include\' or \'exclude\' argument should be provided.')

    # win time by not doing this
    # check_var(include, var_name='include', var_types=[str, tuple], enforce_not_none=False)
    # check_var(exclude, var_name='exclude', var_types=[str, tuple], enforce_not_none=False)

    if attr_name is 'self':
        return False
    if exclude and attr_name in exclude:
        return False
    if not include or attr_name in include:
        return True
    else:
        return False

Response: decide whether an action has to be performed on the attribute or not based on its name


Instruction:
Here you have a function in Python 3, explain what it does
def get_constructor(typ,
                    allow_inheritance=False  # type: bool
                    ):
    """
    Utility method to return the unique constructor (__init__) of a type

    :param typ: a type
    :param allow_inheritance: if True, the constructor will be returned even if it is not defined in this class
    (inherited). By default this is set to False: an exception is raised when no constructor is explicitly defined in
    the class
    :return: the found constructor
    """
    if allow_inheritance:
        return typ.__init__
    else:
        # check that the constructor is really defined here
        if '__init__' in typ.__dict__:
            return typ.__init__
        else:
            raise Exception('No explicit constructor was found for class ' + str(typ))

Response:
Utility method to return the unique constructor of a type
WorkItem


Instruction:
Explain what the following Python 3 code does
def _check_known_decorators(typ, calling_decorator  # type: str
                            ):
    # type: (...) -> bool
    """
    Checks that a given type is not already decorated by known decorators that may cause trouble.
    If so, it raises an Exception
    :return:
    """
    for member in typ.__dict__.values():
        if hasattr(member, '__enforcer__'):
            raise AutoclassDecorationException('It seems that @runtime_validation decorator was applied to type <'
                                               + str(typ) + '> BEFORE ' + calling_decorator + '. This is not supported '
                                               'as it may lead to counter-intuitive behaviour, please change the order '
                                               'of the decorators on <' + str(typ) + '>')

Response: Checks that a given type is not already decorated by known decorators.


Instruction:
Given the following Python 3 function, write the documentation
def method_already_there(object_type, method_name, this_class_only=False):
    if this_class_only:
        return method_name in vars(object_type)  # or object_type.__dict__
    else:
        try:
            method = getattr(object_type, method_name)
        except AttributeError:
            return False
        else:
            return method is not None and method is not getattr(object, method_name, None)

Response: Returns True if method_name is already implemented by object_type False otherwise.


Instruction:
Make a summary of the following Python 3 code
def autoargs(include=None,  # type: Union[str, Tuple[str]]
             exclude=None,  # type: Union[str, Tuple[str]]
             f=DECORATED
             ):
    """
    Defines a decorator with parameters, to automatically assign the inputs of a function to self PRIOR to executing
    the function. In other words:

    ```
    @autoargs
    def myfunc(a):
        print('hello')
    ```

    will create the equivalent of

    ```
    def myfunc(a):
        self.a = a
        print('hello')
    ```

    Initial code from http://stackoverflow.com/questions/3652851/what-is-the-best-way-to-do-automatic-attribute-assignment-in-python-and-is-it-a#answer-3653049

    :param include: a tuple of attribute names to include in the auto-assignment. If None, all arguments will be
        included by default
    :param exclude: a tuple of attribute names to exclude from the auto-assignment. In such case, include should be None
    :return:
    """
    return autoargs_decorate(f, include=include, exclude=exclude)

Response: A decorator that automatically assigns the input values of a function to the current object.