ds-caselaw-marklogic-api-client 22.0.2__tar.gz → 23.0.1__tar.gz

{ds_caselaw_marklogic_api_client-22.0.2 → ds_caselaw_marklogic_api_client-23.0.1}/PKG-INFO

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

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "ds-caselaw-marklogic-api-client"
-version = "22.0.2"
+version = "23.0.1"
 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"
@@ -30,9 +30,10 @@ mypy-boto3-sns = "^1.26.69"
 [tool.poetry.group.dev.dependencies]
 coverage = "^7.2.3"
 pytest = "^7.3.2"
-responses = "^0.24.0"
+responses = "^0.25.0"
 python-dotenv = "^1.0.0"
 time-machine = "^2.13.0"
+moto = {version = "^5.0.1", extras = ["all"]}
 
 [tool.poetry.group.docs]
 optional = true

{ds_caselaw_marklogic_api_client-22.0.2 → ds_caselaw_marklogic_api_client-23.0.1}/src/caselawclient/Client.py

@@ -647,6 +647,22 @@ class MarklogicApiClient:
 
         return self._send_to_eval(vars, "get_judgment_version.xqy")
 
+    def validate_document(self, document_uri: DocumentURIString) -> bool:
+        vars: query_dicts.ValidateDocumentDict = {
+            "uri": self._format_uri_for_marklogic(document_uri)
+        }
+        response = self._send_to_eval(vars, "validate_document.xqy")
+        content = decoder.MultipartDecoder.from_response(response).parts[0].text
+        xml = ElementTree.fromstring(content)
+        return (
+            len(
+                xml.findall(
+                    ".//error:error", {"error": "http://marklogic.com/xdmp/error"}
+                ),
+            )
+            == 0
+        )
+
     def eval(
         self, xquery_path: str, vars: str, accept_header: str = "multipart/mixed"
     ) -> requests.Response:

{ds_caselaw_marklogic_api_client-22.0.2 → ds_caselaw_marklogic_api_client-23.0.1}/src/caselawclient/models/documents.py

@@ -22,6 +22,7 @@ from .utilities import VersionsDict, render_versions
 from .utilities.aws import (
     ParserInstructionsDict,
     announce_document_event,
+    check_docx_exists,
     delete_documents_from_private_bucket,
     generate_docx_url,
     generate_pdf_url,
@@ -31,6 +32,8 @@ from .utilities.aws import (
     uri_for_s3,
 )
 
+MINIMUM_ENRICHMENT_TIME = datetime.timedelta(minutes=20)
+
 
 class UnparsableDate(Warning):
     pass
@@ -165,13 +168,17 @@ class Document:
         :return: `True` if the document exists, `False` otherwise."""
         return self.api_client.document_exists(self.uri)
 
+    def docx_exists(self) -> bool:
+        """There is a docx in S3 private bucket for this Document"""
+        return check_docx_exists(self.uri)
+
     @property
     def best_human_identifier(self) -> Optional[str]:
         """
         Some identifier that is understood by legal professionals to refer to this legal event
         that is not the name of the document.
         Typically, this will be the neutral citation number, should it exist.
-        Should typically overridden in subclasses.
+        Should typically be overridden in subclasses.
         """
         return None
 
@@ -270,10 +277,12 @@ class Document:
 
     @cached_property
     def transformation_datetime(self) -> Optional[datetime.datetime]:
+        """When was this document successfully parsed or reparsed (date from XML)"""
         return self.get_latest_manifestation_datetime("transform")
 
     @cached_property
     def enrichment_datetime(self) -> Optional[datetime.datetime]:
+        """When was this document successfully enriched (date from XML)"""
         return self.get_latest_manifestation_datetime("tna-enriched")
 
     @cached_property
@@ -480,9 +489,9 @@ class Document:
 
         return DOCUMENT_STATUS_NEW
 
-    def enrich(self) -> None:
+    def force_enrich(self) -> None:
         """
-        Request enrichment of the document
+        Request enrichment of the document, but do no checks
         """
         now = datetime.datetime.now(datetime.timezone.utc)
         self.api_client.set_property(
@@ -495,6 +504,42 @@ class Document:
             enrich=True,
         )
 
+    def enrich(self) -> bool:
+        """
+        Request enrichment of a document, if it's sensible to do so.
+        """
+        if self.can_enrich:
+            self.force_enrich()
+            return True
+        return False
+
+    @cached_property
+    def can_enrich(self) -> bool:
+        """
+        Is it sensible to enrich this document?
+        """
+        if (self.enriched_recently is False) and self.validates_against_schema:
+            return True
+        return False
+
+    @cached_property
+    def enriched_recently(self) -> bool:
+        """
+        Has this document been enriched recently?
+        """
+        last_enrichment = self.enrichment_datetime
+        now = datetime.datetime.now(tz=datetime.timezone.utc)
+        if last_enrichment and now - last_enrichment < MINIMUM_ENRICHMENT_TIME:
+            return True
+        return False
+
+    @cached_property
+    def validates_against_schema(self) -> bool:
+        """
+        Does the document validate against the most recent schema?
+        """
+        return self.api_client.validate_document(self.uri)
+
     def publish(self) -> None:
         """
         :raises CannotPublishUnpublishableDocument: This document has not passed the checks in `is_publishable`, and as
@@ -553,7 +598,7 @@ class Document:
     def move(self, new_citation: str) -> None:
         self.api_client.update_document_uri(self.uri, new_citation)
 
-    def reparse(self) -> None:
+    def force_reparse(self) -> None:
         "Send an SNS notification that triggers reparsing, also sending all editor-modifiable metadata and URI"
 
         now = datetime.datetime.now(datetime.timezone.utc)
@@ -589,6 +634,21 @@ class Document:
             parser_instructions=parser_instructions,
         )
 
