ds-caselaw-marklogic-api-client 25.0.0__py3-none-any.whl → 27.0.0__py3-none-any.whl

caselawclient/Client.py

@@ -12,6 +12,7 @@ from xml.etree.ElementTree import Element, ParseError, fromstring
 
 import environ
 import requests
+from ds_caselaw_utils.types import NeutralCitationString
 from requests.auth import HTTPBasicAuth
 from requests.structures import CaseInsensitiveDict
 from requests_toolbelt.multipart import decoder
@@ -800,10 +801,7 @@ class MarklogicApiClient:
             else None
         )
 
-        if os.getenv("XSLT_IMAGE_LOCATION"):
-            image_location = os.getenv("XSLT_IMAGE_LOCATION")
-        else:
-            image_location = ""
+        image_location = os.getenv("XSLT_IMAGE_LOCATION", "")
 
         show_unpublished = self.verify_show_unpublished(show_unpublished)
 
@@ -1038,12 +1036,7 @@ class MarklogicApiClient:
         search_parameters.collections = [DOCUMENT_COLLECTION_URI_JUDGMENT]
         return self.search_and_decode_response(search_parameters)
 
-    def overwrite_document(self, old_uri: str, new_citation: str) -> str:
-        """Move the judgment at old_uri on top of the new citation, which must already exist
-        Compare to update_document_uri"""
-        return move.overwrite_document(old_uri, new_citation, api_client=self)
-
-    def update_document_uri(self, old_uri: str, new_citation: str) -> str:
+    def update_document_uri(self, old_uri: DocumentURIString, new_citation: NeutralCitationString) -> DocumentURIString:
         """
         Move the document at old_uri to the correct location based on the neutral citation
         The new neutral citation *must* not already exist (that is handled elsewhere)

caselawclient/factories.py

@@ -0,0 +1,165 @@
+import datetime
+from typing import Any, Optional, cast
+from unittest.mock import Mock, patch
+
+from typing_extensions import TypeAlias
+
+from caselawclient.Client import MarklogicApiClient
+from caselawclient.models.documents import Document
+from caselawclient.models.documents.body import DocumentBody
+from caselawclient.models.judgments import Judgment
+from caselawclient.models.press_summaries import PressSummary
+from caselawclient.responses.search_result import SearchResult, SearchResultMetadata
+
+DEFAULT_DOCUMENT_BODY_XML = "<akomantoso>This is some XML of a judgment.</akomantoso>"
+
+
+class DocumentBodyFactory:
+    # "name_of_attribute": "default value"
+    PARAMS_MAP: dict[str, Any] = {
+        "name": "Judgment v Judgement",
+        "court": "Court of Testing",
+        "document_date_as_string": "2023-02-03",
+    }
+
+    @classmethod
+    def build(cls, xml_string: str = DEFAULT_DOCUMENT_BODY_XML, **kwargs: Any) -> DocumentBody:
+        document_body = DocumentBody(
+            xml_bytestring=xml_string.encode(encoding="utf-8"),
+        )
+
+        for param_name, default_value in cls.PARAMS_MAP.items():
+            value = kwargs.get(param_name, default_value)
+            setattr(document_body, param_name, value)
+
+        return document_body
+
+
+class DocumentFactory:
+    # "name_of_attribute": "default value"
+    PARAMS_MAP: dict[str, Any] = {
+        "is_published": False,
+        "is_sensitive": False,
+        "is_anonymised": False,
+        "is_failure": False,
+        "source_name": "Example Uploader",
+        "source_email": "uploader@example.com",
+        "consignment_reference": "TDR-12345",
+        "assigned_to": "",
+        "versions": [],
+    }
+
+    target_class: TypeAlias = Document
+
+    @classmethod
+    def build(
+        cls,
+        uri: str = "test/2023/123",
+        html: str = "<p>This is a judgment.</p>",
+        api_client: Optional[MarklogicApiClient] = None,
+        **kwargs: Any,
+    ) -> target_class:
+        if not api_client:
+            api_client = Mock(spec=MarklogicApiClient)
+            api_client.get_judgment_xml_bytestring.return_value = DEFAULT_DOCUMENT_BODY_XML.encode(encoding="utf-8")
+
+        with patch.object(cls.target_class, "content_as_html") as mock_content_as_html:
+            mock_content_as_html.return_value = html
+            document = cls.target_class(uri, api_client=api_client)
+
+        document.body = kwargs.pop("body") if "body" in kwargs else DocumentBodyFactory.build()
+
+        for param_name, default_value in cls.PARAMS_MAP.items():
+            value = kwargs.get(param_name, default_value)
+            setattr(document, param_name, value)
+
+        return document
+
+
+class JudgmentFactory(DocumentFactory):
+    target_class = Judgment
+
+    def __init__(self) -> None:
+        self.PARAMS_MAP = self.PARAMS_MAP | {
+            "neutral_citation": "[2023] Test 123",
+            "best_human_identifier": "[2023] Test 123",
+        }
+
+        super().__init__()
+
+    @classmethod
+    def build(
+        cls,
+        uri: str = "test/2023/123",
+        html: str = "<p>This is a judgment.</p>",
+        api_client: Optional[MarklogicApiClient] = None,
+        **kwargs: Any,
+    ) -> Judgment:
+        return cast(Judgment, super().build(uri, html, api_client, **kwargs))
+
+
+class PressSummaryFactory(DocumentFactory):
+    target_class = PressSummary
+
+    def __init__(self) -> None:
+        self.PARAMS_MAP = self.PARAMS_MAP | {
+            "neutral_citation": "[2023] Test 123",
+            "best_human_identifier": "[2023] Test 123",
+        }
+
+        super().__init__()
+
+    @classmethod
+    def build(
+        cls,
+        uri: str = "test/2023/123/press-summary/1",
+        html: str = "<p>This is a judgment.</p>",
+        api_client: Optional[MarklogicApiClient] = None,
+        **kwargs: Any,
+    ) -> PressSummary:
+        return cast(PressSummary, super().build(uri, html, api_client, **kwargs))
+
+
+class SimpleFactory:
+    # "name_of_attribute": "default value"
+    PARAMS_MAP: dict[str, Any]
+
+    target_class: TypeAlias = object
+
+    @classmethod
+    def build(cls, **kwargs: Any) -> target_class:
+        mock_object = Mock(spec=cls.target_class, autospec=True)
+
+        for param, default in cls.PARAMS_MAP.items():
+            if param in kwargs:
+                setattr(mock_object.return_value, param, kwargs[param])
+            else:
+                setattr(mock_object.return_value, param, default)
+
+        return mock_object()
+
+
+class SearchResultMetadataFactory(SimpleFactory):
+    target_class = SearchResultMetadata
+    # "name_of_attribute": "default value"
+    PARAMS_MAP = {
+        "author": "Fake Name",
+        "author_email": "fake.email@gov.invalid",
+        "consignment_reference": "TDR-2023-ABC",
+        "submission_datetime": datetime.datetime(2023, 2, 3, 9, 12, 34),
+    }
+
+
+class SearchResultFactory(SimpleFactory):
+    target_class = SearchResult
+
+    # "name_of_attribute": ("name of incoming param", "default value")
+    PARAMS_MAP = {
+        "uri": "test/2023/123",
+        "name": "Judgment v Judgement",
+        "neutral_citation": "[2023] Test 123",
+        "court": "Court of Testing",
+        "date": datetime.date(2023, 2, 3),
+        "metadata": SearchResultMetadataFactory.build(),
+        "is_failure": False,
+    }

caselawclient/models/{documents.py → documents/__init__.py}

@@ -1,27 +1,22 @@
 import datetime
 import warnings
 from functools import cached_property
-from typing import TYPE_CHECKING, Any, Dict, NewType, Optional
+from typing import TYPE_CHECKING, Any, NewType, Optional
 
-import pytz
 from ds_caselaw_utils import courts
 from ds_caselaw_utils.courts import CourtNotFoundException
-from lxml import etree
+from ds_caselaw_utils.types import NeutralCitationString
 from lxml import html as html_parser
 from requests_toolbelt.multipart import decoder
 
-from caselawclient.models.utilities import extract_version
-from caselawclient.models.utilities.dates import parse_string_date_as_utc
-
-from ..errors import (
+from caselawclient.errors import (
     DocumentNotFoundError,
     GatewayTimeoutError,
     NotSupportedOnVersion,
     OnlySupportedOnVersion,
 )
-from ..xml_helpers import get_xpath_match_string, get_xpath_match_strings
-from .utilities import VersionsDict, render_versions
-from .utilities.aws import (
+from caselawclient.models.utilities import VersionsDict, extract_version, render_versions
+from caselawclient.models.utilities.aws import (
     ParserInstructionsDict,
     announce_document_event,
     check_docx_exists,
@@ -34,31 +29,17 @@ from .utilities.aws import (
     uri_for_s3,
 )
 
-MINIMUM_ENRICHMENT_TIME = datetime.timedelta(minutes=20)
-
+from .body import DocumentBody
+from .exceptions import CannotPublishUnpublishableDocument, DocumentNotSafeForDeletion
+from .statuses import DOCUMENT_STATUS_HOLD, DOCUMENT_STATUS_IN_PROGRESS, DOCUMENT_STATUS_NEW, DOCUMENT_STATUS_PUBLISHED
 
-class UnparsableDate(Warning):
-    pass
+MINIMUM_ENRICHMENT_TIME = datetime.timedelta(minutes=20)
 
 
 class GatewayTimeoutGettingHTMLWithQuery(RuntimeWarning):
     pass
 
 
-DOCUMENT_STATUS_HOLD = "On hold"
-""" This document has been placed on hold to actively prevent publication. """
-
-DOCUMENT_STATUS_PUBLISHED = "Published"
-""" This document has been published and should be considered publicly visible. """
-
-DOCUMENT_STATUS_IN_PROGRESS = "In progress"
-""" This document has not been published or put on hold, and has been picked up by an editor and
-    should be progressing through the document pipeline. """
-
-DOCUMENT_STATUS_NEW = "New"
-""" This document isn't published, on hold, or assigned, and can be picked up by an editor in the future. """
-
-
 DOCUMENT_COLLECTION_URI_JUDGMENT = "judgment"
 DOCUMENT_COLLECTION_URI_PRESS_SUMMARY = "press-summary"
 
