Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Fixed #1422 -- Docstring improvements for the models in the admin app…

…. Thanks

akaihola.


git-svn-id: http://code.djangoproject.com/svn/django/trunk@3167 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit b2e5c4ef025326e88ae240f429adc58260b3a5bf 1 parent 7aec348
Malcolm Tredinnick authored
32  django/contrib/auth/models.py
@@ -10,6 +10,18 @@ class SiteProfileNotAvailable(Exception):
10 10
     pass
11 11
 
12 12
 class Permission(models.Model):
  13
+    """The permissions system provides a way to assign permissions to specific users and groups of users.
  14
+
  15
+    The permission system is used by the Django admin site, but may also be useful in your own code. The Django admin site uses permissions as follows:
  16
+
  17
+        - The "add" permission limits the user's ability to view the "add" form and add an object.
  18
+        - The "change" permission limits a user's ability to view the change list, view the "change" form and change an object.
  19
+        - The "delete" permission limits the ability to delete an object.
  20
+        
  21
+    Permissions are set globally per type of object, not per specific object instance. It is possible to say "Mary may change news stories," but it's not currently possible to say "Mary may change news stories, but only the ones she created herself" or "Mary may only change news stories that have a certain status or publication date."
  22
+
  23
+    Three basic permissions -- add, create and delete -- are automatically created for each Django model.
  24
+    """
13 25
     name = models.CharField(_('name'), maxlength=50)
14 26
     content_type = models.ForeignKey(ContentType)
15 27
     codename = models.CharField(_('codename'), maxlength=100)
@@ -23,6 +35,12 @@ def __str__(self):
23 35
         return "%s | %s" % (self.content_type, self.name)
24 36
 
25 37
 class Group(models.Model):
  38
+    """Groups are a generic way of categorizing users to apply permissions, or some other label, to those users. A user can belong to any number of groups.
  39
+
  40
+    A user in a group automatically has all the permissions granted to that group. For example, if the group Site editors has the permission can_edit_home_page, any user in that group will have that permission.
  41
+
  42
+    Beyond permissions, groups are a convenient way to categorize users to apply some label, or extended functionality, to them. For example, you could create a group 'Special users', and you could write code that would do special things to those users -- such as giving them access to a members-only portion of your site, or sending them members-only e-mail messages.
  43
+    """
26 44
     name = models.CharField(_('name'), maxlength=80, unique=True)
27 45
     permissions = models.ManyToManyField(Permission, verbose_name=_('permissions'), blank=True, filter_interface=models.HORIZONTAL)
28 46
     class Meta:
@@ -52,14 +70,18 @@ def make_random_password(self, length=10, allowed_chars='abcdefghjkmnpqrstuvwxyz
52 70
         return ''.join([choice(allowed_chars) for i in range(length)])
53 71
 
54 72
 class User(models.Model):
55  
-    username = models.CharField(_('username'), maxlength=30, unique=True, validator_list=[validators.isAlphaNumeric])
  73
+    """Users within the Django authentication system are represented by this model.
  74
+
  75
+    Username and password are required, other fields are optional.
  76
+    """
  77
+    username = models.CharField(_('username'), maxlength=30, unique=True, validator_list=[validators.isAlphaNumeric], help_text=_("Required. 30 characters or fewer. Alphanumeric characters only (letters, digits and underscores)."))
56 78
     first_name = models.CharField(_('first name'), maxlength=30, blank=True)
57 79
     last_name = models.CharField(_('last name'), maxlength=30, blank=True)
58 80
     email = models.EmailField(_('e-mail address'), blank=True)
59 81
     password = models.CharField(_('password'), maxlength=128, help_text=_("Use '[algo]$[salt]$[hexdigest]'"))
60 82
     is_staff = models.BooleanField(_('staff status'), help_text=_("Designates whether the user can log into this admin site."))
61  
-    is_active = models.BooleanField(_('active'), default=True)
62  
-    is_superuser = models.BooleanField(_('superuser status'))
  83
+    is_active = models.BooleanField(_('active'), default=True, help_text=_("Designates whether this user can log into the Django admin. Unselect this instead of deleting accounts."))
  84
+    is_superuser = models.BooleanField(_('superuser status'), help_text=_("Designates that this user has all permissions without explicitly assigning them."))
63 85
     last_login = models.DateTimeField(_('last login'), default=models.LazyDate())
64 86
     date_joined = models.DateTimeField(_('date joined'), default=models.LazyDate())
65 87
     groups = models.ManyToManyField(Group, verbose_name=_('groups'), blank=True,
@@ -89,9 +111,11 @@ def get_absolute_url(self):
89 111
         return "/users/%s/" % self.username
90 112
 
91 113
     def is_anonymous(self):
  114
+        "Always returns False. This is a way of comparing User objects to anonymous users."
92 115
         return False
93 116
 
94 117
     def get_full_name(self):
  118
+        "Returns the first_name plus the last_name, with a space in between."
95 119
         full_name = '%s %s' % (self.first_name, self.last_name)
96 120
         return full_name.strip()
97 121
 
@@ -215,6 +239,8 @@ def get_profile(self):
215 239
         return self._profile_cache
216 240
 
217 241
 class Message(models.Model):
  242
+    """The message system is a lightweight way to queue messages for given users. A message is associated with a User instance (so it is only applicable for registered users). There's no concept of expiration or timestamps. Messages are created by the Django admin after successful actions. For example, "The poll Foo was created successfully." is a message.
  243
+    """
218 244
     user = models.ForeignKey(User)
219 245
     message = models.TextField(_('message'))
220 246
 
6  django/contrib/sessions/models.py
@@ -32,6 +32,12 @@ def save(self, session_key, session_dict, expire_date):
32 32
         return s
33 33
 
34 34
 class Session(models.Model):
  35
+    """Django provides full support for anonymous sessions. The session framework lets you store and retrieve arbitrary data on a per-site-visitor basis. It stores data on the server side and abstracts the sending and receiving of cookies. Cookies contain a session ID -- not the data itself.
  36
+
  37
+    The Django sessions framework is entirely cookie-based. It does not fall back to putting session IDs in URLs. This is an intentional design decision. Not only does that behavior make URLs ugly, it makes your site vulnerable to session-ID theft via the "Referer" header.
  38
+
  39
+    For complete documentation on using Sessions in your code, consult the sessions documentation that is shipped with Django (also available on the Django website).
  40
+    """
35 41
     session_key = models.CharField(_('session key'), maxlength=40, primary_key=True)
36 42
     session_data = models.TextField(_('session data'))
37 43
     expire_date = models.DateTimeField(_('expire date'))

0 notes on commit b2e5c4e

Please sign in to comment.
Something went wrong with that request. Please try again.