Instruction:
Here you have a function in Python 3, explain what it does
def akismet_check(comment, content_object, request):
    # Return previously cached response
    akismet_result = getattr(comment, '_akismet_result_', None)
    if akismet_result is not None:
        return akismet_result

    # Get Akismet data
    AKISMET_API_KEY = appsettings.AKISMET_API_KEY
    if not AKISMET_API_KEY:
        raise ImproperlyConfigured('You must set AKISMET_API_KEY to use comment moderation with Akismet.')

    current_domain = get_current_site(request).domain
    auto_blog_url = '{0}://{1}/'.format(request.is_secure() and 'https' or 'http', current_domain)
    blog_url = appsettings.AKISMET_BLOG_URL or auto_blog_url

    akismet = Akismet(
        AKISMET_API_KEY,
        blog=blog_url,
        is_test=int(bool(appsettings.AKISMET_IS_TEST)),
        application_user_agent='django-fluent-comments/{0}'.format(fluent_comments.__version__),
    )

    akismet_data = _get_akismet_data(blog_url, comment, content_object, request)
    akismet_result = akismet.check(**akismet_data)  # raises AkismetServerError when key is invalid
    setattr(comment, "_akismet_result_", akismet_result)
    return akismet_result

Response: Checks if the comment is spam.


Instruction:
Can you generate the documentation for the following Python 3 function
def _handle_remark_msg(self, msg):
        msg = msg.strip()
        if msg.startswith("runtime error:"):
            raise exception.OverpassRuntimeError(msg=msg)
        elif msg.startswith("runtime remark:"):
            raise exception.OverpassRuntimeRemark(msg=msg)
        raise exception.OverpassUnknownError(msg=msg)

Response: Handle the message provided with the remark tag or element.


Instruction:
Here you have a function in Python 3, explain what it does
def query(self, query):
        if not isinstance(query, bytes):
            query = query.encode("utf-8")

        retry_num = 0
        retry_exceptions = []
        do_retry = True if self.max_retry_count > 0 else False
        while retry_num <= self.max_retry_count:
            if retry_num > 0:
                time.sleep(self.retry_timeout)
            retry_num += 1
            try:
                f = urlopen(self.url, query)
            except HTTPError as e:
                f = e

            response = f.read(self.read_chunk_size)
            while True:
                data = f.read(self.read_chunk_size)
                if len(data) == 0:
                    break
                response = response + data
            f.close()

            if f.code == 200:
                if PY2:
                    http_info = f.info()
                    content_type = http_info.getheader("content-type")
                else:
                    content_type = f.getheader("Content-Type")

                if content_type == "application/json":
                    return self.parse_json(response)

                if content_type == "application/osm3s+xml":
                    return self.parse_xml(response)

                e = exception.OverpassUnknownContentType(content_type)
                if not do_retry:
                    raise e
                retry_exceptions.append(e)
                continue

            if f.code == 400:
                msgs = []
                for msg in self._regex_extract_error_msg.finditer(response):
                    tmp = self._regex_remove_tag.sub(b"", msg.group("msg"))
                    try:
                        tmp = tmp.decode("utf-8")
                    except UnicodeDecodeError:
                        tmp = repr(tmp)
                    msgs.append(tmp)

                e = exception.OverpassBadRequest(
                    query,
                    msgs=msgs
                )
                if not do_retry:
                    raise e
                retry_exceptions.append(e)
                continue

            if f.code == 429:
                e = exception.OverpassTooManyRequests
                if not do_retry:
                    raise e
                retry_exceptions.append(e)
                continue

            if f.code == 504:
                e = exception.OverpassGatewayTimeout
                if not do_retry:
                    raise e
                retry_exceptions.append(e)
                continue

            e = exception.OverpassUnknownHTTPStatusCode(f.code)
            if not do_retry:
                raise e
            retry_exceptions.append(e)
            continue

        raise exception.MaxRetriesReached(retry_count=retry_num, exceptions=retry_exceptions)

Response: Query the Overpass API and return the parsed result.


Instruction:
Can you generate the documentation for the following Python 3 function
def parse_json(self, data, encoding="utf-8"):
        if isinstance(data, bytes):
            data = data.decode(encoding)
        data = json.loads(data, parse_float=Decimal)
        if "remark" in data:
            self._handle_remark_msg(msg=data.get("remark"))
        return Result.from_json(data, api=self)

Response: Parse raw response from Overpass service.


Instruction:
Create a Python 3 function to
add all elements from an other result to the list of elements of this result object.

Response:
def expand(self, other):
        """
        Add all elements from an other result to the list of elements of this result object.

        It is used by the auto resolve feature.

        :param other: Expand the result with the elements from this result.
        :type other: overpy.Result
        :raises ValueError: If provided parameter is not instance of :class:`overpy.Result`
        """
        if not isinstance(other, Result):
            raise ValueError("Provided argument has to be instance of overpy:Result()")

        other_collection_map = {Node: other.nodes, Way: other.ways, Relation: other.relations, Area: other.areas}
        for element_type, own_collection in self._class_collection_map.items():
            for element in other_collection_map[element_type]:
                if is_valid_type(element, element_type) and element.id not in own_collection:
                    own_collection[element.id] = element


Instruction:
Can you generate a brief explanation for the following Python 3 code
def append(self, element):
        if is_valid_type(element, Element):
            self._class_collection_map[element.__class__].setdefault(element.id, element)

Response: Append a new element to the result.


Instruction:
Create a Python 3 function for
getting a list of elements from the result and filter the element type by a class.

Response:
def get_elements(self, filter_cls, elem_id=None):
        """
        Get a list of elements from the result and filter the element type by a class.

        :param filter_cls:
        :param elem_id: ID of the object
        :type elem_id: Integer
        :return: List of available elements
        :rtype: List
        """
        result = []
        if elem_id is not None:
            try:
                result = [self._class_collection_map[filter_cls][elem_id]]
            except KeyError:
                result = []
        else:
            for e in self._class_collection_map[filter_cls].values():
                result.append(e)
        return result


Instruction:
Here you have a function in Python 3, explain what it does
def from_json(cls, data, api=None):
        result = cls(api=api)
        for elem_cls in [Node, Way, Relation, Area]:
            for element in data.get("elements", []):
                e_type = element.get("type")
                if hasattr(e_type, "lower") and e_type.lower() == elem_cls._type_value:
                    result.append(elem_cls.from_json(element, result=result))

        return result

Response: Create a new Result object from json data.


Instruction:
Can you tell what is the following Python 3 function doing
def from_xml(cls, data, api=None, parser=None):
        if parser is None:
            if isinstance(data, str):
                parser = XML_PARSER_SAX
            else:
                parser = XML_PARSER_DOM

        result = cls(api=api)
        if parser == XML_PARSER_DOM:
            import xml.etree.ElementTree as ET
            if isinstance(data, str):
                root = ET.fromstring(data)
            elif isinstance(data, ET.Element):
                root = data
            else:
                raise exception.OverPyException("Unable to detect data type.")

            for elem_cls in [Node, Way, Relation, Area]:
                for child in root:
                    if child.tag.lower() == elem_cls._type_value:
                        result.append(elem_cls.from_xml(child, result=result))

        elif parser == XML_PARSER_SAX:
            if PY2:
                from StringIO import StringIO
            else:
                from io import StringIO
            source = StringIO(data)
            sax_handler = OSMSAXHandler(result)
            parser = make_parser()
            parser.setContentHandler(sax_handler)
            parser.parse(source)
        else:
            # ToDo: better exception
            raise Exception("Unknown XML parser")
        return result

Response: Create a new Result object from XML data.


Instruction:
Here you have a function in Python 3, explain what it does
def get_area(self, area_id, resolve_missing=False):
        areas = self.get_areas(area_id=area_id)
        if len(areas) == 0:
            if resolve_missing is False:
                raise exception.DataIncomplete("Resolve missing area is disabled")

            query = ("\n"
                     "[out:json];\n"
                     "area({area_id});\n"
                     "out body;\n"
                     )
            query = query.format(
                area_id=area_id
            )
            tmp_result = self.api.query(query)
            self.expand(tmp_result)

            areas = self.get_areas(area_id=area_id)

        if len(areas) == 0:
            raise exception.DataIncomplete("Unable to resolve requested areas")

        return areas[0]

Response: Get an area by its ID.


Instruction:
How would you explain what the following Python 3 function does
def get_areas(self, area_id=None, **kwargs):
        return self.get_elements(Area, elem_id=area_id, **kwargs)

Response: Alias for get_elements but filter the result by Area


Instruction:
Implement a function in Python 3 to
get a node by its ID.

Response:
def get_node(self, node_id, resolve_missing=False):
        """
        Get a node by its ID.

        :param node_id: The node ID
        :type node_id: Integer
        :param resolve_missing: Query the Overpass API if the node is missing in the result set.
        :return: The node
        :rtype: overpy.Node
        :raises overpy.exception.DataIncomplete: At least one referenced node is not available in the result cache.
        :raises overpy.exception.DataIncomplete: If resolve_missing is True and at least one node can't be resolved.
        """
        nodes = self.get_nodes(node_id=node_id)
        if len(nodes) == 0:
            if not resolve_missing:
                raise exception.DataIncomplete("Resolve missing nodes is disabled")

            query = ("\n"
                     "[out:json];\n"
                     "node({node_id});\n"
                     "out body;\n"
                     )
            query = query.format(
                node_id=node_id
            )
            tmp_result = self.api.query(query)
            self.expand(tmp_result)

            nodes = self.get_nodes(node_id=node_id)

        if len(nodes) == 0:
            raise exception.DataIncomplete("Unable to resolve all nodes")

        return nodes[0]


Instruction:
Can you create a Python 3 function that
aliases for get_elements but filter the result by Node

Response:
def get_nodes(self, node_id=None, **kwargs):
        """
        Alias for get_elements() but filter the result by Node()

        :param node_id: The Id of the node
        :type node_id: Integer
        :return: List of elements
        """
        return self.get_elements(Node, elem_id=node_id, **kwargs)


Instruction:
Make a summary of the following Python 3 code
def get_relation(self, rel_id, resolve_missing=False):
        relations = self.get_relations(rel_id=rel_id)
        if len(relations) == 0:
            if resolve_missing is False:
                raise exception.DataIncomplete("Resolve missing relations is disabled")

            query = ("\n"
                     "[out:json];\n"
                     "relation({relation_id});\n"
                     "out body;\n"
                     )
            query = query.format(
                relation_id=rel_id
            )
            tmp_result = self.api.query(query)
            self.expand(tmp_result)

            relations = self.get_relations(rel_id=rel_id)

        if len(relations) == 0:
            raise exception.DataIncomplete("Unable to resolve requested reference")

        return relations[0]

