Instruction:
Write a Python 3 function for
ensuring keys in hashes - type properties are no more than 30 characters long.

Response:
def hash_length(instance):
    """Ensure keys in 'hashes'-type properties are no more than 30 characters long.
    """
    for key, obj in instance['objects'].items():
        if 'type' not in obj:
            continue

        if obj['type'] == 'file':
            try:
                hashes = obj['hashes']
            except KeyError:
                pass
            else:
                for h in hashes:
                    if (len(h) > 30):
                        yield JSONError("Object '%s' has a 'hashes' dictionary"
                                        " with a hash of type '%s', which is "
                                        "longer than 30 characters."
                                        % (key, h), instance['id'], 'hash-algo')

            try:
                ads = obj['extensions']['ntfs-ext']['alternate_data_streams']
            except KeyError:
                pass
            else:
                for datastream in ads:
                    if 'hashes' not in datastream:
                        continue
                    for h in datastream['hashes']:
                        if (len(h) > 30):
                            yield JSONError("Object '%s' has an NTFS extension"
                                            " with an alternate data stream that has a"
                                            " 'hashes' dictionary with a hash of type "
                                            "'%s', which is longer than 30 "
                                            "characters."
                                            % (key, h), instance['id'], 'hash-algo')

            try:
                head_hashes = obj['extensions']['windows-pebinary-ext']['file_header_hashes']
            except KeyError:
                pass
            else:
                for h in head_hashes:
                    if (len(h) > 30):
                        yield JSONError("Object '%s' has a Windows PE Binary "
                                        "File extension with a file header hash of "
                                        "'%s', which is longer than 30 "
                                        "characters."
                                        % (key, h), instance['id'], 'hash-algo')

            try:
                hashes = obj['extensions']['windows-pebinary-ext']['optional_header']['hashes']
            except KeyError:
                pass
            else:
                for h in hashes:
                    if (len(h) > 30):
                        yield JSONError("Object '%s' has a Windows PE Binary "
                                        "File extension with an optional header that "
                                        "has a hash of '%s', which is longer "
                                        "than 30 characters."
                                        % (key, h), instance['id'], 'hash-algo')

            try:
                sections = obj['extensions']['windows-pebinary-ext']['sections']
            except KeyError:
                pass
            else:
                for s in sections:
                    if 'hashes' not in s:
                        continue
                    for h in s['hashes']:
                        if (len(h) > 30):
                            yield JSONError("Object '%s' has a Windows PE "
                                            "Binary File extension with a section that"
                                            " has a hash of '%s', which is "
                                            "longer than 30 characters."
                                            % (key, h), instance['id'], 'hash-algo')

        elif obj['type'] == 'artifact' or obj['type'] == 'x509-certificate':
            try:
                hashes = obj['hashes']
            except KeyError:
                pass
            else:
                for h in hashes:
                    if (len(h) > 30):
                        yield JSONError("Object '%s' has a 'hashes' dictionary"
                                        " with a hash of type '%s', which is "
                                        "longer than 30 characters."
                                        % (key, h), instance['id'], 'hash-algo')


Instruction:
Can you generate the documentation for the following Python 3 function
def duplicate_ids(instance):
    if instance['type'] != 'bundle' or 'objects' not in instance:
        return

    unique_ids = {}
    for obj in instance['objects']:
        if 'id' not in obj or 'modified' not in obj:
            continue
        elif obj['id'] not in unique_ids:
            unique_ids[obj['id']] = obj['modified']
        elif obj['modified'] == unique_ids[obj['id']]:
            yield JSONError("Duplicate ID '%s' has identical `modified` timestamp."
                            " If they are different versions of the same object, "
                            "they should have different `modified` properties."
                            % obj['id'], instance['id'], 'duplicate-ids')

Response: Ensure objects with duplicate IDs have different modified timestamps.


Instruction:
Write a Python 3 function for
constructing the list of SHOULD validators to be run by the validator.

Response:
def list_shoulds(options):
    """Construct the list of 'SHOULD' validators to be run by the validator.
    """
    validator_list = []

    # Default: enable all
    if not options.disabled and not options.enabled:
        validator_list.extend(CHECKS['all'])
        return validator_list

    # --disable
    # Add SHOULD requirements to the list unless disabled
    if options.disabled:
        if 'all' not in options.disabled:
            if 'format-checks' not in options.disabled:
                if 'custom-prefix' not in options.disabled:
                    validator_list.append(CHECKS['custom-prefix'])
                elif 'custom-prefix-lax' not in options.disabled:
                    validator_list.append(CHECKS['custom-prefix-lax'])
                if 'open-vocab-format' not in options.disabled:
                    validator_list.append(CHECKS['open-vocab-format'])
                if 'kill-chain-names' not in options.disabled:
                    validator_list.append(CHECKS['kill-chain-names'])
                if 'observable-object-keys' not in options.disabled:
                    validator_list.append(CHECKS['observable-object-keys'])
                if 'observable-dictionary-keys' not in options.disabled:
                    validator_list.append(CHECKS['observable-dictionary-keys'])
                if 'windows-process-priority-format' not in options.disabled:
                    validator_list.append(CHECKS['windows-process-priority-format'])
                if 'hash-length' not in options.disabled:
                    validator_list.append(CHECKS['hash-length'])

            if 'approved-values' not in options.disabled:
                if 'marking-definition-type' not in options.disabled:
                    validator_list.append(CHECKS['marking-definition-type'])
                if 'relationship-types' not in options.disabled:
                    validator_list.append(CHECKS['relationship-types'])
                if 'duplicate-ids' not in options.disabled:
                    validator_list.append(CHECKS['duplicate-ids'])
                if 'all-vocabs' not in options.disabled:
                    if 'attack-motivation' not in options.disabled:
                        validator_list.append(CHECKS['attack-motivation'])
                    if 'attack-resource-level' not in options.disabled:
                        validator_list.append(CHECKS['attack-resource-level'])
                    if 'identity-class' not in options.disabled:
                        validator_list.append(CHECKS['identity-class'])
                    if 'indicator-types' not in options.disabled:
                        validator_list.append(CHECKS['indicator-types'])
                    if 'industry-sector' not in options.disabled:
                        validator_list.append(CHECKS['industry-sector'])
                    if 'malware-types' not in options.disabled:
                        validator_list.append(CHECKS['malware-types'])
                    if 'report-types' not in options.disabled:
                        validator_list.append(CHECKS['report-types'])
                    if 'threat-actor-types' not in options.disabled:
                        validator_list.append(CHECKS['threat-actor-types'])
                    if 'threat-actor-role' not in options.disabled:
                        validator_list.append(CHECKS['threat-actor-role'])
                    if 'threat-actor-sophistication' not in options.disabled:
                        validator_list.append(CHECKS['threat-actor-sophistication'])
                    if 'tool-types' not in options.disabled:
                        validator_list.append(CHECKS['tool-types'])
                    if 'region' not in options.disabled:
                        validator_list.append(CHECKS['region'])
                    if 'hash-algo' not in options.disabled:
                        validator_list.append(CHECKS['hash-algo'])
                    if 'windows-pebinary-type' not in options.disabled:
                        validator_list.append(CHECKS['windows-pebinary-type'])
                    if 'account-type' not in options.disabled:
                        validator_list.append(CHECKS['account-type'])
                if 'all-external-sources' not in options.disabled:
                    if 'mime-type' not in options.disabled:
                        validator_list.append(CHECKS['mime-type'])
                    if 'protocols' not in options.disabled:
                        validator_list.append(CHECKS['protocols'])
                    if 'ipfix' not in options.disabled:
                        validator_list.append(CHECKS['ipfix'])
                    if 'http-request-headers' not in options.disabled:
                        validator_list.append(CHECKS['http-request-headers'])
                    if 'socket-options' not in options.disabled:
                        validator_list.append(CHECKS['socket-options'])
                    if 'pdf-doc-info' not in options.disabled:
                        validator_list.append(CHECKS['pdf-doc-info'])
                    if 'countries' not in options.disabled:
                        validator_list.append(CHECKS['countries'])

            if 'network-traffic-ports' not in options.disabled:
                validator_list.append(CHECKS['network-traffic-ports'])
            if 'extref-hashes' not in options.disabled:
                validator_list.append(CHECKS['extref-hashes'])

    # --enable
    if options.enabled:
        for check in options.enabled:
            try:
                if CHECKS[check] in validator_list:
                    continue

                if type(CHECKS[check]) is list:
                    validator_list.extend(CHECKS[check])
                else:
                    validator_list.append(CHECKS[check])
            except KeyError:
                raise JSONError("%s is not a valid check!" % check)

    return validator_list


Instruction:
Write a Python 3 script for
ensuring timestamps contain sane months days hours minutes seconds.

