Metadata-Version: 2.1
Name: django-cancan
Version: 0.3.1
Summary: Authorization library for Django
Home-page: https://github.com/pgorecki/django-cancan
Author: Przemysław Górecki
Author-email: przemyslaw.gorecki@gmail.com
License: UNKNOWN
Description: # django-cancan
        
        [![Build Status](https://travis-ci.com/pgorecki/django-cancan.svg?branch=master)](https://travis-ci.com/pgorecki/django-cancan)
        
        `django-cancan` is an authorization library for Django. It works on top of default Django permissions and allows to restrict the resources (models and objects) a given user can access.
        
        This library is inspired by [cancancan](https://github.com/CanCanCommunity/cancancan) for Ruby on Rails.
        
        ## Quick start
        
        1. Add `cancan` to your `INSTALLED_APPS` setting like this:
        
        ```python
        INSTALLED_APPS = [
            ...,
            'cancan',
        ]
        ```
        
        2. Create a function that define user abilites. For example, in `abilities.py`:
        
        ```python
        def declare_abilities(user, ability):
            if not user.is_authenticated:
                # Allow anonymous users to view published articles
                return ability.can('view', Article, published=True)
        
            if user.has_perm('article.view_own_article'):
                # Allow logged in user to change his articles
                return ability.can('change', Article, author=user)
        
            if user.is_superuser:
                # Allow superuser change all articles
                return ability.can('change', Article)
        ```
        
        3. Configure `cancan` by adding `CANCAN` section in `settings.py`:
        
        ```python
        CANCAN = {
            'ABILITIES': 'myapp.abilities.declare_abilities'
        }
        ```
        
        Next, add `cancan` middleware after `AuthenticationMiddleware`:
        
        ```python
        MIDDLEWARE = [
            ...
            'django.contrib.auth.middleware.AuthenticationMiddleware',
            'cancan.middleware.CanCanMiddleware',
            ...
        ]
        ```
        
        Adding the middleware adds `request.ability` instance which you can use
        to check for: model permissions, object permissions and model querysets.
        
        4. Check abilities in views:
        
        ```python
        
        class ArticleListView(ListView):
            model = Article
        
            def get_queryset():
                # this is how you can retrieve all objects a user can access
                qs = self.request.ability.queryset_for('view', Article)
                return qs
        
        
        class ArticleDetailView(PermissionRequiredMixin, DetailView):
            queryset = Article.objects.all()
        
            def has_permission(self):
                article = self.get_object()
                # this is how you can check if user can access an object
                return self.request.ability.can('view', article)
        ```
        
        ## Testing
        
        Run `./manage.py test` to run all test for the `testapp`
        
Platform: UNKNOWN
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Framework :: Django :: 2.2
Classifier: Framework :: Django :: 3.0
Classifier: Framework :: Django :: 3.1
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Internet :: WWW/HTTP
Requires-Python: >=3.6
Description-Content-Type: text/markdown