Response: Get a relation by its ID.


Instruction:
Write a Python 3 script for
aliasing for get_elements but filter the result by Relation

Response:
def get_relations(self, rel_id=None, **kwargs):
        """
        Alias for get_elements() but filter the result by Relation

        :param rel_id: Id of the relation
        :type rel_id: Integer
        :return: List of elements
        """
        return self.get_elements(Relation, elem_id=rel_id, **kwargs)


Instruction:
Can you tell what is the following Python 3 function doing
def get_way(self, way_id, resolve_missing=False):
        ways = self.get_ways(way_id=way_id)
        if len(ways) == 0:
            if resolve_missing is False:
                raise exception.DataIncomplete("Resolve missing way is disabled")

            query = ("\n"
                     "[out:json];\n"
                     "way({way_id});\n"
                     "out body;\n"
                     )
            query = query.format(
                way_id=way_id
            )
            tmp_result = self.api.query(query)
            self.expand(tmp_result)

            ways = self.get_ways(way_id=way_id)

        if len(ways) == 0:
            raise exception.DataIncomplete("Unable to resolve requested way")

        return ways[0]

Response: Get a way by its ID.


Instruction:
Here you have a function in Python 3, explain what it does
def get_ways(self, way_id=None, **kwargs):
        return self.get_elements(Way, elem_id=way_id, **kwargs)

Response: Alias for get_elements but filter the result by Way


Instruction:
Given the following Python 3 function, write the documentation
def get_center_from_json(cls, data):
        center_lat = None
        center_lon = None
        center = data.get("center")
        if isinstance(center, dict):
            center_lat = center.get("lat")
            center_lon = center.get("lon")
            if center_lat is None or center_lon is None:
                raise ValueError("Unable to get lat or lon of way center.")
            center_lat = Decimal(center_lat)
            center_lon = Decimal(center_lon)
        return (center_lat, center_lon)

Response: Get center information from json data.


Instruction:
Can you implement a function in Python 3 that
creates a new way element from an xml. etree. Element object.

Response:
def from_xml(cls, child, result=None):
        """
        Create new way element from XML data

        :param child: XML node to be parsed
        :type child: xml.etree.ElementTree.Element
        :param result: The result this node belongs to
        :type result: overpy.Result
        :return: New Way oject
        :rtype: overpy.Way
        :raises overpy.exception.ElementDataWrongType: If name of the xml child node doesn't match
        :raises ValueError: If the ref attribute of the xml node is not provided
        :raises ValueError: If a tag doesn't have a name
        """
        if child.tag.lower() != cls._type_value:
            raise exception.ElementDataWrongType(
                type_expected=cls._type_value,
                type_provided=child.tag.lower()
            )

        tags = {}

        for sub_child in child:
            if sub_child.tag.lower() == "tag":
                name = sub_child.attrib.get("k")
                if name is None:
                    raise ValueError("Tag without name/key.")
                value = sub_child.attrib.get("v")
                tags[name] = value

        area_id = child.attrib.get("id")
        if area_id is not None:
            area_id = int(area_id)

        attributes = {}
        ignore = ["id"]
        for n, v in child.attrib.items():
            if n in ignore:
                continue
            attributes[n] = v

        return cls(area_id=area_id, attributes=attributes, tags=tags, result=result)


Instruction:
Write a Python 3 script for
creating a new Node element from a JSON data dict.

Response:
def from_json(cls, data, result=None):
        """
        Create new Node element from JSON data

        :param data: Element data from JSON
        :type data: Dict
        :param result: The result this element belongs to
        :type result: overpy.Result
        :return: New instance of Node
        :rtype: overpy.Node
        :raises overpy.exception.ElementDataWrongType: If type value of the passed JSON data does not match.
        """
        if data.get("type") != cls._type_value:
            raise exception.ElementDataWrongType(
                type_expected=cls._type_value,
                type_provided=data.get("type")
            )

        tags = data.get("tags", {})

        node_id = data.get("id")
        lat = data.get("lat")
        lon = data.get("lon")

        attributes = {}
        ignore = ["type", "id", "lat", "lon", "tags"]
        for n, v in data.items():
            if n in ignore:
                continue
            attributes[n] = v

        return cls(node_id=node_id, lat=lat, lon=lon, tags=tags, attributes=attributes, result=result)


Instruction:
Implement a function in Python 3 to
create a new way element from an XML node.

Response:
def from_xml(cls, child, result=None):
        """
        Create new way element from XML data

        :param child: XML node to be parsed
        :type child: xml.etree.ElementTree.Element
        :param result: The result this node belongs to
        :type result: overpy.Result
        :return: New Way oject
        :rtype: overpy.Node
        :raises overpy.exception.ElementDataWrongType: If name of the xml child node doesn't match
        :raises ValueError: If a tag doesn't have a name
        """
        if child.tag.lower() != cls._type_value:
            raise exception.ElementDataWrongType(
                type_expected=cls._type_value,
                type_provided=child.tag.lower()
            )

        tags = {}

        for sub_child in child:
            if sub_child.tag.lower() == "tag":
                name = sub_child.attrib.get("k")
                if name is None:
                    raise ValueError("Tag without name/key.")
                value = sub_child.attrib.get("v")
                tags[name] = value

        node_id = child.attrib.get("id")
        if node_id is not None:
            node_id = int(node_id)
        lat = child.attrib.get("lat")
        if lat is not None:
            lat = Decimal(lat)
        lon = child.attrib.get("lon")
        if lon is not None:
            lon = Decimal(lon)

        attributes = {}
        ignore = ["id", "lat", "lon"]
        for n, v in child.attrib.items():
            if n in ignore:
                continue
            attributes[n] = v

        return cls(node_id=node_id, lat=lat, lon=lon, tags=tags, attributes=attributes, result=result)


Instruction:
Create a Python 3 function to
get the nodes defining the geometry of the way.

Response:
def get_nodes(self, resolve_missing=False):
        """
        Get the nodes defining the geometry of the way

        :param resolve_missing: Try to resolve missing nodes.
        :type resolve_missing: Boolean
        :return: List of nodes
        :rtype: List of overpy.Node
        :raises overpy.exception.DataIncomplete: At least one referenced node is not available in the result cache.
        :raises overpy.exception.DataIncomplete: If resolve_missing is True and at least one node can't be resolved.
        """
        result = []
        resolved = False

        for node_id in self._node_ids:
            try:
                node = self._result.get_node(node_id)
            except exception.DataIncomplete:
                node = None

            if node is not None:
                result.append(node)
                continue

            if not resolve_missing:
                raise exception.DataIncomplete("Resolve missing nodes is disabled")

            # We tried to resolve the data but some nodes are still missing
            if resolved:
                raise exception.DataIncomplete("Unable to resolve all nodes")

            query = ("\n"
                     "[out:json];\n"
                     "way({way_id});\n"
                     "node(w);\n"
                     "out body;\n"
                     )
            query = query.format(
                way_id=self.id
            )
            tmp_result = self._result.api.query(query)
            self._result.expand(tmp_result)
            resolved = True

            try:
                node = self._result.get_node(node_id)
            except exception.DataIncomplete:
                node = None

            if node is None:
                raise exception.DataIncomplete("Unable to resolve all nodes")

            result.append(node)

        return result


Instruction:
Given the following Python 3 function, write the documentation
def from_json(cls, data, result=None):
        if data.get("type") != cls._type_value:
            raise exception.ElementDataWrongType(
                type_expected=cls._type_value,
                type_provided=data.get("type")
            )

        tags = data.get("tags", {})

        way_id = data.get("id")
        node_ids = data.get("nodes")
        (center_lat, center_lon) = cls.get_center_from_json(data=data)

        attributes = {}
        ignore = ["center", "id", "nodes", "tags", "type"]
        for n, v in data.items():
            if n in ignore:
                continue
            attributes[n] = v

        return cls(
            attributes=attributes,
            center_lat=center_lat,
            center_lon=center_lon,
            node_ids=node_ids,
            tags=tags,
            result=result,
            way_id=way_id
        )

Response: Create a new Way element from JSON data.


Instruction:
Can you create a Python 3 function that
creates a new way element from an XML node.

Response:
def from_xml(cls, child, result=None):
        """
        Create new way element from XML data

        :param child: XML node to be parsed
        :type child: xml.etree.ElementTree.Element
        :param result: The result this node belongs to
        :type result: overpy.Result
        :return: New Way oject
        :rtype: overpy.Way
        :raises overpy.exception.ElementDataWrongType: If name of the xml child node doesn't match
        :raises ValueError: If the ref attribute of the xml node is not provided
        :raises ValueError: If a tag doesn't have a name
        """
        if child.tag.lower() != cls._type_value:
            raise exception.ElementDataWrongType(
                type_expected=cls._type_value,
                type_provided=child.tag.lower()
            )

        tags = {}
        node_ids = []
        center_lat = None
        center_lon = None

        for sub_child in child:
            if sub_child.tag.lower() == "tag":
                name = sub_child.attrib.get("k")
                if name is None:
                    raise ValueError("Tag without name/key.")
                value = sub_child.attrib.get("v")
                tags[name] = value
            if sub_child.tag.lower() == "nd":
                ref_id = sub_child.attrib.get("ref")
                if ref_id is None:
                    raise ValueError("Unable to find required ref value.")
                ref_id = int(ref_id)
                node_ids.append(ref_id)
            if sub_child.tag.lower() == "center":
                (center_lat, center_lon) = cls.get_center_from_xml_dom(sub_child=sub_child)

        way_id = child.attrib.get("id")
        if way_id is not None:
            way_id = int(way_id)

        attributes = {}
        ignore = ["id"]
        for n, v in child.attrib.items():
            if n in ignore:
                continue
            attributes[n] = v

        return cls(way_id=way_id, center_lat=center_lat, center_lon=center_lon,
                   attributes=attributes, node_ids=node_ids, tags=tags, result=result)


Instruction:
Write a Python 3 script to
create a new relation element from JSON data.