Response:
def timestamp(instance):
    """Ensure timestamps contain sane months, days, hours, minutes, seconds.
    """
    ts_re = re.compile(r"^[0-9]{4}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01])T([01][0-9]|2[0-3]):([0-5][0-9]):([0-5][0-9]|60)(\.[0-9]+)?Z$")
    timestamp_props = ['created', 'modified']
    if instance['type'] in enums.TIMESTAMP_PROPERTIES:
        timestamp_props += enums.TIMESTAMP_PROPERTIES[instance['type']]

    for tprop in timestamp_props:
        if tprop in instance and ts_re.match(instance[tprop]):
            # Don't raise an error if schemas will catch it
            try:
                parser.parse(instance[tprop])
            except ValueError as e:
                yield JSONError("'%s': '%s' is not a valid timestamp: %s"
                                % (tprop, instance[tprop], str(e)), instance['id'])

    if has_cyber_observable_data(instance):
        for key, obj in instance['objects'].items():
            if 'type' not in obj:
                continue
            if obj['type'] in enums.TIMESTAMP_OBSERVABLE_PROPERTIES:
                for tprop in enums.TIMESTAMP_OBSERVABLE_PROPERTIES[obj['type']]:
                    if tprop in obj and ts_re.match(obj[tprop]):
                        # Don't raise an error if schemas will catch it
                        try:
                            parser.parse(obj[tprop])
                        except ValueError as e:
                            yield JSONError("'%s': '%s': '%s' is not a valid timestamp: %s"
                                            % (obj['type'], tprop, obj[tprop], str(e)), instance['id'])
            if obj['type'] in enums.TIMESTAMP_EMBEDDED_PROPERTIES:
                for embed in enums.TIMESTAMP_EMBEDDED_PROPERTIES[obj['type']]:
                    if embed in obj:
                        for tprop in enums.TIMESTAMP_EMBEDDED_PROPERTIES[obj['type']][embed]:
                            if embed == 'extensions':
                                for ext in obj[embed]:
                                    if tprop in obj[embed][ext] and ts_re.match(obj[embed][ext][tprop]):
                                        try:
                                            parser.parse(obj[embed][ext][tprop])
                                        except ValueError as e:
                                            yield JSONError("'%s': '%s': '%s': '%s' is not a valid timestamp: %s"
                                                            % (obj['type'], ext, tprop, obj[embed][ext][tprop], str(e)), instance['id'])
                            elif tprop in obj[embed] and ts_re.match(obj[embed][tprop]):
                                try:
                                    parser.parse(obj[embed][tprop])
                                except ValueError as e:
                                    yield JSONError("'%s': '%s': '%s' is not a valid timestamp: %s"
                                                    % (obj['type'], tprop, obj[embed][tprop], str(e)), instance['id'])


Instruction:
Write a Python 3 script to
validate that modified property is later or equal to created property

Response:
def modified_created(instance):
    """`modified` property must be later or equal to `created` property
    """
    if 'modified' in instance and 'created' in instance and \
            instance['modified'] < instance['created']:
        msg = "'modified' (%s) must be later or equal to 'created' (%s)"
        return JSONError(msg % (instance['modified'], instance['created']),
                         instance['id'])


Instruction:
Write a Python 3 function that can
ensure that the object_marking_refs property of a marking definition object is not circular references.

Response:
def object_marking_circular_refs(instance):
    """Ensure that marking definitions do not contain circular references (ie.
    they do not reference themselves in the `object_marking_refs` property).
    """
    if instance['type'] != 'marking-definition':
        return

    if 'object_marking_refs' in instance:
        for ref in instance['object_marking_refs']:
            if ref == instance['id']:
                yield JSONError("`object_marking_refs` cannot contain any "
                                "references to this marking definition object"
                                " (no circular references).", instance['id'])


Instruction:
Write a Python 3 script for
ensuring that the granular_markings property of a marking definition object does not contain circular references.

Response:
def granular_markings_circular_refs(instance):
    """Ensure that marking definitions do not contain circular references (ie.
    they do not reference themselves in the `granular_markings` property).
    """
    if instance['type'] != 'marking-definition':
        return

    if 'granular_markings' in instance:
        for marking in instance['granular_markings']:
            if 'marking_ref' in marking and marking['marking_ref'] == instance['id']:
                yield JSONError("`granular_markings` cannot contain any "
                                "references to this marking definition object"
                                " (no circular references).", instance['id'])


Instruction:
Can you implement a function in Python 3 that
ensures selectors in granular markings refer to items which are actually present in the object.

Response:
def marking_selector_syntax(instance):
    """Ensure selectors in granular markings refer to items which are actually
    present in the object.
    """
    if 'granular_markings' not in instance:
        return

    list_index_re = re.compile(r"\[(\d+)\]")
    for marking in instance['granular_markings']:
        if 'selectors' not in marking:
            continue

        selectors = marking['selectors']
        for selector in selectors:
            segments = selector.split('.')

            obj = instance
            prev_segmt = None
            for segmt in segments:
                index_match = list_index_re.match(segmt)
                if index_match:
                    try:
                        idx = int(index_match.group(1))
                        obj = obj[idx]
                    except IndexError:
                        yield JSONError("'%s' is not a valid selector because"
                                        " %s is not a valid index."
                                        % (selector, idx), instance['id'])
                    except KeyError:
                        yield JSONError("'%s' is not a valid selector because"
                                        " '%s' is not a list."
                                        % (selector, prev_segmt), instance['id'])
                else:
                    try:
                        obj = obj[segmt]
                    except KeyError as e:
                        yield JSONError("'%s' is not a valid selector because"
                                        " %s is not a property."
                                        % (selector, e), instance['id'])
                    except TypeError:
                        yield JSONError("'%s' is not a valid selector because"
                                        " '%s' is not a property."
                                        % (selector, segmt), instance['id'])
                prev_segmt = segmt


Instruction:
Can you generate the documentation for the following Python 3 function
def observable_object_references(instance):
    for key, obj in instance['objects'].items():
        if 'type' not in obj:
            continue
        elif obj['type'] not in enums.OBSERVABLE_PROP_REFS:
            continue

        obj_type = obj['type']
        for obj_prop in enums.OBSERVABLE_PROP_REFS[obj_type]:
            if obj_prop not in obj:
                continue
            enum_prop = enums.OBSERVABLE_PROP_REFS[obj_type][obj_prop]
            if isinstance(enum_prop, list):
                refs = obj[obj_prop]
                enum_vals = enum_prop
                for x in check_observable_refs(refs, obj_prop, enum_prop, '',
                                               enum_vals, key, instance):
                    yield x

            elif isinstance(enum_prop, dict):
                for embedded_prop in enum_prop:
                    if isinstance(obj[obj_prop], dict):
                        if embedded_prop not in obj[obj_prop]:
                            continue
                        embedded_obj = obj[obj_prop][embedded_prop]
                        for embed_obj_prop in embedded_obj:
                            if embed_obj_prop not in enum_prop[embedded_prop]:
                                continue
                            refs = embedded_obj[embed_obj_prop]
                            enum_vals = enum_prop[embedded_prop][embed_obj_prop]
                            for x in check_observable_refs(refs, obj_prop, enum_prop,
                                                           embed_obj_prop, enum_vals,
                                                           key, instance):
                                yield x

                    elif isinstance(obj[obj_prop], list):
                        for embedded_list_obj in obj[obj_prop]:

                            if embedded_prop not in embedded_list_obj:
                                continue
                            embedded_obj = embedded_list_obj[embedded_prop]
                            refs = embedded_obj
                            enum_vals = enum_prop[embedded_prop]
                            for x in check_observable_refs(refs, obj_prop, enum_prop,
                                                           embedded_prop, enum_vals,
                                                           key, instance):
                                yield x

Response: Ensure certain observable object properties reference the correct type


Instruction:
Can you generate the documentation for the following Python 3 function
def artifact_mime_type(instance):
    for key, obj in instance['objects'].items():
        if ('type' in obj and obj['type'] == 'artifact' and 'mime_type' in obj):
            if enums.media_types():
                if obj['mime_type'] not in enums.media_types():
                    yield JSONError("The 'mime_type' property of object '%s' "
                                    "('%s') must be an IANA registered MIME "
                                    "Type of the form 'type/subtype'."
                                    % (key, obj['mime_type']), instance['id'])

            else:
                info("Can't reach IANA website; using regex for mime types.")
                mime_re = re.compile(r'^(application|audio|font|image|message|model'
                                     '|multipart|text|video)/[a-zA-Z0-9.+_-]+')
                if not mime_re.match(obj['mime_type']):
                    yield JSONError("The 'mime_type' property of object '%s' "
                                    "('%s') should be an IANA MIME Type of the"
                                    " form 'type/subtype'."
                                    % (key, obj['mime_type']), instance['id'])

Response: Ensure the mime_type property of artifact objects comes from the IANA media type registry.


Instruction:
Create a Python 3 function to
ensure certain properties of cyber observable objects come from the IANA character set list.

Response:
def character_set(instance):
    """Ensure certain properties of cyber observable objects come from the IANA
    Character Set list.
    """
    char_re = re.compile(r'^[a-zA-Z0-9_\(\)-]+$')
    for key, obj in instance['objects'].items():
        if ('type' in obj and obj['type'] == 'directory' and 'path_enc' in obj):
            if enums.char_sets():
                if obj['path_enc'] not in enums.char_sets():
                    yield JSONError("The 'path_enc' property of object '%s' "
                                    "('%s') must be an IANA registered "
                                    "character set."
                                    % (key, obj['path_enc']), instance['id'])
            else:
                info("Can't reach IANA website; using regex for character_set.")
                if not char_re.match(obj['path_enc']):
                    yield JSONError("The 'path_enc' property of object '%s' "
                                    "('%s') must be an IANA registered "
                                    "character set."
                                    % (key, obj['path_enc']), instance['id'])

        if ('type' in obj and obj['type'] == 'file' and 'name_enc' in obj):
            if enums.char_sets():
                if obj['name_enc'] not in enums.char_sets():
                    yield JSONError("The 'name_enc' property of object '%s' "
                                    "('%s') must be an IANA registered "
                                    "character set."
                                    % (key, obj['name_enc']), instance['id'])
            else:
                info("Can't reach IANA website; using regex for character_set.")
                if not char_re.match(obj['name_enc']):
                    yield JSONError("The 'name_enc' property of object '%s' "
                                    "('%s') must be an IANA registered "
                                    "character set."
                                    % (key, obj['name_enc']), instance['id'])


Instruction:
Given the following Python 3 function, write the documentation
def software_language(instance):
    for key, obj in instance['objects'].items():
        if ('type' in obj and obj['type'] == 'software' and
                'languages' in obj):
            for lang in obj['languages']:
                if lang not in enums.SOFTWARE_LANG_CODES:
                    yield JSONError("The 'languages' property of object '%s' "
                                    "contains an invalid ISO 639-2 language "
                                    " code ('%s')."
                                    % (key, lang), instance['id'])

Response: Ensure the language property of software objects is a valid ISO 639 - 2 language code.


