Django Passwords 技术文档

1. 安装指南

1.1 使用 pip 安装

你可以通过以下命令使用 pip 安装 django-passwords：

pip install django-passwords

1.2 使用 easy_install 安装

你也可以通过以下命令使用 easy_install 安装 django-passwords：

easy_install django-passwords

1.3 手动安装

如果你选择手动安装，可以下载 django-passwords 的压缩包，然后运行以下命令：

python setup.py install

2. 项目的使用说明

2.1 兼容性

django-passwords 兼容 Django 1.3 到 1.9 RC1 版本，并且支持 Python 2.7 和 3.4。

2.2 配置设置

django-passwords 提供了 6 个可选的配置项，你可以在 Django 项目的 settings.py 文件中进行配置：

# 密码最小长度
PASSWORD_MIN_LENGTH = 6  # 默认值为 6

# 密码最大长度
PASSWORD_MAX_LENGTH = 120  # 默认值为 None

# 字典文件路径
PASSWORD_DICTIONARY = "/usr/share/dict/words"  # 默认值为 None

# 模糊匹配阈值
PASSWORD_MATCH_THRESHOLD = 0.9  # 默认值为 0.9，范围为 0.0 - 1.0，1.0 表示完全匹配

# 常见序列列表
PASSWORD_COMMON_SEQUENCES = []  # 应为字符串列表，默认值见 passwords/validators.py

# 密码复杂度要求
PASSWORD_COMPLEXITY = {
    "UPPER": 1,  # 大写字母
    "LOWER": 1,  # 小写字母
    "LETTERS": 1,  # 大写或小写字母
    "DIGITS": 1,  # 数字
    "SPECIAL": 1,  # 非字母数字、空格或标点符号的字符
    "WORDS": 1  # 单词（由空格或标点符号分隔的字母数字序列）
}

3. 项目 API 使用文档

3.1 使用 PasswordField

你可以在 Django 的表单中使用 PasswordField 来验证密码强度：

from django import forms
from passwords.fields import PasswordField

class ExampleForm(forms.Form):
    password = PasswordField(label="密码")

3.2 使用自定义验证器

你可以使用 django-passwords 提供的验证器来验证自定义字段：

from django import forms
from passwords.validators import dictionary_words

field = forms.CharField(validators=[dictionary_words])

3.3 创建自定义验证器实例

你可以创建自定义的验证器实例，以便为特定字段指定配置，而不是使用全局配置：

from django import forms
from passwords.validators import (
    DictionaryValidator, LengthValidator, ComplexityValidator)

field = forms.CharField(validators=[
    DictionaryValidator(words=['banned_word'], threshold=0.9),
    LengthValidator(min_length=8),
    ComplexityValidator(complexities=dict(
        UPPER=1,
        LOWER=1,
        DIGITS=1
    )),
])

3.4 使用 Django 的密码验证 API

django-passwords 还提供了与 Django 密码验证 API 兼容的包装器：

AUTH_PASSWORD_VALIDATORS = [
    …,
    {"NAME": "passwords.auth_password_validators.ComplexityValidator"}
]

4. 项目安装方式

4.1 使用 pip 安装

pip install django-passwords

4.2 使用 easy_install 安装

easy_install django-passwords

4.3 手动安装

下载 django-passwords 的压缩包，然后运行以下命令：

python setup.py install

通过以上内容，你可以详细了解 django-passwords 的安装、配置和使用方法。希望这篇文档能帮助你更好地使用该项目。