← Back to branch summary

~ubuntu-branches/debian/sid/python-django/sid

« back to all changes in this revision

Viewing changes to docs/topics/auth/customizing.txt

  • Committer: Package Import Robot
  • Author(s): Raphaël Hertzog
  • Date: 2014-09-17 14:15:11 UTC
  • mfrom: (1.3.17) (6.2.18 experimental)
  • Revision ID: package-import@ubuntu.com-20140917141511-icneokthe9ww5sk4
Tags: 1.7-2
* Release to unstable.
* Add a migrate-south sample script to help users apply their South
  migrations. Thanks to Brian May.

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/topics/auth/customizing.txt
275
275
            )
276
276
 
277
277
The only thing this does is create those extra permissions when you run
278
 
:djadmin:`manage.py syncdb <syncdb>`. Your code is in charge of checking the
 
278
:djadmin:`manage.py migrate <migrate>`. Your code is in charge of checking the
279
279
value of these permissions when a user is trying to access the functionality
280
280
provided by the application (viewing tasks, changing the status of tasks,
281
281
closing tasks.) Continuing the above example, the following checks if a user may
354
354
existing links to the default User model within your project's apps may justify
355
355
the extra database load.
356
356
 
357
 
.. _auth-profiles:
358
 
 
359
 
.. deprecated:: 1.5
360
 
    With the introduction of :ref:`custom User models <auth-custom-user>`,
361
 
    the use of :setting:`AUTH_PROFILE_MODULE` to define a single profile
362
 
    model is no longer supported. See the
363
 
    :doc:`Django 1.5 release notes</releases/1.5>` for more information.
364
 
 
365
 
Prior to 1.5, a single profile model could be specified site-wide with the
366
 
setting :setting:`AUTH_PROFILE_MODULE` with a string consisting of the
367
 
following items, separated by a dot:
368
 
 
369
 
1. The name of the application (case sensitive) in which the user
370
 
   profile model is defined (in other words, the
371
 
   name which was passed to :djadmin:`manage.py startapp <startapp>` to create
372
 
   the application).
373
 
 
374
 
2. The name of the model (not case sensitive) class.
375
 
 
376
 
For example, if the profile model was a class named ``UserProfile`` and was
377
 
defined inside an application named ``accounts``, the appropriate setting would
378
 
be::
379
 
 
380
 
    AUTH_PROFILE_MODULE = 'accounts.UserProfile'
381
 
 
382
 
When a user profile model has been defined and specified in this manner, each
383
 
:class:`~django.contrib.auth.models.User` object will have a method --
384
 
:class:`~django.contrib.auth.models.User.get_profile()` -- which returns the
385
 
instance of the user profile model associated with that
386
 
:class:`~django.contrib.auth.models.User`.
387
 
 
388
 
The method :class:`~django.contrib.auth.models.User.get_profile()`
389
 
does not create a profile if one does not exist.
390
 
 
391
357
.. _auth-custom-user:
392
358
 
393
359
Substituting a custom User model
394
360
================================
395
361
 
396
 
.. versionadded:: 1.5
397
 
 
398
362
Some kinds of projects may have authentication requirements for which Django's
399
363
built-in :class:`~django.contrib.auth.models.User` model is not always
400
364
appropriate. For instance, on some sites it makes more sense to use an email
414
378
   Changing :setting:`AUTH_USER_MODEL` has a big effect on your database
415
379
   structure. It changes the tables that are available, and it will affect the
416
380
   construction of foreign keys and many-to-many relationships. If you intend
417
 
   to set :setting:`AUTH_USER_MODEL`, you should set it before running
418
 
   ``manage.py syncdb`` for the first time.
419
 
 
420
 
   If you have an existing project and you want to migrate to using a custom
421
 
   User model, you may need to look into using a migration tool like South_
422
 
   to ease the transition.
423
 
 
424
 
.. _South: http://south.aeracode.org
 
381
   to set :setting:`AUTH_USER_MODEL`, you should set it before creating
 
382
   any migrations or running ``manage.py migrate`` for the first time.
 
383
 
 
384
   Changing this setting after you have tables created is not supported
 
385
   by :djadmin:`makemigrations` and will result in you having to manually
 
386
   fix your schema, port your data from the old user table, and possibly
 
