ds-caselaw-marklogic-api-client 37.3.1__py3-none-any.whl → 38.0.0__py3-none-any.whl

caselawclient/factories.py

@@ -1,15 +1,14 @@
 import datetime
 import json
-from typing import Any, Optional
+from typing import Any, Generic, Optional, Type, TypeAlias, TypeVar, cast
 from unittest.mock import Mock
 
-from typing_extensions import TypeAlias
-
 from caselawclient.Client import MarklogicApiClient
 from caselawclient.identifier_resolution import IdentifierResolution, IdentifierResolutions
 from caselawclient.models.documents import Document
 from caselawclient.models.documents.body import DocumentBody
 from caselawclient.models.identifiers import Identifier
+from caselawclient.models.identifiers.collection import IdentifiersCollection
 from caselawclient.models.identifiers.fclid import FindCaseLawIdentifier
 from caselawclient.models.identifiers.neutral_citation import NeutralCitationNumber
 from caselawclient.models.judgments import Judgment
@@ -17,6 +16,8 @@ from caselawclient.models.press_summaries import PressSummary
 from caselawclient.responses.search_result import SearchResult, SearchResultMetadata
 from caselawclient.types import DocumentURIString
 
+T = TypeVar("T")
+
 DEFAULT_DOCUMENT_BODY_XML = """<akomaNtoso xmlns="http://docs.oasis-open.org/legaldocml/ns/akn/3.0" xmlns:uk="https://caselaw.nationalarchives.gov.uk/akn">
             <judgment name="decision">
                 <meta/><header/>
@@ -114,13 +115,13 @@ class PressSummaryFactory(DocumentFactory):
     }
 
 
-class SimpleFactory:
-    target_class: TypeAlias = object
+class SimpleFactory(Generic[T]):
+    target_class: Type[T]
     # "name_of_attribute": "default value"
     PARAMS_MAP: dict[str, Any]
 
     @classmethod
-    def build(cls, **kwargs: Any) -> target_class:
+    def build(cls, **kwargs: Any) -> T:
         mock_object = Mock(spec=cls.target_class, autospec=True)
 
         for param, default in cls.PARAMS_MAP.items():
@@ -129,10 +130,10 @@ class SimpleFactory:
             else:
                 setattr(mock_object.return_value, param, default)
 
-        return mock_object()
+        return cast(T, mock_object())
 
 
-class SearchResultMetadataFactory(SimpleFactory):
+class SearchResultMetadataFactory(SimpleFactory[SearchResultMetadata]):
     target_class = SearchResultMetadata
     # "name_of_attribute": "default value"
     PARAMS_MAP = {
@@ -174,9 +175,8 @@ class IdentifierResolutionsFactory:
         return IdentifierResolutions(resolutions)
 
 
-class SearchResultFactory(SimpleFactory):
+class SearchResultFactory(SimpleFactory[SearchResult]):
     target_class = SearchResult
-
     PARAMS_MAP = {
         "uri": "d-a1b2c3",
         "name": "Judgment v Judgement",
@@ -189,5 +189,10 @@ class SearchResultFactory(SimpleFactory):
         "matches": None,
         "slug": "uksc/2025/1",
         "content_hash": "ed7002b439e9ac845f22357d822bac1444730fbdb6016d3ec9432297b9ec9f73",
-        "identifiers": {"id-1": NeutralCitationNumber("[2025] UKSC 123", "id-1")},
+        "identifiers": IdentifiersCollection(
+            {
+                "id-1": NeutralCitationNumber("[2025] UKSC 123", "id-1"),
+                "id-2": FindCaseLawIdentifier("bcdfghjk", "id-2"),
+            }
+        ),
     }

caselawclient/models/documents/__init__.py

@@ -16,6 +16,7 @@ from caselawclient.errors import (
 )
 from caselawclient.identifier_resolution import IdentifierResolutions
 from caselawclient.models.identifiers import Identifier
+from caselawclient.models.identifiers.exceptions import IdentifierValidationException
 from caselawclient.models.identifiers.fclid import FindCaseLawIdentifier, FindCaseLawIdentifierSchema
 from caselawclient.models.identifiers.unpacker import unpack_all_identifiers_from_etree
 from caselawclient.models.utilities import VersionsDict, extract_version, render_versions
@@ -33,7 +34,7 @@ from caselawclient.models.utilities.aws import (
 from caselawclient.types import DocumentURIString
 
 from .body import DocumentBody
-from .exceptions import CannotPublishUnpublishableDocument, DocumentNotSafeForDeletion
+from .exceptions import CannotEnrichUnenrichableDocument, CannotPublishUnpublishableDocument, DocumentNotSafeForDeletion
 from .statuses import DOCUMENT_STATUS_HOLD, DOCUMENT_STATUS_IN_PROGRESS, DOCUMENT_STATUS_NEW, DOCUMENT_STATUS_PUBLISHED
 
 MINIMUM_ENRICHMENT_TIME = datetime.timedelta(minutes=20)
@@ -340,22 +341,34 @@ class Document:
             now.isoformat(),
         )
 
+        if not self.can_enrich:
+            msg = f"{self.uri} cannot be enriched"
+            raise CannotEnrichUnenrichableDocument(msg)
+
         announce_document_event(
             uri=self.uri,
             status="enrich",
             enrich=True,
         )
 
-    def enrich(self) -> bool:
+    def enrich(self, even_if_recent: bool = False, accept_failures: bool = False) -> bool:
         """
         Request enrichment of a document, if it's sensible to do so.
         """
-        if self.enriched_recently is False:
-            print("Enrichment requested")
+        if not (even_if_recent) and self.enriched_recently:
+            print("Enrichment not requested as document was enriched recently")
+            return False
+
+        print("Enrichment requested")
+
+        try:
             self.force_enrich()
-            return True
-        print("Enrichment not requested as document was enriched recently")
-        return False
+        except CannotEnrichUnenrichableDocument as e:
+            if not accept_failures:
+                raise e
+            return False
+
+        return True
 
     @cached_property
     def enriched_recently(self) -> bool:
@@ -501,10 +514,22 @@ class Document:
         """
         return self.docx_exists()
 
