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:
  • value (str) – The task_file_name to filter by.

  • exact (bool) – If True, match the exact task_file_name, otherwise use contains. Defaults to True.

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

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:
  • value (str) – The task type to filter by.

  • exact (bool) – If True, match the exact type, otherwise use contains. Defaults to True.

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

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:
  • value (str) – The status to filter by.

  • exact (bool) – If True, match the exact status, otherwise use contains. Defaults to True.

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

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:
  • value (str | None) – The result to filter by. Pass None to find tasks with no result.

  • exact (bool) – If True, match the exact result, otherwise use contains. Defaults to True.

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

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)
related_document(value)[source]

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])