ds-caselaw-marklogic-api-client 40.0.0__py3-none-any.whl → 43.1.0__py3-none-any.whl

caselawclient/Client.py

@@ -21,19 +21,20 @@ from requests.structures import CaseInsensitiveDict
 from requests_toolbelt.multipart import decoder
 
 from caselawclient import xquery_type_dicts as query_dicts
-from caselawclient.client_helpers import VersionAnnotation
 from caselawclient.identifier_resolution import IdentifierResolutions
 from caselawclient.models.documents import (
     DOCUMENT_COLLECTION_URI_JUDGMENT,
     DOCUMENT_COLLECTION_URI_PRESS_SUMMARY,
     Document,
 )
+from caselawclient.models.documents.versions import VersionAnnotation
 from caselawclient.models.judgments import Judgment
 from caselawclient.models.press_summaries import PressSummary
 from caselawclient.models.utilities import move
 from caselawclient.search_parameters import SearchParameters
 from caselawclient.types import DocumentIdentifierSlug, DocumentIdentifierValue, DocumentURIString
 from caselawclient.xquery_type_dicts import (
+    CheckContentHashUniqueByUriDict,
     MarkLogicDocumentURIString,
     MarkLogicDocumentVersionURIString,
     MarkLogicPrivilegeURIString,
@@ -728,6 +729,14 @@ class MarklogicApiClient:
             == 0
         )
 
+    def has_unique_content_hash(self, judgment_uri: DocumentURIString) -> bool:
+        """
+        Returns True if the content hash for this document is unique (not shared with other documents).
+        """
+        uri = self._format_uri_for_marklogic(judgment_uri)
+        vars: CheckContentHashUniqueByUriDict = {"uri": uri}
+        return self._eval_and_decode(vars, "check_content_hash_unique_by_uri.xqy") == "true"
+
     def eval(
         self,
         xquery_path: str,
@@ -793,6 +802,8 @@ class MarklogicApiClient:
         :param judge:
         :param party:
         :param neutral_citation:
+        :param document_name:
+        :param consignment_number:
         :param specific_keyword:
         :param order:
         :param date_from:

caselawclient/client_helpers/__init__.py

@@ -1,9 +1,4 @@
-import json
-from enum import Enum
-from typing import Any, Optional, TypedDict
-
 from lxml import etree
-from typing_extensions import NotRequired
 
 from caselawclient.xml_helpers import DEFAULT_NAMESPACES
 
@@ -17,115 +12,6 @@ class CannotDetermineDocumentType(Exception):
     pass
 
 
-class AnnotationDataDict(TypedDict):
-    type: str
-    calling_function: str
-    calling_agent: str
-    message: NotRequired[str]
-    payload: NotRequired[dict[str, Any]]
-    automated: bool
-
-
-class VersionType(Enum):
-    """Valid types of version."""
-
-    SUBMISSION = "submission"
-    """ This version has been created as a result of a submission of a new document. """
-
-    ENRICHMENT = "enrichment"
-    """ This version has been created through an enrichment process. """
-
-    EDIT = "edit"
-    """ This version has been created as the result of a manual edit. """
-
-
-class VersionAnnotation:
-    """A class holding structured data about the reason for a version."""
-
-    def __init__(
-        self,
-        version_type: VersionType,
-        automated: bool,
-        message: Optional[str] = None,
-        payload: Optional[dict[str, Any]] = None,
-    ):
-        """
-        :param version_type: The type of version being created
-        :param automated: `True` if this action has happened as the result of an automated process, rather than a human
-            action
-        :param message: A human-readable string containing information about the version which can't be expressed in the
-            structured data.
-        :param payload: A dict containing additional information relevant to this version change
-        """
-        self.version_type = version_type
-        self.automated = automated
-        self.message = message
-        self.payload = payload
-
-        self.calling_function: Optional[str] = None
-        self.calling_agent: Optional[str] = None
-
-    def set_calling_function(self, calling_function: str) -> None:
-        """
-        Set the name of the calling function for tracing purposes
-
-        :param calling_function: The name of the function which is performing the database write
-        """
-        self.calling_function = calling_function
-
-    def set_calling_agent(self, calling_agent: str) -> None:
-        """
-        Set the name of the calling agent for tracing purposes
-
-        :param calling_agent: The name of the agent which is performing the database write
-        """
-        self.calling_agent = calling_agent
-
-    @property
-    def structured_annotation_dict(self) -> AnnotationDataDict:
-        """
-        :return: A structured dict representing this `VersionAnnotation`
-
-        :raises AttributeError: The name of the calling function has not been set; use `set_calling_function()`
-        :raises AttributeError: The name of the calling agent has not been set; use `set_calling_agent()`
-        """
-        if not self.calling_function:
-            raise AttributeError(
-                "The name of the calling function has not been set; use set_calling_function()",
-            )
-
-        if not self.calling_agent:
-            raise AttributeError(
-                "The name of the calling agent has not been set; use set_calling_agent()",
-            )
-
-        annotation_data: AnnotationDataDict = {
-            "type": self.version_type.value,
-            "calling_function": self.calling_function,
-            "calling_agent": self.calling_agent,
-            "automated": self.automated,
-        }
-
-        if self.message:
-            annotation_data["message"] = self.message
-
-        if self.payload:
-            annotation_data["payload"] = self.payload
-
-        return annotation_data
-
-    @property
-    def as_json(self) -> str:
-        """Render the structured annotation data as JSON, so it can be stored in the MarkLogic dls:annotation field.
-
-        :return: A JSON string representing this `VersionAnnotation`"""
-
-        return json.dumps(self.structured_annotation_dict)
-
-    def __str__(self) -> str:
-        return self.as_json
-
-
 def get_document_type_class(xml: bytes) -> type[Document]:
     """Attempt to get the type of the document based on the top-level structure of the XML document."""
 

caselawclient/factories.py

@@ -61,6 +61,8 @@ class DocumentFactory:
         "source_name": "Example Uploader",
         "source_email": "uploader@example.com",
         "consignment_reference": "TDR-12345",
+        "first_published_datetime": None,
+        "has_ever_been_published": False,
         "assigned_to": "",
         "versions": [],
     }

