caselawclient.models.documents.versions

  1import json
  2from enum import Enum
  3from typing import Any, Optional, TypedDict
  4
  5from typing_extensions import NotRequired
  6
  7
  8class AnnotationDataDict(TypedDict):
  9    type: str
 10    calling_function: str
 11    calling_agent: str
 12    message: NotRequired[str]
 13    payload: NotRequired[dict[str, Any]]
 14    automated: bool
 15
 16
 17class VersionType(Enum):
 18    """Valid types of version."""
 19
 20    SUBMISSION = "submission"
 21    """ This version has been created as a result of a submission of a new document. """
 22
 23    ENRICHMENT = "enrichment"
 24    """ This version has been created through an enrichment process. """
 25
 26    EDIT = "edit"
 27    """ This version has been created as the result of a manual edit. """
 28
 29
 30class VersionAnnotation:
 31    """A class holding structured data about the reason for a version."""
 32
 33    def __init__(
 34        self,
 35        version_type: VersionType,
 36        automated: bool,
 37        message: Optional[str] = None,
 38        payload: Optional[dict[str, Any]] = None,
 39    ):
 40        """
 41        :param version_type: The type of version being created
 42        :param automated: `True` if this action has happened as the result of an automated process, rather than a human
 43            action
 44        :param message: A human-readable string containing information about the version which can't be expressed in the
 45            structured data.
 46        :param payload: A dict containing additional information relevant to this version change
 47        """
 48        self.version_type = version_type
 49        self.automated = automated
 50        self.message = message
 51        self.payload = payload
 52
 53        self.calling_function: Optional[str] = None
 54        self.calling_agent: Optional[str] = None
 55
 56    def set_calling_function(self, calling_function: str) -> None:
 57        """
 58        Set the name of the calling function for tracing purposes
 59
 60        :param calling_function: The name of the function which is performing the database write
 61        """
 62        self.calling_function = calling_function
 63
 64    def set_calling_agent(self, calling_agent: str) -> None:
 65        """
 66        Set the name of the calling agent for tracing purposes
 67
 68        :param calling_agent: The name of the agent which is performing the database write
 69        """
 70        self.calling_agent = calling_agent
 71
 72    @property
 73    def structured_annotation_dict(self) -> AnnotationDataDict:
 74        """
 75        :return: A structured dict representing this `VersionAnnotation`
 76
 77        :raises AttributeError: The name of the calling function has not been set; use `set_calling_function()`
 78        :raises AttributeError: The name of the calling agent has not been set; use `set_calling_agent()`
 79        """
 80        if not self.calling_function:
 81            raise AttributeError(
 82                "The name of the calling function has not been set; use set_calling_function()",
 83            )
 84
 85        if not self.calling_agent:
 86            raise AttributeError(
 87                "The name of the calling agent has not been set; use set_calling_agent()",
 88            )
 89
 90        annotation_data: AnnotationDataDict = {
 91            "type": self.version_type.value,
 92            "calling_function": self.calling_function,
 93            "calling_agent": self.calling_agent,
 94            "automated": self.automated,
 95        }
 96
 97        if self.message:
 98            annotation_data["message"] = self.message
 99
100        if self.payload:
101            annotation_data["payload"] = self.payload
102
103        return annotation_data
104
105    @property
106    def as_json(self) -> str:
107        """Render the structured annotation data as JSON, so it can be stored in the MarkLogic dls:annotation field.
108
109        :return: A JSON string representing this `VersionAnnotation`"""
110
111        return json.dumps(self.structured_annotation_dict)
112
113    def __str__(self) -> str:
114        return self.as_json