Added comments to db_adapter files.

flask_user/db_adapters/db_adapter_interface.py

@@ -20,21 +20,37 @@ def __init__(self, app, db):
         self.app = app
         self.db = db
 
-    def get_object(self, ObjectClass, id):
-        """ Retrieve object of type ``ObjectClass`` by ``id``.
+    def add_object(self, ObjectClass, **kwargs):
+        """ Add a new object of type ``ObjectClass``,
+        with fields and values specified in ``**kwargs``.
+        """
+        raise NotImplementedError
 
-        | Returns object on success.
-        | Returns None otherwise.
+    def commit(self):
+        """Save modified objects in the database session.
+        Only used by session-centric object-database mappers.
         """
         raise NotImplementedError
 
+    def delete_object(self, object):
+        """ Delete object specified by ``object``."""
+        raise NotImplementedError
+
     def find_objects(self, ObjectClass, **kwargs):
         """ Retrieve all objects of type ``ObjectClass``,
         matching the filters specified in ``**kwargs`` -- case sensitive.
         """
 
         raise NotImplementedError
 
+    def get_object(self, ObjectClass, id):
+        """ Retrieve object of type ``ObjectClass`` by ``id``.
+
+        | Returns object on success.
+        | Returns None otherwise.
+        """
+        raise NotImplementedError
+
     def find_first_object(self, ObjectClass, **kwargs):
         """ Retrieve the first object of type ``ObjectClass``,
         matching the filters specified in ``**kwargs`` -- case sensitive.
@@ -53,15 +69,13 @@ def ifind_first_object(self, ObjectClass, **kwargs):
         """
         raise NotImplementedError
 
-    def add_object(self, ObjectClass, **kwargs):
-        """ Add a new object of type ``ObjectClass``,
-        with fields and values specified in ``**kwargs``.
-        """
-        raise NotImplementedError
-
     def update_object(self, object, **kwargs):
         """ Update an existing object, specified by ``object``,
         with the fields and values specified in ``**kwargs``.
+
+        .. note::
+
+            Role management methods.
         """
         # Convert name=value kwargs to object.name=value
         for key,value in kwargs.items():
@@ -70,18 +84,9 @@ def update_object(self, object, **kwargs):
             else:
                 raise KeyError("Object '%s' has no field '%s'." % (type(object), key))
 
-    def delete_object(self, object):
-        """ Delete object specified by ``object``."""
-        raise NotImplementedError
-
-    def commit(self):
-        """Save modified objects in the database session.
 
-        .. note::
-
-            User-class specific utility methods.
-        """
-        raise NotImplementedError
+    # Role management methods
+    # -----------------------
 
     def add_user_role(self, user, role_name, RoleClass=None):
         """ Add a ``role_name`` role to ``user``."""
@@ -92,10 +97,14 @@ def get_user_roles(self, user):
 
         .. note::
 
-            Database specific utility methods.
+            Database management methods.
         """
         raise NotImplementedError
 
+
+    # Database management methods
+    # ---------------------------
+
     def create_all_tables(self):
         """Create database tables for all known database data-models."""
 

flask_user/db_adapters/dynamo_db_adapter.py

@@ -30,14 +30,20 @@ def __init__(self, app, db):
         |    app = Flask(__name__)
         |    db = MongoEngine()
         |    db_adapter = DynamoDbAdapter(app, db)
-
-        .. note::
-
-            Generic methods.
         """
         # This no-op method is defined to show it in Sphinx docs in order 'bysource'
         super(DynamoDbAdapter, self).__init__(app, db)
 
+    def add_object(self, ObjectClass, **kwargs):
+        """Add a new object of type ``ObjectClass``,
+        with fields and values specified in ``**kwargs``.
+        """
+
+        print('dynamo.add_object(%s, %s)' % (ObjectClass, str(kwargs)))
+        object=ObjectClass(**kwargs)
+        self.db.engine.save(object)
+        return object
+
     def get_object(self, ObjectClass, id):
         """ Retrieve object of type ``ObjectClass`` by ``id``.
 
@@ -117,16 +123,6 @@ def ifind_first_object(self, ObjectClass, **kwargs):
         # Execute query
         return query.first(desc=True)
 
-    def add_object(self, ObjectClass, **kwargs):
-        """Add a new object of type ``ObjectClass``,
-        with fields and values specified in ``**kwargs``.
-        """
-
-        print('dynamo.add_object(%s, %s)' % (ObjectClass, str(kwargs)))
-        object=ObjectClass(**kwargs)
-        self.db.engine.save(object)
-        return object
-
     def update_object(self, object, **kwargs):
         """ Update an existing object, specified by ``object``,
         with the fields and values specified in ``**kwargs``.
@@ -144,16 +140,16 @@ def delete_object(self, object):
 
     def commit(self):
         """This method does nothing for DynamoDbAdapter.