caselawclient/managers/merge/__init__.py

@@ -0,0 +1,51 @@
+import caselawclient.managers.merge.checks as checks
+from caselawclient.models.documents import Document
+from caselawclient.types import SuccessFailureMessageTuple
+
+
+def _combine_list_of_successfailure_results(
+    validations: list[SuccessFailureMessageTuple],
+) -> SuccessFailureMessageTuple:
+    """Given a list of SuccessFailureMessageTuples, combine the success/failure states and any messages into a single new object representing the overall success/failure state."""
+    success = True
+    messages: list[str] = []
+
+    for validation in validations:
+        if validation.success is False:
+            success = False
+
+        messages += validation.messages
+
+    return SuccessFailureMessageTuple(success, messages)
+
+
+class MergeManager:
+    @classmethod
+    def check_document_is_safe_as_merge_source(cls, source_document: Document) -> SuccessFailureMessageTuple:
+        """
+        Is the given document safe to be considered as a merge source?
+        """
+
+        return _combine_list_of_successfailure_results(
+            [
+                checks.check_document_is_not_version(source_document),
+                checks.check_document_has_only_one_version(source_document),
+                checks.check_document_has_never_been_published(source_document),
+                checks.check_document_is_safe_to_delete(source_document),
+            ]
+        )
+
+    @classmethod
+    def check_source_document_is_safe_to_merge_into_target(
+        cls, source_document: Document, target_document: Document
+    ) -> SuccessFailureMessageTuple:
+        """Is the given source document safe to merge into a given target?"""
+
+        return _combine_list_of_successfailure_results(
+            [
+                checks.check_documents_are_not_same_document(source_document, target_document),
+                checks.check_document_is_not_version(target_document),
+                checks.check_documents_are_same_type(source_document, target_document),
+                checks.check_source_document_is_newer_than_target(source_document, target_document),
+            ]
+        )

caselawclient/managers/merge/checks.py

@@ -0,0 +1,79 @@
+from caselawclient.models.documents import Document
+from caselawclient.types import SuccessFailureMessageTuple
+
+
+def check_document_is_not_version(document: Document) -> SuccessFailureMessageTuple:
+    """Check that the document URI isn't a specific version"""
+    if document.is_version:
+        return SuccessFailureMessageTuple(
+            False,
+            ["This document is a specific version, and cannot be used as a merge source"],
+        )
+
+    return SuccessFailureMessageTuple(True, [])
+
+
+def check_document_has_only_one_version(document: Document) -> SuccessFailureMessageTuple:
+    """Make sure the document has exactly one version."""
+    if len(document.versions) > 1:
+        return SuccessFailureMessageTuple(
+            False,
+            ["This document has more than one version"],
+        )
+
+    return SuccessFailureMessageTuple(True, [])
+
+
+def check_document_has_never_been_published(document: Document) -> SuccessFailureMessageTuple:
+    """Make sure the document has never been published."""
+    if document.has_ever_been_published:
+        return SuccessFailureMessageTuple(
+            False,
+            ["This document has previously been published"],
+        )
+
+    return SuccessFailureMessageTuple(True, [])
+
+
+def check_document_is_safe_to_delete(document: Document) -> SuccessFailureMessageTuple:
+    """Make sure the document is safe to delete."""
+    if not document.safe_to_delete:
+        return SuccessFailureMessageTuple(
+            False,
+            ["This document cannot be deleted because it is published"],
+        )
+
+    return SuccessFailureMessageTuple(True, [])
+
+
+def check_documents_are_not_same_document(document_one: Document, document_two: Document) -> SuccessFailureMessageTuple:
+    """Check that two documents aren't actually the same"""
+    if document_one.uri == document_two.uri:
+        return SuccessFailureMessageTuple(
+            False,
+            ["You cannot merge a document with itself"],
+        )
+    return SuccessFailureMessageTuple(True, [])
+
+
+def check_documents_are_same_type(document_one: Document, document_two: Document) -> SuccessFailureMessageTuple:
+    """Check to see if this document is the same type as a target document."""
+    if type(document_one) is not type(document_two):
+        return SuccessFailureMessageTuple(
+            False,
+            [
+                f"The type of {document_one.uri} ({type(document_one).document_noun}) does not match the type of {document_two.uri} ({type(document_two).document_noun})"
+            ],
+        )
+    return SuccessFailureMessageTuple(True, [])
+
+
+def check_source_document_is_newer_than_target(
+    source_document: Document, target_document: Document
+) -> SuccessFailureMessageTuple:
+    """Check to see if the created datetime of the latest version of this document is newer than the created datetime of the latest version of a target document."""
+    if source_document.version_created_datetime < target_document.version_created_datetime:
+        return SuccessFailureMessageTuple(
+            False, [f"The document at {source_document.uri} is older than the latest version of {target_document.uri}"]
+        )
+    return SuccessFailureMessageTuple(True, [])

caselawclient/models/documents/__init__.py

@@ -7,6 +7,7 @@ from typing import TYPE_CHECKING, Any, Optional
 from ds_caselaw_utils import courts
 from ds_caselaw_utils.courts import CourtNotFoundException
 from ds_caselaw_utils.types import NeutralCitationString
+from pydantic import TypeAdapter
 from requests_toolbelt.multipart import decoder
 
 import caselawclient.models.documents.comparison as comparison
