WAeUP permissions and roles
***************************

Permissions and roles used in a WAeUP portal.

.. :doctest:
.. :layer: waeup.sirp.testing.WAeUPSIRPUnitTestLayer

Convenience functions
=====================

:mod:`waeup.sirp` offers some convenience functions to handle security
roles.

:func:`getRoles`
----------------

Gives us all roles defined in a WAeUP SIRP portal. We get tuples of
kind

  ``(<ROLE-NAME>, <ROLE>)``

where ``<ROLE-NAME>`` is the name under which a role was registered
with the ZCA (a string) and ``<ROLE>`` is the real role object.

    >>> from waeup.sirp.permissions import getRoles
    >>> getRoles()
    <generator object at 0x...>

    >>> sorted(list(getRoles()))
    [(u'waeup.PortalManager', <waeup...PortalManager object at 0x...>), ...]

:func:`getWAeUPRoles`
---------------------

Gives us all roles, except the WAeUP specific roles. We can get a list
with or without local roles:

    >>> from waeup.sirp.permissions import getWAeUPRoles
    >>> len(list(getWAeUPRoles()))
    2

    >>> len(list(getWAeUPRoles(also_local=True)))
    5


:func:`getRoleNames`
--------------------

We can get all role names defined in a WAeUP portal (except 'local'
roles that are meant not to be assigned globally):

    >>> from waeup.sirp.permissions import getWAeUPRoleNames
    >>> list(getWAeUPRoleNames())
    [u'waeup.PortalManager', u'waeup.PortalUser']