+    @cached_property
+    def can_enrich(self) -> bool:
+        """
+        Is it possible to enrich this document?
+        """
+        return self.body.has_content
+
     def save_identifiers(self) -> None:
-        """Save the current state of this Document's identifiers to MarkLogic."""
-        self.identifiers.validate()
-        self.api_client.set_property_as_node(self.uri, "identifiers", self.identifiers.as_etree)
+        """Validate the identifiers, and if the validation passes save them to MarkLogic"""
+        validations = self.identifiers.perform_all_validations(document_type=type(self), api_client=self.api_client)
+        if validations.success is True:
+            self.api_client.set_property_as_node(self.uri, "identifiers", self.identifiers.as_etree)
+        else:
+            raise IdentifierValidationException(
+                "Unable to save identifiers; validation constraints not met: " + ", ".join(validations.messages)
+            )
 
     def __getattr__(self, name: str) -> Any:
         warnings.warn(f"{name} no longer exists on Document, using Document.body instead", DeprecationWarning)
@@ -541,3 +566,13 @@ class Document:
     def content_as_html(self) -> str | None:
         xlst_image_location = os.getenv("XSLT_IMAGE_LOCATION", "")
         return self.body.content_html(f"{xlst_image_location}/{self.uri}")
+
+    def xml_with_correct_frbr(self) -> bytes:
+        """Dynamically modify FRBR uris to reflect current storage location and FCL id"""
+        fcl_identifiers = self.identifiers.of_type(FindCaseLawIdentifier)
+        work_uri = f"https://caselaw.nationalarchives.gov.uk/id/{fcl_identifiers[0].url_slug}"
+        expression_uri = f"https://caselaw.nationalarchives.gov.uk/{self.uri.lstrip('/')}"
+        manifestation_uri = f"https://caselaw.nationalarchives.gov.uk/{self.uri.lstrip('/')}/data.xml"
+        return self.body.apply_xslt(
+            "modify_xml_live.xsl", work_uri=work_uri, expression_uri=expression_uri, manifestation_uri=manifestation_uri
+        )

caselawclient/models/documents/body.py

@@ -51,6 +51,14 @@ 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 category(self) -> Optional[str]:
+        return self.get_xpath_match_string("/akn:akomaNtoso/akn:*/akn:meta/akn:proprietary/uk:category/text()")
+
+    @cached_property
+    def case_number(self) -> Optional[str]:
+        return self.get_xpath_match_string("/akn:akomaNtoso/akn:*/akn:meta/akn:proprietary/uk:caseNumber/text()")
+
     @property
     def court_and_jurisdiction_identifier_string(self) -> CourtCode:
         if self.jurisdiction != "":