Response:
def from_json(cls, data, result=None):
        """
        Create new Relation element from JSON data

        :param data: Element data from JSON
        :type data: Dict
        :param result: The result this element belongs to
        :type result: overpy.Result
        :return: New instance of Relation
        :rtype: overpy.Relation
        :raises overpy.exception.ElementDataWrongType: If type value of the passed JSON data does not match.
        """
        if data.get("type") != cls._type_value:
            raise exception.ElementDataWrongType(
                type_expected=cls._type_value,
                type_provided=data.get("type")
            )

        tags = data.get("tags", {})

        rel_id = data.get("id")
        (center_lat, center_lon) = cls.get_center_from_json(data=data)

        members = []

        supported_members = [RelationNode, RelationWay, RelationRelation]
        for member in data.get("members", []):
            type_value = member.get("type")
            for member_cls in supported_members:
                if member_cls._type_value == type_value:
                    members.append(
                        member_cls.from_json(
                            member,
                            result=result
                        )
                    )

        attributes = {}
        ignore = ["id", "members", "tags", "type"]
        for n, v in data.items():
            if n in ignore:
                continue
            attributes[n] = v

        return cls(
            rel_id=rel_id,
            attributes=attributes,
            center_lat=center_lat,
            center_lon=center_lon,
            members=members,
            tags=tags,
            result=result
        )


Instruction:
Explain what the following Python 3 code does
def from_xml(cls, child, result=None):
        if child.tag.lower() != cls._type_value:
            raise exception.ElementDataWrongType(
                type_expected=cls._type_value,
                type_provided=child.tag.lower()
            )

        tags = {}
        members = []
        center_lat = None
        center_lon = None

        supported_members = [RelationNode, RelationWay, RelationRelation, RelationArea]
        for sub_child in child:
            if sub_child.tag.lower() == "tag":
                name = sub_child.attrib.get("k")
                if name is None:
                    raise ValueError("Tag without name/key.")
                value = sub_child.attrib.get("v")
                tags[name] = value
            if sub_child.tag.lower() == "member":
                type_value = sub_child.attrib.get("type")
                for member_cls in supported_members:
                    if member_cls._type_value == type_value:
                        members.append(
                            member_cls.from_xml(
                                sub_child,
                                result=result
                            )
                        )
            if sub_child.tag.lower() == "center":
                (center_lat, center_lon) = cls.get_center_from_xml_dom(sub_child=sub_child)

        rel_id = child.attrib.get("id")
        if rel_id is not None:
            rel_id = int(rel_id)

        attributes = {}
        ignore = ["id"]
        for n, v in child.attrib.items():
            if n in ignore:
                continue
            attributes[n] = v

        return cls(
            rel_id=rel_id,
            attributes=attributes,
            center_lat=center_lat,
            center_lon=center_lon,
            members=members,
            tags=tags,
            result=result
        )

Response: Create a new way element from an XML node.


Instruction:
Create a Python 3 function to
create a new RelationMember element from JSON data.

Response:
def from_json(cls, data, result=None):
        """
        Create new RelationMember element from JSON data

        :param child: Element data from JSON
        :type child: Dict
        :param result: The result this element belongs to
        :type result: overpy.Result
        :return: New instance of RelationMember
        :rtype: overpy.RelationMember
        :raises overpy.exception.ElementDataWrongType: If type value of the passed JSON data does not match.
        """
        if data.get("type") != cls._type_value:
            raise exception.ElementDataWrongType(
                type_expected=cls._type_value,
                type_provided=data.get("type")
            )

        ref = data.get("ref")
        role = data.get("role")

        attributes = {}
        ignore = ["geometry", "type", "ref", "role"]
        for n, v in data.items():
            if n in ignore:
                continue
            attributes[n] = v

        geometry = data.get("geometry")
        if isinstance(geometry, list):
            geometry_orig = geometry
            geometry = []
            for v in geometry_orig:
                geometry.append(
                    RelationWayGeometryValue(
                        lat=v.get("lat"),
                        lon=v.get("lon")
                    )
                )
        else:
            geometry = None

        return cls(
            attributes=attributes,
            geometry=geometry,
            ref=ref,
            role=role,
            result=result
        )


Instruction:
Write a Python 3 function for
creating a new relation member from XML data.

Response:
def from_xml(cls, child, result=None):
        """
        Create new RelationMember from XML data

        :param child: XML node to be parsed
        :type child: xml.etree.ElementTree.Element
        :param result: The result this element belongs to
        :type result: overpy.Result
        :return: New relation member oject
        :rtype: overpy.RelationMember
        :raises overpy.exception.ElementDataWrongType: If name of the xml child node doesn't match
        """
        if child.attrib.get("type") != cls._type_value:
            raise exception.ElementDataWrongType(
                type_expected=cls._type_value,
                type_provided=child.tag.lower()
            )

        ref = child.attrib.get("ref")
        if ref is not None:
            ref = int(ref)
        role = child.attrib.get("role")

        attributes = {}
        ignore = ["geometry", "ref", "role", "type"]
        for n, v in child.attrib.items():
            if n in ignore:
                continue
            attributes[n] = v

        geometry = None
        for sub_child in child:
            if sub_child.tag.lower() == "nd":
                if geometry is None:
                    geometry = []
                geometry.append(
                    RelationWayGeometryValue(
                        lat=Decimal(sub_child.attrib["lat"]),
                        lon=Decimal(sub_child.attrib["lon"])
                    )
                )

        return cls(
            attributes=attributes,
            geometry=geometry,
            ref=ref,
            role=role,
            result=result
        )


Instruction:
Explain what the following Python 3 code does
def startElement(self, name, attrs):
        if name in self.ignore_start:
            return
        try:
            handler = getattr(self, '_handle_start_%s' % name)
        except AttributeError:
            raise KeyError("Unknown element start '%s'" % name)
        handler(attrs)

Response:
Handle opening elements.

        :param name: Name of the element
        :type name: String
        :param attrs: Attributes of the element
        :type attrs: Dict


Instruction:
How would you code a function in Python 3 to
handle closing elements of the specified name.

Response:
def endElement(self, name):
        """
        Handle closing elements

        :param name: Name of the element
        :type name: String
        """
        if name in self.ignore_end:
            return
        try:
            handler = getattr(self, '_handle_end_%s' % name)
        except AttributeError:
            raise KeyError("Unknown element end '%s'" % name)
        handler()


Instruction:
How would you implement a function in Python 3 that
handles opening center element

Response:
def _handle_start_center(self, attrs):
        """
        Handle opening center element

        :param attrs: Attributes of the element
        :type attrs: Dict
        """
        center_lat = attrs.get("lat")
        center_lon = attrs.get("lon")
        if center_lat is None or center_lon is None:
            raise ValueError("Unable to get lat or lon of way center.")
        self._curr["center_lat"] = Decimal(center_lat)
        self._curr["center_lon"] = Decimal(center_lon)


Instruction:
How would you implement a function in Python 3 that
handles opening tag element

Response:
def _handle_start_tag(self, attrs):
        """
        Handle opening tag element

        :param attrs: Attributes of the element
        :type attrs: Dict
        """
        try:
            tag_key = attrs['k']
        except KeyError:
            raise ValueError("Tag without name/key.")
        self._curr['tags'][tag_key] = attrs.get('v')


Instruction:
Can you tell what is the following Python 3 function doing
def _handle_start_node(self, attrs):
        self._curr = {
            'attributes': dict(attrs),
            'lat': None,
            'lon': None,
            'node_id': None,
            'tags': {}
        }
        if attrs.get('id', None) is not None:
            self._curr['node_id'] = int(attrs['id'])
            del self._curr['attributes']['id']
        if attrs.get('lat', None) is not None:
            self._curr['lat'] = Decimal(attrs['lat'])
            del self._curr['attributes']['lat']
        if attrs.get('lon', None) is not None:
            self._curr['lon'] = Decimal(attrs['lon'])
            del self._curr['attributes']['lon']

Response: Handle opening node element


Instruction:
Make a summary of the following Python 3 code
def _handle_end_node(self):
        self._result.append(Node(result=self._result, **self._curr))
        self._curr = {}

Response: Handle closing node element


Instruction:
Implement a Python 3 function for
handling opening way element

Response:
def _handle_start_way(self, attrs):
        """
        Handle opening way element

        :param attrs: Attributes of the element
        :type attrs: Dict
        """
        self._curr = {
            'center_lat': None,
            'center_lon': None,
            'attributes': dict(attrs),
            'node_ids': [],
            'tags': {},
            'way_id': None
        }
        if attrs.get('id', None) is not None:
            self._curr['way_id'] = int(attrs['id'])
            del self._curr['attributes']['id']


Instruction:
Can you tell what is the following Python 3 function doing
def _handle_end_way(self):
        self._result.append(Way(result=self._result, **self._curr))
        self._curr = {}

Response: Handle closing way element


Instruction:
How would you code a function in Python 3 to
handle opening area element

Response:
def _handle_start_area(self, attrs):
        """
        Handle opening area element

        :param attrs: Attributes of the element
        :type attrs: Dict
        """
        self._curr = {
            'attributes': dict(attrs),
            'tags': {},
            'area_id': None
        }
        if attrs.get('id', None) is not None:
            self._curr['area_id'] = int(attrs['id'])
            del self._curr['attributes']['id']


Instruction:
Write a Python 3 function that can
handle closing area element

Response:
def _handle_end_area(self):
        """
        Handle closing area element
        """
        self._result.append(Area(result=self._result, **self._curr))
        self._curr = {}


Instruction:
Explain what the following Python 3 code does
def _handle_start_nd(self, attrs):
        if isinstance(self.cur_relation_member, RelationWay):
            if self.cur_relation_member.geometry is None:
                self.cur_relation_member.geometry = []
            self.cur_relation_member.geometry.append(
                RelationWayGeometryValue(
                    lat=Decimal(attrs["lat"]),
                    lon=Decimal(attrs["lon"])
                )
            )
        else:
            try:
                node_ref = attrs['ref']
            except KeyError:
                raise ValueError("Unable to find required ref value.")
            self._curr['node_ids'].append(int(node_ref))

Response: Handle opening nd element


Instruction:
Can you generate the documentation for the following Python 3 function
def _handle_start_relation(self, attrs):
        self._curr = {
            'attributes': dict(attrs),
            'members': [],
            'rel_id': None,
            'tags': {}
        }
        if attrs.get('id', None) is not None:
            self._curr['rel_id'] = int(attrs['id'])
            del self._curr['attributes']['id']

Response: Handle opening relation element


Instruction:
Explain what the following Python 3 code does
def _handle_end_relation(self):
        self._result.append(Relation(result=self._result, **self._curr))
        self._curr = {}

Response: Handle closing relation element


Instruction:
How would you code a function in Python 3 to
handle opening member element

