document osusers code

gnuviechadmin/osusers/admin.py

@@ -1,3 +1,7 @@
+"""
+This module contains the Django admin classes of the :py:mod:`osusers` app.
+
+"""
 from django import forms
 from django.utils.translation import ugettext as _
 from django.contrib import admin
@@ -10,13 +14,24 @@ from .models import (
 )
 
 PASSWORD_MISMATCH_ERROR = _("Passwords don't match")
+"""
+Error message for non matching passwords.
+"""
 
 
 class AdditionalGroupInline(admin.TabularInline):
+    """
+    Inline for :py:class:`osusers.models.AdditionalGroup` instances.
+
+    """
     model = AdditionalGroup
 
 
 class ShadowInline(admin.TabularInline):
+    """
+    Inline for :py:class:`osusers.models.ShadowInline` instances.
+
+    """
     model = Shadow
     readonly_fields = ['passwd']
     can_delete = False
@@ -24,7 +39,8 @@ class ShadowInline(admin.TabularInline):
 
 class UserCreationForm(forms.ModelForm):
     """
-    A form for creating system users.
+    A form for creating :py:class:`operating system users
+    <osusers.models.User>`.
 
     """
     password1 = forms.CharField(
@@ -44,6 +60,9 @@ class UserCreationForm(forms.ModelForm):
         """
         Check that the two password entries match.
 
+        :return: the validated password
+        :rtype: str or None
+
         """
         password1 = self.cleaned_data.get('password1')
         password2 = self.cleaned_data.get('password2')
@@ -55,6 +74,10 @@ class UserCreationForm(forms.ModelForm):
         """
         Save the provided password in hashed format.
 
+        :param boolean commit: whether to save the created user
+        :return: user instance
+        :rtype: :py:class:`osusers.models.User`
+
         """
         user = User.objects.create_user(
             customer=self.cleaned_data['customer'],
@@ -65,10 +88,16 @@ class UserCreationForm(forms.ModelForm):
         """
         No additional groups are created when this form is saved, so this
         method just does nothing.
+
         """
 
 
 class UserAdmin(admin.ModelAdmin):
+    """
+    Admin class for working with :py:class:`operating system users
+    <osusers.models.User>`.
+
+    """
     actions = ['perform_delete_selected']
     add_form = UserCreationForm
     inlines = [AdditionalGroupInline, ShadowInline]
@@ -83,6 +112,13 @@ class UserAdmin(admin.ModelAdmin):
         """
         Use special form during user creation.
 
+        :param request: the current HTTP request
+        :param obj: either a :py:class:`User <osusers.models.User>` instance or
+            None for a new user
+        :param kwargs: keyword arguments to be passed to
+            :py:meth:`django.contrib.admin.ModelAdmin.get_form`
+        :return: form instance
+
         """
         defaults = {}
         if obj is None:
@@ -94,16 +130,47 @@ class UserAdmin(admin.ModelAdmin):
         return super(UserAdmin, self).get_form(request, obj, **defaults)
 
     def get_readonly_fields(self, request, obj=None):
+        """
+        Make sure that uid is not editable for existing users.
+
+        :param request: the current HTTP request
+        :param obj: either a :py:class:`User <osusers.models.User>` instance or
+            None for a new user
+        :return: a list of fields
+        :rtype: list
+
+        """
         if obj:
             return ['uid']
         return []
 
     def perform_delete_selected(self, request, queryset):
+        """
+        Action to delete a list of selected users.
+
+        This action calls the delete method of each selected user in contrast
+        to the default `delete_selected`.
+
+        :param request: the current HTTP request
+        :param queryset: Django ORM queryset representing the selected users
+
+        """
         for user in queryset.all():
             user.delete()
     perform_delete_selected.short_description = _('Delete selected users')
 
     def get_actions(self, request):
+        """
+        Get the available actions for users.
+
+        This overrides the default behavior to remove the default
+        `delete_selected` action.
+
+        :param request: the current HTTP request
+        :return: list of actions
+        :rtype: list
+
+        """
         actions = super(UserAdmin, self).get_actions(request)
         if 'delete_selected' in actions:
             del actions['delete_selected']
@@ -111,19 +178,40 @@ class UserAdmin(admin.ModelAdmin):
 
 
 class GroupAdmin(admin.ModelAdmin):
+    """
+    Admin class for workint with :py:class:`operating system groups
+    <osusers.models.Group>`.
+
+    """
     actions = ['perform_delete_selected']
 
-    def get_inline_instances(self, request, obj=None):
-        if obj is None:
-            return []
-        return super(GroupAdmin, self).get_inline_instances(request, obj)
-
     def perform_delete_selected(self, request, queryset):
+        """
+        Action to delete a list of selected groups.
+
+        This action calls the delete method of each selected group in contrast
+        to the default `delete_selected`.
+
+        :param request: the current HTTP request
+        :param queryset: Django ORM queryset representing the selected groups
+
+        """
         for group in queryset.all():
             group.delete()
     perform_delete_selected.short_description = _('Delete selected groups')
 
     def get_actions(self, request):
+        """
+        Get the available actions for groups.
+
+        This overrides the default behavior to remove the default
+        `delete_selected` action.
+
+        :param request: the current HTTP request
+        :return: list of actions
+        :rtype: list
+
+        """
         actions = super(GroupAdmin, self).get_actions(request)
         if 'delete_selected' in actions:
             del actions['delete_selected']