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. Shane _______________________________________________ Repoze-dev mailing list Repoze-dev@lists.repoze.org http://lists.repoze.org/listinfo/repoze-dev