387
   manually reapply some migrations.
 
388
 
 
389
.. warning::
 
390
 
 
391
   Due to limitations of Django's dynamic dependency feature for swappable
 
392
   models, you must ensure that the model referenced by :setting:`AUTH_USER_MODEL`
 
393
   is created in the first migration of its app (usually called ``0001_initial``);
 
394
   otherwise, you will have dependency issues.
 
395
 
 
396
   In addition, you may run into a CircularDependencyError when running your
 
397
   migrations as Django won't be able to automatically break the dependency
 
398
   loop due to the dynamic dependency. If you see this error, you should
 
399
   break the loop by moving the models depended on by your User model
 
400
   into a second migration (you can try making two normal models that
 
401
   have a ForeignKey to each other and seeing how ``makemigrations`` resolves that
 
402
   circular dependency if you want to see how it's usually done)
 
403
 
425
404
 
426
405
Referencing the User model
427
406
--------------------------
451
430
        class Article(models.Model):
452
431
            author = models.ForeignKey(settings.AUTH_USER_MODEL)
453
432
 
 
433
    .. versionadded:: 1.7
 
434
 
 
435
        When connecting to signals sent by the User model, you should specify the
 
436
        custom model using the :setting:`AUTH_USER_MODEL` setting. For example::
 
437
 
 
438
            from django.conf import settings
 
439
            from django.db.models.signals import post_save
 
440
 
 
441
            def post_save_receiver(signal, sender, instance, **kwargs):
 
442
                pass
 
443
 
 
444
            post_save.connect(post_save_receiver, sender=settings.AUTH_USER_MODEL)
 
445
 
 
446
    Generally speaking, you should reference the User model with the
 
447
    :setting:`AUTH_USER_MODEL` setting in code that is executed at import
 
448
    time. ``get_user_model()`` only works once Django has imported all models.
 
449
 
454
450
.. _specifying-custom-user-model:
455
451
 
456
452
Specifying a custom User model
627
623
        :meth:`~django.contrib.auth.models.AbstractBaseUser.set_unusable_password()` has
628
624
        been called for this user.
629
625
 
 
626
    .. method:: models.AbstractBaseUser.get_session_auth_hash()
 
627
 
 
628
        .. versionadded:: 1.7
 
629
 
 
630
        Returns an HMAC of the password field. Used for
 
631
        :ref:`session-invalidation-on-password-change`.
 
632
 
630
633
You should also define a custom manager for your ``User`` model. If your
631
634
``User`` model defines ``username``, ``email``, ``is_staff``, ``is_active``,
632
635
``is_superuser``, ``last_login``, and ``date_joined`` fields the same as
727
730
* :class:`~django.contrib.auth.forms.AuthenticationForm`
728
731
 
729
732
  Works with any subclass of :class:`~django.contrib.auth.models.AbstractBaseUser`,
730
 
  and will adapt to use the field defined in `USERNAME_FIELD`.
 
733
  and will adapt to use the field defined in ``USERNAME_FIELD``.
731
734
 
732
735
* :class:`~django.contrib.auth.forms.PasswordResetForm`
733
736
 
734
737
  Assumes that the user model has an integer primary key, has a field named
735
738
  ``email`` that can be used to identify the user, and a boolean field
736
 
  named `is_active` to prevent password resets for inactive users.
 
739
  named ``is_active`` to prevent password resets for inactive users.
737
740
 
738
741
* :class:`~django.contrib.auth.forms.SetPasswordForm`
739
742
 
915
918
 
916
919
    from django.contrib.auth.tests.utils import skipIfCustomUser
917
920
    from django.contrib.auth.tests.custom_user import CustomUser, ExtensionUser
918
 
    from django.test import TestCase
919
 
    from django.test.utils import override_settings
 
921
    from django.test import TestCase, override_settings
920
922
 
921
923
 
922
924
    class ApplicationTestCase(TestCase):
1014
1016
            # The user is identified by their email address
1015
1017
            return self.email
1016
1018
 
1017
 
        # On Python 3: def __str__(self):
1018
 
        def __unicode__(self):
 
1019
        def __str__(self):              # __unicode__ on Python 2
1019
1020
            return self.email
1020
1021
 
1021
1022
        def has_perm(self, perm, obj=None):