Coverage for src/paperap/models/profile/queryset.py: 71%

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

26

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

28

29 if TYPE_CHECKING:

30 from paperap.models.profile.model import Profile

31

32 logger = logging.getLogger(__name__)

33

34

35 class ProfileQuerySet(StandardQuerySet["Profile"]):

36 """

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

38

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

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

41

42 Examples:

43 >>> profiles = ProfileQuerySet()

44 >>> profiles = profiles.email("example@example.com")

45 >>> for profile in profiles:

46 >>> print(profile.first_name)

47

48 """

49

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

51 """

52 Filter by email.

53

54 Args:

55 value: The email to filter by.

56 exact: Whether to filter by an exact match.

57 case_insensitive: Whether the match should be case insensitive.

58

59 Returns:

60 A new ProfileQuerySet instance with the filter applied.

61

62 Examples:

63 >>> profiles = ProfileQuerySet()

64 >>> profiles = profiles.email("example@example.com")

65

66 Examples:

67 >>> profiles = client.profiles().email("john.doe@gmail.com")

68 >>> profiles = client.profiles().email("gmail.com", exact=False)

69 >>> profiles = client.profiles().email("jOhN.DOE@gmail.com", case_insensitive=True)

70

71 """

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

73

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

75 """

76 Filter by first name.

77

78 Args:

79 first_name: The first name to filter by.

80 exact: Whether to filter by an exact match.

81 case_insensitive: Whether the match should be case insensitive.

82

83 Returns:

84 A new ProfileQuerySet instance with the filter applied.

85

86 Examples:

87 >>> profiles = client.profiles().first_name("John")

88 >>> profiles = client.profiles().first_name("John", exact=False)

89 >>> profiles = client.profiles().first_name("JOHN", case_insensitive=False)

90

91 """

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

93

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

95 """

96 Filter by last name.

97

98 Args:

99 last_name: The last name to filter by.

100 exact: Whether to filter by an exact match.

101

102 Returns:

103 A new ProfileQuerySet instance with the filter applied.

104

105 Examples:

106 >>> profiles = client.profiles().last_name("Doe")

107 >>> profiles = client.profiles().last_name("Doe", exact=False)

108 >>> profiles = client.profiles().last_name("DOE", case_insensitive=False)

109

110 """

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

112

113 def has_usable_password(self, value: bool = True) -> ProfileQuerySet:

114 """

115 Filter by has usable password.

116

117 Args:

118 has_usable_password: The has usable password to filter by.

119

120 Returns:

121 A new ProfileQuerySet instance with the filter applied.

122

123 Examples:

124 >>> profiles = client.profiles().has_usable_password()

125 >>> profiles = client.profiles().has_usable_password(False)

126

127 """

128 return self.filter(has_usable_password=value)