Instruction:
How would you explain what the following Python 3 function does
def types_strict(instance):
    if instance['type'] not in enums.TYPES:
        yield JSONError("Object type '%s' is not one of those defined in the"
                        " specification." % instance['type'], instance['id'])

    if has_cyber_observable_data(instance):
        for key, obj in instance['objects'].items():
            if 'type' in obj and obj['type'] not in enums.OBSERVABLE_TYPES:
                yield JSONError("Observable object %s is type '%s' which is "
                                "not one of those defined in the "
                                "specification."
                                % (key, obj['type']), instance['id'])

Response:
Ensure that no custom object types are used but only the official ones
    is used but only the official ones
Insights from the specification.


Instruction:
Make a summary of the following Python 3 code
def properties_strict(instance):
    if instance['type'] not in enums.TYPES:
        return  # only check properties for official objects

    defined_props = enums.PROPERTIES.get(instance['type'], [])
    for prop in instance.keys():
        if prop not in defined_props:
            yield JSONError("Property '%s' is not one of those defined in the"
                            " specification." % prop, instance['id'])

    if has_cyber_observable_data(instance):
        for key, obj in instance['objects'].items():
            type_ = obj.get('type', '')
            if type_ not in enums.OBSERVABLE_PROPERTIES:
                continue  # custom observable types handled outside this function
            observable_props = enums.OBSERVABLE_PROPERTIES.get(type_, [])
            embedded_props = enums.OBSERVABLE_EMBEDDED_PROPERTIES.get(type_, {})
            extensions = enums.OBSERVABLE_EXTENSIONS.get(type_, [])
            for prop in obj.keys():
                if prop not in observable_props:
                    yield JSONError("Property '%s' is not one of those defined in the"
                                    " specification for %s objects."
                                    % (prop, type_), instance['id'])
                # Check properties of embedded cyber observable types
                elif prop in embedded_props:
                    embedded_prop_keys = embedded_props.get(prop, [])
                    for embedded_key in obj[prop]:
                        if isinstance(embedded_key, dict):
                            for embedded in embedded_key:
                                if embedded not in embedded_prop_keys:
                                    yield JSONError("Property '%s' is not one of those defined in the"
                                                    " specification for the %s property in %s objects."
                                                    % (embedded, prop, type_), instance['id'])
                        elif embedded_key not in embedded_prop_keys:
                            yield JSONError("Property '%s' is not one of those defined in the"
                                            " specification for the %s property in %s objects."
                                            % (embedded_key, prop, type_), instance['id'])

            # Check properties of embedded cyber observable types
            for ext_key in obj.get('extensions', {}):
                if ext_key not in extensions:
                    continue  # don't check custom extensions
                extension_props = enums.OBSERVABLE_EXTENSION_PROPERTIES[ext_key]
                for ext_prop in obj['extensions'][ext_key]:
                    if ext_prop not in extension_props:
                        yield JSONError("Property '%s' is not one of those defined in the"
                                        " specification for the %s extension in %s objects."
                                        % (ext_prop, ext_key, type_), instance['id'])
                    embedded_ext_props = enums.OBSERVABLE_EXTENSION_EMBEDDED_PROPERTIES.get(ext_key, {}).get(ext_prop, [])
                    if embedded_ext_props:
                        for embed_ext_prop in obj['extensions'][ext_key].get(ext_prop, []):
                            if embed_ext_prop not in embedded_ext_props:
                                yield JSONError("Property '%s' in the %s property of the %s extension "
                                                "is not one of those defined in the specification."
                                                % (embed_ext_prop, ext_prop, ext_key), instance['id'])

Response: Ensure that no custom properties are used but only the official ones


Instruction:
Create a Python 3 function to
check that the syntax of the pattern of an indicator is valid and that the objects and properties referenced by the pattern are valid.

Response:
def patterns(instance, options):
    """Ensure that the syntax of the pattern of an indicator is valid, and that
    objects and properties referenced by the pattern are valid.
    """
    if instance['type'] != 'indicator' or 'pattern' not in instance:
        return

    pattern = instance['pattern']
    if not isinstance(pattern, string_types):
        return  # This error already caught by schemas
    errors = pattern_validator(pattern)

    # Check pattern syntax
    if errors:
        for e in errors:
            yield PatternError(str(e), instance['id'])
        return

    type_format_re = re.compile(r'^\-?[a-z0-9]+(-[a-z0-9]+)*\-?$')
    property_format_re = re.compile(r'^[a-z0-9_]{3,250}$')

    p = Pattern(pattern)
    inspection = p.inspect().comparisons
    for objtype in inspection:
        # Check observable object types
        if objtype in enums.OBSERVABLE_TYPES:
            pass
        elif options.strict_types:
            yield PatternError("'%s' is not a valid STIX observable type"
                               % objtype, instance['id'])
        elif (not type_format_re.match(objtype) or
              len(objtype) < 3 or len(objtype) > 250):
            yield PatternError("'%s' is not a valid observable type name"
                               % objtype, instance['id'])
        elif (all(x not in options.disabled for x in ['all', 'format-checks', 'custom-prefix']) and
              not CUSTOM_TYPE_PREFIX_RE.match(objtype)):
            yield PatternError("Custom Observable Object type '%s' should start "
                               "with 'x-' followed by a source unique identifier "
                               "(like a domain name with dots replaced by "
                               "hyphens), a hyphen and then the name"
                               % objtype, instance['id'])
        elif (all(x not in options.disabled for x in ['all', 'format-checks', 'custom-prefix-lax']) and
              not CUSTOM_TYPE_LAX_PREFIX_RE.match(objtype)):
            yield PatternError("Custom Observable Object type '%s' should start "
                               "with 'x-'" % objtype, instance['id'])

        # Check observable object properties
        expression_list = inspection[objtype]
        for exp in expression_list:
            path = exp[0]
            # Get the property name without list index, dictionary key, or referenced object property
            prop = path[0]
            if objtype in enums.OBSERVABLE_PROPERTIES and prop in enums.OBSERVABLE_PROPERTIES[objtype]:
                continue
            elif options.strict_properties:
                yield PatternError("'%s' is not a valid property for '%s' objects"
                                   % (prop, objtype), instance['id'])
            elif not property_format_re.match(prop):
                yield PatternError("'%s' is not a valid observable property name"
                                   % prop, instance['id'])
            elif (all(x not in options.disabled for x in ['all', 'format-checks', 'custom-prefix']) and
                  not CUSTOM_PROPERTY_PREFIX_RE.match(prop)):
                yield PatternError("Cyber Observable Object custom property '%s' "
                                   "should start with 'x_' followed by a source "
                                   "unique identifier (like a domain name with "
                                   "dots replaced by underscores), an "
                                   "underscore and then the name"
                                   % prop, instance['id'])
            elif (all(x not in options.disabled for x in ['all', 'format-checks', 'custom-prefix-lax']) and
                  not CUSTOM_PROPERTY_LAX_PREFIX_RE.match(prop)):
                yield PatternError("Cyber Observable Object custom property '%s' "
                                   "should start with 'x_'" % prop, instance['id'])


Instruction:
Create a Python 3 function for
constructing the list of MUST validators to be run by the validator.

Response:
def list_musts(options):
    """Construct the list of 'MUST' validators to be run by the validator.
    """
    validator_list = [
        timestamp,
        modified_created,
        object_marking_circular_refs,
        granular_markings_circular_refs,
        marking_selector_syntax,
        observable_object_references,
        artifact_mime_type,
        character_set,
        software_language,
        patterns
    ]

    # --strict-types
    if options.strict_types:
        validator_list.append(types_strict)

    # --strict-properties
    if options.strict_properties:
        validator_list.append(properties_strict)

    return validator_list


Instruction:
Explain what the following Python 3 code does
def media_types():
    if not hasattr(media_types, 'typelist'):
        tlist = []
        categories = [
            'application',
            'audio',
            'font',
            'image',
            'message',
            'model',
            'multipart',
            'text',
            'video'
        ]
        for cat in categories:
            try:
                data = requests.get('http://www.iana.org/assignments/'
                                    'media-types/%s.csv' % cat)
            except requests.exceptions.RequestException:
                return []

            types = []
            for line in data.iter_lines():
                if line:
                    line = line.decode("utf-8")
                    if line.count(',') > 0:
                        reg_template = line.split(',')[1]
                        if reg_template:
                            types.append(reg_template)
                        else:
                            types.append(cat + '/' + line.split(',')[0])

            tlist.extend(types)
        media_types.typelist = tlist
    return media_types.typelist

Response: Return a list of the IANA Media Types in the current language.


Instruction:
How would you explain what the following Python 3 function does
def char_sets():
    if not hasattr(char_sets, 'setlist'):
        clist = []
        try:
            data = requests.get('http://www.iana.org/assignments/character-'
                                'sets/character-sets-1.csv')
        except requests.exceptions.RequestException:
            return []

        for line in data.iter_lines():
            if line:
                line = line.decode("utf-8")
                if line.count(',') > 0:
                    vals = line.split(',')
                    if vals[0]:
                        clist.append(vals[0])
                    else:
                        clist.append(vals[1])

        char_sets.setlist = clist
    return char_sets.setlist

Response: Return a list of the IANA Character Sets.


Instruction:
Here you have a function in Python 3, explain what it does
def protocols():
    if not hasattr(protocols, 'protlist'):
        plist = []
        try:
            data = requests.get('http://www.iana.org/assignments/service-names'
                                '-port-numbers/service-names-port-numbers.csv')
        except requests.exceptions.RequestException:
            return []

        for line in data.iter_lines():
            if line:
                line = line.decode("utf-8")
                if line.count(',') > 0:
                    vals = line.split(',')
                    if vals[0]:
                        plist.append(vals[0])
                    if len(vals) > 2 and vals[2] and vals[2] not in plist:
                        plist.append(vals[2])

        plist.append('ipv4')
        plist.append('ipv6')
        plist.append('ssl')
        plist.append('tls')
        plist.append('dns')
        protocols.protlist = plist
    return protocols.protlist

Response:
Return a list of values from the IANA Service Name and Transport
    Protocol Port Number Registry.


