Coverage for src/paperap/models/tag/model.py: 93%

1"""

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

3

4 METADATA:

5

6 File: tag.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 from datetime import datetime

25 from typing import TYPE_CHECKING, Any, Optional

26

27 from pydantic import Field, ValidationError, field_validator

28

29 from paperap.models.abstract.model import StandardModel

30 from paperap.models.mixins.models import MatcherMixin

31 from paperap.models.tag.queryset import TagQuerySet

32

33 if TYPE_CHECKING:

34 from paperap.models.document import Document, DocumentQuerySet

35

36

37 class Tag(StandardModel, MatcherMixin):

38 """

39 Represents a tag in Paperless-NgX.

40 """

41

42 name: str | None = None

43 slug: str | None = None

44 colour: str | None = Field(alias="color", default=None)

45 is_inbox_tag: bool | None = None

46 document_count: int = 0

47 owner: int | None = None

48 user_can_change: bool | None = None

49

50 class Meta(StandardModel.Meta):

51 # Fields that should not be modified

52 read_only_fields = {"slug", "document_count"}

53 queryset = TagQuerySet

54

55 @field_validator("colour", mode="before")

56 @classmethod

57 def validate_colour(cls, value: Any) -> str | None:

58 if value is None:

59 return None

60

61 # It seems like int should not be allowed, but my sample data contains an int??

62 if isinstance(value, (str, int)):

63 return str(value)

64

65 raise TypeError(f"Colour must be a string or integer, not {type(value)}")

66

67 @property

68 def documents(self) -> "DocumentQuerySet":

69 """

70 Get documents with this tag.

71

72 Returns:

73 List of documents.

74

75 """

76 return self._client.documents().all().tag_id(self.id)