@@ -16,6 +17,7 @@ from caselawclient.errors import (
     OnlySupportedOnVersion,
 )
 from caselawclient.identifier_resolution import IdentifierResolutions
+from caselawclient.models.documents.versions import AnnotationDataDict
 from caselawclient.models.identifiers import Identifier
 from caselawclient.models.identifiers.exceptions import IdentifierValidationException
 from caselawclient.models.identifiers.fclid import FindCaseLawIdentifier, FindCaseLawIdentifierSchema
@@ -95,6 +97,11 @@ class Document:
             True,
             "The court for this {document_noun} is not valid",
         ),
+        (
+            "has_unique_content_hash",
+            True,
+            "There is another document with identical content",
+        ),
     ]
     """
     A list of tuples in the form:
@@ -307,10 +314,37 @@ class Document:
 
     @cached_property
     def first_published_datetime(self) -> Optional[datetime.datetime]:
+        """
+        Return the database value for the date and time this document was first published.
+
+        :return: The datetime value in the database for "first published".
+        """
         return self.api_client.get_datetime_property(self.uri, "first_published_datetime")
 
+    @cached_property
+    def first_published_datetime_display(self) -> Optional[datetime.datetime]:
+        """
+        Return the display value for the date and time this document was first published.
+
+        A value of 1970-01-01 00:00 indicates that the document has been published previously, but the exact date and time is unknown. In this case, return `None`. This can be used alongside `has_ever_been_published` to indicate an "unknown" state.
+
+        :return: The datetime value to be displayed to end users for "first published".
+        """
+
+        if self.first_published_datetime == datetime.datetime(1970, 1, 1, 0, 0, tzinfo=datetime.timezone.utc):
+            return None
+
+        return self.first_published_datetime
+
     @cached_property
     def has_ever_been_published(self) -> bool:
+        """
+        Do we consider this document to have ever been published?
+
+        This is `True` if either the document is currently published, or if `first_published_datetime` has any value (including the sentinel value).
+
+        :return: A boolean indicating if the document has ever been published.
+        """
         return self.is_published or self.first_published_datetime is not None
 
     @cached_property
@@ -325,6 +359,17 @@ class Document:
     def annotation(self) -> str:
         return self.api_client.get_version_annotation(self.uri)
 
+    @cached_property
+    def structured_annotation(self) -> AnnotationDataDict:
+        annotation_data_dict_loader = TypeAdapter(AnnotationDataDict)
+
+        return annotation_data_dict_loader.validate_json(self.annotation)
+
+    @cached_property
+    def has_unique_content_hash(self) -> bool:
+        """Check if the content hash of this document is unique compared to all other documents in MarkLogic."""
+        return self.api_client.has_unique_content_hash(self.uri)
+
     @cached_property
     def version_created_datetime(self) -> datetime.datetime:
         return self.api_client.get_version_created_datetime(self.uri)
@@ -540,14 +585,14 @@ class Document:
         """
         Is it sensible to reparse this document?
         """
-        return self.docx_exists()
+        return self.docx_exists() and not self.body.has_external_data
 
     @cached_property
     def can_enrich(self) -> bool:
         """
         Is it possible to enrich this document?
         """
-        return self.body.has_content
+        return self.body.has_content and not self.body.has_external_data
 
     def validate_identifiers(self) -> SuccessFailureMessageTuple:
         return self.identifiers.perform_all_validations(document_type=type(self), api_client=self.api_client)

caselawclient/models/documents/body.py

@@ -6,9 +6,11 @@ from typing import Optional
 
 import pytz
 from ds_caselaw_utils.types import CourtCode
+from lxml import etree
 from saxonche import PySaxonProcessor
 
 from caselawclient.models.utilities.dates import parse_string_date_as_utc
+from caselawclient.types import DocumentCategory
 
 from .xml import XML
 
@@ -37,6 +39,9 @@ class DocumentBody:
     def get_xpath_match_strings(self, xpath: str, namespaces: dict[str, str] = DEFAULT_NAMESPACES) -> list[str]:
         return self._xml.get_xpath_match_strings(xpath, namespaces)
 
+    def get_xpath_nodes(self, xpath: str, namespaces: dict[str, str] = DEFAULT_NAMESPACES) -> list[etree._Element]:
+        return self._xml.get_xpath_nodes(xpath, namespaces)
+
     @cached_property
     def name(self) -> str:
         return self.get_xpath_match_string(
@@ -51,9 +56,46 @@ class DocumentBody:
     def jurisdiction(self) -> str:
         return self.get_xpath_match_string("/akn:akomaNtoso/akn:*/akn:meta/akn:proprietary/uk:jurisdiction/text()")
 
+    @cached_property
+    def categories(self) -> list[DocumentCategory]:
+        xpath = "/akn:akomaNtoso/akn:*/akn:meta/akn:proprietary/uk:category"
+        nodes = self.get_xpath_nodes(xpath, DEFAULT_NAMESPACES)
+
+        categories: dict[str, DocumentCategory] = {}
+        children_map: dict[str, list[DocumentCategory]] = {}
+
+        for node in nodes:
+            name = node.text
+            if name is None or not name.strip():
+                continue
+
+            category = DocumentCategory(name=name)
+            categories[name] = category
+
+            parent = node.get("parent")
+
+            if parent:
+                children_map.setdefault(parent, []).append(category)
+
+        for parent, subcategories in children_map.items():
+            if parent in categories:
+                categories[parent].subcategories.extend(subcategories)
+
+        top_level_categories = [
+            categories[name]
+            for node in nodes
+            if node.get("parent") is None
+            if (name := node.text) and name in categories
+        ]
+
+        return top_level_categories
+
+    # NOTE: Deprecated - use categories function
     @cached_property
     def category(self) -> Optional[str]:
-        return self.get_xpath_match_string("/akn:akomaNtoso/akn:*/akn:meta/akn:proprietary/uk:category/text()")
+        return self.get_xpath_match_string(
+            "/akn:akomaNtoso/akn:*/akn:meta/akn:proprietary/uk:category[not(@parent)][1]/text()"
+        )
 
     @cached_property
     def case_number(self) -> Optional[str]:
@@ -144,6 +186,13 @@ class DocumentBody:
 
         return False
 
+    @cached_property
+    def has_external_data(self) -> bool:
+        """Is there data which is not present within the source document:
+        is there a spreadsheet which has populated some fields. The current implementation
+        "is there a uk:party tag" is intended as a stopgap whilst we're not importing that data."""
+        return bool(self._xml.xml_as_tree.xpath("//uk:party", namespaces=DEFAULT_NAMESPACES))
+
     @cache
     def content_html(self, image_prefix: str) -> Optional[str]:
         """Convert the XML representation of the Document into HTML for rendering."""