Instruction:
How would you implement a function in Python 3 that
returns a list of values from the list of IANA IP Flow Information Export IANA Entities

Response:
def ipfix():
    """Return a list of values from the list of IANA IP Flow Information Export
    (IPFIX) Entities, or an empty list if the IANA website is unreachable.
    Store it as a function attribute so that we only build the list once.
    """
    if not hasattr(ipfix, 'ipflist'):
        ilist = []
        try:
            data = requests.get('http://www.iana.org/assignments/ipfix/ipfix-'
                                'information-elements.csv')
        except requests.exceptions.RequestException:
            return []

        for line in data.iter_lines():
            if line:
                line = line.decode("utf-8")
                if re.match(r'^\d+(,[a-zA-Z0-9]+){2},', line):
                    vals = line.split(',')
                    if vals[1]:
                        ilist.append(vals[1])

        ipfix.ipflist = ilist
    return ipfix.ipflist


Instruction:
Can you generate the documentation for the following Python 3 function
def print_level(log_function, fmt, level, *args):
    if _SILENT:
        return

    msg = fmt % args
    spaces = '    ' * level
    log_function("%s%s" % (spaces, msg))

Response: Print a formatted message to stdout prepended by spaces. Useful for printing hierarchical information like bullet lists.


Instruction:
Can you implement a function in Python 3 that
prints fatal errors that occurred during validation runs.

Response:
def print_fatal_results(results, level=0):
    """Print fatal errors that occurred during validation runs.
    """
    print_level(logger.critical, _RED + "[X] Fatal Error: %s", level, results.error)


Instruction:
Make a summary of the following Python 3 code
def print_schema_results(results, level=0):
    for error in results.errors:
        print_level(logger.error, _RED + "[X] %s", level, error)

Response: Print JSON Schema validation errors to stdout.


Instruction:
How would you explain what the following Python 3 function does
def print_warning_results(results, level=0):
    marker = _YELLOW + "[!] "

    for warning in results.warnings:
        print_level(logger.warning, marker + "Warning: %s", level, warning)

Response: Print warning messages found during validation.


Instruction:
Can you write a function in Python 3 where it
prints a header for the results of a file or object.

Response:
def print_results_header(identifier, is_valid):
    """Print a header for the results of either a file or an object.

    """
    print_horizontal_rule()
    print_level(logger.info, "[-] Results for: %s", 0, identifier)

    if is_valid:
        marker = _GREEN + "[+]"
        verdict = "Valid"
        log_func = logger.info
    else:
        marker = _RED + "[X]"
        verdict = "Invalid"
        log_func = logger.error
    print_level(log_func, "%s STIX JSON: %s", 0, marker, verdict)


Instruction:
Implement a Python 3 function for
printing the results of validating an object.

Response:
def print_object_results(obj_result):
    """Print the results of validating an object.

    Args:
        obj_result: An ObjectValidationResults instance.

    """
    print_results_header(obj_result.object_id, obj_result.is_valid)

    if obj_result.warnings:
        print_warning_results(obj_result, 1)
    if obj_result.errors:
        print_schema_results(obj_result, 1)


Instruction:
Can you generate the documentation for the following Python 3 function
def print_file_results(file_result):
    print_results_header(file_result.filepath, file_result.is_valid)

    for object_result in file_result.object_results:
        if object_result.warnings:
            print_warning_results(object_result, 1)
        if object_result.errors:
            print_schema_results(object_result, 1)

    if file_result.fatal:
        print_fatal_results(file_result.fatal, 1)

Response: Prints the results of validating a file.


Instruction:
Explain what the following Python 3 code does
def print_results(results):
    if not isinstance(results, list):
        results = [results]

    for r in results:
        try:
            r.log()
        except AttributeError:
            raise ValueError('Argument to print_results() must be a list of '
                             'FileValidationResults or ObjectValidationResults.')

Response: Print results to stdout.


Instruction:
Given the following Python 3 function, write the documentation
def vocab_encryption_algo(instance):
    for key, obj in instance['objects'].items():
        if 'type' in obj and obj['type'] == 'file':
            try:
                enc_algo = obj['encryption_algorithm']
            except KeyError:
                continue
            if enc_algo not in enums.ENCRYPTION_ALGO_OV:
                yield JSONError("Object '%s' has an 'encryption_algorithm' of "
                                "'%s', which is not a value in the "
                                "encryption-algo-ov vocabulary."
                                % (key, enc_algo), instance['id'],
                                'encryption-algo')

Response: Ensure file objects encryption_algorithm property is from the availabe encryption - algo - ov vocabulary.


Instruction:
Write a Python 3 script for
ensuring that all SDOs being referenced by the SRO are contained within the same bundle.

Response:
def enforce_relationship_refs(instance):
    """Ensures that all SDOs being referenced by the SRO are contained
    within the same bundle"""
    if instance['type'] != 'bundle' or 'objects' not in instance:
        return

    rel_references = set()

    """Find and store all ids"""
    for obj in instance['objects']:
        if obj['type'] != 'relationship':
            rel_references.add(obj['id'])

    """Check if id has been encountered"""
    for obj in instance['objects']:
        if obj['type'] == 'relationship':
            if obj['source_ref'] not in rel_references:
                yield JSONError("Relationship object %s makes reference to %s "
                                "Which is not found in current bundle "
                                % (obj['id'], obj['source_ref']), 'enforce-relationship-refs')

            if obj['target_ref'] not in rel_references:
                yield JSONError("Relationship object %s makes reference to %s "
                                "Which is not found in current bundle "
                                % (obj['id'], obj['target_ref']), 'enforce-relationship-refs')


Instruction:
Write a Python 3 script to
ensure timestamp properties with a comparison requirement are valid.

Response:
def timestamp_compare(instance):
    """Ensure timestamp properties with a comparison requirement are valid.

    E.g. `modified` must be later or equal to `created`.
    """
    compares = [('modified', 'ge', 'created')]
    additional_compares = enums.TIMESTAMP_COMPARE.get(instance.get('type', ''), [])
    compares.extend(additional_compares)

    for first, op, second in compares:
        comp = getattr(operator, op)
        comp_str = get_comparison_string(op)

        if first in instance and second in instance and \
                not comp(instance[first], instance[second]):
            msg = "'%s' (%s) must be %s '%s' (%s)"
            yield JSONError(msg % (first, instance[first], comp_str, second, instance[second]),
                            instance['id'])


Instruction:
Create a Python 3 function to
ensure that the observable timestamp properties with a comparison requirement are valid.

Response:
def observable_timestamp_compare(instance):
    """Ensure cyber observable timestamp properties with a comparison
    requirement are valid.
    """
    for key, obj in instance['objects'].items():
        compares = enums.TIMESTAMP_COMPARE_OBSERVABLE.get(obj.get('type', ''), [])
        print(compares)
        for first, op, second in compares:
            comp = getattr(operator, op)
            comp_str = get_comparison_string(op)

            if first in obj and second in obj and \
                    not comp(obj[first], obj[second]):
                msg = "In object '%s', '%s' (%s) must be %s '%s' (%s)"
                yield JSONError(msg % (key, first, obj[first], comp_str, second, obj[second]),
                                instance['id'])


Instruction:
How would you explain what the following Python 3 function does
def language_contents(instance):
    if instance['type'] != 'language-content' or 'contents' not in instance:
        return

    for key, value in instance['contents'].items():
        if key not in enums.LANG_CODES:
            yield JSONError("Invalid key '%s' in 'contents' property must be"
                            " an RFC 5646 code" % key, instance['id'])
        for subkey, subvalue in value.items():
            if not PROPERTY_FORMAT_RE.match(subkey):
                yield JSONError("'%s' in '%s' of the 'contents' property is "
                                "invalid and must match a valid property name"
                                % (subkey, key), instance['id'], 'observable-dictionary-keys')

Response:
Ensure keys in Language Content s contents dictionary are valid language codes and that the keys in the sub - dictionaries match the rules
    language codes.


Instruction:
Here you have a function in Python 3, explain what it does
def list_musts(options):
    validator_list = [
        timestamp,
        timestamp_compare,
        observable_timestamp_compare,
        object_marking_circular_refs,
        granular_markings_circular_refs,
        marking_selector_syntax,
        observable_object_references,
        artifact_mime_type,
        character_set,
        language,
        software_language,
        patterns,
        language_contents,
    ]

    # --strict-types
    if options.strict_types:
        validator_list.append(types_strict)

    # --strict-properties
    if options.strict_properties:
        validator_list.append(properties_strict)

    return validator_list

Response: Construct the list of MUST validators to be run by the validator.


Instruction:
Make a summary of the following Python 3 code
def get_code(results):
    status = EXIT_SUCCESS

    for file_result in results:
        error = any(object_result.errors for object_result in file_result.object_results)

        fatal = file_result.fatal

        if error:
            status |= EXIT_SCHEMA_INVALID
        if fatal:
            status |= EXIT_VALIDATION_ERROR

    return status

Response: Determines the exit status code to be returned from a script by inspecting the results returned from validating files.