@@ -67,19 +48,6 @@ if TYPE_CHECKING:
 
 
 DocumentURIString = NewType("DocumentURIString", str)
-CourtIdentifierString = NewType("CourtIdentifierString", str)
-
-
-class CannotPublishUnpublishableDocument(Exception):
-    """A document which has failed publication safety checks in `Document.is_publishable` cannot be published."""
-
-
-class DocumentNotSafeForDeletion(Exception):
-    """A document which is not safe for deletion cannot be deleted."""
-
-
-class NonXMLDocumentError(Exception):
-    """A document cannot be parsed as XML."""
 
 
 class Document:
@@ -96,7 +64,7 @@ class Document:
 
     attributes_to_validate: list[tuple[str, bool, str]] = [
         (
-            "failed_to_parse",
+            "is_failure",
             False,
             "This document failed to parse",
         ),
@@ -143,20 +111,18 @@ class Document:
 
         :raises DocumentNotFoundError: The document does not exist within MarkLogic
         """
-        self.uri = DocumentURIString(uri.strip("/"))
-        self.api_client = api_client
+        self.uri: DocumentURIString = DocumentURIString(uri.strip("/"))
+        self.api_client: MarklogicApiClient = api_client
         if not self.document_exists():
             raise DocumentNotFoundError(f"Document {self.uri} does not exist")
 
-        self.xml = self.XML(
-            xml_bytestring=self.api_client.get_judgment_xml_bytestring(
-                self.uri,
-                show_unpublished=True,
-            ),
+        self.body: DocumentBody = DocumentBody(
+            xml_bytestring=self.api_client.get_judgment_xml_bytestring(self.uri, show_unpublished=True),
         )
+        """ `Document.body` represents the XML of the document itself, without any information such as version tracking or properties. """
 
     def __repr__(self) -> str:
-        name = self.name or "un-named"
+        name = self.body.name or "un-named"
         return f"<{self.document_noun} {self.uri}: {name}>"
 
     def document_exists(self) -> bool:
@@ -186,104 +152,6 @@ class Document:
         """
         return f"https://caselaw.nationalarchives.gov.uk/{self.uri}"
 
-    @cached_property
-    def name(self) -> str:
-        return self.xml.get_xpath_match_string(
-            "/akn:akomaNtoso/akn:*/akn:meta/akn:identification/akn:FRBRWork/akn:FRBRname/@value",
-            {"akn": "http://docs.oasis-open.org/legaldocml/ns/akn/3.0"},
-        )
-
-    @cached_property
-    def court(self) -> str:
-        return self.xml.get_xpath_match_string(
-            "/akn:akomaNtoso/akn:*/akn:meta/akn:proprietary/uk:court/text()",
-            {
-                "uk": "https://caselaw.nationalarchives.gov.uk/akn",
-                "akn": "http://docs.oasis-open.org/legaldocml/ns/akn/3.0",
-            },
-        )
-
-    @cached_property
-    def jurisdiction(self) -> str:
-        return self.xml.get_xpath_match_string(
-            "/akn:akomaNtoso/akn:*/akn:meta/akn:proprietary/uk:jurisdiction/text()",
-            {
-                "uk": "https://caselaw.nationalarchives.gov.uk/akn",
-                "akn": "http://docs.oasis-open.org/legaldocml/ns/akn/3.0",
-            },
-        )
-
-    @property
-    def court_and_jurisdiction_identifier_string(self) -> CourtIdentifierString:
-        if self.jurisdiction != "":
-            return CourtIdentifierString("/".join((self.court, self.jurisdiction)))
-        return CourtIdentifierString(self.court)
-
-    @cached_property
-    def document_date_as_string(self) -> str:
-        return self.xml.get_xpath_match_string(
-            "/akn:akomaNtoso/akn:*/akn:meta/akn:identification/akn:FRBRWork/akn:FRBRdate/@date",
-            {"akn": "http://docs.oasis-open.org/legaldocml/ns/akn/3.0"},
-        )
-
-    @cached_property
-    def document_date_as_date(self) -> Optional[datetime.date]:
-        if not self.document_date_as_string:
-            return None
-        try:
-            return datetime.datetime.strptime(
-                self.document_date_as_string,
-                "%Y-%m-%d",
-            ).date()
-        except ValueError:
-            warnings.warn(
-                f"Unparsable date encountered: {self.document_date_as_string}",
-                UnparsableDate,
-            )
-            return None
-
-    def get_manifestation_datetimes(
-        self,
-        name: Optional[str] = None,
-    ) -> list[datetime.datetime]:
-        name_filter = f"[@name='{name}']" if name else ""
-        iso_datetimes = self.xml.get_xpath_match_strings(
-            "/akn:akomaNtoso/akn:*/akn:meta/akn:identification/akn:FRBRManifestation"
-            f"/akn:FRBRdate{name_filter}/@date",
-            {"akn": "http://docs.oasis-open.org/legaldocml/ns/akn/3.0"},
-        )
-
-        return [parse_string_date_as_utc(event, pytz.UTC) for event in iso_datetimes]
-
-    def get_latest_manifestation_datetime(
-        self,
-        name: Optional[str] = None,
-    ) -> Optional[datetime.datetime]:
-        events = self.get_manifestation_datetimes(name)
-        if not events:
-            return None
-        return max(events)
-
-    def get_latest_manifestation_type(self) -> Optional[str]:
-        return max(
-            (
-                (type, time)
-                for type in ["transform", "tna-enriched"]
-                if (time := self.get_latest_manifestation_datetime(type))
-            ),
-            key=lambda x: x[1],
-        )[0]
-
-    @cached_property
-    def transformation_datetime(self) -> Optional[datetime.datetime]:
-        """When was this document successfully parsed or reparsed (date from XML)"""
-        return self.get_latest_manifestation_datetime("transform")
-
-    @cached_property
-    def enrichment_datetime(self) -> Optional[datetime.datetime]:
-        """When was this document successfully enriched (date from XML)"""
-        return self.get_latest_manifestation_datetime("tna-enriched")
-
     @cached_property
     def is_published(self) -> bool:
         return self.api_client.get_published(self.uri)
@@ -372,10 +240,6 @@ class Document:
         "Is this document a potentially historic version of a document, or is it the main document itself?"
         return extract_version(self.uri) != 0
 
-    @cached_property
-    def content_as_xml(self) -> str:
-        return self.xml.xml_as_string
-
     def content_as_html(
         self,
         version_uri: Optional[DocumentURIString] = None,
@@ -418,39 +282,21 @@ class Document:
 
         :return: `True` if this document is in a 'failure' state, otherwise `False`
         """
-        if self.failed_to_parse:
-            return True
-        return False
+        return self.body.failed_to_parse
 
     @cached_property
     def is_parked(self) -> bool:
-        if "parked" in self.uri:
-            return True
-        return False
-
-    @cached_property
-    def failed_to_parse(self) -> bool:
-        """
-        Did this document entirely fail to parse?
-
-        :return: `True` if there was a complete parser failure, otherwise `False`
-        """
-        if "error" in self.xml.root_element:
-            return True
-        return False
+        return "parked" in self.uri
 
     @cached_property
     def has_name(self) -> bool:
-        if not self.name:
-            return False
-
-        return True
+        return bool(self.body.name)
 
     @cached_property
     def has_valid_court(self) -> bool:
         try:
             return bool(
-                courts.get_by_code(self.court_and_jurisdiction_identifier_string),
+                courts.get_by_code(self.body.court_and_jurisdiction_identifier_string),
             )
         except CourtNotFoundException:
             return False
@@ -521,9 +367,7 @@ class Document:
         """
         Is it sensible to enrich this document?
         """
-        if (self.enriched_recently is False) and self.validates_against_schema:
-            return True
-        return False
+        return (self.enriched_recently is False) and self.validates_against_schema
 
     @cached_property
     def enriched_recently(self) -> bool:
@@ -531,14 +375,13 @@ class Document:
         Has this document been enriched recently?
         """
 
-        last_enrichment = self.enrichment_datetime
+        last_enrichment = self.body.enrichment_datetime
         if not last_enrichment:
             return False
 
         now = datetime.datetime.now(tz=datetime.timezone.utc)
-        if now - last_enrichment < MINIMUM_ENRICHMENT_TIME:
-            return True
-        return False
+
+        return now - last_enrichment < MINIMUM_ENRICHMENT_TIME
 
     @cached_property
     def validates_against_schema(self) -> bool:
@@ -599,10 +442,7 @@ class Document:
         else:
             raise DocumentNotSafeForDeletion
 
-    def overwrite(self, new_citation: str) -> None:
-        self.api_client.overwrite_document(self.uri, new_citation)
-
-    def move(self, new_citation: str) -> None:
+    def move(self, new_citation: NeutralCitationString) -> None:
         self.api_client.update_document_uri(self.uri, new_citation)
 
     def force_reparse(self) -> None:
@@ -612,7 +452,11 @@ class Document:
         self.api_client.set_property(self.uri, "last_sent_to_parser", now.isoformat())
 
         parser_type_noun = {"judgment": "judgment", "press summary": "pressSummary"}[self.document_noun]
-        checked_date = self.document_date_as_string if self.document_date_as_string > "1001" else None
+        checked_date: Optional[str] = (
+            self.body.document_date_as_date.isoformat()
+            if self.body.document_date_as_date and self.body.document_date_as_date > datetime.date(1001, 1, 1)
+            else None
+        )
 
         # the keys of parser_instructions should exactly match the parser output
         # in the *-metadata.json files by the parser. Whilst typically empty
@@ -621,9 +465,9 @@ class Document:
         parser_instructions: ParserInstructionsDict = {
             "documentType": parser_type_noun,
             "metadata": {
-                "name": self.name or None,
+                "name": self.body.name or None,
                 "cite": self.best_human_identifier or None,
-                "court": self.court or None,
+                "court": self.body.court or None,
                 "date": checked_date,
                 "uri": self.uri,
             },
@@ -650,41 +494,4 @@ class Document:
         """
         Is it sensible to reparse this document?
         """
-        if self.docx_exists():
-            return True
-        return False
-
-    class XML:
-        """
-        Represents the XML of a document, and should contain all methods for interacting with it.
-        """
-
-        def __init__(self, xml_bytestring: bytes):
-            """
-            :raises NonXMLDocumentError: This document is not valid XML
-            """
-            try:
-                self.xml_as_tree: etree.Element = etree.fromstring(xml_bytestring)
-            except etree.XMLSyntaxError:
-                raise NonXMLDocumentError
-
-        @property
-        def xml_as_string(self) -> str:
-            """
-            :return: A string representation of this document's XML tree.
-            """
-            return str(etree.tostring(self.xml_as_tree).decode(encoding="utf-8"))
-
-        @property
-        def root_element(self) -> str:
-            return str(self.xml_as_tree.tag)
-
-        def get_xpath_match_string(self, xpath: str, namespaces: Dict[str, str]) -> str:
-            return get_xpath_match_string(self.xml_as_tree, xpath, namespaces)
-
-        def get_xpath_match_strings(
-            self,
-            xpath: str,
-            namespaces: Dict[str, str],
-        ) -> list[str]:
-            return get_xpath_match_strings(self.xml_as_tree, xpath, namespaces)
+        return self.docx_exists()

caselawclient/models/documents/body.py

@@ -0,0 +1,139 @@
+import datetime
+import warnings
+from functools import cached_property
+from typing import Optional
+
+import pytz
+from ds_caselaw_utils.types import CourtCode
+
+from caselawclient.models.utilities.dates import parse_string_date_as_utc
+
+from .xml import XML
+
+
+class UnparsableDate(Warning):
+    pass
+
+
+class DocumentBody:
+    """
+    A class for abstracting out interactions with the body of a document.
+    """
+
+    def __init__(self, xml_bytestring: bytes):
+        self._xml = XML(xml_bytestring=xml_bytestring)
+        """ This is an instance of the `Document.XML` class for manipulation of the XML document itself. """
+
+    def get_xpath_match_string(self, xpath: str, namespaces: dict[str, str]) -> str:
+        return self._xml.get_xpath_match_string(xpath, namespaces)
+
+    @cached_property
+    def name(self) -> str:
+        return self._xml.get_xpath_match_string(
+            "/akn:akomaNtoso/akn:*/akn:meta/akn:identification/akn:FRBRWork/akn:FRBRname/@value",
+            {"akn": "http://docs.oasis-open.org/legaldocml/ns/akn/3.0"},
+        )
+
+    @cached_property
+    def court(self) -> str:
+        return self._xml.get_xpath_match_string(
+            "/akn:akomaNtoso/akn:*/akn:meta/akn:proprietary/uk:court/text()",
+            {
+                "uk": "https://caselaw.nationalarchives.gov.uk/akn",
+                "akn": "http://docs.oasis-open.org/legaldocml/ns/akn/3.0",
+            },
+        )
+
+    @cached_property
+    def jurisdiction(self) -> str:
+        return self._xml.get_xpath_match_string(
+            "/akn:akomaNtoso/akn:*/akn:meta/akn:proprietary/uk:jurisdiction/text()",
+            {
+                "uk": "https://caselaw.nationalarchives.gov.uk/akn",
+                "akn": "http://docs.oasis-open.org/legaldocml/ns/akn/3.0",
+            },
+        )
+
+    @property
+    def court_and_jurisdiction_identifier_string(self) -> CourtCode:
+        if self.jurisdiction != "":
+            return CourtCode("/".join((self.court, self.jurisdiction)))
+        return CourtCode(self.court)
+
+    @cached_property
+    def document_date_as_string(self) -> str:
+        return self._xml.get_xpath_match_string(
+            "/akn:akomaNtoso/akn:*/akn:meta/akn:identification/akn:FRBRWork/akn:FRBRdate/@date",
+            {"akn": "http://docs.oasis-open.org/legaldocml/ns/akn/3.0"},
+        )
+
+    @cached_property
+    def document_date_as_date(self) -> Optional[datetime.date]:
+        if not self.document_date_as_string:
+            return None
+        try:
+            return datetime.datetime.strptime(
+                self.document_date_as_string,
+                "%Y-%m-%d",
+            ).date()
+        except ValueError:
+            warnings.warn(
+                f"Unparsable date encountered: {self.document_date_as_string}",
+                UnparsableDate,
+            )
+            return None
+
+    def get_manifestation_datetimes(
+        self,
+        name: Optional[str] = None,
+    ) -> list[datetime.datetime]:
+        name_filter = f"[@name='{name}']" if name else ""
+        iso_datetimes = self._xml.get_xpath_match_strings(
+            "/akn:akomaNtoso/akn:*/akn:meta/akn:identification/akn:FRBRManifestation"
+            f"/akn:FRBRdate{name_filter}/@date",
+            {"akn": "http://docs.oasis-open.org/legaldocml/ns/akn/3.0"},
+        )
+
+        return [parse_string_date_as_utc(event, pytz.UTC) for event in iso_datetimes]
+
+    def get_latest_manifestation_datetime(
+        self,
+        name: Optional[str] = None,
+    ) -> Optional[datetime.datetime]:
+        events = self.get_manifestation_datetimes(name)
+        if not events:
+            return None
+        return max(events)
+
+    def get_latest_manifestation_type(self) -> Optional[str]:
+        return max(
+            (
+                (type, time)
+                for type in ["transform", "tna-enriched"]
+                if (time := self.get_latest_manifestation_datetime(type))
+            ),
+            key=lambda x: x[1],
+        )[0]
+
+    @cached_property
+    def transformation_datetime(self) -> Optional[datetime.datetime]:
+        """When was this document successfully parsed or reparsed (date from XML)"""
+        return self.get_latest_manifestation_datetime("transform")
+
+    @cached_property
+    def enrichment_datetime(self) -> Optional[datetime.datetime]:
+        """When was this document successfully enriched (date from XML)"""
+        return self.get_latest_manifestation_datetime("tna-enriched")
+
+    @cached_property
+    def content_as_xml(self) -> str:
+        return self._xml.xml_as_string
+
+    @cached_property
+    def failed_to_parse(self) -> bool:
+        """
+        Did this document entirely fail to parse?
+
+        :return: `True` if there was a complete parser failure, otherwise `False`
+        """
+        return "error" in self._xml.root_element

caselawclient/models/documents/exceptions.py

@@ -0,0 +1,6 @@
+class CannotPublishUnpublishableDocument(Exception):
+    """A document which has failed publication safety checks in `Document.is_publishable` cannot be published."""
+
+
+class DocumentNotSafeForDeletion(Exception):
+    """A document which is not safe for deletion cannot be deleted."""

caselawclient/models/documents/statuses.py

@@ -0,0 +1,12 @@
+DOCUMENT_STATUS_HOLD = "On hold"
+""" This document has been placed on hold to actively prevent publication. """
+
+DOCUMENT_STATUS_PUBLISHED = "Published"
+""" This document has been published and should be considered publicly visible. """
+
+DOCUMENT_STATUS_IN_PROGRESS = "In progress"
+""" This document has not been published or put on hold, and has been picked up by an editor and
+    should be progressing through the document pipeline. """
+
+DOCUMENT_STATUS_NEW = "New"
+""" This document isn't published, on hold, or assigned, and can be picked up by an editor in the future. """

caselawclient/models/documents/xml.py

@@ -0,0 +1,43 @@
+from lxml import etree
+
+from caselawclient.xml_helpers import get_xpath_match_string, get_xpath_match_strings
+
+
+class NonXMLDocumentError(Exception):
+    """A document cannot be parsed as XML."""
+
+
+class XML:
+    """
+    A class for interacting with the raw XML of a document.
+    """
+
+    def __init__(self, xml_bytestring: bytes):
+        """
+        :raises NonXMLDocumentError: This document is not valid XML
+        """
+        try:
+            self.xml_as_tree: etree.Element = etree.fromstring(xml_bytestring)
+        except etree.XMLSyntaxError:
+            raise NonXMLDocumentError
+
+    @property
+    def xml_as_string(self) -> str:
+        """
+        :return: A string representation of this document's XML tree.
+        """
+        return str(etree.tostring(self.xml_as_tree).decode(encoding="utf-8"))
+
+    @property
+    def root_element(self) -> str:
+        return str(self.xml_as_tree.tag)
+
+    def get_xpath_match_string(self, xpath: str, namespaces: dict[str, str]) -> str:
+        return get_xpath_match_string(self.xml_as_tree, xpath, namespaces)
+
+    def get_xpath_match_strings(
+        self,
+        xpath: str,
+        namespaces: dict[str, str],
+    ) -> list[str]:
+        return get_xpath_match_strings(self.xml_as_tree, xpath, namespaces)

caselawclient/models/judgments.py

@@ -2,13 +2,14 @@ import importlib
 from functools import cached_property
 from typing import TYPE_CHECKING, Any, Optional
 
+from ds_caselaw_utils.types import NeutralCitationString
+
 from caselawclient.errors import DocumentNotFoundError
 from caselawclient.models.neutral_citation_mixin import NeutralCitationMixin
 
 if TYPE_CHECKING:
     from caselawclient.models.press_summaries import PressSummary
 
-from ..xml_helpers import get_xpath_match_string
 from .documents import Document
 
 
@@ -21,17 +22,18 @@ class Judgment(NeutralCitationMixin, Document):
     document_noun_plural = "judgments"
 
     def __init__(self, *args: Any, **kwargs: Any) -> None:
-        super(Judgment, self).__init__(self.document_noun, *args, **kwargs)
+        super().__init__(self.document_noun, *args, **kwargs)
 
     @cached_property
-    def neutral_citation(self) -> str:
-        return get_xpath_match_string(
-            self.xml.xml_as_tree,
-            "/akn:akomaNtoso/akn:*/akn:meta/akn:proprietary/uk:cite/text()",
-            {
-                "uk": "https://caselaw.nationalarchives.gov.uk/akn",
-                "akn": "http://docs.oasis-open.org/legaldocml/ns/akn/3.0",
-            },
+    def neutral_citation(self) -> NeutralCitationString:
+        return NeutralCitationString(
+            self.body.get_xpath_match_string(
+                "/akn:akomaNtoso/akn:*/akn:meta/akn:proprietary/uk:cite/text()",
+                {
+                    "uk": "https://caselaw.nationalarchives.gov.uk/akn",
+                    "akn": "http://docs.oasis-open.org/legaldocml/ns/akn/3.0",
+                },
+            )
         )
 
     @property

caselawclient/models/neutral_citation_mixin.py

@@ -1,10 +1,12 @@
+from abc import ABC, abstractmethod
 from functools import cached_property
 from typing import Any
 
 from ds_caselaw_utils import neutral_url
+from ds_caselaw_utils.types import NeutralCitationString
 
 
-class NeutralCitationMixin:
+class NeutralCitationMixin(ABC):
     """
     A mixin class that provides functionality related to neutral citation.
 
@@ -35,19 +37,13 @@ class NeutralCitationMixin:
         super(NeutralCitationMixin, self).__init__(*args, **kwargs)
 
     @cached_property
-    def neutral_citation(self) -> str:
-        return ""
+    @abstractmethod
+    def neutral_citation(self) -> NeutralCitationString: ...
 
     @cached_property
     def has_ncn(self) -> bool:
-        if not self.neutral_citation:
-            return False
-
-        return True
+        return bool(self.neutral_citation)
 
     @cached_property
     def has_valid_ncn(self) -> bool:
-        if not self.has_ncn or not neutral_url(self.neutral_citation):
-            return False
-
-        return True
+        return self.has_ncn and neutral_url(self.neutral_citation) is not None

caselawclient/models/press_summaries.py

@@ -4,9 +4,10 @@ import importlib
 from functools import cached_property
 from typing import TYPE_CHECKING, Any, Optional
 
+from ds_caselaw_utils.types import NeutralCitationString
+
 from caselawclient.errors import DocumentNotFoundError
 from caselawclient.models.neutral_citation_mixin import NeutralCitationMixin
-from caselawclient.xml_helpers import get_xpath_match_string
 
 from .documents import Document
 
@@ -23,16 +24,17 @@ class PressSummary(NeutralCitationMixin, Document):
     document_noun_plural = "press summaries"
 
     def __init__(self, *args: Any, **kwargs: Any) -> None:
-        super(PressSummary, self).__init__(self.document_noun, *args, **kwargs)
+        super().__init__(self.document_noun, *args, **kwargs)
 
     @cached_property
-    def neutral_citation(self) -> str:
-        return get_xpath_match_string(
-            self.xml.xml_as_tree,
-            "/akn:akomaNtoso/akn:doc/akn:preface/akn:p/akn:neutralCitation/text()",
-            {
-                "akn": "http://docs.oasis-open.org/legaldocml/ns/akn/3.0",
-            },
+    def neutral_citation(self) -> NeutralCitationString:
+        return NeutralCitationString(
+            self.body.get_xpath_match_string(
+                "/akn:akomaNtoso/akn:doc/akn:preface/akn:p/akn:neutralCitation/text()",
+                {
+                    "akn": "http://docs.oasis-open.org/legaldocml/ns/akn/3.0",
+                },
+            )
         )
 
     @property

caselawclient/models/utilities/aws.py

@@ -249,6 +249,8 @@ def request_parse(
         },
     }
 
+    # breakpoint()
+
     client.publish(
         TopicArn=env("REPARSE_SNS_TOPIC"),
         Message=json.dumps(message_to_send),

caselawclient/models/utilities/dates.py

@@ -9,11 +9,7 @@ def parse_string_date_as_utc(iso_string: str, timezone: tzinfo.BaseTzInfo) -> da
     ensure that it is converted to a UTC-aware datetime"""
 
     mixed_date = isoparse(iso_string)
-    if not mixed_date.tzinfo:
-        # it is an unaware time
-        aware_date = timezone.localize(mixed_date)
-    else:
-        aware_date = mixed_date
+    aware_date = mixed_date if mixed_date.tzinfo else timezone.localize(mixed_date)
 
     # make UTC
     utc_date = aware_date.astimezone(UTC)

caselawclient/models/utilities/move.py

@@ -1,16 +1,17 @@
-from typing import Any, Optional
+from typing import TYPE_CHECKING, Any, Optional
 
 import ds_caselaw_utils as caselawutils
+from ds_caselaw_utils.types import NeutralCitationString
 
 from caselawclient.errors import MarklogicAPIError
+from caselawclient.models.documents import DocumentURIString
 from caselawclient.models.utilities.aws import copy_assets
 
-
-class NeutralCitationToUriError(Exception):
-    pass
+if TYPE_CHECKING:
+    from caselawclient.Client import MarklogicApiClient
 
 
-class OverwriteJudgmentError(Exception):
+class NeutralCitationToUriError(Exception):
     pass
 
 
@@ -18,62 +19,9 @@ class MoveJudgmentError(Exception):
     pass
 
 
-def overwrite_document(
-    source_uri: str,
-    target_citation: str,
-    api_client: Any,
-) -> str:
-    """Move the document at source_uri on top of the new citation, which must already exist
-    Compare to update_document_uri
-
-    :param source_uri: The URI with the contents of the document to be written. (possibly a failure url)
-    :param target_citation: The NCN (implying a URL) whose contents will be overwritten
-    :param api_client: An instance of MarklogicApiClient used to make the search request
-    :return: The URL associated with the `target_citation`
-    """
-
-    new_uri: Optional[str] = caselawutils.neutral_url(target_citation.strip())
-
-    if new_uri == source_uri:
-        raise RuntimeError(
-            f"Attempted to overwrite document {source_uri} with itself, which is not permitted.",
-        )
-    if new_uri is None:
-        raise NeutralCitationToUriError(
-            f"Unable to form new URI for {source_uri} from neutral citation: {target_citation}",
-        )
-    if not api_client.document_exists(new_uri):
-        raise OverwriteJudgmentError(
-            f"The URI {new_uri} generated from {target_citation} does not already exist, so cannot be overwritten",
-        )
-    old_doc = api_client.get_document_by_uri_or_404(source_uri)
-    try:
-        old_doc_xml = old_doc.content_as_xml
-        api_client.update_document_xml(
-            new_uri,
-            old_doc_xml,
-            annotation=f"overwritten from {source_uri}",
-        )
-        set_metadata(source_uri, new_uri, api_client)
-        # TODO: consider deleting existing public assets at that location
-        copy_assets(source_uri, new_uri)
-        api_client.set_judgment_this_uri(new_uri)
-    except MarklogicAPIError as e:
-        raise OverwriteJudgmentError(
-            f"Failure when attempting to copy judgment from {source_uri} to {new_uri}: {e}",
-        )
-
-    try:
-        api_client.delete_judgment(source_uri)
-    except MarklogicAPIError as e:
-        raise OverwriteJudgmentError(
-            f"Failure when attempting to delete judgment from {source_uri}: {e}",
-        )
-
-    return new_uri
-
-
-def update_document_uri(source_uri: str, target_citation: str, api_client: Any) -> str:
+def update_document_uri(
+    source_uri: DocumentURIString, target_citation: NeutralCitationString, api_client: "MarklogicApiClient"
+) -> DocumentURIString:
     """
     Move the document at source_uri to the correct location based on the neutral citation
     The new neutral citation *must* not already exist (that is handled elsewhere)
@@ -83,7 +31,8 @@ def update_document_uri(source_uri: str, target_citation: str, api_client: Any)
     :param api_client: An instance of MarklogicApiClient used to make the search request
     :return: The URL associated with the `target_citation`
     """
-    new_uri: Optional[str] = caselawutils.neutral_url(target_citation.strip())
+    new_ncn_based_uri = caselawutils.neutral_url(target_citation)
+    new_uri: Optional[DocumentURIString] = DocumentURIString(new_ncn_based_uri) if new_ncn_based_uri else None
     if new_uri is None:
         raise NeutralCitationToUriError(
             f"Unable to form new URI for {source_uri} from neutral citation: {target_citation}",
@@ -115,7 +64,7 @@ def update_document_uri(source_uri: str, target_citation: str, api_client: Any)
     return new_uri
 
 
-def set_metadata(old_uri: str, new_uri: str, api_client: Any) -> None:
+def set_metadata(old_uri: DocumentURIString, new_uri: DocumentURIString, api_client: Any) -> None:
     source_organisation = api_client.get_property(old_uri, "source-organisation")
     source_name = api_client.get_property(old_uri, "source-name")
     source_email = api_client.get_property(old_uri, "source-email")

caselawclient/responses/search_response.py

@@ -24,13 +24,13 @@ class SearchResponse:
         self.client = client
 
     @property
-    def total(self) -> str:
+    def total(self) -> int:
         """
         The total number of search results.
 
         :return: The total number of search results
         """
-        return str(
+        return int(
             self.node.xpath("//search:response/@total", namespaces=self.NAMESPACES)[0],
         )
 

caselawclient/responses/search_result.py

@@ -8,6 +8,7 @@ from typing import Dict, Optional
 from dateutil import parser as dateparser
 from dateutil.parser import ParserError
 from ds_caselaw_utils.courts import Court, CourtNotFoundException, courts
+from ds_caselaw_utils.types import CourtCode, JurisdictionCode
 from lxml import etree
 
 from caselawclient.Client import MarklogicApiClient
@@ -193,15 +194,16 @@ class SearchResult:
         """
         :return: The court of the search result
         """
-        court = None
+        court: Optional[Court] = None
         court_code = self._get_xpath_match_string("search:extracted/uk:court/text()")
         jurisdiction_code = self._get_xpath_match_string(
             "search:extracted/uk:jurisdiction/text()",
         )
         if jurisdiction_code:
-            court_code_with_jurisdiction = "%s/%s" % (court_code, jurisdiction_code)
             try:
-                court = courts.get_by_code(court_code_with_jurisdiction)
+                court = courts.get_court_with_jurisdiction_by_code(
+                    CourtCode(court_code), JurisdictionCode(jurisdiction_code)
+                )
             except CourtNotFoundException:
                 logging.warning(
                     "Court not found with court code %s and jurisdiction code %s for judgment with NCN %s, falling back to court."
@@ -209,7 +211,7 @@ class SearchResult:
                 )
         if court is None:
             try:
-                court = courts.get_by_code(court_code)
+                court = courts.get_by_code(CourtCode(court_code))
             except CourtNotFoundException:
                 logging.warning(
                     "Court not found with court code %s for judgment with NCN %s, returning None."

{ds_caselaw_marklogic_api_client-25.0.0.dist-info → ds_caselaw_marklogic_api_client-27.0.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: ds-caselaw-marklogic-api-client
-Version: 25.0.0
+Version: 27.0.0
 Summary: An API client for interacting with the underlying data in Find Caselaw.
 Home-page: https://github.com/nationalarchives/ds-caselaw-custom-api-client
 Keywords: national archives,caselaw
@@ -14,7 +14,7 @@ Requires-Dist: boto3 (>=1.26.112,<2.0.0)
 Requires-Dist: certifi (>=2024.8.30,<2024.9.0)
 Requires-Dist: charset-normalizer (>=3.0.0,<4.0.0)
 Requires-Dist: django-environ (>=0.11.0,<0.12.0)
-Requires-Dist: ds-caselaw-utils (>=1.4.1,<2.0.0)
+Requires-Dist: ds-caselaw-utils (>=2.0.0,<3.0.0)
 Requires-Dist: idna (>=3.4,<4.0)
 Requires-Dist: lxml (>=5.0.0,<6.0.0)
 Requires-Dist: memoization (>=0.4.0,<0.5.0)

{ds_caselaw_marklogic_api_client-25.0.0.dist-info → ds_caselaw_marklogic_api_client-27.0.0.dist-info}/RECORD

@@ -1,22 +1,27 @@
-caselawclient/Client.py,sha256=_eSIWdzyfpPspyoEjuGI7uEx2yQlWMMRYWKIvZFo2Nk,40459
+caselawclient/Client.py,sha256=9tNNo_-qNxIn5E3OUJLg3apVvUie8VfyRfPmnzeqc-0,40182
 caselawclient/__init__.py,sha256=DY-caubLDQWWingSdsBWgovDNXh8KcnkI6kwz08eIFk,612
 caselawclient/client_helpers/__init__.py,sha256=fyDNKCdrTb2N0Ks23YDhmvlXKfLTHnYQCXhnZb-QQbg,3832
 caselawclient/client_helpers/search_helpers.py,sha256=R99HyRLeYHgsw2L3DOidEqlKLLvs6Tga5rKTuWQViig,1525
 caselawclient/content_hash.py,sha256=0cPC4OoABq0SC2wYFX9-24DodNigeOqksDxgxQH_hUA,2221
 caselawclient/errors.py,sha256=tV0vs3wYSd331BzmfuRiZV6GAdsd91rtN65ymRaSx3s,3164
+caselawclient/factories.py,sha256=nmKJLlTH5tN6sDCBz3abgJdGnzQlaPXIOm8aBgTZTaU,5260
 caselawclient/models/__init__.py,sha256=kd23EUpvaC7aLHdgk8farqKAQEx3lf7RvNT2jEatvlg,68
-caselawclient/models/documents.py,sha256=Md7oGmgehf6qHdB3ewGAVXSM_6wF3QE8Ds3Fv1kZG1s,22912
-caselawclient/models/judgments.py,sha256=IsQrllb9GqY_vl_gwIkNJhH6FK3W7srhcmo0zjxiRlQ,1681
-caselawclient/models/neutral_citation_mixin.py,sha256=cEQXq1bWaiu3Sy3QWyK5IesrMS186Kw5-CFfuVqnB-A,1730
-caselawclient/models/press_summaries.py,sha256=L8G3qmnlVt1wpCeAhX9M_Clwh119tr5MN8y-96bEehg,1665
+caselawclient/models/documents/__init__.py,sha256=EwfkYMr5HnmdtxijKwU6AV27Y4JAmobdNHL9Cp--bBs,16624
+caselawclient/models/documents/body.py,sha256=0o8qL7oJ40VikNAgqS41phQyB8Jtfz93eK1KyR4k3F0,4791
+caselawclient/models/documents/exceptions.py,sha256=Mz1P8uNqf5w6uLnRwJt6xK7efsVqtd5VA-WXUUH7QLk,285
+caselawclient/models/documents/statuses.py,sha256=Cp4dTQmJOtsU41EJcxy5dV1841pGD2PNWH0VrkDEv4Q,579
+caselawclient/models/documents/xml.py,sha256=afEsgcnTThqW_gKYq-VGtFr4ovOoT2J7h2gXX7F8BbE,1267
+caselawclient/models/judgments.py,sha256=SuCNtOD4LElp37df4dvhaD0umTowioWH0sZNmBgFsoE,1739
+caselawclient/models/neutral_citation_mixin.py,sha256=5ktKCPIDidVRwxVTzx5e242O1BxOdP--1dnatZyTbYI,1773
+caselawclient/models/press_summaries.py,sha256=ZJ5ZhamPTsj6-vO1g96aP_syzUC2RlLMhgr3xnI1PoM,1703
 caselawclient/models/utilities/__init__.py,sha256=aL1a2nDacPxninETeaVZKwOxZemgvm73IcpWgMNXoGc,1100
-caselawclient/models/utilities/aws.py,sha256=-Ews5k_IGvlXXvPTtpJbavw2k7GpFeRXEvENBifVwh8,8053
-caselawclient/models/utilities/dates.py,sha256=f1ai7WiGELdqdiyFQ7gGjCXFO6sxz5g5hfc2_HRNNvE,563
-caselawclient/models/utilities/move.py,sha256=Xi2uPzruMp_-40Z5pWcSd3AN6C9iiAj6A1YqZHjgeaI,5390
+caselawclient/models/utilities/aws.py,sha256=YQeuFdF5NvhUxo3Ejj3PURDlygA73oq2T42ltuQZ6Oo,8073
+caselawclient/models/utilities/dates.py,sha256=WwORxVjUHM1ZFcBF6Qtwo3Cj0sATsnSECkUZ6ls1N1Q,492
+caselawclient/models/utilities/move.py,sha256=Rsx1eGHVjbGz0WMVDjy8b_5t4Ig8aP55sLudL07MVUs,3621
 caselawclient/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 caselawclient/responses/__init__.py,sha256=2-5NJn_PXPTje_W4dHeHYaNRN6vXK4UcB9eLLNUAKa4,67
-caselawclient/responses/search_response.py,sha256=mULNqqKGKOKIgXYYMRjCRm4THCcpPfrGq7Co3VYhaDk,1951
-caselawclient/responses/search_result.py,sha256=P0vOLqQ-ijKkOrpbpO8sTcOupSbgnyXBdvgK0h1UN8I,8118
+caselawclient/responses/search_response.py,sha256=Z76Zj4VvM-EV_vdiehv2-Jfkr9HZD3SvCTlRrUB_cyE,1951
+caselawclient/responses/search_result.py,sha256=2yR3FP4CQsVymE7RrOMbh1owjYaRTrqkjMObbIkSlhE,8216
 caselawclient/responses/xsl/search_match.xsl,sha256=4Sv--MrwBd7J48E9aI7jlFSXGlNi4dBqgzJ3bdMJ_ZU,1018
 caselawclient/search_parameters.py,sha256=nR-UC1aWZbdXzXBrVDaHECU4Ro8Zi4JZATtgrpAVsKY,3342
 caselawclient/xml_helpers.py,sha256=qmqdGhwrQ-zhvvB-8akwzWnC2uHponKkEnnRExqkx_A,591
@@ -60,7 +65,7 @@ caselawclient/xquery/validate_document.xqy,sha256=PgaDcnqCRJPIVqfmWsNlXmCLNKd21q
 caselawclient/xquery/xslt.xqy,sha256=w57wNijH3dkwHkpKeAxqjlghVflQwo8cq6jS_sm-erM,199
 caselawclient/xquery/xslt_transform.xqy,sha256=smyFFxqmtkuOzBd2l7uw6K2oAsYctudrP8omdv_XNAM,2463
 caselawclient/xquery_type_dicts.py,sha256=YOrXbEYJU84S-YwergCI12OL5Wrn_wpqMcqWpsQrKek,5590
-ds_caselaw_marklogic_api_client-25.0.0.dist-info/LICENSE.md,sha256=fGMzyyLuQW-IAXUeDSCrRdsYW536aEWThdbpCjo6ZKg,1108
-ds_caselaw_marklogic_api_client-25.0.0.dist-info/METADATA,sha256=jKozrLyhJGMqq2OGxyplet-HzwHiRpWjjfV1V0pyF-A,4189
-ds_caselaw_marklogic_api_client-25.0.0.dist-info/WHEEL,sha256=7Z8_27uaHI_UZAc4Uox4PpBhQ9Y5_modZXWMxtUi4NU,88
-ds_caselaw_marklogic_api_client-25.0.0.dist-info/RECORD,,
+ds_caselaw_marklogic_api_client-27.0.0.dist-info/LICENSE.md,sha256=fGMzyyLuQW-IAXUeDSCrRdsYW536aEWThdbpCjo6ZKg,1108
+ds_caselaw_marklogic_api_client-27.0.0.dist-info/METADATA,sha256=miZ3RSM382gJvUf0AH3Xe9Y5yzEqF3r4OkIDj5rXiZg,4189
+ds_caselaw_marklogic_api_client-27.0.0.dist-info/WHEEL,sha256=7Z8_27uaHI_UZAc4Uox4PpBhQ9Y5_modZXWMxtUi4NU,88
+ds_caselaw_marklogic_api_client-27.0.0.dist-info/RECORD,,