@@ -166,3 +174,6 @@ class DocumentBody:
         :return: `True` if there was a complete parser failure, otherwise `False`
         """
         return "error" in self._xml.root_element
+
+    def apply_xslt(self, xslt_filename: str, **values: str) -> bytes:
+        return self._xml.apply_xslt(xslt_filename, **values)

caselawclient/models/documents/exceptions.py

@@ -2,5 +2,9 @@ class CannotPublishUnpublishableDocument(Exception):
     """A document which has failed publication safety checks in `Document.is_publishable` cannot be published."""
 
 
+class CannotEnrichUnenrichableDocument(Exception):
+    """A document which cannot be enriched (see `Document.can_enrich`) tried to be sent to enrichment"""
+
+
 class DocumentNotSafeForDeletion(Exception):
     """A document which is not safe for deletion cannot be deleted."""

caselawclient/models/documents/xml.py

@@ -1,8 +1,16 @@
+import os
+
 from lxml import etree
 
 from caselawclient.xml_helpers import get_xpath_match_string, get_xpath_match_strings
 
 
+def _xslt_path(xslt_file_name: str) -> str:
+    from caselawclient.Client import ROOT_DIR
+
+    return os.path.join(ROOT_DIR, "xslt", xslt_file_name)
+
+
 class NonXMLDocumentError(Exception):
     """A document cannot be parsed as XML."""
 
@@ -41,3 +49,20 @@ class XML:
         namespaces: dict[str, str],
     ) -> list[str]:
         return get_xpath_match_strings(self.xml_as_tree, xpath, namespaces)
+
+    def _modified(
+        self,
+        xslt: str,
+        **values: str,
+    ) -> bytes:
+        """XSLT transform this XML, given a stylesheet"""
+        passable_values = {k: etree.XSLT.strparam(v) for k, v in values.items()}
+        xslt_transform = etree.XSLT(etree.fromstring(xslt))
+        return etree.tostring(xslt_transform(self.xml_as_tree, profile_run=False, **passable_values))
+
+    def apply_xslt(self, xslt_filename: str, **values: str) -> bytes:
+        """XSLT transform this XML, given a path to a stylesheet"""
+        full_xslt_filename = _xslt_path(xslt_filename)
+        with open(full_xslt_filename) as f:
+            xslt = f.read()
+        return self._modified(xslt, **values)

caselawclient/models/identifiers/__init__.py

@@ -1,23 +1,31 @@
 from abc import ABC, abstractmethod
-from typing import Any, Optional, Union
+from typing import TYPE_CHECKING, Any, Optional
 from uuid import uuid4
 
 from lxml import etree
 
-from caselawclient.types import DocumentIdentifierSlug, DocumentIdentifierValue
+from caselawclient.types import DocumentIdentifierSlug, DocumentIdentifierValue, SuccessFailureMessageTuple
 
-from .exceptions import IdentifierValidationException, UUIDMismatchError
+from .exceptions import IdentifierValidationException
+
+if TYPE_CHECKING:
+    from caselawclient.Client import MarklogicApiClient
+    from caselawclient.models.documents import Document
 
 IDENTIFIER_PACKABLE_ATTRIBUTES: list[str] = [
     "uuid",
     "value",
+    "deprecated",
     "url_slug",
 ]
+"""A list of attributes of an Identifier to pack into an XML representation."""
 
 IDENTIFIER_UNPACKABLE_ATTRIBUTES: list[str] = [
     "uuid",
     "value",
+    "deprecated",
 ]
+"""A list of attributes to unpack from an XML representation."""
 
 
 class IdentifierSchema(ABC):
@@ -34,6 +42,19 @@ class IdentifierSchema(ABC):
     base_score_multiplier: float = 1.0
     """ A multiplier used to adjust the relative ranking of this identifier when calculating preferred identifiers. """
 
+    allow_editing: bool = True
+    """ Should editors be allowed to manually manipulate identifiers under this schema? """
+
+    require_globally_unique: bool = True
+    """ Must this identifier be globally unique? """
+
+    document_types: Optional[list[str]] = None
+    """
+    If present, a list of the names of document classes which can have this identifier.
+
+    If `None`, this identifier is valid for all document types.
+    """
+
     def __init_subclass__(cls: type["IdentifierSchema"], **kwargs: Any) -> None:
         """Ensure that subclasses have the required attributes set."""
         for required in (
@@ -50,7 +71,7 @@ class IdentifierSchema(ABC):
 
     @classmethod
     @abstractmethod
-    def validate_identifier(cls, value: str) -> bool:
+    def validate_identifier_value(cls, value: str) -> bool:
         """Check that any given identifier value is valid for this schema."""
         pass
 
@@ -69,6 +90,9 @@ class Identifier(ABC):
     uuid: str
     value: DocumentIdentifierValue
 
+    deprecated: bool
+    """Should this identifier be considered deprecated, ie although we know it refers to a particular document its usage should be discouraged?"""
+
     def __init_subclass__(cls: type["Identifier"], **kwargs: Any) -> None:
         """Ensure that subclasses have the required attributes set."""
         for required in ("schema",):
@@ -77,13 +101,17 @@ class Identifier(ABC):
         super().__init_subclass__(**kwargs)
 
     def __repr__(self) -> str:
-        return f"<{self.schema.name} {self.value}: {self.uuid}>"
+        representation = f"{self.schema.name} {self.value}: {self.uuid}"
+
+        if self.deprecated:
+            return f"<{representation} (deprecated)> "
+        return f"<{representation}>"
 
     def __str__(self) -> str:
         return self.value
 
-    def __init__(self, value: str, uuid: Optional[str] = None) -> None:
-        if not self.schema.validate_identifier(value=value):
+    def __init__(self, value: str, uuid: Optional[str] = None, deprecated: bool = False) -> None:
+        if not self.schema.validate_identifier_value(value=value):
             raise IdentifierValidationException(
                 f'Identifier value "{value}" is not valid according to the {self.schema.name} schema.'
             )
@@ -94,6 +122,8 @@ class Identifier(ABC):
         else:
             self.uuid = "id-" + str(uuid4())
 
+        self.deprecated = deprecated
+
     @property
     def as_xml_tree(self) -> etree._Element:
         """Convert this Identifier into a packed XML representation for storage."""
@@ -102,9 +132,13 @@ class Identifier(ABC):
         namespace_attribute = etree.SubElement(identifier_root, "namespace")
         namespace_attribute.text = self.schema.namespace
 
-        for attribute in IDENTIFIER_PACKABLE_ATTRIBUTES:
-            packed_attribute = etree.SubElement(identifier_root, attribute)
-            packed_attribute.text = getattr(self, attribute)
+        for attribute_name in IDENTIFIER_PACKABLE_ATTRIBUTES:
+            packed_attribute = etree.SubElement(identifier_root, attribute_name)
+            attribute_value = getattr(self, attribute_name)
+            if type(attribute_value) is bool:
+                packed_attribute.text = str(attribute_value).lower()
+            else:
+                packed_attribute.text = getattr(self, attribute_name)
 
         return identifier_root
 
@@ -121,66 +155,54 @@ class Identifier(ABC):
         "Is this the same as another identifier (in value and schema)?"
         return self.value == other.value and self.schema == other.schema
 
+    def validate_require_globally_unique(self, api_client: "MarklogicApiClient") -> SuccessFailureMessageTuple:
+        """
+        Check against the list of identifiers in the database that this value does not currently exist.
 