Instruction:
How would you explain what the following Python 3 function does
def parse_args(cmd_args, is_script=False):
    parser = argparse.ArgumentParser(
        description=__doc__,
        formatter_class=NewlinesHelpFormatter,
        epilog=CODES_TABLE
    )

    # Input options
    if is_script:
        parser.add_argument(
            "files",
            metavar="FILES",
            nargs="*",
            default=sys.stdin,
            help="A whitespace separated list of STIX files or directories of "
                 "STIX files to validate. If none given, stdin will be used."
        )
    parser.add_argument(
        "-r",
        "--recursive",
        dest="recursive",
        action="store_true",
        default=True,
        help="Recursively descend into input directories."
    )
    parser.add_argument(
        "-s",
        "--schemas",
        dest="schema_dir",
        help="Custom schema directory. If provided, input will be validated "
             "against these schemas in addition to the STIX schemas bundled "
             "with this script."
    )
    parser.add_argument(
        "--version",
        dest="version",
        default=DEFAULT_VER,
        help="The version of the STIX specification to validate against (e.g. "
             "\"2.0\")."
    )

    # Output options
    parser.add_argument(
        "-v",
        "--verbose",
        dest="verbose",
        action="store_true",
        default=False,
        help="Print informational notes and more verbose error messages."
    )

    parser.add_argument(
        "-q",
        "--silent",
        dest="silent",
        action="store_true",
        default=False,
        help="Silence all output to stdout."
    )

    parser.add_argument(
        "-d",
        "--disable",
        "--ignore",
        dest="disabled",
        default="",
        help="A comma-separated list of recommended best practice checks to "
             "skip. By default, no checks are disabled. \n\n"
             "Example: --disable 202,210"
    )

    parser.add_argument(
        "-e",
        "--enable",
        "--select",
        dest="enabled",
        default="",
        help="A comma-separated list of recommended best practice checks to "
             "enable. If the --disable option is not used, no other checks "
             "will be run. By default, all checks are enabled.\n\n"
             "Example: --enable 218"
    )

    parser.add_argument(
        "--strict",
        dest="strict",
        action="store_true",
        default=False,
        help="Treat warnings as errors and fail validation if any are found."
    )

    parser.add_argument(
        "--strict-types",
        dest="strict_types",
        action="store_true",
        default=False,
        help="Ensure that no custom object types are used, only those defined"
             " in the STIX specification."
    )

    parser.add_argument(
        "--strict-properties",
        dest="strict_properties",
        action="store_true",
        default=False,
        help="Ensure that no custom properties are used, only those defined"
             " in the STIX specification."
    )

    parser.add_argument(
        "--no-cache",
        dest="no_cache",
        action="store_true",
        default=False,
        help="Disable the caching of external source values."
    )

    parser.add_argument(
        "--refresh-cache",
        dest="refresh_cache",
        action="store_true",
        default=False,
        help="Clears the cache of external source values, then "
             "during validation downloads them again."
    )

    parser.add_argument(
        "--clear-cache",
        dest="clear_cache",
        action="store_true",
        default=False,
        help="Clear the cache of external source values after validation."
    )

    parser.add_argument(
        "--enforce-refs",
        dest="enforce_refs",
        action="store_true",
        default=False,
        help="Ensures that all SDOs being referenced by SROs are contained "
             "within the same bundle."
    )

    args = parser.parse_args(cmd_args)

    if not is_script:
        args.files = ""
    if not args.version:
        args.version = DEFAULT_VER

    return ValidationOptions(args)

Response: Parses a list of command line arguments into a ValidationOptions object.


Instruction:
Can you tell what is the following Python 3 function doing
def init_requests_cache(refresh_cache=False):
    # Cache data from external sources; used in some checks
    dirs = AppDirs("stix2-validator", "OASIS")
    # Create cache dir if doesn't exist
    try:
        os.makedirs(dirs.user_cache_dir)
    except OSError as e:
        if e.errno != errno.EEXIST:
            raise
    requests_cache.install_cache(
        cache_name=os.path.join(dirs.user_cache_dir, 'py{}cache'.format(
            sys.version_info[0])),
        expire_after=datetime.timedelta(weeks=1))

    if refresh_cache:
        clear_requests_cache()

Response: Initializes a requests cache for the given node.


Instruction:
Can you generate the documentation for the following Python 3 function
def render_tag(self, context, kwargs, nodelist):
        '''render content with "active" urls logic'''
        # load configuration from passed options
        self.load_configuration(**kwargs)

        # get request from context
        request = context['request']

        # get full path from request
        self.full_path = request.get_full_path()

        # render content of template tag
        context.push()
        content = nodelist.render(context)
        context.pop()

        # check content for "active" urls
        content = render_content(
            content,
            full_path=self.full_path,
            parent_tag=self.parent_tag,
            css_class=self.css_class,
            menu=self.menu,
            ignore_params=self.ignore_params,
        )

        return content

Response: render content with active urls logic


Instruction:
Write a Python 3 function that can
parse content of extension

Response:
def parse(self, parser):
        '''parse content of extension'''
        # line number of token that started the tag
        lineno = next(parser.stream).lineno

        # template context
        context = nodes.ContextReference()

        # parse keyword arguments
        kwargs = []

        while parser.stream.look().type == lexer.TOKEN_ASSIGN:
            key = parser.stream.expect(lexer.TOKEN_NAME)
            next(parser.stream)
            kwargs.append(
                nodes.Keyword(key.value, parser.parse_expression()),
            )
            parser.stream.skip_if('comma')
        # parse content of the activeurl block up to endactiveurl
        body = parser.parse_statements(['name:endactiveurl'], drop_needle=True)

        args = [context]

        call_method = self.call_method(
            'render_tag',
            args=args,
            kwargs=kwargs,
        )

        return nodes.CallBlock(call_method, [], [], body).set_lineno(lineno)


Instruction:
Can you implement a function in Python 3 that
renders content with active urls logic

Response:
def render_tag(self, context, caller, **kwargs):
        '''render content with "active" urls logic'''
        # load configuration from passed options
        self.load_configuration(**kwargs)

        # get request from context
        request = context['request']

        # get full path from request
        self.full_path = request.get_full_path()

        # render content of extension
        content = caller()

        # check content for "active" urls
        content = render_content(
            content,
            full_path=self.full_path,
            parent_tag=self.parent_tag,
            css_class=self.css_class,
            menu=self.menu,
            ignore_params=self.ignore_params,
        )

        return content


Instruction:
Can you tell what is the following Python 3 function doing
def yesno_to_bool(value, varname):
    if isinstance(value, bool):
        if value:
            value = 'yes'
        else:
            value = 'no'
    elif value is None:
        value = 'no'

    # check value configuration, set boolean value
    if value.lower() in ('yes', 'true'):
        value = True
    elif value.lower() in ('no', 'false'):
        value = False
    else:
        raise ImproperlyConfigured(
            'activeurl: malformed param value for %s' % varname
        )
    return value

Response: Return True or False from yes or no.


Instruction:
How would you explain what the following Python 3 function does
def check_active(url, element, **kwargs):
    '''check "active" url, apply css_class'''
    menu = yesno_to_bool(kwargs['menu'], 'menu')
    ignore_params = yesno_to_bool(kwargs['ignore_params'], 'ignore_params')

    # check missing href parameter
    if not url.attrib.get('href', None) is None:
        # get href attribute
        href = url.attrib['href'].strip()

        # href="#" is often used when links shouldn't be handled by browsers.
        # For example, Bootstrap uses this for expandable menus on
        # small screens, see
        # https://getbootstrap.com/docs/4.0/components/navs/#using-dropdowns
        if href == '#':
            return False

        # split into urlparse object
        href = urlparse.urlsplit(href)

        # cut off hashtag (anchor)
        href = href._replace(fragment='')

        # cut off get params (?key=var&etc=var2)
        if ignore_params:
            href = href._replace(query='')
            kwargs['full_path'] = urlparse.urlunsplit(
                urlparse.urlsplit(
                    kwargs['full_path']
                )._replace(query='')
            )

        # build urlparse object back into string
        href = urlparse.urlunsplit(href)

        # check empty href
        if href == '':
            # replace href with current location
            href = kwargs['full_path']
        # compare full_path with href according to menu configuration

        if menu:
            # try mark "root" (/) url as "active", in equals way
            if href == '/' == kwargs['full_path']:
                logic = True
            # skip "root" (/) url, otherwise it will be always "active"
            elif href != '/':
                # start with logic
                logic = (
                    kwargs['full_path'].startswith(href)
                    or
                    # maybe an urlquoted href was supplied
                    urlquote(kwargs['full_path']).startswith(href)
                    or
                    kwargs['full_path'].startswith(urlquote(href))
                )
            else:
                logic = False
        else:
            # equals logic
            logic = (
                kwargs['full_path'] == href
                or
                # maybe an urlquoted href was supplied
                urlquote(kwargs['full_path']) == href
                or
                kwargs['full_path'] == urlquote(href)
            )
        # "active" url found
        if logic:
            # check parent tag has "class" attribute or it is empty
            if element.attrib.get('class'):
                # prevent multiple "class" attribute adding
                if kwargs['css_class'] not in element.attrib['class']:
                    # append "active" class
                    element.attrib['class'] += ' {css_class}'.format(
                        css_class=kwargs['css_class'],
                    )
            else:
                # create or set (if empty) "class" attribute
                element.attrib['class'] = kwargs['css_class']
            return True
    # no "active" urls found
    return False

Response: check if url is active


Instruction:
Can you generate a brief explanation for the following Python 3 code
def check_content(content, **kwargs):
    '''check content for "active" urls'''
    # valid html root tag
    try:
        # render elements tree from content
        tree = fragment_fromstring(content)
        # flag for prevent content rerendering, when no "active" urls found
        processed = False
        # django > 1.5 template boolean\None variables feature
        if isinstance(kwargs['parent_tag'], bool):
            if not kwargs['parent_tag']:
                kwargs['parent_tag'] = 'self'
            else:
                raise ImproperlyConfigured('''
                    parent_tag=True is not allowed
                ''')
        elif kwargs['parent_tag'] is None:
            kwargs['parent_tag'] = 'self'
        # if parent_tag is False\None\''\a\self
        # "active" status will be applied directly to ""
        if kwargs['parent_tag'].lower() in ('a', 'self', ''):
            # xpath query to get all ""
            urls = tree.xpath('.//a')
            # check "active" status for all urls
            for url in urls:
                if check_active(url, url, **kwargs):
                    # mark flag for rerendering content
                    processed = True
        # otherwise css_class must be applied to parent_tag
        else:
            # xpath query to get all parent tags
            elements = tree.xpath('.//{parent_tag}'.format(
                parent_tag=kwargs['parent_tag'],
            ))
            # check all elements for "active" ""
            for element in elements:
                # xpath query to get all ""
                urls = element.xpath('.//a')
                # check "active" status for all urls
                for url in urls:
                    if check_active(url, element, **kwargs):
                        # flag for rerendering content tree
                        processed = True
                        # stop checking other ""
                        break
        # do not rerender content if no "active" urls found
        if processed:
            # render content from tree
            return tostring(tree, encoding='unicode')
    # not valid html root tag
    except ParserError:
        # raise an exception with configuration example
        raise ImproperlyConfigured('''
            content of {% activeurl %} must have valid html root tag
            for example
                {% activeurl %}

                            page

                            other_page

                {% endactiveurl %}
            in this case
 is valid content root tag
        ''')
    return content

