Add get_primary_reference (#439)

Add `pyobo.get_primary_reference()` function to complement
`pyobo.get_primary_curie()`

Author: cthoyt

src/pyobo/__init__.py

@@ -37,6 +37,7 @@
     get_obsolete,
     get_primary_curie,
     get_primary_identifier,
+    get_primary_reference,
     get_properties,
     get_properties_df,
     get_property,
@@ -139,6 +140,7 @@
     "get_ontology",
     "get_primary_curie",
     "get_primary_identifier",
+    "get_primary_reference",
     "get_properties",
     "get_properties_df",
     "get_property",

src/pyobo/api/__init__.py

@@ -5,6 +5,7 @@
     get_id_to_alts,
     get_primary_curie,
     get_primary_identifier,
+    get_primary_reference,
 )
 from .combine import get_literal_mappings_subset
 from .edges import get_edges, get_edges_df, get_graph
@@ -105,6 +106,7 @@
     "get_ontology",
     "get_primary_curie",
     "get_primary_identifier",
+    "get_primary_reference",
     "get_priority_curie",
     "get_properties",
     "get_properties_df",

src/pyobo/api/alts.py

@@ -20,6 +20,7 @@
     "get_id_to_alts",
     "get_primary_curie",
     "get_primary_identifier",
+    "get_primary_reference",
 ]
 
 logger = logging.getLogger(__name__)
@@ -61,13 +62,13 @@ def get_alts_to_id(prefix: str, **kwargs: Unpack[GetOntologyKwargs]) -> Mapping[
     }
 
 
-def get_primary_curie(
+def get_primary_reference(
     prefix: str | curies.Reference | curies.ReferenceTuple,
     identifier: str | None = None,
     /,
     **kwargs: Unpack[GetOntologyKwargs],
-) -> str | None:
-    """Get the primary curie for an entity."""
+) -> curies.ReferenceTuple | None:
+    """Get the primary reference for an entity."""
     reference = _get_pi(prefix, identifier)
     try:
         primary_identifier = get_primary_identifier(reference, **kwargs)
@@ -76,7 +77,20 @@ def get_primary_curie(
             raise
         # this happens on invalid prefix. maybe revise?
         return None
-    return f"{reference.prefix}:{primary_identifier}"
+    return curies.ReferenceTuple(reference.prefix, primary_identifier)
+
+
+def get_primary_curie(
+    prefix: str | curies.Reference | curies.ReferenceTuple,
+    identifier: str | None = None,
+    /,
+    **kwargs: Unpack[GetOntologyKwargs],
+) -> str | None:
+    """Get the primary curie for an entity."""
+    reference = get_primary_reference(prefix, identifier, **kwargs)
+    if reference is None:
+        return None
+    return reference.curie
 
 
 def get_primary_identifier(

tests/test_api.py

@@ -19,6 +19,7 @@
     get_name_by_curie,
     get_primary_curie,
     get_primary_identifier,
+    get_primary_reference,
 )
 from pyobo.mocks import get_mock_id_alts_mapping, get_mock_id_name_mapping
 from pyobo.ner import get_grounder
@@ -102,6 +103,11 @@ def test_get_primary_by_curie(self, _, __):
         primary_curie = get_primary_curie("go:0001071")
         self.assertIsNotNone(primary_curie)
         self.assertEqual("go:0003700", primary_curie)
+
+        primary_reference = get_primary_reference("go:0001071")
+        self.assertIsNotNone(primary_reference)
+        self.assertEqual(ReferenceTuple("go", "0003700"), primary_reference)
+
         self.assertIsNone(get_name_by_curie("go:0001071", upgrade_identifier=False))
 
         # if set explicitly to true, then it will do it eagerly