django.contrib.auth

字段

class models.User

User 对象有如下字段：

username

必要的。150 个字符或以下。用户名可包含字母数字、_、@、+、. 和 - 字符。

max_length 对许多使用情况来说应该是足够的。如果你需要更长的长度，请使用 自定义用户模型。如果你使用的 MySQL 是 utf8mb4 编码（推荐用于适当的 Unicode 支持），最多指定 max_length=191，因为在这种情况下，MySQL 默认只能创建 191 个字符的唯一索引。

first_name

可选的（blank=True）。150 个字符或更少。

last_name

可选的（blank=True）。150 个字符或更少。

email

可选的（blank=True）。电子邮件地址。

password

需要。一个密码的哈希值和元数据。（Django 不存储原始密码。）原始密码可以任意长，可以包含任何字符。参见 密码文档。

groups

多对多关系到 Group

user_permissions

多对多关系到 Permission

is_staff

布尔型。指定该用户是否可以访问管理站点。

is_active

布尔值。指定该用户账户是否应该被视为活跃账户。我们建议你把这个标志设置为 False，而不是删除账户；这样，如果你的应用程序对用户有任何外键，外键就不会被破坏。

这不一定能控制用户是否能登录。认证后端不一定需要检查 is_active 标志，但默认的后端（ModelBackend）和 RemoteUserBackend 会检查。如果你想允许不活跃的用户登录，你可以使用 AllowAllUsersModelBackend 或者 AllowAllUsersRemoteUserBackend。在这种情况下，你还需要自定义 AuthenticationForm 所使用的 LoginView，因为它拒绝非活动用户。需要注意的是， has_perm() 等权限检查方法，以及 Django 管理中的认证方法，都会对非活跃用户返回 False。

is_superuser

布尔值。指定该用户拥有所有权限，而不用一个个开启权限。

last_login

用户最后一次登录的日期时间。

date_joined

指定账户创建时间的日期时间。帐户创建时，默认设置为当前日期／时间。

属性

class models.User

is_authenticated

只读属性，始终返回 True （匿名用户 AnonymousUser.is_authenticated 始终返回 False ）。这是一种判断用户是否已通过身份认证的方法。这并不意味着任何权限，也不会检查用户是否处于活动状态或是否具有有效会话。即使通常你会根据 request.user 检查这个属性，以确定它是否被 AuthenticationMiddleware 填充（表示当前登录的用户），但是你应该知道该属性对于任何 User 实例都返回 True。

is_anonymous

只读属性，总是 False。这是区分 User 和 AnonymousUser 对象的一种方式。一般来说，你应该优先使用 is_authenticated 来代替这个属性。

方法

class models.User

get_username()

返回用户的用户名。由于 User 模型可以被替换，你应该使用这个方法而不是直接引用用户名属性。

get_full_name()

返回 first_name 加上 last_name，中间有一个空格。

get_short_name()

返回 first_name。

set_password(raw_password)

将用户的密码设置为给定的原始字符串，并进行密码哈希处理。不保存 User 对象。

当 raw_password 为 None 时，密码将被设置为不可用的密码，就像 set_unusable_password() 一样。

check_password(raw_password)

如果给定的原始字符串是用户的正确密码，返回 True。（密码哈希值用于比较）

set_unusable_password()

标记该用户没有设置密码。 check_password() 对这个用户的检查永远不会返回 True。不会保存 User 对象。

如果针对现有外部源（例如 LDAP 目录）进行应用程序的身份认证，则可能需要这个功能。

has_usable_password()

如果 set_unusable_password() 被调用，返回 False。

get_user_permissions(obj=None)

返回用户直接拥有的一组权限字符串。

如果传入了 obj，则只返回这个特定对象的用户权限。

get_group_permissions(obj=None)

返回用户通过他们的组拥有的一组权限字符串。

如果传入了 obj，则只返回这个特定对象的组权限。

get_all_permissions(obj=None)

返回用户拥有的一组权限字符串，包括通过组和用户的权限。

如果传入了 obj，则只返回这个特定对象的权限。

has_perm(perm, obj=None)

如果用户拥有指定的权限，返回 True，其中 perm 的格式是 "<app label>.<permission codename>"。（参见 权限 的文档）。如果用户是不活跃的，这个方法将总是返回 False。对于活跃的超级用户，本方法将始终返回 True。

如果传入了 obj，这个方法不会检查模型的权限，而是检查这个特定对象的权限。

has_perms(perm_list, obj=None)

如果用户拥有指定的每个权限，返回 True，其中每个 perm 的格式为 "<app label>.<permission codename>"。如果用户不活跃，本方法将总是返回 False。对于活跃的超级用户，本方法将始终返回 True。

如果传入了 obj，这个方法不会检查模型的权限，而是检查这个特定对象的权限。

has_module_perms(package_name)

如果用户在给定的包（Django 应用标签）中有任何权限，则返回 True。如果用户不活跃，本方法将总是返回 False。如果是活跃的超级用户，本方法将始终返回 True。

email_user(subject, message, from_email=None, **kwargs)

向用户发送邮件。如果 from_email 是 None，Django 使用 DEFAULT_FROM_EMAIL。任何 **kwargs 都会传递给底层的 send_mail() 调用。

管理器方法

class models.UserManager

User 模型有一个自定义管理器，它有以下辅助方法（除了 BaseUserManager 提供的方法外）：

create_user(username, email=None, password=None, **extra_fields)

创建、保存并返回一个 User。

username 和 password 按给定设置。email 的域名部分会自动转换为小写，返回的 User 对象的 is_active 设置为 True。

如果没有提供密码， set_unusable_password() 将被调用。

extra_fields 关键字参数被传递到 User 的 __init__ 方法中，允许在 自定义用户模型 上设置任意字段。

使用方法参见 创建用户。

create_superuser(username, email=None, password=None, **extra_fields)

与 create_user() 相同，但将 is_staff 和 is_superuser 设置为 True。

with_perm(perm, is_active=True, include_superusers=True, backend=None, obj=None)

返回拥有给定权限 perm 的用户，可以是 "<app label>.<permission codename>" 格式，也可以是 Permission 实例。如果没有找到拥有 perm 的用户，返回一个空的查询集。

如果 is_active 为 True （默认），则只返回活跃用户，如果 False，则只返回非活跃用户。使用 None 返回所有用户，无论其是否处于活跃状态。

如果 include_superusers 为 True （默认），结果将包括超级用户。

如果传入了 backend，并且在 AUTHENTICATION_BACKENDS 中定义了，那么本方法将使用它。否则，它将使用 AUTHENTICATION_BACKENDS 中的 backend，如果只有一个的话，或者引发一个异常。

字段

Permission 对象有以下字段：

class models.Permission

name

必要的。255 个字符或以下。例如：'Can vote'。

content_type

必要的。对 django_content_type 数据库表的引用，该表包含每个已安装模型的记录。

codename

必要的。100 个字符或以下。例如：'can_vote'。

方法

Permission 对象和其他 Django 模型 一样拥有标准的数据访问方法。

字段

Group 对象有以下字段：

class models.Group

name

要求： 150 个字符或以下。允许使用任何字符。例如：'Awesome Users'。

permissions

多对多字段到 Permission：

group.permissions.set([permission_list])
group.permissions.add(permission, permission, ...)
group.permissions.remove(permission, permission, ...)
group.permissions.clear()