-
-        .. note::
-
-            User-class specific utility methods.
         """
         # pdb.set_trace()
         print('dynamo.commit()')
         self.db.engine.sync()
         # self.db.session.commit()
 
+
+    # Role management methods
+    # -----------------------
+
     def add_user_role(self, user, role_name, RoleClass=None):
         """ Add a ``role_name`` role to ``user``."""
         # MongoEngine has a bug where
@@ -165,13 +161,13 @@ def add_user_role(self, user, role_name, RoleClass=None):
 
     def get_user_roles(self, user):
         """ Retrieve a list of user role names.
-
-        .. note::
-
-            Database specific utility methods.
         """
         return user.roles
 
+
+    # Database management methods
+    # ---------------------------
+
     def create_all_tables(self):
         """This method does nothing for DynamoDbAdapter."""
         pass # TODO

flask_user/db_adapters/mongo_db_adapter.py

@@ -29,14 +29,19 @@ def __init__(self, app, db):
         |    app = Flask(__name__)
         |    db = MongoEngine()
         |    db_adapter = MongoDbAdapter(app, db)
-
-        .. note::
-
-            Generic methods.
         """
         # This no-op method is defined to show it in Sphinx docs in order 'bysource'
         super(MongoDbAdapter, self).__init__(app, db)
 
+    def add_object(self, ObjectClass, **kwargs):
+        """Add a new object of type ``ObjectClass``,
+        with fields and values specified in ``**kwargs``.
+        """
+
+        object = ObjectClass(**kwargs)
+        object.save()
+        return object
+
     def get_object(self, ObjectClass, id):
         """ Retrieve object of type ``ObjectClass`` by ``id``.
 
@@ -81,15 +86,6 @@ def ifind_first_object(self, ObjectClass, **kwargs):
         # Retrieve first object
         return ObjectClass.objects(**ikwargs).first()
 
-    def add_object(self, ObjectClass, **kwargs):
-        """Add a new object of type ``ObjectClass``,
-        with fields and values specified in ``**kwargs``.
-        """
-
-        object = ObjectClass(**kwargs)
-        object.save()
-        return object
-
     def update_object(self, object, **kwargs):
         """ Update an existing object, specified by ``object``,
         with the fields and values specified in ``**kwargs``.
@@ -105,13 +101,13 @@ def delete_object(self, object):
 
     def commit(self):
         """This method does nothing for MongoDbAdapter.
-
-        .. note::
-
-            User-class specific utility methods.
         """
         pass
 
+
+    # Role management methods
+    # -----------------------
+
     def add_user_role(self, user, role_name, RoleClass=None):
         """ Add a ``role_name`` role to ``user``."""
         # MongoEngine has a bug where
@@ -123,13 +119,13 @@ def add_user_role(self, user, role_name, RoleClass=None):
 
     def get_user_roles(self, user):
         """ Retrieve a list of user role names.
-
-        .. note::
-
-            Database specific utility methods.
         """
         return user.roles
 
+
+    # Database management methods
+    # ---------------------------
+
     def create_all_tables(self):
         """This method does nothing for MongoDbAdapter."""
         pass

flask_user/db_adapters/sql_db_adapter.py

@@ -27,14 +27,18 @@ def __init__(self, app, db):
         |     app = Flask(__name__)
         |     db = SQLAlchemy()
         |     db_adapter = SQLDbAdapter(app, db)
-
-        .. note::
-
-            Generic methods.
         """
         # This no-op method is defined to show it in Sphinx docs in order 'bysource'
         super(SQLDbAdapter, self).__init__(app, db)
 
+    def add_object(self, ObjectClass, **kwargs):
+        """ Add a new object of type ``ObjectClass``,
+        with fields and values specified in ``**kwargs``.
+        """
+        object=ObjectClass(**kwargs)
+        self.db.session.add(object)
+        return object
+
     def get_object(self, ObjectClass, id):
         """ Retrieve object of type ``ObjectClass`` by ``id``.
 
@@ -110,14 +114,6 @@ def ifind_first_object(self, ObjectClass, **kwargs):
         # Execute query
         return query.first()
 
-    def add_object(self, ObjectClass, **kwargs):
-        """ Add a new object of type ``ObjectClass``,
-        with fields and values specified in ``**kwargs``.
-        """
-        object=ObjectClass(**kwargs)
-        self.db.session.add(object)
-        return object
-
     def update_object(self, object, **kwargs):
         """ Update an existing object, specified by ``object``,
         with the fields and values specified in ``**kwargs``.
@@ -131,13 +127,13 @@ def delete_object(self, object):
 
     def commit(self):
         """Save modified objects in the database session.
-
-        .. note::
-
-            User-class specific utility methods.
         """
         self.db.session.commit()
 
+
+    # Role management methods
+    # -----------------------
+
     def add_user_role(self, user, role_name, RoleClass=None):
         """ Add a ``role_name`` role to ``user``."""
         # Get or add role
@@ -148,13 +144,13 @@ def add_user_role(self, user, role_name, RoleClass=None):
 
     def get_user_roles(self, user):
         """ Retrieve a list of user role names.
-
-        .. note::
-
-            Database specific utility methods.
         """
         return [role.name for role in user.roles]
 
+
+    # Database management methods
+    # ---------------------------
+
     def create_all_tables(self):
         """Create database tables for all known database data-models."""
         self.db.create_all()