Globally renamed 'assign' method/function to 'assign_perm'. Updated '…

….gitingore' to ignore WebDAV cache files.

.gitignore

@@ -18,3 +18,6 @@ dist
 example_project/media
 example_project/conf/*.py
 .idea/
+
+# WebDAV remote filesystem
+.DAV

README.rst

@@ -55,7 +55,7 @@ Lets start really quickly::
     >>> admins = Group.objects.create(name='admins')
     >>> jack.has_perm('change_group', admins)
     False
-    >>> UserObjectPermission.objects.assign('change_group', user=jack, obj=admins)
+    >>> UserObjectPermission.objects.assign_perm('change_group', user=jack, obj=admins)
     <UserObjectPermission: admins | jack | change_group>
     >>> jack.has_perm('change_group', admins)
     True

benchmarks/run_benchmarks.py

@@ -20,7 +20,7 @@
 
 os.environ["DJANGO_SETTINGS_MODULE"] = 'benchmarks.settings'
 from benchmarks import settings
-from guardian.shortcuts import assign
+from guardian.shortcuts import assign_perm
 
 settings.DJALOG_LEVEL = 40
 settings.INSTALLED_APPS = (
@@ -126,7 +126,7 @@ def grant_perms(self):
                 self.grant_perm(user, obj, self.perm)
 
     def grant_perm(self, user, obj, perm):
-        assign(perm, user, obj)
+        assign_perm(perm, user, obj)
 
     @Timed("Check permissions")
     def check_perms(self):

docs/userguide/assign.rst

@@ -60,7 +60,7 @@ Assign object permissions
 -------------------------
 
 We can assign permissions for any user/group and object pairs using same,
-convenient function: :func:`guardian.shortcuts.assign`.
+convenient function: :func:`guardian.shortcuts.assign_perm`.
 
 For user
 ~~~~~~~~
@@ -79,8 +79,8 @@ Well, not so fast Joe, let us create an object permission finally:
 
 .. code-block:: python
 
-    >>> from guardian.shortcuts import assign
-    >>> assign('view_task', joe, task)
+    >>> from guardian.shortcuts import assign_perm
+    >>> assign_perm('view_task', joe, task)
     >>> joe.has_perm('view_task', task)
     True
 
@@ -94,7 +94,7 @@ difference is we have to pass ``Group`` instance rather than ``User``.
 .. code-block:: python
 
     >>> group = Group.objects.create(name='employees')
-    >>> assign('change_task', group, task)
+    >>> assign_perm('change_task', group, task)
     >>> joe.has_perm('change_task', task)
     False
     >>> # Well, joe is not yet within an *employees* group

docs/userguide/check.rst

@@ -24,8 +24,8 @@ additional argument::
 
 Lets assign permission and check again::
 
-    >>> from guardian.shortcuts import assign
-    >>> assign('sites.change_site', joe, site)
+    >>> from guardian.shortcuts import assign_perm
+    >>> assign_perm('sites.change_site', joe, site)
     <UserObjectPermission: example.com | joe | change_site>
     >>> joe = User.objects.get(username='joe')
     >>> joe.has_perm('sites.change_site', site)
@@ -147,8 +147,8 @@ decorator::
     >>> edit_group(request, group_name='foobars')
     <django.http.HttpResponseForbidden object at 0x102b43e50>
     >>>
-    >>> from guardian.shortcuts import assign
-    >>> assign('auth.change_group', joe, foobars)
+    >>> from guardian.shortcuts import assign_perm
+    >>> assign_perm('auth.change_group', joe, foobars)
     <UserObjectPermission: foobars | joe | change_group>
     >>>
     >>> edit_group(request, group_name='foobars')

docs/userguide/performance.rst

@@ -42,10 +42,10 @@ In order to add a *change_project* permission for *joe* user we would use
 
 .. code-block:: python
 
-    >>> from guardian.shortcuts import assign
+    >>> from guardian.shortcuts import assign_perm
     >>> project = Project.objects.get(name='Foobar')
     >>> joe = User.objects.get(username='joe')
-    >>> assign('change_project', joe, project)
+    >>> assign_perm('change_project', joe, project)
 
 What it really does is: create an instance of :model:`UserObjectPermission`.
 Something similar to:

guardian/forms.py

@@ -3,7 +3,7 @@
 from django import forms
 from django.utils.translation import ugettext as _
 
-from guardian.shortcuts import assign
+from guardian.shortcuts import assign_perm
 from guardian.shortcuts import remove_perm
 from guardian.shortcuts import get_perms
 from guardian.shortcuts import get_perms_for_model
@@ -143,7 +143,7 @@ def save_obj_perms(self):
             remove_perm(perm, self.user, self.obj)
 
         for perm in perms:
-            assign(perm, self.user, self.obj)
+            assign_perm(perm, self.user, self.obj)
 
 
 class GroupObjectPermissionsForm(BaseObjectPermissionsForm):
@@ -190,5 +190,5 @@ def save_obj_perms(self):
             remove_perm(perm, self.group, self.obj)
 
         for perm in perms:
-            assign(perm, self.group, self.obj)
+            assign_perm(perm, self.group, self.obj)
 

guardian/managers.py

@@ -5,6 +5,7 @@
 
 from guardian.exceptions import ObjectNotPersisted
 from guardian.models import Permission
+import warnings
 
 # TODO: consolidate UserObjectPermissionManager and GroupObjectPermissionManager
 
@@ -20,7 +21,7 @@ def is_generic(self):
 
 class UserObjectPermissionManager(BaseObjectPermissionManager):
 
-    def assign(self, perm, user, obj):
+    def assign_perm(self, perm, user, obj):
         """
         Assigns permission with given ``perm`` for an instance ``obj`` and
         ``user``.
@@ -40,6 +41,11 @@ def assign(self, perm, user, obj):
         obj_perm, created = self.get_or_create(**kwargs)
         return obj_perm
 
+    def assign(self, perm, user, obj):
+        """ Depreciated function name left in for compatibility"""
+        warnings.warn("UserObjectPermissionManager method 'assign' is being renamed to 'assign_perm'. Update your code accordingly as old name will be depreciated in 1.0.5 version.", DeprecationWarning)
+        return self.assign_perm(perm, user, obj)
+
     def remove_perm(self, perm, user, obj):
         """
         Removes permission ``perm`` for an instance ``obj`` and given ``user``.
@@ -72,7 +78,7 @@ def get_for_object(self, user, obj):
 
 class GroupObjectPermissionManager(BaseObjectPermissionManager):
 
-    def assign(self, perm, group, obj):
+    def assign_perm(self, perm, group, obj):
         """
         Assigns permission with given ``perm`` for an instance ``obj`` and
         ``group``.
@@ -92,6 +98,11 @@ def assign(self, perm, group, obj):
         obj_perm, created = self.get_or_create(**kwargs)
         return obj_perm
 
+    def assign(self, perm, user, obj):
+        """ Depreciated function name left in for compatibility"""
+        warnings.warn("UserObjectPermissionManager method 'assign' is being renamed to 'assign_perm'. Update your code accordingly as old name will be depreciated in 1.0.5 version.", DeprecationWarning)
+        return self.assign_perm(perm, user, obj)
+
     def remove_perm(self, perm, group, obj):
         """
         Removes permission ``perm`` for an instance ``obj`` and given ``group``.

guardian/models.py

@@ -90,12 +90,12 @@ class Meta:
 # Prototype User and Group methods
 setattr(User, 'get_anonymous', staticmethod(lambda: get_anonymous_user()))
 setattr(User, 'add_obj_perm',
-    lambda self, perm, obj: UserObjectPermission.objects.assign(perm, self, obj))
+    lambda self, perm, obj: UserObjectPermission.objects.assign_perm(perm, self, obj))
 setattr(User, 'del_obj_perm',
     lambda self, perm, obj: UserObjectPermission.objects.remove_perm(perm, self, obj))
 
 setattr(Group, 'add_obj_perm',
-    lambda self, perm, obj: GroupObjectPermission.objects.assign(perm, self, obj))
+    lambda self, perm, obj: GroupObjectPermission.objects.assign_perm(perm, self, obj))
 setattr(Group, 'del_obj_perm',
     lambda self, perm, obj: GroupObjectPermission.objects.remove_perm(perm, self, obj))
 

guardian/shortcuts.py

@@ -19,9 +19,9 @@
 from guardian.utils import get_identity
 from guardian.utils import get_user_obj_perms_model
 from guardian.utils import get_group_obj_perms_model
+import warnings
 
-
-def assign(perm, user_or_group, obj=None):
+def assign_perm(perm, user_or_group, obj=None):
     """
     Assigns permission to user/group and object pair.
 
@@ -40,10 +40,10 @@ def assign(perm, user_or_group, obj=None):
 
     >>> from django.contrib.sites.models import Site
     >>> from guardian.models import User, Group
-    >>> from guardian.shortcuts import assign
+    >>> from guardian.shortcuts import assign_perm
     >>> site = Site.objects.get_current()
     >>> user = User.objects.create(username='joe')
-    >>> assign("change_site", user, site)
+    >>> assign_perm("change_site", user, site)
     <UserObjectPermission: example.com | joe | change_site>
     >>> user.has_perm("change_site", site)
     True
@@ -52,7 +52,7 @@ def assign(perm, user_or_group, obj=None):
 
     >>> group = Group.objects.create(name='joe-group')
     >>> user.groups.add(group)
-    >>> assign("delete_site", group, site)
+    >>> assign_perm("delete_site", group, site)
     <GroupObjectPermission: example.com | joe-group | delete_site>
     >>> user.has_perm("delete_site", site)
     True
@@ -63,7 +63,7 @@ def assign(perm, user_or_group, obj=None):
     ``obj`` parameter is omitted. Added Permission would be returned in that
     case:
 
-    >>> assign("sites.change_site", user)
+    >>> assign_perm("sites.change_site", user)
     <Permission: sites | site | Can change site>
 
     """
@@ -87,10 +87,15 @@ def assign(perm, user_or_group, obj=None):
     perm = perm.split('.')[-1]
     if user:
         model = get_user_obj_perms_model(obj)
-        return model.objects.assign(perm, user, obj)
+        return model.objects.assign_perm(perm, user, obj)
     if group:
         model = get_group_obj_perms_model(obj)
-        return model.objects.assign(perm, group, obj)
+        return model.objects.assign_perm(perm, group, obj)
+
+def assign(perm, user_or_group, obj=None):
+    """ Depreciated function name left in for compatibility"""
+    warnings.warn("Shortcut function 'assign' is being renamed to 'assign_perm'. Update your code accordingly as old name will be depreciated in 1.0.5 version.", DeprecationWarning)
+    return assign_perm(perm, user_or_group, obj)
 
 def remove_perm(perm, user_or_group=None, obj=None):
     """
@@ -175,11 +180,11 @@ def get_users_with_perms(obj, attach_perms=False, with_superusers=False,
 
         >>> from django.contrib.flatpages.models import FlatPage
         >>> from django.contrib.auth.models import User
-        >>> from guardian.shortcuts import assign, get_users_with_perms
+        >>> from guardian.shortcuts import assign_perm, get_users_with_perms
         >>>
         >>> page = FlatPage.objects.create(title='Some page', path='/some/page/')
         >>> joe = User.objects.create_user('joe', 'joe@example.com', 'joesecret')
-        >>> assign('change_flatpage', joe, page)
+        >>> assign_perm('change_flatpage', joe, page)
         >>>
         >>> get_users_with_perms(page)
         [<User: joe>]
@@ -240,12 +245,12 @@ def get_groups_with_perms(obj, attach_perms=False):
     Example::
 
         >>> from django.contrib.flatpages.models import FlatPage
-        >>> from guardian.shortcuts import assign, get_groups_with_perms
+        >>> from guardian.shortcuts import assign_perm, get_groups_with_perms
         >>> from guardian.models import Group
         >>>
         >>> page = FlatPage.objects.create(title='Some page', path='/some/page/')
         >>> admins = Group.objects.create(name='Admins')
-        >>> assign('change_flatpage', group, page)
+        >>> assign_perm('change_flatpage', group, page)
         >>>
         >>> get_groups_with_perms(page)
         [<Group: admins>]
@@ -306,9 +311,9 @@ def get_objects_for_user(user, perms, klass=None, use_groups=True, any_perm=Fals
         >>> joe = User.objects.get(username='joe')
         >>> get_objects_for_user(joe, 'auth.change_group')
         []
-        >>> from guardian.shortcuts import assign
+        >>> from guardian.shortcuts import assign_perm
         >>> group = Group.objects.create('some group')
-        >>> assign('auth.change_group', joe, group)
+        >>> assign_perm('auth.change_group', joe, group)
         >>> get_objects_for_user(joe, 'auth.change_group')
         [<Group some group>]
 
@@ -318,7 +323,7 @@ def get_objects_for_user(user, perms, klass=None, use_groups=True, any_perm=Fals
         []
         >>> get_objects_for_user(joe, ['auth.change_group', 'auth.delete_group'], any_perm=True)
         [<Group some group>]
-        >>> assign('auth.delete_group', joe, group)
+        >>> assign_perm('auth.delete_group', joe, group)
         >>> get_objects_for_user(joe, ['auth.change_group', 'auth.delete_group'])
         [<Group some group>]
 
@@ -442,15 +447,15 @@ def get_objects_for_group(group, perms, klass=None, any_perm=False):
         >>> task = Task.objects.create('some task')
         >>> get_objects_for_group(group, 'tasker.add_task')
         []
-        >>> from guardian.shortcuts import assign
-        >>> assign('tasker.add_task', group, task)
+        >>> from guardian.shortcuts import assign_perm
+        >>> assign_perm('tasker.add_task', group, task)
         >>> get_objects_for_group(group, 'tasker.add_task')
         [<Task some task>]
 
     The permission string can also be an iterable. Continuing with the previous example:
         >>> get_objects_for_group(group, ['tasker.add_task', 'tasker.delete_task'])
         []
-        >>> assign('tasker.delete_task', group, task)
+        >>> assign_perm('tasker.delete_task', group, task)
         >>> get_objects_for_group(group, ['tasker.add_task', 'tasker.delete_task'])
         [<Task some task>]
 

guardian/tests/core_test.py

@@ -12,7 +12,7 @@
 from guardian.compat import get_user_model
 from guardian.exceptions import NotUserNorGroup
 from guardian.models import UserObjectPermission, GroupObjectPermission
-from guardian.shortcuts import assign
+from guardian.shortcuts import assign_perm
 
 User = get_user_model()
 
@@ -115,7 +115,7 @@ def test_not_active_superuser(self):
 
     def test_not_active_user(self):
         user = User.objects.create(username='notactive')
-        assign("change_contenttype", user, self.ctype)
+        assign_perm("change_contenttype", user, self.ctype)
 
         # new ObjectPermissionChecker is created for each User.has_perm call
         self.assertTrue(user.has_perm("change_contenttype", self.ctype))
@@ -125,7 +125,7 @@ def test_not_active_user(self):
         # use on one checker only (as user's is_active attr should be checked
         # before try to use cache
         user = User.objects.create(username='notactive-cache')
-        assign("change_contenttype", user, self.ctype)
+        assign_perm("change_contenttype", user, self.ctype)
 
         check = ObjectPermissionChecker(user)
         self.assertTrue(check.has_perm("change_contenttype", self.ctype))
@@ -149,13 +149,13 @@ def test_get_perms(self):
 
         for obj, perms in assign_perms.items():
             for perm in perms:
-                UserObjectPermission.objects.assign(perm, self.user, obj)
+                UserObjectPermission.objects.assign_perm(perm, self.user, obj)
             self.assertEqual(sorted(perms), sorted(check.get_perms(obj)))
 
         check = ObjectPermissionChecker(self.group)
 
         for obj, perms in assign_perms.items():
             for perm in perms:
-                GroupObjectPermission.objects.assign(perm, self.group, obj)
+                GroupObjectPermission.objects.assign_perm(perm, self.group, obj)
             self.assertEqual(sorted(perms), sorted(check.get_perms(obj)))
 

guardian/tests/custompkmodel_test.py

@@ -3,7 +3,7 @@
 from django.test import TestCase
 
 from guardian.compat import get_user_model
-from guardian.shortcuts import assign, remove_perm
+from guardian.shortcuts import assign_perm, remove_perm
 
 
 class CustomPKModelTest(TestCase):
@@ -17,13 +17,13 @@ def setUp(self):
         self.ctype = ContentType.objects.create(name='foo', model='bar',
             app_label='fake-for-guardian-tests')
 
-    def test_assign(self):
-        assign('contenttypes.change_contenttype', self.user, self.ctype)
+    def test_assign_perm(self):
+        assign_perm('contenttypes.change_contenttype', self.user, self.ctype)
         self.assertTrue(self.user.has_perm('contenttypes.change_contenttype',
             self.ctype))
 
     def test_remove_perm(self):
-        assign('contenttypes.change_contenttype', self.user, self.ctype)
+        assign_perm('contenttypes.change_contenttype', self.user, self.ctype)
         self.assertTrue(self.user.has_perm('contenttypes.change_contenttype',
             self.ctype))
         remove_perm('contenttypes.change_contenttype', self.user, self.ctype)