Response: check content for active urls


Instruction:
Here you have a function in Python 3, explain what it does
def render_content(content, **kwargs):
    '''check content for "active" urls, store results to django cache'''
    # try to take pre rendered content from django cache, if caching is enabled
    if settings.ACTIVE_URL_CACHE:
        cache_key = get_cache_key(content, **kwargs)

        # get cached content from django cache backend
        from_cache = cache.get(cache_key)

        # return pre rendered content if it exist in cache
        if from_cache is not None:
            return from_cache

    # render content with "active" logic
    content = check_content(content, **kwargs)

    # write rendered content to django cache backend, if caching is enabled
    if settings.ACTIVE_URL_CACHE:
        cache.set(cache_key, content, settings.ACTIVE_URL_CACHE_TIMEOUT)

    return content

Response: check content for active urls store results to django cache


Instruction:
Create a Python 3 function for
loading configuration merge with default settings

Response:
def load_configuration(self, **kwargs):
        '''load configuration, merge with default settings'''
        # update passed arguments with default values
        for key in settings.ACTIVE_URL_KWARGS:
            kwargs.setdefault(key, settings.ACTIVE_URL_KWARGS[key])

        # "active" html tag css class
        self.css_class = kwargs['css_class']
        # "active" html tag
        self.parent_tag = kwargs['parent_tag']
        # flipper for menu support
        self.menu = kwargs['menu']
        # whether to ignore / chomp get_params
        self.ignore_params = kwargs['ignore_params']


Instruction:
Can you generate a brief explanation for the following Python 3 code
def _parse_response(response, clazz, is_list=False, resource_name=None):
        target = response.json()[
            resource_name] if resource_name else response.json()
        if is_list:
            return [clazz.from_json(resource) for resource in target]
        else:
            return clazz.from_json(target)

Response: Parse a Marathon response into an object or list of objects.


Instruction:
Create a Python 3 function to
perform a request to the Marathon server.

Response:
def _do_request(self, method, path, params=None, data=None):
        """Query Marathon server."""
        headers = {
            'Content-Type': 'application/json', 'Accept': 'application/json'}

        if self.auth_token:
            headers['Authorization'] = "token={}".format(self.auth_token)

        response = None
        servers = list(self.servers)
        while servers and response is None:
            server = servers.pop(0)
            url = ''.join([server.rstrip('/'), path])
            try:
                response = self.session.request(
                    method, url, params=params, data=data, headers=headers,
                    auth=self.auth, timeout=self.timeout, verify=self.verify)
                marathon.log.info('Got response from %s', server)
            except requests.exceptions.RequestException as e:
                marathon.log.error(
                    'Error while calling %s: %s', url, str(e))

        if response is None:
            raise NoResponseError('No remaining Marathon servers to try')

        if response.status_code >= 500:
            marathon.log.error('Got HTTP {code}: {body}'.format(
                code=response.status_code, body=response.text.encode('utf-8')))
            raise InternalServerError(response)
        elif response.status_code >= 400:
            marathon.log.error('Got HTTP {code}: {body}'.format(
                code=response.status_code, body=response.text.encode('utf-8')))
            if response.status_code == 404:
                raise NotFoundError(response)
            elif response.status_code == 409:
                raise ConflictError(response)
            else:
                raise MarathonHttpError(response)
        elif response.status_code >= 300:
            marathon.log.warn('Got HTTP {code}: {body}'.format(
                code=response.status_code, body=response.text.encode('utf-8')))
        else:
            marathon.log.debug('Got HTTP {code}: {body}'.format(
                code=response.status_code, body=response.text.encode('utf-8')))

        return response


Instruction:
Given the following Python 3 function, write the documentation
def _do_sse_request(self, path, params=None):
        urls = [''.join([server.rstrip('/'), path]) for server in self.servers]
        while urls:
            url = urls.pop()
            try:
                # Requests does not set the original Authorization header on cross origin
                # redirects. If set allow_redirects=True we may get a 401 response.
                response = self.sse_session.get(
                    url,
                    params=params,
                    stream=True,
                    headers={'Accept': 'text/event-stream'},
                    auth=self.auth,
                    verify=self.verify,
                    allow_redirects=False
                )
            except Exception as e:
                marathon.log.error(
                    'Error while calling %s: %s', url, e.message)
            else:
                if response.is_redirect and response.next:
                    urls.append(response.next.url)
                    marathon.log.debug("Got redirect to {}".format(response.next.url))
                elif response.ok:
                    return response.iter_lines()

        raise MarathonError('No remaining Marathon servers to try')

Response: Query Marathon server for events.


Instruction:
How would you explain what the following Python 3 function does
def create_app(self, app_id, app, minimal=True):
        app.id = app_id
        data = app.to_json(minimal=minimal)
        response = self._do_request('POST', '/v2/apps', data=data)
        if response.status_code == 201:
            return self._parse_response(response, MarathonApp)
        else:
            return False

Response: Create and start an app.


Instruction:
Can you tell what is the following Python 3 function doing
def list_apps(self, cmd=None, embed_tasks=False, embed_counts=False,
                  embed_deployments=False, embed_readiness=False,
                  embed_last_task_failure=False, embed_failures=False,
                  embed_task_stats=False, app_id=None, label=None, **kwargs):
        """List all apps.

        :param str cmd: if passed, only show apps with a matching `cmd`
        :param bool embed_tasks: embed tasks in result
        :param bool embed_counts: embed all task counts
        :param bool embed_deployments: embed all deployment identifier
        :param bool embed_readiness: embed all readiness check results
        :param bool embed_last_task_failure: embeds the last task failure
        :param bool embed_failures: shorthand for embed_last_task_failure
        :param bool embed_task_stats: embed task stats in result
        :param str app_id: if passed, only show apps with an 'id' that matches or contains this value
        :param str label: if passed, only show apps with the selected labels
        :param kwargs: arbitrary search filters

        :returns: list of applications
        :rtype: list[:class:`marathon.models.app.MarathonApp`]
        """
        params = {}
        if cmd:
            params['cmd'] = cmd
        if app_id:
            params['id'] = app_id
        if label:
            params['label'] = label

        embed_params = {
            'app.tasks': embed_tasks,
            'app.counts': embed_counts,
            'app.deployments': embed_deployments,
            'app.readiness': embed_readiness,
            'app.lastTaskFailure': embed_last_task_failure,
            'app.failures': embed_failures,
            'app.taskStats': embed_task_stats
        }
        filtered_embed_params = [k for (k, v) in embed_params.items() if v]
        if filtered_embed_params:
            params['embed'] = filtered_embed_params

        response = self._do_request('GET', '/v2/apps', params=params)
        apps = self._parse_response(
            response, MarathonApp, is_list=True, resource_name='apps')
        for k, v in kwargs.items():
            apps = [o for o in apps if getattr(o, k) == v]
        return apps

Response: List all apps in the Marathon system.


Instruction:
Implement a function in Python 3 to
get a single application.

Response:
def get_app(self, app_id, embed_tasks=False, embed_counts=False,
                embed_deployments=False, embed_readiness=False,
                embed_last_task_failure=False, embed_failures=False,
                embed_task_stats=False):
        """Get a single app.

        :param str app_id: application ID
        :param bool embed_tasks: embed tasks in result
        :param bool embed_counts: embed all task counts
        :param bool embed_deployments: embed all deployment identifier
        :param bool embed_readiness: embed all readiness check results
        :param bool embed_last_task_failure: embeds the last task failure
        :param bool embed_failures: shorthand for embed_last_task_failure
        :param bool embed_task_stats: embed task stats in result

        :returns: application
        :rtype: :class:`marathon.models.app.MarathonApp`
        """
        params = {}
        embed_params = {
            'app.tasks': embed_tasks,
            'app.counts': embed_counts,
            'app.deployments': embed_deployments,
            'app.readiness': embed_readiness,
            'app.lastTaskFailure': embed_last_task_failure,
            'app.failures': embed_failures,
            'app.taskStats': embed_task_stats
        }
        filtered_embed_params = [k for (k, v) in embed_params.items() if v]
        if filtered_embed_params:
            params['embed'] = filtered_embed_params

        response = self._do_request(
            'GET', '/v2/apps/{app_id}'.format(app_id=app_id), params=params)
        return self._parse_response(response, MarathonApp, resource_name='app')


Instruction:
Implement a function in Python 3 to
update an app. Applies writable settings in `app` to `app_id` Note: this method can not be used to rename apps. :param str app_id: target application ID :param app: application settings :type app: :class:`marathon.models.app.MarathonApp` :param bool force: apply even if a deployment is in progress :param bool minimal: ignore nulls and empty collections :returns: a dict containing the deployment id and version :rtype: dict

Response:
def update_app(self, app_id, app, force=False, minimal=True):
        """Update an app.

        Applies writable settings in `app` to `app_id`
        Note: this method can not be used to rename apps.

        :param str app_id: target application ID
        :param app: application settings
        :type app: :class:`marathon.models.app.MarathonApp`
        :param bool force: apply even if a deployment is in progress
        :param bool minimal: ignore nulls and empty collections

        :returns: a dict containing the deployment id and version
        :rtype: dict
        """
        # Changes won't take if version is set - blank it for convenience
        app.version = None

        params = {'force': force}
        data = app.to_json(minimal=minimal)

        response = self._do_request(
            'PUT', '/v2/apps/{app_id}'.format(app_id=app_id), params=params, data=data)
        return response.json()


