From ca209a4e5a7421bb051bc302a8d7f98f419438bd Mon Sep 17 00:00:00 2001 From: Erik Nyquist Date: Sun, 4 Sep 2022 13:05:25 -0700 Subject: [PATCH] Bump version, update docs --- docs/_modules/versionedobj/object.html | 63 +++++++++++++++++++++++++- versionedobj/__init__.py | 2 +- 2 files changed, 62 insertions(+), 3 deletions(-) diff --git a/docs/_modules/versionedobj/object.html b/docs/_modules/versionedobj/object.html index 4559738..aca354b 100644 --- a/docs/_modules/versionedobj/object.html +++ b/docs/_modules/versionedobj/object.html @@ -116,6 +116,10 @@

Source code for versionedobj.object

 
 
 class _ObjField(object):
+    """
+    Represents a dynamic view of a single field in a versioned object. Can be used
+    to access the same field in either a VersionedConfig instance, or a dict
+    """
     def __init__(self, parents, fieldname, value):
         self.parents = parents
         self.fieldname = fieldname
@@ -128,9 +132,19 @@ 
Source code for versionedobj.object
         return self.__str__()
 
     def dot_name(self):
+        """
+        Get the full object name, with sub-object names separated by dots
+        """
         return '.'.join(self.parents + [self.fieldname])
 
     def get_obj_field(self, parent_obj):
+        """
+        Read the field value from the provided VersionedObject instance
+
+        :param parent_obj: object instance to read field from
+
+        :return: field value from object instance
+        """
         obj = parent_obj
 
         if self.parents:
@@ -146,6 +160,11 @@ 
Source code for versionedobj.object
         return getattr(obj, self.fieldname)
 
     def set_obj_field(self, parent_obj, create_nonexistent=False):
+        """
+        Set the field value on the provided VersionedObject instance
+
+        :param parent_obj: object instance to set field on
+        """
         obj = parent_obj
 
         if self.parents:
@@ -161,6 +180,11 @@ 
Source code for versionedobj.object
         return setattr(obj, self.fieldname, self.value)
 
     def set_dict_field(self, parent_attrs):
+        """
+        Set the field on the provided dict
+
+        :param parent_attrs: dict to set field on
+        """
         attrs = parent_attrs
 
         if self.parents:
@@ -184,8 +208,35 @@ 
Source code for versionedobj.object
 
         yield n
 
+def _field_should_be_skipped(dotname, only, ignore):
+    """
+    Check if a field should be skipped based on 'only' and 'ignore' parameters
+
+    :param list only: List of 'only' names
+    :param list ignore: List of 'ignore' names
+    """
+    if only:
+        found = False
+        for n in only:
+            if dotname.startswith(n):
+                found = True
+                break
+
+        return not found
+
+    for n in ignore:
+        if dotname.startswith(n):
+            return True
 
 def _walk_obj_attrs(parent_obj, only=[], ignore=[]):
+    """
+    Walk all fields (including nested fields) in a versioned object, and
+    generate an _ObjField instance for each field
+
+    :param parent_obj: Versioned object to walk
+    :param list only: List of 'only' names
+    :param list ignore: List of 'ignore' names
+    """
     parents = []
     obj_stack = [(None, parent_obj)]
 
@@ -202,11 +253,19 @@ 
Source code for versionedobj.object
             if isinstance(value, VersionedObject):
                 obj_stack.append((n, value))
             else:
-                if ((not only) or (dotname in only)) and (dotname not in ignore):
+                if not _field_should_be_skipped(dotname, only, ignore):
                     yield field
 
 
 def _walk_dict_attrs(obj, parent_attrs, only=[], ignore=[]):
+    """
+    Walk all fields (including nested fields) in a versioned object as a dict, and
+    generate an _ObjField instance for each field
+
+    :param parent_attrs: Dict to walk
+    :param list only: List of 'only' names
+    :param list ignore: List of 'ignore' names
+    """
     parents = []
     attrs_stack = [(None, parent_attrs)]
 
@@ -224,7 +283,7 @@ 
Source code for versionedobj.object
             if (isinstance(field_value, VersionedObject) and (type(value) == dict)):
                 attrs_stack.append((n, value))
             else:
-                if ((not only) or (dotname in only)) and (dotname not in ignore):
+                if not _field_should_be_skipped(dotname, only, ignore):
                     yield field
 
 
diff --git a/versionedobj/__init__.py b/versionedobj/__init__.py
index 13310a9..7517be9 100644
--- a/versionedobj/__init__.py
+++ b/versionedobj/__init__.py
@@ -1,3 +1,3 @@
-__version__ = "0.2.0"
+__version__ = "0.2.1"
 
 from versionedobj.object import VersionedObject, CustomValue, LoadObjError, InvalidFilterError