From e6af7edc49538f92f2c3e740ee8074cbebc00ff0 Mon Sep 17 00:00:00 2001
From: Samuel Gaist <samuel.gaist@idiap.ch>
Date: Mon, 28 May 2018 12:49:22 +0200
Subject: [PATCH] [dataformat] Added missing doc and fixed doc related warnings

Also fixed import warnings
---
 beat/backend/python/dataformat.py | 54 +++++++++++++++++--------------
 1 file changed, 30 insertions(+), 24 deletions(-)

diff --git a/beat/backend/python/dataformat.py b/beat/backend/python/dataformat.py
index 9946122..be16bb2 100644
--- a/beat/backend/python/dataformat.py
+++ b/beat/backend/python/dataformat.py
@@ -26,9 +26,14 @@
 ###############################################################################
 
 
-"""Validation and parsing for dataformats"""
+"""
+==========
+dataformat
+==========
+
+Validation and parsing for dataformats
+"""
 
-import os
 import re
 import copy
 
@@ -40,7 +45,7 @@ from . import utils
 from .baseformat import baseformat
 
 
-#----------------------------------------------------------
+# ----------------------------------------------------------
 
 
 class Storage(utils.Storage):
@@ -74,7 +79,7 @@ class Storage(utils.Storage):
         return super(Storage, self).hash('#description')
 
 
-#----------------------------------------------------------
+# ----------------------------------------------------------
 
 
 class DataFormat(object):
@@ -149,7 +154,7 @@ class DataFormat(object):
         try:
             self._load(data, dataformat_cache)
         finally:
-            if self._name is not None: #registers it into the cache, even if failed
+            if self._name is not None:  # registers it into the cache, even if failed
                 dataformat_cache[self._name] = self
 
 
@@ -170,7 +175,7 @@ class DataFormat(object):
             with open(json_path, 'rb') as f:
                 self.data = simplejson.loads(f.read().decode('utf-8'))
 
-        dataformat_cache[self._name] = self #registers itself into the cache
+        dataformat_cache[self._name] = self  # registers itself into the cache
 
         self.resolved = copy.deepcopy(self.data)
 
@@ -186,22 +191,22 @@ class DataFormat(object):
         def maybe_load_format(name, obj, dataformat_cache):
             """Tries to load a given dataformat from its relative path"""
 
-            if isinstance(obj, six.string_types) and obj.find('/') != -1: #load it
+            if isinstance(obj, six.string_types) and obj.find('/') != -1:  # load it
 
-                if obj in dataformat_cache: #reuse
+                if obj in dataformat_cache:  # reuse
 
-                    if dataformat_cache[obj] is None: #recursion detected
+                    if dataformat_cache[obj] is None:  # recursion detected
                         return self
 
                     self.referenced[obj] = dataformat_cache[obj]
 
-                else: #load it
+                else:  # load it
                     self.referenced[obj] = DataFormat(self.prefix, obj, (self, name),
                             dataformat_cache)
 
                 return self.referenced[obj]
 
-            elif isinstance(obj, dict): #can cache it, must load from scratch
+            elif isinstance(obj, dict):  # can cache it, must load from scratch
                 return DataFormat(self.prefix, obj, (self, name), dataformat_cache)
 
             elif isinstance(obj, list):
@@ -214,7 +219,7 @@ class DataFormat(object):
         # now checks that every referred dataformat is loaded, resolves it
         for field, value in self.data.items():
             if field in ('#description', '#schema_version'):
-                continue #skip the description and schema version meta attributes
+                continue  # skip the description and schema version meta attributes
             self.resolved[field] = maybe_load_format(field, value, dataformat_cache)
 
         # at this point, there should be no more external references in
@@ -228,8 +233,7 @@ class DataFormat(object):
             tmp = self.resolved
             self.resolved = basetype.resolved
             self.resolved.update(tmp)
-            del self.resolved['#extends'] #avoids infinite recursion
-
+            del self.resolved['#extends']  # avoids infinite recursion
 
     @property
     def name(self):
@@ -271,14 +275,14 @@ class DataFormat(object):
 
         Example:
 
-          To create an object respecting the data format from a JSON descriptor, use
-          the following technique:
+          To create an object respecting the data format from a JSON
+          descriptor, use the following technique:
 
           .. code-block:: python
 
-             ftype = dataformat(...).type
-             json = simplejson.loads(...)
-             newobj = ftype(**json) # instantiates the new object, checks format
+            ftype = dataformat(...).type
+            json = simplejson.loads(...)
+            newobj = ftype(**json) # instantiates the new object, checks format
 
           To dump the object into JSON, use the following technique:
 
@@ -307,7 +311,7 @@ class DataFormat(object):
         # create the converters for the class we're about to return
         for k, v in self.resolved.items():
 
-            if isinstance(v, list): #it is an array
+            if isinstance(v, list):  # it is an array
                 attributes[k] = copy.deepcopy(v)
                 if isinstance(v[-1], DataFormat):
                     attributes[k][-1] = v[-1].type
@@ -317,10 +321,10 @@ class DataFormat(object):
                     else:
                         attributes[k][-1] = numpy.dtype(v[-1])
 
-            elif isinstance(v, DataFormat): #it is another dataformat
+            elif isinstance(v, DataFormat):  # it is another dataformat
                 attributes[k] = v.type
 
-            else: #it is a simple type
+            else:  # it is a simple type
                 if v in ('string', 'str'):
                     attributes[k] = str
                 else:
@@ -335,6 +339,7 @@ class DataFormat(object):
 
     @property
     def valid(self):
+        """A boolean that indicates if this dataformat is valid or not"""
         return not bool(self.errors)
 
 
@@ -444,7 +449,8 @@ class DataFormat(object):
 
         Parameters:
 
-          indent (int): The number of indentation spaces at every indentation level
+          indent (int): The number of indentation spaces at every indentation
+            level
 
 
         Returns:
@@ -475,7 +481,7 @@ class DataFormat(object):
         if storage is None:
             if not self._name:
                 raise RuntimeError("dataformat has no name")
-            storage = self.storage #overwrite
+            storage = self.storage  # overwrite
 
         storage.save(str(self), self.description)
 
-- 
GitLab