Instruction:
Can you create a Python 3 function that
returns True iff self. center. distance ( other. center ) <= self. radius + other. radius

Response:
def doesIntersect(self, other):
        '''
        :param: other - Circle class

        Returns True iff:
          self.center.distance(other.center) <= self.radius+other.radius
        '''

        otherType = type(other)

        if issubclass(otherType, Ellipse):
            distance = self.center.distance(other.center)
            radiisum = self.radius + other.radius
            return distance <= radiisum

        if issubclass(otherType, Line):
            raise NotImplementedError('doesIntersect,other is Line class')

        raise TypeError("unknown type '{t}'".format(t=otherType))


Instruction:
Can you implement a function in Python 3 that
returns a Line normal to this Line.

Response:
def normal(self):
        '''
        :return: Line

        Returns a Line normal (perpendicular) to this Line.
        '''

        d = self.B - self.A

        return Line([-d.y, d.x], [d.y, -d.x])


Instruction:
Explain what the following Python 3 code does
def flip(self):
        '''
        :returns: None

        Swaps the positions of A and B.
        '''
        tmp = self.A.xyz
        self.A = self.B
        self.B = tmp

Response: Flips the positions of A and B.


Instruction:
Create a Python 3 function for
returning True iff self and other are both Line subclasses and Line objects.

Response:
def doesIntersect(self, other):
        '''
        :param: other - Line subclass
        :return: boolean

        Returns True iff:
           ccw(self.A,self.B,other.A) * ccw(self.A,self.B,other.B) <= 0
           and
           ccw(other.A,other.B,self.A) * ccw(other.A,other.B,self.B) <= 0

        '''
        if self.A.ccw(self.B, other.A) * self.A.ccw(self.B, other.B) > 0:
            return False

        if other.A.ccw(other.B, self.A) * other.A.ccw(other.B, self.B) > 0:
            return False

        return True


Instruction:
Create a Python 3 function for
returning the intersection of two Line objects.

Response:
def intersection(self, other):
        '''
        :param: other - Line subclass
        :return: Point subclass

        Returns a Point object with the coordinates of the intersection
        between the current line and the other line.

        Will raise Parallel() if the two lines are parallel.
        Will raise Collinear() if the two lines are collinear.
        '''

        if self.isCollinear(other):
            msg = '{!r} and {!r} are collinear'
            raise CollinearLines(msg.format(self, other))

        d0 = self.A - self.B
        d1 = other.A - other.B

        denominator = (d0.x * d1.y) - (d0.y * d1.x)

        if denominator == 0:
            msg = '{!r} and {!r} are parallel'
            raise ParallelLines(msg.format(self, other))

        cp0 = self.A.cross(self.B)
        cp1 = other.A.cross(other.B)

        x_num = (cp0 * d1.x) - (d0.x * cp1)
        y_num = (cp0 * d1.y) - (d0.y * cp1)

        p = Point(x_num / denominator, y_num / denominator)

        if p in self and p in other:
            return p

        msg = "found point {!r} but not in {!r} and {!r}"
        raise ParallelLines(msg.format(p, self, other))


Instruction:
Implement a Python 3 function for
calculating the distance from the line to the given point.

Response:
def distanceFromPoint(self, point):
        '''
        :param: point - Point subclass
        :return: float

        Distance from the line to the given point.
        '''
        # XXX planar distance, doesn't take into account z ?
        d = self.m
        n = (d.y * point.x) - (d.x * point.y) + self.A.cross(self.B)
        return abs(n / self.A.distance(self.B))


Instruction:
Can you write a function in Python 3 where it
returns the angle measured between two lines in radians

Response:
def radiansBetween(self, other):
        '''
        :param: other - Line subclass
        :return: float

        Returns the angle measured between two lines in radians
        with a range of [0, 2 * math.pi].

        '''
        # a dot b = |a||b| * cos(theta)
        # a dot b / |a||b| = cos(theta)
        # cos-1(a dot b / |a||b|) = theta

        # translate each line so that it passes through the origin and
        # produce a new point whose distance (magnitude) from the
        # origin is 1.
        #

        a = Point.unit(self.A, self.B)
        b = Point.unit(other.A, other.B)

        # in a perfect world, after unit: |A| = |B| = 1
        # which is a noop when dividing the dot product of A,B
        # but sometimes the lengths are different.
        #
        # let's just assume things are perfect and the lengths equal 1.

        return math.acos(a.dot(b))


Instruction:
Explain what the following Python 3 code does
def FloatProperty(name, default=0.0, readonly=False, docs=None):
    '''
    :name: string - property name
    :default: float - property default value
    :readonly: boolean - if True, setter method is NOT generated

    Returns a property object that can be used to initialize a
    class instance variable as a property.
    '''

    private_name = '_' + name

    def getf(self):
        if not hasattr(self, private_name):
            setattr(self, private_name, default)
        return getattr(self, private_name)

    if readonly:
        setf = None
    else:
        def setf(self, newValue):
            def epsilon_set(v):
                # epsilon_set: creates a float from v unless that
                #              float is less than epsilon, which will
                #              be considered effectively zero.
                fv = float(v)
                return 0.0 if nearly_zero(fv) else fv

            try:
                setattr(self, private_name, epsilon_set(newValue))
                return
            except TypeError:
                pass

            if isinstance(newValue, collections.Mapping):
                try:
                    setattr(self, private_name, epsilon_set(newValue[name]))
                except KeyError:
                    pass
                return

            if isinstance(newValue, collections.Iterable):
                try:
                    setattr(self, private_name, epsilon_set(newValue[0]))
                    return
                except (IndexError, TypeError):
                    pass

            try:
                mapping = vars(newValue)
                setattr(self, private_name, epsilon_set(mapping[name]))
                return
            except (TypeError, KeyError):
                pass

            if newValue is None:
                setattr(self, private_name, epsilon_set(default))
                return

            raise ValueError(newValue)

    return property(getf, setf, None, docs)

Response: Returns a property that can be used to initialize a new object variable.


Instruction:
Can you tell what is the following Python 3 function doing
def randomSizeAndLocation(cls, radius, widthLimits,
                              heightLimits, origin=None):
        '''
        :param: radius       - float
        :param: widthLimits  - iterable of floats with length >= 2
        :param: heightLimits - iterable of floats with length >= 2
        :param: origin       - optional Point subclass
        :return: Rectangle
        '''

        r = cls(widthLimits, heightLimits, origin)

        r.origin = Point.randomLocation(radius, origin)

Response: Returns a Rectangle with random size and location.


Instruction:
Make a summary of the following Python 3 code
def randomSize(cls, widthLimits, heightLimits, origin=None):
        '''
        :param: widthLimits  - iterable of integers with length >= 2
        :param: heightLimits - iterable of integers with length >= 2
        :param: origin       - optional Point subclass
        :return: Rectangle
        '''

        r = cls(0, 0, origin)

        r.w = random.randint(widthLimits[0], widthLimits[1])
        r.h = random.randint(heightLimits[0], heightLimits[1])

        return r

Response: Returns a random Rectangle object with width and height limits.


Instruction:
How would you explain what the following Python 3 function does
def randomLocation(cls, radius, width, height, origin=None):
        '''
        :param: radius - float
        :param: width  - float
        :param: height - float
        :param: origin - optional Point subclass
        :return: Rectangle
        '''
        return cls(width,
                   height,
                   Point.randomLocation(radius, origin))

Response: Returns a new Rectangle containing random locations.


Instruction:
Can you implement a function in Python 3 that
returns the origin of the rectangle.

Response:
def origin(self):
        '''
        Point describing the origin of the rectangle. Defaults to (0,0,0).
        '''
        try:
            return self._origin
        except AttributeError:
            pass
        self._origin = Point()
        return self._origin


Instruction:
Can you generate a brief explanation for the following Python 3 code
def B(self):
        '''
        Point whose coordinates are (maxX,minY,origin.z), Point.
        '''
        return Point(self.maxX, self.minY, self.origin.z)

Response: Return a new Point object with the same coordinates as this one.


Instruction:
Write a Python 3 script for
returning a new Point object that is the center of the current point.

Response:
def C(self):
        '''
        Point whose coordinates are (maxX,maxY,origin.z), Point.
        '''
        return Point(self.maxX, self.maxY, self.origin.z)


Instruction:
Create a Python 3 function for
returning the D coordinate of the current Point.

Response:
def D(self):
        '''
        Point whose coordinates are (minX,maxY,origin.Z), Point.
        '''
        return Point(self.minX, self.maxY, self.origin.z)


Instruction:
How would you implement a function in Python 3 that
returns the center of the current Point.

Response:
def center(self):
        '''
        Point whose coordinates are (midX,midY,origin.z), Point.
        '''
        return Point(self.midX, self.midY, self.origin.z)


Instruction:
Can you implement a function in Python 3 that
scales the rectangle s width and height by dx and dy.

Response:
def scale(self, dx=1.0, dy=1.0):
        '''
        :param: dx - optional float
        :param: dy - optional float

        Scales the rectangle's width and height by dx and dy.

        '''
        self.width *= dx
        self.height *= dy


Instruction:
Given the following Python 3 function, write the documentation
def containsPoint(self, point, Zorder=False):
        '''
        :param: point  - Point subclass
        :param: Zorder - optional Boolean

        Is true if the point is contain in the rectangle or
        along the rectangle's edges.

        If Zorder is True, the method will check point.z for
        equality with the rectangle origin's Z coordinate.

        '''
        if not point.isBetweenX(self.A, self.B):
            return False
        if not point.isBetweenY(self.A, self.D):
            return False

        if Zorder:
            return point.z == self.origin.z

        return True

Response: Returns True if the point is contained in the rectangle or False otherwise.


Instruction:
How would you code a function in Python 3 to
return a new Triangle with random coordinates in the circle described by origin and radius.

Response:
def random(cls, origin=None, radius=1):
        '''
        :origin: - optional Point subclass
        :radius: - optional float
        :return: Triangle

        Creates a triangle with random coordinates in the circle
        described by (origin,radius).  If origin is unspecified, (0,0)
        is assumed. If the radius is unspecified, 1.0 is assumed.

        '''
        # XXX no collinearity checks, possible to generate a
        #     line (not likely, just possible).
        #
        pts = set()
        while len(pts) < 3:
            p = Point.random(origin, radius)
            pts.add(p)
        return cls(pts)


Instruction:
Implement a function in Python 3 to
return a new avec triangle initialized with points comprising a equilateral triangle.

