Auth docs refactor #603

Closed
wants to merge 58 commits into
from

Projects

None yet

4 participants

@timheap timheap commented on an outdated diff Dec 20, 2012
docs/topics/auth/default.txt
@@ -0,0 +1,1060 @@
+======================================
+Using the Django authentication system
+======================================
+
+.. currentmodule:: django.contrib.auth
+
+This document explains the usage of Django's authentication system in its
+default configuration. This configuration has evolved to serve the most common
+project needs, handling a reasonably wide range of tasks, and has a careful
+implementation of passwords and permissions. While this default configuration
+may handle the majority of cases as is. For projects where authentication needs
@timheap
timheap Dec 20, 2012

may handle the majority of cases as is, for projects where authentication needs

@pydanny pydanny commented on an outdated diff Dec 20, 2012
docs/topics/auth/customizing.txt
+
+One limitation of custom User models is that installing a custom User model
+will break any proxy model extending :class:`~django.contrib.auth.models.User`.
+Proxy models must be based on a concrete base class; by defining a custom User
+model, you remove the ability of Django to reliably identify the base class.
+
+If your project uses proxy models, you must either modify the proxy to extend
+the User model that is currently in use in your project, or merge your proxy's
+behavior into your User subclass.
+
+Custom users and signals
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Another limitation of custom User models is that you can't use
+:func:`django.contrib.auth.get_user_model()` as the sender or target of a signal
+handler. Instead, you must register the handler with the actual User model.
@pydanny
pydanny Dec 20, 2012

How do you register this handler? If you don't register it, what kind of impact could it have?

@timgraham timgraham commented on an outdated diff Dec 22, 2012
docs/topics/testing.txt
@@ -956,7 +956,7 @@ Use the ``django.test.client.Client`` class to make requests.
.. method:: Client.login(**credentials)
- If your site uses Django's :doc:`authentication system</topics/auth>`
@timgraham
timgraham Dec 22, 2012

need to rebase to pickup the testing factor

