########
User API
########

.. module:: roles

RoleType metaclass
------------------

.. autoclass:: RoleType
   :members: assign, revoke, played_by


Using roles in a context
------------------------

Roles are played in a context. The ``roles.context`` module provides a
means to access the context from within your roles. Use this to make your
role's code simpler and more readable.

.. module:: roles.context

.. autofunction:: context

.. autofunction:: in_context


Ways to assign roles
--------------------

There are basically 3 ways to assign a role to an instance. The first one is
to manipulate the instance's class (this is the default) and the second is
to proxy the object by referencing the same instance dict (Borg pattern). The this (last resort) is to create an adapter on top of the data instance.

.. autofunction:: instance

.. autofunction:: clone

.. autofunction:: adapter


Generic roles
-------------

As an (non-DCI) extension it is possible to create role implementations tailored
for specific classes.

Although this may clutter the clear and readable ways provided by DCI, for
specific tasks it may help. Use it wisely.

.. module:: roles.factory

.. autofunction:: assignto


.. vim:syntax=rst
