Merge pull request #340 from nationalarchives/best-human-identifier

Best human identifier

src/caselawclient/models/documents.py

@@ -111,6 +111,16 @@ def document_exists(self) -> bool:
         :return: `True` if the document exists, `False` otherwise."""
         return self.api_client.document_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.
+        """
+        return None
+
     @property
     def public_uri(self) -> str:
         """

src/caselawclient/models/judgments.py

@@ -28,3 +28,7 @@ def neutral_citation(self) -> str:
                 "akn": "http://docs.oasis-open.org/legaldocml/ns/akn/3.0",
             },
         )
+
+    @property
+    def best_human_identifier(self) -> str:
+        return self.neutral_citation

src/caselawclient/models/press_summaries.py

@@ -27,3 +27,7 @@ def neutral_citation(self) -> str:
                 "akn": "http://docs.oasis-open.org/legaldocml/ns/akn/3.0",
             },
         )
+
+    @property
+    def best_human_identifier(self) -> str:
+        return self.neutral_citation

tests/models/test_documents.py

@@ -142,6 +142,10 @@ def test_document_status(self, mock_api_client):
         published_document.is_published = True
         assert published_document.status == DOCUMENT_STATUS_PUBLISHED
 
+    def test_document_best_identifier(self, mock_api_client):
+        example_document = Document("uri", mock_api_client)
+        assert example_document.best_human_identifier is None
+
 
 class TestDocumentValidation:
     def test_judgment_is_failure(self, mock_api_client):

tests/models/test_judgments.py

@@ -11,6 +11,13 @@ def mock_api_client():
     return Mock(spec=MarklogicApiClient)
 
 
+class TestJudgment:
+    def test_best_identifier(self, mock_api_client):
+        judgment = Judgment("test/1234", mock_api_client)
+        judgment.neutral_citation = "[2023] TEST 1234"
+        assert judgment.best_human_identifier == judgment.neutral_citation
+
+
 class TestJudgmentValidation:
     def test_has_ncn(self, mock_api_client):
         document_with_ncn = Judgment("test/1234", mock_api_client)

tests/models/test_press_summaries.py

@@ -11,6 +11,13 @@ def mock_api_client():
     return Mock(spec=MarklogicApiClient)
 
 
+class TestPressSummary:
+    def test_best_identifier(self, mock_api_client):
+        summary = PressSummary("test/1234", mock_api_client)
+        summary.neutral_citation = "[2023] TEST 1234"
+        assert summary.best_human_identifier == summary.neutral_citation
+
+
 class TestPressSummaryValidation:
     def test_has_ncn(self, mock_api_client):
         document_with_ncn = PressSummary("test/1234", mock_api_client)