paperap.models.tag.queryset module
Provide specialized query capabilities for Paperless-ngx tag resources.
This module implements the TagQuerySet class, which extends the standard queryset functionality with tag-specific filtering methods. These methods enable efficient and intuitive querying of tag resources based on their unique attributes such as color, matching algorithm, and inbox status.
- class paperap.models.tag.queryset.TagQuerySet(resource, filters=None, _cache=None, _fetch_all=False, _next_url=None, _last_response=None, _iter=None, _urls_fetched=None)[source]
Bases:
StandardQuerySet
[Tag],HasStandard
,SupportsBulkActions
Implement specialized filtering methods for Paperless-ngx tags.
Extends StandardQuerySet to provide tag-specific filtering capabilities, including filtering by color, matching algorithm, inbox status, and other tag-specific attributes.
The TagQuerySet provides a fluent interface for building complex queries against tag resources in the Paperless-ngx API.
Examples
- Get all inbox tags:
>>> inbox_tags = client.tags.all().is_inbox_tag()
- Find tags with a specific color:
>>> red_tags = client.tags.all().colour("#ff0000")
- Find tags that can be changed by the user:
>>> editable_tags = client.tags.all().user_can_change()
- 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)
- colour(value, *, exact=True, case_insensitive=True)[source]
Filter tags by color.
Allows filtering tags based on their color attribute. The color can be specified as either a string (e.g., “#ff0000” for red) or an integer representation.
- Parameters:
- Return type:
Self
- Returns:
A filtered TagQuerySet containing only tags with matching colors.
Examples
- Find tags with red color:
>>> red_tags = client.tags.all().colour("#ff0000")
- Find tags with colors containing “blue” (case insensitive):
>>> blue_tags = client.tags.all().colour("blue", exact=False)
- match(value, *, exact=True, case_insensitive=True)[source]
Filter tags by match value.
Filters tags based on their match pattern, which is used by Paperless-ngx for automatic tag assignment.
- Parameters:
- Return type:
Self
- Returns:
A filtered TagQuerySet containing only tags with matching patterns.
Examples
- Find tags that match “invoice”:
>>> invoice_tags = client.tags.all().match("invoice")
- Find tags with match patterns containing “tax”:
>>> tax_tags = client.tags.all().match("tax", exact=False)
- matching_algorithm(value)[source]
Filter tags by matching algorithm.
Filters tags based on the algorithm used for automatic tag assignment. Paperless-ngx supports different matching algorithms like exact, regex, fuzzy matching, etc., each represented by an integer value.
- Parameters:
value (
int
) – The matching algorithm ID to filter by. Common values include: 1 (any), 2 (all), 3 (literal), 4 (regex), 5 (fuzzy match).- Return type:
Self
- Returns:
A filtered TagQuerySet containing only tags using the specified matching algorithm.
Examples
- Find tags using regex matching:
>>> regex_tags = client.tags.all().matching_algorithm(4)
- case_insensitive(value=True)[source]
Filter tags by case insensitivity setting.
Filters tags based on whether their matching is case insensitive or not. This affects how Paperless-ngx performs automatic tag assignment.
- Parameters:
value (
bool
) – If True, returns tags configured for case-insensitive matching. If False, returns tags configured for case-sensitive matching. Defaults to True.- Return type:
Self
- Returns:
A filtered TagQuerySet containing only tags with the specified case sensitivity setting.
Examples
- Find case-insensitive tags:
>>> insensitive_tags = client.tags.all().case_insensitive()
- Find case-sensitive tags:
>>> sensitive_tags = client.tags.all().case_insensitive(False)
- is_inbox_tag(value=True)[source]
Filter tags by inbox status.
In Paperless-ngx, inbox tags are special tags that mark documents as needing attention or processing. This method filters tags based on whether they are designated as inbox tags.
- Parameters:
value (
bool
) – If True, returns only inbox tags. If False, returns only non-inbox tags. Defaults to True.- Return type:
Self
- Returns:
A filtered TagQuerySet containing only tags with the specified inbox status.
Examples
- Get all inbox tags:
>>> inbox_tags = client.tags.all().is_inbox_tag()
- Get all non-inbox tags:
>>> regular_tags = client.tags.all().is_inbox_tag(False)
- user_can_change(value=True)[source]
Filter tags by user change permission.
Filters tags based on whether the current authenticated user has permission to modify them. This is useful for identifying which tags can be edited in user interfaces.
- Parameters:
value (
bool
) – If True, returns tags that can be changed by the current user. If False, returns tags that cannot be changed by the current user. Defaults to True.- Return type:
Self
- Returns:
A filtered TagQuerySet containing only tags with the specified change permission.
Examples
- Get tags the current user can modify:
>>> editable_tags = client.tags.all().user_can_change()
- Get tags the current user cannot modify:
>>> readonly_tags = client.tags.all().user_can_change(False)