Metadata-Version: 2.1
Name: django-zxcvbn-password
Version: 2.1.1
Summary: Back-end and Front-end password validation with ZXCVBN.
Home-page: https://github.com/Pawamoy/django-zxcvbn-password
Author: Timothee Mazzucotelli
Author-email: timothee.mazzucotelli@gmail.com
License: ISC
Keywords: django,zxcvbn,password
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: ISC License (ISCL)
Classifier: Operating System :: Unix
Classifier: Framework :: Django
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Topic :: Utilities
License-File: LICENSE
License-File: AUTHORS.rst
Requires-Dist: zxcvbn

======================
Django ZXCVBN Password
======================



Back-end and Front-end password validation with ZXCVBN.

A combination of
`pirandig’s django-zxcvbn`_ and `aj-may’s django-password-strength`_ Django apps.
It combines back-end and front-end validation with strength meter display.

.. _pirandig’s django-zxcvbn: https://github.com/pirandig/django-zxcvbn
.. _aj-may’s django-password-strength: https://github.com/aj-may/django-password-strength

License
=======

Software licensed under `ISC`_ license.

.. _ISC: https://www.isc.org/downloads/software-support-policy/isc-license/

Installation
============

::

    pip install django-zxcvbn-password


Requirements
============

The JavaScript code of this application uses JQuery, but JQuery is not bundled
with it. Please install it separately. You might also want to use Bootstrap.

Usage
=====

.. code:: python

    # settings.py

    INSTALLED_APPS = [
        ...
        'zxcvbn_password',
        ...
    ]

    AUTH_PASSWORD_VALIDATORS = [
        {
            'NAME': 'django.contrib.auth.password_validation.UserAttributeSimilarityValidator',
        },
        {
            'NAME': 'django.contrib.auth.password_validation.MinimumLengthValidator',
        },
        {
            'NAME': 'django.contrib.auth.password_validation.CommonPasswordValidator',
        },
        {
            'NAME': 'django.contrib.auth.password_validation.NumericPasswordValidator',
        },
        {
            'NAME': 'zxcvbn_password.ZXCVBNValidator',
            'OPTIONS': {
                'min_score': 3,
                'user_attributes': ('username', 'email', 'first_name', 'last_name')
            }
        }
    ]

.. code:: python

    # forms.py

    from django import forms
    from zxcvbn_password.fields import PasswordField, PasswordConfirmationField

    class RegisterForm(forms.Form):
        password1 = PasswordField()
        password2 = PasswordConfirmationField(confirm_with=’password1’)


.. code:: python

    # views.py

    if form.is_valid():
        user = User.objects.create_user(
            username=...,
            password=form.cleaned_data['password1']
        )


By default, other inputs won't be used to compute the score, but you can enforce it
like this:

.. code:: python

    # forms.py

    from django import forms
    from zxcvbn_password import zxcvbn
    from zxcvbn_password.fields import PasswordField, PasswordConfirmationField

    class RegisterForm(forms.Form):
        password1 = PasswordField()
        password2 = PasswordConfirmationField(confirm_with=’password1’)

        def clean(self):
            password = self.cleaned_data.get('password1')
            other_field1 = ...
            other_field2 = ...

            if password:
                score = zxcvbn(password, [other_field1, other_field2])['score']
                # score is between 0 and 4
                # raise forms.ValidationError if needed

            return self.cleaned_data

Custom frequency lists
======================
zxcvbn-python provides a feature to add custom frequency lists, you can specify your
own custom frequency lists in the validator by adding frequency_lists to AUTH_PASSWORD_VALIDATORS, where dutch_words
is a list of strings:

.. code:: python

    # settings.py

    AUTH_PASSWORD_VALIDATORS = [
        ...
        {
            'NAME': 'zxcvbn_password.ZXCVBNValidator',
            'OPTIONS': {
                'frequency_lists': {
                    'dutch': dutch_words,
                }
            }
        }
    ]


Screen-shot
===========

.. image:: https://cloud.githubusercontent.com/assets/3999221/23079032/5ae1513a-f54b-11e6-9d66-90660ad5fb2d.png


.. important::

    The password field's widget declares two JavaScript files that must be added to the HTML page.
    To do so, add ``{{ form.media }}`` in your template, something like:

    .. code:: html

        <form role="form" action="my_url" method="post">
          {% csrf_token %}
          {{ form }}
        </form>

        {% block js %}
          {{ block.super }}
          {{ form.media }}
        {% endblock %}


.. note::

    If you are not using Bootstrap, the strength bar will not have colors.
    You can fix this with these three CSS rules:

    .. code:: css

        .progress-bar-warning {
            background-color: yellow;
        }

        .progress-bar-danger {
            background-color: red;
        }

        .progress-bar-success {
            background-color: green;
        }


Documentation
=============

`On ReadTheDocs`_

.. _`On ReadTheDocs`: http://django-zxcvbn-password.readthedocs.io/

Development
===========

To run all the tests: ``tox``

Similar projects
================

You should check out `django-zxcvbn-password-validator`_
for backend validation only, but with a good UX  and translated messages.

.. _django-zxcvbn-password-validator: https://github.com/Pierre-Sassoulas/django-zxcvbn-password-validator

=========
Changelog
=========

2.1.1 (2021-12-16)
==================

- Avoid using deprecated ugettext (PR #143).

2.1.0 (2019-12-15)
==================

- Allow specifying frequency lists in ``ZXCVBNValidator`` options (baa47cd).
- Return warnings as validationErrors, create list of warning/suggestion to return as ValidationError(s), fixing translations (12946bb).

2.0.3 (2019-02-21)
==================

- Use new location for package ``python-zxcvbn``, now ``zxcvbn`` (2ea1b69).


2.0.2 (2018-08-21)
==================

Documented
----------
- Improve usage notes (7a1ed42). Related issues/PRs: #31.

Fixed
-----
- Fix call to super in PasswordConfirmationInput (fc551b8).
- Improve password validator help text (c5d21a1). Related issues/PRs: #46.
- Strength bar color go green only when superior to min score (9a44fd8). Related issues/PRs: #3.

Tests
-----
- Add django 1.11 tests (815aaef).
- Add py37/pypy plus django 2.0 tests, remove py34 tests (05711cd).

2.0.1 (2017-02-17)
==================

* Fix call to super in PasswordStrengthInput.

2.0.0 (2017-02-17)
==================

* Drop Django 1.8 support in favor of AUTH_PASSWORD_VALIDATORS setting
  introduced in Django 1.9.
* Update zxcvbn to more recent version (dwolfhub/zxcvbn-python on GitHub).
* Update JavaScript code to latest version.
* Remove all settings (they now go in AUTH_PASSWORD_VALIDATOR options).
* Change license to ISC.

Thanks to Nick Stefan and Daniel Wolf.

1.1.0 (2016-10-18)
==================

* Cookiecutterize the project.

1.0.5 (2015-03-31)
==================

* I don't remember.

1.0.3 (2015-03-12)
==================

* Switch README to rst.
* Fix manifest rules.

1.0.2 (2015-03-12)
==================

* Change package name from django_zxcvbn_password to zxcvbn_password.

1.0.0 (2015-02-21)
==================

* Beta release on PyPI.

0.1.0 (2015-02-01)
==================

* Alpha release on PyPI.


