add docstrings to functions

add docstrings to functions

Change-Id: I112e297d20de5026784298e93b6ff05733639a1c
Implements: blueprint document-pycadf

16 files changed, 155 insertions, 4 deletions

diff --git a/pycadf/attachment.py b/pycadf/attachment.py
index 8519867..9b5e43e 100644
--- a/pycadf/attachment.py
+++ b/pycadf/attachment.py
@@ -43,6 +43,12 @@ class Attachment(cadftype.CADFAbstractType):
                                                              six.string_types))
 
     def __init__(self, typeURI=None, content=None, name=None):
+        """Create Attachment data type
+
+        :param typeURI: uri that identifies type of data in content
+        :param content: container that contains any type of data
+        :param contentType: name used to identify content.
+        """
         # Attachment.typeURI
         if typeURI is not None:
             setattr(self, ATTACHMENT_KEYNAME_TYPEURI, typeURI)
@@ -57,7 +63,8 @@ class Attachment(cadftype.CADFAbstractType):
 
     # self validate cadf:Attachment type against schema
     def is_valid(self):
-        # Existence test, All attributes must exist for valid Attachment type
+        """Validation to ensure Attachment required attributes are set.
+        """
         return (
             self._isset(ATTACHMENT_KEYNAME_TYPEURI) and
             self._isset(ATTACHMENT_KEYNAME_NAME) and
diff --git a/pycadf/credential.py b/pycadf/credential.py
index 3b7141a..e8836ce 100644
--- a/pycadf/credential.py
+++ b/pycadf/credential.py
@@ -38,6 +38,11 @@ class Credential(cadftype.CADFAbstractType):
         lambda x: isinstance(x, six.string_types))
 
     def __init__(self, token, type=None):
+        """Create Credential data type
+
+        :param token: identity or security token
+        :param type: type of credential (ie. identity token)
+        """
 
         # Credential.token
         setattr(self, CRED_KEYNAME_TOKEN, utils.mask_value(token))
@@ -48,5 +53,7 @@ class Credential(cadftype.CADFAbstractType):
 
     # TODO(mrutkows): validate this cadf:Credential type against schema
     def is_valid(self):
+        """Validation to ensure Credential required attributes are set.
+        """
         # TODO(mrutkows): validate specific attribute type/format
         return self._isset(CRED_KEYNAME_TOKEN)
diff --git a/pycadf/endpoint.py b/pycadf/endpoint.py
index 95f9895..b31a000 100644
--- a/pycadf/endpoint.py
+++ b/pycadf/endpoint.py
@@ -39,6 +39,12 @@ class Endpoint(cadftype.CADFAbstractType):
         ENDPOINT_KEYNAME_PORT, lambda x: isinstance(x, six.string_types))
 
     def __init__(self, url, name=None, port=None):
+        """Create Endpoint data type
+
+        :param url: address of endpoint
+        :param name: name of endpoint
+        :param port: port of endpoint
+        """
 
         # ENDPOINT.url
         setattr(self, ENDPOINT_KEYNAME_URL, url)
@@ -51,4 +57,6 @@ class Endpoint(cadftype.CADFAbstractType):
 
     # TODO(mrutkows): validate this cadf:ENDPOINT type against schema
     def is_valid(self):
+        """Validation to ensure Endpoint required attributes are set.
+        """
         return self._isset(ENDPOINT_KEYNAME_URL)
diff --git a/pycadf/event.py b/pycadf/event.py
index 3931a31..92a39c8 100644
--- a/pycadf/event.py
+++ b/pycadf/event.py
@@ -112,7 +112,22 @@ class Event(cadftype.CADFAbstractType):
                  action=cadftaxonomy.UNKNOWN, outcome=cadftaxonomy.UNKNOWN,
                  initiator=None, initiatorId=None, target=None, targetId=None,
                  severity=None, reason=None, observer=None, observerId=None):
