Converted a large part of utils/ folder to google code docstrings as per #709.

evennia/utils/dbserialize.py

@@ -25,7 +25,6 @@ try:
     from cPickle import dumps, loads
 except ImportError:
     from pickle import dumps, loads
-from django.db import transaction
 from django.core.exceptions import ObjectDoesNotExist
 from django.contrib.contenttypes.models import ContentType
 from evennia.server.models import ServerConfig
@@ -52,8 +51,14 @@ else:
 
 def _TO_DATESTRING(obj):
     """
-    this will only be called with valid database objects. Returns datestring
-    on correct form.
+    Creates datestring hash.
+
+    Args:
+        obj (Object): Database object.
+
+    Returns:
+        datestring (str): A datestring hash.
+
     """
     try:
         return _GA(obj, "db_date_created").strftime(_DATESTRING)
@@ -209,8 +214,14 @@ class _SaverSet(_SaverMutable, MutableSet):
 def pack_dbobj(item):
     """
     Check and convert django database objects to an internal representation.
-    This either returns the original input item or a tuple
-      ("__packed_dbobj__", key, creation_time, id)
+
+    Args:
+        item (any): A database entity to pack
+
+    Returns:
+        packed (any or tuple): Either returns the original input item
+            or the packing tuple `("__packed_dbobj__", key, creation_time, id)`.
+
     """
     _init_globals()
     obj = item
@@ -224,10 +235,18 @@ def pack_dbobj(item):
 
 def unpack_dbobj(item):
     """
-    Check and convert internal representations back to Django database models.
-    The fact that item is a packed dbobj should be checked before this call.
-    This either returns the original input or converts the internal store back
-    to a database representation (its typeclass is returned if applicable).
+    Check and convert internal representations back to Django database
+    models.
+
+    Args:
+        item (packed_dbobj): The fact that item is a packed dbobj
+            should be checked before this call.
+
+    Returns:
+        unpacked (any): Either the original input or converts the
+            internal store back to a database representation (its
+            typeclass is returned if applicable).
+
     """
     _init_globals()
     try:
@@ -244,11 +263,18 @@ def unpack_dbobj(item):
 
 def to_pickle(data):
     """
-    This prepares data on arbitrary form to be pickled. It handles any nested
-    structure and returns data on a form that is safe to pickle (including
-    having converted any database models to their internal representation).
-    We also convert any Saver*-type objects back to their normal
-    representations, they are not pickle-safe.
+    This prepares data on arbitrary form to be pickled. It handles any
+    nested structure and returns data on a form that is safe to pickle
+    (including having converted any database models to their internal
+    representation).  We also convert any Saver*-type objects back to
+    their normal representations, they are not pickle-safe.
+
+    Args:
+        data (any): Data to pickle.
+
+    Returns:
+        data (any): Pickled data.
+
     """
     def process_item(item):
         "Recursive processor and identification of data"
@@ -281,13 +307,18 @@ def from_pickle(data, db_obj=None):
     object was removed (or changed in-place) in the database, None will be
     returned.
 
-    db_obj - this is the model instance (normally an Attribute) that
-             _Saver*-type iterables (_SaverList etc) will save to when they
-             update. It must have a 'value' property that saves assigned data
-             to the database. Skip if not serializing onto a given object.
+    Args_
+        data (any): Pickled data to unpickle.
+        db_obj (Atribute, any): This is the model instance (normally
+            an Attribute) that _Saver*-type iterables (_SaverList etc)
+            will save to when they update. It must have a 'value' property
+            that saves assigned data to the database. Skip if not
+            serializing onto a given object.  If db_obj is given, this
+            function will convert lists, dicts and sets to their
+            _SaverList, _SaverDict and _SaverSet counterparts.
 
-    If db_obj is given, this function will convert lists, dicts and sets
-    to their _SaverList, _SaverDict and _SaverSet counterparts.
+    Returns:
+        data (any): Unpickled data.
 
     """
     def process_item(item):