paperap.models.task.queryset module
Provide query interface for Paperless-NGX tasks.
This module implements the TaskQuerySet class, which extends StandardQuerySet to provide specialized filtering methods for Paperless-NGX tasks. It enables efficient querying of the task API endpoint with task-specific filters.
- class paperap.models.task.queryset.TaskQuerySet(resource, filters=None, _cache=None, _fetch_all=False, _next_url=None, _last_response=None, _iter=None, _urls_fetched=None)[source]
Bases:
StandardQuerySet
[Task]Provide a lazy-loaded, chainable query interface for Paperless-NGX tasks.
Extends StandardQuerySet to provide specialized filtering methods for task-specific attributes like task_id, status, and result. Enables efficient querying of the Paperless-NGX task API endpoint.
The queryset is lazy-loaded, meaning API requests are only made when data is actually needed (when iterating, slicing, or calling terminal methods like count() or get()).
Examples
- Get all tasks:
>>> all_tasks = client.tasks.all()
- Get a specific task by ID:
>>> task = client.tasks.get(123)
- Filter tasks by status:
>>> pending = client.tasks.all().status("PENDING")
- Chain filters:
>>> document_tasks = client.tasks.all().type("document").status("SUCCESS")
- 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)
- task_id(value)[source]
Filter tasks by task_id.
- Parameters:
value (
int
) – The task_id to filter by.- Return type:
Self
- Returns:
A filtered queryset containing only tasks with the specified task_id.
Examples
- Get task with specific task_id:
>>> task = client.tasks.all().task_id(12345).first()
- task_file_name(value, *, exact=True, case_insensitive=True)[source]
Filter tasks by task_file_name.
- Parameters:
- Return type:
Self
- Returns:
A filtered queryset containing only tasks with the matching task_file_name.
Examples
- Exact match, case insensitive (default):
>>> pdf_tasks = client.tasks.all().task_file_name("document.pdf")
- Contains match, case sensitive:
>>> pdf_tasks = client.tasks.all().task_file_name("pdf", exact=False, case_insensitive=False)
- date_done(value)[source]
Filter tasks by completion date.
- Parameters:
value (
str
|None
) – The date_done to filter by, in ISO format (YYYY-MM-DDTHH:MM:SS.sssZ). Pass None to find tasks that haven’t completed.- Return type:
Self
- Returns:
A filtered queryset containing only tasks with the matching completion date.
Examples
- Tasks completed on a specific date:
>>> completed = client.tasks.all().date_done("2023-04-15T00:00:00Z")
- Tasks that haven’t completed yet:
>>> pending = client.tasks.all().date_done(None)
- type(value, *, exact=True, case_insensitive=True)[source]
Filter tasks by type.
Task types typically include ‘document’, ‘mail’, ‘consumption’, etc.
- Parameters:
- Return type:
Self
- Returns:
A filtered queryset containing only tasks with the matching type.
Examples
- Get all document processing tasks:
>>> doc_tasks = client.tasks.all().type("document")
- Get all mail-related tasks (contains match):
>>> mail_tasks = client.tasks.all().type("mail", exact=False)
- status(value, *, exact=True, case_insensitive=True)[source]
Filter tasks by status.
Common status values include ‘PENDING’, ‘STARTED’, ‘SUCCESS’, ‘FAILURE’, ‘RETRY’, etc.
- Parameters:
- Return type:
Self
- Returns:
A filtered queryset containing only tasks with the matching status.
Examples
- Get all successful tasks:
>>> successful = client.tasks.all().status("SUCCESS")
- Get all failed tasks:
>>> failed = client.tasks.all().status("FAILURE")
- Get all in-progress tasks:
>>> in_progress = client.tasks.all().status("STARTED")
- result(value, *, exact=True, case_insensitive=True)[source]
Filter tasks by result.
The result field typically contains the output of the task, which may be a document ID, error message, or other task-specific data.
- Parameters:
- Return type:
Self
- Returns:
A filtered queryset containing only tasks with the matching result.
Examples
- Find tasks with a specific document ID in the result:
>>> doc_tasks = client.tasks.all().result("42")
- Find tasks with no result yet:
>>> no_result = client.tasks.all().result(None)
- Find tasks with error messages:
>>> error_tasks = client.tasks.all().result("error", exact=False)
- acknowledged(value)[source]
Filter tasks by acknowledged status.
Acknowledged tasks are those that have been marked as seen/reviewed by a user. This is particularly useful for filtering out tasks that need attention.
- Parameters:
value (
bool
) – True to get only acknowledged tasks, False to get only unacknowledged tasks.- Return type:
Self
- Returns:
A filtered queryset containing only tasks with the matching acknowledged status.
Examples
- Get all unacknowledged tasks that need attention:
>>> needs_attention = client.tasks.all().acknowledged(False)
- Get all acknowledged tasks:
>>> reviewed = client.tasks.all().acknowledged(True)
Filter tasks by related document ID.
Many tasks in Paperless-NGX are associated with specific documents. This method allows filtering tasks by their related document ID(s).
- Parameters:
value (
int
|list
[int
]) – Either a single document ID or a list of document IDs to filter by.- Return type:
Self
- Returns:
A filtered queryset containing only tasks related to the specified document(s).
Examples
- Get all tasks related to document #42:
>>> doc_tasks = client.tasks.all().related_document(42)
- Get all tasks related to a set of documents:
>>> batch_tasks = client.tasks.all().related_document([42, 43, 44])