paperap.models.user.queryset module

Provide query interfaces for Paperless-NGX user and group resources.

This module contains specialized querysets for interacting with users and groups in a Paperless-NGX instance. It extends the base queryset functionality with user and group-specific filtering methods to enable efficient and expressive queries against the Paperless-NGX API.

class paperap.models.user.queryset.UserQuerySet(resource, filters=None, _cache=None, _fetch_all=False, _next_url=None, _last_response=None, _iter=None, _urls_fetched=None)[source]

Bases: StandardQuerySet[User]

Provide a lazy-loaded, chainable query interface for Paperless-NGX users.

Extends StandardQuerySet to provide user-specific filtering methods, allowing for efficient querying of user resources from the Paperless-NGX API. Supports filtering by username, email, name, permissions, and various user status flags.

All query methods return a new queryset instance, allowing for method chaining to build complex queries that are only executed when the results are accessed.

Examples

Find active staff users:
>>> staff_users = client.users.filter().staff().active()
Find users with a specific permission:
>>> admin_users = client.users.filter().has_permission("admin")
Find users by email domain:
>>> company_users = client.users.filter().email("@company.com", exact=False)
Parameters:
  • resource (BaseResource[_Model, Self])

  • filters (dict[str, Any] | None)

  • _cache (list[_Model] | None)

  • _fetch_all (bool)

  • _next_url (str | None)

  • _last_response (ClientResponse)

  • _iter (Iterator[_Model] | None)

  • _urls_fetched (list[str] | None)

username(value, *, exact=True, case_insensitive=True)[source]

Filter users by username.

Parameters:
  • value (str) – The username to filter by.

  • exact (bool) – If True, match the exact username; if False, use contains matching.

  • case_insensitive (bool) – If True, ignore case when matching.

Return type:

Self

Returns:

A filtered UserQuerySet containing only users matching the username criteria.

Examples

Find user with exact username:
>>> user = client.users.filter().username("admin")
Find users with ‘admin’ in their username:
>>> admin_users = client.users.filter().username("admin", exact=False)
email(value, *, exact=True, case_insensitive=True)[source]

Filter users by email address.

Parameters:
  • value (str) – The email address to filter by.

  • exact (bool) – If True, match the exact email; if False, use contains matching.

  • case_insensitive (bool) – If True, ignore case when matching.

Return type:

Self

Returns:

A filtered UserQuerySet containing only users matching the email criteria.

Examples

Find users with a specific domain:
>>> gmail_users = client.users.filter().email("@gmail.com", exact=False)
first_name(value, *, exact=True, case_insensitive=True)[source]

Filter users by first name.

Parameters:
  • value (str) – The first name to filter by.

  • exact (bool) – If True, match the exact first name; if False, use contains matching.

  • case_insensitive (bool) – If True, ignore case when matching.

Return type:

Self

Returns:

A filtered UserQuerySet containing only users matching the first name criteria.

last_name(value, *, exact=True, case_insensitive=True)[source]

Filter users by last name.

Parameters:
  • value (str) – The last name to filter by.

  • exact (bool) – If True, match the exact last name; if False, use contains matching.

  • case_insensitive (bool) – If True, ignore case when matching.

Return type:

Self

Returns:

A filtered UserQuerySet containing only users matching the last name criteria.

staff(value=True)[source]

Filter users by staff status.

Staff users typically have additional permissions in Paperless-NGX.

Parameters:

value (bool) – If True, return users that are staff members; if False, return non-staff users.

Return type:

Self

Returns:

A filtered UserQuerySet containing only users matching the staff status.

Examples

Get all staff users:
>>> staff = client.users.filter().staff()
Get all non-staff users:
>>> regular_users = client.users.filter().staff(False)
active(value=True)[source]

Filter users by active status.

Inactive users cannot log in to Paperless-NGX.

Parameters:

value (bool) – If True, return active users; if False, return inactive users.

Return type:

Self

Returns:

