ds-caselaw-marklogic-api-client 27.4.0__py3-none-any.whl → 28.1.0__py3-none-any.whl

caselawclient/Client.py

@@ -13,12 +13,14 @@ from xml.etree.ElementTree import Element, ParseError, fromstring
 import environ
 import requests
 from ds_caselaw_utils.types import NeutralCitationString
+from lxml import etree
 from requests.auth import HTTPBasicAuth
 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,
@@ -209,12 +211,14 @@ class MarklogicApiClient:
         Returns a list of PressSummary objects associated with a given Document URI
         """
         vars: query_dicts.GetComponentsForDocumentDict = {
-            "parent_uri": DocumentURIString(uri if uri.startswith("/") else "/" + uri),
+            "parent_uri": uri,
             "component": "pressSummary",
         }
         response = self._send_to_eval(vars, "get_components_for_document.xqy")
         uris = get_multipart_strings_from_marklogic_response(response)
-        return [PressSummary(uri.strip(".xml"), self) for uri in uris]
+        return [
+            PressSummary(DocumentURIString(uri.strip("/").strip(".xml")), self) for uri in uris
+        ]  # TODO: Migrate this strip behaviour into proper manipulation of a MarkLogicURIString
 
     def get_document_by_uri(
         self,
@@ -862,6 +866,17 @@ class MarklogicApiClient:
         }
         return self._eval_and_decode(vars, "get_property.xqy")
 
+    def get_property_as_node(self, judgment_uri: DocumentURIString, name: str) -> Optional[etree._Element]:
+        uri = self._format_uri_for_marklogic(judgment_uri)
+        vars: query_dicts.GetPropertyAsNodeDict = {
+            "uri": uri,
+            "name": name,
+        }
+        value = self._eval_and_decode(vars, "get_property_as_node.xqy")
+        if not value:
+            return None
+        return etree.fromstring(value)
+
     def get_version_annotation(self, judgment_uri: DocumentURIString) -> str:
         uri = self._format_uri_for_marklogic(judgment_uri)
         vars: query_dicts.GetVersionAnnotationDict = {
@@ -894,6 +909,22 @@ class MarklogicApiClient:
 
         return self._send_to_eval(vars, "set_property.xqy")
 
+    def set_property_as_node(
+        self,
+        judgment_uri: DocumentURIString,
+        name: str,
+        value: etree._Element,
+    ) -> requests.Response:
+        """Given a root node, set the value of the MarkLogic property for a document to the _contents_ of that root node. The root node itself is discarded."""
+        uri = self._format_uri_for_marklogic(judgment_uri)
+        vars: query_dicts.SetPropertyAsNodeDict = {
+            "uri": uri,
+            "value": etree.tostring(value).decode(),
+            "name": name,
+        }
+
+        return self._send_to_eval(vars, "set_property_as_node.xqy")
+
     def set_boolean_property(
         self,
         judgment_uri: DocumentURIString,
@@ -1107,6 +1138,21 @@ class MarklogicApiClient:
 
         return results
 
+    def get_recently_enriched(
+        self,
+    ) -> list[list[Any]]:
+        """Retrieve documents which are not yet enriched with a given version."""
+        results: list[list[Any]] = json.loads(
+            get_single_string_from_marklogic_response(
+                self._send_to_eval(
+                    {},
+                    "get_recently_enriched.xqy",
+                ),
+            ),
+        )
+
+        return results
+
     def get_highest_parser_version(self) -> tuple[int, int]:
         """This gets the highest parser version in the database, so if nothing has been parsed with the most recent version of the parser, this won't reflect that change."""
         table = json.loads(
@@ -1141,3 +1187,33 @@ class MarklogicApiClient:
         )
 
         return results
+
+    def get_recently_parsed(
+        self,
+    ) -> list[list[Any]]:
+        """Retrieve documents which are not yet enriched with a given version."""
+        results: list[list[Any]] = json.loads(
+            get_single_string_from_marklogic_response(
+                self._send_to_eval(
+                    {},
+                    "get_recently_parsed.xqy",
+                ),
+            ),
+        )
+
+        return results
+
+    def resolve_from_identifier(self, identifier_uri: str, published_only: bool = True) -> IdentifierResolutions:
+        """Given a PUI/EUI url, look up the precomputed slug and return the
+        MarkLogic document URIs which match that slug. Multiple returns should be anticipated"""
+        vars: query_dicts.ResolveFromIdentifierDict = {
+            "identifier_uri": DocumentURIString(identifier_uri),
+            "published_only": int(published_only),
+        }
+        raw_results: list[str] = get_multipart_strings_from_marklogic_response(
+            self._send_to_eval(
+                vars,
+                "resolve_from_identifier.xqy",
+            ),
+        )
+        return IdentifierResolutions.from_marklogic_output(raw_results)

caselawclient/factories.py

@@ -5,7 +5,7 @@ from unittest.mock import Mock
 from typing_extensions import TypeAlias
 
 from caselawclient.Client import MarklogicApiClient
-from caselawclient.models.documents import Document
+from caselawclient.models.documents import Document, DocumentURIString
 from caselawclient.models.documents.body import DocumentBody
 from caselawclient.models.judgments import Judgment
 from caselawclient.models.press_summaries import PressSummary