-class Identifiers(dict[str, Identifier]):
-    def validate(self) -> None:
-        for uuid, identifier in self.items():
-            if uuid != identifier.uuid:
-                msg = "Key of {identifier} in Identifiers is {uuid} not {identifier.uuid}"
-                raise UUIDMismatchError(msg)
-
-    def contains(self, other_identifier: Identifier) -> bool:
-        "Do the identifier's value and namespace already exist in this group?"
-        return any(other_identifier.same_as(identifier) for identifier in self.values())
-
-    def add(self, identifier: Identifier) -> None:
-        if not self.contains(identifier):
-            self[identifier.uuid] = identifier
-
-    def __delitem__(self, key: Union[Identifier, str]) -> None:
-        if isinstance(key, Identifier):
-            super().__delitem__(key.uuid)
-        else:
-            super().__delitem__(key)
+        nb: We don't need to check that the identifier value is unique within a parent `Identifiers` object, because `Identifiers.add()` will only allow one value per namespace.
+        """
+        resolutions = [
+            resolution
+            for resolution in api_client.resolve_from_identifier_value(identifier_value=self.value)
+            if resolution.identifier_namespace == self.schema.namespace
+        ]
+        if len(resolutions) > 0:
+            return SuccessFailureMessageTuple(
+                False,
+                [f'Identifiers in scheme "{self.schema.namespace}" must be unique; "{self.value}" already exists!'],
+            )
 
-    def of_type(self, identifier_type: type[Identifier]) -> list[Identifier]:
-        """Return a list of all identifiers of a given type."""
-        uuids = self.keys()
-        return [self[uuid] for uuid in list(uuids) if isinstance(self[uuid], identifier_type)]
+        return SuccessFailureMessageTuple(True, [])
 
-    def delete_type(self, deleted_identifier_type: type[Identifier]) -> None:
-        "For when we want an identifier to be the only valid identifier of that type, delete the others first"
-        uuids = self.keys()
-        for uuid in list(uuids):
-            # we could use compare to .schema instead, which would have diffferent behaviour for subclasses
-            if isinstance(self[uuid], deleted_identifier_type):
-                del self[uuid]
+    def validate_valid_for_document_type(self, document_type: type["Document"]) -> SuccessFailureMessageTuple:
+        document_type_classname = document_type.__name__
 
-    @property
-    def as_etree(self) -> etree._Element:
-        """Return an etree representation of all the Document's identifiers."""
-        identifiers_root = etree.Element("identifiers")
+        if self.schema.document_types and document_type_classname not in self.schema.document_types:
+            return SuccessFailureMessageTuple(
+                False,
+                [
+                    f'Document type "{document_type_classname}" is not accepted for identifier schema "{self.schema.name}"'
+                ],
+            )
 
-        for identifier in self.values():
-            identifiers_root.append(identifier.as_xml_tree)
+        return SuccessFailureMessageTuple(True, [])
 
-        return identifiers_root
+    def perform_all_validations(
+        self, document_type: type["Document"], api_client: "MarklogicApiClient"
+    ) -> SuccessFailureMessageTuple:
+        """Perform all validations on a given identifier"""
+        validations = [
+            self.validate_require_globally_unique(api_client=api_client),
+            self.validate_valid_for_document_type(document_type=document_type),
+        ]
 
-    def by_score(self, type: Optional[type[Identifier]] = None) -> list[Identifier]:
-        """
-        :param type: Optionally, an identifier type to constrain this list to.
+        success = True
+        messages: list[str] = []
 
-        :return: Return a list of identifiers, sorted by their score in descending order.
-        """
-        identifiers = self.of_type(type) if type else list(self.values())
-        return sorted(identifiers, key=lambda v: v.score, reverse=True)
+        for validation in validations:
+            if validation.success is False:
+                success = False
 
-    def preferred(self, type: Optional[type[Identifier]] = None) -> Optional[Identifier]:
-        """
-        :param type: Optionally, an identifier type to constrain the results to.
+            messages += validation.messages
 
-        :return: Return the highest scoring identifier of the given type (or of any type, if none is specified). Returns `None` if no identifier is available.
-        """
-        if len(self.by_score(type)) == 0:
-            return None
-        return self.by_score(type)[0]
+        return SuccessFailureMessageTuple(success, messages)

caselawclient/models/identifiers/collection.py

