ds-caselaw-marklogic-api-client 28.2.0__py3-none-any.whl → 29.0.0__py3-none-any.whl

caselawclient/models/documents/__init__.py

@@ -15,6 +15,7 @@ from caselawclient.errors import (
     NotSupportedOnVersion,
     OnlySupportedOnVersion,
 )
+from caselawclient.models.identifiers import Identifier
 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
@@ -171,13 +172,11 @@ class Document:
         self.identifiers = unpack_all_identifiers_from_etree(identifiers_element_as_etree)
 
     @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 be overridden in subclasses.
-        """
+    def best_human_identifier(self) -> Optional[Identifier]:
+        """Return the preferred identifier for the document, providing that it is considered human readable."""
+        preferred_identifier = self.identifiers.preferred()
+        if preferred_identifier and preferred_identifier.schema.human_readable:
+            return preferred_identifier
         return None
 
     @property
@@ -507,13 +506,17 @@ class Document:
             "documentType": parser_type_noun,
             "metadata": {
                 "name": self.body.name or None,
-                "cite": self.best_human_identifier or None,
+                "cite": None,
                 "court": self.body.court or None,
                 "date": checked_date,
                 "uri": self.uri,
             },
         }
 
+        ## TODO: Remove this hack around the fact that NCNs are assumed to be present for all documents' metadata, but actually different document classes may have different metadata
+        if hasattr(self, "neutral_citation"):
+            parser_instructions["metadata"]["cite"] = self.neutral_citation
+
         request_parse(
             uri=self.uri,
             reference=self.consignment_reference,

caselawclient/models/identifiers/__init__.py

@@ -32,13 +32,20 @@ class IdentifierSchema(ABC):
     name: str
     namespace: str
 
+    human_readable: bool
+    """ Should this identifier type be considered for display as a 'human readable' identifier? """
+
+    base_score_multiplier: float = 1.0
+    """ A multiplier used to adjust the relative ranking of this identifier when calculating preferred identifiers. """
+
     def __init_subclass__(cls: type["IdentifierSchema"], **kwargs: Any) -> None:
         """Ensure that subclasses have the required attributes set."""
         for required in (
             "name",
             "namespace",
+            "human_readable",
         ):
-            if not getattr(cls, required, False):
+            if not hasattr(cls, required):
                 raise NotImplementedError(f"Can't instantiate IdentifierSchema without {required} attribute.")
         super().__init_subclass__(**kwargs)
 
@@ -101,6 +108,11 @@ class Identifier(ABC):
     def url_slug(self) -> str:
         return self.schema.compile_identifier_url_slug(self.value)
 
+    @property
+    def score(self) -> float:
+        """Return the score of this identifier, used to calculate the preferred identifier for a document."""
+        return 1 * self.schema.base_score_multiplier
+
     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
@@ -149,3 +161,22 @@ class Identifiers(dict[str, Identifier]):
             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) == 0:
+            return None
+        return self.by_score(type)[0]

caselawclient/models/identifiers/fclid.py

@@ -27,6 +27,8 @@ class FindCaseLawIdentifierSchema(IdentifierSchema):
 
     name = "Find Case Law Identifier"
     namespace = "fclid"
+    human_readable = False
+    base_score_multiplier = 0.8
 
     @classmethod
     def validate_identifier(cls, value: str) -> bool:

caselawclient/models/identifiers/neutral_citation.py

@@ -30,6 +30,8 @@ class NeutralCitationNumberSchema(IdentifierSchema):
 
     name = "Neutral Citation Number"
     namespace = "ukncn"
+    human_readable = True
+    base_score_multiplier = 1.5
 
     @classmethod
     def validate_identifier(cls, value: str) -> bool:

caselawclient/models/judgments.py

@@ -25,20 +25,17 @@ class Judgment(NeutralCitationMixin, Document):
         super().__init__(self.document_noun, uri, *args, **kwargs)
 
     @cached_property
-    def neutral_citation(self) -> NeutralCitationString:
-        return NeutralCitationString(
-            self.body.get_xpath_match_string(
-                "/akn:akomaNtoso/akn:*/akn:meta/akn:proprietary/uk:cite/text()",
-                {
-                    "uk": "https://caselaw.nationalarchives.gov.uk/akn",
-                    "akn": "http://docs.oasis-open.org/legaldocml/ns/akn/3.0",
-                },
-            )
+    def neutral_citation(self) -> Optional[NeutralCitationString]:
+        value_in_xml = self.body.get_xpath_match_string(
+            "/akn:akomaNtoso/akn:*/akn:meta/akn:proprietary/uk:cite/text()",
+            {
+                "uk": "https://caselaw.nationalarchives.gov.uk/akn",
+                "akn": "http://docs.oasis-open.org/legaldocml/ns/akn/3.0",
+            },
         )
-
-    @property
-    def best_human_identifier(self) -> str:
-        return self.neutral_citation
+        if value_in_xml:
+            return NeutralCitationString(value_in_xml)
+        return None
 
     @cached_property
     def linked_document(self) -> Optional["PressSummary"]:

caselawclient/models/neutral_citation_mixin.py

@@ -1,9 +1,10 @@
 from abc import ABC, abstractmethod
 from functools import cached_property
-from typing import Any
+from typing import Any, Optional
 
 from ds_caselaw_utils import neutral_url
 from ds_caselaw_utils.types import NeutralCitationString
+from typing_extensions import deprecated
 
 
 class NeutralCitationMixin(ABC):
@@ -38,12 +39,15 @@ class NeutralCitationMixin(ABC):
 
     @cached_property
     @abstractmethod
-    def neutral_citation(self) -> NeutralCitationString: ...
+    @deprecated("Legacy usage of NCNs is deprecated; you should be moving to the Identifiers framework")
+    def neutral_citation(self) -> Optional[NeutralCitationString]: ...
 
     @cached_property
+    @deprecated("Legacy usage of NCNs is deprecated; you should be moving to the Identifiers framework")
     def has_ncn(self) -> bool:
-        return bool(self.neutral_citation)
+        return self.neutral_citation is not None and self.neutral_citation != ""
 
     @cached_property
+    @deprecated("Legacy usage of NCNs is deprecated; you should be moving to the Identifiers framework")
     def has_valid_ncn(self) -> bool:
-        return self.has_ncn and neutral_url(self.neutral_citation) is not None
+        return self.neutral_citation is not None and neutral_url(self.neutral_citation) is not None

caselawclient/models/press_summaries.py

@@ -27,19 +27,16 @@ class PressSummary(NeutralCitationMixin, Document):
         super().__init__(self.document_noun, uri, *args, **kwargs)
 
     @cached_property
-    def neutral_citation(self) -> NeutralCitationString:
-        return NeutralCitationString(
-            self.body.get_xpath_match_string(
-                "/akn:akomaNtoso/akn:doc/akn:preface/akn:p/akn:neutralCitation/text()",
-                {
-                    "akn": "http://docs.oasis-open.org/legaldocml/ns/akn/3.0",
-                },
-            )
+    def neutral_citation(self) -> Optional[NeutralCitationString]:
+        value_in_xml = self.body.get_xpath_match_string(
+            "/akn:akomaNtoso/akn:doc/akn:preface/akn:p/akn:neutralCitation/text()",
+            {
+                "akn": "http://docs.oasis-open.org/legaldocml/ns/akn/3.0",
+            },
         )
-
-    @property
-    def best_human_identifier(self) -> str:
-        return self.neutral_citation
+        if value_in_xml:
+            return NeutralCitationString(value_in_xml)
+        return None
 
     @cached_property
     def linked_document(self) -> Optional[Judgment]:

{ds_caselaw_marklogic_api_client-28.2.0.dist-info → ds_caselaw_marklogic_api_client-29.0.0.dist-info}/METADATA

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

{ds_caselaw_marklogic_api_client-28.2.0.dist-info → ds_caselaw_marklogic_api_client-29.0.0.dist-info}/RECORD

@@ -7,19 +7,19 @@ caselawclient/errors.py,sha256=tV0vs3wYSd331BzmfuRiZV6GAdsd91rtN65ymRaSx3s,3164
 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=DS2jqj4ShRHxAWIqQeeyCCcXctLor4xUvT3sc903D2E,19186
+caselawclient/models/documents/__init__.py,sha256=Lzb18MyCPLlG0Y4EdnjZvnGFSSpsNs_BUgJA6BQqL28,19520
 caselawclient/models/documents/body.py,sha256=mtdjmG1WU2qSpyRLS8-PWcSoXpDa2Qz6xlcTbxZgxvA,5603
 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=HlmPb63lLMnySSOLP4iexcAyQiLByKBZtTd25f8sY8M,1268
-caselawclient/models/identifiers/__init__.py,sha256=CxKu5iZqPb6BOjrQ3upkzyjU3YSsJhBZd7VATYxDI-A,5061
-caselawclient/models/identifiers/fclid.py,sha256=pAxZKKlKRSHwJqrEHOSlbuCt3gBOgS3sNv98bBjuNBc,1295
-caselawclient/models/identifiers/neutral_citation.py,sha256=yddlfumdnkrNpoTIOf8dB1foA7hE41-zmlfa17-Ulug,1790
+caselawclient/models/identifiers/__init__.py,sha256=4D_ssfNK7gj7Z4XMHqCzn-EwsPM4a6IofYkU1JjnRF4,6449
+caselawclient/models/identifiers/fclid.py,sha256=pTO586ra0sr4DbjHSxuI8UlxfNXLm9nDNVoDUIxiUrE,1354
+caselawclient/models/identifiers/neutral_citation.py,sha256=3Jw1_-NmGfGmrWGFSzLdTHBYHIHq4tPkF8U7Jba-jGo,1848
 caselawclient/models/identifiers/unpacker.py,sha256=01gWWlOd_2PxT1GJzOIXbp0G4iGGIxHaTaJMBOQ1TDs,1834
-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=06flQ8wSLnNxoQtXO0ckmotFKszYZcub0oPcDzYbVQw,1879
+caselawclient/models/judgments.py,sha256=xFjfOspa9ZL29gvvGVNq11JC7h-LKebFMrQYvVIIoEI,1868
+caselawclient/models/neutral_citation_mixin.py,sha256=LDaxNndLcTKsjJCyEKO1kGTJ6YD6h-6SzQVE0-gwPSI,2208
+caselawclient/models/press_summaries.py,sha256=bEqJxu-7eBLhwulOsDXYDl2ptIp3RkkMpOcdVvWB5ds,1836
 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
@@ -77,7 +77,7 @@ caselawclient/xquery/validate_document.xqy,sha256=PgaDcnqCRJPIVqfmWsNlXmCLNKd21q
 caselawclient/xquery/xslt.xqy,sha256=w57wNijH3dkwHkpKeAxqjlghVflQwo8cq6jS_sm-erM,199
 caselawclient/xquery/xslt_transform.xqy,sha256=smyFFxqmtkuOzBd2l7uw6K2oAsYctudrP8omdv_XNAM,2463
 caselawclient/xquery_type_dicts.py,sha256=kybL-YzwK34Fr6MeWfqVOJHYrs0ZNeDWXDsp8o2Yb1U,6114
-ds_caselaw_marklogic_api_client-28.2.0.dist-info/LICENSE.md,sha256=fGMzyyLuQW-IAXUeDSCrRdsYW536aEWThdbpCjo6ZKg,1108
-ds_caselaw_marklogic_api_client-28.2.0.dist-info/METADATA,sha256=i7v85V8SC6lm8oYboo4aGxSmVVaO4QZwj3WVSWDU5Cs,4272
-ds_caselaw_marklogic_api_client-28.2.0.dist-info/WHEEL,sha256=7Z8_27uaHI_UZAc4Uox4PpBhQ9Y5_modZXWMxtUi4NU,88
-ds_caselaw_marklogic_api_client-28.2.0.dist-info/RECORD,,
+ds_caselaw_marklogic_api_client-29.0.0.dist-info/LICENSE.md,sha256=fGMzyyLuQW-IAXUeDSCrRdsYW536aEWThdbpCjo6ZKg,1108
+ds_caselaw_marklogic_api_client-29.0.0.dist-info/METADATA,sha256=x0GZ0GgA91sa_O9Eq2aal3FONl6Vs2lknsPdrPUmlzE,4272
+ds_caselaw_marklogic_api_client-29.0.0.dist-info/WHEEL,sha256=7Z8_27uaHI_UZAc4Uox4PpBhQ9Y5_modZXWMxtUi4NU,88
+ds_caselaw_marklogic_api_client-29.0.0.dist-info/RECORD,,