@@ -54,7 +54,7 @@ class DocumentFactory:
     @classmethod
     def build(
         cls,
-        uri: str = "test/2023/123",
+        uri: DocumentURIString = DocumentURIString("test/2023/123"),
         html: str = "<p>This is a judgment.</p>",
         api_client: Optional[MarklogicApiClient] = None,
         **kwargs: Any,
@@ -62,6 +62,7 @@ class DocumentFactory:
         if not api_client:
             api_client = Mock(spec=MarklogicApiClient)
             api_client.get_judgment_xml_bytestring.return_value = DEFAULT_DOCUMENT_BODY_XML.encode(encoding="utf-8")
+            api_client.get_property_as_node.return_value = None
 
         document = cls.target_class(uri, api_client=api_client)
         document.content_as_html = Mock(return_value=html)  # type: ignore[method-assign]

caselawclient/identifier_resolution.py

@@ -0,0 +1,43 @@
+import json
+from typing import NamedTuple
+
+from caselawclient.models.documents import DocumentURIString
+from caselawclient.xquery_type_dicts import MarkLogicDocumentURIString
+
+
+class IdentifierResolutions(list["IdentifierResolution"]):
+    """
+    A list of candidate MarkLogic documents which correspond to a Public UI uri
+
+    MarkLogic returns a list of dictionaries; IdentifierResolution handles a single dictionary
+    which corresponds to a single identifier to MarkLogic document mapping.
+
+    see `xquery/resolve_from_identifier.xqy` and `resolve_from_identifier` in `Client.py`
+    """
+
+    @staticmethod
+    def from_marklogic_output(table: list[str]) -> "IdentifierResolutions":
+        return IdentifierResolutions(list(IdentifierResolution.from_marklogic_output(row) for row in table))
+
+    def published(self) -> "IdentifierResolutions":
+        "Filter the list so that only published documents are returned"
+        return IdentifierResolutions(list(x for x in self if x.document_published))
+
+
+class IdentifierResolution(NamedTuple):
+    """A single response from MarkLogic about a single identifier / document mapping"""
+
+    identifier_uuid: str
+    document_uri: MarkLogicDocumentURIString
+    identifier_slug: DocumentURIString
+    document_published: bool
+
+    @staticmethod
+    def from_marklogic_output(raw_row: str) -> "IdentifierResolution":
+        row = json.loads(raw_row)
+        return IdentifierResolution(
+            identifier_uuid=row["documents.compiled_url_slugs.identifier_uuid"],
+            document_uri=MarkLogicDocumentURIString(row["documents.compiled_url_slugs.document_uri"]),
+            identifier_slug=DocumentURIString(row["documents.compiled_url_slugs.identifier_slug"]),
+            document_published=row["documents.compiled_url_slugs.document_published"] == "true",
+        )

caselawclient/models/documents/__init__.py

@@ -1,7 +1,7 @@
 import datetime
 import warnings
 from functools import cached_property
-from typing import TYPE_CHECKING, Any, NewType, Optional
+from typing import TYPE_CHECKING, Any, Optional
 
 from ds_caselaw_utils import courts
 from ds_caselaw_utils.courts import CourtNotFoundException
@@ -15,6 +15,7 @@ from caselawclient.errors import (
     NotSupportedOnVersion,
     OnlySupportedOnVersion,
 )
+from caselawclient.models.identifiers.unpacker import unpack_all_identifiers_from_etree
 from caselawclient.models.utilities import VersionsDict, extract_version, render_versions
 from caselawclient.models.utilities.aws import (
     ParserInstructionsDict,
@@ -30,7 +31,7 @@ from caselawclient.models.utilities.aws import (
 )
 
 from .body import DocumentBody
-from .exceptions import CannotPublishUnpublishableDocument, DocumentNotSafeForDeletion
+from .exceptions import CannotPublishUnpublishableDocument, DocumentNotSafeForDeletion, InvalidDocumentURIException
 from .statuses import DOCUMENT_STATUS_HOLD, DOCUMENT_STATUS_IN_PROGRESS, DOCUMENT_STATUS_NEW, DOCUMENT_STATUS_PUBLISHED
 
 MINIMUM_ENRICHMENT_TIME = datetime.timedelta(minutes=20)
@@ -47,7 +48,26 @@ if TYPE_CHECKING:
     from caselawclient.Client import MarklogicApiClient
 
 
-DocumentURIString = NewType("DocumentURIString", str)
+class DocumentURIString(str):
+    """
+    This class checks that the string is actually a valid Document URI on creation. It does _not_ manipulate the string.
+    """
+
+    def __new__(cls, content: str) -> "DocumentURIString":
+        # Check that the URI doesn't begin or end with a slash
+        if content[0] == "/" or content[-1] == "/":
+            raise InvalidDocumentURIException(
+                f'"{content}" is not a valid document URI; URIs cannot begin or end with slashes.'
+            )
+
+        # Check that the URI doesn't contain a full stop
+        if "." in content:
+            raise InvalidDocumentURIException(
+                f'"{content}" is not a valid document URI; URIs cannot contain full stops.'
+            )
+
+        # If everything is good, return as usual
+        return str.__new__(cls, content)
 
 
 class Document:
@@ -105,13 +125,15 @@ class Document:
     Individual document classes should extend this list where necessary to validate document type-specific attributes.
     """
 
-    def __init__(self, uri: str, api_client: "MarklogicApiClient", search_query: Optional[str] = None):
+    def __init__(self, uri: DocumentURIString, api_client: "MarklogicApiClient", search_query: Optional[str] = None):
         """
-        :param uri: For historical reasons this accepts a pseudo-URI which may include leading or trailing slashes.
+        :param uri: The URI of the document to retrieve from MarkLogic.
+        :param api_client: An instance of the API client object to handle communication with the MarkLogic server.
+        :param search_query: Optionally, a search string which should be highlighted if it appears in the document body.
 
         :raises DocumentNotFoundError: The document does not exist within MarkLogic
         """
-        self.uri: DocumentURIString = DocumentURIString(uri.strip("/"))
+        self.uri: DocumentURIString = uri
         self.api_client: MarklogicApiClient = api_client
         if not self.document_exists():
             raise DocumentNotFoundError(f"Document {self.uri} does not exist")
@@ -123,7 +145,9 @@ class Document:
                 search_query=search_query,
             ),
         )
-        """ `Document.body` represents the XML of the document itself, without any information such as version tracking or properties. """
+        """ `Document.body` represents the body of the document itself, without any information such as version tracking or properties. """
+
+        self._initialise_identifiers()
 
     def __repr__(self) -> str:
         name = self.body.name or "un-named"
@@ -139,6 +163,12 @@ class Document:
         """There is a docx in S3 private bucket for this Document"""
         return check_docx_exists(self.uri)
 
+    def _initialise_identifiers(self) -> None:
+        """Load this document's identifiers from MarkLogic."""
+
+        identifiers_element_as_etree = self.api_client.get_property_as_node(self.uri, "identifiers")
+        self.identifiers = unpack_all_identifiers_from_etree(identifiers_element_as_etree)
+
     @property
     def best_human_identifier(self) -> Optional[str]:
         """
@@ -500,6 +530,11 @@ class Document:
         """
         return self.docx_exists()
 
+    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)
+
     def __getattr__(self, name: str) -> Any:
         warnings.warn(f"{name} no longer exists on Document, using Document.body instead", DeprecationWarning)
         try:

caselawclient/models/documents/exceptions.py

@@ -4,3 +4,7 @@ class CannotPublishUnpublishableDocument(Exception):
 
 class DocumentNotSafeForDeletion(Exception):
     """A document which is not safe for deletion cannot be deleted."""
+
+
+class InvalidDocumentURIException(Exception):
+    """The document URI is not valid."""

caselawclient/models/documents/xml.py

@@ -17,7 +17,7 @@ class XML:
         :raises NonXMLDocumentError: This document is not valid XML
         """
         try:
-            self.xml_as_tree: etree.Element = etree.fromstring(xml_bytestring)
+            self.xml_as_tree: etree._Element = etree.fromstring(xml_bytestring)
         except etree.XMLSyntaxError:
             raise NonXMLDocumentError
 

caselawclient/models/identifiers/__init__.py

@@ -0,0 +1,146 @@
+from abc import ABC, abstractmethod
+from typing import Any, Optional, Union
+from uuid import uuid4
+
+from lxml import etree
+
+IDENTIFIER_PACKABLE_ATTRIBUTES: list[str] = [
+    "uuid",
+    "value",
+    "url_slug",
+]
+
+IDENTIFIER_UNPACKABLE_ATTRIBUTES: list[str] = [
+    "uuid",
+    "value",
+]
+
+
+class InvalidIdentifierXMLRepresentationException(Exception):
+    pass
+
+
+class UUIDMismatchError(Exception):
+    pass
+
+
+class IdentifierSchema(ABC):
+    """
+    A base class which describes what an identifier schema should look like.
+    """
+
+    name: str
+    namespace: str
+
+    def __init_subclass__(cls: type["IdentifierSchema"], **kwargs: Any) -> None:
+        """Ensure that subclasses have the required attributes set."""
+        for required in (
+            "name",
+            "namespace",
+        ):
+            if not getattr(cls, required, False):
+                raise NotImplementedError(f"Can't instantiate IdentifierSchema without {required} attribute.")
+        super().__init_subclass__(**kwargs)
+
+    def __repr__(self) -> str:
+        return self.name
+
+    @classmethod
+    @abstractmethod
+    def validate_identifier(cls, value: str) -> bool:
+        """Check that any given identifier value is valid for this schema."""
+        pass
+
+    @classmethod
+    @abstractmethod
+    def compile_identifier_url_slug(cls, value: str) -> str:
+        """Convert an identifier into a precompiled URL slug."""
+        pass
+
+
+class Identifier(ABC):
+    """A base class for subclasses representing a concrete identifier."""
+
+    schema: type[IdentifierSchema]
+
+    uuid: str
+    value: str
+
+    def __init_subclass__(cls: type["Identifier"], **kwargs: Any) -> None:
+        """Ensure that subclasses have the required attributes set."""
+        for required in ("schema",):
+            if not getattr(cls, required, False):
+                raise NotImplementedError(f"Can't instantiate Identifier without {required} attribute.")
+        super().__init_subclass__(**kwargs)
+
+    def __repr__(self) -> str:
+        return f"<{self.schema.name} {self.value}: {self.uuid}>"
+
+    def __init__(self, value: str, uuid: Optional[str] = None) -> None:
+        self.value = value
+        if uuid:
+            self.uuid = uuid
+        else:
+            self.uuid = "id-" + str(uuid4())
+
+    @property
+    def as_xml_tree(self) -> etree._Element:
+        """Convert this Identifier into a packed XML representation for storage."""
+        identifier_root = etree.Element("identifier")
+
+        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)
+
+        return identifier_root
+
+    @property
+    def url_slug(self) -> str:
+        return self.schema.compile_identifier_url_slug(self.value)
+
+    def same_as(self, other: "Identifier") -> bool:
+        "Is this the same as another identifier (in value and schema)?"
+        return self.value == other.value and self.schema == other.schema
+
+
+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)
+
+    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

caselawclient/models/identifiers/neutral_citation.py

@@ -0,0 +1,49 @@
+import re
+
+from ds_caselaw_utils import neutral_url
+from ds_caselaw_utils.types import NeutralCitationString
+
+from . import Identifier, IdentifierSchema
+
+VALID_NCN_PATTERN = re.compile(r"(^\[([0-9]{4})\] ([a-zA-Z]+)(?: ([a-zA-Z]+))? ([0-9]+)(?: \(([a-zA-Z]+)\))?$)")
+"""
+This is a catch-all pattern for anything which looks like a Neutral Citation, even if the court itself isn't valid. Checking that an NCN is plausibly correct is handled elsewhere.
+
+This pattern also defines five capture groups to standardise how we interface with the elements:
+
+- `0`: The year of the decision
+- `1`: The court
+- `2`: (Optionally) the jurisdiction or division, depending on the court
+- `3`: The sequence number of the decision
+- `4`: (Optionally) the jurisdiction or division, depending on the court
+
+TODO: When these capture groups are being used in anger (eg to build URL slugs) you should go through and name the groups.
+"""
+
+
+class NeutralCitationNumberSchema(IdentifierSchema):
+    """
+    Identifier schema describing a Neutral Citation Number.
+
+    https://www.iclr.co.uk/knowledge/case-law/neutral-citations/
+    """
+
+    name = "Neutral Citation Number"
+    namespace = "ukncn"
+
+    @classmethod
+    def validate_identifier(cls, value: str) -> bool:
+        return bool(VALID_NCN_PATTERN.match(value))
+
+    @classmethod
+    def compile_identifier_url_slug(cls, value: str) -> str:
+        ncn_based_uri_string = neutral_url(
+            NeutralCitationString(value)
+        )  # TODO: At some point this should move out of utils and into this class.
+        if not ncn_based_uri_string:
+            raise Exception(f"Unable to convert NCN {value} into NCN-based URL slug")
+        return ncn_based_uri_string
+
+
+class NeutralCitationNumber(Identifier):
+    schema = NeutralCitationNumberSchema

caselawclient/models/identifiers/unpacker.py

@@ -0,0 +1,44 @@
+from typing import Optional
+
+from lxml import etree
+
+from . import IDENTIFIER_UNPACKABLE_ATTRIBUTES, Identifier, Identifiers, InvalidIdentifierXMLRepresentationException
+from .neutral_citation import NeutralCitationNumber
+
+IDENTIFIER_NAMESPACE_MAP: dict[str, type[Identifier]] = {
+    "ukncn": NeutralCitationNumber,
+}
+
+
+def unpack_all_identifiers_from_etree(identifiers_etree: Optional[etree._Element]) -> Identifiers:
+    """This expects the entire <identifiers> tag, and unpacks all Identifiers inside it"""
+    identifiers = Identifiers()
+    if identifiers_etree is None:
+        return identifiers
+    for identifier_etree in identifiers_etree.findall("identifier"):
+        identifier = unpack_an_identifier_from_etree(identifier_etree)
+        identifiers.add(identifier)
+    return identifiers
+
+
+def unpack_an_identifier_from_etree(identifier_xml: etree._Element) -> Identifier:
+    """Given an etree representation of a single identifier, unpack it into an appropriate instance of an Identifier."""
+
+    namespace_element = identifier_xml.find("namespace")
+
+    if namespace_element is None or not namespace_element.text:
+        raise InvalidIdentifierXMLRepresentationException(
+            "Identifer XML representation is not valid: namespace not present or empty"
+        )
+
+    kwargs: dict[str, str] = {}
+
+    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)

caselawclient/models/judgments.py

@@ -10,7 +10,7 @@ from caselawclient.models.neutral_citation_mixin import NeutralCitationMixin
 if TYPE_CHECKING:
     from caselawclient.models.press_summaries import PressSummary
 
-from .documents import Document
+from .documents import Document, DocumentURIString
 
 
 class Judgment(NeutralCitationMixin, Document):
@@ -21,8 +21,8 @@ class Judgment(NeutralCitationMixin, Document):
     document_noun = "judgment"
     document_noun_plural = "judgments"
 
-    def __init__(self, *args: Any, **kwargs: Any) -> None:
-        super().__init__(self.document_noun, *args, **kwargs)
+    def __init__(self, uri: DocumentURIString, *args: Any, **kwargs: Any) -> None:
+        super().__init__(self.document_noun, uri, *args, **kwargs)
 
     @cached_property
     def neutral_citation(self) -> NeutralCitationString:
@@ -46,8 +46,9 @@ class Judgment(NeutralCitationMixin, Document):
         Attempt to fetch a linked press summary, and return it, if it exists
         """
         try:
-            uri = self.uri + "/press-summary/1"
-            PressSummary = importlib.import_module("caselawclient.models.press_summaries").PressSummary
-            return PressSummary(uri, self.api_client)  # type: ignore
+            uri = DocumentURIString(self.uri + "/press-summary/1")
+            if not TYPE_CHECKING:  # This isn't nice, but will be cleaned up when we refactor how related documents work
+                PressSummary = importlib.import_module("caselawclient.models.press_summaries").PressSummary
+            return PressSummary(uri, self.api_client)
         except DocumentNotFoundError:
             return None

caselawclient/models/press_summaries.py

@@ -9,7 +9,7 @@ from ds_caselaw_utils.types import NeutralCitationString
 from caselawclient.errors import DocumentNotFoundError
 from caselawclient.models.neutral_citation_mixin import NeutralCitationMixin
 
-from .documents import Document
+from .documents import Document, DocumentURIString
 
 if TYPE_CHECKING:
     from caselawclient.models.judgments import Judgment
@@ -23,8 +23,8 @@ class PressSummary(NeutralCitationMixin, Document):
     document_noun = "press summary"
     document_noun_plural = "press summaries"
 
-    def __init__(self, *args: Any, **kwargs: Any) -> None:
-        super().__init__(self.document_noun, *args, **kwargs)
+    def __init__(self, uri: DocumentURIString, *args: Any, **kwargs: Any) -> None:
+        super().__init__(self.document_noun, uri, *args, **kwargs)
 
     @cached_property
     def neutral_citation(self) -> NeutralCitationString:
@@ -47,8 +47,9 @@ class PressSummary(NeutralCitationMixin, Document):
         Attempt to fetch a linked judgement, and return it, if it exists
         """
         try:
-            uri = self.uri.removesuffix("/press-summary/1")
-            Judgment = importlib.import_module("caselawclient.models.judgments").Judgment
-            return Judgment(uri, self.api_client)  # type: ignore
+            uri = DocumentURIString(self.uri.removesuffix("/press-summary/1"))
+            if not TYPE_CHECKING:  # This isn't nice, but will be cleaned up when we refactor how related documents work
+                Judgment = importlib.import_module("caselawclient.models.judgments").Judgment
+            return Judgment(uri, self.api_client)
         except DocumentNotFoundError:
             return None

caselawclient/models/utilities/__init__.py

@@ -12,14 +12,14 @@ uk_namespace = {"uk": "https://caselaw.nationalarchives.gov.uk/akn"}
 
 
 class VersionsDict(TypedDict):
-    uri: str
+    uri: str  ## TODO: This should be either a MarkLogicDocumentURIString (raw from ML) or a DocumentURIString (and we parse it out). Just a str is too vague.
     version: int
 
 
 def render_versions(decoded_versions: list[BodyPart]) -> list[VersionsDict]:
     versions: list[VersionsDict] = [
         {
-            "uri": part.text.rstrip(".xml"),
+            "uri": part.text.strip("/").rstrip(".xml"),
             "version": extract_version(part.text),
         }
         for part in decoded_versions

caselawclient/models/utilities/aws.py

@@ -137,12 +137,14 @@ def publish_documents(uri: str) -> None:
     response = client.list_objects(Bucket=private_bucket, Prefix=uri)
 
     for result in response.get("Contents", []):
+        print(f"Contemplating copying {result!r}")
         key = str(result["Key"])
 
         if not key.endswith("parser.log") and not key.endswith(".tar.gz"):
             source: CopySourceTypeDef = {"Bucket": private_bucket, "Key": key}
             extra_args: dict[str, str] = {}
             try:
+                print(f"Copying {key!r} from {private_bucket!r} to {public_bucket!r}")
                 client.copy(source, public_bucket, key, extra_args)
             except botocore.client.ClientError as e:
                 logging.warning(

caselawclient/xml_helpers.py

@@ -9,8 +9,7 @@ def get_xpath_match_string(
     namespaces: Optional[Dict[str, str]] = None,
     fallback: str = "",
 ) -> str:
-    kwargs = {"namespaces": namespaces} if namespaces else {}
-    return str((node.xpath(path, **kwargs) or [fallback])[0])
+    return str((node.xpath(path, namespaces=namespaces) or [fallback])[0])
 
 
 def get_xpath_match_strings(
@@ -18,5 +17,4 @@ def get_xpath_match_strings(
     path: str,
     namespaces: Optional[Dict[str, str]] = None,
 ) -> list[str]:
-    kwargs = {"namespaces": namespaces} if namespaces else {}
-    return [str(x) for x in node.xpath(path, **kwargs)]
+    return [str(x) for x in node.xpath(path, namespaces=namespaces)]

caselawclient/xquery/get_components_for_document.xqy

@@ -14,7 +14,7 @@ let $docTypeQuery := cts:element-attribute-value-query(
     )
 let $refQuery := cts:element-query(
       xs:QName("uk:summaryOf"),
-      concat("https://caselaw.nationalarchives.gov.uk/id", $parent_uri)
+      concat("https://caselaw.nationalarchives.gov.uk/id/", $parent_uri)
     )
 
 return xdmp:node-uri(cts:search(//akn:akomaNtoso, cts:and-query(($refQuery, $collectionQuery, $docTypeQuery))))

caselawclient/xquery/get_property_as_node.xqy

@@ -0,0 +1,9 @@
+xquery version "1.0-ml";
+
+declare variable $uri as xs:string external;
+
+declare variable $name as xs:string external;
+
+let $prop := fn:QName("", $name)
+
+return xdmp:document-get-properties($uri, $prop)

caselawclient/xquery/get_recently_enriched.xqy

@@ -0,0 +1,18 @@
+xquery version "1.0-ml";
+
+declare namespace xdmp="http://marklogic.com/xdmp"; 
+xdmp:to-json(xdmp:sql(
+  "SELECT *, process_data.uri, hours_since_enrichment_request, enrich_major_version, enrich_minor_version
+  FROM (
+    SELECT 
+      process_data.uri, enrich_major_version, enrich_minor_version,
+      DATEDIFF('hour', last_sent_to_enrichment, CURRENT_TIMESTAMP) AS hours_since_enrichment_request
+    FROM documents.process_data
+    JOIN documents.process_property_data ON process_data.uri = process_property_data.uri
+  )
+  ORDER BY hours_since_enrichment_request ASC
+  LIMIT 1000",
+  "array",
+  map:new((
+  ))
+))

caselawclient/xquery/get_recently_parsed.xqy

@@ -0,0 +1,19 @@
+xquery version "1.0-ml";
+
+declare namespace xdmp="http://marklogic.com/xdmp"; 
+xdmp:to-json(xdmp:sql(
+  "SELECT process_data.uri, hours_since_parse_request, parser_major_version, parser_minor_version
+  FROM (
+    SELECT 
+      process_data.uri, parser_major_version, parser_minor_version,
+      DATEDIFF('hour', last_sent_to_parser, CURRENT_TIMESTAMP) AS hours_since_parse_request
+    FROM documents.process_data
+    JOIN documents.process_property_data ON process_data.uri = process_property_data.uri
+  )
+  ORDER BY hours_since_parse_request ASC
+  LIMIT 1000",
+  "array",
+  map:new((
+  ))
+))
+

caselawclient/xquery/resolve_from_identifier.xqy

@@ -0,0 +1,17 @@
+xquery version "1.0-ml";
+
+declare namespace xdmp="http://marklogic.com/xdmp"; 
+declare variable $identifier_uri as xs:string external;
+declare variable $published_only as xs:int? external := 1;
+
+let $published_query := if ($published_only) then " AND document_published = 'true'" else ""
+let $query := "SELECT * from compiled_url_slugs WHERE (identifier_slug = @uri)" ||  $published_query
+
+return xdmp:sql(
+  $query,
+  "map",
+  map:new((
+    map:entry("uri", $identifier_uri)
+  ))
+)
+

caselawclient/xquery/set_property_as_node.xqy

@@ -0,0 +1,11 @@
+xquery version "1.0-ml";
+
+import module namespace dls = "http://marklogic.com/xdmp/dls" at "/MarkLogic/dls.xqy";
+
+declare variable $uri as xs:string external;
+declare variable $value as xs:string external;
+declare variable $name as xs:string external;
+
+let $props := ( element {$name} {xdmp:unquote($value)/*/*} )
+
+return dls:document-set-property($uri, $props)

caselawclient/xquery_type_dicts.py

@@ -113,6 +113,12 @@ class GetPropertyDict(MarkLogicAPIDict):
     uri: MarkLogicDocumentURIString
 
 
+# get_property_as_node.xqy
+class GetPropertyAsNodeDict(MarkLogicAPIDict):
+    name: str
+    uri: MarkLogicDocumentURIString
+
+
 # get_version_annotation.xqy
 class GetVersionAnnotationDict(MarkLogicAPIDict):
     uri: MarkLogicDocumentURIString
@@ -135,6 +141,12 @@ class ListJudgmentVersionsDict(MarkLogicAPIDict):
     uri: MarkLogicDocumentURIString
 
 
+# resolve_from_identifier.xqy
+class ResolveFromIdentifierDict(MarkLogicAPIDict):
+    identifier_uri: DocumentURIString
+    published_only: Optional[int]
+
+
 # set_boolean_property.xqy
 class SetBooleanPropertyDict(MarkLogicAPIDict):
     name: str
@@ -187,6 +199,13 @@ class SetPropertyDict(MarkLogicAPIDict):
     value: str
 
 
+# set_property_as_node.xqy
+class SetPropertyAsNodeDict(MarkLogicAPIDict):
+    name: str
+    uri: MarkLogicDocumentURIString
+    value: str
+
+
 # update_document.xqy
 class UpdateDocumentDict(MarkLogicAPIDict):
     annotation: str

{ds_caselaw_marklogic_api_client-27.4.0.dist-info → ds_caselaw_marklogic_api_client-28.1.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: ds-caselaw-marklogic-api-client
-Version: 27.4.0
+Version: 28.1.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

{ds_caselaw_marklogic_api_client-27.4.0.dist-info → ds_caselaw_marklogic_api_client-28.1.0.dist-info}/RECORD

@@ -1,22 +1,26 @@
-caselawclient/Client.py,sha256=05vFmk39Gy23i-Mo04pZk_3EmsTe_2feIiwd7fXjDpM,40797
+caselawclient/Client.py,sha256=OFqiKNYuz8C7UF6AP36Bie64UP3p8mKLZ-NQIc_LEWc,43636
 caselawclient/__init__.py,sha256=DY-caubLDQWWingSdsBWgovDNXh8KcnkI6kwz08eIFk,612
 caselawclient/client_helpers/__init__.py,sha256=fyDNKCdrTb2N0Ks23YDhmvlXKfLTHnYQCXhnZb-QQbg,3832
 caselawclient/client_helpers/search_helpers.py,sha256=R99HyRLeYHgsw2L3DOidEqlKLLvs6Tga5rKTuWQViig,1525
 caselawclient/content_hash.py,sha256=0cPC4OoABq0SC2wYFX9-24DodNigeOqksDxgxQH_hUA,2221
 caselawclient/errors.py,sha256=tV0vs3wYSd331BzmfuRiZV6GAdsd91rtN65ymRaSx3s,3164
-caselawclient/factories.py,sha256=wTGGP8VyUME2gwbnuYE2uC5PdCdJ2PXF9gEET3U9CZg,4356
+caselawclient/factories.py,sha256=6-xZMVmvtXA8AnyWJgJTums1EWfM6lPIhrWQu0NopJo,4472
+caselawclient/identifier_resolution.py,sha256=IOqrZcIHoHhNOCAkNveOBcWddBNpkOB8cz1r0zFa8mQ,1829
 caselawclient/models/__init__.py,sha256=kd23EUpvaC7aLHdgk8farqKAQEx3lf7RvNT2jEatvlg,68
-caselawclient/models/documents/__init__.py,sha256=uNjmmNKAthBmB6RSNlmJPir3E2MGrYkcP17iEY-xtkk,17100
+caselawclient/models/documents/__init__.py,sha256=OF-0tTSA5VO6qi630zONrL2lC768yTkwHWmNyRxZ_D8,18762
 caselawclient/models/documents/body.py,sha256=mtdjmG1WU2qSpyRLS8-PWcSoXpDa2Qz6xlcTbxZgxvA,5603
-caselawclient/models/documents/exceptions.py,sha256=Mz1P8uNqf5w6uLnRwJt6xK7efsVqtd5VA-WXUUH7QLk,285
+caselawclient/models/documents/exceptions.py,sha256=rw1xId16vBKvBImgFmFUpeFgKqU7VTNtVLIEVBPGKyk,374
 caselawclient/models/documents/statuses.py,sha256=Cp4dTQmJOtsU41EJcxy5dV1841pGD2PNWH0VrkDEv4Q,579
 caselawclient/models/documents/transforms/html.xsl,sha256=oSSO-IBX4qLiSWexQYmWJfGNevF09aCBx4D1NYqXxpo,38322
-caselawclient/models/documents/xml.py,sha256=afEsgcnTThqW_gKYq-VGtFr4ovOoT2J7h2gXX7F8BbE,1267
-caselawclient/models/judgments.py,sha256=SuCNtOD4LElp37df4dvhaD0umTowioWH0sZNmBgFsoE,1739
+caselawclient/models/documents/xml.py,sha256=HlmPb63lLMnySSOLP4iexcAyQiLByKBZtTd25f8sY8M,1268
+caselawclient/models/identifiers/__init__.py,sha256=Ft0cFE7LlCecsS5In_hi9So0x6La1kRJ8Who-VgC4YM,4795
+caselawclient/models/identifiers/neutral_citation.py,sha256=yddlfumdnkrNpoTIOf8dB1foA7hE41-zmlfa17-Ulug,1790
+caselawclient/models/identifiers/unpacker.py,sha256=V79m4rd0FZx5TRueL1m3MbrSUWO8c0f5NoNxSP3dlFw,1757
+caselawclient/models/judgments.py,sha256=NVOg4ZTU7Jtr33UuswL2TXCaN6_W0fKFPK4EdQ-jUhE,1915
 caselawclient/models/neutral_citation_mixin.py,sha256=5ktKCPIDidVRwxVTzx5e242O1BxOdP--1dnatZyTbYI,1773
-caselawclient/models/press_summaries.py,sha256=ZJ5ZhamPTsj6-vO1g96aP_syzUC2RlLMhgr3xnI1PoM,1703
-caselawclient/models/utilities/__init__.py,sha256=aL1a2nDacPxninETeaVZKwOxZemgvm73IcpWgMNXoGc,1100
-caselawclient/models/utilities/aws.py,sha256=YQeuFdF5NvhUxo3Ejj3PURDlygA73oq2T42ltuQZ6Oo,8073
+caselawclient/models/press_summaries.py,sha256=06flQ8wSLnNxoQtXO0ckmotFKszYZcub0oPcDzYbVQw,1879
+caselawclient/models/utilities/__init__.py,sha256=u3yIhbTjFQ1JJyAm5wsMEBswWl4t6Z7UMORF5FqC2xQ,1257
+caselawclient/models/utilities/aws.py,sha256=umfPzjtykg_-OP1ACirpXfOLN4QenqA0A8tJk3DzYRk,8211
 caselawclient/models/utilities/dates.py,sha256=WwORxVjUHM1ZFcBF6Qtwo3Cj0sATsnSECkUZ6ls1N1Q,492
 caselawclient/models/utilities/move.py,sha256=Rsx1eGHVjbGz0WMVDjy8b_5t4Ig8aP55sLudL07MVUs,3621
 caselawclient/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -25,7 +29,7 @@ caselawclient/responses/search_response.py,sha256=Z76Zj4VvM-EV_vdiehv2-Jfkr9HZD3
 caselawclient/responses/search_result.py,sha256=2yR3FP4CQsVymE7RrOMbh1owjYaRTrqkjMObbIkSlhE,8216
 caselawclient/responses/xsl/search_match.xsl,sha256=4Sv--MrwBd7J48E9aI7jlFSXGlNi4dBqgzJ3bdMJ_ZU,1018
 caselawclient/search_parameters.py,sha256=nR-UC1aWZbdXzXBrVDaHECU4Ro8Zi4JZATtgrpAVsKY,3342
-caselawclient/xml_helpers.py,sha256=qmqdGhwrQ-zhvvB-8akwzWnC2uHponKkEnnRExqkx_A,591
+caselawclient/xml_helpers.py,sha256=FEtE8gxaEZmcgua-Xu8awPmiOm9K58OSabEYVGpiVEY,493
 caselawclient/xquery/break_judgment_checkout.xqy,sha256=rISzoBKxQKrP5ZRdCSoRqOXW8T_NDBSZRFjOXo_H3ns,220
 caselawclient/xquery/checkin_judgment.xqy,sha256=QeGqO3kL-q0UrjopCVU0lCbkwbyoc5SuNLYFAIbbyMg,197
 caselawclient/xquery/checkout_judgment.xqy,sha256=aRwVo4KXoEKXfXRZ6IrVfvh0pXK-7pFxVIgEyzE5DRY,385
@@ -34,7 +38,7 @@ caselawclient/xquery/delete_judgment.xqy,sha256=-t5uc_3nCKM1HMYqlfVxv_M4Ng2jGrEJ
 caselawclient/xquery/document_collections.xqy,sha256=hbKY4CNiqZTK6IiLOcIqOKim4YbJxzOsItis6N4pQmw,267
 caselawclient/xquery/document_exists.xqy,sha256=eh9pttmU9THjoUWT4eYckzJvWlHrAyKYbGjbCJvzscY,95
 caselawclient/xquery/get_combined_stats_table.xqy,sha256=cclNqSzIB6sX6A_hgVOFZonpPpwqZt9hofu1a_-jfuo,694
-caselawclient/xquery/get_components_for_document.xqy,sha256=qh_F56XEDyVKMIaN4J1fskcjYK3Mc6JR8ARGwS2b0lw,768
+caselawclient/xquery/get_components_for_document.xqy,sha256=qBOn5OI7ThK0OHizSm68oySfAdp2dsHFJaIMTI4iIC0,769
 caselawclient/xquery/get_highest_enrichment_version.xqy,sha256=a0dwVmEZuIMyRjIlvenSmbOaaN0WvgaCZvMtVWoLulQ,247
 caselawclient/xquery/get_highest_parser_version.xqy,sha256=LW3iSg4eWArbfBaCVWWOpr4MoUcDBz514nV48ElOsAM,247
 caselawclient/xquery/get_judgment.xqy,sha256=8V-sEFKmtpf2LIZD9QKVRfpblEsmDpP4BA6QztSCyHA,2216
@@ -45,10 +49,14 @@ caselawclient/xquery/get_pending_enrichment_for_version.xqy,sha256=8J5Pi-jMXJd_B
 caselawclient/xquery/get_pending_parse_for_version.xqy,sha256=9cjVZtHeBBjm-a7RMsn1PVJt_Ug78YFlmp5CN8VJ1jQ,1197
 caselawclient/xquery/get_properties_for_search_results.xqy,sha256=Tlv3EKwVV_q-JyQyhjWVHIleicPDpucxP4ScuQjpgSw,625
 caselawclient/xquery/get_property.xqy,sha256=RHlOTrK0aH-S7s_ykYzGmUeKOJxXlI4vE5sKRt556NY,209
+caselawclient/xquery/get_property_as_node.xqy,sha256=7EXNgjVD1QugJ1621pvg8PdjBRIuh7GugwARv04TuBk,202
+caselawclient/xquery/get_recently_enriched.xqy,sha256=qSA9EYlKaAyYwewBRj494aC_JnzlLzbsWyTgWIJqFbw,614
+caselawclient/xquery/get_recently_parsed.xqy,sha256=k8NP72O11FyDZ3MeKAJWlcrzPsynhPTddYIeS0pRaII,594
 caselawclient/xquery/get_version_annotation.xqy,sha256=pFDMGA9SxI59iUPaoAeUsq23kUp4Op7cUg-PFNFqxcI,262
 caselawclient/xquery/get_version_created.xqy,sha256=bRweaXFtwMBNzL16SlOdiOxHkbqNUwpwDHLxpZYVCh0,250
 caselawclient/xquery/insert_document.xqy,sha256=iP2xTaLGa-u6X9KfS1yJ6yPCKQUWQFYdEW1S4YcMY7w,531
 caselawclient/xquery/list_judgment_versions.xqy,sha256=WShga8igeD21hSLfVSvCOiDMPDhNH6KGf1OW6G0SAkY,190
+caselawclient/xquery/resolve_from_identifier.xqy,sha256=Fa-RSw9ZwD__BmT5LLJ0J0HcDstDbedkEccv45M3L4g,484
 caselawclient/xquery/set_boolean_property.xqy,sha256=8Vg3yDWqeDynUJQHw2OF4daDIKTnp8ARol1_OCqY0Dk,355
 caselawclient/xquery/set_metadata_citation.xqy,sha256=ImwijXowvOCiH_br_LepnKsEpys9tg4Cf3uz6MoC5-c,659
 caselawclient/xquery/set_metadata_court.xqy,sha256=xQGR3e4pdJuDPMlzdAdzrBDSeQbEFiLVIm2z_KQI_Ds,996
@@ -57,6 +65,7 @@ caselawclient/xquery/set_metadata_name.xqy,sha256=7UeCo13ePNPxXcz9v7o1Pw7MoL6b5v
 caselawclient/xquery/set_metadata_this_uri.xqy,sha256=lBHk2EJxcRcxu1JqNdBlSzUZmFvVaSs0vu2cVrt84c8,1762
 caselawclient/xquery/set_metadata_work_expression_date.xqy,sha256=eN4VvRA5FqP3aKrlvnqwa7e9mcuuNXqLH5_yHWvrjrU,1017
 caselawclient/xquery/set_property.xqy,sha256=wUDCMLrUUgTMqn_-_T48DXsdDLtFncrVjidVuCwtpS4,343
+caselawclient/xquery/set_property_as_node.xqy,sha256=85ywMo5VPGXBnHepIajDOPYEy_ZmeU_9glgDcJ_CwEI,362
 caselawclient/xquery/update_document.xqy,sha256=-kbv3Ig2nuBviCyn0R_H6GPE1kpDP4UOhWsYk5oBgtU,420
 caselawclient/xquery/update_locked_judgment.xqy,sha256=wFDEtKh7MxvPmEHrzOHTJIRlY01ATneESl-n_lIQ7cU,556
 caselawclient/xquery/user_has_privilege.xqy,sha256=TfqPjhdpXt-4Fo7E2kEYRhfqQm6uES-IuLbAlCxylbg,371
@@ -65,8 +74,8 @@ 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=smyFFxqmtkuOzBd2l7uw6K2oAsYctudrP8omdv_XNAM,2463
-caselawclient/xquery_type_dicts.py,sha256=AUEmycChASKl8sbqVQWe6WA0s-lIfEqh9mA-GdnUCQ8,5692
-ds_caselaw_marklogic_api_client-27.4.0.dist-info/LICENSE.md,sha256=fGMzyyLuQW-IAXUeDSCrRdsYW536aEWThdbpCjo6ZKg,1108
-ds_caselaw_marklogic_api_client-27.4.0.dist-info/METADATA,sha256=9acabO_PzOjK3LScvlra8WgiyVnNRb7ItdcjIBs1zsg,4232
-ds_caselaw_marklogic_api_client-27.4.0.dist-info/WHEEL,sha256=7Z8_27uaHI_UZAc4Uox4PpBhQ9Y5_modZXWMxtUi4NU,88
-ds_caselaw_marklogic_api_client-27.4.0.dist-info/RECORD,,
+caselawclient/xquery_type_dicts.py,sha256=kybL-YzwK34Fr6MeWfqVOJHYrs0ZNeDWXDsp8o2Yb1U,6114
+ds_caselaw_marklogic_api_client-28.1.0.dist-info/LICENSE.md,sha256=fGMzyyLuQW-IAXUeDSCrRdsYW536aEWThdbpCjo6ZKg,1108
+ds_caselaw_marklogic_api_client-28.1.0.dist-info/METADATA,sha256=e9Z30AABT4vao0GmVnuD8LPfK2dRXHXkBltukUpNzVM,4232
+ds_caselaw_marklogic_api_client-28.1.0.dist-info/WHEEL,sha256=7Z8_27uaHI_UZAc4Uox4PpBhQ9Y5_modZXWMxtUi4NU,88
+ds_caselaw_marklogic_api_client-28.1.0.dist-info/RECORD,,