caselawclient/models/documents/versions.py

@@ -0,0 +1,114 @@
+import json
+from enum import Enum
+from typing import Any, Optional, TypedDict
+
+from typing_extensions import NotRequired
+
+
+class AnnotationDataDict(TypedDict):
+    type: str
+    calling_function: str
+    calling_agent: str
+    message: NotRequired[str]
+    payload: NotRequired[dict[str, Any]]
+    automated: bool
+
+
+class VersionType(Enum):
+    """Valid types of version."""
+
+    SUBMISSION = "submission"
+    """ This version has been created as a result of a submission of a new document. """
+
+    ENRICHMENT = "enrichment"
+    """ This version has been created through an enrichment process. """
+
+    EDIT = "edit"
+    """ This version has been created as the result of a manual edit. """
+
+
+class VersionAnnotation:
+    """A class holding structured data about the reason for a version."""
+
+    def __init__(
+        self,
+        version_type: VersionType,
+        automated: bool,
+        message: Optional[str] = None,
+        payload: Optional[dict[str, Any]] = None,
+    ):
+        """
+        :param version_type: The type of version being created
+        :param automated: `True` if this action has happened as the result of an automated process, rather than a human
+            action
+        :param message: A human-readable string containing information about the version which can't be expressed in the
+            structured data.
+        :param payload: A dict containing additional information relevant to this version change
+        """
+        self.version_type = version_type
+        self.automated = automated
+        self.message = message
+        self.payload = payload
+
+        self.calling_function: Optional[str] = None
+        self.calling_agent: Optional[str] = None
+
+    def set_calling_function(self, calling_function: str) -> None:
+        """
+        Set the name of the calling function for tracing purposes
+
+        :param calling_function: The name of the function which is performing the database write
+        """
+        self.calling_function = calling_function
+
+    def set_calling_agent(self, calling_agent: str) -> None:
+        """
+        Set the name of the calling agent for tracing purposes
+
+        :param calling_agent: The name of the agent which is performing the database write
+        """
+        self.calling_agent = calling_agent
+
+    @property
+    def structured_annotation_dict(self) -> AnnotationDataDict:
+        """
+        :return: A structured dict representing this `VersionAnnotation`
+
+        :raises AttributeError: The name of the calling function has not been set; use `set_calling_function()`
+        :raises AttributeError: The name of the calling agent has not been set; use `set_calling_agent()`
+        """
+        if not self.calling_function:
+            raise AttributeError(
+                "The name of the calling function has not been set; use set_calling_function()",
+            )
+
+        if not self.calling_agent:
+            raise AttributeError(
+                "The name of the calling agent has not been set; use set_calling_agent()",
+            )
+
+        annotation_data: AnnotationDataDict = {
+            "type": self.version_type.value,
+            "calling_function": self.calling_function,
+            "calling_agent": self.calling_agent,
+            "automated": self.automated,
+        }
+
+        if self.message:
+            annotation_data["message"] = self.message
+
+        if self.payload:
+            annotation_data["payload"] = self.payload
+
+        return annotation_data
+
+    @property
+    def as_json(self) -> str:
+        """Render the structured annotation data as JSON, so it can be stored in the MarkLogic dls:annotation field.
+
+        :return: A JSON string representing this `VersionAnnotation`"""
+
+        return json.dumps(self.structured_annotation_dict)
+
+    def __str__(self) -> str:
+        return self.as_json

caselawclient/models/documents/xml.py

@@ -2,7 +2,7 @@ import os
 
 from lxml import etree
 
-from caselawclient.xml_helpers import get_xpath_match_string, get_xpath_match_strings
+from caselawclient.xml_helpers import get_xpath_match_string, get_xpath_match_strings, get_xpath_nodes
 
 
 def _xslt_path(xslt_file_name: str) -> str:
@@ -50,6 +50,9 @@ class XML:
     ) -> list[str]:
         return get_xpath_match_strings(self.xml_as_tree, xpath, namespaces)
 
