"""
Provide query functionality for storage paths in Paperless-ngx.
This module contains the StoragePathQuerySet class, which enables filtering and
querying storage path objects from the Paperless-ngx API. It extends the standard
queryset functionality with storage path-specific filtering methods.
"""
from __future__ import annotations
import logging
from typing import TYPE_CHECKING, Any, Self
from paperap.models.abstract.queryset import BaseQuerySet, StandardQuerySet
from paperap.models.mixins.queryset import HasStandard
if TYPE_CHECKING:
from paperap.models.storage_path.model import StoragePath
logger = logging.getLogger(__name__)
[docs]
class StoragePathQuerySet(StandardQuerySet["StoragePath"], HasStandard):
"""
QuerySet for Paperless-ngx storage paths with specialized filtering methods.
Extends StandardQuerySet to provide storage path-specific filtering
capabilities, including filtering by path value, match criteria, matching algorithm,
and permission settings. This queryset enables efficient querying and filtering
of storage path objects from the Paperless-ngx API.
Examples:
Get all storage paths:
>>> all_paths = client.storage_paths.all()
Filter by path:
>>> tax_paths = client.storage_paths.path("/documents/taxes/")
Filter by matching algorithm:
>>> auto_paths = client.storage_paths.matching_algorithm(1) # 1 = Auto
"""
[docs]
def path(self, value: str, *, exact: bool = True, case_insensitive: bool = True) -> Self:
"""
Filter storage paths by their actual path value.
Args:
value: The path string to filter by.
exact: If True, match the exact path string. If False, match paths
containing the value string. Defaults to True.
case_insensitive: If True, ignore case when matching. Defaults to True.
Returns:
A filtered StoragePathQuerySet containing only matching storage paths.
Examples:
Find exact path match:
>>> tax_paths = client.storage_paths.path("/documents/taxes/")
Find paths containing "invoice" (case insensitive):
>>> invoice_paths = client.storage_paths.path("invoice", exact=False)
"""
return self.filter_field_by_str("path", value, exact=exact, case_insensitive=case_insensitive)
[docs]
def match(self, value: str, *, exact: bool = True) -> Self:
"""
Filter storage paths by their match pattern value.
Filter storage paths based on the match pattern used for automatic
document routing in Paperless-ngx.
Args:
value: The match pattern string to filter by.
exact: If True, match the exact pattern string. If False, match
patterns containing the value string. Defaults to True.
Returns:
A filtered StoragePathQuerySet containing only matching storage paths.
Examples:
Find paths with exact match pattern:
>>> invoice_paths = client.storage_paths.match("invoice")
Find paths with match patterns containing "tax":
>>> tax_paths = client.storage_paths.match("tax", exact=False)
"""
return self.filter_field_by_str("match", value, exact=exact)
[docs]
def matching_algorithm(self, value: int) -> Self:
"""
Filter storage paths by their matching algorithm.
Filter storage paths based on the algorithm used for matching
documents to storage paths in Paperless-ngx.
Args:
value: The matching algorithm ID to filter by. Common values are:
1: Auto (let Paperless decide)
2: Exact (exact string matching)
3: Regular expression
4: Fuzzy match
Returns:
A filtered StoragePathQuerySet containing only storage paths
using the specified matching algorithm.
Examples:
Find paths using regular expressions:
>>> regex_paths = client.storage_paths.matching_algorithm(3)
"""
return self.filter(matching_algorithm=value)
[docs]
def case_insensitive(self, insensitive: bool = True) -> Self:
"""
Filter storage paths by their case sensitivity setting.
Filter storage paths based on whether they use case-insensitive
matching for document routing.
Args:
insensitive: If True, return storage paths configured for
case-insensitive matching. If False, return paths with
case-sensitive matching. Defaults to True.
Returns:
A filtered StoragePathQuerySet containing only storage paths
with the specified case sensitivity setting.
Examples:
Find case-insensitive paths:
>>> insensitive_paths = client.storage_paths.case_insensitive()
Find case-sensitive paths:
>>> sensitive_paths = client.storage_paths.case_insensitive(False)
"""
return self.filter(is_insensitive=insensitive)
[docs]
def user_can_change(self, can_change: bool = True) -> Self:
"""
Filter storage paths by user modification permissions.
Filter storage paths based on whether the current user has
permission to modify them in the Paperless-ngx system.
Args:
can_change: If True, return storage paths that the current user
can modify. If False, return paths that the user cannot modify.
Defaults to True.
Returns:
A filtered StoragePathQuerySet containing only storage paths
with the specified permission setting.
Examples:
Find paths the current user can modify:
>>> editable_paths = client.storage_paths.user_can_change()
Find paths the current user cannot modify:
>>> readonly_paths = client.storage_paths.user_can_change(False)
"""
return self.filter(user_can_change=can_change)