Response:
def equilateral(cls, origin=None, side=1):
        '''
        :origin: optional Point
        :side: optional float describing triangle side length
        :return: Triangle initialized with points comprising a
                 equilateral triangle.

        XXX equilateral triangle definition

        '''
        o = Point(origin)

        base = o.x + side
        h = 0.5 * Sqrt_3 * side + o.y

        return cls(o, [base, o.y], [base / 2, h])


Instruction:
Write a Python 3 script for
returning a new isosceles triangle initialized with points comprising a .

Response:
def isosceles(cls, origin=None, base=1, alpha=90):
        '''
        :origin: optional Point
        :base: optional float describing triangle base length
        :return: Triangle initialized with points comprising a
                 isosceles triangle.

        XXX isoceles triangle definition

        '''
        o = Point(origin)
        base = o.x + base

        return cls(o, [base, o.y], [base / 2, o.y + base])


Instruction:
How would you explain what the following Python 3 function does
def C(self):
        '''
        Third vertex of triangle, Point subclass.

        '''
        try:
            return self._C
        except AttributeError:
            pass
        self._C = Point(0, 1)
        return self._C

Response: Return the Third vertex of triangle Point subclass.


Instruction:
Given the following Python 3 function, write the documentation
def AC(self):
        '''
        Vertices A and C, list.

        '''
        try:
            return self._AC
        except AttributeError:
            pass
        self._AC = [self.A, self.C]
        return self._AC

Response: A list of A and C vertices.


Instruction:
Can you tell what is the following Python 3 function doing
def CA(self):
        '''
        Vertices C and A, list.

        '''
        try:
            return self._CA
        except AttributeError:
            pass
        self._CA = [self.C, self.A]
        return self._CA

Response: A list of all possible unique names for the current set of resources.


Instruction:
How would you explain what the following Python 3 function does
def CB(self):
        '''
        Vertices C and B, list.

        '''
        try:
            return self._CB
        except AttributeError:
            pass
        self._CB = [self.C, self.B]
        return self._CB

Response: Returns a list of the n - ary items that are in the order of the two sets.


Instruction:
Can you generate the documentation for the following Python 3 function
def segments(self):
        '''
        A list of the Triangle's line segments [AB, BC, AC], list.

        '''
        return [Segment(self.AB),
                Segment(self.BC),
                Segment(self.AC)]

Response: A list of the Triangle s line segments [ AB BC AC ]


Instruction:
Make a summary of the following Python 3 code
def circumcenter(self):
        '''
        The intersection of the median perpendicular bisectors, Point.

        The center of the circumscribed circle, which is the circle that
        passes through all vertices of the triangle.

        https://en.wikipedia.org/wiki/Circumscribed_circle#Cartesian_coordinates_2

        BUG: only finds the circumcenter in the XY plane
        '''

        if self.isRight:
            return self.hypotenuse.midpoint

        if self.A.isOrigin:
            t = self
        else:
            # translate triangle to origin
            t = Triangle(self.A - self.A, self.B - self.A, self.C - self.A)
            # XXX translation would be easier by defining add and sub for points
            # t = self - self.A

        if not t.A.isOrigin:
            raise ValueError('failed to translate {} to origin'.format(t))

        BmulC = t.B * t.C.yx

        d = 2 * (BmulC.x - BmulC.y)

        bSqSum = sum((t.B ** 2).xy)
        cSqSum = sum((t.C ** 2).xy)

        x = (((t.C.y * bSqSum) - (t.B.y * cSqSum)) / d) + self.A.x
        y = (((t.B.x * cSqSum) - (t.C.x * bSqSum)) / d) + self.A.y

        return Point(x, y)

Response: Return the center of the circumscribed circle.


Instruction:
Implement a function in Python 3 to
true if all sides of the triangle are the same length.

Response:
def isEquilateral(self):
        '''
        True if all sides of the triangle are the same length.

        All equilateral triangles are also isosceles.
        All equilateral triangles are also acute.

        '''
        if not nearly_eq(self.a, self.b):
            return False

        if not nearly_eq(self.b, self.c):
            return False

        return nearly_eq(self.a, self.c)


Instruction:
Create a Python 3 function for
returning a new Triangle with flipped side.

Response:
def swap(self, side='AB', inplace=False):
        '''
        :side: - optional string
        :inplace: - optional boolean
        :return: Triangle with flipped side.

        The optional side paramater should have one of three values:
        AB, BC, or AC.

        Changes the order of the triangle's points, swapping the
        specified points. Doing so will change the results of isCCW
        and ccw.

        '''
        try:
            flipset = {'AB': (self.B.xyz, self.A.xyz, self.C.xyz),
                       'BC': (self.A.xyz, self.C.xyz, self.B.xyz),
                       'AC': (self.C.xyz, self.B.xyz, self.A.xyz)}[side]
        except KeyError as e:
            raise KeyError(str(e))

        if inplace:
            self.ABC = flipset
            return self

        return Triangle(flipset)


Instruction:
Implement a function in Python 3 to
return True iff any of the segments in self intersects any segment in other.

Response:
def doesIntersect(self, other):
        '''
        :param: other - Triangle or Line subclass
        :return: boolean

        Returns True iff:
           Any segment in self intersects any segment in other.

        '''
        otherType = type(other)

        if issubclass(otherType, Triangle):
            for s in self.segments.values():
                for q in other.segments.values():
                    if s.doesIntersect(q):
                        return True
            return False

        if issubclass(otherType, Line):
            for s in self.segments.values():
                if s.doesIntersect(other):
                    return True
            return False

        msg = "expecting Line or Triangle subclasses, got '{}'"

        raise TypeError(msg.format(otherType))


Instruction:
How would you explain what the following Python 3 function does
def perimeter(self):
        '''
        Sum of the length of all sides, float.
        '''
        return sum([a.distance(b) for a, b in self.pairs()])

Response: Returns the total length of all sides of the current set.


Instruction:
Given the following Python 3 function, write the documentation
def vl_dsift(data, fast=False, norm=False, bounds=None, size=3, step=1,
              window_size=None, float_descriptors=False,
              verbose=False, matlab_style=True):
    '''
    Dense sift descriptors from an image.

    Returns:
        frames: num_frames x (2 or 3) matrix of x, y, (norm)
        descrs: num_frames x 128 matrix of descriptors
    '''
    if not matlab_style:
        import warnings
        warnings.warn("matlab_style=False gets different results than matlab, "
                      "not sure why or how incorrect they are.")

    order = 'F' if matlab_style else 'C'
    data = as_float_image(data, dtype=np.float32, order=order)
    if data.ndim != 2:
        raise TypeError("data should be a 2d array")

    if window_size is not None:
        assert np.isscalar(window_size) and window_size >= 0

    # construct the dsift object
    M, N = data.shape
    dsift_p = vl_dsift_new_basic(M, N, step, size)

    try:
        dsift = dsift_p.contents

        # set parameters
        if bounds is not None:
            if matlab_style:
                y0, x0, y1, x1 = bounds  # transposed
            else:
                x0, y0, x1, y1 = bounds
            dsift.boundMinX = int(max(x0, 0))
            dsift.boundMinY = int(max(y0, 0))
            dsift.boundMaxX = int(min(x1, M - 1))
            dsift.boundMaxY = int(min(y1, N - 1))
            _vl_dsift_update_buffers(dsift_p)

        dsift.useFlatWindow = fast

        if window_size is not None:
            dsift.windowSize = window_size

        # get calculated parameters
        descr_size = dsift.descrSize
        num_frames = dsift.numFrames
        geom = dsift.geom

        if verbose:
            pr = lambda *a, **k: print('vl_dsift:', *a, **k)
            pr("image size         [W, H] = [{}, {}]".format(N, M))
            x0 = dsift.boundMinX + 1
            y0 = dsift.boundMinY + 1
            x1 = dsift.boundMaxX + 1
            y1 = dsift.boundMaxY + 1
            bound_args = [y0, x0, y1, x1] if matlab_style else [x0, y0, x1, y1]
            pr("bounds:            [minX,minY,maxX,maxY] = [{}, {}, {}, {}]"
                .format(*bound_args))
            pr("subsampling steps: stepX={}, stepY={}".format(
                    dsift.stepX, dsift.stepY))
            pr("num bins:          [numBinT, numBinX, numBinY] = [{}, {}, {}]"
                .format(geom.numBinT, geom.numBinX, geom.numBinY))
            pr("descriptor size:   {}".format(descr_size))
            pr("bin sizes:         [binSizeX, binSizeY] = [{}, {}]".format(
                    geom.binSizeX, geom.binSizeY))
            pr("flat window:       {}".format(bool(fast)))
            pr("window size:       {}".format(dsift.windowSize))
            pr("num of features:   {}".format(num_frames))

        # do the actual processing
        vl_dsift_process(dsift_p, data)

        # copy frames' locations, norms out
        # the frames are a structure of just 4 doubles (VLDsiftKeypoint),
        # which luckily looks exactly like an array of doubles. :)
        # NOTE: this might be platform/compiler-dependent...but it works with
        #       the provided binaries on os x, at least
        frames_p = cast(dsift.frames, c_double_p)
        frames_p_a = npc.as_array(frames_p, shape=(num_frames, 4))
        cols = [1, 0] if matlab_style else [0, 1]
        if norm:
            cols.append(3)
        frames = np.require(frames_p_a[:, cols], requirements=['C', 'O'])

        # copy descriptors into a new array
        descrs_p = npc.as_array(dsift.descrs, shape=(num_frames, descr_size))
        descrs = descrs_p * 512
        assert descrs.flags.owndata
        np.minimum(descrs, 255, out=descrs)
        if not float_descriptors:
            descrs = descrs.astype(np.uint8)  # TODO: smarter about copying?
        if matlab_style:
            new_order = np.empty(descr_size, dtype=int)
            vl_dsift_transpose_descriptor(new_order, np.arange(descr_size),
                geom.numBinT, geom.numBinX, geom.numBinY)
            descrs = descrs[:, new_order]
        # the old, super-slow way:
        ## # gross pointer arithmetic to get the relevant descriptor
        ## descrs_addr = addressof(descrs.contents)
        ## descrs_step = descr_size * sizeof(c_float)
        ##
        ## for k in range(num_frames):
        ##     out_frames[:2, k] = [frames[k].y + 1, frames[k].x + 1]
        ##     if norm:  # there's an implied / 2 in norm, because of clipping
        ##         out_frames[2, k] = frames[k].norm
        ##
        ##     # gross pointer arithmetic to get the relevant descriptor
        ##     the_descr = cast(descrs_addr + k * descrs_step, c_float_p)
        ##     transposed = vl_dsift_transpose_descriptor(
        ##         the_descr,
        ##         geom.numBinT, geom.numBinX, geom.numBinY)
        ##     out_descrs[:, k] = np.minimum(512. * transposed, 255.)

        return frames, descrs

    finally:
        vl_dsift_delete(dsift_p)

