Source code for paperap.models.correspondent.queryset

"""
Provide queryset functionality for Paperless-ngx correspondents.

This module implements the CorrespondentQuerySet class, which enables
filtering and querying correspondent objects from the Paperless-ngx API.
It extends the standard queryset functionality with correspondent-specific
filtering methods.
"""

from __future__ import annotations

import logging
from typing import TYPE_CHECKING, Any, Self, Union

from paperap.models.mixins.queryset import HasDocumentCount, HasOwner
from paperap.models.abstract.queryset import BaseQuerySet, StandardQuerySet, SupportsBulkActions

if TYPE_CHECKING:
    from paperap.models.correspondent.model import Correspondent

logger = logging.getLogger(__name__)


[docs] class CorrespondentQuerySet(StandardQuerySet["Correspondent"], HasOwner, HasDocumentCount, SupportsBulkActions): """ QuerySet for Paperless-ngx correspondents with specialized filtering methods. Extends StandardQuerySet to provide correspondent-specific filtering capabilities, including filtering by name, matching algorithm, and other correspondent attributes. Inherits document counting capabilities from HasDocumentCount and owner-related filtering from HasOwner. Examples: Get all correspondents: >>> correspondents = client.correspondents() Filter by name: >>> electric = client.correspondents().name("Electric Company") Find correspondents with case-insensitive matching: >>> insensitive = client.correspondents().case_insensitive(True) """
[docs] def name(self, value: str, *, exact: bool = True, case_insensitive: bool = True) -> Self: """ Filter correspondents by name. Args: value: The correspondent name to filter by. exact: If True, match the exact name, otherwise use contains. case_insensitive: If True, ignore case when matching. Returns: Filtered CorrespondentQuerySet. Examples: Find correspondents with exact name: >>> exact_match = client.correspondents().name("Electric Company") Find correspondents with name containing "electric": >>> contains = client.correspondents().name("electric", exact=False) """ return self.filter_field_by_str("name", value, exact=exact, case_insensitive=case_insensitive)
[docs] def matching_algorithm(self, value: int) -> Self: """ Filter correspondents by their matching algorithm. Paperless-ngx supports different algorithms for matching documents to correspondents. This method filters correspondents by the algorithm they use. Args: value: The matching algorithm ID to filter by. Common values include: 1: Any word 2: All words 3: Exact match 4: Regular expression 5: Fuzzy match 6: Auto Returns: Filtered CorrespondentQuerySet. """ return self.filter(matching_algorithm=value)
[docs] def match(self, match: str, *, exact: bool = True, case_insensitive: bool = True) -> Self: """ Filter correspondents by their match pattern. The match pattern is the text pattern used by Paperless-ngx to automatically assign documents to this correspondent. Args: match: The match pattern to filter by. exact: If True, match the exact pattern, otherwise use contains. case_insensitive: If True, ignore case when matching. Returns: Filtered CorrespondentQuerySet. Examples: Find correspondents with match pattern containing "invoice": >>> invoice_matchers = client.correspondents().match("invoice", exact=False) """ return self.filter_field_by_str("match", match, exact=exact, case_insensitive=case_insensitive)
[docs] def case_insensitive(self, insensitive: bool = True) -> Self: """ Filter correspondents by case sensitivity setting. Paperless-ngx allows correspondents to have case-sensitive or case-insensitive matching. This method filters correspondents based on that setting. Args: insensitive: If True, get correspondents with case-insensitive matching. If False, get correspondents with case-sensitive matching. Returns: Filtered CorrespondentQuerySet. """ return self.filter(is_insensitive=insensitive)
[docs] def user_can_change(self, value: bool = True) -> Self: """ Filter correspondents by user change permission. In Paperless-ngx, some correspondents may be restricted from modification by certain users based on permissions. This method filters correspondents based on whether the current user can change them. Args: value: If True, get correspondents that can be changed by the current user. If False, get correspondents that cannot be changed by the current user. Returns: Filtered CorrespondentQuerySet. """ return self.filter(user_can_change=value)
[docs] def slug(self, value: str, *, exact: bool = True, case_insensitive: bool = True) -> Self: """ Filter correspondents by slug. Slugs are URL-friendly versions of the correspondent name used in the Paperless-ngx web interface and API. This method filters correspondents based on their slug value. Args: value: The slug to filter by. exact: If True, match the exact slug, otherwise use contains. case_insensitive: If True, ignore case when matching. Returns: Filtered CorrespondentQuerySet. Examples: Find correspondent with slug "electric-company": >>> electric = client.correspondents().slug("electric-company") """ return self.filter_field_by_str("slug", value, exact=exact, case_insensitive=case_insensitive)