@@ -0,0 +1,102 @@
+from typing import TYPE_CHECKING, Optional, Union
+
+from lxml import etree
+
+from caselawclient.types import SuccessFailureMessageTuple
+
+from . import Identifier
+from .exceptions import UUIDMismatchError
+from .fclid import FindCaseLawIdentifier
+from .neutral_citation import NeutralCitationNumber
+from .press_summary_ncn import PressSummaryRelatedNCNIdentifier
+
+if TYPE_CHECKING:
+    from caselawclient.Client import MarklogicApiClient
+    from caselawclient.models.documents import Document
+
+SUPPORTED_IDENTIFIER_TYPES: list[type["Identifier"]] = [
+    FindCaseLawIdentifier,
+    NeutralCitationNumber,
+    PressSummaryRelatedNCNIdentifier,
+]
+
+
+class IdentifiersCollection(dict[str, Identifier]):
+    def validate_uuids_match_keys(self) -> None:
+        for uuid, identifier in self.items():
+            if uuid != identifier.uuid:
+                msg = "Key of {identifier} in Identifiers is {uuid} not {identifier.uuid}"
+                raise UUIDMismatchError(msg)
+
+    def perform_all_validations(
+        self, document_type: type["Document"], api_client: "MarklogicApiClient"
+    ) -> SuccessFailureMessageTuple:
+        self.validate_uuids_match_keys()
+
+        success = True
+        messages: list[str] = []
+
+        for _, identifier in self.items():
+            validations = identifier.perform_all_validations(document_type=document_type, api_client=api_client)
+            if validations.success is False:
+                success = False
+
+            messages += validations.messages
+
+        return SuccessFailureMessageTuple(success, messages)
+
+    def contains(self, other_identifier: Identifier) -> bool:
+        "Do the identifier's value and namespace already exist in this group?"
+        return any(other_identifier.same_as(identifier) for identifier in self.values())
+
+    def add(self, identifier: Identifier) -> None:
+        if not self.contains(identifier):
+            self[identifier.uuid] = identifier
+
+    def __delitem__(self, key: Union[Identifier, str]) -> None:
+        if isinstance(key, Identifier):
+            super().__delitem__(key.uuid)
+        else:
+            super().__delitem__(key)
+
+    def of_type(self, identifier_type: type[Identifier]) -> list[Identifier]:
+        """Return a list of all identifiers of a given type."""
+        uuids = self.keys()
+        return [self[uuid] for uuid in list(uuids) if isinstance(self[uuid], identifier_type)]
+
+    def delete_type(self, deleted_identifier_type: type[Identifier]) -> None:
+        "For when we want an identifier to be the only valid identifier of that type, delete the others first"
+        uuids = self.keys()
+        for uuid in list(uuids):
+            # we could use compare to .schema instead, which would have diffferent behaviour for subclasses
+            if isinstance(self[uuid], deleted_identifier_type):
+                del self[uuid]
+
+    @property
+    def as_etree(self) -> etree._Element:
+        """Return an etree representation of all the Document's identifiers."""
+        identifiers_root = etree.Element("identifiers")
+
+        for identifier in self.values():
+            identifiers_root.append(identifier.as_xml_tree)
+
+        return identifiers_root
+
+    def by_score(self, type: Optional[type[Identifier]] = None) -> list[Identifier]:
+        """
+        :param type: Optionally, an identifier type to constrain this list to.
+
+        :return: Return a list of identifiers, sorted by their score in descending order.
+        """
+        identifiers = self.of_type(type) if type else list(self.values())
+        return sorted(identifiers, key=lambda v: v.score, reverse=True)
+
+    def preferred(self, type: Optional[type[Identifier]] = None) -> Optional[Identifier]:
+        """
+        :param type: Optionally, an identifier type to constrain the results to.
+
+        :return: Return the highest scoring identifier of the given type (or of any type, if none is specified). Returns `None` if no identifier is available.
+        """
+        if len(self.by_score(type)) == 0:
+            return None
+        return self.by_score(type)[0]

caselawclient/models/identifiers/fclid.py

@@ -32,8 +32,11 @@ class FindCaseLawIdentifierSchema(IdentifierSchema):
     human_readable = False
     base_score_multiplier = 0.6
 
+    allow_editing = False
+    require_globally_unique = True
+
     @classmethod
-    def validate_identifier(cls, value: str) -> bool:
+    def validate_identifier_value(cls, value: str) -> bool:
         return bool(VALID_FCLID_PATTERN.match(value))
 
     @classmethod

caselawclient/models/identifiers/neutral_citation.py

@@ -48,8 +48,10 @@ class NeutralCitationNumberSchema(IdentifierSchema):
     human_readable = True
     base_score_multiplier = 1.5
 
+    document_types = ["Judgment"]
+
     @classmethod
-    def validate_identifier(cls, value: str) -> bool:
+    def validate_identifier_value(cls, value: str) -> bool:
         # Quick check to see if the NCN matches the expected pattern
         if not bool(VALID_NCN_PATTERN.match(value)):
             raise NCNDoesNotMatchExpectedPatternException(f"NCN '{value}' is not in the expected format")

caselawclient/models/identifiers/press_summary_ncn.py

@@ -13,6 +13,8 @@ class PressSummaryRelatedNCNIdentifierSchema(NeutralCitationNumberSchema):
     human_readable = True
     base_score_multiplier = 0.8
 
+    document_types = ["PressSummary"]
+
     @classmethod
     def compile_identifier_url_slug(cls, value: str) -> DocumentIdentifierSlug:
         return DocumentIdentifierSlug(super().compile_identifier_url_slug(value) + "/press-summary")

caselawclient/models/identifiers/unpacker.py

@@ -3,22 +3,18 @@ from warnings import warn
 
 from lxml import etree
 
-from . import IDENTIFIER_UNPACKABLE_ATTRIBUTES, Identifier, Identifiers
+from . import IDENTIFIER_UNPACKABLE_ATTRIBUTES, Identifier
+from .collection import SUPPORTED_IDENTIFIER_TYPES, IdentifiersCollection
 from .exceptions import InvalidIdentifierXMLRepresentationException
-from .fclid import FindCaseLawIdentifier
-from .neutral_citation import NeutralCitationNumber
-from .press_summary_ncn import PressSummaryRelatedNCNIdentifier
 
 IDENTIFIER_NAMESPACE_MAP: dict[str, type[Identifier]] = {
-    "fclid": FindCaseLawIdentifier,
-    "ukncn": NeutralCitationNumber,
-    "uksummaryofncn": PressSummaryRelatedNCNIdentifier,
+    identifier_type.schema.namespace: identifier_type for identifier_type in SUPPORTED_IDENTIFIER_TYPES
 }
 
 
-def unpack_all_identifiers_from_etree(identifiers_etree: Optional[etree._Element]) -> Identifiers:
+def unpack_all_identifiers_from_etree(identifiers_etree: Optional[etree._Element]) -> IdentifiersCollection:
     """This expects the entire <identifiers> tag, and unpacks all Identifiers inside it"""
-    identifiers = Identifiers()
+    identifiers = IdentifiersCollection()
     if identifiers_etree is None:
         return identifiers
     for identifier_etree in identifiers_etree.findall("identifier"):