Response: Create a new DSIFT object from an image.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def rgb2gray(img):
    T = np.linalg.inv(np.array([
        [1.0,  0.956,  0.621],
        [1.0, -0.272, -0.647],
        [1.0, -1.106,  1.703],
    ]))
    r_c, g_c, b_c = T[0]
    r, g, b = np.rollaxis(as_float_image(img), axis=-1)
    return r_c * r + g_c * g + b_c * b

Response: Converts an RGB image to grayscale using matlab s algorithm.


Instruction:
Explain what the following Python 3 code does
def rgb2hsv(arr):
    arr = np.asanyarray(arr)
    if arr.ndim != 3 or arr.shape[2] != 3:
        raise ValueError("the input array must have a shape == (.,.,3)")
    arr = as_float_image(arr)

    out = np.empty_like(arr)

    # -- V channel
    out_v = arr.max(-1)

    # -- S channel
    delta = arr.ptp(-1)
    # Ignore warning for zero divided by zero
    old_settings = np.seterr(invalid='ignore')
    out_s = delta / out_v
    out_s[delta == 0.] = 0.

    # -- H channel
    # red is max
    idx = (arr[:, :, 0] == out_v)
    out[idx, 0] = (arr[idx, 1] - arr[idx, 2]) / delta[idx]

    # green is max
    idx = (arr[:, :, 1] == out_v)
    out[idx, 0] = 2. + (arr[idx, 2] - arr[idx, 0]) / delta[idx]

    # blue is max
    idx = (arr[:, :, 2] == out_v)
    out[idx, 0] = 4. + (arr[idx, 0] - arr[idx, 1]) / delta[idx]
    out_h = (out[:, :, 0] / 6.) % 1.
    out_h[delta == 0.] = 0.

    np.seterr(**old_settings)

    # -- output
    out[:, :, 0] = out_h
    out[:, :, 1] = out_s
    out[:, :, 2] = out_v

    # remove NaN
    out[np.isnan(out)] = 0
    return out

Response: Converts an RGB image to HSV using scikit - image s algorithm.


Instruction:
Write a Python 3 function that can
parse an SCI command response into an ElementTree Element

Response:
def _parse_command_response(response):
    """Parse an SCI command response into ElementTree XML

    This is a helper method that takes a Requests Response object
    of an SCI command response and will parse it into an ElementTree Element
    representing the root of the XML response.

    :param response: The requests response object
    :return: An ElementTree Element that is the root of the response XML
    :raises ResponseParseError: If the response XML is not well formed
    """
    try:
        root = ET.fromstring(response.text)
    except ET.ParseError:
        raise ResponseParseError(
            "Unexpected response format, could not parse XML. Response: {}".format(response.text))

    return root


Instruction:
Make a summary of the following Python 3 code
def _parse_error_tree(error):
    errinf = ErrorInfo(error.get('id'), None)
    if error.text is not None:
        errinf.message = error.text
    else:
        desc = error.find('./desc')
        if desc is not None:
            errinf.message = desc.text
    return errinf

Response: Parse an error ElementTree Node to create an ErrorInfo object


Instruction:
Can you tell what is the following Python 3 function doing
def get_data(self):

        target = DeviceTarget(self.device_id)
        return self._fssapi.get_file(target, self.path)[self.device_id]

Response: Get the contents of this file


Instruction:
Can you generate the documentation for the following Python 3 function
def delete(self):
        target = DeviceTarget(self.device_id)
        return self._fssapi.delete_file(target, self.path)[self.device_id]

Response: Delete this file from the device


Instruction:
Implement a Python 3 function for
listing the contents of this directory and return a LsInfo object that contains directories and files that are not yet modified.

Response:
def list_contents(self):
        """List the contents of this directory

        :return: A LsInfo object that contains directories and files
        :rtype: :class:`~.LsInfo` or :class:`~.ErrorInfo`

        Here is an example usage::

            # let dirinfo be a DirectoryInfo object
            ldata = dirinfo.list_contents()
            if isinstance(ldata, ErrorInfo):
                # Do some error handling
                logger.warn("Error listing file info: (%s) %s", ldata.errno, ldata.message)
            # It's of type LsInfo
            else:
                # Look at all the files
                for finfo in ldata.files:
                    logger.info("Found file %s of size %s", finfo.path, finfo.size)
                # Look at all the directories
                for dinfo in ldata.directories:
                    logger.info("Found directory %s of last modified %s", dinfo.path, dinfo.last_modified)
        """
        target = DeviceTarget(self.device_id)
        return self._fssapi.list_files(target, self.path)[self.device_id]


Instruction:
Create a Python 3 function for
parsing the server response for this ls command and return a list of directories and files on the device.

Response:
def parse_response(cls, response, device_id=None, fssapi=None, **kwargs):
        """Parse the server response for this ls command

        This will parse xml of the following form::

            <ls hash="hash_type">
              <file path="file_path" last_modified=last_modified_time ... />
              ...
              <dir path="dir_path" last_modified=last_modified_time />
              ...
            </ls>

        or with an error::

            <ls>
                <error ... />
            </ls>

        :param response: The XML root of the response for an ls command
        :type response: :class:`xml.etree.ElementTree.Element`
        :param device_id: The device id of the device this ls response came from
        :param fssapi: A reference to a :class:`~FileSystemServiceAPI` for use with the
            :class:`~FileInfo` and :class:`~DirectoryInfo` objects for future commands
        :return: An :class:`~LsInfo` object containing the list of directories and files on
            the device or an :class:`~ErrorInfo` if the xml contained an error
        """
        if response.tag != cls.command_name:
            raise ResponseParseError(
                "Received response of type {}, LsCommand can only parse responses of type {}".format(response.tag,
                                                                                cls.command_name))

        if fssapi is None:
            raise FileSystemServiceException("fssapi is required to parse an LsCommand response")
        if device_id is None:
            raise FileSystemServiceException("device_id is required to parse an LsCommand response")

        error = response.find('./error')
        if error is not None:
            return _parse_error_tree(error)

        hash_type = response.get('hash')
        dirs = []
        files = []

        # Get each file listed in this response
        for myfile in response.findall('./file'):
            fi = FileInfo(fssapi,
                          device_id,
                          myfile.get('path'),
                          int(myfile.get('last_modified')),
                          int(myfile.get('size')),
                          myfile.get('hash'),
                          hash_type)
            files.append(fi)
        # Get each directory listed for this device
        for mydir in response.findall('./dir'):
            di = DirectoryInfo(fssapi,
                               device_id,
                               mydir.get('path'),
                               int(mydir.get('last_modified')))
            dirs.append(di)
        return LsInfo(directories=dirs, files=files)


Instruction:
Here you have a function in Python 3, explain what it does
def parse_response(cls, response, **kwargs):
        if response.tag != cls.command_name:
            raise ResponseParseError(
                "Received response of type {}, GetCommand can only parse responses of type {}".format(response.tag,
                                                                                cls.command_name))

        error = response.find('./error')
        if error is not None:
            return _parse_error_tree(error)

        text = response.find('./data').text
        if text:
            return base64.b64decode(six.b(text))
        else:
            return six.b('')

Response: Parse the server response for this get file command


Instruction:
Can you tell what is the following Python 3 function doing
def parse_response(cls, response, **kwargs):
        if response.tag != cls.command_name:
            raise ResponseParseError(
                "Received response of type {}, PutCommand can only parse responses of type {}".format(response.tag,
                                                                                cls.command_name))
        error = response.find('./error')
        if error is not None:
            return _parse_error_tree(error)

        return None

Response: Parse the server response for this put file command and return the corresponding object.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def send_command_block(self, target, command_block):
        root = _parse_command_response(
            self._sci_api.send_sci("file_system", target, command_block.get_command_string()))

        out_dict = {}
        for device in root.findall('./file_system/device'):
            device_id = device.get('id')
            results = []
            for command in device.find('./commands'):
                for command_class in FILE_SYSTEM_COMMANDS:
                    if command_class.command_name == command.tag.lower():
                        results.append(command_class.parse_response(command, fssapi=self, device_id=device_id))
            out_dict[device_id] = results
        return out_dict

Response: Send an arbitrary file system command block to a target.


Instruction:
Can you tell what is the following Python 3 function doing
def list_files(self, target, path, hash='any'):
        command_block = FileSystemServiceCommandBlock()
        command_block.add_command(LsCommand(path, hash=hash))
        root = _parse_command_response(
            self._sci_api.send_sci("file_system", target, command_block.get_command_string()))

        out_dict = {}

        #  At this point the XML we have is of the form
        # <sci_reply>
        #   <file_system>
        #     <device id="device_id">
        #       <commands>
        #         <ls hash="hash_type">
        #           <file path="file_path" last_modified=last_modified_time ... />
        #           ...
        #           <dir path="dir_path" last_modified=last_modified_time />
        #           ...
        #         </ls>
        #       </commands>
        #     </device>
        #     <device id="device_id">
        #       <commands>
        #         <ls hash="hash_type">
        #           <file path="file_path" last_modified=last_modified_time ... />
        #           ...
        #           <dir path="dir_path" last_modified=last_modified_time />
        #           ...
        #         </ls>
        #       </commands>
        #     </device>
        #     ...
        #   </file_system>
        # </sci_reply>

        # Here we will get each of the XML trees rooted at the device nodes
        for device in root.findall('./file_system/device'):
            device_id = device.get('id')
            error = device.find('./error')
            if error is not None:
                out_dict[device_id] = _parse_error_tree(error)
            else:
                linfo = LsCommand.parse_response(device.find('./commands/ls'), device_id=device_id, fssapi=self)
                out_dict[device_id] = linfo
        return out_dict

Response: List all files and directories on the target and return a dictionary containing the files and directories and directories and error messages.


Instruction:
Given the following Python 3 function, write the documentation
def get_file(self, target, path, offset=None, length=None):
        command_block = FileSystemServiceCommandBlock()
        command_block.add_command(GetCommand(path, offset, length))
        root = _parse_command_response(
            self._sci_api.send_sci("file_system", target, command_block.get_command_string()))
        out_dict = {}
        for device in root.findall('./file_system/device'):
            device_id = device.get('id')
            error = device.find('./error')
            if error is not None:
                out_dict[device_id] = _parse_error_tree(error)
            else:
                data = GetCommand.parse_response(device.find('./commands/get_file'))
                out_dict[device_id] = data
        return out_dict

