feat(FCL-533): getting scored or preferred identifiers can now be don…

…e by type

src/caselawclient/models/documents/__init__.py

@@ -174,7 +174,7 @@ def _initialise_identifiers(self) -> None:
     @property
     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
+        preferred_identifier = self.identifiers.preferred()
         if preferred_identifier and preferred_identifier.schema.human_readable:
             return preferred_identifier
         return None

src/caselawclient/models/identifiers/__init__.py

@@ -162,14 +162,21 @@ def as_etree(self) -> etree._Element:
 
         return identifiers_root
 
-    @property
-    def by_score(self) -> list[Identifier]:
-        """Return a list of identifiers, sorted by their score in descending order."""
-        return sorted(self.values(), key=lambda v: v.score, reverse=True)
+    def by_score(self, type: Optional[type[Identifier]] = None) -> list[Identifier]:
+        """
+        :param type: Optionally, an identifier type to constrain this list to.
 
-    @property
-    def preferred(self) -> Optional[Identifier]:
-        """If this document has identifiers, return the preferred one."""
+        :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[0]
+        return self.by_score(type)[0]

tests/models/identifiers/test_identifiers.py

@@ -131,7 +131,13 @@ def test_base_scoring(self):
         assert identifier.score == 2.5
 
     def test_sorting(self, mixed_identifiers):
-        assert mixed_identifiers.by_score == [TEST_IDENTIFIER_999, TEST_NCN_1701, TEST_NCN_1234]
+        assert mixed_identifiers.by_score() == [TEST_IDENTIFIER_999, TEST_NCN_1701, TEST_NCN_1234]
 
     def test_preferred_identifier(self, mixed_identifiers):
-        assert mixed_identifiers.preferred == TEST_IDENTIFIER_999
+        assert mixed_identifiers.preferred() == TEST_IDENTIFIER_999
+
+    def test_sorting_with_type(self, mixed_identifiers):
+        assert mixed_identifiers.by_score(type=NeutralCitationNumber) == [TEST_NCN_1701, TEST_NCN_1234]
+
+    def test_preferred_identifier_with_type(self, mixed_identifiers):
+        assert mixed_identifiers.preferred(type=NeutralCitationNumber) == TEST_NCN_1701