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

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

    >>> sorted(list(getAllRoles()))
    [(u'waeup.AccommodationOfficer', <waeup.sirp.hostels.permissions.AccommodationOfficer 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()))
    9

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


: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.AccommodationOfficer', u'waeup.Applicant',
     u'waeup.ApplicationsOfficer',
     u'waeup.PortalManager', u'waeup.PortalUser', 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
    []