correcting the way we use the controllers and adding documentation

3 files changed, 34 insertions, 14 deletions

diff --git a/pyaggr3g470r/controllers/abstract.py b/pyaggr3g470r/controllers/abstract.py
index c084deb9..f1173817 100644
--- a/pyaggr3g470r/controllers/abstract.py
+++ b/pyaggr3g470r/controllers/abstract.py
@@ -9,11 +9,25 @@ class AbstractController(object):
     _db_cls = None  # reference to the database class
     _user_id_key = 'user_id'
 
-    def __init__(self, user_id):
+    def __init__(self, user_id=None):
+        """User id is a right management mechanism that should be used to
+        filter objects in database on their denormalized "user_id" field
+        (or "id" field for users).
+        Should no user_id be provided, the Controller won't apply any filter
+        allowing for a kind of "super user" mode.
+        """
         self.user_id = user_id
 
     def _to_filters(self, **filters):
-        if self.user_id:
+        """
+        Will translate filters to sqlalchemy filter.
+        This method will also apply user_id restriction if available.
+
+        each parameters of the function is treated as an equality unless the
+        name of the parameter ends with either "__gt", "__lt", "__ge", "__le",
+        "__ne" or "__in".
+        """
+        if self.user_id is not None:
             filters[self._user_id_key] = self.user_id
         db_filters = set()
         for key, value in filters.items():
@@ -37,17 +51,21 @@ class AbstractController(object):
         return self._db_cls.query.filter(*self._to_filters(**filters))
 
     def get(self, **filters):
+        """Will return one single objects corresponding to filters"""
         obj = self._get(**filters).first()
         if not obj:
             raise NotFound({'message': 'No %r (%r)'
                                 % (self._db_cls.__class__.__name__, filters)})
-        if getattr(obj, self._user_id_key) != self.user_id:
+        if self.user_id is not None \
+                and getattr(obj, self._user_id_key) != self.user_id:
             raise Forbidden({'message': 'No authorized to access %r (%r)'
                                 % (self._db_cls.__class__.__name__, filters)})
         return obj
 
     def create(self, **attrs):
-        attrs[self._user_id_key] = self.user_id
+        assert self._user_id_key in attrs or self.user_id is not None, \
+                "You must provide user_id one way or another"
+        attrs[self._user_id_key] = self.user_id or attrs.get(self._user_id_key)
         obj = self._db_cls(**attrs)
         db.session.add(obj)
         db.session.commit()
diff --git a/pyaggr3g470r/controllers/user.py b/pyaggr3g470r/controllers/user.py
index ed46e1e7..c6c1d545 100644
--- a/pyaggr3g470r/controllers/user.py
+++ b/pyaggr3g470r/controllers/user.py
@@ -4,4 +4,4 @@ from pyaggr3g470r.models import User
 
 class UserController(AbstractController):
     _db_cls = User
-    _user_id_key = 'email'
+    _user_id_key = 'id'
diff --git a/pyaggr3g470r/views/views.py b/pyaggr3g470r/views/views.py
index e202ad4d..fd970cba 100644
--- a/pyaggr3g470r/views/views.py
+++ b/pyaggr3g470r/views/views.py
@@ -93,7 +93,7 @@ def before_request():
 @login_manager.user_loader
 def load_user(email):
     # Return an instance of the User model
-    return controllers.UserController(email).get(email=email)
+    return controllers.UserController().get(email=email)
 
 
 #
@@ -153,7 +153,7 @@ def login():
     form = SigninForm()
 
     if form.validate_on_submit():
-        user = controllers.UserController(form.email.data).get(email=form.email.data)
+        user = controllers.UserController().get(email=form.email.data)
         login_user(user)
         g.user = user
         session['email'] = form.email.data
@@ -382,7 +382,7 @@ def inactives():
     List of inactive feeds.
     """
     nb_days = int(request.args.get('nb_days', 365))
-    user = controllers.UserController(g.user.email).get(email=g.user.email)
+    user = controllers.UserController(g.user.id).get(email=g.user.email)
     today = datetime.datetime.now()
     inactives = []
     for feed in user.feeds:
@@ -429,7 +429,7 @@ def export_articles():
     """
     Export all articles to HTML or JSON.
     """
-    user = controllers.UserController(g.user.email).get(id=g.user.id)
+    user = controllers.UserController(g.user.id).get(id=g.user.id)
     if request.args.get('format') == "HTML":
         # Export to HTML
         try:
@@ -439,7 +439,8 @@ def export_articles():
             return redirect(redirect_url())
         response = make_response(archive_file)
         response.headers['Content-Type'] = 'application/x-compressed'
-        response.headers['Content-Disposition'] = 'attachment; filename='+archive_file_name
+        response.headers['Content-Disposition'] = 'attachment; filename=%s' \
+                % archive_file_name
     elif request.args.get('format') == "JSON":
         # Export to JSON
         try:
@@ -461,8 +462,9 @@ def export_opml():
     """
     Export all feeds to OPML.
     """
-    user = controllers.UserController(g.user.email).get(id=g.user.id)
-    response = make_response(render_template('opml.xml', user=user, now=datetime.datetime.now()))
+    user = controllers.UserController(g.user.id).get(id=g.user.id)
+    response = make_response(render_template('opml.xml', user=user,
+                                             now=datetime.datetime.now()))
     response.headers['Content-Type'] = 'application/xml'
     response.headers['Content-Disposition'] = 'attachment; filename=feeds.opml'
     return response
@@ -637,7 +639,7 @@ def profile():
     """
     Edit the profile of the currently logged user.
     """
-    user = controllers.UserController(g.user.email).get(id=g.user.id)
+    user = controllers.UserController(g.user.id).get(id=g.user.id)
     form = ProfileForm()
 
     if request.method == 'POST':
@@ -663,7 +665,7 @@ def delete_account():
     """
     Delete the account of the user (with all its data).
     """
-    user = controllers.UserController(g.user.email).get(id=g.user.id)
+    user = controllers.UserController(g.user.id).get(id=g.user.id)
     if user is not None:
         db.session.delete(user)
         db.session.commit()