+    def reparse(self) -> bool:
+        if self.can_reparse:
+            self.force_reparse()
+            return True
+        return False
+
+    @cached_property
+    def can_reparse(self) -> bool:
+        """
+        Is it sensible to reparse this document?
+        """
+        if self.docx_exists():
+            return True
+        return False
+
     class XML:
         """
         Represents the XML of a document, and should contain all methods for interacting with it.

{ds_caselaw_marklogic_api_client-22.0.2 → ds_caselaw_marklogic_api_client-23.0.1}/src/caselawclient/models/judgments.py

@@ -1,8 +1,13 @@
+import importlib
 from functools import cached_property
-from typing import Any
+from typing import TYPE_CHECKING, Any, Optional
 
+from caselawclient.errors import DocumentNotFoundError
 from caselawclient.models.neutral_citation_mixin import NeutralCitationMixin
 
+if TYPE_CHECKING:
+    from caselawclient.models.press_summaries import PressSummary
+
 from ..xml_helpers import get_xpath_match_string
 from .documents import Document
 
@@ -32,3 +37,18 @@ class Judgment(NeutralCitationMixin, Document):
     @property
     def best_human_identifier(self) -> str:
         return self.neutral_citation
+
+    @cached_property
+    def linked_document(self) -> Optional["PressSummary"]:
+        """
+        Attempt to fetch a linked press summary, and return it, if it exists
+        """
+        try:
+            uri = self.uri + "/press-summary/1"
+            PressSummary = getattr(
+                importlib.import_module("caselawclient.models.press_summaries"),
+                "PressSummary",
+            )
+            return PressSummary(uri, self.api_client)  # type: ignore
+        except DocumentNotFoundError:
+            return None

{ds_caselaw_marklogic_api_client-22.0.2 → ds_caselaw_marklogic_api_client-23.0.1}/src/caselawclient/models/press_summaries.py

@@ -1,11 +1,18 @@
+from __future__ import annotations
+
+import importlib
 from functools import cached_property
-from typing import Any
+from typing import TYPE_CHECKING, Any, Optional
 
+from caselawclient.errors import DocumentNotFoundError
 from caselawclient.models.neutral_citation_mixin import NeutralCitationMixin
 from caselawclient.xml_helpers import get_xpath_match_string
 
 from .documents import Document
 
+if TYPE_CHECKING:
+    from caselawclient.models.judgments import Judgment
+
 
 class PressSummary(NeutralCitationMixin, Document):
     """
