paperap.models.user.model module

Define models for interacting with Paperless-NgX users and groups.

Provides the User and Group models that represent users and groups in a Paperless-NgX instance. These models allow for querying, creating, and managing users and their permissions within the system.

The models in this module follow the same pattern as other Paperless-NgX resources, with standard CRUD operations and relationship management.

class paperap.models.user.model.Group(**data)[source]

Bases: StandardModel

Represent a user group in Paperless-NgX.

A group is a collection of users that share the same permissions. Groups are used to simplify permission management by assigning permissions to groups rather than individual users.

name

The name of the group.

Type:

str, optional

permissions

A list of permission strings assigned to this group.

Type:

list[str]

Examples

Get all admin groups:

admin_groups = client.groups().filter(name__icontains="admin")

Create a new group:

new_group = client.groups().create(
    name="Finance",
    permissions=["view_document"]
)
Parameters:

data (Any)

name: str | None
permissions: list[str]
class Meta(model)[source]

Bases: Meta

Parameters:

model (type[_Self])

queryset

alias of GroupQuerySet

blacklist_filtering_params: ClassVar[set[str]] = {}
field_map: dict[str, str] = {}
filtering_disabled: ClassVar[set[str]] = {}
filtering_fields: ClassVar[set[str]] = {'_resource', 'id', 'name', 'permissions'}
read_only_fields: ClassVar[set[str]] = {'id'}
supported_filtering_params: ClassVar[set[str]] = {'id', 'id__in', 'limit'}
model: type[_Self]
name: str
property users: UserQuerySet

Get all users that are members of this group.

Returns a queryset of all users that belong to this group, allowing for further filtering and operations on those users.

Returns:

A queryset containing all users that are members of this group.

Return type:

UserQuerySet

Examples

Get active users in a group:

group = client.groups().get(1)  # Get group with ID 1
active_users = group.users.filter(is_active=True)
print(f"Group {group.name} has {active_users.count()} active users")
model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'ignore', 'populate_by_name': True, 'use_enum_values': True, 'validate_assignment': True, 'validate_default': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context: Any, /) None

We need to both initialize private attributes and call the user-defined model_post_init method.

Parameters:
Return type:

None

id: int
class paperap.models.user.model.User(**data)[source]

Bases: StandardModel

Represent a user in Paperless-NgX.

Models a user account in the Paperless-NgX system, including authentication details, personal information, and permission settings. Users can belong to groups and have both direct and inherited permissions.

username

The user’s login username.

Type:

str, optional

email

The user’s email address.

Type:

str, optional

password

The user’s password (only used when creating new users).

Type:

str, optional

first_name

The user’s first name.

Type:

str, optional

last_name

The user’s last name.

Type:

str, optional

date_joined

ISO 8601 formatted date when the user joined.

Type:

str, optional

is_staff

Whether the user has staff privileges.

Type:

bool, optional

is_active

Whether the user account is active.

Type:

bool, optional

is_superuser

Whether the user has superuser privileges.

Type:

bool, optional

groups

List of group IDs the user belongs to.

Type:

list[int]

user_permissions

List of permission strings directly assigned to the user.

Type:

list[str]

inherited_permissions

List of permission strings inherited from groups.

Type:

list[str]

Examples

Get all active users:

active_users = client.users().filter(is_active=True)

Create a new user:

new_user = client.users().create(
    username="jsmith",
    email="jsmith@example.com",
    password="secure_password",
    first_name="John",
    last_name="Smith",
    is_active=True
)
Parameters:

data (Any)

username: str | None
email: str | None
password: str | None
first_name: str | None
last_name: str | None
date_joined: str | None
is_staff: bool | None
is_active: bool | None
is_superuser: bool | None
groups: list[int]
user_permissions: list[str]
inherited_permissions: list[str]
class Meta(model)[source]

Bases: Meta

Parameters:

model (type[_Self])

queryset

alias of UserQuerySet

blacklist_filtering_params: ClassVar[set[str]] = {}
field_map: dict[str, str] = {}
filtering_disabled: ClassVar[set[str]] = {}
filtering_fields: ClassVar[set[str]] = {'_resource', 'date_joined', 'email', 'first_name', 'groups', 'id', 'inherited_permissions', 'is_active', 'is_staff', 'is_superuser', 'last_name', 'password', 'user_permissions', 'username'}
read_only_fields: ClassVar[set[str]] = {'id'}
supported_filtering_params: ClassVar[set[str]] = {'id', 'id__in', 'limit'}
model: type[_Self]
name: str
get_groups()[source]

Get all groups this user is a member of.

Returns a queryset containing all the groups that this user belongs to, allowing for further filtering and operations on those groups.

Returns:

A queryset containing all groups this user is a member of.

Return type:

GroupQuerySet

Examples

Find admin groups a user belongs to:

user = client.users().get(1)  # Get user with ID 1
admin_groups = user.get_groups().filter(name__icontains="admin")
print(f"User {user.username} belongs to {user.get_groups().count()} groups")
model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'ignore', 'populate_by_name': True, 'use_enum_values': True, 'validate_assignment': True, 'validate_default': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context: Any, /) None

We need to both initialize private attributes and call the user-defined model_post_init method.

Parameters:
Return type:

None

id: int