CUser, make email the USERNAME\_FIELD
=====================================
CUser makes it easy to use email address as your identification token
instead of a username.
CUser is a custom Django user model (extends ``AbstractBaseUser``) so it
takes a tiny amount of effort to use.
The only difference between CUser and the vanilla Django ``User`` is email
address is the ``USERNAME_FIELD`` (and username does not exist).
CUser supports Django 3.2 - 5.1. If you need to use CUser with
Django 1.8 - 3.1, you must install an older, unmaintained version of
CUser, as noted in the "Install & Set up" section.
Why use CUser?
--------------
Because you want everything in ``django.contrib.auth`` except for the
``username`` field and you also want users to **log in with email addresses**.
And you don't want to create your own custom user model or authentication
backend.
Install & Set up
----------------
**Important:** To keep things simple, the steps below will guide you through
the process of using CUser's ``CUser`` model for your Django project's user
model. However, it is strongly recommended that you set up a custom user model
that extends CUser's ``AbstractCUser`` class, even if CUser's ``CUser`` model
is sufficient for you (this way, you can customize the user model if the need
arises). If you would *not* like to follow this recommendation and just want to
use CUser's ``CUser`` model, simply follow the steps below (you can skip the
rest of this paragraph). If you *would* like to follow this recommendation, you
should still follow the steps below, but with the following adjustments: After
step 3, follow
`these instructions <https://docs.djangoproject.com/en/3.2/topics/auth/customizing/#using-a-custom-user-model-when-starting-a-project>`_,
but instead of using ``from django.contrib.auth.models import AbstractUser``
use ``from cuser.models import AbstractCUser`` and instead of using
``from django.contrib.auth.admin import UserAdmin`` use
``from cuser.admin import UserAdmin``. Then for step 4 of the steps below, you
should set ``AUTH_USER_MODEL`` to your custom user model instead of CUser's
``CUser`` model. You should then run ``python manage.py makemigrations``. After
that, you may follow the remaining steps below just the way they are.
1. If your Django project previously used Django's default user model,
``django.contrib.auth.models.User``, or if you are unfamiliar with using
custom user models, jump to **Notes** first (then come
back). Otherwise, continue onward!
2. Install with ``pip``:
.. code-block:: shell
# Django 3.2 - 5.1
pip install django-username-email
# Django 3.1 (unmaintained)
pip install django-username-email==2.4.2
# Django 2.2 or 3.0 (unmaintained)
pip install django-username-email==2.3.1
# Django 2.0 or 2.1 (unmaintained)
pip install django-username-email==2.2.4
# Django 1.11 (unmaintained)
pip install django-username-email==2.1.6
# Django 1.8 - 1.10 (unmaintained)
pip install django-username-email==2.1.2
3. Add ``cuser`` to your ``INSTALLED_APPS`` setting:
.. code-block:: python
INSTALLED_APPS = [
...
'cuser',
]
4. Specify the custom model as the default user model for your project
using the ``AUTH_USER_MODEL`` setting in your settings.py:
.. code-block:: python
AUTH_USER_MODEL = 'cuser.CUser'
5. If you use Django's default ``AuthenticationForm`` class, it is
strongly recommended that you replace it with the one included with
CUser. This will make the ``<input>`` have its ``type`` attribute set
to ``email`` and browsers' autocomplete feature will suggest email
addresses instead of usernames. For example, if your project is using
Django's default ``LoginView`` view (or ``login`` view in Django < 1.11), this is
what you would put in your urls.py in order to make use of CUser's
``AuthenticationForm`` class:
.. code-block:: python
from cuser.forms import AuthenticationForm
from django.conf.urls import include, url
from django.contrib.auth.views import LoginView
urlpatterns = [
url(r'^accounts/login/$', LoginView.as_view(authentication_form=AuthenticationForm), name='login'),
url(r'^accounts/', include('django.contrib.auth.urls')),
...
]
Or if you're using Django < 1.11:
.. code-block:: python
from cuser.forms import AuthenticationForm
from django.conf.urls import include, url
from django.contrib.auth.views import login
urlpatterns = [
url(r'^accounts/login/$', login, {'authentication_form': AuthenticationForm}, name='login'),
url(r'^accounts/', include('django.contrib.auth.urls')),
...
]
6. Run migrations.
.. code-block:: shell
python manage.py migrate
7. There is a good chance that you want foo@example.com and FOO@example.com to
be treated as the same email address. There is a variety of ways to go about
doing this. How you handle it will depend on the needs of your project and
personal preference, so CUser does not provide a solution for this out of
the box. You will need to address this yourself if this applies to you. If
you're using CUser's ``AuthenticationForm`` class (see step 5), you may want
to subclass it and override ``error_messages['invalid_login']``.
Configuration
-------------
To override any of the default settings, create a dictionary named ``CUSER`` in
your settings.py with each setting you want to override. For example:
.. code-block:: python
CUSER = {
'app_verbose_name': 'Authentication and Authorization',
'register_proxy_auth_group_model': True,
}
These are the settings:
``app_verbose_name`` (default: ``_("Custom User")``)
****************************************************
This controls the value that CUser will use for its ``AppConfig`` class'
``verbose_name``.
``register_proxy_auth_group_model`` (default: ``False``)
********************************************************
When set to ``True``, CUser's admin.py will unregister Django's default
``Group`` model and register its own proxy model of Django's default ``Group``
model (also named ``Group``). This is useful if you want Django's default
``Group`` model to appear in the same part of the admin as CUser's ``CUser``
model.
Notes
-----
If you have tables referencing Django's ``User`` model, you will have to
delete those table and migrations, then re-migrate. This will ensure
everything is set up correctly from the beginning.
Instead of referring to User directly, you should reference the user model
using ``django.contrib.auth.get_user_model()``
When you define a foreign key or many-to-many relations to the ``User``
model, you should specify the custom model using the ``AUTH_USER_MODEL``
setting.
For example:
.. code-block:: python
from django.conf import settings
from django.db import models
class Profile(models.Model):
user = models.ForeignKey(
settings.AUTH_USER_MODEL,
on_delete=models.CASCADE,
)
License
-------
Released under the MIT license. See LICENSE for details.
Original author
---------------
Tom Meagher
Questions, comments, or anything else?
--------------------------------------
- Open an issue
Raw data
{
"_id": null,
"home_page": "https://github.com/tmm/django-username-email/",
"name": "django-username-email",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "user email username",
"author": "Adam Taylor",
"author_email": "ataylor32@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/f5/46/8d3abb975f8635f67574a262cc2b0c6675bc0887d8d0f3de9e53c778f275/django_username_email-2.5.6.tar.gz",
"platform": null,
"description": "CUser, make email the USERNAME\\_FIELD\n=====================================\n\nCUser makes it easy to use email address as your identification token\ninstead of a username.\n\nCUser is a custom Django user model (extends ``AbstractBaseUser``) so it\ntakes a tiny amount of effort to use.\n\nThe only difference between CUser and the vanilla Django ``User`` is email\naddress is the ``USERNAME_FIELD`` (and username does not exist).\n\nCUser supports Django 3.2 - 5.1. If you need to use CUser with\nDjango 1.8 - 3.1, you must install an older, unmaintained version of\nCUser, as noted in the \"Install & Set up\" section.\n\nWhy use CUser?\n--------------\n\nBecause you want everything in ``django.contrib.auth`` except for the\n``username`` field and you also want users to **log in with email addresses**.\nAnd you don't want to create your own custom user model or authentication\nbackend.\n\nInstall & Set up\n----------------\n\n**Important:** To keep things simple, the steps below will guide you through\nthe process of using CUser's ``CUser`` model for your Django project's user\nmodel. However, it is strongly recommended that you set up a custom user model\nthat extends CUser's ``AbstractCUser`` class, even if CUser's ``CUser`` model\nis sufficient for you (this way, you can customize the user model if the need\narises). If you would *not* like to follow this recommendation and just want to\nuse CUser's ``CUser`` model, simply follow the steps below (you can skip the\nrest of this paragraph). If you *would* like to follow this recommendation, you\nshould still follow the steps below, but with the following adjustments: After\nstep 3, follow\n`these instructions <https://docs.djangoproject.com/en/3.2/topics/auth/customizing/#using-a-custom-user-model-when-starting-a-project>`_,\nbut instead of using ``from django.contrib.auth.models import AbstractUser``\nuse ``from cuser.models import AbstractCUser`` and instead of using\n``from django.contrib.auth.admin import UserAdmin`` use\n``from cuser.admin import UserAdmin``. Then for step 4 of the steps below, you\nshould set ``AUTH_USER_MODEL`` to your custom user model instead of CUser's\n``CUser`` model. You should then run ``python manage.py makemigrations``. After\nthat, you may follow the remaining steps below just the way they are.\n\n1. If your Django project previously used Django's default user model,\n ``django.contrib.auth.models.User``, or if you are unfamiliar with using\n custom user models, jump to **Notes** first (then come\n back). Otherwise, continue onward!\n\n2. Install with ``pip``:\n\n .. code-block:: shell\n\n # Django 3.2 - 5.1\n pip install django-username-email\n\n # Django 3.1 (unmaintained)\n pip install django-username-email==2.4.2\n\n # Django 2.2 or 3.0 (unmaintained)\n pip install django-username-email==2.3.1\n\n # Django 2.0 or 2.1 (unmaintained)\n pip install django-username-email==2.2.4\n\n # Django 1.11 (unmaintained)\n pip install django-username-email==2.1.6\n\n # Django 1.8 - 1.10 (unmaintained)\n pip install django-username-email==2.1.2\n\n3. Add ``cuser`` to your ``INSTALLED_APPS`` setting:\n\n .. code-block:: python\n\n INSTALLED_APPS = [\n ...\n 'cuser',\n ]\n\n4. Specify the custom model as the default user model for your project\n using the ``AUTH_USER_MODEL`` setting in your settings.py:\n\n .. code-block:: python\n\n AUTH_USER_MODEL = 'cuser.CUser'\n\n5. If you use Django's default ``AuthenticationForm`` class, it is\n strongly recommended that you replace it with the one included with\n CUser. This will make the ``<input>`` have its ``type`` attribute set\n to ``email`` and browsers' autocomplete feature will suggest email\n addresses instead of usernames. For example, if your project is using\n Django's default ``LoginView`` view (or ``login`` view in Django < 1.11), this is\n what you would put in your urls.py in order to make use of CUser's\n ``AuthenticationForm`` class:\n\n .. code-block:: python\n\n from cuser.forms import AuthenticationForm\n from django.conf.urls import include, url\n from django.contrib.auth.views import LoginView\n\n urlpatterns = [\n url(r'^accounts/login/$', LoginView.as_view(authentication_form=AuthenticationForm), name='login'),\n url(r'^accounts/', include('django.contrib.auth.urls')),\n ...\n ]\n\n Or if you're using Django < 1.11:\n\n .. code-block:: python\n\n from cuser.forms import AuthenticationForm\n from django.conf.urls import include, url\n from django.contrib.auth.views import login\n\n urlpatterns = [\n url(r'^accounts/login/$', login, {'authentication_form': AuthenticationForm}, name='login'),\n url(r'^accounts/', include('django.contrib.auth.urls')),\n ...\n ]\n\n6. Run migrations.\n\n .. code-block:: shell\n\n python manage.py migrate\n\n7. There is a good chance that you want foo@example.com and FOO@example.com to\n be treated as the same email address. There is a variety of ways to go about\n doing this. How you handle it will depend on the needs of your project and\n personal preference, so CUser does not provide a solution for this out of\n the box. You will need to address this yourself if this applies to you. If\n you're using CUser's ``AuthenticationForm`` class (see step 5), you may want\n to subclass it and override ``error_messages['invalid_login']``.\n\nConfiguration\n-------------\n\nTo override any of the default settings, create a dictionary named ``CUSER`` in\nyour settings.py with each setting you want to override. For example:\n\n.. code-block:: python\n\n CUSER = {\n 'app_verbose_name': 'Authentication and Authorization',\n 'register_proxy_auth_group_model': True,\n }\n\nThese are the settings:\n\n``app_verbose_name`` (default: ``_(\"Custom User\")``)\n****************************************************\n\nThis controls the value that CUser will use for its ``AppConfig`` class'\n``verbose_name``.\n\n``register_proxy_auth_group_model`` (default: ``False``)\n********************************************************\n\nWhen set to ``True``, CUser's admin.py will unregister Django's default\n``Group`` model and register its own proxy model of Django's default ``Group``\nmodel (also named ``Group``). This is useful if you want Django's default\n``Group`` model to appear in the same part of the admin as CUser's ``CUser``\nmodel.\n\nNotes\n-----\n\nIf you have tables referencing Django's ``User`` model, you will have to\ndelete those table and migrations, then re-migrate. This will ensure\neverything is set up correctly from the beginning.\n\nInstead of referring to User directly, you should reference the user model\nusing ``django.contrib.auth.get_user_model()``\n\nWhen you define a foreign key or many-to-many relations to the ``User``\nmodel, you should specify the custom model using the ``AUTH_USER_MODEL``\nsetting.\n\nFor example:\n\n.. code-block:: python\n\n from django.conf import settings\n from django.db import models\n\n class Profile(models.Model):\n user = models.ForeignKey(\n settings.AUTH_USER_MODEL,\n on_delete=models.CASCADE,\n )\n\nLicense\n-------\n\nReleased under the MIT license. See LICENSE for details.\n\nOriginal author\n---------------\n\nTom Meagher\n\nQuestions, comments, or anything else?\n--------------------------------------\n\n- Open an issue\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Custom Django User model that makes email the USERNAME_FIELD.",
"version": "2.5.6",
"project_urls": {
"Homepage": "https://github.com/tmm/django-username-email/"
},
"split_keywords": [
"user",
"email",
"username"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "adf98c64629569e7e131b0facbd3522a1446122200fb466b97e04531ce2ca88a",
"md5": "7bbfd8563717a7d9fea95520bd30b579",
"sha256": "0c35008c138c8dce9fab33f86179a87d2e3e3962ea738c5ab62fc5f7e2021187"
},
"downloads": -1,
"filename": "django_username_email-2.5.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7bbfd8563717a7d9fea95520bd30b579",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 13440,
"upload_time": "2024-09-19T01:13:41",
"upload_time_iso_8601": "2024-09-19T01:13:41.823585Z",
"url": "https://files.pythonhosted.org/packages/ad/f9/8c64629569e7e131b0facbd3522a1446122200fb466b97e04531ce2ca88a/django_username_email-2.5.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f5468d3abb975f8635f67574a262cc2b0c6675bc0887d8d0f3de9e53c778f275",
"md5": "13d8e9d4a40a3b3312bb79607f1e505d",
"sha256": "5c7eb9eb47bad6d3246cb05993f2f8e95d41dfb852dffb63acd6d26550934079"
},
"downloads": -1,
"filename": "django_username_email-2.5.6.tar.gz",
"has_sig": false,
"md5_digest": "13d8e9d4a40a3b3312bb79607f1e505d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 13596,
"upload_time": "2024-09-19T01:13:43",
"upload_time_iso_8601": "2024-09-19T01:13:43.213617Z",
"url": "https://files.pythonhosted.org/packages/f5/46/8d3abb975f8635f67574a262cc2b0c6675bc0887d8d0f3de9e53c778f275/django_username_email-2.5.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-19 01:13:43",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "tmm",
"github_project": "django-username-email",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "django-username-email"
}
JSON