A filtered UserQuerySet containing only users matching the active status.

Examples

Get only active users:
>>> active_users = client.users.filter().active()
Get inactive users:
>>> inactive_users = client.users.filter().active(False)
superuser(value=True)[source]

Filter users by superuser status.

Superusers have all permissions in Paperless-NGX regardless of their assigned permissions or groups.

Parameters:

value (bool) – If True, return superusers; if False, return non-superusers.

Return type:

Self

Returns:

A filtered UserQuerySet containing only users matching the superuser status.

Examples

Get only superusers:
>>> admins = client.users.filter().superuser()
Get non-superusers:
>>> regular_users = client.users.filter().superuser(False)
in_group(value)[source]

Filter users by group membership.

Parameters:

value (int) – The group ID to filter by.

Return type:

Self

Returns:

A filtered UserQuerySet containing only users who are members of the specified group.

Examples

Find all users in the ‘Accounting’ group (ID: 5):
>>> accounting_users = client.users.filter().in_group(5)
has_permission(value)[source]

Filter users by direct permission assignment.

Filter users who have been directly assigned the specified permission through their groups. Does not include permissions inherited from other sources.

Parameters:

value (str) – The permission string to filter by (e.g., “documents.view_document”).

Return type:

Self

Returns:

A filtered UserQuerySet containing only users with the specified permission.

Examples

Find users who can view documents:
>>> viewers = client.users.filter().has_permission("documents.view_document")
has_inherited_permission(value)[source]

Filter users by inherited permission.

Filter users who have the specified permission through any means, including direct assignment, group membership, or superuser status.

Parameters:

value (str) – The permission string to filter by (e.g., “documents.view_document”).

Return type:

Self

Returns:

A filtered UserQuerySet containing only users with the specified inherited permission.

Examples

Find users who can add documents:
>>> can_add = client.users.filter().has_inherited_permission("documents.add_document")
class paperap.models.user.queryset.GroupQuerySet(resource, filters=None, _cache=None, _fetch_all=False, _next_url=None, _last_response=None, _iter=None, _urls_fetched=None)[source]

Bases: StandardQuerySet[Group]

Provide a lazy-loaded, chainable query interface for Paperless-NGX user groups.

Extends StandardQuerySet to provide group-specific filtering methods, allowing for efficient querying of group resources from the Paperless-NGX API. Supports filtering by name and permissions.

All query methods return a new queryset instance, allowing for method chaining to build complex queries that are only executed when the results are accessed.

Examples

Find groups with a specific permission:
>>> admin_groups = client.groups.filter().has_permission("admin.add_user")
Find groups by name:
>>> finance_groups = client.groups.filter().name("finance", exact=False)
Parameters:
  • resource (BaseResource[_Model, Self])

  • filters (dict[str, Any] | None)

  • _cache (list[_Model] | None)

  • _fetch_all (bool)

  • _next_url (str | None)

  • _last_response (ClientResponse)

  • _iter (Iterator[_Model] | None)

  • _urls_fetched (list[str] | None)

name(value, *, exact=True, case_insensitive=True)[source]

Filter groups by name.

Parameters:
  • value (str) – The name to filter by.

  • exact (bool) – If True, match the exact name; if False, use contains matching.

  • case_insensitive (bool) – If True, ignore case when matching.

Return type:

Self

Returns:

A filtered GroupQuerySet containing only groups matching the name criteria.

Examples

Find the ‘Administrators’ group:
>>> admin_group = client.groups.filter().name("Administrators")
Find all groups with ‘admin’ in their name:
>>> admin_groups = client.groups.filter().name("admin", exact=False)
has_permission(value)[source]

Filter groups by assigned permission.

Parameters:

value (str) – The permission string to filter by (e.g., “documents.view_document”).

Return type:

Self

Returns:

A filtered GroupQuerySet containing only groups with the specified permission.

Examples

Find groups that can delete documents:
>>> delete_groups = client.groups.filter().has_permission("documents.delete_document")