"""
Provide specialized querysets for interacting with Paperless-NGX workflow resources.
This module contains queryset implementations for workflows, workflow actions, and
workflow triggers. Each queryset extends the standard queryset functionality with
specialized filtering methods specific to workflow-related resources.
"""
from __future__ import annotations
import logging
from typing import TYPE_CHECKING, Any, Self
from paperap.models.abstract.queryset import BaseQuerySet, StandardQuerySet
if TYPE_CHECKING:
from paperap.models.workflow.model import Workflow, WorkflowAction, WorkflowTrigger
logger = logging.getLogger(__name__)
[docs]
class WorkflowQuerySet(StandardQuerySet["Workflow"]):
"""
Specialized queryset for interacting with Paperless-NGX workflows.
Extends StandardQuerySet to provide workflow-specific filtering methods,
making it easier to query workflows by attributes such as name, order,
and enabled status. The queryset is lazy-loaded, meaning API requests
are only made when data is actually needed.
Examples:
Get all enabled workflows:
>>> enabled_workflows = client.workflows.filter(enabled=True)
>>> # Or using the specialized method
>>> enabled_workflows = client.workflows.enabled()
Filter workflows by name:
>>> tax_workflows = client.workflows.name("tax")
"""
[docs]
def name(self, value: str, *, exact: bool = True, case_insensitive: bool = True) -> Self:
"""
Filter workflows by name.
Args:
value: The workflow name to filter by.
exact: If True, match the exact name; if False, use contains matching.
case_insensitive: If True, ignore case when matching.
Returns:
A filtered WorkflowQuerySet containing matching workflows.
Examples:
Find workflows with exact name:
>>> invoice_workflows = client.workflows.name("Invoice Processing")
Find workflows containing a string (case-insensitive):
>>> invoice_workflows = client.workflows.name("invoice", exact=False)
"""
return self.filter_field_by_str("name", value, exact=exact, case_insensitive=case_insensitive)
[docs]
def order(self, value: int) -> Self:
"""
Filter workflows by their execution order.
Paperless-NGX workflows have an order value that determines their
execution sequence. This method finds workflows with a specific order value.
Args:
value: The order value to filter by.
Returns:
A filtered WorkflowQuerySet containing workflows with the specified order.
"""
return self.filter(order=value)
[docs]
def enabled(self, value: bool = True) -> Self:
"""
Filter workflows by their enabled status.
Args:
value: If True, return only enabled workflows; if False, return only disabled workflows.
Returns:
A filtered WorkflowQuerySet containing workflows with the specified enabled status.
Examples:
Get all enabled workflows:
>>> active_workflows = client.workflows.enabled()
Get all disabled workflows:
>>> inactive_workflows = client.workflows.enabled(False)
"""
return self.filter(enabled=value)
[docs]
class WorkflowActionQuerySet(StandardQuerySet["WorkflowAction"]):
"""
Specialized queryset for interacting with Paperless-NGX workflow actions.
Extends StandardQuerySet to provide workflow action-specific filtering methods,
making it easier to query actions by attributes such as type and assigned metadata.
Workflow actions define what happens when a workflow is triggered, such as
assigning tags, correspondents, or document types to documents.
Examples:
Get actions that assign a specific tag:
>>> tag_actions = client.workflow_actions.assign_tags(5)
Find actions that set a specific title:
>>> title_actions = client.workflow_actions.assign_title("Invoice")
"""
[docs]
def type(self, value: str, *, exact: bool = True, case_insensitive: bool = True) -> Self:
"""
Filter workflow actions by their type.
Workflow actions in Paperless-NGX have different types that determine
what they do (e.g., assign metadata, move document, etc.).
Args:
value: The action type to filter by.
exact: If True, match the exact type; if False, use contains matching.
case_insensitive: If True, ignore case when matching.
Returns:
A filtered WorkflowActionQuerySet containing actions of the specified type.
Examples:
Find all actions that assign metadata:
>>> assign_actions = client.workflow_actions.type("assign")
"""
return self.filter_field_by_str("type", value, exact=exact, case_insensitive=case_insensitive)
[docs]
def assign_title(self, value: str, *, exact: bool = True, case_insensitive: bool = True) -> Self:
"""
Filter workflow actions by the title they assign to documents.
Find workflow actions that set a specific document title when triggered.
Args:
value: The title text to filter by.
exact: If True, match the exact title; if False, use contains matching.
case_insensitive: If True, ignore case when matching.
Returns:
A filtered WorkflowActionQuerySet containing actions that assign the specified title.
Examples:
Find actions that set titles containing "Invoice":
>>> invoice_actions = client.workflow_actions.assign_title("Invoice", exact=False)
"""
return self.filter_field_by_str("assign_title", value, exact=exact, case_insensitive=case_insensitive)
[docs]
def assign_correspondent(self, value: int) -> Self:
"""
Filter workflow actions by the correspondent they assign to documents.
Find workflow actions that assign a specific correspondent to documents when triggered.
Args:
value: The correspondent ID to filter by.
Returns:
A filtered WorkflowActionQuerySet containing actions that assign the specified correspondent.
Examples:
Find actions that assign a specific correspondent:
>>> vendor_actions = client.workflow_actions.assign_correspondent(3)
"""
return self.filter(assign_correspondent=value)
[docs]
def assign_document_type(self, value: int) -> Self:
"""
Filter workflow actions by the document type they assign.
Find workflow actions that assign a specific document type to documents when triggered.
Args:
value: The document type ID to filter by.
Returns:
A filtered WorkflowActionQuerySet containing actions that assign the specified document type.
Examples:
Find actions that assign a specific document type:
>>> invoice_type_actions = client.workflow_actions.assign_document_type(2)
"""
return self.filter(assign_document_type=value)
[docs]
def assign_storage_path(self, value: int) -> Self:
"""
Filter workflow actions by the storage path they assign to documents.
Find workflow actions that assign a specific storage path to documents when triggered.
Args:
value: The storage path ID to filter by.
Returns:
A filtered WorkflowActionQuerySet containing actions that assign the specified storage path.
Examples:
Find actions that assign a specific storage path:
>>> tax_path_actions = client.workflow_actions.assign_storage_path(4)
"""
return self.filter(assign_storage_path=value)
[docs]
def assign_owner(self, value: int) -> Self:
"""
Filter workflow actions by the owner they assign to documents.
Find workflow actions that assign a specific owner (user) to documents when triggered.
Args:
value: The owner (user) ID to filter by.
Returns:
A filtered WorkflowActionQuerySet containing actions that assign the specified owner.
Examples:
Find actions that assign documents to a specific user:
>>> admin_actions = client.workflow_actions.assign_owner(1)
"""
return self.filter(assign_owner=value)
[docs]
class WorkflowTriggerQuerySet(StandardQuerySet["WorkflowTrigger"]):
"""
Specialized queryset for interacting with Paperless-NGX workflow triggers.
Extends StandardQuerySet to provide workflow trigger-specific filtering methods,
making it easier to query triggers by attributes such as type and filter conditions.
Workflow triggers define when a workflow should be executed, such as when a document
is added with specific attributes or matches certain criteria.
Examples:
Get all triggers of a specific type:
>>> consumption_triggers = client.workflow_triggers.type(1) # Type 1 might be "document added"
Find triggers that look for specific tags:
>>> tax_triggers = client.workflow_triggers.has_tags(5) # Tag ID 5 might be "Tax"
"""
[docs]
def type(self, value: int) -> Self:
"""
Filter workflow triggers by their type.
Workflow triggers in Paperless-NGX have different types that determine
when they activate (e.g., document added, document consumed, etc.).
Args:
value: The trigger type ID to filter by.
Returns:
A filtered WorkflowTriggerQuerySet containing triggers of the specified type.
Examples:
Find all triggers that activate when documents are consumed:
>>> consumption_triggers = client.workflow_triggers.type(1) # Assuming 1 is consumption type
"""
return self.filter(type=value)
[docs]
def filter_path(self, value: str, *, exact: bool = True, case_insensitive: bool = True) -> Self:
"""
Filter workflow triggers by their path filter condition.
Find workflow triggers that activate based on a document's source path
matching specific criteria.
Args:
value: The path filter text to match.
exact: If True, match the exact path; if False, use contains matching.
case_insensitive: If True, ignore case when matching.
Returns:
A filtered WorkflowTriggerQuerySet containing triggers with the specified path filter.
Examples:
Find triggers that look for documents from a specific directory:
>>> inbox_triggers = client.workflow_triggers.filter_path("/inbox/")
Find triggers that look for documents from any path containing a string:
>>> invoice_triggers = client.workflow_triggers.filter_path("invoices", exact=False)
"""
return self.filter_field_by_str("filter_path", value, exact=exact, case_insensitive=case_insensitive)
[docs]
def filter_filename(self, value: str, *, exact: bool = True, case_insensitive: bool = True) -> Self:
"""
Filter workflow triggers by their filename filter condition.
Find workflow triggers that activate based on a document's original
filename matching specific criteria.
Args:
value: The filename filter text to match.
exact: If True, match the exact filename; if False, use contains matching.
case_insensitive: If True, ignore case when matching.
Returns:
A filtered WorkflowTriggerQuerySet containing triggers with the specified filename filter.
Examples:
Find triggers that look for documents with specific text in filenames:
>>> invoice_triggers = client.workflow_triggers.filter_filename("invoice", exact=False)
Find triggers that look for specific file types:
>>> pdf_triggers = client.workflow_triggers.filter_filename(".pdf", exact=False)
"""
return self.filter_field_by_str("filter_filename", value, exact=exact, case_insensitive=case_insensitive)
[docs]
def filter_mailrule(self, value: str, *, exact: bool = True, case_insensitive: bool = True) -> Self:
"""
Filter workflow triggers by their mail rule filter condition.
Find workflow triggers that activate based on a document's associated
mail rule matching specific criteria.
Args:
value: The mail rule filter text to match.
exact: If True, match the exact mail rule; if False, use contains matching.
case_insensitive: If True, ignore case when matching.
Returns:
A filtered WorkflowTriggerQuerySet containing triggers with the specified mail rule filter.
Examples:
Find triggers that look for documents from a specific mail rule:
>>> vendor_mail_triggers = client.workflow_triggers.filter_mailrule("vendor@example.com")
Find triggers that look for documents from mail rules containing specific text:
>>> invoice_mail_triggers = client.workflow_triggers.filter_mailrule("invoice", exact=False)
"""
return self.filter_field_by_str("filter_mailrule", value, exact=exact, case_insensitive=case_insensitive)
[docs]
def has_correspondent(self, value: int) -> Self:
"""
Filter workflow triggers by their correspondent filter condition.
Find workflow triggers that activate based on a document having a specific correspondent.
Args:
value: The correspondent ID to filter by.
Returns:
A filtered WorkflowTriggerQuerySet containing triggers with the specified correspondent filter.
Examples:
Find triggers that look for documents from a specific correspondent:
>>> vendor_triggers = client.workflow_triggers.has_correspondent(3)
"""
return self.filter(filter_has_correspondent=value)
[docs]
def has_document_type(self, value: int) -> Self:
"""
Filter workflow triggers by their document type filter condition.
Find workflow triggers that activate based on a document having a specific document type.
Args:
value: The document type ID to filter by.
Returns:
A filtered WorkflowTriggerQuerySet containing triggers with the specified document type filter.
Examples:
Find triggers that look for documents of a specific type:
>>> invoice_triggers = client.workflow_triggers.has_document_type(2)
"""
return self.filter(filter_has_document_type=value)