Response: Retrieves the contents of a file on the device.


Instruction:
Implement a Python 3 function for
putting data into a file on the devicecloud server.

Response:
def put_file(self, target, path, file_data=None, server_file=None, offset=None, truncate=False):
        """Put data into a file on the device

        :param target: The device(s) to be targeted with this request
        :type target: :class:`devicecloud.sci.TargetABC` or list of :class:`devicecloud.sci.TargetABC` instances
        :param path: The path on the target to the file to write to.  If the file already exists it will be overwritten.
        :param file_data: A `six.binary_type` containing the data to put into the file
        :param server_file: The path to a file on the devicecloud server containing the data to put into the file on the
            device
        :param offset: Start writing bytes to the file at this position, if None start at the beginning
        :param truncate: Boolean, if True after bytes are done being written end the file their even if previous data
            exists beyond it.  If False, leave any existing data in place.
        :return: A dictionary with keys being device ids and value being None if successful or an :class:`~.ErrorInfo`
            if the operation failed on that device
        :raises: :class:`~.FileSystemServiceException` if either both file_data and server_file are specified or
            neither are specified
        :raises: :class:`~.ResponseParseError` If the SCI response has unrecognized formatting
        """

        command_block = FileSystemServiceCommandBlock()
        command_block.add_command(PutCommand(path, file_data, server_file, offset, truncate))

        root = _parse_command_response(self._sci_api.send_sci("file_system", target, command_block.get_command_string()))
        out_dict = {}
        for device in root.findall('./file_system/device'):
            device_id = device.get('id')
            error = device.find('./error')
            if error is not None:
                out_dict[device_id] = _parse_error_tree(error)
            else:
                out_dict[device_id] = PutCommand.parse_response(device.find('./commands/put_file'))

        return out_dict


Instruction:
Write a Python 3 function for
deleting a file from a specific target.

Response:
def delete_file(self, target, path):
        """Delete a file from a device

        :param target: The device(s) to be targeted with this request
        :type target: :class:`devicecloud.sci.TargetABC` or list of :class:`devicecloud.sci.TargetABC` instances
        :param path: The path on the target to the file to delete.
        :return: A dictionary with keys being device ids and value being None if successful or an :class:`~.ErrorInfo`
            if the operation failed on that device
        :raises: :class:`~.ResponseParseError` If the SCI response has unrecognized formatting
        """
        command_block = FileSystemServiceCommandBlock()
        command_block.add_command(DeleteCommand(path))
        root = _parse_command_response(self._sci_api.send_sci("file_system", target, command_block.get_command_string()))

        out_dict = {}
        for device in root.findall('./file_system/device'):
            device_id = device.get('id')
            error = device.find('./error')
            if error is not None:
                out_dict[device_id] = _parse_error_tree(error)
            else:
                out_dict[device_id] = DeleteCommand.parse_response(device.find('./commands/rm'))
        return out_dict


Instruction:
Write a Python 3 script to
get all files and directories that have been modified since a given time.

Response:
def get_modified_items(self, target, path, last_modified_cutoff):
        """Get all files and directories from a path on the device modified since a given time

        :param target: The device(s) to be targeted with this request
        :type target: :class:`devicecloud.sci.TargetABC` or list of :class:`devicecloud.sci.TargetABC` instances
        :param path: The path on the target to the directory to check for modified files.
        :param last_modified_cutoff: The time (as Unix epoch time) to get files modified since
        :type last_modified_cutoff: int
        :return: A dictionary where the key is a device id and the value is either an :class:`~.ErrorInfo` if there
            was a problem with the operation or a :class:`~.LsInfo` with the items modified since the
            specified date
        """
        file_list = self.list_files(target, path)
        out_dict = {}
        for device_id, device_data in six.iteritems(file_list):
            if isinstance(device_data, ErrorInfo):
                out_dict[device_id] = device_data
            else:
                files = []
                dirs = []
                for cur_file in device_data.files:
                    if cur_file.last_modified > last_modified_cutoff:
                        files.append(cur_file)

                for cur_dir in device_data.directories:
                    if cur_dir.last_modified > last_modified_cutoff:
                        dirs.append(cur_dir)
                out_dict[device_id] = LsInfo(directories=dirs, files=files)

        return out_dict


Instruction:
Can you implement a function in Python 3 that
checks if a path refers to an existing path on the devicecloud

Response:
def exists(self, target, path, path_sep="/"):
        """Check if path refers to an existing path on the device

        :param target: The device(s) to be targeted with this request
        :type target: :class:`devicecloud.sci.TargetABC` or list of :class:`devicecloud.sci.TargetABC` instances
        :param path: The path on the target to check for existence.
        :param path_sep: The path separator of the device
        :return: A dictionary where the key is a device id and the value is either an :class:`~.ErrorInfo` if there
            was a problem with the operation or a boolean with the existence status of the path on that device
        """
        if path.endswith(path_sep):
            path = path[:-len(path_sep)]
        par_dir, filename = path.rsplit(path_sep, 1)
        file_list = self.list_files(target, par_dir)
        out_dict = {}
        for device_id, device_data in six.iteritems(file_list):
            if isinstance(device_data, ErrorInfo):
                out_dict[device_id] = device_data
            else:
                out_dict[device_id] = False
                for cur_file in device_data.files:
                    if cur_file.path == path:
                        out_dict[device_id] = True
                for cur_dir in device_data.directories:
                    if cur_dir.path == path:
                        out_dict[device_id] = True

        return out_dict


Instruction:
Can you tell what is the following Python 3 function doing
def get_devices(self, condition=None, page_size=1000):

        condition = validate_type(condition, type(None), Expression, *six.string_types)
        page_size = validate_type(page_size, *six.integer_types)

        params = {"embed": "true"}
        if condition is not None:
            params["condition"] = condition.compile()

        for device_json in self._conn.iter_json_pages("/ws/DeviceCore", page_size=page_size, **params):
            yield Device(self._conn, self._sci, device_json)

Response: Get all devices in this cloud account that match the condition.


Instruction:
Explain what the following Python 3 code does
def get_group_tree_root(self, page_size=1000):

        # first pass, build mapping
        group_map = {}  # map id -> group
        page_size = validate_type(page_size, *six.integer_types)
        for group in self.get_groups(page_size=page_size):
            group_map[group.get_id()] = group

        # second pass, find root and populate list of children for each node
        root = None
        for group_id, group in group_map.items():
            if group.is_root():
                root = group
            else:
                parent = group_map[group.get_parent_id()]
                parent.add_child(group)
        return root

Response: Return the root group for this accounts group tree.


Instruction:
Here you have a function in Python 3, explain what it does
def get_groups(self, condition=None, page_size=1000):
        query_kwargs = {}
        if condition is not None:
            query_kwargs["condition"] = condition.compile()
        for group_data in self._conn.iter_json_pages("/ws/Group", page_size=page_size, **query_kwargs):
            yield Group.from_json(group_data)

Response: Returns an iterator over all groups in this device cloud account.


Instruction:
Write a Python 3 function for
provisioning multiple devices with a single API call

Response:
def provision_devices(self, devices):
        """Provision multiple devices with a single API call

        This method takes an iterable of dictionaries where the values in the dictionary are
        expected to match the arguments of a call to :meth:`provision_device`.  The
        contents of each dictionary will be validated.

        :param list devices: An iterable of dictionaries each containing information about
            a device to be provision.  The form of the dictionary should match the keyword
            arguments taken by :meth:`provision_device`.
        :raises DeviceCloudHttpException: If there is an unexpected error reported by Device Cloud.
        :raises ValueError: If any input fields are known to have a bad form.
        :return: A list of dictionaries in the form described for :meth:`provision_device` in the
            order matching the requested device list.  Note that it is possible for there to
            be mixed success and error when provisioning multiple devices.

        """
        # Validate all the input for each device provided
        sio = six.StringIO()

        def write_tag(tag, val):
            sio.write("<{tag}>{val}</{tag}>".format(tag=tag, val=val))

        def maybe_write_element(tag, val):
            if val is not None:
                write_tag(tag, val)
                return True
            return False

        sio.write("<list>")
        for d in devices:
            sio.write("<DeviceCore>")

            mac_address = d.get("mac_address")
            device_id = d.get("device_id")
            imei = d.get("imei")
            if mac_address is not None:
                write_tag("devMac", mac_address)
            elif device_id is not None:
                write_tag("devConnectwareId", device_id)
            elif imei is not None:
                write_tag("devCellularModemId", imei)
            else:
                raise ValueError("mac_address, device_id, or imei must be provided for device %r" % d)

            # Write optional elements if present.
            maybe_write_element("grpPath", d.get("group_path"))
            maybe_write_element("dpUserMetaData", d.get("metadata"))
            maybe_write_element("dpTags", d.get("tags"))
            maybe_write_element("dpMapLong", d.get("map_long"))
            maybe_write_element("dpMapLat", d.get("map_lat"))
            maybe_write_element("dpContact", d.get("contact"))
            maybe_write_element("dpDescription", d.get("description"))

            sio.write("</DeviceCore>")
        sio.write("</list>")

        # Send the request, set the Accept XML as a nicety
        results = []
        response = self._conn.post("/ws/DeviceCore", sio.getvalue(), headers={'Accept': 'application/xml'})
        root = ET.fromstring(response.content)  # <result> tag is root of <list> response
        for child in root:
            if child.tag.lower() == "location":
                results.append({
                    "error": False,
                    "error_msg": None,
                    "location": child.text
                })
            else:  # we expect "error" but handle generically
                results.append({
                    "error": True,
                    "location": None,
                    "error_msg": child.text
                })

        return results


Instruction:
Can you generate a brief explanation for the following Python 3 code
def from_json(cls, json_data):
        # Example Data:
        # { "grpId": "11817", "grpName": "7603_Digi", "grpDescription": "7603_Digi root group",
        #   "grpPath": "\/7603_Digi\/", "grpParentId": "1"}
        return cls(
            group_id=json_data["grpId"],
            name=json_data["grpName"],
            description=json_data.get("grpDescription", ""),
            path=json_data["grpPath"],
            parent_id=json_data["grpParentId"],
        )

Response: Build and return a new Group object from json data.