@@ -43,14 +39,23 @@ def unpack_an_identifier_from_etree(identifier_xml: etree._Element) -> Optional[
         warn(f"Identifier type {namespace_element.text} is not known.")
         return None
 
-    kwargs: dict[str, str] = {}
+    str_kwargs: dict[str, str] = {}
+    deprecated = False
 
     for attribute in IDENTIFIER_UNPACKABLE_ATTRIBUTES:
         element = identifier_xml.find(attribute)
-        if element is None or not element.text:
-            raise InvalidIdentifierXMLRepresentationException(
-                f"Identifer XML representation is not valid: {element} not present or empty"
-            )
-        kwargs[attribute] = element.text
 
-    return IDENTIFIER_NAMESPACE_MAP[namespace_element.text](**kwargs)
+        # Special case for unpacking deprecation state into a boolean
+        if attribute == "deprecated":
+            if element is not None and element.text is not None and element.text.lower() == "true":
+                deprecated = True
+
+        else:
+            # Case for unpacking all other element types
+            if element is None or not element.text:
+                raise InvalidIdentifierXMLRepresentationException(
+                    f"Identifer XML representation is not valid: {element} not present or empty"
+                )
+            str_kwargs[attribute] = element.text
+
+    return IDENTIFIER_NAMESPACE_MAP[namespace_element.text](deprecated=deprecated, **str_kwargs)

caselawclient/responses/search_result.py

@@ -12,7 +12,7 @@ from ds_caselaw_utils.types import CourtCode, JurisdictionCode
 from lxml import etree
 
 from caselawclient.Client import MarklogicApiClient
-from caselawclient.models.identifiers import Identifiers
+from caselawclient.models.identifiers.collection import IdentifiersCollection
 from caselawclient.models.identifiers.unpacker import unpack_all_identifiers_from_etree
 from caselawclient.types import DocumentURIString
 from caselawclient.xml_helpers import get_xpath_match_string
@@ -180,7 +180,7 @@ class SearchResult:
         )
 
     @property
-    def identifiers(self) -> Identifiers:
+    def identifiers(self) -> IdentifiersCollection:
         identifiers_etrees = self._get_xpath(".//identifiers")
         count = len(identifiers_etrees)
         if count != 1:

caselawclient/types.py

@@ -1,3 +1,6 @@
+from typing import NamedTuple
+
+
 class InvalidDocumentURIException(Exception):
     """The document URI is not valid."""
 
@@ -58,3 +61,11 @@ class DocumentIdentifierSlug(str):
 
 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).
