Kofa permissions and roles
**************************

Permissions and roles used in a Kofa portal.

.. :doctest:
.. :layer: waeup.kofa.testing.KofaUnitTestLayer

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

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

:func:`get_all_roles`
---------------------

Gives us all roles defined in Kofa. 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.kofa.permissions import get_all_roles
    >>> get_all_roles()
    <generator object...at 0x...>

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

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

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

    >>> from waeup.kofa.permissions import get_waeup_roles
    >>> len(list(get_waeup_roles()))
    25

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


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

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

    >>> from waeup.kofa.permissions import get_waeup_role_names
    >>> list(get_waeup_role_names())
    [u'waeup.ACManager',
     u'waeup.AcademicsManager',
     u'waeup.AcademicsOfficer',
     u'waeup.AccommodationOfficer',
     u'waeup.Applicant',
     u'waeup.ApplicationsManager',
     u'waeup.ApplicationsOfficer',
     u'waeup.BursaryOfficer',
     u'waeup.DataCenterManager',
     u'waeup.DocumentsManager',
     u'waeup.DocumentsOfficer',
     u'waeup.ExportManager',
     u'waeup.ImportManager',
     u'waeup.PortalManager',
     u'waeup.ReportsManager',
     u'waeup.Student',
     u'waeup.StudentImpersonator',
     u'waeup.StudentsClearanceOfficer',
     u'waeup.StudentsCourseAdviser',
     u'waeup.StudentsManager',
     u'waeup.StudentsOfficer',
     u'waeup.TranscriptOfficer',
     u'waeup.UsersManager',
     u'waeup.WorkflowManager',
     u'waeup.xmlrpcusers1']

: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.kofa.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
    []

:func:`get_users_with_role`
---------------------------

We can get all users with a specific role for a certain context
object:

    >>> from waeup.kofa.permissions import get_users_with_role
    >>> mycontext = object()
    >>> people = get_users_with_role('waeup.portalManager', mycontext)
    >>> people
    <generator object...at 0x...>

In this case, the result is empty:

    >>> people = list(people)
    >>> people
    []