Instruction:
Here you have a function in Python 3, explain what it does
def print_subtree(self, fobj=sys.stdout, level=0):
        fobj.write("{}{!r}\n".format(" " * (level * 2), self))
        for child in self.get_children():
            child.print_subtree(fobj, level + 1)

Response: Print this group node and the subtree rooted at it


Instruction:
Explain what the following Python 3 code does
def get_device_json(self, use_cached=True):
        if not use_cached:
            devicecore_data = self._conn.get_json(
                "/ws/DeviceCore/{}".format(self.get_device_id()))
            self._device_json = devicecore_data["items"][0]  # should only be 1
        return self._device_json

Response: Get the JSON metadata for this device as a python data structure.


Instruction:
Given the following Python 3 function, write the documentation
def get_tags(self, use_cached=True):
        device_json = self.get_device_json(use_cached)
        potential_tags = device_json.get("dpTags")
        if potential_tags:
            return list(filter(None, potential_tags.split(",")))
        else:
            return []

Response: Get the list of tags for this device


Instruction:
How would you implement a function in Python 3 that
returns True if the device is currrently connect and False if not.

Response:
def is_connected(self, use_cached=True):
        """Return True if the device is currrently connect and False if not"""
        device_json = self.get_device_json(use_cached)
        return int(device_json.get("dpConnectionStatus")) > 0


Instruction:
Can you generate a brief explanation for the following Python 3 code
def get_connectware_id(self, use_cached=True):
        device_json = self.get_device_json(use_cached)
        return device_json.get("devConnectwareId")

Response: Get the connectware id of this device


Instruction:
Can you create a Python 3 function that
gets this device s device id

Response:
def get_device_id(self, use_cached=True):
        """Get this device's device id"""
        device_json = self.get_device_json(use_cached)
        return device_json["id"].get("devId")


Instruction:
Can you implement a function in Python 3 that
gets the last known IP of this device

Response:
def get_ip(self, use_cached=True):
        """Get the last known IP of this device"""
        device_json = self.get_device_json(use_cached)
        return device_json.get("dpLastKnownIp")


Instruction:
Create a Python 3 function to
get the MAC address of this device

Response:
def get_mac(self, use_cached=True):
        """Get the MAC address of this device"""
        device_json = self.get_device_json(use_cached)
        return device_json.get("devMac")


Instruction:
Implement a function in Python 3 to
get the last 4 characters in the device mac address hex

Response:
def get_mac_last4(self, use_cached=True):
        """Get the last 4 characters in the device mac address hex (e.g. 00:40:9D:58:17:5B -> 175B)

        This is useful for use as a short reference to the device.  It is not guaranteed to
        be unique (obviously) but will often be if you don't have too many devices.

        """
        chunks = self.get_mac(use_cached).split(":")
        mac4 = "%s%s" % (chunks[-2], chunks[-1])
        return mac4.upper()


Instruction:
Explain what the following Python 3 code does
def get_registration_dt(self, use_cached=True):
        device_json = self.get_device_json(use_cached)
        start_date_iso8601 = device_json.get("devRecordStartDate")
        if start_date_iso8601:
            return iso8601_to_dt(start_date_iso8601)
        else:
            return None

Response: Get the datetime of when this device was added to Device Cloud


Instruction:
How would you explain what the following Python 3 function does
def get_latlon(self, use_cached=True):
        device_json = self.get_device_json(use_cached)
        lat = device_json.get("dpMapLat")
        lon = device_json.get("dpMapLong")
        return (float(lat) if lat else None,
                float(lon) if lon else None, )

Response: Get a tuple with device latitude and longitude... these may be None


Instruction:
Given the following Python 3 function, write the documentation
def add_to_group(self, group_path):

        if self.get_group_path() != group_path:
            post_data = ADD_GROUP_TEMPLATE.format(connectware_id=self.get_connectware_id(),
                                                  group_path=group_path)
            self._conn.put('/ws/DeviceCore', post_data)

            # Invalidate cache
            self._device_json = None

Response: Add a device to a group


Instruction:
Implement a Python 3 function for
adding a tag to existing device tags. This method will not add a duplicate, if already in the list. :param new_tags: the tag(s) to be added. new_tags can be a comma-separated string or list

Response:
def add_tag(self, new_tags):
        """Add a tag to existing device tags. This method will not add a duplicate, if already in the list.

        :param new_tags: the tag(s) to be added. new_tags can be a comma-separated string or list
        """

        tags = self.get_tags()
        orig_tag_cnt = len(tags)
        # print("self.get_tags() {}".format(tags))

        if isinstance(new_tags, six.string_types):
            new_tags = new_tags.split(',')
            # print("spliting tags :: {}".format(new_tags))

        for tag in new_tags:
            if not tag in tags:
                tags.append(tag.strip())

        if len(tags) > orig_tag_cnt:
            xml_tags = escape(",".join(tags))
            post_data = TAGS_TEMPLATE.format(connectware_id=self.get_connectware_id(),
                                             tags=xml_tags)
            self._conn.put('/ws/DeviceCore', post_data)

            # Invalidate cache
            self._device_json = None


Instruction:
Create a Python 3 function to
remove a tag from existing device tags

Response:
def remove_tag(self, tag):
        """Remove tag from existing device tags

        :param tag: the tag to be removed from the list

        :raises ValueError: If tag does not exist in list
        """

        tags = self.get_tags()
        tags.remove(tag)

        post_data = TAGS_TEMPLATE.format(connectware_id=self.get_connectware_id(),
                                         tags=escape(",".join(tags)))
        self._conn.put('/ws/DeviceCore', post_data)

        # Invalidate cache
        self._device_json = None


Instruction:
Write a Python 3 script for
getting the hostname that this connection is associated with

Response:
def hostname(self):
        """Get the hostname that this connection is associated with"""
        from six.moves.urllib.parse import urlparse
        return urlparse(self._base_url).netloc.split(':', 1)[0]


Instruction:
Given the following Python 3 function, write the documentation
def iter_json_pages(self, path, page_size=1000, **params):
        path = validate_type(path, *six.string_types)
        page_size = validate_type(page_size, *six.integer_types)

        offset = 0
        remaining_size = 1  # just needs to be non-zero
        while remaining_size > 0:
            reqparams = {"start": offset, "size": page_size}
            reqparams.update(params)
            response = self.get_json(path, params=reqparams)
            offset += page_size
            remaining_size = int(response.get("remainingSize", "0"))
            for item_json in response.get("items", []):
                yield item_json

Response: Return an iterator over JSON items from a paginated resource.


Instruction:
Explain what the following Python 3 code does
def get(self, path, **kwargs):
        url = self._make_url(path)
        return self._make_request("GET", url, **kwargs)

Response:
Perform an HTTP GET request against Device Cloud with this accounts
            credentials and base url.


Instruction:
Explain what the following Python 3 code does
def get_json(self, path, **kwargs):

        url = self._make_url(path)
        headers = kwargs.setdefault('headers', {})
        headers.update({'Accept': 'application/json'})
        response = self._make_request("GET", url, **kwargs)
        return json.loads(response.text)

Response:
Perform an HTTP GET request with JSON headers of the specified path against Device Cloud with this accounts
        credentials and base url.


Instruction:
How would you code a function in Python 3 to
perform an HTTP POST request against Device Cloud with this accounts credentials and base url.

Response:
def post(self, path, data, **kwargs):
        """Perform an HTTP POST request of the specified path in Device Cloud

        Make an HTTP POST request against Device Cloud with this accounts
        credentials and base url.  This method uses the
        `requests <http://docs.python-requests.org/en/latest/>`_ library
        `request method <http://docs.python-requests.org/en/latest/api/#requests.request>`_
        and all keyword arguments will be passed on to that method.

        :param str path: Device Cloud path to POST
        :param int retries: The number of times the request should be retried if an
            unsuccessful response is received.  Most likely, you should leave this at 0.
        :param data: The data to be posted in the body of the POST request (see docs for
            ``requests.post``
        :raises DeviceCloudHttpException: if a non-success response to the request is received
            from Device Cloud
        :returns: A requests ``Response`` object

        """
        url = self._make_url(path)
        return self._make_request("POST", url, data=data, **kwargs)


Instruction:
Explain what the following Python 3 code does
def put(self, path, data, **kwargs):

        url = self._make_url(path)
        return self._make_request("PUT", url, data=data, **kwargs)

Response:
Perform an HTTP PUT request against Device Cloud with this accounts
            credentials and base url.


Instruction:
Write a Python 3 function that can
perform an HTTP DELETE request against Device Cloud with this accounts credentials and base url.

Response:
def delete(self, path, retries=DEFAULT_THROTTLE_RETRIES, **kwargs):
        """Perform an HTTP DELETE request of the specified path in Device Cloud

        Make an HTTP DELETE request against Device Cloud with this accounts
        credentials and base url.  This method uses the
        `requests <http://docs.python-requests.org/en/latest/>`_ library
        `request method <http://docs.python-requests.org/en/latest/api/#requests.request>`_
        and all keyword arguments will be passed on to that method.

        :param str path: Device Cloud path to DELETE
        :param int retries: The number of times the request should be retried if an
            unsuccessful response is received.  Most likely, you should leave this at 0.
        :raises DeviceCloudHttpException: if a non-success response to the request is received
            from Device Cloud
        :returns: A requests ``Response`` object

        """
        url = self._make_url(path)
        return self._make_request("DELETE", url, **kwargs)


Instruction:
How would you explain what the following Python 3 function does
def streams(self):
        if self._streams_api is None:
            self._streams_api = self.get_streams_api()
        return self._streams_api

Response: Property providing access to the streams API


Instruction:
Explain what the following Python 3 code does
def filedata(self):
        if self._filedata_api is None:
            self._filedata_api = self.get_filedata_api()
        return self._filedata_api

Response: Property providing access to the FileDataAPI


Instruction:
Given the following Python 3 function, write the documentation
def devicecore(self):
        if self._devicecore_api is None:
            self._devicecore_api = self.get_devicecore_api()
        return self._devicecore_api

Response: Property providing access to the device core API


Instruction:
How would you implement a function in Python 3 that
returns a DeviceCoreAPI object bound to this device cloud instance

Response:
def get_devicecore_api(self):
        """Returns a :class:`.DeviceCoreAPI` bound to this device cloud instance

        This provides access to the same API as :attr:`.DeviceCloud.devicecore` but will create
        a new object (with a new cache) each time called.

        :return: devicecore API object bound to this device cloud account
        :rtype: :class:`.DeviceCoreAPI`

        """
        from devicecloud.devicecore import DeviceCoreAPI

        return DeviceCoreAPI(self._conn, self.get_sci_api())