Instruction:
Can you implement a function in Python 3 that
updates multiple apps. Applies writable settings in elements of apps either by upgrading existing ones or creating new ones :param apps: sequence of application settings :param bool force: apply even if a deployment is in progress :param bool minimal: ignore nulls and empty collections :returns: a dict containing the deployment id and version :rtype: dict

Response:
def update_apps(self, apps, force=False, minimal=True):
        """Update multiple apps.

        Applies writable settings in elements of apps either by upgrading existing ones or creating new ones

        :param apps: sequence of application settings
        :param bool force: apply even if a deployment is in progress
        :param bool minimal: ignore nulls and empty collections

        :returns: a dict containing the deployment id and version
        :rtype: dict
        """
        json_repr_apps = []
        for app in apps:
            # Changes won't take if version is set - blank it for convenience
            app.version = None
            json_repr_apps.append(app.json_repr(minimal=minimal))

        params = {'force': force}
        encoder = MarathonMinimalJsonEncoder if minimal else MarathonJsonEncoder
        data = json.dumps(json_repr_apps, cls=encoder, sort_keys=True)

        response = self._do_request(
            'PUT', '/v2/apps', params=params, data=data)
        return response.json()


Instruction:
Given the following Python 3 function, write the documentation
def rollback_app(self, app_id, version, force=False):
        params = {'force': force}
        data = json.dumps({'version': version})
        response = self._do_request(
            'PUT', '/v2/apps/{app_id}'.format(app_id=app_id), params=params, data=data)
        return response.json()

Response: Roll an app back to a previous version.


Instruction:
Explain what the following Python 3 code does
def delete_app(self, app_id, force=False):
        params = {'force': force}
        response = self._do_request(
            'DELETE', '/v2/apps/{app_id}'.format(app_id=app_id), params=params)
        return response.json()

Response: Stop and destroy an application.


Instruction:
Make a summary of the following Python 3 code
def scale_app(self, app_id, instances=None, delta=None, force=False):
        if instances is None and delta is None:
            marathon.log.error('instances or delta must be passed')
            return

        try:
            app = self.get_app(app_id)
        except NotFoundError:
            marathon.log.error('App "{app}" not found'.format(app=app_id))
            return

        desired = instances if instances is not None else (
            app.instances + delta)
        return self.update_app(app.id, MarathonApp(instances=desired), force=force)

Response: Scale an app to a target number of instances or by some delta.


Instruction:
Create a Python 3 function for
creating and start a group.

Response:
def create_group(self, group):
        """Create and start a group.

        :param :class:`marathon.models.group.MarathonGroup` group: the group to create

        :returns: success
        :rtype: dict containing the version ID
        """
        data = group.to_json()
        response = self._do_request('POST', '/v2/groups', data=data)
        return response.json()


Instruction:
Can you create a Python 3 function that
lists all groups. :param kwargs: arbitrary search filters :returns: list of groups :rtype: list[:class:`marathon.models.group.MarathonGroup`]

Response:
def list_groups(self, **kwargs):
        """List all groups.

        :param kwargs: arbitrary search filters

        :returns: list of groups
        :rtype: list[:class:`marathon.models.group.MarathonGroup`]
        """
        response = self._do_request('GET', '/v2/groups')
        groups = self._parse_response(
            response, MarathonGroup, is_list=True, resource_name='groups')
        for k, v in kwargs.items():
            groups = [o for o in groups if getattr(o, k) == v]
        return groups


Instruction:
How would you code a function in Python 3 to
get a single group.

Response:
def get_group(self, group_id):
        """Get a single group.

        :param str group_id: group ID

        :returns: group
        :rtype: :class:`marathon.models.group.MarathonGroup`
        """
        response = self._do_request(
            'GET', '/v2/groups/{group_id}'.format(group_id=group_id))
        return self._parse_response(response, MarathonGroup)


Instruction:
Create a Python 3 function for
updating a group s internal cache entries.

Response:
def update_group(self, group_id, group, force=False, minimal=True):
        """Update a group.

        Applies writable settings in `group` to `group_id`
        Note: this method can not be used to rename groups.

        :param str group_id: target group ID
        :param group: group settings
        :type group: :class:`marathon.models.group.MarathonGroup`
        :param bool force: apply even if a deployment is in progress
        :param bool minimal: ignore nulls and empty collections

        :returns: a dict containing the deployment id and version
        :rtype: dict
        """
        # Changes won't take if version is set - blank it for convenience
        group.version = None

        params = {'force': force}
        data = group.to_json(minimal=minimal)

        response = self._do_request(
            'PUT', '/v2/groups/{group_id}'.format(group_id=group_id), data=data, params=params)
        return response.json()


Instruction:
How would you implement a function in Python 3 that
rolls a group back to a previous version.

Response:
def rollback_group(self, group_id, version, force=False):
        """Roll a group back to a previous version.

        :param str group_id: group ID
        :param str version: group version
        :param bool force: apply even if a deployment is in progress

        :returns: a dict containing the deployment id and version
        :rtype: dict
        """
        params = {'force': force}
        response = self._do_request(
            'PUT',
            '/v2/groups/{group_id}/versions/{version}'.format(
                group_id=group_id, version=version),
            params=params)
        return response.json()


Instruction:
Can you create a Python 3 function that
stops and destroy a group.

Response:
def delete_group(self, group_id, force=False):
        """Stop and destroy a group.

        :param str group_id: group ID
        :param bool force: apply even if a deployment is in progress

        :returns: a dict containing the deleted version
        :rtype: dict
        """
        params = {'force': force}
        response = self._do_request(
            'DELETE', '/v2/groups/{group_id}'.format(group_id=group_id), params=params)
        return response.json()


Instruction:
Explain what the following Python 3 code does
def scale_group(self, group_id, scale_by):
        data = {'scaleBy': scale_by}
        response = self._do_request(
            'PUT', '/v2/groups/{group_id}'.format(group_id=group_id), data=json.dumps(data))
        return response.json()

Response: Scale a group by a factor.


Instruction:
Here you have a function in Python 3, explain what it does
def list_tasks(self, app_id=None, **kwargs):
        response = self._do_request(
            'GET', '/v2/apps/%s/tasks' % app_id if app_id else '/v2/tasks')
        tasks = self._parse_response(
            response, MarathonTask, is_list=True, resource_name='tasks')
        [setattr(t, 'app_id', app_id)
         for t in tasks if app_id and t.app_id is None]
        for k, v in kwargs.items():
            tasks = [o for o in tasks if getattr(o, k) == v]

        return tasks

Response: List running tasks optionally filtered by app_id.


Instruction:
Can you generate the documentation for the following Python 3 function
def kill_given_tasks(self, task_ids, scale=False, force=None):
        params = {'scale': scale}
        if force is not None:
            params['force'] = force
        data = json.dumps({"ids": task_ids})
        response = self._do_request(
            'POST', '/v2/tasks/delete', params=params, data=data)
        return response == 200

Response: Kill a list of given tasks.


Instruction:
How would you explain what the following Python 3 function does
def kill_tasks(self, app_id, scale=False, wipe=False,
                   host=None, batch_size=0, batch_delay=0):
        """Kill all tasks belonging to app.

        :param str app_id: application ID
        :param bool scale: if true, scale down the app by the number of tasks killed
        :param str host: if provided, only terminate tasks on this Mesos slave
        :param int batch_size: if non-zero, terminate tasks in groups of this size
        :param int batch_delay: time (in seconds) to wait in between batched kills. If zero, automatically determine

        :returns: list of killed tasks
        :rtype: list[:class:`marathon.models.task.MarathonTask`]
        """
        def batch(iterable, size):
            sourceiter = iter(iterable)
            while True:
                batchiter = itertools.islice(sourceiter, size)
                yield itertools.chain([next(batchiter)], batchiter)

        if batch_size == 0:
            # Terminate all at once
            params = {'scale': scale, 'wipe': wipe}
            if host:
                params['host'] = host
            response = self._do_request(
                'DELETE', '/v2/apps/{app_id}/tasks'.format(app_id=app_id), params)
            # Marathon is inconsistent about what type of object it returns on the multi
            # task deletion endpoint, depending on the version of Marathon. See:
            # https://github.com/mesosphere/marathon/blob/06a6f763a75fb6d652b4f1660685ae234bd15387/src/main/scala/mesosphere/marathon/api/v2/AppTasksResource.scala#L88-L95
            if "tasks" in response.json():
                return self._parse_response(response, MarathonTask, is_list=True, resource_name='tasks')
            else:
                return response.json()
        else:
            # Terminate in batches
            tasks = self.list_tasks(
                app_id, host=host) if host else self.list_tasks(app_id)
            for tbatch in batch(tasks, batch_size):
                killed_tasks = [self.kill_task(app_id, t.id, scale=scale, wipe=wipe)
                                for t in tbatch]

                # Pause until the tasks have been killed to avoid race
                # conditions
                killed_task_ids = set(t.id for t in killed_tasks)
                running_task_ids = killed_task_ids
                while killed_task_ids.intersection(running_task_ids):
                    time.sleep(1)
                    running_task_ids = set(
                        t.id for t in self.get_app(app_id).tasks)

                if batch_delay == 0:
                    # Pause until the replacement tasks are healthy
                    desired_instances = self.get_app(app_id).instances
                    running_instances = 0
                    while running_instances < desired_instances:
                        time.sleep(1)
                        running_instances = sum(
                            t.started_at is None for t in self.get_app(app_id).tasks)
                else:
                    time.sleep(batch_delay)

            return tasks

Response: Kill all tasks belonging to an app.


Instruction:
Can you generate the documentation for the following Python 3 function
def kill_task(self, app_id, task_id, scale=False, wipe=False):
        params = {'scale': scale, 'wipe': wipe}
        response = self._do_request('DELETE', '/v2/apps/{app_id}/tasks/{task_id}'
                                    .format(app_id=app_id, task_id=task_id), params)
        # Marathon is inconsistent about what type of object it returns on the multi
        # task deletion endpoint, depending on the version of Marathon. See:
        # https://github.com/mesosphere/marathon/blob/06a6f763a75fb6d652b4f1660685ae234bd15387/src/main/scala/mesosphere/marathon/api/v2/AppTasksResource.scala#L88-L95
        if "task" in response.json():
            return self._parse_response(response, MarathonTask, is_list=False, resource_name='task')
        else:
            return response.json()