Response:
def _handle_start_member(self, attrs):
        """
        Handle opening member element

        :param attrs: Attributes of the element
        :type attrs: Dict
        """

        params = {
            # ToDo: Parse attributes
            'attributes': {},
            'ref': None,
            'result': self._result,
            'role': None
        }
        if attrs.get('ref', None):
            params['ref'] = int(attrs['ref'])
        if attrs.get('role', None):
            params['role'] = attrs['role']

        cls_map = {
            "area": RelationArea,
            "node": RelationNode,
            "relation": RelationRelation,
            "way": RelationWay
        }
        cls = cls_map.get(attrs["type"])
        if cls is None:
            raise ValueError("Undefined type for member: '%s'" % attrs['type'])

        self.cur_relation_member = cls(**params)
        self._curr['members'].append(self.cur_relation_member)


Instruction:
Write a Python 3 function for
retrieving streets in a given bounding area.

Response:
def get_street(street, areacode, api=None):
    """
    Retrieve streets in a given bounding area

    :param overpy.Overpass api: First street of intersection
    :param String street: Name of street
    :param String areacode: The OSM id of the bounding area
    :return: Parsed result
    :raises overpy.exception.OverPyException: If something bad happens.
    """
    if api is None:
        api = overpy.Overpass()

    query = """
        area(%s)->.location;
        (
            way[highway][name="%s"](area.location);
            - (
                way[highway=service](area.location);
                way[highway=track](area.location);
            );
        );
        out body;
        >;
        out skel qt;
    """

    data = api.query(query % (areacode, street))

    return data


Instruction:
Can you generate the documentation for the following Python 3 function
def get_intersection(street1, street2, areacode, api=None):
    if api is None:
        api = overpy.Overpass()

    query = """
        area(%s)->.location;
        (
            way[highway][name="%s"](area.location); node(w)->.n1;
            way[highway][name="%s"](area.location); node(w)->.n2;
        );
        node.n1.n2;
        out meta;
    """

    data = api.query(query % (areacode, street1, street2))

    return data.get_nodes()

Response: Retrieve intersection of two streets in a given bounding area.


Instruction:
Create a Python 3 function for
printing a tree of nodes.

Response:
def print_tree(current_node, childattr='children', nameattr='name', indent='', last='updown'):

    if hasattr(current_node, nameattr):
        name = lambda node: getattr(node, nameattr)
    else:
        name = lambda node: str(node)

    children = lambda node: getattr(node, childattr)
    nb_children = lambda node: sum(nb_children(child) for child in children(node)) + 1
    size_branch = {child: nb_children(child) for child in children(current_node)}

    """ Creation of balanced lists for "up" branch and "down" branch. """
    up = sorted(children(current_node), key=lambda node: nb_children(node))
    down = []
    while up and sum(size_branch[node] for node in down) < sum(size_branch[node] for node in up):
        down.append(up.pop())

    """ Printing of "up" branch. """
    for child in up:
        next_last = 'up' if up.index(child) is 0 else ''
        next_indent = '{0}{1}{2}'.format(indent, ' ' if 'up' in last else '│', ' ' * len(name(current_node)))
        print_tree(child, childattr, nameattr, next_indent, next_last)

    """ Printing of current node. """
    if last == 'up': start_shape = '┌'
    elif last == 'down': start_shape = '└'
    elif last == 'updown': start_shape = ' '
    else: start_shape = '├'

    if up: end_shape = '┤'
    elif down: end_shape = '┐'
    else: end_shape = ''

    print('{0}{1}{2}{3}'.format(indent, start_shape, name(current_node), end_shape))

    """ Printing of "down" branch. """
    for child in down:
        next_last = 'down' if down.index(child) is len(down) - 1 else ''
        next_indent = '{0}{1}{2}'.format(indent, ' ' if 'down' in last else '│', ' ' * len(name(current_node)))
        print_tree(child, childattr, nameattr, next_indent, next_last)


Instruction:
How would you code a function in Python 3 to
check if the platforms have a valid platform code

Response:
def check_platforms(platforms):
  """Checks if the platforms have a valid platform code"""
  if len(platforms) > 0:
    return all(platform in PLATFORM_IDS for platform in platforms)
  return True


Instruction:
Can you tell what is the following Python 3 function doing
def main(active, upcoming, hiring, short, goto, platforms, time):

  if not check_platforms(platforms):
    raise IncorrectParametersException('Invlaid code for platform. Please check the platform ids')

  try:
    if active:
      active_challenges = active_contests(platforms)
      if goto:
        webbrowser.open(active_challenges[goto - 1]["contest_url"], new=2)
      else:
        writers.write_contests(active_challenges, "active")
      return

    if upcoming:
      upcoming_challenges = upcoming_contests(platforms, time)
      if goto:
        goto = int(goto)
        webbrowser.open(upcoming_challenges[goto - 1]["contest_url"], new=2)
      else:
        writers.write_contests(upcoming_challenges, "upcoming")
      return

    if hiring:
      hiring_challenges = hiring_contests()
      if goto:
        webbrowser.open(hiring_challenges[goto - 1]["contest_url"], new=2)
      else:
        writers.write_contests(hiring_challenges, "hiring")
      return

    if short:
      short_challenges = short_contests(platforms)
      if goto:
        goto = int(goto)
        webbrowser.open(short_challenges[goto - 1]["contest_url"], new=2)
      else:
        writers.write_contests(short_challenges, "short")
      return

    all_contests = get_all_contests(platforms, time)
    if goto:
      webbrowser.open(all_contests[goto - 1]["contest_url"], new=2)
    else:
      writers.write_contests(all_contests, "all")
  except IncorrectParametersException as e:
    click.secho(e.message, fg="red", bold=True)

Response: A CLI for active and upcoming programming challenges from various platforms


Instruction:
Make a summary of the following Python 3 code
def colors():
  enums = dict(
    TIME_LEFT="red",
    CONTEST_NAME="yellow",
    HOST="green",
    MISC="blue",
    TIME_TO_START="green",
  )

  return type('Enum', (), enums)

Response: Creates an enum for colors


Instruction:
Can you tell what is the following Python 3 function doing
def challenge():
  enums = dict(
    ACTIVE="active",
    UPCOMING="upcoming",
    HIRING="hiring",
    ALL="all",
    SHORT="short",
  )

  return type('Enum', (), enums)

Response: Creates an enum for contest type


Instruction:
Implement a function in Python 3 to
return a string with time for the contest to begin or end

Response:
def get_time_string(contest, contest_type):
  """Return a string with time for the contest to begin/end"""

  if contest_type == challenge().ACTIVE:
    time_diff = time_difference(contest["end"])
  elif contest_type == challenge().UPCOMING:
    time_diff = time_difference(contest["start"])
  elif contest_type in [challenge().HIRING, challenge().SHORT, challenge().ALL]:
    try:
      time_diff = time_difference(contest["start"])
    except:
      time_diff = time_difference(contest["end"])
  time_diff_string = ""

  if time_diff.days > 0:
    time_diff_string = "{0} days {1} hours".format(time_diff.days, time_diff.hours)
  elif time_diff.hours > 0:
    time_diff_string = "{0} hours {1} minutes".format(time_diff.hours, time_diff.minutes)
  else:
    time_diff_string = "{0} minutes".format(time_diff.minutes)
  return time_diff_string


Instruction:
How would you implement a function in Python 3 that
calculates the difference between the current time and the given time

Response:
def time_difference(target_time):
  """Calculate the difference between the current time and the given time"""
  TimeDiff = namedtuple("TimeDiff", ["days", "hours", "minutes", "seconds"])
  time_diff = format_date(target_time) - datetime.utcnow()
  hours, remainder = divmod(time_diff.seconds, 3600)
  minutes, seconds = divmod(remainder, 60)
  return TimeDiff(days=time_diff.days, hours=hours, minutes=minutes, seconds=seconds)


Instruction:
Explain what the following Python 3 code does
def IntegerLike(msg=None):
    '''
    Checks whether a value is:
        - int, or
        - long, or
        - float without a fractional part, or
        - str or unicode composed only of digits
    '''
    def fn(value):
        if not any([
            isinstance(value, numbers.Integral),
            (isinstance(value, float) and value.is_integer()),
            (isinstance(value, basestring) and value.isdigit())
        ]):
            raise Invalid(msg or (
                'Invalid input <{0}>; expected an integer'.format(value))
            )
        else:
            return value
    return fn

Response: Returns a validation function that checks whether a value is an integer.


Instruction:
Given the following Python 3 function, write the documentation
def Alphanumeric(msg=None):
    '''
    Checks whether a value is:
        - int, or
        - long, or
        - float without a fractional part, or
        - str or unicode composed only of alphanumeric characters
    '''
    def fn(value):
        if not any([
            isinstance(value, numbers.Integral),
            (isinstance(value, float) and value.is_integer()),
            (isinstance(value, basestring) and value.isalnum())
        ]):
            raise Invalid(msg or (
                'Invalid input <{0}>; expected an integer'.format(value))
            )
        else:
            return value
    return fn

Response: A function that checks whether a value is an integer or a float with a fractional part or a unicode string composed only of alphanumeric characters.


Instruction:
Create a Python 3 function to
check whether a value is: - str or unicode, and - composed of both alphabets and digits

Response:
def StrictlyAlphanumeric(msg=None):
    '''
    Checks whether a value is:
        - str or unicode, and
        - composed of both alphabets and digits
    '''
    def fn(value):
        if not (
            isinstance(value, basestring) and
            value.isalnum() and not
            value.isdigit() and not
            value.isalpha()
        ):
            raise Invalid(msg or (
                'Invalid input <{0}>; expected an integer'.format(value))
            )
        else:
            return value
    return fn


Instruction:
Implement a function in Python 3 to
return a function that checks whether a value is a valid castable datetime object with timezone.

Response:
def DatetimeWithTZ(msg=None):
    '''
    Checks whether a value is :
        - a valid castable datetime object with timezone.
    '''
    def fn(value):
        try:
            date = parse_datetime(value) or parse_date(value)
            if date is not None:
                return date
            else:
                raise ValueError
        except ValueError:
            raise Invalid('<{0}> is not a valid datetime.'.format(value))
    return fn


Instruction:
Can you generate a brief explanation for the following Python 3 code
def CSVofIntegers(msg=None):
    '''
    Checks whether a value is list of integers.
    Returns list of integers or just one integer in
    list if there is only one element in given CSV string.
    '''
    def fn(value):
        try:
            if isinstance(value, basestring):
                if ',' in value:
                    value = list(map(
                        int, filter(
                            bool, list(map(
                                lambda x: x.strip(), value.split(',')
                            ))
                        )
                    ))
                    return value
                else:
                    return [int(value)]
            else:
                raise ValueError
        except ValueError:
            raise Invalid(
                '<{0}> is not a valid csv of integers'.format(value)
            )
    return fn

