On 04/25/2010 04:40 PM, Chris McDonough wrote:
> There's a relationship between the authentication policy and authorization
> policy (authorization depends on authentication) that makes writing a good
> docstring for this API a bit tortured. For example:
>       def set_security_policies(self, authentication, authorization=None):
>           """
>           Add a pair of *security policy* (authentication and
>           authorization policy) objects to the configuration.
>           ``authentication`` must be an instance of an
>           :term:`authentication policy`.  This argument is required.
>           If ``authorization`` is provided, it must be an instance of an
>           :term:`authorization policy`.  This argument is optional.  If
>           an ``authorization`` argument is not passed or it is ``None``,
>           an :class:`repoze.bfg.authorization.ACLAuthorizationPolicy`
>           will be used as the authorization policy.
>           .. warning:: This API is destructive, not additive. In
>              particular, it will always register a new authorization
>              policy (which will override any existing authorization
>              policy) even if the ``authorization`` argument is ``None``.
>           Calling
>           :meth:`repoze.bfg.configuration.Configurator.set_security_policies`
>           will override both the ``authentication_policy`` and
>           ``authorization_policy`` previously passed as constructor
>           arguments.  It will also override any authentication and
>           authorization policies picked up via
>           :meth:`repoze.bfg.configuration.Configurator.load_zcml`.
>           """
>           if authorization is None:
>               authorization = ACLAuthorizationPolicy() # default
>           if authorization and not authentication:
>               raise ConfigurationError(
>                   'If "authorization" is passed a value, '
>                   'the "authentication" argument must also be '
>                   'passed a value; authorization requires authentication.')
>           self._set_authentication_policy(authentication)
>           self._set_authorization_policy(authorization)
> Anybody have a better idea?

FWIW, I would make both parameters mandatory, then suggest in the 
docstring that ACLAuthorizationPolicy() is a likely choice for the 
authorization parameter.  That way the documentation is easy and you can 
choose at a later time to create a default.

Repoze-dev mailing list

Reply via email to