+    def get_xpath_nodes(self, xpath: str, namespaces: dict[str, str]) -> list[etree._Element]:
+        return get_xpath_nodes(self.xml_as_tree, xpath, namespaces)
+
     def _modified(
         self,
         xslt: str,

caselawclient/models/identifiers/__init__.py

@@ -46,7 +46,10 @@ class IdentifierSchema(ABC):
     """ Should editors be allowed to manually manipulate identifiers under this schema? """
 
     require_globally_unique: bool = True
-    """ Must this identifier be globally unique? """
+    """ Must this identifier be globally unique? (appear on no other documents) """
+
+    allow_multiple: bool = False
+    """ May documents have more than one non-deprecated identifier of this type? """
 
     document_types: Optional[list[str]] = None
     """

caselawclient/models/identifiers/collection.py

@@ -43,6 +43,8 @@ class IdentifiersCollection(dict[str, Identifier]):
         """Check that only one non-deprecated identifier exists per schema where that schema does not allow multiples."""
 
         for schema, identifiers in self._list_all_identifiers_by_schema().items():
+            if schema.allow_multiple:
+                continue
             non_deprecated_identifiers = [i for i in identifiers if not i.deprecated]
             if len(non_deprecated_identifiers) > 1:
                 return SuccessFailureMessageTuple(

caselawclient/models/utilities/aws.py

@@ -2,6 +2,7 @@ import datetime
 import json
 import logging
 import uuid
+from collections.abc import Callable
 from typing import Any, Literal, Optional, TypedDict, overload
 
 import boto3
@@ -118,11 +119,20 @@ def generate_pdf_url(uri: DocumentURIString) -> str:
 
 
 def delete_from_bucket(uri: DocumentURIString, bucket: str) -> None:
+    delete_some_from_bucket(uri=uri, bucket=bucket, filter=lambda x: True)
+
+
+def delete_some_from_bucket(
+    uri: DocumentURIString, bucket: str, filter: Callable[[ObjectIdentifierTypeDef], bool]
+) -> None:
     client = create_s3_client()
     response = client.list_objects(Bucket=bucket, Prefix=uri_for_s3(uri))
 
     if response.get("Contents"):
-        objects_to_delete: list[ObjectIdentifierTypeDef] = [{"Key": obj["Key"]} for obj in response.get("Contents", [])]
+        objects_to_maybe_delete: list[ObjectIdentifierTypeDef] = [
+            {"Key": obj["Key"]} for obj in response.get("Contents", [])
+        ]
+        objects_to_delete = [obj for obj in objects_to_maybe_delete if filter(obj)]
         client.delete_objects(
             Bucket=bucket,
             Delete={
@@ -131,6 +141,10 @@ def delete_from_bucket(uri: DocumentURIString, bucket: str) -> None:
         )
 
 
+def delete_non_targz_from_bucket(uri: DocumentURIString, bucket: str) -> None:
+    delete_some_from_bucket(uri=uri, bucket=bucket, filter=lambda x: not x["Key"].endswith(".tar.gz"))
+
+
 def publish_documents(uri: DocumentURIString) -> None:
     """
     Copy assets from the unpublished bucket to the published one.
@@ -217,6 +231,26 @@ def copy_assets(old_uri: DocumentURIString, new_uri: DocumentURIString) -> None:
             )
 
 
+def are_unpublished_assets_clean(uri: DocumentURIString) -> bool:
+    """Returns true if all non-tar.gz assets in the relevant S3 bucket have been cleaned
+    (they have a DOCUMENT_PROCESSOR_VERSION tag)
+    Note: if there are no assets, then this returns true."""
+    client = create_s3_client()
+    bucket = env("PRIVATE_ASSET_BUCKET")
+    response = client.list_objects(Bucket=bucket, Prefix=uri_for_s3(uri))
+    for result in response.get("Contents", []):
+        file_key = str(result["Key"])
+        # ignore original tar.gz files
+        if file_key.endswith(".tar.gz"):
+            continue
+
+        # check if assets are tagged as being processed by S3
+        tag_response = client.get_object_tagging(Bucket=bucket, Key=file_key)
+        if not (any(tag["Key"] == "DOCUMENT_PROCESSOR_VERSION" for tag in tag_response["TagSet"])):
+            return False
+    return True
+
+
 def build_new_key(old_key: str, new_uri: DocumentURIString) -> str:
     """Ensure that DOCX and PDF filenames are modified to reflect their new home
     as we get the name of the new S3 path"""

caselawclient/search_parameters.py

@@ -15,6 +15,8 @@ class SearchParameters:
     judge: Optional[str] = None
     party: Optional[str] = None
     neutral_citation: Optional[str] = None
+    document_name: Optional[str] = None
+    consignment_number: Optional[str] = None
     specific_keyword: Optional[str] = None
     order: Optional[str] = None
     date_from: Optional[str] = None
@@ -39,6 +41,8 @@ class SearchParameters:
             "q": str(self.query or ""),
             "party": str(self.party or ""),
             "neutral_citation": str(self.neutral_citation or ""),
+            "document_name": str(self.document_name or ""),
+            "consignment_number": str(self.consignment_number or ""),
             "specific_keyword": str(self.specific_keyword or ""),
             "order": str(self.order or ""),
             "from": str(self.date_from or ""),

caselawclient/types.py

@@ -1,4 +1,10 @@
-from typing import NamedTuple
+from dataclasses import dataclass, field
+
+
+@dataclass
+class DocumentCategory:
+    name: str
+    subcategories: list["DocumentCategory"] = field(default_factory=list)
 
 
 class InvalidDocumentURIException(Exception):
@@ -63,9 +69,40 @@ class DocumentIdentifierValue(str):
     pass
 
 