Response: Returns a function that takes a CSV string and returns a list of integers.


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

        query_params = self.request.query_params
        url_params = self.kwargs

        # get queryset_filters from FilterMixin
        queryset_filters = self.get_db_filters(url_params, query_params)

        # This dict will hold filter kwargs to pass in to Django ORM calls.
        db_filters = queryset_filters['db_filters']

        # This dict will hold exclude kwargs to pass in to Django ORM calls.
        db_excludes = queryset_filters['db_excludes']

        queryset = Team.objects.prefetch_related(
            'players'
        ).all()

        return queryset.filter(**db_filters).exclude(**db_excludes)

Response: Returns a queryset of the items in the current locale.


Instruction:
Write a Python 3 function that can
get a specific setting from the django settings.

Response:
def get_setting(name, default):
    """
    A little helper for fetching global settings with a common prefix.
    """
    parent_name = "CMSPLUGIN_NEWS_{0}".format(name)
    return getattr(django_settings, parent_name, default)


Instruction:
Write a Python 3 function that can
mark selected news items as published

Response:
def make_published(self, request, queryset):
        """
            Marks selected news items as published
        """
        rows_updated = queryset.update(is_published=True)
        self.message_user(request,
                          ungettext('%(count)d newsitem was published',
                                    '%(count)d newsitems were published',
                                    rows_updated) % {'count': rows_updated})


Instruction:
Can you create a Python 3 function that
marks selected news items as unpublished

Response:
def make_unpublished(self, request, queryset):
        """
            Marks selected news items as unpublished
        """
        rows_updated = queryset.update(is_published=False)
        self.message_user(request,
                          ungettext('%(count)d newsitem was unpublished',
                                    '%(count)d newsitems were unpublished',
                                    rows_updated) % {'count': rows_updated})


Instruction:
Can you generate the documentation for the following Python 3 function
def render(self, name, value, attrs=None):
        if value is None:
            value = ''
        value = smart_unicode(value)
        final_attrs = self.build_attrs(attrs)
        final_attrs['name'] = name
        assert 'id' in final_attrs, \
            "TinyMCE widget attributes must contain 'id'"
        mce_config = cms.plugins.text.settings.TINYMCE_CONFIG.copy()
        mce_config.update(get_language_config(self.content_language))
        if tinymce.settings.USE_FILEBROWSER:
            mce_config['file_browser_callback'] = "djangoFileBrowser"
        mce_config.update(self.mce_attrs)
        mce_config['mode'] = 'exact'
        mce_config['elements'] = final_attrs['id']
        mce_config['strict_loading_mode'] = 1
        """
        plugins = mce_config.get("plugins", "")
        if len(plugins):
            plugins += ","
        plugins += "-cmsplugins"
        mce_config['plugins'] = plugins
        adv2 = mce_config.get('theme_advanced_buttons1', "")
        if len(adv2):
            adv2 = "," + adv2
        adv2 = "cmsplugins,cmspluginsedit" + adv2
        mce_config['theme_advanced_buttons1'] = adv2
        """
        json = simplejson.dumps(mce_config)

        html = [u'<textarea%s>%s</textarea>' % (flatatt(final_attrs),
                escape(value))]
        if tinymce.settings.USE_COMPRESSOR:
            compressor_config = {
                'plugins': mce_config.get('plugins', ''),
                'themes': mce_config.get('theme', 'advanced'),
                'languages': mce_config.get('language', ''),
                'diskcache': True,
                'debug': False,
            }
            c_json = simplejson.dumps(compressor_config)
            html.append(
                (u'<script type="text/javascript">'
                    'tinyMCE_GZ.init(%s);</script>') % (c_json))
        html.append(
            (u'<script type="text/javascript">%s;\ntinyMCE.init(%s);'
                '</script>') % (
                self.render_additions(
                    name,
                    value,
                    attrs),
                    json))
        return mark_safe(u'\n'.join(html))

Response: Render the TinyMCE widget.


Instruction:
Given the following Python 3 function, write the documentation
def _execute_wk(*args, input=None):
    wk_args = (WK_PATH,) + args
    return subprocess.run(wk_args, input=input, stdout=subprocess.PIPE, stderr=subprocess.PIPE)

Response: Generate path for the wkhtmltopdf binary and execute command.


Instruction:
Can you implement a function in Python 3 that
generates a pdf from a string or url.

Response:
def generate_pdf(html, *,
                 cache_dir: Path=DFT_CACHE_DIR,
                 grayscale: bool=False,
                 lowquality: bool=False,
                 margin_bottom: str=None,
                 margin_left: str=None,
                 margin_right: str=None,
                 margin_top: str=None,
                 orientation: str=None,
                 page_height: str=None,
                 page_width: str=None,
                 page_size: str=None,
                 image_dpi: str=None,
                 image_quality: str=None,
                 **extra_kwargs):
    """
    Generate a pdf from either a url or a html string.

    After the html and url arguments all other arguments are
    passed straight to wkhtmltopdf

    For details on extra arguments see the output of get_help()
    and get_extended_help()

    All arguments whether specified or caught with extra_kwargs are converted
    to command line args with "'--' + original_name.replace('_', '-')"

    Arguments which are True are passed with no value eg. just --quiet, False
    and None arguments are missed, everything else is passed with str(value).

    :param html: html string to generate pdf from
    :param grayscale: bool
    :param lowquality: bool
    :param margin_bottom: string eg. 10mm
    :param margin_left: string eg. 10mm
    :param margin_right: string eg. 10mm
    :param margin_top: string eg. 10mm
    :param orientation: Portrait or Landscape
    :param page_height: string eg. 10mm
    :param page_width: string eg. 10mm
    :param page_size: string: A4, Letter, etc.
    :param image_dpi: int default 600
    :param image_quality: int default 94
    :param extra_kwargs: any exotic extra options for wkhtmltopdf
    :return: string representing pdf
    """
    if not cache_dir.exists():
        Path.mkdir(cache_dir)

    py_args = dict(
        cache_dir=cache_dir,
        grayscale=grayscale,
        lowquality=lowquality,
        margin_bottom=margin_bottom,
        margin_left=margin_left,
        margin_right=margin_right,
        margin_top=margin_top,
        orientation=orientation,
        page_height=page_height,
        page_width=page_width,
        page_size=page_size,
        image_dpi=image_dpi,
        image_quality=image_quality,
    )
    py_args.update(extra_kwargs)
    cmd_args = _convert_args(**py_args)

    p = _execute_wk(*cmd_args, input=html.encode())
    pdf_content = p.stdout

    # it seems wkhtmltopdf's error codes can be false, we'll ignore them if we
    # seem to have generated a pdf
    if p.returncode != 0 and pdf_content[:4] != b'%PDF':
        raise RuntimeError('error running wkhtmltopdf, command: {!r}\n'
                           'response: "{}"'.format(cmd_args, p.stderr.decode().strip()))
    return pdf_content


Instruction:
Can you tell what is the following Python 3 function doing
def get_version():
    try:
        wk_version = _string_execute('-V')
    except Exception as e:
        # we catch all errors here to make sure we get a version no matter what
        wk_version = '%s: %s' % (e.__class__.__name__, e)
    return 'pydf version: %s\nwkhtmltopdf version: %s' % (VERSION, wk_version)

Response: Get version of pydf and wkhtmltopdf


Instruction:
Create a Python 3 function for
performing sctring escape - for regexp literals

Response:
def _interpret_regexp(self, string, flags):
        '''Perform sctring escape - for regexp literals'''
        self.index = 0
        self.length = len(string)
        self.source = string
        self.lineNumber = 0
        self.lineStart = 0
        octal = False
        st = ''
        inside_square = 0
        while (self.index < self.length):
            template = '[%s]' if not inside_square else '%s'
            ch = self.source[self.index]
            self.index += 1
            if ch == '\\':
                ch = self.source[self.index]
                self.index += 1
                if (not isLineTerminator(ch)):
                    if ch == 'u':
                        digs = self.source[self.index:self.index + 4]
                        if len(digs) == 4 and all(isHexDigit(d) for d in digs):
                            st += template % unichr(int(digs, 16))
                            self.index += 4
                        else:
                            st += 'u'
                    elif ch == 'x':
                        digs = self.source[self.index:self.index + 2]
                        if len(digs) == 2 and all(isHexDigit(d) for d in digs):
                            st += template % unichr(int(digs, 16))
                            self.index += 2
                        else:
                            st += 'x'
                    # special meaning - single char.
                    elif ch == '0':
                        st += '\\0'
                    elif ch == 'n':
                        st += '\\n'
                    elif ch == 'r':
                        st += '\\r'
                    elif ch == 't':
                        st += '\\t'
                    elif ch == 'f':
                        st += '\\f'
                    elif ch == 'v':
                        st += '\\v'

                    # unescape special single characters like . so that they are interpreted literally
                    elif ch in REGEXP_SPECIAL_SINGLE:
                        st += '\\' + ch

                    # character groups
                    elif ch == 'b':
                        st += '\\b'
                    elif ch == 'B':
                        st += '\\B'
                    elif ch == 'w':
                        st += '\\w'
                    elif ch == 'W':
                        st += '\\W'
                    elif ch == 'd':
                        st += '\\d'
                    elif ch == 'D':
                        st += '\\D'
                    elif ch == 's':
                        st += template % u' \f\n\r\t\v\u00a0\u1680\u180e\u2000-\u200a\u2028\u2029\u202f\u205f\u3000\ufeff'
                    elif ch == 'S':
                        st += template % u'\u0000-\u0008\u000e-\u001f\u0021-\u009f\u00a1-\u167f\u1681-\u180d\u180f-\u1fff\u200b-\u2027\u202a-\u202e\u2030-\u205e\u2060-\u2fff\u3001-\ufefe\uff00-\uffff'
                    else:
                        if isDecimalDigit(ch):
                            num = ch
                            while self.index < self.length and isDecimalDigit(
                                    self.source[self.index]):
                                num += self.source[self.index]
                                self.index += 1
                            st += '\\' + num

                        else:
                            st += ch  # DONT ESCAPE!!!
                else:
                    self.lineNumber += 1
                    if (ch == '\r' and self.source[self.index] == '\n'):
                        self.index += 1
                    self.lineStart = self.index
            else:
                if ch == '[':
                    inside_square = True
                elif ch == ']':
                    inside_square = False
                st += ch
        # print string, 'was transformed to', st
        return st


Instruction:
Implement a Python 3 function for
searching Crossref works for a set of DOIs.