Instruction:
Can you write a function in Python 3 where it
queries an asynchronous SCI job by ID This is useful for getting the job information from the async queue.

Response:
def get_async_job(self, job_id):
        """Query an asynchronous SCI job by ID

        This is useful if the job was not created with send_sci_async().

        :param int job_id: The job ID to query
        :returns: The SCI response from GETting the job information
        """
        uri = "/ws/sci/{0}".format(job_id)
        # TODO: do parsing here?
        return self._conn.get(uri)


Instruction:
Explain what the following Python 3 code does
def send_sci_async(self, operation, target, payload, **sci_options):
        sci_options['synchronous'] = False
        resp = self.send_sci(operation, target, payload, **sci_options)
        dom = ET.fromstring(resp.content)
        job_element = dom.find('.//jobId')
        if job_element is None:
            return
        job_id = int(job_element.text)
        return AsyncRequestProxy(job_id, self._conn)

Response: Send an asynchronous SCI request and wrap the job in an AsyncRequestProxy.


Instruction:
Create a Python 3 function to
send an SCI request to one or more targets.

Response:
def send_sci(self, operation, target, payload, reply=None, synchronous=None, sync_timeout=None,
                 cache=None, allow_offline=None, wait_for_reconnect=None):
        """Send SCI request to 1 or more targets

        :param str operation: The operation is one of {send_message, update_firmware, disconnect, query_firmware_targets,
            file_system, data_service, and reboot}
        :param target: The device(s) to be targeted with this request
        :type target: :class:`~.TargetABC` or list of :class:`~.TargetABC` instances

        TODO: document other params

        """
        if not isinstance(payload, six.string_types) and not isinstance(payload, six.binary_type):
            raise TypeError("payload is required to be a string or bytes")

        # validate targets and bulid targets xml section
        try:
            iter(target)
            targets = target
        except TypeError:
            targets = [target, ]
        if not all(isinstance(t, TargetABC) for t in targets):
            raise TypeError("Target(s) must each be instances of TargetABC")
        targets_xml = "".join(t.to_xml() for t in targets)

        # reply argument
        if not isinstance(reply, (type(None), six.string_types)):
            raise TypeError("reply must be either None or a string")
        if reply is not None:
            reply_xml = ' reply="{}"'.format(reply)
        else:
            reply_xml = ''

        # synchronous argument
        if not isinstance(synchronous, (type(None), bool)):
            raise TypeError("synchronous expected to be either None or a boolean")
        if synchronous is not None:
            synchronous_xml = ' synchronous="{}"'.format('true' if synchronous else 'false')
        else:
            synchronous_xml = ''

        # sync_timeout argument
        # TODO: What units is syncTimeout in?  seconds?
        if sync_timeout is not None and not isinstance(sync_timeout, six.integer_types):
            raise TypeError("sync_timeout expected to either be None or a number")
        if sync_timeout is not None:
            sync_timeout_xml = ' syncTimeout="{}"'.format(sync_timeout)
        else:
            sync_timeout_xml = ''

        # cache argument
        if not isinstance(cache, (type(None), bool)):
            raise TypeError("cache expected to either be None or a boolean")
        if cache is not None:
            cache_xml = ' cache="{}"'.format('true' if cache else 'false')
        else:
            cache_xml = ''

        # allow_offline argument
        if not isinstance(allow_offline, (type(None), bool)):
            raise TypeError("allow_offline is expected to be either None or a boolean")
        if allow_offline is not None:
            allow_offline_xml = ' allowOffline="{}"'.format('true' if allow_offline else 'false')
        else:
            allow_offline_xml = ''

        # wait_for_reconnect argument
        if not isinstance(wait_for_reconnect, (type(None), bool)):
            raise TypeError("wait_for_reconnect expected to be either None or a boolean")
        if wait_for_reconnect is not None:
            wait_for_reconnect_xml = ' waitForReconnect="{}"'.format('true' if wait_for_reconnect else 'false')
        else:
            wait_for_reconnect_xml = ''

        full_request = SCI_TEMPLATE.format(
            operation=operation,
            targets=targets_xml,
            reply=reply_xml,
            synchronous=synchronous_xml,
            sync_timeout=sync_timeout_xml,
            cache=cache_xml,
            allow_offline=allow_offline_xml,
            wait_for_reconnect=wait_for_reconnect_xml,
            payload=payload
        )

        # TODO: do parsing here?
        return self._conn.post("/ws/sci", full_request)


Instruction:
Write a Python 3 script to
write to stream using fmt and value

Response:
def conditional_write(strm, fmt, value, *args, **kwargs):
    """Write to stream using fmt and value if value is not None"""
    if value is not None:
        strm.write(fmt.format(value, *args, **kwargs))


Instruction:
Implement a function in Python 3 to
give an ISO8601 string as returned by Device Cloud convert to a datetime object

Response:
def iso8601_to_dt(iso8601):
    """Given an ISO8601 string as returned by Device Cloud, convert to a datetime object"""
    # We could just use arrow.get() but that is more permissive than we actually want.
    # Internal (but still public) to arrow is the actual parser where we can be
    # a bit more specific
    parser = DateTimeParser()
    try:
        arrow_dt = arrow.Arrow.fromdatetime(parser.parse_iso(iso8601))
        return arrow_dt.to('utc').datetime
    except ParserError as pe:
        raise ValueError("Provided was not a valid ISO8601 string: %r" % pe)


Instruction:
Write a Python 3 script for
converting input to either None or a datetime object.

Response:
def to_none_or_dt(input):
    """Convert ``input`` to either None or a datetime object

    If the input is None, None will be returned.
    If the input is a datetime object, it will be converted to a datetime
    object with UTC timezone info.  If the datetime object is naive, then
    this method will assume the object is specified according to UTC and
    not local or some other timezone.
    If the input to the function is a string, this method will attempt to
    parse the input as an ISO-8601 formatted string.

    :param input: Input data (expected to be either str, None, or datetime object)
    :return: datetime object from input or None if already None
    :rtype: datetime or None

    """
    if input is None:
        return input
    elif isinstance(input, datetime.datetime):
        arrow_dt = arrow.Arrow.fromdatetime(input, input.tzinfo or 'utc')
        return arrow_dt.to('utc').datetime
    if isinstance(input, six.string_types):
        # try to convert from ISO8601
        return iso8601_to_dt(input)
    else:
        raise TypeError("Not a string, NoneType, or datetime object")


Instruction:
Implement a function in Python 3 to
return an ISO - 8601 formatted string from the provided datetime object

Response:
def isoformat(dt):
    """Return an ISO-8601 formatted string from the provided datetime object"""
    if not isinstance(dt, datetime.datetime):
        raise TypeError("Must provide datetime.datetime object to isoformat")

    if dt.tzinfo is None:
        raise ValueError("naive datetime objects are not allowed beyond the library boundaries")

    return dt.isoformat().replace("+00:00", "Z")


Instruction:
Write a Python 3 script for
returning a generator over all filedata matching the condition.

Response:
def get_filedata(self, condition=None, page_size=1000):
        """Return a generator over all results matching the provided condition

        :param condition: An :class:`.Expression` which defines the condition
            which must be matched on the filedata that will be retrieved from
            file data store. If a condition is unspecified, the following condition
            will be used ``fd_path == '~/'``.  This condition will match all file
            data in this accounts "home" directory (a sensible root).
        :type condition: :class:`.Expression` or None
        :param int page_size: The number of results to fetch in a single page.  Regardless
            of the size specified, :meth:`.get_filedata` will continue to fetch pages
            and yield results until all items have been fetched.
        :return: Generator yielding :class:`.FileDataObject` instances matching the
            provided conditions.

        """

        condition = validate_type(condition, type(None), Expression, *six.string_types)
        page_size = validate_type(page_size, *six.integer_types)
        if condition is None:
            condition = (fd_path == "~/")  # home directory

        params = {"embed": "true", "condition": condition.compile()}
        for fd_json in self._conn.iter_json_pages("/ws/FileData", page_size=page_size, **params):
            yield FileDataObject.from_json(self, fd_json)


Instruction:
Create a Python 3 function for
writing a file to the file data store at the given path.

Response:
def write_file(self, path, name, data, content_type=None, archive=False,
                   raw=False):
        """Write a file to the file data store at the given path

        :param str path: The path (directory) into which the file should be written.
        :param str name: The name of the file to be written.
        :param data: The binary data that should be written into the file.
        :type data: str (Python2) or bytes (Python3)
        :param content_type: The content type for the data being written to the file.  May
             be left unspecified.
        :type content_type: str or None
        :param bool archive: If true, history will be retained for various revisions of this
            file.  If this is not required, leave as false.
        :param bool raw: If true, skip the FileData XML headers (necessary for binary files)

        """
        path = validate_type(path, *six.string_types)
        name = validate_type(name, *six.string_types)
        data = validate_type(data, six.binary_type)
        content_type = validate_type(content_type, type(None), *six.string_types)
        archive_str = "true" if validate_type(archive, bool) else "false"

        if not path.startswith("/"):
            path = "/" + path
        if not path.endswith("/"):
            path += "/"
        name = name.lstrip("/")

        sio = six.moves.StringIO()
        if not raw:
            if six.PY3:
                base64_encoded_data = base64.encodebytes(data).decode('utf-8')
            else:
                base64_encoded_data = base64.encodestring(data)

            sio.write("<FileData>")
            if content_type is not None:
                sio.write("<fdContentType>{}</fdContentType>".format(content_type))
            sio.write("<fdType>file</fdType>")
            sio.write("<fdData>{}</fdData>".format(base64_encoded_data))
            sio.write("<fdArchive>{}</fdArchive>".format(archive_str))
            sio.write("</FileData>")
        else:
            sio.write(data)

        params = {
            "type": "file",
            "archive": archive_str
        }
        self._conn.put(
            "/ws/FileData{path}{name}".format(path=path, name=name),
            sio.getvalue(),
            params=params)


Instruction:
Can you write a function in Python 3 where it
deletes a file or directory from the filedata store

Response:
def delete_file(self, path):
        """Delete a file or directory from the filedata store

        This method removes a file or directory (recursively) from
        the filedata store.

        :param path: The path of the file or directory to remove
            from the file data store.

        """
        path = validate_type(path, *six.string_types)
        if not path.startswith("/"):
            path = "/" + path

        self._conn.delete("/ws/FileData{path}".format(path=path))


