diff options
| -rw-r--r-- | .gitignore | 1 | ||||
| -rw-r--r-- | python-django-email-verification.spec | 947 | ||||
| -rw-r--r-- | sources | 1 |
3 files changed, 949 insertions, 0 deletions
@@ -0,0 +1 @@ +/django-email-verification-0.3.1.tar.gz diff --git a/python-django-email-verification.spec b/python-django-email-verification.spec new file mode 100644 index 0000000..5a0bec3 --- /dev/null +++ b/python-django-email-verification.spec @@ -0,0 +1,947 @@ +%global _empty_manifest_terminate_build 0 +Name: python-django-email-verification +Version: 0.3.1 +Release: 1 +Summary: Email confirmation app for django +License: MIT +URL: https://github.com/LeoneBacciu/django-email-verification +Source0: https://mirrors.nju.edu.cn/pypi/web/packages/15/60/0050786d650ae8674614d6cf675171861acaa2de95c5885d4398f89679c4/django-email-verification-0.3.1.tar.gz +BuildArch: noarch + +Requires: python3-deprecation +Requires: python3-PyJWT + +%description +# Django Email Verification + +[](https://pypi.org/project/django-email-verification/) +[](https://github.com/LeoneBacciu/django-email-verification/blob/version-0.1.0/LICENSE) +[](https://github.com/LeoneBacciu/django-email-verification/actions) +[](https://codecov.io/gh/LeoneBacciu/django-email-verification) + +<p align="center"> + <img src="https://github.com/LeoneBacciu/django-email-verification/blob/master/icon.png?raw=True" width="300px" alt="icon"> +</p> + +<p align="center"> +Do you like my work and want to support me?<br/><br/> +<a href="https://www.buymeacoffee.com/LeoneBacciu" target="_blank"><img src="https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png" alt="Buy Me A Coffee" style="height: auto !important;width: auto !important;" ></a> +</p> + +> ## 🚧 Work in progress 🚧 +> The package now also provides all the feature needed for **password recovery**, but the documentation is not ready +> yet. \ +> Thanks for your patience! + +## Requirements + ++ Python >= 3.8 ++ Django >= 3.1 + +## General concept + + + +## Installation + +You can install by: + +```commandline +pip3 install django-email-verification +``` + +and import by: + +```python +INSTALLED_APPS = [ + 'django.contrib.admin', + 'django.contrib.auth', + ... + 'django_email_verification', # you have to add this +] +``` + +## Settings parameters + +You have to add these parameters to the settings, you have to include all of them except the last one: + +```python +def verified_callback(user): + user.is_active = True + + +EMAIL_VERIFIED_CALLBACK = verified_callback +EMAIL_FROM_ADDRESS = 'noreply@aliasaddress.com' +EMAIL_MAIL_SUBJECT = 'Confirm your email' +EMAIL_MAIL_HTML = 'mail_body.html' +EMAIL_MAIL_PLAIN = 'mail_body.txt' +EMAIL_TOKEN_LIFE = 60 * 60 +EMAIL_PAGE_TEMPLATE = 'confirm_template.html' +EMAIL_PAGE_DOMAIN = 'http://mydomain.com/' +EMAIL_MULTI_USER = True # optional (defaults to False) + +# For Django Email Backend +EMAIL_BACKEND = 'django.core.mail.backends.console.EmailBackend' +EMAIL_HOST = 'smtp.gmail.com' +EMAIL_PORT = 587 +EMAIL_HOST_USER = 'mymail@gmail.com' +EMAIL_HOST_PASSWORD = 'mYC00lP4ssw0rd' # os.environ['password_key'] suggested +EMAIL_USE_TLS = True + + +``` + +In detail: + ++ `EMAIL_VERIFIED_CALLBACK`: the function that will be called when the user successfully verifies the email. Takes the + user object as argument. ++ `EMAIL_FROM_ADDRESS`: this can be the same as `EMAIL_HOST_USER` or an alias address if required. ++ `EMAIL_MAIL_`: + * `SUBJECT`: the mail default subject. + * `HTML`: the mail body template in form of html. + * `PLAIN`: the mail body template in form of .txt file. ++ `EMAIL_TOKEN_LIFE`: the lifespan of the email link (in seconds). ++ `EMAIL_PAGE_TEMPLATE`: the template of the success/error view. ++ `EMAIL_PAGE_DOMAIN`: the domain of the confirmation link (usually your site's domain). ++ `EMAIL_MULTI_USER`: (optional) if `True` an error won't be thrown if multiple users with the same email are present ( + just one will be activated) + +For the Django Email Backend fields look at the +official [documentation](https://docs.djangoproject.com/en/3.1/topics/email/). + +The `EMAIL_VERIFIED_CALLBACK` can be a function on the `AUTH_USER_MODEL`, for example: +```python +EMAIL_VERIFIED_CALLBACK = get_user_model().verified_callback +``` +The function will receive no arguments. + +## Templates examples + +The `EMAIL_MAIL_SUBJECT` should look like this (`{{ link }}`(`str`), `{{ expiry }}`(`datetime`) and `user`(`Model`) are +passed during the rendering): + +```python +EMAIL_MAIL_SUBJECT = 'Confirm your email {{ user.username }}' +``` + +The `EMAIL_MAIL_HTML` should look like this (`{{ link }}`(`str`), `{{ expiry }}`(`datetime`) and `user`(`Model`) are +passed during the rendering): + +```html +<h1>You are almost there, {{ user.username }}!</h1><br> +<h2>Please click <a href="{{ link }}">here</a> to confirm your account</h2> +<h2>The token expires on {{ expiry|time:"TIME_FORMAT" }}</h2> +``` + +The `EMAIL_MAIL_PLAIN` should look like this (`{{ link }}`(`str`), `{{ expiry }}`(`datetime`) and `user`(`Model`) are +passed during the rendering): + +```text +You are almost there, {{ user.username }}! +Please click the following link to confirm your account: {{ link }} +The token expires on {{ expiry|time:"TIME_FORMAT" }} +``` + +The `EMAIL_PAGE_TEMPLATE` should look like this (`{{ success }}`(`bool`), `{{ user }}`(`Model`) +and `{{ request }}`(`WSGIRequest`) are passed during the rendering): + +```html +<!DOCTYPE html> +<html lang="en"> +<head> + <meta charset="UTF-8"> + <title>Confirmation</title> +</head> +<body> +{% if success %} +{{ user.username }}, your account is confirmed! +{% else %} +Error, invalid token! +{% endif %} +</body> +</html> +``` + +## Email sending + +After you have created the user you can send the confirm email + +```python +from django.shortcuts import render +from django.contrib.auth import get_user_model +from django_email_verification import send_email + + +def my_functional_view(request): + ... + user = get_user_model().objects.create(username=username, password=password, email=email) + user.is_active = False # Example + send_email(user) + return render(...) +``` + +`send_email(user)` sends an email with the defined template (and the pseudo-random generated token) to the user. + +> **_IMPORTANT:_** You have to manually set the user to inactive before sending the email. + +If you are using class based views, then it is necessary to call the superclass before calling the `send_confirm` +method. + +```python +from django.views.generic.edit import FormView +from django_email_verification import send_email + + +class MyClassView(FormView): + + def form_valid(self, form): + user = form.save() + returnVal = super(MyClassView, self).form_valid(form) + send_email(user) + return returnVal +``` + +## Token verification + +There are two ways to get the token verified: + ++ The first one is the simplest: you just have to include the app urls in `urls.py` + + ```python + from django.contrib import admin + from django.urls import path, include + from django_email_verification import urls as email_urls # include the urls + + urlpatterns = [ + path('admin/', admin.site.urls), + ... + path('email/', include(email_urls)), # connect them to an arbitrary path + ] + ``` + When a request arrives to `https.//mydomain.com/email/<token>` the package verifies the token and: + + + if it corresponds to a pending token it renders the `EMAIL_PAGE_TEMPLATE` passing `success=True` and deletes the token + + if it doesn't correspond it renders the `EMAIL_PAGE_TEMPLATE` passing `success=False` + + ++ The second one is more customizable: you can build your own view for verification, mark it as `@verify_view`, verify the token manually with the function `verify_token(token)` and execute your custom logic, + here's how: + + ```python + ### For the view + + from django.http import HttpResponse + from django_email_verification import verify_view, verify_token + + + @verify_view + def confirm(request, token): + success, user = verify_token(token) + return HttpResponse(f'Account verified, {user.username}' if success else 'Invalid token') + + + ### For the urls + from django.urls import path + + urlpatterns = [ + ... + path('email/<str:token>/', confirm), # remember to set the "token" parameter in the url! + ... + ] + ``` + > **_IMPORTANT:_** the path must **NOT** have the `name` attribute set + + The library makes sure one and only one `@verify_view` is present and throws an error if this condition is not met. + + +## Testing + +If you are using django-email-verification and you want to test the email, if settings.DEBUG == True, then two items +will be added to the email headers. +You can obtain these by checking the django.core.mail outbox, which will have a non-zero length if an email has been +sent. Retrieve the email and obtain the link (includes token) or the token to use in your code. + +```python +from django.core import mail + +... +test +body... + +try: + email = mail.outbox[0] + link = mail.extra_headers['LINK'] + token = mail.extra_headers['TOKEN'] + browser.visit(link) # verifies token... +except AttributeError: + logger.warn("no email") +``` + +For the email to be in the inbox, you will need to use the correct email backend. Use either: +``` +EMAIL_BACKEND = 'django.core.mail.backends.locmem.EmailBackend' +``` +or: +``` +EMAIL_BACKEND = 'django.core.mail.backends.console.EmailBackend' +``` + +## Console backend for development + +If you want to use the console email backend provided by django, then define: + +```python +EMAIL_BACKEND = 'django.core.mail.backends.console.EmailBackend' +``` + +You can use all the django email backends and also your custom one. + + +### Logo copyright: + +Logo by by <a href="https://github.com/filippoveggo" title="Flippo Veggo">Filippo Veggo</a> +<div>"Django and the Django logo are registered trademarks of Django Software Foundation.<br/>Usage of the Django trademarks are subject to the Django Trademark licensing Agreement."</div> +<div>Icons made by <a href="https://www.flaticon.com/authors/kiranshastry" title="Kiranshastry">Kiranshastry</a> from <a href="https://www.flaticon.com/" title="Flaticon">www.flaticon.com</a></div> +<div>Icons made by <a href="https://www.flaticon.com/authors/pixel-perfect" title="Pixel perfect">Pixel perfect</a> from <a href="https://www.flaticon.com/" title="Flaticon">www.flaticon.com</a></div> + + +%package -n python3-django-email-verification +Summary: Email confirmation app for django +Provides: python-django-email-verification +BuildRequires: python3-devel +BuildRequires: python3-setuptools +BuildRequires: python3-pip +%description -n python3-django-email-verification +# Django Email Verification + +[](https://pypi.org/project/django-email-verification/) +[](https://github.com/LeoneBacciu/django-email-verification/blob/version-0.1.0/LICENSE) +[](https://github.com/LeoneBacciu/django-email-verification/actions) +[](https://codecov.io/gh/LeoneBacciu/django-email-verification) + +<p align="center"> + <img src="https://github.com/LeoneBacciu/django-email-verification/blob/master/icon.png?raw=True" width="300px" alt="icon"> +</p> + +<p align="center"> +Do you like my work and want to support me?<br/><br/> +<a href="https://www.buymeacoffee.com/LeoneBacciu" target="_blank"><img src="https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png" alt="Buy Me A Coffee" style="height: auto !important;width: auto !important;" ></a> +</p> + +> ## 🚧 Work in progress 🚧 +> The package now also provides all the feature needed for **password recovery**, but the documentation is not ready +> yet. \ +> Thanks for your patience! + +## Requirements + ++ Python >= 3.8 ++ Django >= 3.1 + +## General concept + + + +## Installation + +You can install by: + +```commandline +pip3 install django-email-verification +``` + +and import by: + +```python +INSTALLED_APPS = [ + 'django.contrib.admin', + 'django.contrib.auth', + ... + 'django_email_verification', # you have to add this +] +``` + +## Settings parameters + +You have to add these parameters to the settings, you have to include all of them except the last one: + +```python +def verified_callback(user): + user.is_active = True + + +EMAIL_VERIFIED_CALLBACK = verified_callback +EMAIL_FROM_ADDRESS = 'noreply@aliasaddress.com' +EMAIL_MAIL_SUBJECT = 'Confirm your email' +EMAIL_MAIL_HTML = 'mail_body.html' +EMAIL_MAIL_PLAIN = 'mail_body.txt' +EMAIL_TOKEN_LIFE = 60 * 60 +EMAIL_PAGE_TEMPLATE = 'confirm_template.html' +EMAIL_PAGE_DOMAIN = 'http://mydomain.com/' +EMAIL_MULTI_USER = True # optional (defaults to False) + +# For Django Email Backend +EMAIL_BACKEND = 'django.core.mail.backends.console.EmailBackend' +EMAIL_HOST = 'smtp.gmail.com' +EMAIL_PORT = 587 +EMAIL_HOST_USER = 'mymail@gmail.com' +EMAIL_HOST_PASSWORD = 'mYC00lP4ssw0rd' # os.environ['password_key'] suggested +EMAIL_USE_TLS = True + + +``` + +In detail: + ++ `EMAIL_VERIFIED_CALLBACK`: the function that will be called when the user successfully verifies the email. Takes the + user object as argument. ++ `EMAIL_FROM_ADDRESS`: this can be the same as `EMAIL_HOST_USER` or an alias address if required. ++ `EMAIL_MAIL_`: + * `SUBJECT`: the mail default subject. + * `HTML`: the mail body template in form of html. + * `PLAIN`: the mail body template in form of .txt file. ++ `EMAIL_TOKEN_LIFE`: the lifespan of the email link (in seconds). ++ `EMAIL_PAGE_TEMPLATE`: the template of the success/error view. ++ `EMAIL_PAGE_DOMAIN`: the domain of the confirmation link (usually your site's domain). ++ `EMAIL_MULTI_USER`: (optional) if `True` an error won't be thrown if multiple users with the same email are present ( + just one will be activated) + +For the Django Email Backend fields look at the +official [documentation](https://docs.djangoproject.com/en/3.1/topics/email/). + +The `EMAIL_VERIFIED_CALLBACK` can be a function on the `AUTH_USER_MODEL`, for example: +```python +EMAIL_VERIFIED_CALLBACK = get_user_model().verified_callback +``` +The function will receive no arguments. + +## Templates examples + +The `EMAIL_MAIL_SUBJECT` should look like this (`{{ link }}`(`str`), `{{ expiry }}`(`datetime`) and `user`(`Model`) are +passed during the rendering): + +```python +EMAIL_MAIL_SUBJECT = 'Confirm your email {{ user.username }}' +``` + +The `EMAIL_MAIL_HTML` should look like this (`{{ link }}`(`str`), `{{ expiry }}`(`datetime`) and `user`(`Model`) are +passed during the rendering): + +```html +<h1>You are almost there, {{ user.username }}!</h1><br> +<h2>Please click <a href="{{ link }}">here</a> to confirm your account</h2> +<h2>The token expires on {{ expiry|time:"TIME_FORMAT" }}</h2> +``` + +The `EMAIL_MAIL_PLAIN` should look like this (`{{ link }}`(`str`), `{{ expiry }}`(`datetime`) and `user`(`Model`) are +passed during the rendering): + +```text +You are almost there, {{ user.username }}! +Please click the following link to confirm your account: {{ link }} +The token expires on {{ expiry|time:"TIME_FORMAT" }} +``` + +The `EMAIL_PAGE_TEMPLATE` should look like this (`{{ success }}`(`bool`), `{{ user }}`(`Model`) +and `{{ request }}`(`WSGIRequest`) are passed during the rendering): + +```html +<!DOCTYPE html> +<html lang="en"> +<head> + <meta charset="UTF-8"> + <title>Confirmation</title> +</head> +<body> +{% if success %} +{{ user.username }}, your account is confirmed! +{% else %} +Error, invalid token! +{% endif %} +</body> +</html> +``` + +## Email sending + +After you have created the user you can send the confirm email + +```python +from django.shortcuts import render +from django.contrib.auth import get_user_model +from django_email_verification import send_email + + +def my_functional_view(request): + ... + user = get_user_model().objects.create(username=username, password=password, email=email) + user.is_active = False # Example + send_email(user) + return render(...) +``` + +`send_email(user)` sends an email with the defined template (and the pseudo-random generated token) to the user. + +> **_IMPORTANT:_** You have to manually set the user to inactive before sending the email. + +If you are using class based views, then it is necessary to call the superclass before calling the `send_confirm` +method. + +```python +from django.views.generic.edit import FormView +from django_email_verification import send_email + + +class MyClassView(FormView): + + def form_valid(self, form): + user = form.save() + returnVal = super(MyClassView, self).form_valid(form) + send_email(user) + return returnVal +``` + +## Token verification + +There are two ways to get the token verified: + ++ The first one is the simplest: you just have to include the app urls in `urls.py` + + ```python + from django.contrib import admin + from django.urls import path, include + from django_email_verification import urls as email_urls # include the urls + + urlpatterns = [ + path('admin/', admin.site.urls), + ... + path('email/', include(email_urls)), # connect them to an arbitrary path + ] + ``` + When a request arrives to `https.//mydomain.com/email/<token>` the package verifies the token and: + + + if it corresponds to a pending token it renders the `EMAIL_PAGE_TEMPLATE` passing `success=True` and deletes the token + + if it doesn't correspond it renders the `EMAIL_PAGE_TEMPLATE` passing `success=False` + + ++ The second one is more customizable: you can build your own view for verification, mark it as `@verify_view`, verify the token manually with the function `verify_token(token)` and execute your custom logic, + here's how: + + ```python + ### For the view + + from django.http import HttpResponse + from django_email_verification import verify_view, verify_token + + + @verify_view + def confirm(request, token): + success, user = verify_token(token) + return HttpResponse(f'Account verified, {user.username}' if success else 'Invalid token') + + + ### For the urls + from django.urls import path + + urlpatterns = [ + ... + path('email/<str:token>/', confirm), # remember to set the "token" parameter in the url! + ... + ] + ``` + > **_IMPORTANT:_** the path must **NOT** have the `name` attribute set + + The library makes sure one and only one `@verify_view` is present and throws an error if this condition is not met. + + +## Testing + +If you are using django-email-verification and you want to test the email, if settings.DEBUG == True, then two items +will be added to the email headers. +You can obtain these by checking the django.core.mail outbox, which will have a non-zero length if an email has been +sent. Retrieve the email and obtain the link (includes token) or the token to use in your code. + +```python +from django.core import mail + +... +test +body... + +try: + email = mail.outbox[0] + link = mail.extra_headers['LINK'] + token = mail.extra_headers['TOKEN'] + browser.visit(link) # verifies token... +except AttributeError: + logger.warn("no email") +``` + +For the email to be in the inbox, you will need to use the correct email backend. Use either: +``` +EMAIL_BACKEND = 'django.core.mail.backends.locmem.EmailBackend' +``` +or: +``` +EMAIL_BACKEND = 'django.core.mail.backends.console.EmailBackend' +``` + +## Console backend for development + +If you want to use the console email backend provided by django, then define: + +```python +EMAIL_BACKEND = 'django.core.mail.backends.console.EmailBackend' +``` + +You can use all the django email backends and also your custom one. + + +### Logo copyright: + +Logo by by <a href="https://github.com/filippoveggo" title="Flippo Veggo">Filippo Veggo</a> +<div>"Django and the Django logo are registered trademarks of Django Software Foundation.<br/>Usage of the Django trademarks are subject to the Django Trademark licensing Agreement."</div> +<div>Icons made by <a href="https://www.flaticon.com/authors/kiranshastry" title="Kiranshastry">Kiranshastry</a> from <a href="https://www.flaticon.com/" title="Flaticon">www.flaticon.com</a></div> +<div>Icons made by <a href="https://www.flaticon.com/authors/pixel-perfect" title="Pixel perfect">Pixel perfect</a> from <a href="https://www.flaticon.com/" title="Flaticon">www.flaticon.com</a></div> + + +%package help +Summary: Development documents and examples for django-email-verification +Provides: python3-django-email-verification-doc +%description help +# Django Email Verification + +[](https://pypi.org/project/django-email-verification/) +[](https://github.com/LeoneBacciu/django-email-verification/blob/version-0.1.0/LICENSE) +[](https://github.com/LeoneBacciu/django-email-verification/actions) +[](https://codecov.io/gh/LeoneBacciu/django-email-verification) + +<p align="center"> + <img src="https://github.com/LeoneBacciu/django-email-verification/blob/master/icon.png?raw=True" width="300px" alt="icon"> +</p> + +<p align="center"> +Do you like my work and want to support me?<br/><br/> +<a href="https://www.buymeacoffee.com/LeoneBacciu" target="_blank"><img src="https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png" alt="Buy Me A Coffee" style="height: auto !important;width: auto !important;" ></a> +</p> + +> ## 🚧 Work in progress 🚧 +> The package now also provides all the feature needed for **password recovery**, but the documentation is not ready +> yet. \ +> Thanks for your patience! + +## Requirements + ++ Python >= 3.8 ++ Django >= 3.1 + +## General concept + + + +## Installation + +You can install by: + +```commandline +pip3 install django-email-verification +``` + +and import by: + +```python +INSTALLED_APPS = [ + 'django.contrib.admin', + 'django.contrib.auth', + ... + 'django_email_verification', # you have to add this +] +``` + +## Settings parameters + +You have to add these parameters to the settings, you have to include all of them except the last one: + +```python +def verified_callback(user): + user.is_active = True + + +EMAIL_VERIFIED_CALLBACK = verified_callback +EMAIL_FROM_ADDRESS = 'noreply@aliasaddress.com' +EMAIL_MAIL_SUBJECT = 'Confirm your email' +EMAIL_MAIL_HTML = 'mail_body.html' +EMAIL_MAIL_PLAIN = 'mail_body.txt' +EMAIL_TOKEN_LIFE = 60 * 60 +EMAIL_PAGE_TEMPLATE = 'confirm_template.html' +EMAIL_PAGE_DOMAIN = 'http://mydomain.com/' +EMAIL_MULTI_USER = True # optional (defaults to False) + +# For Django Email Backend +EMAIL_BACKEND = 'django.core.mail.backends.console.EmailBackend' +EMAIL_HOST = 'smtp.gmail.com' +EMAIL_PORT = 587 +EMAIL_HOST_USER = 'mymail@gmail.com' +EMAIL_HOST_PASSWORD = 'mYC00lP4ssw0rd' # os.environ['password_key'] suggested +EMAIL_USE_TLS = True + + +``` + +In detail: + ++ `EMAIL_VERIFIED_CALLBACK`: the function that will be called when the user successfully verifies the email. Takes the + user object as argument. ++ `EMAIL_FROM_ADDRESS`: this can be the same as `EMAIL_HOST_USER` or an alias address if required. ++ `EMAIL_MAIL_`: + * `SUBJECT`: the mail default subject. + * `HTML`: the mail body template in form of html. + * `PLAIN`: the mail body template in form of .txt file. ++ `EMAIL_TOKEN_LIFE`: the lifespan of the email link (in seconds). ++ `EMAIL_PAGE_TEMPLATE`: the template of the success/error view. ++ `EMAIL_PAGE_DOMAIN`: the domain of the confirmation link (usually your site's domain). ++ `EMAIL_MULTI_USER`: (optional) if `True` an error won't be thrown if multiple users with the same email are present ( + just one will be activated) + +For the Django Email Backend fields look at the +official [documentation](https://docs.djangoproject.com/en/3.1/topics/email/). + +The `EMAIL_VERIFIED_CALLBACK` can be a function on the `AUTH_USER_MODEL`, for example: +```python +EMAIL_VERIFIED_CALLBACK = get_user_model().verified_callback +``` +The function will receive no arguments. + +## Templates examples + +The `EMAIL_MAIL_SUBJECT` should look like this (`{{ link }}`(`str`), `{{ expiry }}`(`datetime`) and `user`(`Model`) are +passed during the rendering): + +```python +EMAIL_MAIL_SUBJECT = 'Confirm your email {{ user.username }}' +``` + +The `EMAIL_MAIL_HTML` should look like this (`{{ link }}`(`str`), `{{ expiry }}`(`datetime`) and `user`(`Model`) are +passed during the rendering): + +```html +<h1>You are almost there, {{ user.username }}!</h1><br> +<h2>Please click <a href="{{ link }}">here</a> to confirm your account</h2> +<h2>The token expires on {{ expiry|time:"TIME_FORMAT" }}</h2> +``` + +The `EMAIL_MAIL_PLAIN` should look like this (`{{ link }}`(`str`), `{{ expiry }}`(`datetime`) and `user`(`Model`) are +passed during the rendering): + +```text +You are almost there, {{ user.username }}! +Please click the following link to confirm your account: {{ link }} +The token expires on {{ expiry|time:"TIME_FORMAT" }} +``` + +The `EMAIL_PAGE_TEMPLATE` should look like this (`{{ success }}`(`bool`), `{{ user }}`(`Model`) +and `{{ request }}`(`WSGIRequest`) are passed during the rendering): + +```html +<!DOCTYPE html> +<html lang="en"> +<head> + <meta charset="UTF-8"> + <title>Confirmation</title> +</head> +<body> +{% if success %} +{{ user.username }}, your account is confirmed! +{% else %} +Error, invalid token! +{% endif %} +</body> +</html> +``` + +## Email sending + +After you have created the user you can send the confirm email + +```python +from django.shortcuts import render +from django.contrib.auth import get_user_model +from django_email_verification import send_email + + +def my_functional_view(request): + ... + user = get_user_model().objects.create(username=username, password=password, email=email) + user.is_active = False # Example + send_email(user) + return render(...) +``` + +`send_email(user)` sends an email with the defined template (and the pseudo-random generated token) to the user. + +> **_IMPORTANT:_** You have to manually set the user to inactive before sending the email. + +If you are using class based views, then it is necessary to call the superclass before calling the `send_confirm` +method. + +```python +from django.views.generic.edit import FormView +from django_email_verification import send_email + + +class MyClassView(FormView): + + def form_valid(self, form): + user = form.save() + returnVal = super(MyClassView, self).form_valid(form) + send_email(user) + return returnVal +``` + +## Token verification + +There are two ways to get the token verified: + ++ The first one is the simplest: you just have to include the app urls in `urls.py` + + ```python + from django.contrib import admin + from django.urls import path, include + from django_email_verification import urls as email_urls # include the urls + + urlpatterns = [ + path('admin/', admin.site.urls), + ... + path('email/', include(email_urls)), # connect them to an arbitrary path + ] + ``` + When a request arrives to `https.//mydomain.com/email/<token>` the package verifies the token and: + + + if it corresponds to a pending token it renders the `EMAIL_PAGE_TEMPLATE` passing `success=True` and deletes the token + + if it doesn't correspond it renders the `EMAIL_PAGE_TEMPLATE` passing `success=False` + + ++ The second one is more customizable: you can build your own view for verification, mark it as `@verify_view`, verify the token manually with the function `verify_token(token)` and execute your custom logic, + here's how: + + ```python + ### For the view + + from django.http import HttpResponse + from django_email_verification import verify_view, verify_token + + + @verify_view + def confirm(request, token): + success, user = verify_token(token) + return HttpResponse(f'Account verified, {user.username}' if success else 'Invalid token') + + + ### For the urls + from django.urls import path + + urlpatterns = [ + ... + path('email/<str:token>/', confirm), # remember to set the "token" parameter in the url! + ... + ] + ``` + > **_IMPORTANT:_** the path must **NOT** have the `name` attribute set + + The library makes sure one and only one `@verify_view` is present and throws an error if this condition is not met. + + +## Testing + +If you are using django-email-verification and you want to test the email, if settings.DEBUG == True, then two items +will be added to the email headers. +You can obtain these by checking the django.core.mail outbox, which will have a non-zero length if an email has been +sent. Retrieve the email and obtain the link (includes token) or the token to use in your code. + +```python +from django.core import mail + +... +test +body... + +try: + email = mail.outbox[0] + link = mail.extra_headers['LINK'] + token = mail.extra_headers['TOKEN'] + browser.visit(link) # verifies token... +except AttributeError: + logger.warn("no email") +``` + +For the email to be in the inbox, you will need to use the correct email backend. Use either: +``` +EMAIL_BACKEND = 'django.core.mail.backends.locmem.EmailBackend' +``` +or: +``` +EMAIL_BACKEND = 'django.core.mail.backends.console.EmailBackend' +``` + +## Console backend for development + +If you want to use the console email backend provided by django, then define: + +```python +EMAIL_BACKEND = 'django.core.mail.backends.console.EmailBackend' +``` + +You can use all the django email backends and also your custom one. + + +### Logo copyright: + +Logo by by <a href="https://github.com/filippoveggo" title="Flippo Veggo">Filippo Veggo</a> +<div>"Django and the Django logo are registered trademarks of Django Software Foundation.<br/>Usage of the Django trademarks are subject to the Django Trademark licensing Agreement."</div> +<div>Icons made by <a href="https://www.flaticon.com/authors/kiranshastry" title="Kiranshastry">Kiranshastry</a> from <a href="https://www.flaticon.com/" title="Flaticon">www.flaticon.com</a></div> +<div>Icons made by <a href="https://www.flaticon.com/authors/pixel-perfect" title="Pixel perfect">Pixel perfect</a> from <a href="https://www.flaticon.com/" title="Flaticon">www.flaticon.com</a></div> + + +%prep +%autosetup -n django-email-verification-0.3.1 + +%build +%py3_build + +%install +%py3_install +install -d -m755 %{buildroot}/%{_pkgdocdir} +if [ -d doc ]; then cp -arf doc %{buildroot}/%{_pkgdocdir}; fi +if [ -d docs ]; then cp -arf docs %{buildroot}/%{_pkgdocdir}; fi +if [ -d example ]; then cp -arf example %{buildroot}/%{_pkgdocdir}; fi +if [ -d examples ]; then cp -arf examples %{buildroot}/%{_pkgdocdir}; fi +pushd %{buildroot} +if [ -d usr/lib ]; then + find usr/lib -type f -printf "/%h/%f\n" >> filelist.lst +fi +if [ -d usr/lib64 ]; then + find usr/lib64 -type f -printf "/%h/%f\n" >> filelist.lst +fi +if [ -d usr/bin ]; then + find usr/bin -type f -printf "/%h/%f\n" >> filelist.lst +fi +if [ -d usr/sbin ]; then + find usr/sbin -type f -printf "/%h/%f\n" >> filelist.lst +fi +touch doclist.lst +if [ -d usr/share/man ]; then + find usr/share/man -type f -printf "/%h/%f.gz\n" >> doclist.lst +fi +popd +mv %{buildroot}/filelist.lst . +mv %{buildroot}/doclist.lst . + +%files -n python3-django-email-verification -f filelist.lst +%dir %{python3_sitelib}/* + +%files help -f doclist.lst +%{_docdir}/* + +%changelog +* Fri May 05 2023 Python_Bot <Python_Bot@openeuler.org> - 0.3.1-1 +- Package Spec generated @@ -0,0 +1 @@ +d0e858d5f825e8867a5cae6f40938af2 django-email-verification-0.3.1.tar.gz |