Response:
def works(self, ids = None, query = None, filter = None, offset = None,
              limit = None, sample = None, sort = None,
              order = None, facet = None, select = None, cursor = None,
              cursor_max = 5000, **kwargs):
        '''
        Search Crossref works

        :param ids: [Array] DOIs (digital object identifier) or other identifiers
        :param query: [String] A query string
        :param filter: [Hash] Filter options. See examples for usage.
            Accepts a dict, with filter names and their values. For repeating filter names
            pass in a list of the values to that filter name, e.g.,
            `{'award_funder': ['10.13039/100004440', '10.13039/100000861']}`.
            See https://github.com/CrossRef/rest-api-doc#filter-names
            for filter names and their descriptions and :func:`~habanero.Crossref.filter_names`
            and :func:`~habanero.Crossref.filter_details`
        :param offset: [Fixnum] Number of record to start at, from 1 to 10000
        :param limit: [Fixnum] Number of results to return. Not relavant when searching with specific dois.
            Default: 20. Max: 1000
        :param sample: [Fixnum] Number of random results to return. when you use the sample parameter,
            the limit and offset parameters are ignored. Max: 100
        :param sort: [String] Field to sort on. Note: If the API call includes a query, then the sort
            order will be by the relevance score. If no query is included, then the sort order
            will be by DOI update date. See sorting_ for possible values.
        :param order: [String] Sort order, one of 'asc' or 'desc'
        :param facet: [Boolean/String] Set to `true` to include facet results (default: false).
            Optionally, pass a query string, e.g., `facet=type-name:*` or `facet=license=*`.
            See Facets_ for options.
        :param select: [String/list(Strings)] Crossref metadata records can be
            quite large. Sometimes you just want a few elements from the schema. You can "select"
            a subset of elements to return. This can make your API calls much more efficient. Not
            clear yet which fields are allowed here.
        :param cursor: [String] Cursor character string to do deep paging. Default is None.
            Pass in '*' to start deep paging. Any combination of query, filters and facets may be
            used with deep paging cursors. While rows may be specified along with cursor, offset
            and sample cannot be used.
            See https://github.com/CrossRef/rest-api-doc/blob/master/rest_api.md#deep-paging-with-cursors
        :param cursor_max: [Fixnum] Max records to retrieve. Only used when cursor param used. Because
            deep paging can result in continuous requests until all are retrieved, use this
            parameter to set a maximum number of records. Of course, if there are less records
            found than this value, you will get only those found.
        :param kwargs: additional named arguments passed on to `requests.get`, e.g., field
            queries (see examples and FieldQueries_)

        :return: A dict

        Usage::

            from habanero import Crossref
            cr = Crossref()
            cr.works()
            cr.works(ids = '10.1371/journal.pone.0033693')
            dois = ['10.1371/journal.pone.0033693', ]
            cr.works(ids = dois)
            x = cr.works(query = "ecology")
            x['status']
            x['message-type']
            x['message-version']
            x['message']
            x['message']['total-results']
            x['message']['items-per-page']
            x['message']['query']
            x['message']['items']

            # Get full text links
            x = cr.works(filter = {'has_full_text': True})
            x

            # Parse output to various data pieces
            x = cr.works(filter = {'has_full_text': True})
            ## get doi for each item
            [ z['DOI'] for z in x['message']['items'] ]
            ## get doi and url for each item
            [ {"doi": z['DOI'], "url": z['URL']} for z in x['message']['items'] ]
            ### print every doi
            for i in x['message']['items']:
                 print i['DOI']

            # filters - pass in as a dict
            ## see https://github.com/CrossRef/rest-api-doc#filter-names
            cr.works(filter = {'has_full_text': True})
            cr.works(filter = {'has_funder': True, 'has_full_text': True})
            cr.works(filter = {'award_number': 'CBET-0756451', 'award_funder': '10.13039/100000001'})
            ## to repeat a filter name, pass in a list
            x = cr.works(filter = {'award_funder': ['10.13039/100004440', '10.13039/100000861']}, limit = 100)
            map(lambda z:z['funder'][0]['DOI'], x['message']['items'])

            # Deep paging, using the cursor parameter
            ## this search should lead to only ~215 results
            cr.works(query = "widget", cursor = "*", cursor_max = 100)
            ## this search should lead to only ~2500 results, in chunks of 500
            res = cr.works(query = "octopus", cursor = "*", limit = 500)
            sum([ len(z['message']['items']) for z in res ])
            ## about 167 results
            res = cr.works(query = "extravagant", cursor = "*", limit = 50, cursor_max = 500)
            sum([ len(z['message']['items']) for z in res ])
            ## cursor_max to get back only a maximum set of results
            res = cr.works(query = "widget", cursor = "*", cursor_max = 100)
            sum([ len(z['message']['items']) for z in res ])
            ## cursor_max - especially useful when a request could be very large
            ### e.g., "ecology" results in ~275K records, lets max at 10,000
            ###   with 1000 at a time
            res = cr.works(query = "ecology", cursor = "*", cursor_max = 10000, limit = 1000)
            sum([ len(z['message']['items']) for z in res ])
            items = [ z['message']['items'] for z in res ]
            items = [ item for sublist in items for item in sublist ]
            [ z['DOI'] for z in items ][0:50]

            # field queries
            res = cr.works(query = "ecology", query_author = 'carl boettiger')
            [ x['author'][0]['family'] for x in res['message']['items'] ]

            # select certain fields to return
            ## as a comma separated string
            cr.works(query = "ecology", select = "DOI,title")
            ## or as a list
            cr.works(query = "ecology", select = ["DOI","title"])
        '''
        if ids.__class__.__name__ != 'NoneType':
            return request(self.mailto, self.base_url, "/works/", ids,
                query, filter, offset, limit, sample, sort,
                order, facet, select, None, None, None, None, **kwargs)
        else:
            return Request(self.mailto, self.base_url, "/works/",
              query, filter, offset, limit, sample, sort,
              order, facet, select, cursor, cursor_max, None, **kwargs).do_request()


Instruction:
Can you tell what is the following Python 3 function doing
def prefixes(self, ids = None, filter = None, offset = None,
              limit = None, sample = None, sort = None,
              order = None, facet = None, works = False, select = None,
              cursor = None, cursor_max = 5000, **kwargs):
        '''
        Search Crossref prefixes

        :param ids: [Array] DOIs (digital object identifier) or other identifiers
        :param filter: [Hash] Filter options. See examples for usage.
            Accepts a dict, with filter names and their values. For repeating filter names
            pass in a list of the values to that filter name, e.g.,
            `{'award_funder': ['10.13039/100004440', '10.13039/100000861']}`.
            See https://github.com/CrossRef/rest-api-doc#filter-names
            for filter names and their descriptions and :func:`~habanero.Crossref.filter_names`
            and :func:`~habanero.Crossref.filter_details`
        :param offset: [Fixnum] Number of record to start at, from 1 to 10000
        :param limit: [Fixnum] Number of results to return. Not relevant when searching with specific dois. Default: 20. Max: 1000
        :param sample: [Fixnum] Number of random results to return. when you use the sample parameter,
            the limit and offset parameters are ignored. This parameter only used when works requested. Max: 100
        :param sort: [String] Field to sort on. Note: If the API call includes a query, then the sort
            order will be by the relevance score. If no query is included, then the sort order
            will be by DOI update date. See sorting_ for possible values.
        :param order: [String] Sort order, one of 'asc' or 'desc'
        :param facet: [Boolean/String] Set to `true` to include facet results (default: false).
            Optionally, pass a query string, e.g., `facet=type-name:*` or `facet=license=*`
            See Facets_ for options.
        :param select: [String/list(Strings)] Crossref metadata records can be
            quite large. Sometimes you just want a few elements from the schema. You can "select"
            a subset of elements to return. This can make your API calls much more efficient. Not
            clear yet which fields are allowed here.
        :param works: [Boolean] If true, works returned as well. Default: false
        :param kwargs: additional named arguments passed on to `requests.get`, e.g., field
            queries (see examples and FieldQueries_)

        :return: A dict

        Usage::

            from habanero import Crossref
            cr = Crossref()
            cr.prefixes(ids = "10.1016")
            cr.prefixes(ids = ['10.1016','10.1371','10.1023','10.4176','10.1093'])

            # get works
            cr.prefixes(ids = "10.1016", works = True)

            # Limit number of results
            cr.prefixes(ids = "10.1016", works = True, limit = 3)

            # Sort and order
            cr.prefixes(ids = "10.1016", works = True, sort = "relevance", order = "asc")

            # cursor - deep paging
            res = cr.prefixes(ids = "10.1016", works = True, cursor = "*", limit = 200)
            sum([ len(z['message']['items']) for z in res ])
            items = [ z['message']['items'] for z in res ]
            items = [ item for sublist in items for item in sublist ]
            [ z['DOI'] for z in items ][0:50]

            # field queries
            res = cr.prefixes(ids = "10.1371", works = True, query_editor = 'cooper', filter = {'type': 'journal-article'})
            eds = [ x.get('editor') for x in res['message']['items'] ]
            [ z for z in eds if z is not None ]
        '''
        check_kwargs(["query"], kwargs)
        return request(self.mailto, self.base_url, "/prefixes/", ids,
          query = None, filter = filter, offset = offset, limit = limit,
          sample = sample, sort = sort, order = order, facet = facet,
          select = select, works = works, cursor = cursor, cursor_max = cursor_max,
          **kwargs)

Response: Search Crossref prefixes for a set of DOIs.


Instruction:
Given the following Python 3 function, write the documentation
def types(self, ids = None, query = None, filter = None, offset = None,
              limit = None, sample = None, sort = None,
              order = None, facet = None, works = False, select = None,
              cursor = None, cursor_max = 5000, **kwargs):
        '''
        Search Crossref types

        :param ids: [Array] Type identifier, e.g., journal
        :param query: [String] A query string
        :param filter: [Hash] Filter options. See examples for usage.
            Accepts a dict, with filter names and their values. For repeating filter names
            pass in a list of the values to that filter name, e.g.,
            `{'award_funder': ['10.13039/100004440', '10.13039/100000861']}`.
            See https://github.com/CrossRef/rest-api-doc#filter-names
            for filter names and their descriptions and :func:`~habanero.Crossref.filter_names`
            and :func:`~habanero.Crossref.filter_details`
        :param offset: [Fixnum] Number of record to start at, from 1 to 10000
        :param limit: [Fixnum] Number of results to return. Not relevant when searching with specific dois. Default: 20. Max: 1000
        :param sample: [Fixnum] Number of random results to return. when you use the sample parameter,
            the limit and offset parameters are ignored. This parameter only used when works requested. Max: 100
        :param sort: [String] Field to sort on. Note: If the API call includes a query, then the sort
            order will be by the relevance score. If no query is included, then the sort order
            will be by DOI update date. See sorting_ for possible values.
        :param order: [String] Sort order, one of 'asc' or 'desc'
        :param facet: [Boolean/String] Set to `true` to include facet results (default: false).
            Optionally, pass a query string, e.g., `facet=type-name:*` or `facet=license=*`
            See Facets_ for options.
        :param select: [String/list(Strings)] Crossref metadata records can be
            quite large. Sometimes you just want a few elements from the schema. You can "select"
            a subset of elements to return. This can make your API calls much more efficient. Not
            clear yet which fields are allowed here.
        :param works: [Boolean] If true, works returned as well. Default: false
        :param kwargs: additional named arguments passed on to `requests.get`, e.g., field
            queries (see examples and FieldQueries_)

        :return: A dict

        Usage::

            from habanero import Crossref
            cr = Crossref()
            cr.types()
            cr.types(ids = "journal")
            cr.types(ids = "journal-article")
            cr.types(ids = "journal", works = True)

            # field queries
            res = cr.types(ids = "journal-article", works = True, query_title = 'gender', rows = 100)
            [ x.get('title') for x in res['message']['items'] ]
        '''
        return request(self.mailto, self.base_url, "/types/", ids,
            query, filter, offset, limit, sample, sort,
            order, facet, select, works, cursor, cursor_max, **kwargs)