-SuccessFailureMessageTuple = NamedTuple("SuccessFailureMessageTuple", [("success", bool), ("messages", list[str])])
-"""
-A tuple used to return if an operation has succeeded or failed (and optionally a list of messages associated with that operation).
+class SuccessFailureMessageTuple(tuple[bool, list[str]]):
+    """
+    Return whether an operation has succeeded or failed
+    (and optionally a list of messages associated with that operation).
+    Typically the messages will be exposed to the end-user.
+    Use only where a failure is a routine event (such as during validation).
+    """
+
+    def __new__(cls, success: bool, messages: list[str]) -> "SuccessFailureMessageTuple":
+        return super().__new__(cls, [success, messages])
+
+    @property
+    def success(self) -> bool:
+        return self[0]
+
+    @property
+    def messages(self) -> list[str]:
+        return self[1]
+
+    def __repr__(self) -> str:
+        return f"SuccessFailureMessageTuple({self.success!r}, {self.messages!r})"
+
+    def __bool__(self) -> bool:
+        return self.success
+
+    def __or__(self, other: "SuccessFailureMessageTuple") -> "SuccessFailureMessageTuple":
+        """Allows us to write combined_tuple = first_tuple | second_tuple"""
+        return SuccessFailureMessageTuple(self.success and other.success, self.messages + other.messages)
+
+
+def SuccessTuple() -> SuccessFailureMessageTuple:
+    return SuccessFailureMessageTuple(True, [])
+
 
-This should only be used where a failure is considered a routine part of the application (eg during validation options); where an unexpected action has led to a failure the application should raise an appropriate exception.
-"""
+def FailureTuple(message: str | list[str]) -> SuccessFailureMessageTuple:
+    messages = message if isinstance(message, list) else [message]
+    return SuccessFailureMessageTuple(success=False, messages=messages)

caselawclient/xml_helpers.py

@@ -7,9 +7,25 @@ DEFAULT_NAMESPACES = {
     "akn": "http://docs.oasis-open.org/legaldocml/ns/akn/3.0",
 }
 
