serialization¶
STIX2 core serialization methods.
-
class
STIXJSONEncoder
(skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=False, sort_keys=False, indent=None, separators=None, encoding='utf-8', default=None, use_decimal=True, namedtuple_as_object=True, tuple_as_array=True, bigint_as_string=False, item_sort_key=None, for_json=False, ignore_nan=False, int_as_string_bitcount=None, iterable_as_array=False)¶ Custom JSONEncoder subclass for serializing Python
stix2
objects.If an optional property with a default value specified in the STIX 2 spec is set to that default value, it will be left out of the serialized output.
An example of this type of property include the
revoked
common property.-
default
(obj)¶ Implement this method in a subclass such that it returns a serializable object for
o
, or calls the base implementation (to raise aTypeError
).For example, to support arbitrary iterators, you could implement default like this:
def default(self, o): try: iterable = iter(o) except TypeError: pass else: return list(iterable) return JSONEncoder.default(self, o)
-
-
class
STIXJSONIncludeOptionalDefaultsEncoder
(skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=False, sort_keys=False, indent=None, separators=None, encoding='utf-8', default=None, use_decimal=True, namedtuple_as_object=True, tuple_as_array=True, bigint_as_string=False, item_sort_key=None, for_json=False, ignore_nan=False, int_as_string_bitcount=None, iterable_as_array=False)¶ Custom JSONEncoder subclass for serializing Python
stix2
objects.Differs from
STIXJSONEncoder
in that if an optional property with a default value specified in the STIX 2 spec is set to that default value, it will be included in the serialized output.-
default
(obj)¶ Implement this method in a subclass such that it returns a serializable object for
o
, or calls the base implementation (to raise aTypeError
).For example, to support arbitrary iterators, you could implement default like this:
def default(self, o): try: iterable = iter(o) except TypeError: pass else: return list(iterable) return JSONEncoder.default(self, o)
-
-
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.
Parameters: - 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
-
fp_serialize
(obj, fp, pretty=False, include_optional_defaults=False, **kwargs)¶ Serialize a STIX object to
fp
(a text stream file-like supporting object).Parameters: - obj – The STIX object to be serialized.
- fp – A text stream file-like object supporting
.write()
. - pretty (bool) – If True, output properties following the STIX specs
formatting. This includes indentation. Refer to notes for more
details. (Default:
False
) - include_optional_defaults (bool) – Determines whether to include optional properties set to the default value defined in the spec.
- **kwargs – The arguments for a json.dumps() call.
Returns: None
Note
The argument
pretty=True
will output the STIX object following spec order. Using this argument greatly impacts object serialization performance. If your use case is centered across machine-to-machine operation it is recommended to setpretty=False
.When
pretty=True
the following key-value pairs will be added or overridden: indent=4, separators=(“,”, “: “), item_sort_key=sort_by.
-
serialize
(obj, pretty=False, include_optional_defaults=False, **kwargs)¶ Serialize a STIX object.
Parameters: - obj – The STIX object to be serialized.
- pretty (bool) – If True, output properties following the STIX specs
formatting. This includes indentation. Refer to notes for more
details. (Default:
False
) - include_optional_defaults (bool) – Determines whether to include optional properties set to the default value defined in the spec.
- **kwargs – The arguments for a json.dumps() call.
Returns: str – The serialized JSON object.
Note
The argument
pretty=True
will output the STIX object following spec order. Using this argument greatly impacts object serialization performance. If your use case is centered across machine-to-machine operation it is recommended to setpretty=False
.When
pretty=True
the following key-value pairs will be added or overridden: indent=4, separators=(“,”, “: “), item_sort_key=sort_by.