Instruction:
Make a summary of the following Python 3 code
def walk(self, root="~/"):
        root = validate_type(root, *six.string_types)

        directories = []
        files = []

        # fd_path is real picky
        query_fd_path = root
        if not query_fd_path.endswith("/"):
            query_fd_path += "/"

        for fd_object in self.get_filedata(fd_path == query_fd_path):
            if fd_object.get_type() == "directory":
                directories.append(fd_object)
            else:
                files.append(fd_object)

        # Yield the walk results for this level of the tree
        yield (root, directories, files)

        # recurse on each directory and yield results up the chain
        for directory in directories:
            for dirpath, directories, files in self.walk(directory.get_full_path()):
                yield (dirpath, directories, files)

Response: Emulation of os. walk behavior against Device Cloud filedata store


Instruction:
Here you have a function in Python 3, explain what it does
def get_data(self):
        # NOTE: we assume that the "embed" option is used
        base64_data = self._json_data.get("fdData")
        if base64_data is None:
            return None
        else:
            # need to convert to bytes() with python 3
            return base64.decodestring(six.b(base64_data))

Response: Get the data associated with this filedata object


Instruction:
Explain what the following Python 3 code does
def write_file(self, *args, **kwargs):
        return self._fdapi.write_file(self.get_path(), *args, **kwargs)

Response: Write a file into this directory


Instruction:
Can you generate a brief explanation for the following Python 3 code
def create_tcp_monitor(self, topics, batch_size=1, batch_duration=0,
                           compression='gzip', format_type='json'):
        """Creates a TCP Monitor instance in Device Cloud for a given list of topics

        :param topics: a string list of topics (e.g. ['DeviceCore[U]',
                  'FileDataCore']).
        :param batch_size: How many Msgs received before sending data.
        :param batch_duration: How long to wait before sending batch if it
            does not exceed batch_size.
        :param compression: Compression value (i.e. 'gzip').
        :param format_type: What format server should send data in (i.e. 'xml' or 'json').

        Returns an object of the created Monitor
        """

        monitor_xml = """\
        <Monitor>
            <monTopic>{topics}</monTopic>
            <monBatchSize>{batch_size}</monBatchSize>
            <monFormatType>{format_type}</monFormatType>
            <monTransportType>tcp</monTransportType>
            <monCompression>{compression}</monCompression>
        </Monitor>
        """.format(
            topics=','.join(topics),
            batch_size=batch_size,
            batch_duration=batch_duration,
            format_type=format_type,
            compression=compression,
        )
        monitor_xml = textwrap.dedent(monitor_xml)

        response = self._conn.post("/ws/Monitor", monitor_xml)
        location = ET.fromstring(response.text).find('.//location').text
        monitor_id = int(location.split('/')[-1])
        return TCPDeviceCloudMonitor(self._conn, monitor_id, self._tcp_client_manager)

Response: Creates a new TCP Monitor instance for a given list of topics.


Instruction:
Can you implement a function in Python 3 that
creates a Monitor instance in Device Cloud for a given list of topics.

Response:
def create_http_monitor(self, topics, transport_url, transport_token=None, transport_method='PUT', connect_timeout=0,
                            response_timeout=0, batch_size=1, batch_duration=0, compression='none', format_type='json'):
        """Creates a HTTP Monitor instance in Device Cloud for a given list of topics

        :param topics: a string list of topics (e.g. ['DeviceCore[U]',
                  'FileDataCore']).
        :param transport_url: URL of the customer web server.
        :param transport_token: Credentials for basic authentication in the following format: username:password
        :param transport_method: HTTP method to use for sending data: PUT or POST. The default is PUT.
        :param connect_timeout: A value of 0 means use the system default of 5000 (5 seconds).
        :param response_timeout: A value of 0 means use the system default of 5000 (5 seconds).
        :param batch_size: How many Msgs received before sending data.
        :param batch_duration: How long to wait before sending batch if it
            does not exceed batch_size.
        :param compression: Compression value (i.e. 'gzip').
        :param format_type: What format server should send data in (i.e. 'xml' or 'json').

        Returns an object of the created Monitor
        """

        monitor_xml = """\
        <Monitor>
            <monTopic>{topics}</monTopic>
            <monBatchSize>{batch_size}</monBatchSize>
            <monFormatType>{format_type}</monFormatType>
            <monTransportType>http</monTransportType>
            <monTransportUrl>{transport_url}</monTransportUrl>
            <monTransportToken>{transport_token}</monTransportToken>
            <monTransportMethod>{transport_method}</monTransportMethod>
            <monConnectTimeout>{connect_timeout}</monConnectTimeout>
            <monResponseTimeout>{response_timeout}</monResponseTimeout>
            <monCompression>{compression}</monCompression>
        </Monitor>
        """.format(
            topics=','.join(topics),
            transport_url=transport_url,
            transport_token=transport_token,
            transport_method=transport_method,
            connect_timeout=connect_timeout,
            response_timeout=response_timeout,
            batch_size=batch_size,
            batch_duration=batch_duration,
            format_type=format_type,
            compression=compression,
        )
        monitor_xml = textwrap.dedent(monitor_xml)

        response = self._conn.post("/ws/Monitor", monitor_xml)
        location = ET.fromstring(response.text).find('.//location').text
        monitor_id = int(location.split('/')[-1])
        return HTTPDeviceCloudMonitor(self._conn, monitor_id)


Instruction:
Given the following Python 3 function, write the documentation
def get_monitors(self, condition=None, page_size=1000):
        req_kwargs = {}
        if condition:
            req_kwargs['condition'] = condition.compile()
        for monitor_data in self._conn.iter_json_pages("/ws/Monitor", **req_kwargs):
            yield DeviceCloudMonitor.from_json(self._conn, monitor_data, self._tcp_client_manager)

Response: Returns an iterator over all monitors matching the provided condition.


Instruction:
Make a summary of the following Python 3 code
def get_monitor(self, topics):
        for monitor in self.get_monitors(MON_TOPIC_ATTR == ",".join(topics)):
            return monitor  # return the first one, even if there are multiple
        return None

Response: Attempts to find a Monitor in device cloud that matches the provided topics. Returns None if no Monitor is found.


Instruction:
Given the following Python 3 function, write the documentation
def _get_decoder_method(stream_type):
    if stream_type is not None:
        return DSTREAM_TYPE_MAP.get(stream_type.upper(), (lambda x: x, lambda x: x))[0]
    else:
        return lambda x: x

Response: Returns a function that returns the python type converter function for the given stream type.


Instruction:
Create a Python 3 function to
get a list of all the streams in the system

Response:
def _get_streams(self, uri_suffix=None):
        """Clear and update internal cache of stream objects"""
        # TODO: handle paging, perhaps change this to be a generator
        if uri_suffix is not None and not uri_suffix.startswith('/'):
            uri_suffix = '/' + uri_suffix
        elif uri_suffix is None:
            uri_suffix = ""
        streams = {}
        response = self._conn.get_json("/ws/DataStream{}".format(uri_suffix))
        for stream_data in response["items"]:
            stream_id = stream_data["streamId"]
            stream = DataStream(self._conn, stream_id, stream_data)
            streams[stream_id] = stream
        return streams


Instruction:
How would you implement a function in Python 3 that
creates a new data stream on Device Cloud This method will attempt to create a new data stream on Device Cloud. This method will only succeed if the stream does not already exist. :param str stream_id: The path/id of the stream being created on Device Cloud. :param str data_type: The type of this stream. This must be in the set `{ INTEGER, LONG, FLOAT, DOUBLE, STRING, BINARY, UNKNOWN }`. These values are available in constants like :attr:`~STREAM_TYPE_INTEGER`. :param str description: An optional description of this stream. See :meth:`~DataStream.get_description`. :param int data_ttl: The TTL for data points in this stream. See :meth:`~DataStream.get_data_ttl`. :param int rollup_ttl: The TTL for performing rollups on data. See :meth:~DataStream.get_rollup_ttl`. :param str units: Units for data in this stream. See :meth:`~DataStream.get_units`

Response:
def create_stream(self, stream_id, data_type, description=None, data_ttl=None,
                      rollup_ttl=None, units=None):
        """Create a new data stream on Device Cloud

        This method will attempt to create a new data stream on Device Cloud.
        This method will only succeed if the stream does not already exist.

        :param str stream_id: The path/id of the stream being created on Device Cloud.
        :param str data_type: The type of this stream.  This must be in the set
            `{ INTEGER, LONG, FLOAT, DOUBLE, STRING, BINARY, UNKNOWN }`.  These values are
            available in constants like :attr:`~STREAM_TYPE_INTEGER`.
        :param str description: An optional description of this stream. See :meth:`~DataStream.get_description`.
        :param int data_ttl: The TTL for data points in this stream. See :meth:`~DataStream.get_data_ttl`.
        :param int rollup_ttl: The TTL for performing rollups on data. See :meth:~DataStream.get_rollup_ttl`.
        :param str units: Units for data in this stream.  See :meth:`~DataStream.get_units`

        """

        stream_id = validate_type(stream_id, *six.string_types)
        data_type = validate_type(data_type, type(None), *six.string_types)
        if isinstance(data_type, *six.string_types):
            data_type = str(data_type).upper()
        if not data_type in (set([None, ]) | set(list(DSTREAM_TYPE_MAP.keys()))):
            raise ValueError("data_type %r is not valid" % data_type)
        description = validate_type(description, type(None), *six.string_types)
        data_ttl = validate_type(data_ttl, type(None), *six.integer_types)
        rollup_ttl = validate_type(rollup_ttl, type(None), *six.integer_types)
        units = validate_type(units, type(None), *six.string_types)

        sio = StringIO()
        sio.write("<DataStream>")
        conditional_write(sio, "<streamId>{}</streamId>", stream_id)
        conditional_write(sio, "<dataType>{}</dataType>", data_type)
        conditional_write(sio, "<description>{}</description>", description)
        conditional_write(sio, "<dataTtl>{}</dataTtl>", data_ttl)
        conditional_write(sio, "<rollupTtl>{}</rollupTtl>", rollup_ttl)
        conditional_write(sio, "<units>{}</units>", units)
        sio.write("</DataStream>")

        self._conn.post("/ws/DataStream", sio.getvalue())
        logger.info("Data stream (%s) created successfully", stream_id)
        stream = DataStream(self._conn, stream_id)
        return stream


Instruction:
How would you explain what the following Python 3 function does
def get_stream_if_exists(self, stream_id):
        stream = self.get_stream(stream_id)
        try:
            stream.get_data_type(use_cached=True)
        except NoSuchStreamException:
            return None
        else:
            return stream

Response: Return a reference to a stream with the given stream_id if it exists.


Instruction:
Create a Python 3 function to
perform a bulk write (or set of writes) of a collection of data points This method takes a list (or other iterable) of datapoints and writes them to Device Cloud in an efficient manner, minimizing the number of HTTP requests that need to be made. As this call is performed from outside the context of any particular stream, each DataPoint object passed in must include information about the stream into which the point should be written. If all data points being written are for the same stream, you may want to consider using :meth:`~DataStream.bulk_write_datapoints` instead. Example:: datapoints = [] for i in range(300): datapoints.append(DataPoint( stream_id="my/stream%d" % (i % 3), data_type=STREAM_TYPE_INTEGER, units="meters", data=i, )) dc.streams.bulk_write_datapoints(datapoints) Depending on the size of the list of datapoints provided, this method may need to make multiple calls to Device Cloud (in chunks of 250). :param list datapoints: a list of datapoints to be written to Device Cloud :raises TypeError: if a list of datapoints is not provided :raises ValueError: if any of the provided data points do not have all required information (such as information about the stream) :raises DeviceCloudHttpException: in the case of an unexpected error in communicating with Device Cloud.

Response:
def bulk_write_datapoints(self, datapoints):
        """Perform a bulk write (or set of writes) of a collection of data points

        This method takes a list (or other iterable) of datapoints and writes them
        to Device Cloud in an efficient manner, minimizing the number of HTTP
        requests that need to be made.

        As this call is performed from outside the context of any particular stream,
        each DataPoint object passed in must include information about the stream
        into which the point should be written.

        If all data points being written are for the same stream, you may want to
        consider using :meth:`~DataStream.bulk_write_datapoints` instead.

        Example::

            datapoints = []
            for i in range(300):
                datapoints.append(DataPoint(
                    stream_id="my/stream%d" % (i % 3),
                    data_type=STREAM_TYPE_INTEGER,
                    units="meters",
                    data=i,
                ))
            dc.streams.bulk_write_datapoints(datapoints)

        Depending on the size of the list of datapoints provided, this method may
        need to make multiple calls to Device Cloud (in chunks of 250).

        :param list datapoints: a list of datapoints to be written to Device Cloud
        :raises TypeError: if a list of datapoints is not provided
        :raises ValueError: if any of the provided data points do not have all required
            information (such as information about the stream)
        :raises DeviceCloudHttpException: in the case of an unexpected error in communicating
            with Device Cloud.

        """
        datapoints = list(datapoints)  # effectively performs validation that we have the right type
        for dp in datapoints:
            if not isinstance(dp, DataPoint):
                raise TypeError("All items in the datapoints list must be DataPoints")
            if dp.get_stream_id() is None:
                raise ValueError("stream_id must be set on all datapoints")

        remaining_datapoints = datapoints
        while remaining_datapoints:
            # take up to 250 points and post them until complete
            this_chunk_of_datapoints = remaining_datapoints[:MAXIMUM_DATAPOINTS_PER_POST]
            remaining_datapoints = remaining_datapoints[MAXIMUM_DATAPOINTS_PER_POST:]

            # Build XML list containing data for all points
            datapoints_out = StringIO()
            datapoints_out.write("<list>")
            for dp in this_chunk_of_datapoints:
                datapoints_out.write(dp.to_xml())
            datapoints_out.write("</list>")

            # And send the HTTP Post
            self._conn.post("/ws/DataPoint", datapoints_out.getvalue())
            logger.info('DataPoint batch of %s datapoints written', len(this_chunk_of_datapoints))


Instruction:
Write a Python 3 script to
create a new DataPoint object from a JSON data stream.

Response:
def from_json(cls, stream, json_data):
        """Create a new DataPoint object from device cloud JSON data

        :param DataStream stream: The :class:`~DataStream` out of which this data is coming
        :param dict json_data: Deserialized JSON data from Device Cloud about this device
        :raises ValueError: if the data is malformed
        :return: (:class:`~DataPoint`) newly created :class:`~DataPoint`

        """
        type_converter = _get_decoder_method(stream.get_data_type())
        data = type_converter(json_data.get("data"))
        return cls(
            # these are actually properties of the stream, not the data point
            stream_id=stream.get_stream_id(),
            data_type=stream.get_data_type(),
            units=stream.get_units(),

            # and these are part of the data point itself
            data=data,
            description=json_data.get("description"),
            timestamp=json_data.get("timestampISO"),
            server_timestamp=json_data.get("serverTimestampISO"),
            quality=json_data.get("quality"),
            location=json_data.get("location"),
            dp_id=json_data.get("id"),
        )


Instruction:
How would you explain what the following Python 3 function does
def from_rollup_json(cls, stream, json_data):
        dp = cls.from_json(stream, json_data)

        # Special handling for timestamp
        timestamp = isoformat(dc_utc_timestamp_to_dt(int(json_data.get("timestamp"))))

        # Special handling for data, all rollup data is float type
        type_converter = _get_decoder_method(stream.get_data_type())
        data = type_converter(float(json_data.get("data")))

        # Update the special fields
        dp.set_timestamp(timestamp)
        dp.set_data(data)
        return dp

Response: Create a new data point from a rollup json data stream.


Instruction:
How would you code a function in Python 3 to
set the stream id associated with this data point

Response:
def set_stream_id(self, stream_id):
        """Set the stream id associated with this data point"""
        stream_id = validate_type(stream_id, type(None), *six.string_types)
        if stream_id is not None:
            stream_id = stream_id.lstrip('/')
        self._stream_id = stream_id


Instruction:
How would you explain what the following Python 3 function does
def set_description(self, description):
        self._description = validate_type(description, type(None), *six.string_types)

Response: Set the description for this data point


Instruction:
Can you tell what is the following Python 3 function doing
def set_quality(self, quality):
        if isinstance(quality, *six.string_types):
            quality = int(quality)
        elif isinstance(quality, float):
            quality = int(quality)

        self._quality = validate_type(quality, type(None), *six.integer_types)

Response: Set the quality for this sample


Instruction:
Explain what the following Python 3 code does
def set_location(self, location):
        if location is None:
            self._location = location

        elif isinstance(location, *six.string_types):  # from device cloud, convert from csv
            parts = str(location).split(",")
            if len(parts) == 3:
                self._location = tuple(map(float, parts))
                return
            else:
                raise ValueError("Location string %r has unexpected format" % location)

        # TODO: could maybe try to allow any iterable but this covers the most common cases
        elif (isinstance(location, (tuple, list))
                and len(location) == 3
                and all([isinstance(x, (float, six.integer_types)) for x in location])):
            self._location = tuple(map(float, location))  # coerce ints to float
        else:
            raise TypeError("Location must be None or 3-tuple of floats")

        self._location = location

Response: Set the location for this data point.


Instruction:
Can you generate the documentation for the following Python 3 function
def set_data_type(self, data_type):
        validate_type(data_type, type(None), *six.string_types)
        if isinstance(data_type, *six.string_types):
            data_type = str(data_type).upper()
        if not data_type in ({None} | set(DSTREAM_TYPE_MAP.keys())):
            raise ValueError("Provided data type not in available set of types")
        self._data_type = data_type

Response: Set the data type for the current entry point.


Instruction:
Write a Python 3 function that can
set the unit for this data point

Response:
def set_units(self, unit):
        """Set the unit for this data point

        Unit, as with data_type, are actually associated with the stream and not
        the individual data point.  As such, changing this within a stream is
        not encouraged.  Setting the unit on the data point is useful when the
        stream might be created with the write of a data point.

        """
        self._units = validate_type(unit, type(None), *six.string_types)


Instruction:
Make a summary of the following Python 3 code
def to_xml(self):
        type_converter = _get_encoder_method(self._data_type)
        # Convert from python native to device cloud
        encoded_data = type_converter(self._data)

        out = StringIO()
        out.write("<DataPoint>")
        out.write("<streamId>{}</streamId>".format(self.get_stream_id()))
        out.write("<data>{}</data>".format(encoded_data))
        conditional_write(out, "<description>{}</description>", self.get_description())
        if self.get_timestamp() is not None:
            out.write("<timestamp>{}</timestamp>".format(isoformat(self.get_timestamp())))
        conditional_write(out, "<quality>{}</quality>", self.get_quality())
        if self.get_location() is not None:
            out.write("<location>%s</location>" % ",".join(map(str, self.get_location())))
        conditional_write(out, "<streamType>{}</streamType>", self.get_data_type())
        conditional_write(out, "<streamUnits>{}</streamUnits>", self.get_units())
        out.write("</DataPoint>")
        return out.getvalue()

Response: Convert this datapoint into a form suitable for pushing to device cloud cloud.


Instruction:
How would you code a function in Python 3 to
retrieve metadata about this stream from Device Cloud

Response:
def _get_stream_metadata(self, use_cached):
        """Retrieve metadata about this stream from Device Cloud"""
        if self._cached_data is None or not use_cached:
            try:
                self._cached_data = self._conn.get_json("/ws/DataStream/%s" % self._stream_id)["items"][0]
            except DeviceCloudHttpException as http_exception:
                if http_exception.response.status_code == 404:
                    raise NoSuchStreamException("Stream with id %r has not been created" % self._stream_id)
                raise http_exception
        return self._cached_data


Instruction:
Create a Python 3 function to
get the data type of this data stream.

Response:
def get_data_type(self, use_cached=True):
        """Get the data type of this stream if it exists

        The data type is the type of data stored in this data stream. Valid types include:

        * INTEGER - data can be represented with a network (= big-endian) 32-bit two's-complement integer.  Data
          with this type maps to a python int.
        * LONG - data can be represented with a network (= big-endian) 64-bit two's complement integer.  Data
          with this type maps to a python int.
        * FLOAT - data can be represented with a network (= big-endian) 32-bit IEEE754 floating point.  Data
          with this type maps to a python float.
        * DOUBLE - data can be represented with a network (= big-endian) 64-bit IEEE754 floating point.  Data
          with this type maps to a python float.
        * STRING - UTF-8.  Data with this type map to a python string
        * BINARY - Data with this type map to a python string.
        * UNKNOWN - Data with this type map to a python string.

        :param bool use_cached: If False, the function will always request the latest from Device Cloud.
            If True, the device will not make a request if it already has cached data.
        :return: The data type of this stream as a string
        :rtype: str

        """
        dtype = self._get_stream_metadata(use_cached).get("dataType")
        if dtype is not None:
            dtype = dtype.upper()
        return dtype