From b6d1bb26de500d4b4c325aae30fa38844ec9cef5 Mon Sep 17 00:00:00 2001 From: Chris Lenk Date: Fri, 22 Sep 2017 14:54:21 -0400 Subject: [PATCH] Improve utils docs, rename subpackage docs folders --- .../stix2.markings.granular_markings.rst | 0 .../stix2.markings.object_markings.rst | 0 .../stix2.markings.utils.rst | 0 .../stix2.sources.filesystem.rst | 0 .../stix2.sources.filters.rst | 0 .../{api => sources}/stix2.sources.memory.rst | 0 .../{api => sources}/stix2.sources.taxii.rst | 0 stix2/markings/__init__.py | 2 +- stix2/sources/__init__.py | 2 +- stix2/utils.py | 29 ++++++++++++++----- 10 files changed, 23 insertions(+), 10 deletions(-) rename docs/api/{api => markings}/stix2.markings.granular_markings.rst (100%) rename docs/api/{api => markings}/stix2.markings.object_markings.rst (100%) rename docs/api/{api => markings}/stix2.markings.utils.rst (100%) rename docs/api/{api => sources}/stix2.sources.filesystem.rst (100%) rename docs/api/{api => sources}/stix2.sources.filters.rst (100%) rename docs/api/{api => sources}/stix2.sources.memory.rst (100%) rename docs/api/{api => sources}/stix2.sources.taxii.rst (100%) diff --git a/docs/api/api/stix2.markings.granular_markings.rst b/docs/api/markings/stix2.markings.granular_markings.rst similarity index 100% rename from docs/api/api/stix2.markings.granular_markings.rst rename to docs/api/markings/stix2.markings.granular_markings.rst diff --git a/docs/api/api/stix2.markings.object_markings.rst b/docs/api/markings/stix2.markings.object_markings.rst similarity index 100% rename from docs/api/api/stix2.markings.object_markings.rst rename to docs/api/markings/stix2.markings.object_markings.rst diff --git a/docs/api/api/stix2.markings.utils.rst b/docs/api/markings/stix2.markings.utils.rst similarity index 100% rename from docs/api/api/stix2.markings.utils.rst rename to docs/api/markings/stix2.markings.utils.rst diff --git a/docs/api/api/stix2.sources.filesystem.rst b/docs/api/sources/stix2.sources.filesystem.rst similarity index 100% rename from docs/api/api/stix2.sources.filesystem.rst rename to docs/api/sources/stix2.sources.filesystem.rst diff --git a/docs/api/api/stix2.sources.filters.rst b/docs/api/sources/stix2.sources.filters.rst similarity index 100% rename from docs/api/api/stix2.sources.filters.rst rename to docs/api/sources/stix2.sources.filters.rst diff --git a/docs/api/api/stix2.sources.memory.rst b/docs/api/sources/stix2.sources.memory.rst similarity index 100% rename from docs/api/api/stix2.sources.memory.rst rename to docs/api/sources/stix2.sources.memory.rst diff --git a/docs/api/api/stix2.sources.taxii.rst b/docs/api/sources/stix2.sources.taxii.rst similarity index 100% rename from docs/api/api/stix2.sources.taxii.rst rename to docs/api/sources/stix2.sources.taxii.rst diff --git a/stix2/markings/__init__.py b/stix2/markings/__init__.py index 6c13b87..400c54d 100644 --- a/stix2/markings/__init__.py +++ b/stix2/markings/__init__.py @@ -6,7 +6,7 @@ granular markings unless otherwise noted in each of the functions. .. autosummary:: - :toctree: api + :toctree: markings granular_markings object_markings diff --git a/stix2/sources/__init__.py b/stix2/sources/__init__.py index 8e19d1d..a8c27da 100644 --- a/stix2/sources/__init__.py +++ b/stix2/sources/__init__.py @@ -16,7 +16,7 @@ Note: .. autosummary:: - :toctree: api + :toctree: sources filters filesystem diff --git a/stix2/utils.py b/stix2/utils.py index ca195f6..8b9a136 100644 --- a/stix2/utils.py +++ b/stix2/utils.py @@ -34,16 +34,21 @@ class STIXdatetime(dt.datetime): def get_timestamp(): + """Return a STIX timestamp of the current date and time.""" return STIXdatetime.now(tz=pytz.UTC) def format_datetime(dttm): - # 1. Convert to timezone-aware - # 2. Convert to UTC - # 3. Format in ISO format - # 4. Ensure correct precision - # 4a. Add subsecond value if non-zero and precision not defined - # 5. Add "Z" + """Convert a datetime object into a valid STIX timestamp string. + + 1. Convert to timezone-aware + 2. Convert to UTC + 3. Format in ISO format + 4. Ensure correct precision + a. Add subsecond value if non-zero and precision not defined + 5. Add "Z" + + """ if dttm.tzinfo is None or dttm.tzinfo.utcoffset(dttm) is None: # dttm is timezone-naive; assume UTC @@ -63,6 +68,8 @@ def format_datetime(dttm): def parse_into_datetime(value, precision=None): + """Parse a value into a valid STIX timestamp object. + """ if isinstance(value, dt.date): if hasattr(value, 'hour'): ts = value @@ -102,6 +109,7 @@ def parse_into_datetime(value, precision=None): def get_dict(data): """Return data as a dictionary. + Input can be a dictionary, string, or file-like object. """ @@ -124,7 +132,7 @@ def get_dict(data): def find_property_index(obj, properties, tuple_to_find): """Recursively find the property in the object model, return the index - according to the _properties OrderedDict. If its a list look for + according to the _properties OrderedDict. If it's a list look for individual objects. """ from .base import _STIXBase @@ -159,7 +167,7 @@ def find_property_index(obj, properties, tuple_to_find): def new_version(data, **kwargs): """Create a new version of a STIX object, by modifying properties and - updating the `modified` property. + updating the ``modified`` property. """ if not isinstance(data, Mapping): @@ -196,6 +204,11 @@ def new_version(data, **kwargs): def revoke(data): + """Revoke a STIX object. + + Returns: + A new version of the object with ``revoked`` set to ``True``. + """ if not isinstance(data, Mapping): raise ValueError('cannot revoke object of this type! Try a dictionary ' 'or instance of an SDO or SRO class.')