Response: Search Crossref types in the specified list of type identifiers.


Instruction:
Given the following Python 3 function, write the documentation
def licenses(self, query = None, offset = None,
              limit = None, sample = None, sort = None,
              order = None, facet = None, **kwargs):
        '''
        Search Crossref licenses

        :param query: [String] A query string
        :param offset: [Fixnum] Number of record to start at, from 1 to 10000
        :param limit: [Fixnum] Number of results to return. Not relevant when searching with specific dois. Default: 20. Max: 1000
        :param sort: [String] Field to sort on. Note: If the API call includes a query, then the sort
            order will be by the relevance score. If no query is included, then the sort order
            will be by DOI update date. See sorting_ for possible values.
        :param order: [String] Sort order, one of 'asc' or 'desc'
        :param facet: [Boolean/String] Set to `true` to include facet results (default: false).
            Optionally, pass a query string, e.g., `facet=type-name:*` or `facet=license=*`
            See Facets_ for options.
        :param kwargs: additional named arguments passed on to `requests.get`, e.g., field
            queries (see examples and FieldQueries_)

        :return: A dict

        Usage::

            from habanero import Crossref
            cr = Crossref()
            cr.licenses()
            cr.licenses(query = "creative")
        '''
        check_kwargs(["ids", "filter", "works"], kwargs)
        res = request(self.mailto, self.base_url, "/licenses/", None,
            query, None, offset, limit, None, sort,
            order, facet, None, None, None, None, **kwargs)
        return res

Response: Search Crossref licenses for a specific set of dois.


Instruction:
Make a summary of the following Python 3 code
def registration_agency(self, ids, **kwargs):
        '''
        Determine registration agency for DOIs

        :param ids: [Array] DOIs (digital object identifier) or other identifiers
        :param kwargs: additional named arguments passed on to `requests.get`, e.g., field
            queries (see examples)

        :return: list of DOI minting agencies

        Usage::

            from habanero import Crossref
            cr = Crossref()
            cr.registration_agency('10.1371/journal.pone.0033693')
            cr.registration_agency(ids = ['10.1007/12080.1874-1746','10.1007/10452.1573-5125', '10.1111/(issn)1442-9993'])
        '''
        check_kwargs(["query", "filter", "offset", "limit", "sample", "sort",
            "order", "facet", "works"], kwargs)
        res = request(self.mailto, self.base_url, "/works/", ids,
            None, None, None, None, None, None,
            None, None, None, None, None, None, True, **kwargs)
        if res.__class__ != list:
            k = []
            k.append(res)
        else:
            k = res
        return [ z['message']['agency']['label'] for z in k ]

Response: Determine registration agency for a list of DOIs.


Instruction:
Given the following Python 3 function, write the documentation
def random_dois(self, sample = 10, **kwargs):
        '''
        Get a random set of DOIs

        :param sample: [Fixnum] Number of random DOIs to return. Default: 10. Max: 100
        :param kwargs: additional named arguments passed on to `requests.get`, e.g., field
            queries (see examples)

        :return: [Array] of DOIs

        Usage::

            from habanero import Crossref
            cr = Crossref()
            cr.random_dois(1)
            cr.random_dois(10)
            cr.random_dois(50)
            cr.random_dois(100)
        '''
        res = request(self.mailto, self.base_url, "/works/", None,
            None, None, None, None, sample, None,
            None, None, None, True, None, None, None, **kwargs)
        return [ z['DOI'] for z in res['message']['items'] ]

Response: Get a random set of DOIs.


Instruction:
Write a Python 3 script to
get list of CSL styles from github. com. citation - style - language. styles

Response:
def csl_styles(**kwargs):
  '''
  Get list of styles from https://github.com/citation-style-language/styles

  :param kwargs: any additional arguments will be passed on to `requests.get`

  :return: list, of CSL styles

  Usage::

      from habanero import cn
      cn.csl_styles()
  '''
  base = "https://api.github.com/repos/citation-style-language/styles"
  tt = requests.get(base + '/commits?per_page=1', **kwargs)
  tt.raise_for_status()
  check_json(tt)
  commres = tt.json()
  sha = commres[0]['sha']
  sty = requests.get(base + "/git/trees/" + sha, **kwargs)
  sty.raise_for_status()
  check_json(sty)
  res = sty.json()
  files = [ z['path'] for z in res['tree'] ]
  matches = [ re.search(".csl", g) for g in files ]
  csls = [ x.string for x in filter(None, matches) ]
  return [ re.sub(".csl", "", x) for x in csls ]


Instruction:
How would you code a function in Python 3 to
get the content negotiation of the given list of DOIs in various formats.

Response:
def content_negotiation(ids = None, format = "bibtex", style = 'apa',
    locale = "en-US", url = None, **kwargs):
    '''
    Get citations in various formats from CrossRef

    :param ids: [str] Search by a single DOI or many DOIs, each a string. If many
        passed in, do so in a list
    :param format: [str] Name of the format. One of "rdf-xml", "turtle", "citeproc-json",
        "citeproc-json-ish", "text", "ris", "bibtex" (Default), "crossref-xml",
        "datacite-xml","bibentry", or "crossref-tdm"
    :param style: [str] A CSL style (for text format only). See :func:`~habanero.cn.csl_styles`
        for options. Default: "apa". If there's a style that CrossRef doesn't support
        you'll get a `(500) Internal Server Error`
    :param locale: [str] Language locale. See `locale.locale_alias`
    :param url: [str] Base URL for the content negotiation request. Default: `https://doi.org`
    :param kwargs: any additional arguments will be passed on to `requests.get`

    :return: string, which can be parsed to various formats depending on what
        format you request (e.g., JSON vs. XML vs. bibtex)

    Usage::

        from habanero import cn
        cn.content_negotiation(ids = '10.1126/science.169.3946.635')

        # get citeproc-json
        cn.content_negotiation(ids = '10.1126/science.169.3946.635', format = "citeproc-json")

        # some other formats
        cn.content_negotiation(ids = "10.1126/science.169.3946.635", format = "rdf-xml")
        cn.content_negotiation(ids = "10.1126/science.169.3946.635", format = "crossref-xml")
        cn.content_negotiation(ids = "10.1126/science.169.3946.635", format = "text")

        # return an R bibentry type
        cn.content_negotiation(ids = "10.1126/science.169.3946.635", format = "bibentry")
        cn.content_negotiation(ids = "10.6084/m9.figshare.97218", format = "bibentry")

        # return an apa style citation
        cn.content_negotiation(ids = "10.1126/science.169.3946.635", format = "text", style = "apa")
        cn.content_negotiation(ids = "10.1126/science.169.3946.635", format = "text", style = "harvard3")
        cn.content_negotiation(ids = "10.1126/science.169.3946.635", format = "text", style = "elsevier-harvard")
        cn.content_negotiation(ids = "10.1126/science.169.3946.635", format = "text", style = "ecoscience")
        cn.content_negotiation(ids = "10.1126/science.169.3946.635", format = "text", style = "heredity")
        cn.content_negotiation(ids = "10.1126/science.169.3946.635", format = "text", style = "oikos")

        # Using DataCite DOIs
        ## some formats don't work
        # cn.content_negotiation(ids = "10.5284/1011335", format = "text")
        # cn.content_negotiation(ids = "10.5284/1011335", format = "crossref-xml")
        # cn.content_negotiation(ids = "10.5284/1011335", format = "crossref-tdm")

        ## But most do work
        cn.content_negotiation(ids = "10.5284/1011335", format = "datacite-xml")
        cn.content_negotiation(ids = "10.5284/1011335", format = "rdf-xml")
        cn.content_negotiation(ids = "10.5284/1011335", format = "turtle")
        cn.content_negotiation(ids = "10.5284/1011335", format = "citeproc-json")
        cn.content_negotiation(ids = "10.5284/1011335", format = "ris")
        cn.content_negotiation(ids = "10.5284/1011335", format = "bibtex")
        cn.content_negotiation(ids = "10.5284/1011335", format = "bibentry")
        cn.content_negotiation(ids = "10.5284/1011335", format = "bibtex")

        # many DOIs
        dois = ['10.5167/UZH-30455','10.5167/UZH-49216','10.5167/UZH-503', '10.5167/UZH-38402','10.5167/UZH-41217']
        x = cn.content_negotiation(ids = dois)

        # Use a different base url
        url = "http://dx.doi.org"
        cn.content_negotiation(ids = "10.1126/science.169.3946.635", url = url)
        cn.content_negotiation(ids = "10.5284/1011335", url = url)
    '''
    if url is None:
        url = cn_base_url
    return CNRequest(url, ids, format, style, locale, **kwargs)


Instruction:
Can you tell what is the following Python 3 function doing
def citation_count(doi, url = "http://www.crossref.org/openurl/",
    key = "cboettig@ropensci.org", **kwargs):
    '''
    Get a citation count with a DOI

    :param doi: [String] DOI, digital object identifier
    :param url: [String] the API url for the function (should be left to default)
    :param keyc: [String] your API key

    See http://labs.crossref.org/openurl/ for more info on this Crossref API service.

    Usage::

        from habanero import counts
        counts.citation_count(doi = "10.1371/journal.pone.0042793")
        counts.citation_count(doi = "10.1016/j.fbr.2012.01.001")
        # DOI not found
        ## FIXME
        counts.citation_count(doi = "10.1016/j.fbr.2012")
    '''
    args = {"id": "doi:" + doi, "pid": key, "noredirect": True}
    args = dict((k, v) for k, v in args.items() if v)
    res = requests.get(url, params = args, headers = make_ua(), **kwargs)
    xmldoc = minidom.parseString(res.content)
    val = xmldoc.getElementsByTagName('query')[0].attributes['fl_count'].value
    return int(str(val))

