Browse files

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

…. Thanks


git-svn-id: bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
1 parent 7aec348 commit b2e5c4ef025326e88ae240f429adc58260b3a5bf @malcolmt malcolmt committed Jun 20, 2006
Showing with 35 additions and 3 deletions.
  1. +29 −3 django/contrib/auth/
  2. +6 −0 django/contrib/sessions/
@@ -10,6 +10,18 @@ class SiteProfileNotAvailable(Exception):
class Permission(models.Model):
+ """The permissions system provides a way to assign permissions to specific users and groups of users.
+ 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:
+ - The "add" permission limits the user's ability to view the "add" form and add an object.
+ - The "change" permission limits a user's ability to view the change list, view the "change" form and change an object.
+ - The "delete" permission limits the ability to delete an object.
+ 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."
+ Three basic permissions -- add, create and delete -- are automatically created for each Django model.
+ """
name = models.CharField(_('name'), maxlength=50)
content_type = models.ForeignKey(ContentType)
codename = models.CharField(_('codename'), maxlength=100)
@@ -23,6 +35,12 @@ def __str__(self):
return "%s | %s" % (self.content_type,
class Group(models.Model):
+ """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.
+ 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.
+ 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.
+ """
name = models.CharField(_('name'), maxlength=80, unique=True)
permissions = models.ManyToManyField(Permission, verbose_name=_('permissions'), blank=True, filter_interface=models.HORIZONTAL)
class Meta:
@@ -52,14 +70,18 @@ def make_random_password(self, length=10, allowed_chars='abcdefghjkmnpqrstuvwxyz
return ''.join([choice(allowed_chars) for i in range(length)])
class User(models.Model):
- username = models.CharField(_('username'), maxlength=30, unique=True, validator_list=[validators.isAlphaNumeric])
+ """Users within the Django authentication system are represented by this model.
+ Username and password are required, other fields are optional.
+ """
+ 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)."))
first_name = models.CharField(_('first name'), maxlength=30, blank=True)
last_name = models.CharField(_('last name'), maxlength=30, blank=True)
email = models.EmailField(_('e-mail address'), blank=True)
password = models.CharField(_('password'), maxlength=128, help_text=_("Use '[algo]$[salt]$[hexdigest]'"))
is_staff = models.BooleanField(_('staff status'), help_text=_("Designates whether the user can log into this admin site."))
- is_active = models.BooleanField(_('active'), default=True)
- is_superuser = models.BooleanField(_('superuser status'))
+ 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."))
+ is_superuser = models.BooleanField(_('superuser status'), help_text=_("Designates that this user has all permissions without explicitly assigning them."))
last_login = models.DateTimeField(_('last login'), default=models.LazyDate())
date_joined = models.DateTimeField(_('date joined'), default=models.LazyDate())
groups = models.ManyToManyField(Group, verbose_name=_('groups'), blank=True,
@@ -89,9 +111,11 @@ def get_absolute_url(self):
return "/users/%s/" % self.username
def is_anonymous(self):
+ "Always returns False. This is a way of comparing User objects to anonymous users."
return False
def get_full_name(self):
+ "Returns the first_name plus the last_name, with a space in between."
full_name = '%s %s' % (self.first_name, self.last_name)
return full_name.strip()
@@ -215,6 +239,8 @@ def get_profile(self):
return self._profile_cache
class Message(models.Model):
+ """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.
+ """
user = models.ForeignKey(User)
message = models.TextField(_('message'))
@@ -32,6 +32,12 @@ def save(self, session_key, session_dict, expire_date):
return s
class Session(models.Model):
+ """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.
+ 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.
+ For complete documentation on using Sessions in your code, consult the sessions documentation that is shipped with Django (also available on the Django website).
+ """
session_key = models.CharField(_('session key'), maxlength=40, primary_key=True)
session_data = models.TextField(_('session data'))
expire_date = models.DateTimeField(_('expire date'))

0 comments on commit b2e5c4e

Please sign in to comment.