Response:
Kill a task.

        :param str app_id: application ID
        :param str task_id: the task to kill
        :param bool scale: if true, scale down the app by one if the task exists

        :returns: the killed task
        :rtype: :class:`marathon.models.task.MarathonTask`


Instruction:
Here you have a function in Python 3, explain what it does
def list_versions(self, app_id):
        response = self._do_request(
            'GET', '/v2/apps/{app_id}/versions'.format(app_id=app_id))
        return [version for version in response.json()['versions']]

Response: List the versions of an app.


Instruction:
Make a summary of the following Python 3 code
def get_version(self, app_id, version):
        response = self._do_request('GET', '/v2/apps/{app_id}/versions/{version}'
                                    .format(app_id=app_id, version=version))
        return MarathonApp.from_json(response.json())

Response: Get the configuration of an app at a specific version.


Instruction:
Can you tell what is the following Python 3 function doing
def create_event_subscription(self, url):
        params = {'callbackUrl': url}
        response = self._do_request('POST', '/v2/eventSubscriptions', params)
        return response.json()

Response: Register a callback URL as an event subscriber.


Instruction:
Create a Python 3 function to
list all running deployments.

Response:
def list_deployments(self):
        """List all running deployments.

        :returns: list of deployments
        :rtype: list[:class:`marathon.models.deployment.MarathonDeployment`]
        """
        response = self._do_request('GET', '/v2/deployments')
        return self._parse_response(response, MarathonDeployment, is_list=True)


Instruction:
Can you generate the documentation for the following Python 3 function
def list_queue(self, embed_last_unused_offers=False):
        if embed_last_unused_offers:
            params = {'embed': 'lastUnusedOffers'}
        else:
            params = {}
        response = self._do_request('GET', '/v2/queue', params=params)
        return self._parse_response(response, MarathonQueueItem, is_list=True, resource_name='queue')

Response: List all the tasks queued up or waiting to be scheduled.


Instruction:
Implement a function in Python 3 to
cancel a deployment. :param str deployment_id: deployment id :param bool force: if true, don't create a rollback deployment to restore the previous configuration :returns: a dict containing the deployment id and version (empty dict if force=True) :rtype: dict

Response:
def delete_deployment(self, deployment_id, force=False):
        """Cancel a deployment.

        :param str deployment_id: deployment id
        :param bool force: if true, don't create a rollback deployment to restore the previous configuration

        :returns: a dict containing the deployment id and version (empty dict if force=True)
        :rtype: dict
        """
        if force:
            params = {'force': True}
            self._do_request('DELETE', '/v2/deployments/{deployment}'.format(
                deployment=deployment_id), params=params)
            # Successful DELETE with ?force=true returns empty text (and status
            # code 202). Client code should poll until deployment is removed.
            return {}
        else:
            response = self._do_request(
                'DELETE', '/v2/deployments/{deployment}'.format(deployment=deployment_id))
            return response.json()


Instruction:
Here you have a function in Python 3, explain what it does
def event_stream(self, raw=False, event_types=None):

        ef = EventFactory()

        params = {
            'event_type': [
                EventFactory.class_to_event[et] if isinstance(
                    et, type) and issubclass(et, MarathonEvent) else et
                for et in event_types or []
            ]
        }

        for raw_message in self._do_sse_request('/v2/events', params=params):
            try:
                _data = raw_message.decode('utf8').split(':', 1)

                if _data[0] == 'data':
                    if raw:
                        yield _data[1]
                    else:
                        event_data = json.loads(_data[1].strip())
                        if 'eventType' not in event_data:
                            raise MarathonError('Invalid event data received.')
                        yield ef.process(event_data)
            except ValueError:
                raise MarathonError('Invalid event data received.')

Response: Polls event bus using / v2 / events


Instruction:
Can you write a function in Python 3 where it
checks if a path is a correct format that Marathon expects. Raises ValueError if not valid.

Response:
def assert_valid_path(path):
    """Checks if a path is a correct format that Marathon expects. Raises ValueError if not valid.

    :param str path: The app id.

    :rtype: str
    """
    if path is None:
        return
    # As seen in:
    # https://github.com/mesosphere/marathon/blob/0c11661ca2f259f8a903d114ef79023649a6f04b/src/main/scala/mesosphere/marathon/state/PathId.scala#L71
    for id in filter(None, path.strip('/').split('/')):
        if not ID_PATTERN.match(id):
            raise ValueError(
                'invalid path (allowed: lowercase letters, digits, hyphen, "/", ".", ".."): %r' % path)
    return path


Instruction:
Explain what the following Python 3 code does
def assert_valid_id(id):
    if id is None:
        return
    if not ID_PATTERN.match(id.strip('/')):
        raise ValueError(
            'invalid id (allowed: lowercase letters, digits, hyphen, ".", ".."): %r' % id)
    return id

Response: Checks if an id is the correct format that Marathon expects. Raises ValueError if not valid.


Instruction:
Can you create a Python 3 function that
constructs a JSON - friendly representation of the object.

Response:
def json_repr(self, minimal=False):
        """Construct a JSON-friendly representation of the object.

        :param bool minimal: Construct a minimal representation of the object (ignore nulls and empty collections)

        :rtype: dict
        """
        if minimal:
            return {to_camel_case(k): v for k, v in vars(self).items() if (v or v is False or v == 0)}
        else:
            return {to_camel_case(k): v for k, v in vars(self).items()}


Instruction:
Can you implement a function in Python 3 that
constructs an object from a parsed response.

Response:
def from_json(cls, attributes):
        """Construct an object from a parsed response.

        :param dict attributes: object attributes from parsed response
        """
        return cls(**{to_snake_case(k): v for k, v in attributes.items()})


Instruction:
Write a Python 3 script for
encoding an object as a JSON string.

Response:
def to_json(self, minimal=True):
        """Encode an object as a JSON string.

        :param bool minimal: Construct a minimal representation of the object (ignore nulls and empty collections)

        :rtype: str
        """
        if minimal:
            return json.dumps(self.json_repr(minimal=True), cls=MarathonMinimalJsonEncoder, sort_keys=True)
        else:
            return json.dumps(self.json_repr(), cls=MarathonJsonEncoder, sort_keys=True)


Instruction:
Can you tell what is the following Python 3 function doing
def json_repr(self, minimal=False):
        if self.value:
            return [self.field, self.operator, self.value]
        else:
            return [self.field, self.operator]

Response: Construct a JSON - friendly representation of the object.


Instruction:
Implement a Python 3 function for
constructing a MarathonConstraint from a parsed response.

Response:
def from_json(cls, obj):
        """Construct a MarathonConstraint from a parsed response.

        :param dict attributes: object attributes from parsed response

        :rtype: :class:`MarathonConstraint`
        """
        if len(obj) == 2:
            (field, operator) = obj
            return cls(field, operator)
        if len(obj) > 2:
            (field, operator, value) = obj
            return cls(field, operator, value)


Instruction:
Can you tell what is the following Python 3 function doing
def from_string(cls, constraint):
        obj = constraint.split(':')
        marathon_constraint = cls.from_json(obj)

        if marathon_constraint:
            return marathon_constraint

        raise ValueError("Invalid string format. "
                         "Expected `field:operator:value`")

Response: Returns a MarathonResource object from a string representation of a MarathonConstraint.


Instruction:
Make a summary of the following Python 3 code
def from_tasks(cls, tasks):

        endpoints = [
            [
                MarathonEndpoint(task.app_id, task.service_ports[
                                 port_index], task.host, task.id, port)
                for port_index, port in enumerate(task.ports)
            ]
            for task in tasks
        ]
        # Flatten result
        return [item for sublist in endpoints for item in sublist]

Response: Construct a list of MarathonEndpoints from a list of tasks.


Instruction:
Make a summary of the following Python 3 code
def _format_newlines(prefix, formatted_node, options):
    replacement = u''.join([
        options.NEWLINE,
        u'\n',
        prefix])
    return formatted_node.replace(u'\n', replacement)

Response: Convert newlines into U + 23EC characters followed by an actual newline and a tree prefix.


Instruction:
Write a Python 3 function that can
get a band with the specified tag.

Response:
def get_band(self, tag):
        """Gets a band.

        Gets a band with specified tag. If no tag is specified, the request will fail.
        If the tag is invalid, a brawlstars.InvalidTag will be raised.
        If the data is missing, a ValueError will be raised.
        If the connection times out, a brawlstars.Timeout will be raised.
        If the data was unable to be received, a brawlstars.HTTPError will be raised along with the
        HTTP status code.
        On success, will return a Band.
        """

        tag = tag.strip("#")
        tag = tag.upper()

        try:
            resp = requests.get(self._base_url + 'bands/' + tag, headers=self.headers, timeout=self.timeout)
            if resp.status_code == 200:
                data = resp.json()
            elif 500 > resp.status_code > 400:
                raise HTTPError(resp.status_code)
            else:
                raise Error()
        except ValueError:
            raise MissingData('data')
        except Exception:
            raise Timeout()

        data = Box(data)
        band = Band(data)
        return band


Instruction:
Make a summary of the following Python 3 code
async def get_player(self, tag):

        tag = tag.strip("#")
        tag = tag.upper()

        try:
            async with self.session.get(self._base_url + 'players/' + tag, timeout=self.timeout,
                                        headers=self.headers) as resp:
                if resp.status == 200:
                    data = await resp.json()
                elif 500 > resp.status > 400:
                    raise HTTPError(resp.status)
                else:
                    raise Error()
        except asyncio.TimeoutError:
            raise Timeout()
        except ValueError:
            raise MissingData('data')
        except Exception:
            raise InvalidArg('tag')

        data = Box(data)
        player = Player(data)
        return player

Response: Gets a player with specified tag.