+        """Create an Event
 
+        :param eventType: eventType of Event. Defaults to 'activity' type
+        :param id: id of event. will generate uuid if None
+        :param eventTime: time of event. will take current utc if None
+        :param action: event's action (see Action taxonomy)
+        :param outcome: Event's outcome (see Outcome taxonomy)
+        :param initiator: Event's Initiator Resource
+        :param initiatorId: Event's Initiator Resource id
+        :param target: Event's Target Resource
+        :param targetId: Event's Target Resource id
+        :param severity: domain-relative severity of Event
+        :param reason: domain-specific Reason type
+        :param observer: Event's Observer Resource
+        :param observerId: Event's Observer Resource id
+        """
         # Establish typeURI for the CADF Event data type
         # TODO(mrutkows): support extended typeURIs for Event subtypes
         setattr(self, EVENT_KEYNAME_TYPEURI, TYPE_URI_EVENT)
@@ -164,6 +179,10 @@ class Event(cadftype.CADFAbstractType):
 
     # Event.reporterchain
     def add_reporterstep(self, step):
+        """Add a Reporterstep
+
+        :param step: Reporterstep to be added to reporterchain
+        """
         if step is not None and isinstance(step, reporterstep.Reporterstep):
             if step.is_valid():
                 # Create the list of Reportersteps if needed
@@ -181,6 +200,10 @@ class Event(cadftype.CADFAbstractType):
 
     # Event.measurements
     def add_measurement(self, measure_val):
+        """Add a measurement value
+
+        :param measure_val: Measurement data type to be added to Event
+        """
         if (measure_val is not None
                 and isinstance(measure_val, measurement.Measurement)):
 
@@ -200,6 +223,10 @@ class Event(cadftype.CADFAbstractType):
 
     # Event.tags
     def add_tag(self, tag_val):
+        """Add Tag to Event
+
+        :param tag_val: Tag to add to event
+        """
         if tag.is_valid(tag_val):
             if not hasattr(self, EVENT_KEYNAME_TAGS):
                 setattr(self, EVENT_KEYNAME_TAGS, list())
@@ -209,6 +236,10 @@ class Event(cadftype.CADFAbstractType):
 
     # Event.attachments
     def add_attachment(self, attachment_val):
+        """Add Attachment to Event
+
+        :param attachment_val: Attachment to add to Event
+        """
         if (attachment_val is not None
                 and isinstance(attachment_val, attachment.Attachment)):
 
@@ -227,6 +258,8 @@ class Event(cadftype.CADFAbstractType):
 
     # self validate cadf:Event record against schema
     def is_valid(self):
+        """Validation to ensure Event required attributes are set.
+        """
         # TODO(mrutkows): Eventually, make sure all attributes are
         # from either the CADF spec. (or profiles thereof)
         # TODO(mrutkows): validate all child attributes that are CADF types
