Coverage for src/paperap/models/user/queryset.py: 61%

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.user.model import Group, User

31

32 logger = logging.getLogger(__name__)

33

34

35 class UserQuerySet(StandardQuerySet["User"]):

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 username(self, value: str, *, exact: bool = True, case_insensitive: bool = True) -> Self:

44 """

45 Filter users by username.

46

47 Args:

48 value (str): The username to filter by

49 exact (bool): If True, match the exact username, otherwise use contains

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

51

52 Returns:

53 Filtered UserQuerySet

54

55 """

56 return self.filter_field_by_str("username", value, exact=exact, case_insensitive=case_insensitive)

57

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

59 """

60 Filter users by email.

61

62 Args:

63 value (str): The email to filter by

64 exact (bool): If True, match the exact email, otherwise use contains

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

66

67 Returns:

68 Filtered UserQuerySet

69

70 """

71 return self.filter_field_by_str("email", value, exact=exact, case_insensitive=case_insensitive)

72

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

74 """

75 Filter users by first name.

76

77 Args:

78 value (str): The first name to filter by

79 exact (bool): If True, match the exact first name, otherwise use contains

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

81

82 Returns:

83 Filtered UserQuerySet

84

85 """

86 return self.filter_field_by_str("first_name", value, exact=exact, case_insensitive=case_insensitive)

87

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

89 """

90 Filter users by last name.

91

92 Args:

93 value (str): The last name to filter by

94 exact (bool): If True, match the exact last name, otherwise use contains

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

96

97 Returns:

98 Filtered UserQuerySet

99

100 """

101 return self.filter_field_by_str("last_name", value, exact=exact, case_insensitive=case_insensitive)

102

103 def staff(self, value: bool = True) -> Self:

104 """

105 Filter users by staff status.

106

107 Args:

108 value: If True, filter users that are staff

109

110 Returns:

111 Filtered UserQuerySet

112

113 """

114 return self.filter(is_staff=value)

115

116 def active(self, value: bool = True) -> Self:

117 """

118 Filter users by active status.

119

120 Args:

121 value: If True, filter users that are active

122

123 Returns:

124 Filtered UserQuerySet

125

126 """

127 return self.filter(is_active=value)

128

129 def superuser(self, value: bool = True) -> Self:

130 """

131 Filter users by superuser status.

132

133 Args:

134 value: If True, filter users that are superusers

135

136 Returns:

137 Filtered UserQuerySet

138

139 """

140 return self.filter(is_superuser=value)

141

142 def in_group(self, value: int) -> Self:

143 """

144 Filter users by group.

145

146 Args:

147 value: The group to filter by

148

149 Returns:

150 Filtered UserQuerySet

151

152 """

153 return self.filter(groups_contains=value)

154

155 def has_permission(self, value: str) -> Self:

156 """

157 Filter users by permission.

158

159 Args:

160 value: The permission to filter by

161

162 Returns:

163 Filtered UserQuerySet

164

165 """

166 return self.filter(groups_permissions_contains=value)

167

168 def has_inherited_permission(self, value: str) -> Self:

169 """

170 Filter users by inherited permission.

171

172 Args:

173 value: The inherited permission to filter by

174

175 Returns:

176 Filtered UserQuerySet

177

178 """

179 return self.filter(inherited_permissions_contains=value)

180

181

182 class GroupQuerySet(StandardQuerySet["Group"]):

183 """

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

185

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

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

188 """

189

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

191 """

192 Filter groups by name.

193

194 Args:

195 value (str): The name to filter by

196 exact (bool): If True, match the exact name, otherwise use contains

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

198

199 Returns:

200 Filtered GroupQuerySet

201

202 """

203 return self.filter_field_by_str("name", value, exact=exact, case_insensitive=case_insensitive)

204

205 def has_permission(self, value: str) -> Self:

206 """

207 Filter groups by permission.

208

209 Args:

210 value: The permission to filter by

211

212 Returns:

213 Filtered GroupQuerySet

214

215 """

216 return self.filter(permissions__contains=value)