+# _Element is the only class lxml exposes, so need to use the private class for typing
+Element = etree._Element  # noqa: SLF001
+
+
+def get_xpath_nodes(
+    node: Element,
+    path: str,
+    namespaces: Optional[Dict[str, str]] = None,
+) -> list[Element]:
+    result = node.xpath(path, namespaces=namespaces)
+
+    if not isinstance(result, list) or not all(isinstance(x, Element) for x in result):
+        raise TypeError(f"Expected to return list[Element], got {type(result).__name__}")
+
+    return result
+
 
 def get_xpath_match_string(
-    node: etree._Element,
+    node: Element,
     path: str,
     namespaces: Optional[Dict[str, str]] = None,
     fallback: str = "",
@@ -18,7 +34,7 @@ def get_xpath_match_string(
 
 
 def get_xpath_match_strings(
-    node: etree._Element,
+    node: Element,
     path: str,
     namespaces: Optional[Dict[str, str]] = None,
 ) -> list[str]:

caselawclient/xquery/check_content_hash_unique_by_uri.xqy

@@ -0,0 +1,15 @@
+xquery version "1.0-ml";
+declare namespace akn = "http://docs.oasis-open.org/legaldocml/ns/akn/3.0";
+declare namespace uk = "https://caselaw.nationalarchives.gov.uk/akn";
+declare variable $uri as xs:string external;
+
+let $doc := doc($uri)
+let $hash := $doc//uk:hash/text()
+let $count := count(cts:uris(
+  (), (),
+  cts:and-query((
+    cts:element-value-query(xs:QName("uk:hash"), $hash),
+    cts:collection-query("http://marklogic.com/collections/dls/latest-version")
+  ))
+))
+return $count = 1

caselawclient/xquery_type_dicts.py

@@ -23,6 +23,11 @@ class BreakJudgmentCheckoutDict(MarkLogicAPIDict):
     uri: MarkLogicDocumentURIString
 
 
+# check_content_hash_unique_by_uri.xqy
+class CheckContentHashUniqueByUriDict(MarkLogicAPIDict):
+    uri: MarkLogicDocumentURIString
+
+
 # checkin_judgment.xqy
 class CheckinJudgmentDict(MarkLogicAPIDict):
     uri: MarkLogicDocumentURIString

{ds_caselaw_marklogic_api_client-40.0.0.dist-info → ds_caselaw_marklogic_api_client-43.1.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: ds-caselaw-marklogic-api-client
-Version: 40.0.0
+Version: 43.1.0
 Summary: An API client for interacting with the underlying data in Find Caselaw.
 Keywords: national archives,caselaw
 Author: The National Archives
@@ -9,7 +9,7 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Requires-Dist: boto3 (>=1.26.112,<2.0.0)
-Requires-Dist: certifi (>=2025.8.3,<2025.9.0)
+Requires-Dist: certifi (>=2025.10.5,<2025.11.0)
 Requires-Dist: charset-normalizer (>=3.0.0,<4.0.0)
 Requires-Dist: defusedxml (>=0.7.1,<0.8.0)
 Requires-Dist: django-environ (>=0.12.0)
@@ -19,6 +19,7 @@ Requires-Dist: lxml (>=6.0.0,<7.0.0)
 Requires-Dist: memoization (>=0.4.0,<0.5.0)
 Requires-Dist: mypy-boto3-s3 (>=1.26.104,<2.0.0)
 Requires-Dist: mypy-boto3-sns (>=1.26.69,<2.0.0)
+Requires-Dist: pydantic (>=2.12.3,<3.0.0)
 Requires-Dist: python-dateutil (>=2.9.0-post.0,<3.0.0)
 Requires-Dist: pytz (>2024)
 Requires-Dist: requests (>=2.28.2,<3.0.0)

{ds_caselaw_marklogic_api_client-40.0.0.dist-info → ds_caselaw_marklogic_api_client-43.1.0.dist-info}/RECORD

@@ -1,21 +1,25 @@
-caselawclient/Client.py,sha256=tof_riZN5c1x3_cYScfIDiGaPIYt1EuAtKOpg3qI_cg,46880
+caselawclient/Client.py,sha256=OZ7ee3QVvN59go2oHxndgRgAKSMaVAn-mmG7E9rpPgg,47415
 caselawclient/__init__.py,sha256=QZtsOB_GR5XfFnWMJ6E9_fBany-JXFIrQmzs1mD_KVg,1225
-caselawclient/client_helpers/__init__.py,sha256=eucyUXwUqI72TPw-C5zLcHlMu4GtFY507a6lQc03lQY,5053
+caselawclient/client_helpers/__init__.py,sha256=tpXWjwBAqOf8ChtSiEeMhdkiO7tVbfZ4FfQXsXaGJlI,1221
 caselawclient/client_helpers/search_helpers.py,sha256=R99HyRLeYHgsw2L3DOidEqlKLLvs6Tga5rKTuWQViig,1525
 caselawclient/content_hash.py,sha256=0cPC4OoABq0SC2wYFX9-24DodNigeOqksDxgxQH_hUA,2221
 caselawclient/errors.py,sha256=JC16fEGq_MRJX-_KFzfINCV2Cqx8o6OWOt3C16rQd84,3142
-caselawclient/factories.py,sha256=eGj9TiZpmF3todW-08Ps7bHNMvByHqwEbgujRhvU_Yc,7382
+caselawclient/factories.py,sha256=HXJeWpN7__X462joco07ziNqMOOMr-wUPJ91Y69gFk8,7466
 caselawclient/identifier_resolution.py,sha256=B5I1sD7o7YjzsXMECjbKjgiGLDda5bGhejsJ-lYpTIg,2429
+caselawclient/managers/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+caselawclient/managers/merge/__init__.py,sha256=Rd6YIGifT3TP6UOf0gBrRoYzK5MJqTPeRaIJznS8dgI,2078
+caselawclient/managers/merge/checks.py,sha256=J9RBG6jZAKIZk27jdFq-BByoRLKWsViCfHDyA8ZM3qU,3205
 caselawclient/models/__init__.py,sha256=kd23EUpvaC7aLHdgk8farqKAQEx3lf7RvNT2jEatvlg,68
-caselawclient/models/documents/__init__.py,sha256=ugbklabbI1LcoN5mE6rffYDApUOtkTXBzYH3Rv2fhBE,22667
-caselawclient/models/documents/body.py,sha256=O1ZTV3KHo-YNi7Syd4oCV1CVSuRF7mcLXojwshyY4jg,6601
+caselawclient/models/documents/__init__.py,sha256=6OBZfMy_6FgLQ6ZnMvjKv1Poiq-UP7pb2TcxHx-uSTI,24705
+caselawclient/models/documents/body.py,sha256=pzk3bm9FGIWfI0Hs8dBuzk6RCiA9M4GHfgOYKpNlzyE,8455
 caselawclient/models/documents/comparison.py,sha256=KwFZQByOcYcZKe8csjAntttACKq4BZb28n2VeV5rK54,1355
 caselawclient/models/documents/exceptions.py,sha256=te7PPQTDHjZ9EYVg5pVaiZfF00lMBFy333PHj8_mkC4,443
 caselawclient/models/documents/statuses.py,sha256=Cp4dTQmJOtsU41EJcxy5dV1841pGD2PNWH0VrkDEv4Q,579
 caselawclient/models/documents/transforms/html.xsl,sha256=XyUQLFcJ7_GwthWQ6ShU0bmzrgpl7xDFU-U8VLgOvEs,38258
-caselawclient/models/documents/xml.py,sha256=BVra2VL_0JyImM8GC3wdouu1tApy79C-e2dHvQyrXPE,2195
-caselawclient/models/identifiers/__init__.py,sha256=bcXiree1FKIlJklWggvS_IKMHMppAjDbadOpxCJx3yw,7727
-caselawclient/models/identifiers/collection.py,sha256=kGlziJiLAqoyd6LaaZ5tsgUf2fD6Y-7fv1It9S4-Otw,7448
+caselawclient/models/documents/versions.py,sha256=fyDNKCdrTb2N0Ks23YDhmvlXKfLTHnYQCXhnZb-QQbg,3832
+caselawclient/models/documents/xml.py,sha256=uGRULm_XcA9ABZmwTxxwwysPItQl1qnMd2pUVTZprgc,2376
+caselawclient/models/identifiers/__init__.py,sha256=Vp5zJdJSskCuUOUwmPDiDvVlNsYmPRH350-wRx7Q8Dc,7877
+caselawclient/models/identifiers/collection.py,sha256=1fw9yAuHBBMCgAfYRwgpoIPHW_vWQA-eCGDBnWI-gWI,7511
 caselawclient/models/identifiers/exceptions.py,sha256=6LVjvx-UOwqkrpxU19ydmrphKNw0rcG5GXwjTFyf8Dk,130
 caselawclient/models/identifiers/fclid.py,sha256=hj8z-VhXFrUHKOY6k_ItPvOakIvbhJ5xEbZ04E2j7t8,1521
 caselawclient/models/identifiers/neutral_citation.py,sha256=bYAeXHVm_ls0aDTeYI4uv35iZmJGSKU4-H-iLh2xED0,2912
@@ -26,7 +30,7 @@ caselawclient/models/neutral_citation_mixin.py,sha256=jAac3PPuWyPdj9N-n-U_Jfwkbg
 caselawclient/models/parser_logs.py,sha256=iOhKTAAi87XQvxz1DHjF2lrqScD19g_c8EjSf0vPdfs,364
 caselawclient/models/press_summaries.py,sha256=rtrYs_3BazUXxdA2oYmIJ6YIAiVlKeyc1aSF9uvkJJU,2196
 caselawclient/models/utilities/__init__.py,sha256=LPhyrQwLKc5tIJUO8Bysn9wCiR6Z6jMMTksjOV4JH9U,1041
-caselawclient/models/utilities/aws.py,sha256=_JUoJatfC1m_etT5MDwbCrOHpdqqTRqGCyzzNiW1WRA,8660
+caselawclient/models/utilities/aws.py,sha256=s86_kOpnyc-seefy7eZQsnE4v3b5TZCAVhESiDEpqx8,10084
 caselawclient/models/utilities/dates.py,sha256=WwORxVjUHM1ZFcBF6Qtwo3Cj0sATsnSECkUZ6ls1N1Q,492
 caselawclient/models/utilities/move.py,sha256=MXdUqkSiyqRb8YKs_66B6ICWn8EWM6DiJV95fuJO1Us,3610
 caselawclient/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -34,10 +38,11 @@ caselawclient/responses/__init__.py,sha256=2-5NJn_PXPTje_W4dHeHYaNRN6vXK4UcB9eLL
 caselawclient/responses/search_response.py,sha256=Z76Zj4VvM-EV_vdiehv2-Jfkr9HZD3SvCTlRrUB_cyE,1951
 caselawclient/responses/search_result.py,sha256=glcoCeo2xO-17aV2pcpyfgl0_UjjEUqHfm2kVylXCwk,9782
 caselawclient/responses/xsl/search_match.xsl,sha256=4Sv--MrwBd7J48E9aI7jlFSXGlNi4dBqgzJ3bdMJ_ZU,1018
-caselawclient/search_parameters.py,sha256=A-9icXdyFYLDACjUaRQF8mrnaVRlFJ9XCPtu5uZ-_Lo,3484
-caselawclient/types.py,sha256=5lE_0kRd7ZMUkr53Rh4ooo74Ab8JTXnMo8rNrwn_HUo,2578
-caselawclient/xml_helpers.py,sha256=xCboRhhzezqh-VyoKBQwal5lwxv96vTMJyVFWJNN-ok,639
+caselawclient/search_parameters.py,sha256=BQzDrfxqyZTkqgNj8Ruy-lSr_m4bYrUzUKrqCxB8GrM,3699
+caselawclient/types.py,sha256=Q1RE2HMZUGKTuDzg9wARq9AuVaIIlDyYFE4tqhpcN_U,3630
+caselawclient/xml_helpers.py,sha256=31cxsDu680SFi3gR35rL7EdBZaW6r6mt4zvWHjJeX9o,1131
 caselawclient/xquery/break_judgment_checkout.xqy,sha256=rISzoBKxQKrP5ZRdCSoRqOXW8T_NDBSZRFjOXo_H3ns,220
+caselawclient/xquery/check_content_hash_unique_by_uri.xqy,sha256=kXfJL0sclcCulsaw5KGgVCyuiIfINkSeMwFGXSvuYME,494
 caselawclient/xquery/checkin_judgment.xqy,sha256=QeGqO3kL-q0UrjopCVU0lCbkwbyoc5SuNLYFAIbbyMg,197
 caselawclient/xquery/checkout_judgment.xqy,sha256=aRwVo4KXoEKXfXRZ6IrVfvh0pXK-7pFxVIgEyzE5DRY,385
 caselawclient/xquery/copy_document.xqy,sha256=GwgafibZhUB4rZ7x5wmHAKi0DO1aEWNVithkguwsVGE,453
@@ -85,10 +90,10 @@ caselawclient/xquery/validate_all_documents.xqy,sha256=z_0YEXmRcZ-FaJM0ouKiTjdI4
 caselawclient/xquery/validate_document.xqy,sha256=PgaDcnqCRJPIVqfmWsNlXmCLNKd21qkJrvY1RtNP7eA,140
 caselawclient/xquery/xslt.xqy,sha256=w57wNijH3dkwHkpKeAxqjlghVflQwo8cq6jS_sm-erM,199
 caselawclient/xquery/xslt_transform.xqy,sha256=cccaFiGkCcvSfDv007UriZ3I4ak2nTLP1trRZdbOoS8,2462
-caselawclient/xquery_type_dicts.py,sha256=ROwV-BpQYDOrtW6aKx5MXVi85SW5J5oGgyQT7-Ra1sA,6633
+caselawclient/xquery_type_dicts.py,sha256=f4PM8yZi5RRMdL2lQ8tsLUs0aJjBa5chvd-VVj40fJY,6767
 caselawclient/xslt/modify_xml_live.xsl,sha256=gNjwBun2-UzOeeuf0wNjFtN3jXm1yrwqv_KT8r1slXw,2370
 caselawclient/xslt/sample.xsl,sha256=IG-v77stjwqiw25pguh391K-5DTKiX651WqILDZixm0,825
-ds_caselaw_marklogic_api_client-40.0.0.dist-info/LICENSE.md,sha256=fGMzyyLuQW-IAXUeDSCrRdsYW536aEWThdbpCjo6ZKg,1108
-ds_caselaw_marklogic_api_client-40.0.0.dist-info/METADATA,sha256=Nxrgxi6sCKcfetI5h5k0PcwLkkkUQYs2e8nbtj-PUQY,4364
-ds_caselaw_marklogic_api_client-40.0.0.dist-info/WHEEL,sha256=XbeZDeTWKc1w7CSIyre5aMDU_-PohRwTQceYnisIYYY,88
-ds_caselaw_marklogic_api_client-40.0.0.dist-info/RECORD,,
+ds_caselaw_marklogic_api_client-43.1.0.dist-info/LICENSE.md,sha256=fGMzyyLuQW-IAXUeDSCrRdsYW536aEWThdbpCjo6ZKg,1108
+ds_caselaw_marklogic_api_client-43.1.0.dist-info/METADATA,sha256=P-ddB6xJtOQa9vfR5Yl5iFIxXZL2mOgeLRg-YxVQRMY,4408
+ds_caselaw_marklogic_api_client-43.1.0.dist-info/WHEEL,sha256=XbeZDeTWKc1w7CSIyre5aMDU_-PohRwTQceYnisIYYY,88
+ds_caselaw_marklogic_api_client-43.1.0.dist-info/RECORD,,