diff --git a/pycadf/eventfactory.py b/pycadf/eventfactory.py
index 2b33c41..f276860 100644
--- a/pycadf/eventfactory.py
+++ b/pycadf/eventfactory.py
@@ -32,6 +32,10 @@ class EventFactory(object):
        and reflect some policy decision.
     """
     def new_event(self, eventType=cadftype.EVENTTYPE_ACTIVITY, **kwargs):
+        """Create new event
+
+        :param eventType: eventType of event. Defaults to 'activitiy'
+        """
 
         # for now, construct a base ('activity') event as the default
         event_val = event.Event(**kwargs)
diff --git a/pycadf/geolocation.py b/pycadf/geolocation.py
index cbd6aa7..85e6a97 100644
--- a/pycadf/geolocation.py
+++ b/pycadf/geolocation.py
@@ -78,6 +78,17 @@ class Geolocation(cadftype.CADFAbstractType):
     def __init__(self, id=None, latitude=None, longitude=None,
                  elevation=None, accuracy=None, city=None, state=None,
                  regionICANN=None):
+        """Create Geolocation data type
+
+        :param id: id of geolocation
+        :param latitude: latitude of geolocation
+        :param longitude: longitude of geolocation
+        :param elevation: elevation of geolocation in meters
+        :param accuracy: accuracy of geolocation in meters
+        :param city: city of geolocation
+        :param state: state/province of geolocation
+        :param regionICANN: region of geolocation (ie. country)
+        """
 
         # Geolocation.id
         if id is not None:
diff --git a/pycadf/host.py b/pycadf/host.py
index 952b4f0..c5a8e7a 100644
--- a/pycadf/host.py
+++ b/pycadf/host.py
@@ -45,6 +45,13 @@ class Host(cadftype.CADFAbstractType):
 
     def __init__(self, id=None, address=None, agent=None,
                  platform=None):
+        """Create Host data type
+
+        :param id: id of Host
+        :param address: optional Address of Host
+        :param agent: agent (name) of Host
+        :param platform: platform of Host
+        """
 
         # Host.id
         if id is not None:
@@ -61,4 +68,6 @@ class Host(cadftype.CADFAbstractType):
 
     # TODO(mrutkows): validate this cadf:Host type against schema
     def is_valid(self):
+        """Validation to ensure Host required attributes are set.
+        """
         return True
diff --git a/pycadf/identifier.py b/pycadf/identifier.py
index 7b76708..28713dc 100644
--- a/pycadf/identifier.py
+++ b/pycadf/identifier.py
@@ -34,10 +34,14 @@ CONF.register_opts(opts, group='audit')
 # a full openstack namespace/domain value via some declaration (e.g.
 # "openstack:" == "http:\\www.openstack.org\")...
 def generate_uuid():
+    """Generate a CADF identifier
+    """
     return norm_ns(str(uuid.uuid4()))
 
 
 def norm_ns(str_id):
+    """Apply a namespace to the identifier
+    """
     prefix = CONF.audit.namespace + ':' if CONF.audit.namespace else ''
     return prefix + str_id
 
@@ -45,6 +49,8 @@ def norm_ns(str_id):
 # TODO(mrutkows): validate any cadf:Identifier (type) record against
 # CADF schema.  This would include schema validation as an optional parm.
 def is_valid(value):
+    """Validation to ensure Identifier is correct.
+    """
     if not isinstance(value, six.string_types):
         raise TypeError
     return True
diff --git a/pycadf/measurement.py b/pycadf/measurement.py
index 3cef90d..8ff72bf 100644
--- a/pycadf/measurement.py
+++ b/pycadf/measurement.py
@@ -45,7 +45,13 @@ class Measurement(cadftype.CADFAbstractType):
 
     def __init__(self, result=None, metric=None, metricId=None,
                  calculatedBy=None):
+        """Create Measurement data type
 
