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

31 statements  

« prev     ^ index     » next       coverage.py v7.6.12, created at 2025-03-12 23:40 -0400

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 

22from __future__ import annotations 

23 

24import logging 

25from typing import TYPE_CHECKING, Any, Self 

26 

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

28 

29if TYPE_CHECKING: 

30 from paperap.models.user.model import Group, User 

31 

32logger = logging.getLogger(__name__) 

33 

34 

35class 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 

182class 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)