Changeset 5769

Show
Ignore:
Timestamp:
11/26/08 11:01:38 (1 month ago)
Author:
Gustavo
Message:

Tons of corrections in the auth-related docs.

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • docs/2.0/docs/main/Auth/Authorization.rst

    r5760 r5769  
    7878    from repoze.what.predicates import not_anonymous 
    7979     
    80     p = not_anonymous(msg='Please login to access this area') 
     80    p = not_anonymous(msg='Only logged in users can read this post') 
    8181 
    8282Or if you have a predicate which is "allow access to root or anyone with the 
    …… 
    8787     
    8888    p = Any(is_user('root'), has_permission('manage'), 
    89             msg='You must be root or have the "manage" permission') 
     89            msg='Only administrators can remove blog posts') 
    9090 
    9191As you may have noticed, predicates receive the ``msg`` keyword argument to 
    …… 
    9595messages translatable. 
    9696 
     97.. note:: 
     98 
     99    Good predicate messages don't explain `what` went wrong; instead, they  
     100    describe the predicate in the current context (regardless of whether 
     101    the condition is met or not!). This is because such messages may be used in  
     102    places other than in a user-visible message (e.g., in the log file). 
     103     
     104    * Really bad: "Please login to access this area". 
     105    * Bad: "You cannot delete an user account because you are not an  
     106      administrator". 
     107    * OK: "You have to be an administrator to delete user accounts". 
     108    * Perfect: "Only administrators can delete user accounts". 
     109 
    97110Below are described the convenient utilities TurboGears provides to deal with 
    98111predicates in your applications. 
    …… 
    114127        @expose('yourproject.templates.start_vacations') 
    115128        @require(Any(is_user('root'), has_permission('manage'), 
    116                      msg='You must be root or have the "manage" permission')) 
     129                     msg='Only administrators can remove blog posts')) 
    117130        def only_for_admins(): 
    118131            flash('Hello admin!') 
    …… 
    218231        granted to the user. 
    219232 
     233.. class:: Not(predicate) 
     234 
     235    Negate the specified predicate. 
     236     
     237    :param predicate: The predicate to be negated. 
     238 
    220239 
    221240Custom single predicate checkers 
    …… 
    233252     
    234253    class is_month(Predicate): 
    235         error_message = 'You cannot access this page this month' 
     254        message = 'The current month must be %(right_month)s' 
    236255         
    237         def __init__(self, month, **kwargs): 
    238             self.month = month 
     256        def __init__(self, right_month, **kwargs): 
     257            self.right_month = right_month 
    239258            self.today = date.today() 
    240259            super(is_month, self).__init__(**kwargs) 
    241260         
    242261        def _eval_with_environ(self, environ): 
    243             if today.month == self.month: 
    244                 return True 
    245             return False 
     262            return self.today.month == self.right_month 
     263 
     264.. warning:: 
     265 
     266    When you create a predicate, don't try to guess/assume the context in 
     267    which the predicate is evaluated when you write the predicate message 
     268    because such a predicate may be used in a different context. 
     269     
     270    * Bad: "The software can be released if it's %(right_month)s". 
     271    * Good: "The current month must be %(right_month)s". 
    246272 
    247273If you defined that class in, say, ``{yourproject}.lib.auth``, you may use it 

  • docs/2.0/docs/main/Auth/Customization.rst

    r5761 r5769  
    11Customizing authentication and authorization 
    22============================================ 
     3 
     4.. module:: repoze.what.plugins.quickstart 
     5    :synopsis: Configuring the repoze.what quickstart 
    36 
    47:Status: Official 

  • docs/2.0/docs/main/Auth/index.rst

    r5752 r5769  
    9696  <http://www.sqlalchemy.org/>`_-managed database. To implement it on an 
    9797  existing project, or customize the model structure assumed by it, you have to 
    98   read the documentation for :mod:`repoze.what.quickstart`. 
     98  read the documentation for :mod:`repoze.what.plugins.quickstart`. 
    9999 
    100100