granular_markings¶
Functions for working with STIX2 granular markings.
-
add_markings
(obj, marking, selectors)¶ Append a granular marking to the granular_markings collection. The method makes a best-effort attempt to distinguish between a marking-definition or language granular marking.
Parameters: - obj – An SDO or SRO object.
- marking – identifier or list of marking identifiers that apply to the properties selected by selectors.
- selectors – list of type string, selectors must be relative to the TLO in which the properties appear.
Raises: InvalidSelectorError
– If selectors fail validation.Returns: A new version of the given SDO or SRO with specified markings added.
-
clear_markings
(obj, selectors, marking_ref=True, lang=True)¶ Remove all granular markings associated with the selectors.
Parameters: - obj – An SDO or SRO object.
- selectors – string or list of selectors strings relative to the SDO or SRO in which the properties appear.
- marking_ref (bool) – If False, markings that use the
marking_ref
property will not be removed. - lang (bool) – If False, markings that use the
lang
property will not be removed.
Raises: InvalidSelectorError
– If selectors fail validation.MarkingNotFoundError
– If markings to remove are not found on the provided SDO or SRO.
Returns: A new version of the given SDO or SRO with specified markings cleared.
-
get_markings
(obj, selectors, inherited=False, descendants=False, marking_ref=True, lang=True)¶ Get all granular markings associated to with the properties.
Parameters: - obj – An SDO or SRO object.
- selectors – string or list of selector strings relative to the SDO or SRO in which the properties appear.
- inherited (bool) – If True, include markings inherited relative to the properties.
- descendants (bool) – If True, include granular markings applied to any children relative to the properties.
- marking_ref (bool) – If False, excludes markings that use
marking_ref
property. - lang (bool) – If False, excludes markings that use
lang
property.
Raises: InvalidSelectorError
– If selectors fail validation.Returns: list – Marking identifiers that matched the selectors expression.
-
is_marked
(obj, marking=None, selectors=None, inherited=False, descendants=False)¶ Check if field is marked by any marking or by specific marking(s).
Parameters: - obj – An SDO or SRO object.
- marking – identifier or list of marking identifiers that apply to the properties selected by selectors.
- selectors (bool) – string or list of selectors strings relative to the SDO or SRO in which the properties appear.
- inherited (bool) – If True, return markings inherited from the given selector.
- descendants (bool) – If True, return granular markings applied to any children of the given selector.
Raises: InvalidSelectorError
– If selectors fail validation.Returns: bool –
- True if
selectors
is found on internal SDO or SRO collection. False otherwise.
Note
When a list of marking identifiers is provided, if ANY of the provided marking identifiers match, True is returned.
-
remove_markings
(obj, marking, selectors)¶ Remove a granular marking from the granular_markings collection. The method makes a best-effort attempt to distinguish between a marking-definition or language granular marking.
Parameters: - obj – An SDO or SRO object.
- marking – identifier or list of marking identifiers that apply to the properties selected by selectors.
- selectors – string or list of selectors strings relative to the SDO or SRO in which the properties appear.
Raises: InvalidSelectorError
– If selectors fail validation.MarkingNotFoundError
– If markings to remove are not found on the provided SDO or SRO.
Returns: A new version of the given SDO or SRO with specified markings removed.
-
set_markings
(obj, marking, selectors, marking_ref=True, lang=True)¶ Remove all granular markings associated with selectors and append a new granular marking. Refer to clear_markings and add_markings for details.
Parameters: - obj – An SDO or SRO object.
- selectors – string or list of selector strings relative to the SDO or SRO in which the properties appear.
- marking – identifier or list of marking identifiers that apply to the properties selected by selectors.
- marking_ref (bool) – If False, markings that use the
marking_ref
property will not be removed. - lang (bool) – If False, markings that use the
lang
property will not be removed.
Returns: A new version of the given SDO or SRO with specified markings removed and new ones added.