Coverage for src/paperap/models/task/queryset.py: 54%

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, Self

26

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

28

29 if TYPE_CHECKING:

30 from paperap.models.task.model import Task

31

32 logger = logging.getLogger(__name__)

33

34

35 class TaskQuerySet(StandardQuerySet["Task"]):

36 """

37 A lazy-loaded, chainable query interface for Paperless NGX resources.

38

39 BaseQuerySet provides pagination, filtering, and caching functionality similar to Django's BaseQuerySet.

40 It's designed to be lazy - only fetching data when it's actually needed.

41 """

42

43 def task_id(self, value: int) -> Self:

44 """

45 Filter tasks by task_id.

46

47 Args:

48 value (int): The task_id to filter by

49

50 Returns:

51 TaskQuerySet: The filtered queryset

52

53 """

54 return self.filter(task_id=value)

55

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

57 """

58 Filter tasks by task_file_name.

59

60 Args:

61 value (str): The task_file_name to filter by

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

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

64

65 Returns:

66 TaskQuerySet: The filtered queryset

67

68 """

69 return self.filter_field_by_str("task_file_name", value, exact=exact, case_insensitive=case_insensitive)

70

71 def date_done(self, value: str | None) -> Self:

72 """

73 Filter tasks by date_done.

74

75 Args:

76 value (str | None): The date_done to filter by

77

78 Returns:

79 TaskQuerySet: The filtered queryset

80

81 """

82 return self.filter(date_done=value)

83

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

85 """

86 Filter tasks by type.

87

88 Args:

89 value (str): The type to filter by

90 exact (bool): If True, match the exact type, otherwise use contains

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

92

93 Returns:

94 TaskQuerySet: The filtered queryset

95

96 """

97 return self.filter_field_by_str("type", value, exact=exact, case_insensitive=case_insensitive)

98

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

100 """

101 Filter tasks by status.

102

103 Args:

104 value (str): The status to filter by

105 exact (bool): If True, match the exact status, otherwise use contains

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

107

108 Returns:

109 TaskQuerySet: The filtered queryset

110

111 """

112 return self.filter_field_by_str("status", value, exact=exact, case_insensitive=case_insensitive)

113

114 def result(self, value: str | None, *, exact: bool = True, case_insensitive: bool = True) -> Self:

115 """

116 Filter tasks by result.

117

118 Args:

119 value (str | None): The result to filter by

120 exact (bool): If True, match the exact result, otherwise use contains

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

122

123 Returns:

124 TaskQuerySet: The filtered queryset

125

126 """

127 if value is None:

128 return self.filter(result__isnull=True)

129 return self.filter_field_by_str("result", value, exact=exact, case_insensitive=case_insensitive)

130

131 def acknowledged(self, value: bool) -> Self:

132 """

133 Filter tasks by acknowledged.

134

135 Args:

136 value (bool): The acknowledged to filter by

137

138 Returns:

139 TaskQuerySet: The filtered queryset

140

141 """

142 return self.filter(acknowledged=value)

143

144 def related_document(self, value: int | list[int]) -> Self:

145 """

146 Filter tasks by related_document.

147

148 Args:

149 value (int | list[int]): The related_document to filter by

150

151 Returns:

152 TaskQuerySet: The filtered queryset

153

154 """

155 if isinstance(value, int):

156 return self.filter(related_document=value)

157 return self.filter(related_document__in=value)