@@ -31,3 +38,18 @@ class PressSummary(NeutralCitationMixin, Document):
     @property
     def best_human_identifier(self) -> str:
         return self.neutral_citation
+
+    @cached_property
+    def linked_document(self) -> Optional["Judgment"]:
+        """
+        Attempt to fetch a linked judgement, and return it, if it exists
+        """
+        try:
+            uri = self.uri.removesuffix("/press-summary/1")
+            Judgment = getattr(
+                importlib.import_module("caselawclient.models.judgments"),
+                "Judgment",
+            )
+            return Judgment(uri, self.api_client)  # type: ignore
+        except DocumentNotFoundError:
+            return None

{ds_caselaw_marklogic_api_client-22.0.2 → ds_caselaw_marklogic_api_client-23.0.1}/src/caselawclient/models/utilities/aws.py

@@ -78,6 +78,20 @@ def generate_signed_asset_url(key: str) -> str:
     )
 
 
+def check_docx_exists(uri: str) -> bool:
+    """Does the docx for a document URI actually exist?"""
+    bucket = env("PRIVATE_ASSET_BUCKET", None)
+    s3_key = generate_docx_key(uri)
+    client = create_s3_client()
+    try:
+        client.head_object(Bucket=bucket, Key=s3_key)
+        return True
+    except botocore.exceptions.ClientError as e:
+        if e.response["Error"]["Code"] == "404":
+            return False
+        raise
+
+
 def generate_docx_key(uri: str) -> str:
     """from a canonical caselaw URI (eat/2022/1) return the S3 key of the associated docx"""
     return f'{uri}/{uri.replace("/", "_")}.docx'
@@ -227,7 +241,7 @@ def request_parse(
             .replace("+00:00", "Z"),
             "function": "fcl-judgment-parse-request",
             "producer": "FCL",
-            "executionId": f"fcl_ex_id_{uuid.uuid4()}",
+            "executionId": str(uuid.uuid4()),
             "parentExecutionId": None,
         },
         "parameters": {

{ds_caselaw_marklogic_api_client-22.0.2 → ds_caselaw_marklogic_api_client-23.0.1}/src/caselawclient/responses/search_response.py

@@ -45,3 +45,20 @@ class SearchResponse:
             "//search:response/search:result", namespaces=self.NAMESPACES
         )
         return [SearchResult(result, self.client) for result in results]
+
+    @property
+    def facets(self) -> dict[str, str]:
+        """
+        Returns search facets from the SearchResponse as a dictionary
+
+        :return: A flattened dictionary of search facet values
+        """
+        # TODO: preserve the name of the facet (e.g. "court", "year")
+        results = self.node.xpath(
+            "//search:response/search:facet/search:facet-value",
+            namespaces={"search": "http://marklogic.com/appservices/search"},
+        )
+        facets_dictionary = {
+            result.attrib["name"]: result.attrib["count"] for result in results
+        }
+        return facets_dictionary

ds_caselaw_marklogic_api_client-23.0.1/src/caselawclient/xquery/validate_document.xqy

@@ -0,0 +1,7 @@
+xquery version "1.0-ml";
+
+declare variable $uri as xs:string external;
+
+let $judgment := fn:document($uri)
+
+return xdmp:validate($judgment)

{ds_caselaw_marklogic_api_client-22.0.2 → ds_caselaw_marklogic_api_client-23.0.1}/src/caselawclient/xquery_type_dicts.py

@@ -211,6 +211,11 @@ class UserHasRoleDict(MarkLogicAPIDict):
     user: str
 
 
+# validate_document.xqy
+class ValidateDocumentDict(MarkLogicAPIDict):
+    uri: MarkLogicDocumentURIString
+
+
 # xslt.xqy
 class XsltDict(MarkLogicAPIDict):
     uri: MarkLogicDocumentURIString