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:`get_all_roles`
---------------------

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 get_all_roles
    >>> get_all_roles()
    <generator object...at 0x...>

    >>> sorted(list(get_all_roles()))
    [(u'waeup.ACManager', <waeup.sirp.permissions.ACManager object at 0x...]

:func:`get_waeup_roles`
-----------------------

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

    >>> from waeup.sirp.permissions import get_waeup_roles
    >>> len(list(get_waeup_roles()))
    10

    >>> len(list(get_waeup_roles(also_local=True)))
    16


:func:`get_waeup_role_names`
----------------------------

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 get_waeup_role_names
    >>> list(get_waeup_role_names())
    [u'waeup.ACManager', u'waeup.AcademicsOfficer',
     u'waeup.AccommodationOfficer', u'waeup.Applicant',
     u'waeup.ApplicationsOfficer',
     u'waeup.PortalManager', u'waeup.Student',
     u'waeup.StudentsClearanceOfficer', u'waeup.StudentsManager',
     u'waeup.StudentsOfficer']

:func:`get_users_with_local_roles`
----------------------------------

We can get all users and their roles for a certain context
object. This even works for objects that cannot have local roles as
they are not stored in the ZODB:

    >>> from waeup.sirp.permissions import get_users_with_local_roles
    >>> mycontext = object()
    >>> people_and_roles = get_users_with_local_roles(mycontext)
    >>> people_and_roles
    <generator object...at 0x...>

In this case, the result is empty:

    >>> people_and_roles = list(people_and_roles)
    >>> people_and_roles
    []