diff --git a/stix2/core.py b/stix2/core.py index 6861674..3c5fcba 100644 --- a/stix2/core.py +++ b/stix2/core.py @@ -25,12 +25,14 @@ def parse(data, allow_custom=False, version=None): Returns: An instantiated Python STIX object. - WARNING: 'allow_custom=True' will allow for the return of any supplied STIX - dict(s) that cannot be found to map to any known STIX object types (both STIX2 - domain objects or defined custom STIX2 objects); NO validation is done. This is - done to allow the processing of possibly unknown custom STIX objects (example - scenario: I need to query a third-party TAXII endpoint that could provide custom - STIX objects that I dont know about ahead of time) + Warnings: + 'allow_custom=True' will allow for the return of any supplied STIX + dict(s) that cannot be found to map to any known STIX object types + (both STIX2 domain objects or defined custom STIX2 objects); NO + validation is done. This is done to allow the processing of possibly + unknown custom STIX objects (example scenario: I need to query a + third-party TAXII endpoint that could provide custom STIX objects that + I don't know about ahead of time) """ # convert STIX object to dict, if not already @@ -49,9 +51,10 @@ def dict_to_stix2(stix_dict, allow_custom=False, version=None): stix_dict (dict): a python dictionary of a STIX object that (presumably) is semantically correct to be parsed into a full python-stix2 obj - allow_custom (bool): Whether to allow custom properties as well unknown - custom objects. Note that unknown custom objects cannot be parsed - into STIX objects, and will be returned as is. Default: False. + allow_custom (bool): Whether to allow custom properties as well + unknown custom objects. Note that unknown custom objects cannot + be parsed into STIX objects, and will be returned as is. + Default: False. version: Only used for bundles. If the spec_version property is missing, it is ambiguous what spec should be used to parse the bundle. In this case, this version parameter gives the spec @@ -60,12 +63,14 @@ def dict_to_stix2(stix_dict, allow_custom=False, version=None): Returns: An instantiated Python STIX object - WARNING: 'allow_custom=True' will allow for the return of any supplied STIX - dict(s) that cannot be found to map to any known STIX object types (both STIX2 - domain objects or defined custom STIX2 objects); NO validation is done. This is - done to allow the processing of possibly unknown custom STIX objects (example - scenario: I need to query a third-party TAXII endpoint that could provide custom - STIX objects that I dont know about ahead of time) + Warnings: + 'allow_custom=True' will allow for the return of any supplied STIX + dict(s) that cannot be found to map to any known STIX object types + (both STIX2 domain objects or defined custom STIX2 objects); NO + validation is done. This is done to allow the processing of + possibly unknown custom STIX objects (example scenario: I need to + query a third-party TAXII endpoint that could provide custom STIX + objects that I don't know about ahead of time) """ if 'type' not in stix_dict: diff --git a/stix2/utils.py b/stix2/utils.py index 2ccbc2c..ab382b5 100644 --- a/stix2/utils.py +++ b/stix2/utils.py @@ -170,9 +170,12 @@ def _find(seq, val): Search sequence 'seq' for val. This behaves like str.find(): if not found, -1 is returned instead of throwing an exception. - :param seq: The sequence to search - :param val: The value to search for - :return: The index of the value if found, or -1 if not found + Args: + seq: The sequence to search + val: The value to search for + + Returns: + int: The index of the value if found, or -1 if not found """ try: return seq.index(val) @@ -185,10 +188,13 @@ def _find_property_in_seq(seq, search_key, search_value): Helper for find_property_index(): search for the property in all elements of the given sequence. - :param seq: The sequence - :param search_key: Property name to find - :param search_value: Property value to find - :return: A property index, or -1 if the property was not found + Args: + seq: The sequence + search_key: Property name to find + search_value: Property value to find + + Returns: + int: A property index, or -1 if the property was not found """ idx = -1 for elem in seq: @@ -204,10 +210,13 @@ def find_property_index(obj, search_key, search_value): Search (recursively) for the given key and value in the given object. Return an index for the key, relative to whatever object it's found in. - :param obj: The object to search (list, dict, or stix object) - :param search_key: A search key - :param search_value: A search value - :return: An index; -1 if the key and value aren't found + Args: + obj: The object to search (list, dict, or stix object) + search_key: A search key + search_value: A search value + + Returns: + int: An index; -1 if the key and value aren't found """ from .base import _STIXBase @@ -302,14 +311,14 @@ def get_class_hierarchy_names(obj): def remove_custom_stix(stix_obj): """Remove any custom STIX objects or properties. - Warning: This function is a best effort utility, in that - it will remove custom objects and properties based on the - type names; i.e. if "x-" prefixes object types, and "x\\_" - prefixes property types. According to the STIX2 spec, - those naming conventions are a SHOULDs not MUSTs, meaning - that valid custom STIX content may ignore those conventions - and in effect render this utility function invalid when used - on that STIX content. + Warnings: + This function is a best effort utility, in that it will remove custom + objects and properties based on the type names; i.e. if "x-" prefixes + object types, and "x\\_" prefixes property types. According to the + STIX2 spec, those naming conventions are a SHOULDs not MUSTs, meaning + that valid custom STIX content may ignore those conventions and in + effect render this utility function invalid when used on that STIX + content. Args: stix_obj (dict OR python-stix obj): a single python-stix object