ds-caselaw-marklogic-api-client 41.1.0__tar.gz → 43.1.0__tar.gz

{ds_caselaw_marklogic_api_client-41.1.0 → ds_caselaw_marklogic_api_client-43.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: ds-caselaw-marklogic-api-client
-Version: 41.1.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-41.1.0 → ds_caselaw_marklogic_api_client-43.1.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "ds-caselaw-marklogic-api-client"
-version = "41.1.0"
+version = "43.1.0"
 description = "An API client for interacting with the underlying data in Find Caselaw."
 authors = ["The National Archives"]
 homepage = "https://github.com/nationalarchives/ds-caselaw-custom-api-client"
@@ -12,7 +12,7 @@ packages = [
 
 [tool.poetry.dependencies]
 python = "^3.12.0"
-certifi = ">=2025.8.3,<2025.9.0"
+certifi = ">=2025.10.5,<2025.11.0"
 charset-normalizer = "^3.0.0"
 django-environ = ">=0.12.0"
 idna = "^3.4"
@@ -30,22 +30,23 @@ python-dateutil = "^2.9.0-post.0"
 saxonche = "^12.5.0"
 sqids = "^0.5.0"
 defusedxml = "^0.7.1"
+pydantic = "^2.12.3"
 
 [tool.poetry.group.dev.dependencies]
-coverage = "7.10.6"
+coverage = "7.11.0"
 pytest = "8.4.2"
-pytest-cov = "6.3.0"
-beautifulsoup4 = "4.13.5"
+pytest-cov = "7.0.0"
+beautifulsoup4 = "4.14.2"
 responses = "0.25.8"
-python-dotenv = "1.1.1"
+python-dotenv = "1.2.1"
 time-machine = "2.19.0"
-moto = {version = "5.1.11", extras = ["all"]}
+moto = {version = "5.1.16", extras = ["all"]}
 
 [tool.poetry.group.docs]
 optional = true
 
 [tool.poetry.group.docs.dependencies]
-pdoc = "^15.0.0"
+pdoc = "^16.0.0"
 
 
 [tool.commitizen]

{ds_caselaw_marklogic_api_client-41.1.0 → ds_caselaw_marklogic_api_client-43.1.0}/src/caselawclient/Client.py

@@ -21,13 +21,13 @@ 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
@@ -802,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:

ds_caselaw_marklogic_api_client-43.1.0/src/caselawclient/client_helpers/__init__.py

@@ -0,0 +1,35 @@
+from lxml import etree
+
+from caselawclient.xml_helpers import DEFAULT_NAMESPACES
+
+from ..models.documents import Document
+from ..models.judgments import Judgment
+from ..models.parser_logs import ParserLog
+from ..models.press_summaries import PressSummary
+
+
+class CannotDetermineDocumentType(Exception):
+    pass
+
+
+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."""
+
+    node = etree.fromstring(xml)
+
+    # If the main node is `<judgment>`, it's a judgment
+    if node.xpath("/akn:akomaNtoso/akn:judgment", namespaces=DEFAULT_NAMESPACES):
+        return Judgment
+
+    # If the main node is `<doc name='pressSummary'>`, it's a press summary
+    if node.xpath("/akn:akomaNtoso/akn:doc[@name='pressSummary']", namespaces=DEFAULT_NAMESPACES):
+        return PressSummary
+
+    # If the document is a parser error with a root element of `error`, it's not of a special type.
+    if node.xpath("/error", namespaces=DEFAULT_NAMESPACES):
+        return ParserLog
+
+    # Otherwise, we don't know for sure. Fail out.
+    raise CannotDetermineDocumentType(
+        "Unable to determine the Document type by its XML",
+    )

ds_caselaw_marklogic_api_client-43.1.0/src/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),
+            ]
+        )

ds_caselaw_marklogic_api_client-43.1.0/src/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, [])

{ds_caselaw_marklogic_api_client-41.1.0 → ds_caselaw_marklogic_api_client-43.1.0}/src/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
@@ -357,6 +359,12 @@ 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."""

ds_caselaw_marklogic_api_client-41.1.0/src/caselawclient/client_helpers/__init__.py → ds_caselaw_marklogic_api_client-43.1.0/src/caselawclient/models/documents/versions.py

@@ -2,20 +2,8 @@ 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
-
-from ..models.documents import Document
-from ..models.judgments import Judgment
-from ..models.parser_logs import ParserLog
-from ..models.press_summaries import PressSummary
-
-
-class CannotDetermineDocumentType(Exception):
-    pass
-
 
 class AnnotationDataDict(TypedDict):
     type: str
@@ -124,26 +112,3 @@ class VersionAnnotation:
 
     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."""
-
-    node = etree.fromstring(xml)
-
-    # If the main node is `<judgment>`, it's a judgment
-    if node.xpath("/akn:akomaNtoso/akn:judgment", namespaces=DEFAULT_NAMESPACES):
-        return Judgment
-
-    # If the main node is `<doc name='pressSummary'>`, it's a press summary
-    if node.xpath("/akn:akomaNtoso/akn:doc[@name='pressSummary']", namespaces=DEFAULT_NAMESPACES):
-        return PressSummary
-
-    # If the document is a parser error with a root element of `error`, it's not of a special type.
-    if node.xpath("/error", namespaces=DEFAULT_NAMESPACES):
-        return ParserLog
-
-    # Otherwise, we don't know for sure. Fail out.
-    raise CannotDetermineDocumentType(
-        "Unable to determine the Document type by its XML",
-    )

{ds_caselaw_marklogic_api_client-41.1.0 → ds_caselaw_marklogic_api_client-43.1.0}/src/caselawclient/models/utilities/aws.py

@@ -231,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"""

{ds_caselaw_marklogic_api_client-41.1.0 → ds_caselaw_marklogic_api_client-43.1.0}/src/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 ""),

{ds_caselaw_marklogic_api_client-41.1.0 → ds_caselaw_marklogic_api_client-43.1.0}/src/caselawclient/types.py

@@ -1,5 +1,4 @@
 from dataclasses import dataclass, field
-from typing import NamedTuple
 
 
 @dataclass
@@ -70,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)

{ds_caselaw_marklogic_api_client-41.1.0 → ds_caselaw_marklogic_api_client-43.1.0}/src/caselawclient/xquery/check_content_hash_unique_by_uri.xqy

@@ -5,5 +5,11 @@ declare variable $uri as xs:string external;
 
 let $doc := doc($uri)
 let $hash := $doc//uk:hash/text()
-let $count := count(cts:search(fn:doc(), cts:element-value-query(xs:QName("uk:hash"), $hash)))
+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