==============
Access control
==============
 
The purpose of the :mod:`access_control` component is to selectively control
which users have access to which items in the database.

This component depends on :mod:`helmholtz.core`.
 
Setting permissions
===================

Suppose we have a file, which Alice is allowed to download but Bob is not.

    >>> from helmholtz.storage.models import File
    >>> from django.contrib.auth.models import User
    >>> alices_data = File(name="my_data.dat")
    >>> alices_data.save()
    >>> alice = User.objects.get(first_name="Alice")
    >>> bob = User.objects.get(first_name="Robert")

The easiest way to set access permissions for the file is to use the helper functions
in :mod:`helmholtz.access_control.lifecycle`::

    >>> from helmholtz.access_control.lifecycle import put_class_under_access_control, create_user_permission
    >>> put_class_under_access_control(File)
    >>> create_user_permission(alices_data, alice, can_download=True)
    >>> create_user_permission(alices_data, bob)
    
Here we give Bob the default permissions, which allow viewing but no other access.

Testing permissions
===================

Helper functions that allow testing whether a given user has a certain access to
a given object are available in the :mod:`helmholtz.access_control.conditions`
module::

    >>> from helmholtz.access_control.conditions import is_accessible_by, is_downloadable_by
    >>> is_accessible_by(alices_data, alice)
    True
    >>> is_accessible_by(alices_data, bob)
    True
    >>> is_downloadable_by(alices_data, alice)
    True
    >>> is_downloadable_by(alices_data, bob)
    False

User and group-level permissions
================================

As well as user-level permissions, group-level permissions can be set, based on
the :class:`Group` class from the :mod:`django.contrib.auth` component.

 
Reference
=========

Models
------

.. automodule:: helmholtz.access_control.models

.. autoclass:: UnderAccessControlEntity
    :members:

.. autoclass:: Permission
    :members:
    
.. autoclass:: IntegerPermission
    :members:
    
.. autoclass:: CharPermission
    :members:

.. autoclass:: IntegerUserPermission
    :members:
    
.. autoclass:: CharUserPermission
    :members:
    
.. autoclass:: IntegerGroupPermission
    :members:
    
.. autoclass:: CharGroupPermission
    :members:

Views
-----

.. automodule:: helmholtz.access_control.views
   :members:

Conditions module
-----------------

.. automodule:: helmholtz.access_control.conditions
   :members:

Decorators module
-----------------

.. automodule:: helmholtz.access_control.decorators
   :members:

Filters module
--------------

.. automodule:: helmholtz.access_control.filters
   :members:

Lifecycle module
----------------

.. automodule:: helmholtz.access_control.lifecycle
   :members:

Overload module
---------------

.. automodule:: helmholtz.access_control.overload
   :members:
   
Proxies module
--------------
   
.. automodule:: helmholtz.access_control.proxies
   :members:


