ds-caselaw-marklogic-api-client 31.0.1__tar.gz → 31.2.0__tar.gz

{ds_caselaw_marklogic_api_client-31.0.1 → ds_caselaw_marklogic_api_client-31.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: ds-caselaw-marklogic-api-client
-Version: 31.0.1
+Version: 31.2.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-31.0.1 → ds_caselaw_marklogic_api_client-31.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "ds-caselaw-marklogic-api-client"
-version = "31.0.1"
+version = "31.2.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"

{ds_caselaw_marklogic_api_client-31.0.1 → ds_caselaw_marklogic_api_client-31.2.0}/src/caselawclient/Client.py

@@ -30,7 +30,7 @@ from caselawclient.models.judgments import Judgment
 from caselawclient.models.press_summaries import PressSummary
 from caselawclient.models.utilities import move
 from caselawclient.search_parameters import SearchParameters
-from caselawclient.types import DocumentURIString
+from caselawclient.types import DocumentIdentifierSlug, DocumentIdentifierValue, DocumentURIString
 from caselawclient.xquery_type_dicts import (
     MarkLogicDocumentURIString,
     MarkLogicDocumentVersionURIString,
@@ -1203,11 +1203,13 @@ class MarklogicApiClient:
 
         return results
 
-    def resolve_from_identifier_slug(self, identifier_uri: str, published_only: bool = True) -> IdentifierResolutions:
+    def resolve_from_identifier_slug(
+        self, identifier_slug: DocumentIdentifierSlug, 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.ResolveFromIdentifierSlugDict = {
-            "identifier_uri": DocumentURIString(identifier_uri),
+            "identifier_slug": identifier_slug,
             "published_only": int(published_only),
         }
         raw_results: list[str] = get_multipart_strings_from_marklogic_response(
@@ -1218,14 +1220,8 @@ class MarklogicApiClient:
         )
         return IdentifierResolutions.from_marklogic_output(raw_results)
 
-    def resolve_from_identifier(self, identifier_uri: str, published_only: bool = True) -> IdentifierResolutions:
-        warnings.warn(
-            "resolve_from_identifier deprecated, use resolve_from_identifier_slug instead", DeprecationWarning
-        )
-        return self.resolve_from_identifier_slug(identifier_uri, published_only)
-
     def resolve_from_identifier_value(
-        self, identifier_value: str, published_only: bool = True
+        self, identifier_value: DocumentIdentifierValue, 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"""

{ds_caselaw_marklogic_api_client-31.0.1 → ds_caselaw_marklogic_api_client-31.2.0}/src/caselawclient/factories.py

@@ -9,6 +9,8 @@ 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.fclid import FindCaseLawIdentifier
 from caselawclient.models.judgments import Judgment
 from caselawclient.models.press_summaries import PressSummary
 from caselawclient.responses.search_result import SearchResult, SearchResultMetadata
@@ -68,8 +70,12 @@ class DocumentFactory:
         cls,
         uri: DocumentURIString = DocumentURIString("test/2023/123"),
         api_client: Optional[MarklogicApiClient] = None,
+        identifiers: Optional[list[Identifier]] = None,
         **kwargs: Any,
     ) -> target_class:
+        def _fake_linked_documents(*args: Any, **kwargs: Any) -> list["Document"]:
+            return [document]
+
         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")
@@ -78,6 +84,14 @@ class DocumentFactory:
         document = cls.target_class(uri, api_client=api_client)
         document.body = kwargs.pop("body") if "body" in kwargs else DocumentBodyFactory.build()
 
+        if identifiers is None:
+            document.identifiers.add(FindCaseLawIdentifier(value="a1b2c3"))
+        else:
+            for identifier in identifiers:
+                document.identifiers.add(identifier)
+
+        setattr(document, "linked_documents", _fake_linked_documents)
+
         for param_name, default_value in cls.PARAMS_MAP.items():
             value = kwargs.get(param_name, default_value)
             setattr(document, param_name, value)

{ds_caselaw_marklogic_api_client-31.0.1 → ds_caselaw_marklogic_api_client-31.2.0}/src/caselawclient/identifier_resolution.py

@@ -3,7 +3,7 @@ from typing import NamedTuple
 
 from caselawclient.models.identifiers import Identifier
 from caselawclient.models.identifiers.unpacker import IDENTIFIER_NAMESPACE_MAP
-from caselawclient.types import DocumentURIString
+from caselawclient.types import DocumentIdentifierSlug, DocumentIdentifierValue
 from caselawclient.xquery_type_dicts import MarkLogicDocumentURIString
 
 
@@ -31,9 +31,9 @@ class IdentifierResolution(NamedTuple):
 
     identifier_uuid: str
     document_uri: MarkLogicDocumentURIString
-    identifier_slug: DocumentURIString
+    identifier_slug: DocumentIdentifierSlug
     document_published: bool
-    identifier_value: str
+    identifier_value: DocumentIdentifierValue
     identifier_namespace: str
     identifier_type: type[Identifier]
 
@@ -44,9 +44,9 @@ class IdentifierResolution(NamedTuple):
         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"]),
+            identifier_slug=DocumentIdentifierSlug(row["documents.compiled_url_slugs.identifier_slug"]),
             document_published=row["documents.compiled_url_slugs.document_published"] == "true",
-            identifier_value=row["documents.compiled_url_slugs.identifier_value"],
+            identifier_value=DocumentIdentifierValue(row["documents.compiled_url_slugs.identifier_value"]),
             identifier_namespace=identifier_namespace,
             identifier_type=IDENTIFIER_NAMESPACE_MAP[identifier_namespace],
         )

{ds_caselaw_marklogic_api_client-31.0.1 → ds_caselaw_marklogic_api_client-31.2.0}/src/caselawclient/models/documents/__init__.py

@@ -161,7 +161,19 @@ class Document:
         """
         :return: The absolute, public URI at which a copy of this document can be found
         """
-        return f"https://caselaw.nationalarchives.gov.uk/{self.uri}"
+        return f"https://caselaw.nationalarchives.gov.uk/{self.slug}"
+
+    @cached_property
+    def slug(self) -> str:
+        """
+        :return: The best public-facing URL for the judgment, which is the slug
+        of the most-preferred identifier, which should either be an NCN or fclid.
+        """
+        preferred_identifier = self.identifiers.preferred()
+        if preferred_identifier:
+            return preferred_identifier.url_slug
+        msg = f"No preferred identifier exists for {self.uri}"
+        raise RuntimeError(msg)
 
     @cached_property
     def is_published(self) -> bool:
@@ -497,7 +509,7 @@ class Document:
             raise AttributeError(f"Neither 'Document' nor 'DocumentBody' objects have an attribute '{name}'")
 
     def linked_document_resolutions(self, namespaces: list[str], only_published: bool = True) -> IdentifierResolutions:
-        """Get documents which share the same neutral citation as this document."""
+        """Get document resolutions which share the same neutral citation as this document."""
         if not hasattr(self, "neutral_citation") or not self.neutral_citation:
             return IdentifierResolutions([])
 
@@ -513,3 +525,10 @@ class Document:
                 if resolution.document_uri != self.uri.as_marklogic() and resolution.identifier_namespace in namespaces
             ]
         )
+
+    def linked_documents(self, namespaces: list[str], only_published: bool = True) -> list["Document"]:
+        resolutions = self.linked_document_resolutions(namespaces=namespaces, only_published=only_published)
+        return [
+            Document(resolution.document_uri.as_document_uri(), api_client=self.api_client)
+            for resolution in resolutions
+        ]

{ds_caselaw_marklogic_api_client-31.0.1 → ds_caselaw_marklogic_api_client-31.2.0}/src/caselawclient/models/identifiers/__init__.py

@@ -4,6 +4,8 @@ from uuid import uuid4
 
 from lxml import etree
 
+from caselawclient.types import DocumentIdentifierSlug, DocumentIdentifierValue
+
 IDENTIFIER_PACKABLE_ATTRIBUTES: list[str] = [
     "uuid",
     "value",
@@ -60,7 +62,7 @@ class IdentifierSchema(ABC):
 
     @classmethod
     @abstractmethod
-    def compile_identifier_url_slug(cls, value: str) -> str:
+    def compile_identifier_url_slug(cls, value: str) -> DocumentIdentifierSlug:
         """Convert an identifier into a precompiled URL slug."""
         pass
 
@@ -71,7 +73,7 @@ class Identifier(ABC):
     schema: type[IdentifierSchema]
 
     uuid: str
-    value: str
+    value: DocumentIdentifierValue
 
     def __init_subclass__(cls: type["Identifier"], **kwargs: Any) -> None:
         """Ensure that subclasses have the required attributes set."""
@@ -87,7 +89,7 @@ class Identifier(ABC):
         return self.value
 
     def __init__(self, value: str, uuid: Optional[str] = None) -> None:
-        self.value = value
+        self.value = DocumentIdentifierValue(value)
         if uuid:
             self.uuid = uuid
         else:

{ds_caselaw_marklogic_api_client-31.0.1 → ds_caselaw_marklogic_api_client-31.2.0}/src/caselawclient/models/identifiers/fclid.py

@@ -3,6 +3,8 @@ from typing import TYPE_CHECKING
 
 from sqids import Sqids
 
+from caselawclient.types import DocumentIdentifierSlug
+
 from . import Identifier, IdentifierSchema
 
 if TYPE_CHECKING:
@@ -35,8 +37,8 @@ class FindCaseLawIdentifierSchema(IdentifierSchema):
         return bool(VALID_FCLID_PATTERN.match(value))
 
     @classmethod
-    def compile_identifier_url_slug(cls, value: str) -> str:
-        return "tna." + value
+    def compile_identifier_url_slug(cls, value: str) -> DocumentIdentifierSlug:
+        return DocumentIdentifierSlug("tna." + value)
 
     @classmethod
     def mint(cls, api_client: "MarklogicApiClient") -> "FindCaseLawIdentifier":

{ds_caselaw_marklogic_api_client-31.0.1 → ds_caselaw_marklogic_api_client-31.2.0}/src/caselawclient/models/identifiers/neutral_citation.py

@@ -3,6 +3,8 @@ import re
 from ds_caselaw_utils import neutral_url
 from ds_caselaw_utils.types import NeutralCitationString
 
+from caselawclient.types import DocumentIdentifierSlug
+
 from . import Identifier, IdentifierSchema
 
 VALID_NCN_PATTERN = re.compile(r"(^\[([0-9]{4})\] ([a-zA-Z]+)(?: ([a-zA-Z]+))? ([0-9]+)(?: \(([a-zA-Z]+)\))?$)")
@@ -38,13 +40,13 @@ class NeutralCitationNumberSchema(IdentifierSchema):
         return bool(VALID_NCN_PATTERN.match(value))
 
     @classmethod
-    def compile_identifier_url_slug(cls, value: str) -> str:
+    def compile_identifier_url_slug(cls, value: str) -> DocumentIdentifierSlug:
         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
+        return DocumentIdentifierSlug(ncn_based_uri_string)
 
 
 class NeutralCitationNumber(Identifier):

{ds_caselaw_marklogic_api_client-31.0.1 → ds_caselaw_marklogic_api_client-31.2.0}/src/caselawclient/models/identifiers/press_summary_ncn.py

@@ -1,3 +1,5 @@
+from caselawclient.types import DocumentIdentifierSlug
+
 from .neutral_citation import NeutralCitationNumber, NeutralCitationNumberSchema
 
 
@@ -12,8 +14,8 @@ class PressSummaryRelatedNCNIdentifierSchema(NeutralCitationNumberSchema):
     base_score_multiplier = 0.5
 
     @classmethod
-    def compile_identifier_url_slug(cls, value: str) -> str:
-        return super().compile_identifier_url_slug(value) + "/press-summary"
+    def compile_identifier_url_slug(cls, value: str) -> DocumentIdentifierSlug:
+        return DocumentIdentifierSlug(super().compile_identifier_url_slug(value) + "/press-summary")
 
 
 class PressSummaryRelatedNCNIdentifier(NeutralCitationNumber):

{ds_caselaw_marklogic_api_client-31.0.1 → ds_caselaw_marklogic_api_client-31.2.0}/src/caselawclient/types.py

@@ -2,8 +2,29 @@ class InvalidDocumentURIException(Exception):
     """The document URI is not valid."""
 
 
+class InvalidMarkLogicDocumentURIException(Exception):
+    """The MarkLogic document URI is not valid."""
+
+
 class MarkLogicDocumentURIString(str):
-    pass
+    def __new__(cls, content: str) -> "MarkLogicDocumentURIString":
+        # Check that the URI begins with a slash
+        if content[0] != "/":
+            raise InvalidMarkLogicDocumentURIException(
+                f'"{content}" is not a valid MarkLogic document URI; URIs must begin with a slash.'
+            )
+
+        # Check that the URI ends with ".xml"
+        if not content.endswith(".xml"):
+            raise InvalidMarkLogicDocumentURIException(
+                f'"{content}" is not a valid MarkLogic document URI; URIs must end with ".xml". '
+            )
+
+        # If everything is good, return as usual
+        return str.__new__(cls, content)
+
+    def as_document_uri(self) -> "DocumentURIString":
+        return DocumentURIString(self.lstrip("/").rstrip(".xml"))
 
 
 class DocumentURIString(str):
@@ -29,3 +50,11 @@ class DocumentURIString(str):
 
     def as_marklogic(self) -> MarkLogicDocumentURIString:
         return MarkLogicDocumentURIString(f"/{self}.xml")
+
+
+class DocumentIdentifierSlug(str):
+    pass
+
+
+class DocumentIdentifierValue(str):
+    pass

{ds_caselaw_marklogic_api_client-31.0.1 → ds_caselaw_marklogic_api_client-31.2.0}/src/caselawclient/xquery/resolve_from_identifier_slug.xqy

@@ -1,7 +1,7 @@
 xquery version "1.0-ml";
 
 declare namespace xdmp="http://marklogic.com/xdmp"; 
-declare variable $identifier_uri as xs:string external;
+declare variable $identifier_slug 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 ""
@@ -11,7 +11,6 @@ return xdmp:sql(
   $query,
   "map",
   map:new((
-    map:entry("uri", $identifier_uri)
+    map:entry("uri", $identifier_slug)
   ))
 )
-

{ds_caselaw_marklogic_api_client-31.0.1 → ds_caselaw_marklogic_api_client-31.2.0}/src/caselawclient/xquery_type_dicts.py

@@ -7,7 +7,7 @@ checks. They are used to enforce appropriately typed variables being passed in t
 """
 
 from typing import Any, NewType, Optional, TypedDict
-from caselawclient.types import DocumentURIString
+from caselawclient.types import DocumentURIString, DocumentIdentifierSlug, DocumentIdentifierValue
 from caselawclient.types import MarkLogicDocumentURIString as MarkLogicDocumentURIString
 
 MarkLogicDocumentVersionURIString = NewType("MarkLogicDocumentVersionURIString", MarkLogicDocumentURIString)
@@ -143,13 +143,13 @@ class ListJudgmentVersionsDict(MarkLogicAPIDict):
 
 # resolve_from_identifier_slug.xqy
 class ResolveFromIdentifierSlugDict(MarkLogicAPIDict):
-    identifier_uri: DocumentURIString
+    identifier_slug: DocumentIdentifierSlug
     published_only: Optional[int]
 
 
 # resolve_from_identifier_value.xqy
 class ResolveFromIdentifierValueDict(MarkLogicAPIDict):
-    identifier_value: str
+    identifier_value: DocumentIdentifierValue
     published_only: Optional[int]