@timgraham timgraham commented on an outdated diff Dec 22, 2012
docs/topics/auth/customizing.txt
@@ -0,0 +1,1065 @@
+====================================
+Customising authentication in Django
@timgraham timgraham commented on an outdated diff Dec 22, 2012
docs/ref/middleware.txt
@@ -180,7 +180,7 @@ Authentication middleware
Adds the ``user`` attribute, representing the currently-logged-in user, to
every incoming ``HttpRequest`` object. See :doc:`Authentication in Web requests
@timgraham
timgraham Dec 22, 2012

link to topics/auth/default.html#authentication-in-web-requests?

@timgraham timgraham and 1 other commented on an outdated diff Dec 22, 2012
docs/ref/settings.txt
@@ -107,8 +107,8 @@ AUTHENTICATION_BACKENDS
Default: ``('django.contrib.auth.backends.ModelBackend',)``
A tuple of authentication backend classes (as strings) to use when attempting to
-authenticate a user. See the :doc:`authentication backends documentation
-</ref/authbackends>` for details.
+authenticate a user. See the `authentication backends documentation
+<authentication-backends>`_ for details.
@timgraham
timgraham Dec 22, 2012

should these links use the :ref:text <link> format, instead of trailing underscore?

@ptone
ptone Dec 23, 2012

Indeed perhaps - I'm still not super familiar with all the different link types in Django

@timgraham timgraham commented on an outdated diff Dec 22, 2012
docs/topics/auth/customizing.txt
+ add_fieldsets = (
+ (None, {
+ 'classes': ('wide',),
+ 'fields': ('email', 'date_of_birth', 'password1', 'password2')}
+ ),
+ )
+ search_fields = ('email',)
+ ordering = ('email',)
+ filter_horizontal = ()
+
+ # Now register the new UserAdmin...
+ admin.site.register(MyUser, MyUserAdmin)
+ # ... and, since we're not using Django's builtin permissions,
+ # unregister the Group model from admin.
+ admin.site.unregister(Group)
+
@timgraham
timgraham Dec 22, 2012

no trailing newlines

@timgraham timgraham commented on the diff Dec 24, 2012
docs/ref/contrib/auth.txt
@@ -1,4 +1,447 @@
``django.contrib.auth``
=======================
-See :doc:`/topics/auth`.
@timgraham
timgraham Dec 24, 2012

Add a brief summary like the other ref pages have and a link to the topic guide?

@timgraham timgraham commented on an outdated diff Dec 24, 2012
docs/ref/contrib/auth.txt
-See :doc:`/topics/auth`.
+.. currentmodule:: django.contrib.auth.models
+
+
+User
+====
+
+Fields
+------
+
+.. class:: User
+
+ :class:`~django.contrib.auth.models.User` objects have the following
+ fields:
+
+ .. attribute:: models.User.username
@timgraham
timgraham Dec 24, 2012

'models.User' prefix is unnecessary through the attributes and methods as this path is established by the currentmodule and class annotations

@timgraham timgraham commented on an outdated diff Dec 24, 2012
docs/ref/contrib/auth.txt
+ explicitly assigning them.
+
+ .. attribute:: models.User.last_login
+
+ A datetime of the user's last login. Is set to the current date/time by
+ default.
+
+ .. attribute:: models.User.date_joined
+
+ A datetime designating when the account was created. Is set to the
+ current date/time by default when the account is created.
+
+Methods
+-------
+
+.. class:: User
@timgraham
timgraham Dec 24, 2012

I think this class may be redundant since it's already defined above

@timgraham timgraham commented on an outdated diff Dec 24, 2012
docs/ref/contrib/auth.txt
+
+ Returns a site-specific profile for this user. Raises
+ :exc:`django.contrib.auth.models.SiteProfileNotAvailable` if the
+ current site doesn't allow profiles, or
+ :exc:`django.core.exceptions.ObjectDoesNotExist` if the user does not
+ have a profile.
+
+Manager functions
+-----------------
+
+.. class:: UserManager
+
+ The :class:`~django.contrib.auth.models.User` model has a custom manager
+ that has the following helper functions:
+
+ .. method:: models.UserManager.create_user(username, email=None, password=None)
@timgraham
timgraham Dec 24, 2012

same here, remove models.UserManager prefix

@timgraham timgraham commented on an outdated diff Dec 24, 2012
docs/ref/contrib/auth.txt
+In practice, you probably won't need to use
+:class:`~django.contrib.auth.models.AnonymousUser` objects on your own, but
+they're used by Web requests, as explained in the next section.
+
+Permission
+==========
+
+.. class:: Permission
+
+Fields
+------
+
+:class:`~django.contrib.auth.models.Permission` objects have the following
+fields:
+
+.. attribute:: Permission.name
@timgraham
timgraham Dec 24, 2012

remove Permission. prefix

@timgraham timgraham commented on an outdated diff Dec 24, 2012
docs/ref/contrib/auth.txt
+
+:class:`~django.contrib.auth.models.Permission` objects have the standard
+data-access methods like any other :doc:`Django model </ref/models/instances>`.
+
+
+Group
+=====
+
+.. class:: Group
+
+Fields
+------
+
+:class:`~django.contrib.auth.models.Group` objects have the following fields:
+
+.. attribute:: Group.name
@timgraham timgraham and 1 other commented on an outdated diff Dec 24, 2012
docs/topics/auth/customizing.txt
+ or any other unique attribute.
+
+2. Your model must provide a way to address the user in a "short" and
+ "long" form. The most common interpretation of this would be to use
+ the user's given name as the "short" identifier, and the user's full
+ name as the "long" identifier. However, there are no constraints on
+ what these two methods return - if you want, they can return exactly
+ the same value.
+
+The easiest way to construct a compliant custom User model is to inherit from
+:class:`~django.contrib.auth.models.AbstractBaseUser`.
+:class:`~django.contrib.auth.models.AbstractBaseUser` provides the core
+implementation of a `User` model, including hashed passwords and tokenized
+password resets. You must then provide some key implementation details:
+
+.. class:: models.CustomUser
@timgraham
timgraham Dec 24, 2012

think this file is current currentmodule annotation

@ptone
ptone Dec 27, 2012

Not sure what is best doc approach here - CusomUser is not an actual shipped model - but documenting a hypothetical example and/or the included test model

@timgraham
timgraham Dec 27, 2012

sorry, I meant "this file is 'missing' the currentmodule annotation."

I'd add this to the top of the file:

.. currentmodule:: django.contrib.auth (or include .models if you want to omit it throughout the rest of this doc)

Unless you decide on what to do, I think we can ignore the issue of CustomerUser not being an actual model for now. I'll be happy to clean that up as part of #19516

@timgraham timgraham commented on an outdated diff Dec 24, 2012
docs/topics/auth/customizing.txt
+2. Your model must provide a way to address the user in a "short" and
+ "long" form. The most common interpretation of this would be to use
+ the user's given name as the "short" identifier, and the user's full
+ name as the "long" identifier. However, there are no constraints on
+ what these two methods return - if you want, they can return exactly
+ the same value.
+
+The easiest way to construct a compliant custom User model is to inherit from
+:class:`~django.contrib.auth.models.AbstractBaseUser`.
+:class:`~django.contrib.auth.models.AbstractBaseUser` provides the core
+implementation of a `User` model, including hashed passwords and tokenized
+password resets. You must then provide some key implementation details:
+
+.. class:: models.CustomUser
+
+ .. attribute:: User.USERNAME_FIELD
@timgraham
timgraham Dec 24, 2012

not sure if User. prefix is correct. path would be django.contrib.auth.models.CustomUser.User.USERNAME_FIELD. should is just be CustomUser?

@timgraham timgraham commented on an outdated diff Dec 24, 2012
docs/topics/auth/customizing.txt
+ would be the full name name of the user, but it can be any string that
+ identifies the user.
+
+ .. method:: User.get_short_name():
+
+ A short, informal identifier for the user. A common interpretation
+ would be the first name of the user, but it can be any string that
+ identifies the user in an informal way. It may also return the same
+ value as :meth:`django.contrib.auth.User.get_full_name()`.
+
+The following methods are available on any subclass of
+:class:`~django.contrib.auth.models.AbstractBaseUser`:
+
+.. class:: models.AbstractBaseUser
+
+ .. method:: models.AbstractBaseUser.get_username()
@timgraham timgraham commented on the diff Dec 24, 2012
docs/topics/auth/customizing.txt
+
+ Returns ``False`` if
+ :meth:`~django.contrib.auth.models.AbstractBaseUser.set_unusable_password()` has
+ been called for this user.
+
+You should also define a custom manager for your User model. If your User
+model defines `username` and `email` fields the same as Django's default User,
+you can just install Django's
+:class:`~django.contrib.auth.models.UserManager`; however, if your User model
+defines different fields, you will need to define a custom manager that
+extends :class:`~django.contrib.auth.models.BaseUserManager` providing two
+additional methods:
+
+.. class:: models.CustomUserManager
+
+ .. method:: models.CustomUserManager.create_user(*username_field*, password=None, \**other_fields)
@timgraham timgraham commented on an outdated diff Dec 24, 2012
docs/topics/auth/default.txt
+
+...or display an error message::
+
+ from django.shortcuts import render
+
+ def my_view(request):
+ if not request.user.is_authenticated():
+ return render('myapp/login_error.html')
+ # ...
+
+.. currentmodule:: django.contrib.auth.decorators
+
+The login_required decorator
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. function:: decorators.login_required([redirect_field_name=REDIRECT_FIELD_NAME, login_url=None])
@timgraham
timgraham Dec 24, 2012

remove decorators. prefix

@timgraham timgraham commented on an outdated diff Dec 24, 2012
docs/topics/auth/default.txt
+Django provides no default template for the authentication views - however the
+template context is documented for each view below.
+
+.. versionadded:: 1.4
+
+The built-in views all return
+a :class:`~django.template.response.TemplateResponse` instance, which allows
+you to easily customize the response data before rendering. For more details,
+see the :doc:`TemplateResponse documentation </ref/template-response>`.
+
+Most built-in authentication views provide a URL name for easier reference. See
+:doc:`the URL documentation </topics/http/urls>` for details on using named URL
+patterns.
+
+
+.. function:: views.login(request, [template_name, redirect_field_name, authentication_form])
@timgraham
timgraham Dec 24, 2012

remove views. prefix

@timgraham timgraham commented on an outdated diff Dec 24, 2012
docs/topics/auth/customizing.txt
+ * ``o``, ``O``, and ``0`` (uppercase letter o, lowercase letter o,
+ and zero)
+
+Extending Django's default User
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you're entirely happy with Django's :class:`~django.contrib.auth.models.User`
+model and you just want to add some additional profile information, you can
+simply subclass :class:`~django.contrib.auth.models.AbstractUser` and add your
+custom profile fields.
+
+Custom users and the built-in auth forms
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+As you may expect, built-in Django's :ref:`forms <built-in-auth-forms>` and
+:ref:`views <other-built-in-views>` make certain assumptions about the user
@timgraham
timgraham Dec 24, 2012

'other-built-in-views' links to the original topics/auth.txt

@timgraham

I'd break into two sentences ". For more details...."

  • no comma before "or"
@timgraham

period at end of sentence

@timgraham

line wrap

@timgraham

does currentmodule provide any function here? my quasi-understanding of how things work is that a module directive right below it would override what comes before it.

there are some refs to check_password in releases/1.4.txt and corresponding alpha/beta notes if you' like to update them.

Django member

You're right - I was mucking around trying to get references to this module with :mod: working - and tried one, then the other, then did not remove one.

found the docs here:
http://sphinx-doc.org/markup/desc.html

A cleanup item is to ensure one and only one .. module:: exists for documented modules, and then use .. currentmodule:: everywhere else

@timgraham
Django member

I think this looks RFC besides my couple comments, great work!

@ptone
Django member

Merged in 11ded96

@ptone ptone closed this Dec 29, 2012
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment