Implement named references (#118)

This PR adds an extension of the `Reference` classes that has a name.

src/curies/__init__.py

@@ -5,6 +5,7 @@
     DuplicatePrefixes,
     DuplicateURIPrefixes,
     DuplicateValueError,
+    NamedReference,
     Record,
     Records,
     Reference,
@@ -37,6 +38,7 @@
     "Records",
     "ReferenceTuple",
     "Reference",
+    "NamedReference",
     "DuplicateValueError",
     "DuplicateURIPrefixes",
     "DuplicatePrefixes",

src/curies/api.py

@@ -34,6 +34,7 @@
     "Converter",
     "Reference",
     "ReferenceTuple",
+    "NamedReference",
     "Record",
     "Records",
     "DuplicateValueError",
@@ -208,6 +209,16 @@ def __lt__(self, other: "Reference") -> bool:
         """Sort the reference lexically first by prefix, then by identifier."""
         return self.pair < other.pair
 
+    def __hash__(self) -> int:
+        return hash((self.prefix, self.identifier))
+
+    def __eq__(self, other: Any) -> bool:
+        return (
+            isinstance(other, Reference)
+            and self.prefix == other.prefix
+            and self.identifier == other.identifier
+        )
+
     @property
     def curie(self) -> str:
         """Get the reference as a CURIE string.
@@ -240,6 +251,31 @@ def from_curie(cls, curie: str, *, sep: str = ":") -> "Reference":
         return cls(prefix=prefix, identifier=identifier)
 
 
+class NamedReference(Reference):
+    """A reference with a name."""
+
+    name: str = Field(
+        ..., description="The name of the entity referenced by this object's prefix and identifier."
+    )
+
+    model_config = ConfigDict(frozen=True)
+
+    @classmethod
+    def from_curie(cls, curie: str, name: str, *, sep: str = ":") -> "NamedReference":  # type:ignore
+        """Parse a CURIE string and populate a reference.
+
+        :param curie: A string representation of a compact URI (CURIE)
+        :param name: The name of the reference
+        :param sep: The separator
+        :return: A reference object
+
+        >>> NamedReference.from_curie("chebi:1234", "6-methoxy-2-octaprenyl-1,4-benzoquinone")
+        NamedReference(prefix='chebi', identifier='1234', name='6-methoxy-2-octaprenyl-1,4-benzoquinone')
+        """
+        prefix, identifier = _split(curie, sep=sep)
+        return cls(prefix=prefix, identifier=identifier, name=name)
+
+
 RecordKey = tuple[str, str, str, str]
 
 

tests/test_api.py

@@ -17,6 +17,7 @@
     DuplicatePrefixes,
     DuplicateURIPrefixes,
     ExpansionError,
+    NamedReference,
     NoCURIEDelimiterError,
     PrefixStandardizationError,
     Record,
@@ -100,6 +101,24 @@ def test_set_membership(self):
         self.assertNotIn(Reference.from_curie(":1234"), collection)
         self.assertNotIn(Reference.from_curie("abc:"), collection)
 
+    def test_named_set_membership(self):
+        """Test membership in sets of named references."""
+        references = {
+            NamedReference.from_curie("a:1", "name1"),
+            NamedReference.from_curie("a:2", "name2"),
+        }
+        self.assertIn(Reference.from_curie("a:1"), references)
+        self.assertIn(NamedReference.from_curie("a:1", "name1"), references)
+        # the following is a weird case, but shows how this works
+        self.assertIn(NamedReference.from_curie("a:1", "name2"), references)
+
+        references_2 = {
+            Reference.from_curie("a:1"),
+            Reference.from_curie("a:2"),
+        }
+        self.assertIn(Reference.from_curie("a:1"), references_2)
+        self.assertIn(NamedReference.from_curie("a:1", "name1"), references_2)
+
 
 class TestAddRecord(unittest.TestCase):
     """Test adding records."""