paperap.models.correspondent.queryset module

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.

class paperap.models.correspondent.queryset.CorrespondentQuerySet(resource, filters=None, _cache=None, _fetch_all=False, _next_url=None, _last_response=None, _iter=None, _urls_fetched=None)[source]

Bases: 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)
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)

name(value, *, exact=True, case_insensitive=True)[source]

Filter correspondents by name.

Parameters:
  • value (str) – The correspondent name to filter by.

  • exact (bool) – If True, match the exact name, otherwise use contains.

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

Return type:

Self

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

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.

Parameters:

value (int) – 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

Return type:

Self

Returns:

Filtered CorrespondentQuerySet.

match(match, *, exact=True, case_insensitive=True)[source]

Filter correspondents by their match pattern.

The match pattern is the text pattern used by Paperless-ngx to automatically assign documents to this correspondent.

Parameters:
  • match (str) – The match pattern to filter by.

  • exact (bool) – If True, match the exact pattern, otherwise use contains.

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

Return type:

Self

Returns:

Filtered CorrespondentQuerySet.

Examples

Find correspondents with match pattern containing “invoice”:
>>> invoice_matchers = client.correspondents().match("invoice", exact=False)
case_insensitive(insensitive=True)[source]

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.

Parameters:

insensitive (bool) – If True, get correspondents with case-insensitive matching. If False, get correspondents with case-sensitive matching.

Return type:

Self

Returns:

Filtered CorrespondentQuerySet.

user_can_change(value=True)[source]

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.

Parameters:

value (bool) – If True, get correspondents that can be changed by the current user. If False, get correspondents that cannot be changed by the current user.

Return type:

Self

Returns:

Filtered CorrespondentQuerySet.

slug(value, *, exact=True, case_insensitive=True)[source]

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.

Parameters:
  • value (str) – The slug to filter by.

  • exact (bool) – If True, match the exact slug, otherwise use contains.

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

Return type:

Self

Returns:

Filtered CorrespondentQuerySet.

Examples

Find correspondent with slug “electric-company”:
>>> electric = client.correspondents().slug("electric-company")