What it does
------------

django-group-access restricts access to records based on group membership.
It does not manage finer grained permissions such as editing or deleting.
If a user has access to a record, they have all permissions as defined
by the django auth permissions.


Installation
------------

Add 'django_group_access' to your INSTALLED_APPS in settings.py


Integration and use
-------------------

Example: Installing to a single model and restricting access in a view

models.py

  from django.db import models
  from django_group_access import registration


  class MyModel(models.Model):
      name = models.CharField(max_length=24)

  registration.register(MyModel)

MyModel will gain access_groups which is a ManyToManyField containing
the groups that have access to each record.

MyModel will also gain 'owner' which is a ForeignKey to
django.contrib.auth.models.User and is used to determine ownership
of the record.


views.py

  def my_view(request):
      records = MyModel.objects.accessible_by_user(request.user)

All related fields and reverse relationships for model instances in
`records` will be filtered for the same user automatically.


Access to "parent" records can be determined by access the user has
to "child" records. In the following example, if you have access to a Room
you have access to the House it appears in.


  from django.db import models
  from django_group_access import registration


  class House(models.Model):
      address = models.CharField(max_length=128)


  class Room(models.Model):
      house = models.ForeignKey(House)
      name = models.CharField(max_length=32)


  registration.register(Room)
  registration.register(House, control_relation='room')

  houses = House.objects.accessible_by_user(user_object)


The group model used for access control is AccessGroup. This is
separate from the django auth Group for flexbility.


Sharing records
---------------

  obj = MyModel.objects.accessible_by_user(user_object)[0]
  group_i_want_to_share_with = AccessGroup.objects.get(name='Friends')
  obj.access_groups.add(group_i_want_to_share_with)

`obj` would then become visible to members of the 'Friends' AccessGroup.

For ease of sharing data between groups, AccessGroup has a property called
`auto_share_groups`. This is a list of AccessGroups that records owned
by the group will automatically be shared with.


Public record mode
------------------

If you want to have all data public by default, and use the access groups
to restrict access to individual records add the following to settings.py

    DGA_UNSHARED_RECORDS_ARE_PUBLIC = True


Automatically restricting based on logged in user
-------------------------------------------------

Add 'django_group_access.middleware.DjangoGroupAccessMiddleware' to the
MIDDLEWARE_CLASSES in settings.py. All access controlled models will be filtered
based on the currently logged in user, meaning you do not have to call
'accessible_by_user' in your code. Anonymous users will see no records.

The middleware must be come after the AuthenticationMiddleware in the list
of MIDDLEWARE_CLASSES.

Registering a model with 'auto_filter=False' will stop the automatic
filtering for that model, meaning you will have to do it manually using
'accessible_by_user' in your code.


Access to unrestricted records
------------------------------

Registering a model with the option 'unrestricted_manager="manager_name"' will
create a manager on that model with unrestricted access to all records, even if
you are using the automatic restriction based on the logged in user.

Example:

  registration.register(MyModel, unrestricted_manager='all_objects')
  all_records = MyModel.all_objects.all()
