Ticket #1422: auth-doc.diff

File auth-doc.diff, 6.3 KB (added by Antti Kaihola, 19 years ago)

Added docstrings. They intentionally start straight after quotes to avoid gap in admin documentation screens. Also added a couple of field help_texts and method docstrings.

  • magic-removal/django/contrib/auth/models.py

     
    1010    pass
    1111
    1212class Permission(models.Model):
     13    """Django comes with a user authentication system. It handles user accounts, groups, permissions and cookie-based user sessions. Permissions are represented by this model. 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 you're welcome to use it in your own code. The Django admin site uses permissions as follows:
     16
     17        * Access to view the "add" form and add an object is limited to users with the "add" permission for that type of object.
     18        * Access to view the change list, view the "change" form and change an object is limited to users with the "change" permission for that type of object.
     19        * Access to delete an object is limited to users with the "delete" permission for that type of object.
     20       
     21    Permissions are set globally per type of object, not per specific object instance. For example, it's 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." The latter functionality is something Django developers are currently discussing.
     22
     23    Three basic permissions -- add, create and delete -- are automatically created for each Django model that has admin set.
     24    """
    1325    name = models.CharField(_('name'), maxlength=50)
    1426    content_type = models.ForeignKey(ContentType)
    1527    codename = models.CharField(_('codename'), maxlength=100)
     
    2335        return "%r | %s" % (self.content_type, self.name)
    2436
    2537class Group(models.Model):
    26     name = models.CharField(_('name'), maxlength=80, unique=True)
     38    """Django comes with a user authentication system. It handles user accounts, groups, permissions and cookie-based user sessions. Groups are represented by this model.
     39
     40    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.
     41
     42    A user in a group automatically has 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.
     43
     44    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.
     45    """
     46    name = models.CharField(_('name'), maxlength=80, unique=True, help_text=_("Required. 80 characters or fewer."))
    2747    permissions = models.ManyToManyField(Permission, blank=True, filter_interface=models.HORIZONTAL)
    2848    class Meta:
    2949        verbose_name = _('Group')
     
    5272        return ''.join([choice(allowed_chars) for i in range(length)])
    5373
    5474class User(models.Model):
    55     username = models.CharField(_('username'), maxlength=30, unique=True, validator_list=[validators.isAlphaNumeric])
     75    """Django comes with a user authentication system. It handles user accounts, groups, permissions and cookie-based user sessions. Users are represented by this model.
     76
     77    Username and password are required, other fields are optional.
     78    """
     79    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)."))
    5680    first_name = models.CharField(_('first name'), maxlength=30, blank=True)
    5781    last_name = models.CharField(_('last name'), maxlength=30, blank=True)
    5882    email = models.EmailField(_('e-mail address'), blank=True)
    5983    password = models.CharField(_('password'), maxlength=128, help_text=_("Use '[algo]$[salt]$[hexdigest]'"))
    6084    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'))
     85    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."))
     86    is_superuser = models.BooleanField(_('superuser status'), help_text=_("Designates that this user has all permissions without explicitly assigning them."))
    6387    last_login = models.DateTimeField(_('last login'), default=models.LazyDate())
    6488    date_joined = models.DateTimeField(_('date joined'), default=models.LazyDate())
    6589    groups = models.ManyToManyField(Group, blank=True,
     
    89113        return "/users/%s/" % self.username
    90114
    91115    def is_anonymous(self):
     116        "Always returns False. This is a way of comparing User objects to anonymous users."
    92117        return False
    93118
    94119    def get_full_name(self):
     120        "Returns the first_name plus the last_name, with a space in between."
    95121        full_name = '%s %s' % (self.first_name, self.last_name)
    96122        return full_name.strip()
    97123
     
    215241        return self._profile_cache
    216242
    217243class Message(models.Model):
     244    """The message system is a lightweight way to queue messages for given users. A message is associated with a User. There's no concept of expiration or timestamps. Messages are used by the Django admin after successful actions. For example, "The poll Foo was created successfully." is a message.
     245
     246    When you use DjangoContext, the currently logged-in user and his/her messages are made available in the template context as the template variable {{ messages }}. Note that DjangoContext calls get_and_delete_messages behind the scenes, so any messages will be deleted even if you don't display them. Finally, note that this messages framework only works with users in the user database. To send messages to anonymous users, use the session framework.
     247    """
    218248    user = models.ForeignKey(User)
    219249    message = models.TextField(_('Message'))
    220250
Back to Top