+        :param result: value of measurement
+        :param metric: Metric data type of current measurement
+        :param metricId: id of Metric data type of current measurement
+        :param calculatedBy: Resource that calculated measurement
+        """
         # Measurement.result
         if result is not None:
             setattr(self, MEASUREMENT_KEYNAME_RESULT, result)
@@ -64,6 +70,8 @@ class Measurement(cadftype.CADFAbstractType):
 
     # self validate this cadf:Measurement type against schema
     def is_valid(self):
+        """Validation to ensure Measurement required attributes are set.
+        """
         return (self._isset(MEASUREMENT_KEYNAME_RESULT) and
                 (self._isset(MEASUREMENT_KEYNAME_METRIC) ^
                  self._isset(MEASUREMENT_KEYNAME_METRICID)))
diff --git a/pycadf/metric.py b/pycadf/metric.py
index d110f2c..f8b4ae0 100644
--- a/pycadf/metric.py
+++ b/pycadf/metric.py
@@ -49,6 +49,12 @@ class Metric(cadftype.CADFAbstractType):
                                                              six.string_types))
 
     def __init__(self, metricId=None, unit=None, name=None):
+        """Create metric data type
+
+        :param metricId: id of metric. uuid generated if not provided
+        :param unit: unit of metric
+        :param name: name of metric
+        """
         # Metric.id
         setattr(self, METRIC_KEYNAME_METRICID,
                 metricId or identifier.generate_uuid())
@@ -70,6 +76,8 @@ class Metric(cadftype.CADFAbstractType):
 
     # self validate cadf:Metric type against schema
     def is_valid(self):
+        """Validation to ensure Metric required attributes are set.
+        """
         # Existence test, id, and unit attributes must both exist
         return (
             self._isset(METRIC_KEYNAME_METRICID) and
diff --git a/pycadf/reason.py b/pycadf/reason.py
index d4dd52b..ae70fb1 100644
--- a/pycadf/reason.py
+++ b/pycadf/reason.py
@@ -50,6 +50,13 @@ class Reason(cadftype.CADFAbstractType):
 
     def __init__(self, reasonType=None, reasonCode=None, policyType=None,
                  policyId=None):
+        """Create Reason data type
+
+        :param reasonType: domain URI which describes reasonCode
+        :param reasonCode: detailed result code
+        :param policyType: domain URI which describes policyId
+        :param policyId: id of policy applied that describes outcome
+        """
 
         # Reason.reasonType
         if reasonType is not None:
@@ -69,6 +76,8 @@ class Reason(cadftype.CADFAbstractType):
 
     # TODO(mrutkows): validate this cadf:Reason type against schema
     def is_valid(self):
+        """Validation to ensure Reason required attributes are set.
+        """
         # MUST have at least one valid pairing of reason+code or policy+id
         return ((self._isset(REASON_KEYNAME_REASONTYPE) and
                  self._isset(REASON_KEYNAME_REASONCODE)) or
diff --git a/pycadf/reporterstep.py b/pycadf/reporterstep.py
index 6cc03d6..1c307c2 100644
--- a/pycadf/reporterstep.py
+++ b/pycadf/reporterstep.py
@@ -50,6 +50,13 @@ class Reporterstep(cadftype.CADFAbstractType):
 
     def __init__(self, role=cadftype.REPORTER_ROLE_MODIFIER,
                  reporterTime=None, reporter=None, reporterId=None):
+        """Create ReporterStep data type
+
+        :param role: optional role of Reporterstep. Defaults to 'modifier'
+        :param reporterTime: utc time of Reporterstep.
+        :param reporter: CADF Resource of reporter
+        :param reporterId: id of CADF resource for reporter
+        """
         # Reporterstep.role
         setattr(self, REPORTERSTEP_KEYNAME_ROLE, role)
 
@@ -67,6 +74,8 @@ class Reporterstep(cadftype.CADFAbstractType):
 
     # self validate this cadf:Reporterstep type against schema
     def is_valid(self):
+        """Validation to ensure Reporterstep required attributes are set.
+        """
         return (
             self._isset(REPORTERSTEP_KEYNAME_ROLE) and
             (self._isset(REPORTERSTEP_KEYNAME_REPORTER) ^
diff --git a/pycadf/resource.py b/pycadf/resource.py
index b1d15bf..48ad7dc 100644
--- a/pycadf/resource.py
+++ b/pycadf/resource.py
@@ -88,6 +88,17 @@ class Resource(cadftype.CADFAbstractType):
     def __init__(self, id=None, typeURI=cadftaxonomy.UNKNOWN, name=None,
                  ref=None, domain=None, credential=None, host=None,
                  geolocation=None, geolocationId=None):
+        """Resource data type
+
+        :param id: id of resource
+        :param typeURI: typeURI of resource, defaults to 'unknown' if not set
+        :param name: name of resource
+        :param domain: domain to qualify name of resource
+        :param credential: optional security Credential data type
+        :param host: optional Host data type information relating to resource
+        :param geolocation: optional CADF Geolocation of resource
+        :param geolocationId: optional id of CADF Geolocation for resource
+        """
 
         # Resource.id
         setattr(self, RESOURCE_KEYNAME_ID, id or identifier.generate_uuid())
@@ -127,6 +138,10 @@ class Resource(cadftype.CADFAbstractType):
 
     # Resource.address
     def add_address(self, addr):
+        """Add CADF endpoints to Resource
+
+        :param addr: CADF Endpoint to add to Resource
+        """
         if (addr is not None and isinstance(addr, endpoint.Endpoint)):
             if addr.is_valid():
                 # Create the list of Endpoints if needed
@@ -142,6 +157,10 @@ class Resource(cadftype.CADFAbstractType):
 
     # Resource.attachments
     def add_attachment(self, attach_val):
+        """Add CADF attachment to Resource
+
+        :param attach_val: CADF Attachment to add to Resource
+        """
         if (attach_val is not None
                 and isinstance(attach_val, attachment.Attachment)):
             if attach_val.is_valid():
@@ -158,6 +177,8 @@ class Resource(cadftype.CADFAbstractType):
 
     # self validate this cadf:Resource type against schema
     def is_valid(self):
+        """Validation to ensure Resource required attributes are set
+        """
         return (self._isset(RESOURCE_KEYNAME_ID) and
                 (self._isset(RESOURCE_KEYNAME_TYPEURI) or
                  ((getattr(self, RESOURCE_KEYNAME_ID) == "target" or
diff --git a/pycadf/tag.py b/pycadf/tag.py
index b9cb627..3ee78e0 100644
--- a/pycadf/tag.py
+++ b/pycadf/tag.py
@@ -20,8 +20,11 @@ import six
 
 
 def generate_name_value_tag(name, value):
-    # TODO(mrutkows): detailed test/concatenation of independent values
-    # into a URI
+    """Generate a CADF tag in the format name?value=<value>
+
+    :param name: name of tag
+    :param valuue: optional value tag
+    """
     if name is None or value is None:
         raise ValueError('Invalid name and/or value. Values cannot be None')
 
@@ -31,6 +34,8 @@ def generate_name_value_tag(name, value):
 
 # TODO(mrutkows): validate any Tag's name?value= format
 def is_valid(value):
+    """Validation check to ensure proper Tag format
+    """
     if not isinstance(value, six.string_types):
         raise TypeError
     return True
diff --git a/pycadf/timestamp.py b/pycadf/timestamp.py
index 0afd563..82383c0 100644
--- a/pycadf/timestamp.py
+++ b/pycadf/timestamp.py
@@ -24,6 +24,10 @@ TIME_FORMAT = "%Y-%m-%dT%H:%M:%S.%f%z"
 
 
 def get_utc_now(timezone=None):
+    """Return the current UTC time.
+
+    :param timezone: an optional timezone param to offset time to.
+    """
     utc_datetime = pytz.utc.localize(datetime.datetime.utcnow())
     if timezone is not None:
         try:
@@ -36,6 +40,8 @@ def get_utc_now(timezone=None):
 # TODO(mrutkows): validate any cadf:Timestamp (type) record against
 # CADF schema
 def is_valid(value):
+    """Validation to ensure timestamp is a string.
+    """
     if not isinstance(value, six.string_types):
         raise ValueError('Timestamp should be a String')
 
diff --git a/pycadf/utils.py b/pycadf/utils.py
index fba4fbf..75a96ef 100644
--- a/pycadf/utils.py
+++ b/pycadf/utils.py
@@ -20,7 +20,7 @@ def mask_value(value, s_percent=0.125):
     """Obfuscate a given string to show only a percentage of leading
     and trailing characters.
 
-    :param s_percent: The percentage of characters to replace
+    :param s_percent: The percentage (in decimal) of characters to replace
     """
     if isinstance(value, six.string_types):
         visible = (32 if int(round(len(value) * s_percent)) > 32