Ikoba permissions and roles
**************************

Permissions and roles used in a Ikoba portal.

.. :doctest:
.. :layer: waeup.ikoba.testing.IkobaUnitTestLayer

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

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

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

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

    >>> sorted(list(get_all_roles()))
    [(u'waeup.Customer', <waeup.ikoba.customers.permissions.CustomerRole object at 0x...]

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

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

    >>> from waeup.ikoba.permissions import get_waeup_roles
    >>> len(list(get_waeup_roles()))
    15

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


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

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

    >>> from waeup.ikoba.permissions import get_waeup_role_names
    >>> list(get_waeup_role_names())
    [u'waeup.Customer',
    u'waeup.CustomerImpersonator',
    u'waeup.CustomersManager',
    u'waeup.CustomersOfficer',
    u'waeup.DataCenterManager',
    u'waeup.DocumentsManager',
    u'waeup.DocumentsOfficer',
    u'waeup.ExportManager',
    u'waeup.ImportManager',
    u'waeup.PortalManager',
    u'waeup.ProductsManager',
    u'waeup.ProductsOfficer',
    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.ikoba.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.ikoba.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
    []