django-simple-email-confirmation
================================
.. image:: https://img.shields.io/travis/mfogel/django-simple-email-confirmation/develop.svg
:target: https://travis-ci.org/mfogel/django-simple-email-confirmation/
.. image:: https://img.shields.io/coveralls/mfogel/django-simple-email-confirmation/develop.svg
:target: https://coveralls.io/r/mfogel/django-simple-email-confirmation/
.. image:: https://img.shields.io/pypi/dm/django-simple-email-confirmation.svg
:target: https://pypi.python.org/pypi/django-simple-email-confirmation/
A Django app providing simple email confirmation.
This app can be used to support three different ways of organizing your Users their email address(es). Each email address can be in a confirmed/unconfirmed state.
- Users have one email address that is stored on the `User`
- Users have one primary email address stored on the `User` model, and have N secondary emails stored in `EmailAddress` objects
- Users have N email addresses stored in `EmailAddress` objects.
Examples
--------
Create a new User, confirm their email:
.. code:: python
from django.core.mail import send_mail
# ...
email = 'original@here.com'
user = User.objects.create_user(email, email=email)
user.is_confirmed # False
send_mail(email, 'Use %s to confirm your email' % user.confirmation_key)
# User gets email, passes the confirmation_key back to your server
user.confirm_email(user.confirmation_key)
user.is_confirmed # True
Add another email to an existing User, confirm it, then set it as their primary.
.. code:: python
new_email = 'newaddr@nowhere.com'
confirmation_key = user.add_unconfirmed_email(new_email)
new_email in user.unconfirmed_emails # True
send_mail(new_email, 'Use %s to confirm your new email' % confirmation_key)
# User gets email, passes the confirmation_key back to your server
user.confirm_email(confirmation_key)
new_email in user.confirmed_emails # True
user.set_primary_email(new_email)
user.email # newaddr@nowhere.com
Installation
------------
#. From `pypi`__ using `pip`__:
.. code:: sh
pip install django-simple-email-confirmation
#. Add `simple_email_confirmation` to your `settings.INSTALLED_APPS`__:
.. code:: python
INSTALLED_APPS = (
...
'simple_email_confirmation',
...
)
#. Add the provided mixin to your `django 1.5+ custom user model`__:
.. code:: python
from django.contrib.auth.models import AbstractUser
from simple_email_confirmation.models import SimpleEmailConfirmationUserMixin
class User(SimpleEmailConfirmationUserMixin, AbstractUser):
pass
Note: you don't strictly have to do this final step. Without this, you won't have the nice helper functions and properties on your `User` objects but the remainder of the app should function fine.
#. Change default settings (optional):
By default, keys don't expire. If you want them to, set `settings.SIMPLE_EMAIL_CONFIRMATION_PERIOD` to a timedelta.
.. code:: python
from datetime import timedelta
EMAIL_CONFIRMATION_PERIOD_DAYS = 7
SIMPLE_EMAIL_CONFIRMATION_PERIOD = timedelta(days=EMAIL_CONFIRMATION_PERIOD_DAYS)
By default, auto-add unconfirmed EmailAddress objects for new Users. If you want to change this behaviour, set `settings.SIMPLE_EMAIL_CONFIRMATION_AUTO_ADD` to False.
.. code:: python
SIMPLE_EMAIL_CONFIRMATION_AUTO_ADD = False
By default, a length of keys is 12. If you want to change it, set `settings.SIMPLE_EMAIL_CONFIRMATION_KEY_LENGTH` to integer value (maximum 40).
.. code:: python
SIMPLE_EMAIL_CONFIRMATION_KEY_LENGTH = 16
You are able to override the EmailAddress model provided with this app. This works in a similar fashion as Django's custom user model and allows you to add fields to the EmailAddress model, such as a uuid, or define your own model completely. To set a custom email address model, set `settings.SIMPLE_EMAIL_CONFIRMATION_EMAIL_ADDRESS_MODEL` to the model you would like to use in the <app_label>.<model_name> fashion.
An admin interface is included with simple email confirmation. Although, it is designed to work with the EmailAddress provided. Functionality with the admin cannot be guaranteed when a custom model is used so it is recommended you provide your own admin definition.
Note for existing apps that already use the provided model:
Similar to Django's custom user model, migrating a custom email address model after the default one is already migrated is not supported and could have unforeseen side effects. The recommendation is to use a custom model from the beginning of development.
.. code:: python
SIMPLE_EMAIL_CONFIRMATION_EMAIL_ADDRESS_MODEL = 'yourapp.EmailAddress'
Migrating
---------
0.23 to 1.0
~~~~~~~~~~~
A number of backwards incompatible changes are included in the 1.0 release.
- Signal arguments have been refactored. Now, the `email_confirmed`, `unconfirmed_email_created`, and `primary_email_changed` signals send the user class as the `sender` argument and include the user instance as an additional `user` argument. You can update your code as follows:
.. code:: python
@receiver(email_confirmed)
def listener(sender, user, email, **kwargs):
pass
@receiver(unconfirmed_email_created)
def listener(sender, user, email, **kwargs):
pass
@receiver(primary_email_changed)
def listener(sender, user, old_email, new_email, **kwargs):
pass
Python/Django supported versions
--------------------------------
- Python: 2.7, 3.4, 3.5 and 3.6
- Django: 1.8 to 2.0
Running the Tests
-----------------
#. Install `tox`__ and `coverage`__
.. code:: sh
pip install tox coverage
#. From the repository root, run
.. code:: sh
tox
tox -e coverage
It's that simple.
Found a Bug?
------------
To file a bug or submit a patch, please head over to `django-simple-email-confirmation on github`__.
Credits
-------
Originally adapted from `Pinax's django-email-confirmation`__, which was originally adapted from `James Tauber's django-email-confirmation`__.
__ http://pypi.python.org/pypi/django-simple-email-confirmation/
__ http://www.pip-installer.org/
__ https://docs.djangoproject.com/en/dev/ref/settings/#installed-apps
__ https://docs.djangoproject.com/en/dev/topics/auth/customizing/#specifying-a-custom-user-model
__ https://tox.readthedocs.org/
__ https://coverage.readthedocs.org/
__ https://github.com/mfogel/django-simple-email-confirmation
__ https://github.com/pinax/django-email-confirmation
__ https://github.com/jtauber/django-email-confirmation
Raw data
{
"_id": null,
"home_page": "https://github.com/mfogel/django-simple-email-confirmation",
"name": "django-simple-email-confirmation",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "Mike Fogel",
"author_email": "mike@fogel.ca",
"download_url": "https://files.pythonhosted.org/packages/0e/f9/251bc1c25016d6e4cee85278c2a7cd7a1aa873439844d9fbcbc477bf1867/django-simple-email-confirmation-0.71.tar.gz",
"platform": null,
"description": "django-simple-email-confirmation\n================================\n\n.. image:: https://img.shields.io/travis/mfogel/django-simple-email-confirmation/develop.svg\n :target: https://travis-ci.org/mfogel/django-simple-email-confirmation/\n\n.. image:: https://img.shields.io/coveralls/mfogel/django-simple-email-confirmation/develop.svg\n :target: https://coveralls.io/r/mfogel/django-simple-email-confirmation/\n\n.. image:: https://img.shields.io/pypi/dm/django-simple-email-confirmation.svg\n :target: https://pypi.python.org/pypi/django-simple-email-confirmation/\n\nA Django app providing simple email confirmation.\n\nThis app can be used to support three different ways of organizing your Users their email address(es). Each email address can be in a confirmed/unconfirmed state.\n\n- Users have one email address that is stored on the `User`\n- Users have one primary email address stored on the `User` model, and have N secondary emails stored in `EmailAddress` objects\n- Users have N email addresses stored in `EmailAddress` objects.\n\n\nExamples\n--------\n\nCreate a new User, confirm their email:\n\n.. code:: python\n\n from django.core.mail import send_mail\n # ...\n\n email = 'original@here.com'\n user = User.objects.create_user(email, email=email)\n user.is_confirmed # False\n\n send_mail(email, 'Use %s to confirm your email' % user.confirmation_key)\n # User gets email, passes the confirmation_key back to your server\n\n user.confirm_email(user.confirmation_key)\n user.is_confirmed # True\n\nAdd another email to an existing User, confirm it, then set it as their primary.\n\n.. code:: python\n\n new_email = 'newaddr@nowhere.com'\n confirmation_key = user.add_unconfirmed_email(new_email)\n new_email in user.unconfirmed_emails # True\n\n send_mail(new_email, 'Use %s to confirm your new email' % confirmation_key)\n # User gets email, passes the confirmation_key back to your server\n\n user.confirm_email(confirmation_key)\n new_email in user.confirmed_emails # True\n\n user.set_primary_email(new_email)\n user.email # newaddr@nowhere.com\n\n\nInstallation\n------------\n\n#. From `pypi`__ using `pip`__:\n\n .. code:: sh\n\n pip install django-simple-email-confirmation\n\n#. Add `simple_email_confirmation` to your `settings.INSTALLED_APPS`__:\n\n .. code:: python\n\n INSTALLED_APPS = (\n ...\n 'simple_email_confirmation',\n ...\n )\n\n#. Add the provided mixin to your `django 1.5+ custom user model`__:\n\n .. code:: python\n\n from django.contrib.auth.models import AbstractUser\n from simple_email_confirmation.models import SimpleEmailConfirmationUserMixin\n\n class User(SimpleEmailConfirmationUserMixin, AbstractUser):\n pass\n\n Note: you don't strictly have to do this final step. Without this, you won't have the nice helper functions and properties on your `User` objects but the remainder of the app should function fine.\n\n#. Change default settings (optional):\n\n By default, keys don't expire. If you want them to, set `settings.SIMPLE_EMAIL_CONFIRMATION_PERIOD` to a timedelta.\n\n .. code:: python\n\n from datetime import timedelta\n\n EMAIL_CONFIRMATION_PERIOD_DAYS = 7\n SIMPLE_EMAIL_CONFIRMATION_PERIOD = timedelta(days=EMAIL_CONFIRMATION_PERIOD_DAYS)\n\n By default, auto-add unconfirmed EmailAddress objects for new Users. If you want to change this behaviour, set `settings.SIMPLE_EMAIL_CONFIRMATION_AUTO_ADD` to False.\n\n .. code:: python\n\n SIMPLE_EMAIL_CONFIRMATION_AUTO_ADD = False\n\n By default, a length of keys is 12. If you want to change it, set `settings.SIMPLE_EMAIL_CONFIRMATION_KEY_LENGTH` to integer value (maximum 40).\n\n .. code:: python\n\n SIMPLE_EMAIL_CONFIRMATION_KEY_LENGTH = 16\n\n You are able to override the EmailAddress model provided with this app. This works in a similar fashion as Django's custom user model and allows you to add fields to the EmailAddress model, such as a uuid, or define your own model completely. To set a custom email address model, set `settings.SIMPLE_EMAIL_CONFIRMATION_EMAIL_ADDRESS_MODEL` to the model you would like to use in the <app_label>.<model_name> fashion.\n\n An admin interface is included with simple email confirmation. Although, it is designed to work with the EmailAddress provided. Functionality with the admin cannot be guaranteed when a custom model is used so it is recommended you provide your own admin definition.\n\n Note for existing apps that already use the provided model:\n\n Similar to Django's custom user model, migrating a custom email address model after the default one is already migrated is not supported and could have unforeseen side effects. The recommendation is to use a custom model from the beginning of development.\n\n .. code:: python\n\n SIMPLE_EMAIL_CONFIRMATION_EMAIL_ADDRESS_MODEL = 'yourapp.EmailAddress'\n\n\nMigrating\n---------\n\n0.23 to 1.0\n~~~~~~~~~~~\n\nA number of backwards incompatible changes are included in the 1.0 release.\n\n- Signal arguments have been refactored. Now, the `email_confirmed`, `unconfirmed_email_created`, and `primary_email_changed` signals send the user class as the `sender` argument and include the user instance as an additional `user` argument. You can update your code as follows:\n\n .. code:: python\n\n @receiver(email_confirmed)\n def listener(sender, user, email, **kwargs):\n pass\n\n @receiver(unconfirmed_email_created)\n def listener(sender, user, email, **kwargs):\n pass\n\n @receiver(primary_email_changed)\n def listener(sender, user, old_email, new_email, **kwargs):\n pass\n\n\n\nPython/Django supported versions\n--------------------------------\n\n- Python: 2.7, 3.4, 3.5 and 3.6\n- Django: 1.8 to 2.0\n\n\nRunning the Tests\n-----------------\n\n#. Install `tox`__ and `coverage`__\n\n .. code:: sh\n\n pip install tox coverage\n\n#. From the repository root, run\n\n .. code:: sh\n\n tox\n tox -e coverage\n\n It's that simple.\n\n\nFound a Bug?\n------------\n\nTo file a bug or submit a patch, please head over to `django-simple-email-confirmation on github`__.\n\n\nCredits\n-------\n\nOriginally adapted from `Pinax's django-email-confirmation`__, which was originally adapted from `James Tauber's django-email-confirmation`__.\n\n\n__ http://pypi.python.org/pypi/django-simple-email-confirmation/\n__ http://www.pip-installer.org/\n__ https://docs.djangoproject.com/en/dev/ref/settings/#installed-apps\n__ https://docs.djangoproject.com/en/dev/topics/auth/customizing/#specifying-a-custom-user-model\n__ https://tox.readthedocs.org/\n__ https://coverage.readthedocs.org/\n__ https://github.com/mfogel/django-simple-email-confirmation\n__ https://github.com/pinax/django-email-confirmation\n__ https://github.com/jtauber/django-email-confirmation",
"bugtrack_url": null,
"license": "BSD",
"summary": "Simple email confirmation for django.",
"version": "0.71",
"project_urls": {
"Homepage": "https://github.com/mfogel/django-simple-email-confirmation"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "0ef9251bc1c25016d6e4cee85278c2a7cd7a1aa873439844d9fbcbc477bf1867",
"md5": "b55407aaf81371748fc3d5af33c4d31b",
"sha256": "654fc963956639265ed12fe1cc89a2b7392b7c25c8af0fa2be33c43dde2ad691"
},
"downloads": -1,
"filename": "django-simple-email-confirmation-0.71.tar.gz",
"has_sig": false,
"md5_digest": "b55407aaf81371748fc3d5af33c4d31b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 11477,
"upload_time": "2024-01-20T17:51:27",
"upload_time_iso_8601": "2024-01-20T17:51:27.886661Z",
"url": "https://files.pythonhosted.org/packages/0e/f9/251bc1c25016d6e4cee85278c2a7cd7a1aa873439844d9fbcbc477bf1867/django-simple-email-confirmation-0.71.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-20 17:51:27",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mfogel",
"github_project": "django-simple-email-confirmation",
"travis_ci": true,
"coveralls": false,
"github_actions": false,
"tox": true,
"lcname": "django-simple-email-confirmation"
}
JSON