+
+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.
+"""

caselawclient/xslt/modify_xml_live.xsl

@@ -0,0 +1,67 @@
+<?xml version="1.0"?>
+<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:uk='https://caselaw.nationalarchives.gov.uk/akn' xmlns:akn='http://docs.oasis-open.org/legaldocml/ns/akn/3.0'>
+
+    <xsl:param name="work_uri" />
+    <xsl:param name="expression_uri" />
+    <xsl:param name="manifestation_uri" />
+    <xsl:output method="xml" indent="yes" />
+
+    <!-- Identify transformation -->
+    <xsl:template match="@* | node()">
+        <xsl:copy>
+            <xsl:apply-templates select="@* | node()" />
+        </xsl:copy>
+    </xsl:template>
+
+    <!-- <xsl:template match="akn:identification/FRBRWork/FRBRthistext/text()"><xsl:copy-of select="$cat" /></xsl:template> -->
+
+    <xsl:template match="akn:identification/akn:FRBRWork/akn:FRBRthis">
+        <akn:FRBRthis>
+            <xsl:attribute name="value">
+                <xsl:value-of select="$work_uri" />
+            </xsl:attribute>
+        </akn:FRBRthis>
+    </xsl:template>
+
+    <xsl:template match="akn:identification/akn:FRBRWork/akn:FRBRuri">
+        <akn:FRBRuri>
+            <xsl:attribute name="value">
+                <xsl:value-of select="$work_uri" />
+            </xsl:attribute>
+        </akn:FRBRuri>
+    </xsl:template>
+
+    <xsl:template match="akn:identification/akn:FRBRExpression/akn:FRBRthis">
+        <akn:FRBRthis>
+            <xsl:attribute name="value">
+                <xsl:value-of select="$expression_uri" />
+            </xsl:attribute>
+        </akn:FRBRthis>
+    </xsl:template>
+
+    <xsl:template match="akn:identification/akn:FRBRExpression/akn:FRBRuri">
+        <akn:FRBRuri>
+            <xsl:attribute name="value">
+                <xsl:value-of select="$expression_uri" />
+            </xsl:attribute>
+        </akn:FRBRuri>
+    </xsl:template>
+
+    <xsl:template match="akn:identification/akn:FRBRManifestation/akn:FRBRthis">
+        <akn:FRBRthis>
+            <xsl:attribute name="value">
+                <xsl:value-of select="$manifestation_uri" />
+            </xsl:attribute>
+        </akn:FRBRthis>
+    </xsl:template>
+
+    <xsl:template match="akn:identification/akn:FRBRManifestation/akn:FRBRuri">
+        <akn:FRBRuri>
+            <xsl:attribute name="value">
+                <xsl:value-of select="$manifestation_uri" />
+            </xsl:attribute>
+        </akn:FRBRuri>
+    </xsl:template>
+
+
+</xsl:stylesheet>

caselawclient/xslt/sample.xsl

@@ -0,0 +1,26 @@
+<?xml version="1.0"?>
+<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+    xmlns:uk='https://caselaw.nationalarchives.gov.uk/akn'
+    xmlns:akn='http://docs.oasis-open.org/legaldocml/ns/akn/3.0'>
+
+    <xsl:param name="dog" />
+    <xsl:param name="cat" />
+    <xsl:output method="xml" indent="yes" />
+
+    <xsl:template match="@* | node()">
+        <xsl:copy>
+            <xsl:apply-templates select="@* | node()" />
+        </xsl:copy>
+    </xsl:template>
+
+    <xsl:template match="akn:text/text()"><xsl:copy-of select="$cat" /></xsl:template>
+
+    <xsl:template match="akn:attribute">
+        <akn:attribute>
+            <xsl:attribute name="attribute">
+                <xsl:value-of select="$dog" />
+            </xsl:attribute>
+        </akn:attribute>
+    </xsl:template>
+
+</xsl:stylesheet>

{ds_caselaw_marklogic_api_client-37.3.1.dist-info → ds_caselaw_marklogic_api_client-38.0.0.dist-info}/METADATA

@@ -1,16 +1,17 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.3
 Name: ds-caselaw-marklogic-api-client
-Version: 37.3.1
+Version: 38.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
 Author: The National Archives
 Requires-Python: >=3.10.0,<4.0.0
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
+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.4.26,<2025.5.0)
+Requires-Dist: certifi (>=2025.6.15,<2025.7.0)
 Requires-Dist: charset-normalizer (>=3.0.0,<4.0.0)
 Requires-Dist: django-environ (>=0.12.0)
 Requires-Dist: ds-caselaw-utils (>=2.0.0,<3.0.0)
@@ -26,6 +27,7 @@ Requires-Dist: requests-toolbelt (>=0.10.1,<1.1.0)
 Requires-Dist: saxonche (>=12.5.0,<13.0.0)
 Requires-Dist: sqids (>=0.5.0,<0.6.0)
 Requires-Dist: typing-extensions (>=4.7.1,<5.0.0)
+Project-URL: Homepage, https://github.com/nationalarchives/ds-caselaw-custom-api-client
 Description-Content-Type: text/markdown
 
 # The National Archives: Find Case Law

{ds_caselaw_marklogic_api_client-37.3.1.dist-info → ds_caselaw_marklogic_api_client-38.0.0.dist-info}/RECORD

@@ -4,21 +4,22 @@ caselawclient/client_helpers/__init__.py,sha256=eucyUXwUqI72TPw-C5zLcHlMu4GtFY50
 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=XgrnG61hAJ-ty61DLv2qNEAo9ITuDZowZ4MRmPrf2Bg,7109
+caselawclient/factories.py,sha256=eGj9TiZpmF3todW-08Ps7bHNMvByHqwEbgujRhvU_Yc,7382
 caselawclient/identifier_resolution.py,sha256=B5I1sD7o7YjzsXMECjbKjgiGLDda5bGhejsJ-lYpTIg,2429
 caselawclient/models/__init__.py,sha256=kd23EUpvaC7aLHdgk8farqKAQEx3lf7RvNT2jEatvlg,68
-caselawclient/models/documents/__init__.py,sha256=zDrR6XniqB6S2BkNJH8KfvPz-RCBjPVG_N6eJkJiIlA,19467
-caselawclient/models/documents/body.py,sha256=IVcuSbgA7SvCvii_VE8MZy_54enDZY8VPoESkUDgfKU,6114
-caselawclient/models/documents/exceptions.py,sha256=Mz1P8uNqf5w6uLnRwJt6xK7efsVqtd5VA-WXUUH7QLk,285
+caselawclient/models/documents/__init__.py,sha256=3iEzgjX4ooLUKEuAeOylEUTm5rUQkrRztBmv4Rp1Ub4,21117
+caselawclient/models/documents/body.py,sha256=O1ZTV3KHo-YNi7Syd4oCV1CVSuRF7mcLXojwshyY4jg,6601
+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=HlmPb63lLMnySSOLP4iexcAyQiLByKBZtTd25f8sY8M,1268
-caselawclient/models/identifiers/__init__.py,sha256=_iAsx_e-Rxq3ED3TQQ5Vg1ZNnQn6AZQK8QCvHSFhdGg,6848
+caselawclient/models/documents/xml.py,sha256=UPGL4Bm-RRde3ezkm1s1zcL-XdNqy1ncRcbsZNLtGn4,2135
+caselawclient/models/identifiers/__init__.py,sha256=IOMGUT4he1sZ7imjJupkyataB8OHMlsidoHFZJTWFsU,7581
+caselawclient/models/identifiers/collection.py,sha256=zcdFE831vYBh1dueULdKu3cdVEgUlNwCIwq6XNEC36M,4062
 caselawclient/models/identifiers/exceptions.py,sha256=ckVsjPzLuTXkbd7KZRJXoxcltQCXPGL2rMyYwE5orgg,177
-caselawclient/models/identifiers/fclid.py,sha256=Gq0G0eLdUH3j7VybluqJGVcHV3Y-hpjty1OdR91dI5Q,1453
-caselawclient/models/identifiers/neutral_citation.py,sha256=mFc-nYDIkLf5fM2eTSBnBigVgxuDcUF2HuMwQYEYeXY,2871
-caselawclient/models/identifiers/press_summary_ncn.py,sha256=CKhNTnO6pfriS4Sg-gt0Pf0fRhH53Uf0flULPncJWM4,762
-caselawclient/models/identifiers/unpacker.py,sha256=fKfiuTKaN-71e40PV8BC9PueKjwgfX9Xw3IVdy8mkqg,2299
+caselawclient/models/identifiers/fclid.py,sha256=hj8z-VhXFrUHKOY6k_ItPvOakIvbhJ5xEbZ04E2j7t8,1521
+caselawclient/models/identifiers/neutral_citation.py,sha256=bYAeXHVm_ls0aDTeYI4uv35iZmJGSKU4-H-iLh2xED0,2912
+caselawclient/models/identifiers/press_summary_ncn.py,sha256=t-x6PsEe2tz1uO1qZKXKK0TugkQYb_49O_xgjd_oiE4,801
+caselawclient/models/identifiers/unpacker.py,sha256=OpFBw1B6pqSuzcyHbnTY3dScHc2Ujt5StGRnh-tKE1Q,2592
 caselawclient/models/judgments.py,sha256=r40irgdEID-NeSNLm3OUdUBznMpRSwjD2SJrGlBgP8o,2208
 caselawclient/models/neutral_citation_mixin.py,sha256=jAac3PPuWyPdj9N-n-U_JfwkbgbSIXaqFVQahfu95do,2086
 caselawclient/models/parser_logs.py,sha256=30kF4w0GcowiMIFtymUkl7ZARanNh_PjDpJZezn-cA8,315
@@ -30,10 +31,10 @@ caselawclient/models/utilities/move.py,sha256=MXdUqkSiyqRb8YKs_66B6ICWn8EWM6DiJV
 caselawclient/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 caselawclient/responses/__init__.py,sha256=2-5NJn_PXPTje_W4dHeHYaNRN6vXK4UcB9eLLNUAKa4,67
 caselawclient/responses/search_response.py,sha256=Z76Zj4VvM-EV_vdiehv2-Jfkr9HZD3SvCTlRrUB_cyE,1951
-caselawclient/responses/search_result.py,sha256=sGVIJMLXuN2A2MFPPDoOkXu3SE4wO5IcelLZj4yfWuY,9385
+caselawclient/responses/search_result.py,sha256=gjSpnfygw9mEgKa3_sL-6O8JkGYSyxmrPpwwMMuf-ZQ,9416
 caselawclient/responses/xsl/search_match.xsl,sha256=4Sv--MrwBd7J48E9aI7jlFSXGlNi4dBqgzJ3bdMJ_ZU,1018
 caselawclient/search_parameters.py,sha256=A-9icXdyFYLDACjUaRQF8mrnaVRlFJ9XCPtu5uZ-_Lo,3484
-caselawclient/types.py,sha256=0PsEsQzJOInpuwZ-Ydw0UpGns6jbHzlJhc-Ms28sqCU,2064
+caselawclient/types.py,sha256=5lE_0kRd7ZMUkr53Rh4ooo74Ab8JTXnMo8rNrwn_HUo,2578
 caselawclient/xml_helpers.py,sha256=xCboRhhzezqh-VyoKBQwal5lwxv96vTMJyVFWJNN-ok,639
 caselawclient/xquery/break_judgment_checkout.xqy,sha256=rISzoBKxQKrP5ZRdCSoRqOXW8T_NDBSZRFjOXo_H3ns,220
 caselawclient/xquery/checkin_judgment.xqy,sha256=QeGqO3kL-q0UrjopCVU0lCbkwbyoc5SuNLYFAIbbyMg,197
@@ -83,7 +84,9 @@ caselawclient/xquery/validate_document.xqy,sha256=PgaDcnqCRJPIVqfmWsNlXmCLNKd21q
 caselawclient/xquery/xslt.xqy,sha256=w57wNijH3dkwHkpKeAxqjlghVflQwo8cq6jS_sm-erM,199
 caselawclient/xquery/xslt_transform.xqy,sha256=cccaFiGkCcvSfDv007UriZ3I4ak2nTLP1trRZdbOoS8,2462
 caselawclient/xquery_type_dicts.py,sha256=zuyDGTkcN6voOXCm3APXItZ-Ey6tZ2hdZummZWzjl50,6489
-ds_caselaw_marklogic_api_client-37.3.1.dist-info/LICENSE.md,sha256=fGMzyyLuQW-IAXUeDSCrRdsYW536aEWThdbpCjo6ZKg,1108
-ds_caselaw_marklogic_api_client-37.3.1.dist-info/METADATA,sha256=RzqWJC6SHrgrCLLOl4aRL8Th3lhaycwYMR8uATPDZeg,4206
-ds_caselaw_marklogic_api_client-37.3.1.dist-info/WHEEL,sha256=7Z8_27uaHI_UZAc4Uox4PpBhQ9Y5_modZXWMxtUi4NU,88
-ds_caselaw_marklogic_api_client-37.3.1.dist-info/RECORD,,
+caselawclient/xslt/modify_xml_live.xsl,sha256=F-0FM0OhT9Ua1WVEVeHYwwVkktmTOERykOuGhMrKans,2346
+caselawclient/xslt/sample.xsl,sha256=IG-v77stjwqiw25pguh391K-5DTKiX651WqILDZixm0,825
+ds_caselaw_marklogic_api_client-38.0.0.dist-info/LICENSE.md,sha256=fGMzyyLuQW-IAXUeDSCrRdsYW536aEWThdbpCjo6ZKg,1108
+ds_caselaw_marklogic_api_client-38.0.0.dist-info/METADATA,sha256=uvG9_FZesFrKHYJLzQpYw1JokKUIyrqAe7WPf1oVq2A,4320
+ds_caselaw_marklogic_api_client-38.0.0.dist-info/WHEEL,sha256=XbeZDeTWKc1w7CSIyre5aMDU_-PohRwTQceYnisIYYY,88
+ds_caselaw_marklogic_api_client-38.0.0.dist-info/RECORD,,

{ds_caselaw_marklogic_api_client-37.3.1.dist-info → ds_caselaw_marklogic_api_client-38.0.0.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: poetry-core 1.5.2
+Generator: poetry-core 2.1.1
 Root-Is-Purelib: true
 Tag: py3-none-any