Response: Get a citation count with a DOI


Instruction:
Can you generate a brief explanation for the following Python 3 code
def findHierarchy(self, max_subs=10):
        hierarchy = []
        defaults = TOC.default_hierarchy + tuple(
            '%ssection' % ('sub'*i) for i in range(2, max_subs))
        for level in defaults:
            if getattr(self.source, level, False):
                hierarchy.append(level)
        return tuple(hierarchy)

Response: Find hierarchy for the LaTeX source.


Instruction:
Here you have a function in Python 3, explain what it does
def getHeadingLevel(ts, hierarchy=default_hierarchy):
        try:
            return hierarchy.index(ts.name)+1
        except ValueError:
            if ts.name.endswith('section'):
                i, name = 0, ts.name
                while name.startswith('sub'):
                    name, i = name[3:], i+1
                if name == 'section':
                    return i+2
            return float('inf')
        except (AttributeError, TypeError):
            return float('inf')

Response: Extract the heading level for a particular Tex element given a specified hierarchy.


Instruction:
Create a Python 3 function to
parse tex for highest tag in hierarchy

Response:
def parseTopDepth(self, descendants=()):
        """Parse tex for highest tag in hierarchy

        >>> TOC.fromLatex('\\section{Hah}\\subsection{No}').parseTopDepth()
        1
        >>> s = '\\subsubsubsection{Yo}\\subsubsection{Hah}'
        >>> TOC.fromLatex(s).parseTopDepth()
        1
        >>> h = ('section', 'subsubsection', 'subsubsubsection')
        >>> TOC.fromLatex(s, hierarchy=h).parseTopDepth()
        2
        """
        descendants = list(descendants) or \
            list(getattr(self.source, 'descendants', descendants))
        if not descendants:
            return -1
        return min(TOC.getHeadingLevel(e, self.hierarchy) for e in descendants)


Instruction:
Explain what the following Python 3 code does
def parseBranches(self, descendants):
        i, branches = self.parseTopDepth(descendants), []
        for descendant in descendants:
            if self.getHeadingLevel(descendant, self.hierarchy) == i:
                branches.append({'source': descendant})
            if self.getHeadingLevel(descendant, self.hierarchy) > i \
                and branches:
                branches[-1].setdefault('descendants', []).append(descendant)
        return [TOC(str(descendant), depth=i, hierarchy=self.hierarchy,
            **branch) for branch in branches]

Response:
Parse top level of latex
        and return a list of filtered TreeOfContents objects.


Instruction:
Can you write a function in Python 3 where it
creates abstraction using path to file xid

Response:
def fromFile(path_or_buffer):
        """Creates abstraction using path to file

        :param str path_or_buffer: path to tex file or buffer
        :return: TreeOfContents object
        """
        return TOC.fromLatex(open(path_or_buffer).read()
                             if isinstance(path_or_buffer, str)
                             else path_or_buffer)


Instruction:
Can you tell what is the following Python 3 function doing
def fromLatex(tex, *args, **kwargs):
        source = TexSoup(tex)
        return TOC('[document]', source=source,
            descendants=list(source.descendants), *args, **kwargs)

Response: Creates a TreeOfContents object from a Latex string.


Instruction:
Write a Python 3 function that can
check and prepare options dict.

Response:
def process_options(opts):
    """Check and prepare options dict."""
    # Convert match and exclude args into pattern lists
    match = opts.get("match")
    if match and type(match) is str:
        opts["match"] = [pat.strip() for pat in match.split(",")]
    elif match:
        assert type(match) is list
    else:
        opts["match"] = []

    exclude = opts.get("exclude")
    if exclude and type(exclude) is str:
        opts["exclude"] = [pat.strip() for pat in exclude.split(",")]
    elif exclude:
        assert type(exclude) is list
    else:
        # opts["exclude"] = DEFAULT_OMIT
        opts["exclude"] = []


Instruction:
Can you implement a function in Python 3 that
returns True if path matches match and exclude options.

Response:
def match_path(entry, opts):
    """Return True if `path` matches `match` and `exclude` options."""
    if entry.name in ALWAYS_OMIT:
        return False
    # TODO: currently we use fnmatch syntax and match against names.
    # We also might allow glob syntax and match against the whole relative path instead
    # path = entry.get_rel_path()
    path = entry.name
    ok = True
    match = opts.get("match")
    exclude = opts.get("exclude")
    if entry.is_file() and match:
        assert type(match) is list
        ok = False
        for pat in match:
            if fnmatch.fnmatch(path, pat):
                ok = True
                break
    if ok and exclude:
        assert type(exclude) is list
        for pat in exclude:
            if fnmatch.fnmatch(path, pat):
                ok = False
                break
    # write("match", ok, entry)
    return ok


Instruction:
Can you generate a brief explanation for the following Python 3 code
def _compare_file(self, local, remote):
        assert isinstance(local, FileEntry) and isinstance(remote, FileEntry)

        if not local or not remote:
            write("    Files cannot be compared ({} != {}).".format(local, remote))
            return False
        elif local.size != remote.size:
            write(
                "    Files are different (size {:,d} != {:,d}).".format(
                    local.size, remote.size
                )
            )
            return False

        with local.target.open_readable(
            local.name
        ) as fp_src, remote.target.open_readable(remote.name) as fp_dest:
            res, ofs = byte_compare(fp_src, fp_dest)

        if not res:
            write("    Files are different at offset {:,d}.".format(ofs))
        else:
            write("    Files are equal.")
        return res

Response: Byte compare two file entries.


Instruction:
Implement a Python 3 function for
writing progress info and move cursor to beginning of line.

Response:
def _tick(self):
        """Write progress info and move cursor to beginning of line."""
        if (self.verbose >= 3 and not IS_REDIRECTED) or self.options.get("progress"):
            stats = self.get_stats()
            prefix = DRY_RUN_PREFIX if self.dry_run else ""
            sys.stdout.write(
                "{}Touched {}/{} entries in {} directories...\r".format(
                    prefix,
                    stats["entries_touched"],
                    stats["entries_seen"],
                    stats["local_dirs"],
                )
            )
        sys.stdout.flush()
        return


Instruction:
Write a Python 3 function that can
traverse the local folder structure and remote peers and create a new entry pair.

Response:
def _sync_dir(self):
        """Traverse the local folder structure and remote peers.

        This is the core algorithm that generates calls to self.sync_XXX()
        handler methods.
        _sync_dir() is called by self.run().
        """
        local_entries = self.local.get_dir()
        # Convert into a dict {name: FileEntry, ...}
        local_entry_map = dict(map(lambda e: (e.name, e), local_entries))

        remote_entries = self.remote.get_dir()
        # Convert into a dict {name: FileEntry, ...}
        remote_entry_map = dict(map(lambda e: (e.name, e), remote_entries))

        entry_pair_list = []

        # 1. Loop over all local files and classify the relationship to the
        #    peer entries.
        for local_entry in local_entries:
            if isinstance(local_entry, DirectoryEntry):
                self._inc_stat("local_dirs")
            else:
                self._inc_stat("local_files")

            if not self._before_sync(local_entry):
                # TODO: currently, if a file is skipped, it will not be
                # considered for deletion on the peer target
                continue
            # TODO: case insensitive?
            # We should use os.path.normcase() to convert to lowercase on windows
            # (i.e. if the FTP server is based on Windows)
            remote_entry = remote_entry_map.get(local_entry.name)

            entry_pair = EntryPair(local_entry, remote_entry)
            entry_pair_list.append(entry_pair)

            # TODO: renaming could be triggered, if we find an existing
            # entry.unique with a different entry.name

        # 2. Collect all remote entries that do NOT exist on the local target.
        for remote_entry in remote_entries:
            if isinstance(remote_entry, DirectoryEntry):
                self._inc_stat("remote_dirs")
            else:
                self._inc_stat("remote_files")

            if not self._before_sync(remote_entry):
                continue

            if remote_entry.name not in local_entry_map:
                entry_pair = EntryPair(None, remote_entry)
                entry_pair_list.append(entry_pair)
                # print("NOT IN LOCAL")
                # print(remote_entry.name)
                # print(self.remote.get_id())
                # print(local_entry_map.keys())
                # print(self.local.cur_dir_meta.peer_sync.get(self.remote.get_id()))

        # 3. Classify all entries and pairs.
        #    We pass the additional meta data here
        peer_dir_meta = self.local.cur_dir_meta.peer_sync.get(self.remote.get_id())

        for pair in entry_pair_list:
            pair.classify(peer_dir_meta)

        # 4. Perform (or schedule) resulting file operations
        for pair in entry_pair_list:

            # print(pair)

            # Let synchronizer modify the default operation (e.g. apply `--force` option)
            hook_result = self.re_classify_pair(pair)

            # Let synchronizer implement special handling of unmatched entries
            # (e.g. `--delete_unmatched`)
            if not self._match(pair.any_entry):
                self.on_mismatch(pair)
                # ... do not call operation handler...
            elif hook_result is not False:
                handler = getattr(self, "on_" + pair.operation, None)
                # print(handler)
                if handler:
                    try:
                        res = handler(pair)
                    except Exception as e:
                        if self.on_error(e, pair) is not True:
                            raise
                else:
                    # write("NO HANDLER")
                    raise NotImplementedError("No handler for {}".format(pair))

            if pair.is_conflict():
                self._inc_stat("conflict_files")

        # 5. Let the target provider write its meta data for the files in the
        #    current directory.
        self.local.flush_meta()
        self.remote.flush_meta()

        # 6. Finally visit all local sub-directories recursively that also
        #    exist on the remote target.
        for local_dir in local_entries:
            # write("local_dir(%s, %s)" % (local_dir, local_dir))
            if not local_dir.is_dir():
                continue
            elif not self._before_sync(local_dir):
                continue

            remote_dir = remote_entry_map.get(local_dir.name)
            if remote_dir:
                # write("sync_equal_dir(%s, %s)" % (local_dir, remote_dir))
                # self._log_call("sync_equal_dir(%s, %s)" % (local_dir, remote_dir))
                # res = self.sync_equal_dir(local_dir, remote_dir)
                # res = self.on_equal(local_dir, remote_dir)
                if res is not False:
                    self.local.cwd(local_dir.name)
                    self.remote.cwd(local_dir.name)
                    self._sync_dir()
                    self.local.cwd("..")
                    self.remote.cwd("..")

        return True