Coverage for src/paperap/models/tag/queryset.py: 68%

1"""

2----------------------------------------------------------------------------

3

4 METADATA:

5

6 File: queryset.py

7 Project: paperap

8 Created: 2025-03-04

9 Version: 0.0.5

10 Author: Jess Mann

11 Email: jess@jmann.me

12 Copyright (c) 2025 Jess Mann

13

14----------------------------------------------------------------------------

15

16 LAST MODIFIED:

17

18 2025-03-04 By Jess Mann

19

20"""

21

22 from __future__ import annotations

23

24 import logging

25 from typing import TYPE_CHECKING, Any, Optional, Self, Union

26

27 from paperap.models.abstract.queryset import BaseQuerySet, StandardQuerySet

28 from paperap.models.mixins.queryset import HasStandard

29

30 if TYPE_CHECKING:

31 from paperap.models.tag.model import Tag

32

33 logger = logging.getLogger(__name__)

34

35

36 class TagQuerySet(StandardQuerySet["Tag"], HasStandard):

37 """

38 QuerySet for Paperless-ngx tags with specialized filtering methods.

39 """

40

41 def colour(self, value: str, *, exact: bool = True, case_insensitive: bool = True) -> Self:

42 """

43 Filter tags by color.

44

45 Args:

46 value (str): The color to filter by

47 exact (bool): If True, match the exact color, otherwise use contains

48 case_insensitive (bool): If True, ignore case when matching

49

50 Returns:

51 Filtered TagQuerySet

52

53 """

54 return self.filter_field_by_str("colour", value, exact=exact, case_insensitive=case_insensitive)

55

56 def match(self, value: str, *, exact: bool = True) -> Self:

57 """

58 Filter tags by match value.

59

60 Args:

61 value (str): The value to filter by

62 exact (bool): If True, match the exact value, otherwise use contains

63

64 Returns:

65 Filtered TagQuerySet

66

67 """

68 return self.filter_field_by_str("match", value, exact=exact)

69

70 def matching_algorithm(self, value: int) -> Self:

71 """

72 Filter tags by matching algorithm.

73

74 Args:

75 value (int): The matching algorithm to filter by

76

77 Returns:

78 Filtered TagQuerySet

79

80 """

81 return self.filter(matching_algorithm=value)

82

83 def case_insensitive(self, value: bool = True) -> Self:

84 """

85 Filter tags by case insensitivity.

86

87 Args:

88 value: If True, filter tags that are case insensitive

89

90 Returns:

91 Filtered TagQuerySet

92

93 """

94 return self.filter(is_insensitive=value)

95

96 def is_inbox_tag(self, value: bool = True) -> Self:

97 """

98 Filter tags by inbox status.

99

100 Args:

101 value: If True, get inbox tags, otherwise non-inbox tags

102

103 Returns:

104 Filtered TagQuerySet

105

106 """

107 return self.filter(is_inbox_tag=value)

108

109 def user_can_change(self, value: bool = True) -> Self:

110 """

111 Filter tags by user change permission.

112

113 Args:

114 value: If True, get tags that can be changed by user

115

116 Returns:

117 Filtered TagQuerySet

118

119 """

120 return self.filter(user_can_change=value)