Merge "(no-ticket) Document TimestampingMiddleware and minor changes"

oioioi/base/middleware.py

@@ -8,7 +8,7 @@
 
 class TimestampingMiddleware(object):
     """Middleware which adds an attribute ``timestamp`` to each ``request``
-       object, representing the request time as :cls:`datetime.datetime`
+       object, representing the request time as :class:`datetime.datetime`
        instance.
 
        It should be placed as close to the begging of the list of middlewares
@@ -43,7 +43,7 @@ def process_request(self, request):
                 " authentication middleware to be installed.  Edit your"
                 " MIDDLEWARE_CLASSES setting to insert"
                 " 'django.contrib.auth.middleware.AuthenticationMiddleware'"
-                " before the AnnotateUserBackendMiddleware lass.")
+                " before the AnnotateUserBackendMiddleware class.")
 
         if BACKEND_SESSION_KEY in request.session:
             # Barbarously discard request.user laziness.

oioioi/base/permissions.py

@@ -84,6 +84,9 @@ def wrap_condition(func):
         return condition
     return wrap_condition
 
+
+#: Shortcut for ``make_condition(RequestBasedCondition)``.
+#: See example usage below.
 make_request_condition = make_condition(RequestBasedCondition)
 
 

oioioi/su/__init__.py

@@ -1,8 +1,8 @@
 """The SU app is used to change the current logged in user on-the-fly.
 
-   In other to achieve that goal, the module introduces concept of *effective*
+   In order to achieve this goal, the module introduces concept of *effective*
    and *real* user privileges known from Unix-like systems. The *effective*
-   user is stored in ``request.user`` object, while the *real* in
+   user is stored in ``request.user`` field, while the *real* in
    ``request.real_user``.
 
    On-the-fly means that current session variables are preserved while changing

rst/source/sections/misc.rst

@@ -10,6 +10,18 @@ Dynamic mixins
 .. autoclass:: oioioi.base.utils.ObjectWithMixins
    :members:
 
+Getting current time
+--------------------
+
+The main source of the current time in the request processing should be
+the ``request.timestamp`` variable. This variable contains the time when
+the request was initiated and, when used consistently, allows the admins
+to time travel.
+
+Usage of ``timezone.now()`` is highly discouraged.
+
+.. autoclass:: oioioi.base.middleware.TimestampingMiddleware
+
 Remembering the current contest
 -------------------------------
 
@@ -45,6 +57,8 @@ Conditions
 
 .. autofunction:: make_condition(condition_class=Condition)
 
+.. autofunction:: make_request_condition
+
 To assign a condition to a view use the ``enforce_condition`` decorator:
 
 .. autofunction:: enforce_condition
@@ -53,6 +67,16 @@ Additionally, the ``enforce_condition`` decorator adds a ``condition`` attribute
 to the view, which can be later used by
 :meth:`oioioi.base.menu.MenuRegistry.register_decorator`.
 
+Mixing it all together in a simple example::
+
+    @make_request_condition
+    def is_superuser(request):
+        return request.user.is_superuser
+
+    @enforce_condition(is_superuser & ~is_superuser)
+    def not_accessible_view(request):
+        pass
+
 Menu
 ----
 
@@ -65,13 +89,15 @@ Menu items are stored in registries like
 menu is to use the :meth:`~oioioi.base.menu.MenuRegistry.register_decorator`,
 for example::
 
+    from oioioi.base.permissions import not_anonymous
     from oioioi.base.menu import menu_registry
-    @menu_registry.register_decorator(_("Problems"),
+    @menu_registry.register_decorator(_("Example"),
             lambda request: reverse('example', kwargs={'contest_id':
-                request.contest.id},
+                request.contest.id}),
             order=100)
+    @enforce_condition(not_anonymous)
     def example_view(request, contest_id):
-        ...
+        pass
 
 The menu item will only be displayed when all the view's conditions are fulfilled.
 Therefore you should place all :func:`~oioioi.base.permissions.enforce_condition`