Improve markings docstrings
Including a note that the markings functions can be used as methods on SDO/SRO/MarkingDefinition objects.stix2.0
Chris Lenk
parent
ef6dade6f6
commit
c38483b631
|
|
@ -1,9 +1,14 @@
|
|||
"""
|
||||
Functions and classes for working with STIX 2 Data Markings.
|
||||
Functions for working with STIX 2 Data Markings.
|
||||
|
||||
These high level functions will operate on both object level markings and
|
||||
These high level functions will operate on both object-level markings and
|
||||
granular markings unless otherwise noted in each of the functions.
|
||||
|
||||
Note:
|
||||
These functions are also available as methods on SDOs, SROs, and Marking
|
||||
Definitions. The corresponding methods on those classes are identical to
|
||||
these functions except that the `obj` parameter is omitted.
|
||||
|
||||
|
||||
.. autosummary::
|
||||
:toctree: markings
|
||||
|
|
@ -20,7 +25,7 @@ from stix2.markings import granular_markings, object_markings
|
|||
|
||||
def get_markings(obj, selectors=None, inherited=False, descendants=False):
|
||||
"""
|
||||
Get all markings associated to the field(s).
|
||||
Get all markings associated to the field(s) specified by selectors.
|
||||
|
||||
Args:
|
||||
obj: An SDO or SRO object.
|
||||
|
|
@ -57,15 +62,15 @@ def get_markings(obj, selectors=None, inherited=False, descendants=False):
|
|||
|
||||
def set_markings(obj, marking, selectors=None):
|
||||
"""
|
||||
Removes all markings associated with selectors and appends a new granular
|
||||
Remove all markings associated with selectors and appends a new granular
|
||||
marking. Refer to `clear_markings` and `add_markings` for details.
|
||||
|
||||
Args:
|
||||
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: 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.
|
||||
|
||||
Returns:
|
||||
A new version of the given SDO or SRO with specified markings removed
|
||||
|
|
@ -84,14 +89,14 @@ def set_markings(obj, marking, selectors=None):
|
|||
|
||||
def remove_markings(obj, marking, selectors=None):
|
||||
"""
|
||||
Removes granular_marking from the granular_markings collection.
|
||||
Remove a marking from this object.
|
||||
|
||||
Args:
|
||||
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: 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.
|
||||
|
|
@ -114,14 +119,14 @@ def remove_markings(obj, marking, selectors=None):
|
|||
|
||||
def add_markings(obj, marking, selectors=None):
|
||||
"""
|
||||
Appends a granular_marking to the granular_markings collection.
|
||||
Append a marking to this object.
|
||||
|
||||
Args:
|
||||
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: 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.
|
||||
|
|
@ -142,7 +147,7 @@ def add_markings(obj, marking, selectors=None):
|
|||
|
||||
def clear_markings(obj, selectors=None):
|
||||
"""
|
||||
Removes all granular_marking associated with the selectors.
|
||||
Remove all markings associated with the selectors.
|
||||
|
||||
Args:
|
||||
obj: An SDO or SRO object.
|
||||
|
|
@ -170,14 +175,14 @@ def clear_markings(obj, selectors=None):
|
|||
|
||||
def is_marked(obj, marking=None, selectors=None, inherited=False, descendants=False):
|
||||
"""
|
||||
Checks if field(s) is marked by any marking or by specific marking(s).
|
||||
Check if field(s) is marked by any marking or by specific marking(s).
|
||||
|
||||
Args:
|
||||
obj: An SDO or SRO object.
|
||||
selectors: string or list of selectors strings relative to the SDO or
|
||||
SRO in which the field(s) appear(s).
|
||||
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 field(s) appear(s).
|
||||
inherited: If True, include object level markings and granular markings
|
||||
inherited to determine if the properties is/are marked.
|
||||
descendants: If True, include granular markings applied to any children
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@ from stix2.utils import new_version
|
|||
|
||||
def get_markings(obj, selectors, inherited=False, descendants=False):
|
||||
"""
|
||||
Get all markings associated to with the properties.
|
||||
Get all granular markings associated to with the properties.
|
||||
|
||||
Args:
|
||||
obj: An SDO or SRO object.
|
||||
|
|
@ -50,8 +50,8 @@ def get_markings(obj, selectors, inherited=False, descendants=False):
|
|||
|
||||
def set_markings(obj, marking, selectors):
|
||||
"""
|
||||
Removes all markings associated with selectors and appends a new granular
|
||||
marking. Refer to `clear_markings` and `add_markings` for details.
|
||||
Remove all granular markings associated with selectors and append a new
|
||||
granular marking. Refer to `clear_markings` and `add_markings` for details.
|
||||
|
||||
Args:
|
||||
obj: An SDO or SRO object.
|
||||
|
|
@ -71,14 +71,14 @@ def set_markings(obj, marking, selectors):
|
|||
|
||||
def remove_markings(obj, marking, selectors):
|
||||
"""
|
||||
Removes granular_marking from the granular_markings collection.
|
||||
Remove a granular marking from the granular_markings collection.
|
||||
|
||||
Args:
|
||||
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: 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.
|
||||
|
|
@ -123,14 +123,14 @@ def remove_markings(obj, marking, selectors):
|
|||
|
||||
def add_markings(obj, marking, selectors):
|
||||
"""
|
||||
Appends a granular_marking to the granular_markings collection.
|
||||
Append a granular marking to the granular_markings collection.
|
||||
|
||||
Args:
|
||||
obj: An SDO or SRO object.
|
||||
selectors: list of type string, selectors must be relative to the TLO
|
||||
in which the properties appear.
|
||||
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.
|
||||
|
|
@ -157,7 +157,7 @@ def add_markings(obj, marking, selectors):
|
|||
|
||||
def clear_markings(obj, selectors):
|
||||
"""
|
||||
Removes all granular_markings associated with the selectors.
|
||||
Remove all granular markings associated with the selectors.
|
||||
|
||||
Args:
|
||||
obj: An SDO or SRO object.
|
||||
|
|
@ -214,14 +214,14 @@ def clear_markings(obj, selectors):
|
|||
|
||||
def is_marked(obj, marking=None, selectors=None, inherited=False, descendants=False):
|
||||
"""
|
||||
Checks if field is marked by any marking or by specific marking(s).
|
||||
Check if field is marked by any marking or by specific marking(s).
|
||||
|
||||
Args:
|
||||
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: 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.
|
||||
inherited: If True, return markings inherited from the given selector.
|
||||
descendants: If True, return granular markings applied to any children
|
||||
of the given selector.
|
||||
|
|
|
|||
|
|
@ -23,7 +23,7 @@ def get_markings(obj):
|
|||
|
||||
def add_markings(obj, marking):
|
||||
"""
|
||||
Appends an object level marking to the object_marking_refs collection.
|
||||
Append an object level marking to the object_marking_refs collection.
|
||||
|
||||
Args:
|
||||
obj: A SDO or SRO object.
|
||||
|
|
@ -42,7 +42,7 @@ def add_markings(obj, marking):
|
|||
|
||||
def remove_markings(obj, marking):
|
||||
"""
|
||||
Removes object level marking from the object_marking_refs collection.
|
||||
Remove an object level marking from the object_marking_refs collection.
|
||||
|
||||
Args:
|
||||
obj: A SDO or SRO object.
|
||||
|
|
@ -76,7 +76,7 @@ def remove_markings(obj, marking):
|
|||
|
||||
def set_markings(obj, marking):
|
||||
"""
|
||||
Removes all object level markings and appends new object level markings to
|
||||
Remove all object level markings and append new object level markings to
|
||||
the collection. Refer to `clear_markings` and `add_markings` for details.
|
||||
|
||||
Args:
|
||||
|
|
@ -94,7 +94,7 @@ def set_markings(obj, marking):
|
|||
|
||||
def clear_markings(obj):
|
||||
"""
|
||||
Removes all object level markings from the object_marking_refs collection.
|
||||
Remove all object level markings from the object_marking_refs collection.
|
||||
|
||||
Args:
|
||||
obj: A SDO or SRO object.
|
||||
|
|
@ -108,7 +108,7 @@ def clear_markings(obj):
|
|||
|
||||
def is_marked(obj, marking=None):
|
||||
"""
|
||||
Checks if SDO or SRO is marked by any marking or by specific marking(s).
|
||||
Check if SDO or SRO is marked by any marking or by specific marking(s).
|
||||
|
||||
Args:
|
||||
obj: A SDO or SRO object.
|
||||
|
|
|
|||
|
|
@ -9,7 +9,7 @@ from stix2 import exceptions
|
|||
|
||||
|
||||
def _evaluate_expression(obj, selector):
|
||||
"""Walks an SDO or SRO generating selectors to match against ``selector``.
|
||||
"""Walk an SDO or SRO generating selectors to match against ``selector``.
|
||||
|
||||
If a match is found and the the value of this property is present in the
|
||||
objects. Matching value of the property will be returned.
|
||||
|
|
@ -32,7 +32,7 @@ def _evaluate_expression(obj, selector):
|
|||
|
||||
|
||||
def _validate_selector(obj, selector):
|
||||
"""Internal method to evaluate each selector."""
|
||||
"""Evaluate each selector against an object."""
|
||||
results = list(_evaluate_expression(obj, selector))
|
||||
|
||||
if len(results) >= 1:
|
||||
|
|
@ -132,7 +132,7 @@ def compress_markings(granular_markings):
|
|||
|
||||
|
||||
def expand_markings(granular_markings):
|
||||
"""Expands granular markings list.
|
||||
"""Expand granular markings list.
|
||||
|
||||
If there is more than one selector per granular marking. It will be
|
||||
expanded using the same marking_ref.
|
||||
|
|
@ -187,7 +187,7 @@ def expand_markings(granular_markings):
|
|||
|
||||
|
||||
def build_granular_marking(granular_marking):
|
||||
"""Returns a dictionary with the required structure for a granular marking.
|
||||
"""Return a dictionary with the required structure for a granular marking.
|
||||
"""
|
||||
return {"granular_markings": expand_markings(granular_marking)}
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue