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:
- 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:
- 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:
- 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:
- 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:
- 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")