pyobo 0.10.11__py3-none-any.whl → 0.11.0__py3-none-any.whl

pyobo/__init__.py

@@ -1,5 +1,3 @@
-# -*- coding: utf-8 -*-
-
 """A python package for handling and generating OBO."""
 
 from .api import (  # noqa: F401

pyobo/__main__.py

@@ -1,5 +1,3 @@
-# -*- coding: utf-8 -*-
-
 """CLI for PyOBO."""
 
 from .cli import main

pyobo/api/__init__.py

@@ -1,5 +1,3 @@
-# -*- coding: utf-8 -*-
-
 """High-level API for accessing content."""
 
 from .alts import (  # noqa: F401

pyobo/api/alts.py

@@ -1,10 +1,9 @@
-# -*- coding: utf-8 -*-
-
 """High-level API for alternative identifiers."""
 
 import logging
+from collections.abc import Mapping
 from functools import lru_cache
-from typing import List, Mapping, Optional
+from typing import Optional
 
 from .utils import get_version
 from ..getters import get_ontology
@@ -26,11 +25,11 @@ NO_ALTS = {
 }
 
 
-@lru_cache()
+@lru_cache
 @wrap_norm_prefix
 def get_id_to_alts(
     prefix: str, *, force: bool = False, version: Optional[str] = None
-) -> Mapping[str, List[str]]:
+) -> Mapping[str, list[str]]:
     """Get alternate identifiers."""
     if prefix in NO_ALTS:
         return {}
@@ -41,7 +40,7 @@ def get_id_to_alts(
     header = [f"{prefix}_id", "alt_id"]
 
     @cached_multidict(path=path, header=header, force=force)
-    def _get_mapping() -> Mapping[str, List[str]]:
+    def _get_mapping() -> Mapping[str, list[str]]:
         if force:
             logger.info(f"[{prefix}] forcing reload for alts")
         else:
@@ -52,7 +51,7 @@ def get_id_to_alts(
     return _get_mapping()
 
 
-@lru_cache()
+@lru_cache
 @wrap_norm_prefix
 def get_alts_to_id(
     prefix: str, *, force: bool = False, version: Optional[str] = None

pyobo/api/hierarchy.py

@@ -1,10 +1,9 @@
-# -*- coding: utf-8 -*-
-
 """High-level API for hierarchies."""
 
 import logging
+from collections.abc import Iterable
 from functools import lru_cache
-from typing import Iterable, Optional, Set, Tuple
+from typing import Optional
 
 import networkx as nx
 
@@ -70,13 +69,13 @@ def get_hierarchy(
     )
 
 
-@lru_cache()
+@lru_cache
 @wrap_norm_prefix
 def _get_hierarchy_helper(
     prefix: str,
     *,
-    extra_relations: Tuple[TypeDef, ...],
-    properties: Tuple[str, ...],
+    extra_relations: tuple[TypeDef, ...],
+    properties: tuple[str, ...],
     include_part_of: bool,
     include_has_member: bool,
     use_tqdm: bool,
@@ -161,13 +160,13 @@ def is_descendent(
 
     Check that go:0070246 ! natural killer cell apoptotic process is a
     descendant of go:0006915 ! apoptotic process::
-    >>> assert is_descendent('go', '0070246', 'go', '0006915')
+    >>> assert is_descendent("go", "0070246", "go", "0006915")
     """
     descendants = get_descendants(ancestor_prefix, ancestor_identifier, version=version)
     return descendants is not None and f"{prefix}:{identifier}" in descendants
 
 
-@lru_cache()
+@lru_cache
 def get_descendants(
     prefix: str,
     identifier: Optional[str] = None,
@@ -176,7 +175,7 @@ def get_descendants(
     use_tqdm: bool = False,
     force: bool = False,
     **kwargs,
-) -> Optional[Set[str]]:
+) -> Optional[set[str]]:
     """Get all the descendants (children) of the term as CURIEs."""
     curie, prefix, identifier = _pic(prefix, identifier)
     hierarchy = get_hierarchy(
@@ -192,7 +191,7 @@ def get_descendants(
     return nx.ancestors(hierarchy, curie)  # note this is backwards
 
 
-def _pic(prefix, identifier=None) -> Tuple[str, str, str]:
+def _pic(prefix, identifier=None) -> tuple[str, str, str]:
     if identifier is None:
         curie = prefix
         prefix, identifier = prefix.split(":")
@@ -201,7 +200,7 @@ def _pic(prefix, identifier=None) -> Tuple[str, str, str]:
     return curie, prefix, identifier
 
 
-@lru_cache()
+@lru_cache
 def get_children(
     prefix: str,
     identifier: Optional[str] = None,
@@ -210,7 +209,7 @@ def get_children(
     use_tqdm: bool = False,
     force: bool = False,
     **kwargs,
-) -> Optional[Set[str]]:
+) -> Optional[set[str]]:
     """Get all the descendants (children) of the term as CURIEs."""
     curie, prefix, identifier = _pic(prefix, identifier)
     hierarchy = get_hierarchy(
@@ -232,13 +231,13 @@ def has_ancestor(
     """Check that the first identifier has the second as an ancestor.
 
     Check that go:0008219 ! cell death is an ancestor of go:0006915 ! apoptotic process::
-    >>> assert has_ancestor('go', '0006915', 'go', '0008219')
+    >>> assert has_ancestor("go", "0006915", "go", "0008219")
     """
     ancestors = get_ancestors(prefix, identifier, version=version)
     return ancestors is not None and f"{ancestor_prefix}:{ancestor_identifier}" in ancestors
 
 
-@lru_cache()
+@lru_cache
 def get_ancestors(
     prefix: str,
     identifier: Optional[str] = None,
@@ -247,7 +246,7 @@ def get_ancestors(
     use_tqdm: bool = False,
     force: bool = False,
     **kwargs,
-) -> Optional[Set[str]]:
+) -> Optional[set[str]]:
     """Get all the ancestors (parents) of the term as CURIEs."""
     curie, prefix, identifier = _pic(prefix, identifier)
     hierarchy = get_hierarchy(

pyobo/api/metadata.py

@@ -1,10 +1,9 @@
-# -*- coding: utf-8 -*-
-
 """High-level API for metadata."""
 
 import logging
+from collections.abc import Mapping
 from functools import lru_cache
-from typing import Mapping, Optional
+from typing import Optional
 
 from .utils import get_version
 from ..getters import get_ontology
@@ -19,7 +18,7 @@ __all__ = [
 logger = logging.getLogger(__name__)
 
 
-@lru_cache()
+@lru_cache
 @wrap_norm_prefix
 def get_metadata(
     prefix: str, *, force: bool = False, version: Optional[str] = None

pyobo/api/names.py

@@ -1,15 +1,18 @@
-# -*- coding: utf-8 -*-
-
 """High-level API for nomenclature."""
 
+from __future__ import annotations
+
 import logging
 import subprocess
+from collections.abc import Mapping
 from functools import lru_cache
-from typing import Callable, List, Mapping, Optional, Set, TypeVar
+from typing import Callable, TypeVar
+
+from curies import Reference, ReferenceTuple
 
 from .alts import get_primary_identifier
 from .utils import get_version
-from ..getters import NoBuild, get_ontology
+from ..getters import NoBuildError, get_ontology
 from ..identifier_utils import normalize_curie, wrap_norm_prefix
 from ..utils.cache import cached_collection, cached_mapping, cached_multidict
 from ..utils.path import prefix_cache_join
@@ -30,8 +33,10 @@ __all__ = [
 logger = logging.getLogger(__name__)
 
 
-def get_name_by_curie(curie: str, *, version: Optional[str] = None) -> Optional[str]:
+def get_name_by_curie(curie: str, *, version: str | None = None) -> str | None:
     """Get the name for a CURIE, if possible."""
+    if version is None:
+        version = get_version(curie.split(":")[0])
     prefix, identifier = normalize_curie(curie)
     if prefix and identifier:
         return get_name(prefix, identifier, version=version)
@@ -40,7 +45,8 @@ def get_name_by_curie(curie: str, *, version: Optional[str] = None) -> Optional[
 
 X = TypeVar("X")
 
-NO_BUILD_PREFIXES = set()
+NO_BUILD_PREFIXES: set[str] = set()
+NO_BUILD_LOGGED: set = set()
 
 
 def _help_get(
@@ -49,18 +55,20 @@ def _help_get(
     identifier: str,
     force: bool = False,
     strict: bool = False,
-    version: Optional[str] = None,
-) -> Optional[X]:
+    version: str | None = None,
+) -> X | None:
     """Get the result for an entity based on a mapping maker function ``f``."""
     try:
         mapping = f(prefix, force=force, strict=strict, version=version)  # type:ignore
-    except NoBuild:
+    except NoBuildError:
         if prefix not in NO_BUILD_PREFIXES:
             logger.warning("[%s] unable to look up results with %s", prefix, f)
             NO_BUILD_PREFIXES.add(prefix)
         return None
-    except ValueError:
-        logger.warning("[%s] unable to look up results with %s", prefix, f)
+    except ValueError as e:
+        if prefix not in NO_BUILD_PREFIXES:
+            logger.warning("[%s] value error while looking up results with %s: %s", prefix, f, e)
+            NO_BUILD_PREFIXES.add(prefix)
         return None
 
     if not mapping:
@@ -74,16 +82,24 @@ def _help_get(
 
 
 @wrap_norm_prefix
-def get_name(prefix: str, identifier: str, *, version: Optional[str] = None) -> Optional[str]:
+def get_name(
+    prefix: str | Reference | ReferenceTuple,
+    identifier: str | None = None,
+    /,
+    *,
+    version: str | None = None,
+) -> str | None:
     """Get the name for an entity."""
-    return _help_get(get_id_name_mapping, prefix, identifier, version=version)
+    if isinstance(prefix, (ReferenceTuple, Reference)):
+        prefix, identifier = prefix.prefix, prefix.identifier
+    return _help_get(get_id_name_mapping, prefix, identifier, version=version)  # type:ignore
 
 
-@lru_cache()
+@lru_cache
 @wrap_norm_prefix
 def get_ids(
-    prefix: str, *, force: bool = False, strict: bool = False, version: Optional[str] = None
-) -> Set[str]:
+    prefix: str, *, force: bool = False, strict: bool = False, version: str | None = None
+) -> set[str]:
     """Get the set of identifiers for this prefix."""
     if prefix == "ncbigene":
         from ..sources.ncbigene import get_ncbigene_ids
@@ -98,7 +114,7 @@ def get_ids(
     path = prefix_cache_join(prefix, name="ids.tsv", version=version)
 
     @cached_collection(path=path, force=force)
-    def _get_ids() -> Set[str]:
+    def _get_ids() -> set[str]:
         if force:
             logger.info("[%s v%s] forcing reload for names", prefix, version)
         else:
@@ -111,10 +127,10 @@ def get_ids(
     return set(_get_ids())
 
 
-@lru_cache()
+@lru_cache
 @wrap_norm_prefix
 def get_id_name_mapping(
-    prefix: str, *, force: bool = False, strict: bool = False, version: Optional[str] = None
+    prefix: str, *, force: bool = False, strict: bool = False, version: str | None = None
 ) -> Mapping[str, str]:
     """Get an identifier to name mapping for the OBO file."""
     if prefix == "ncbigene":
@@ -140,7 +156,7 @@ def get_id_name_mapping(
 
     try:
         return _get_id_name_mapping()
-    except NoBuild:
+    except NoBuildError:
         logger.debug("[%s] no build", prefix)
         return {}
     except (Exception, subprocess.CalledProcessError) as e:
@@ -148,10 +164,10 @@ def get_id_name_mapping(
         return {}
 
 
-@lru_cache()
+@lru_cache
 @wrap_norm_prefix
 def get_name_id_mapping(
-    prefix: str, *, force: bool = False, version: Optional[str] = None
+    prefix: str, *, force: bool = False, version: str | None = None
 ) -> Mapping[str, str]:
     """Get a name to identifier mapping for the OBO file."""
     id_name = get_id_name_mapping(prefix=prefix, force=force, version=version)
@@ -159,8 +175,12 @@ def get_name_id_mapping(
 
 
 @wrap_norm_prefix
-def get_definition(prefix: str, identifier: str, *, version: Optional[str] = None) -> Optional[str]:
+def get_definition(
+    prefix: str, identifier: str | None = None, *, version: str | None = None
+) -> str | None:
     """Get the definition for an entity."""
+    if identifier is None:
+        prefix, _, identifier = prefix.rpartition(":")
     return _help_get(get_id_definition_mapping, prefix, identifier, version=version)
 
 
@@ -169,7 +189,7 @@ def get_id_definition_mapping(
     *,
     force: bool = False,
     strict: bool = False,
-    version: Optional[str] = None,
+    version: str | None = None,
 ) -> Mapping[str, str]:
     """Get a mapping of descriptions."""
     if version is None:
@@ -192,15 +212,15 @@ def get_obsolete(
     *,
     force: bool = False,
     strict: bool = False,
-    version: Optional[str] = None,
-) -> Set[str]:
+    version: str | None = None,
+) -> set[str]:
     """Get the set of obsolete local unique identifiers."""
     if version is None:
         version = get_version(prefix)
     path = prefix_cache_join(prefix, name="obsolete.tsv", version=version)
 
     @cached_collection(path=path, force=force)
-    def _get_obsolete() -> Set[str]:
+    def _get_obsolete() -> set[str]:
         ontology = get_ontology(prefix, force=force, strict=strict, version=version)
         return ontology.get_obsolete()
 
@@ -208,7 +228,7 @@ def get_obsolete(
 
 
 @wrap_norm_prefix
-def get_synonyms(prefix: str, identifier: str) -> Optional[List[str]]:
+def get_synonyms(prefix: str, identifier: str) -> list[str] | None:
     """Get the synonyms for an entity."""
     return _help_get(get_id_synonyms_mapping, prefix, identifier)
 
@@ -219,15 +239,15 @@ def get_id_synonyms_mapping(
     *,
     force: bool = False,
     strict: bool = False,
-    version: Optional[str] = None,
-) -> Mapping[str, List[str]]:
+    version: str | None = None,
+) -> Mapping[str, list[str]]:
     """Get the OBO file and output a synonym dictionary."""
     if version is None:
         version = get_version(prefix)
     path = prefix_cache_join(prefix, name="synonyms.tsv", version=version)
 
     @cached_multidict(path=path, header=[f"{prefix}_id", "synonym"], force=force)
-    def _get_multidict() -> Mapping[str, List[str]]:
+    def _get_multidict() -> Mapping[str, list[str]]:
         logger.info("[%s v%s] no cached synonyms found. getting from OBO loader", prefix, version)
         ontology = get_ontology(prefix, force=force, strict=strict, version=version)
         return ontology.get_id_synonyms_mapping()

pyobo/api/properties.py

@@ -1,10 +1,9 @@
-# -*- coding: utf-8 -*-
-
 """High-level API for properties."""
 
 import logging
 import os
-from typing import List, Mapping, Optional
+from collections.abc import Mapping
+from typing import Optional
 
 import pandas as pd
 
@@ -105,7 +104,7 @@ def get_filtered_properties_multimapping(
     use_tqdm: bool = False,
     force: bool = False,
     version: Optional[str] = None,
-) -> Mapping[str, List[str]]:
+) -> Mapping[str, list[str]]:
     """Extract multiple properties for each term as a dictionary.
 
     :param prefix: the resource to load
@@ -120,7 +119,7 @@ def get_filtered_properties_multimapping(
     all_properties_path = prefix_cache_join(prefix, name="properties.tsv", version=version)
 
     @cached_multidict(path=path, header=[f"{prefix}_id", prop], force=force)
-    def _mapping_getter() -> Mapping[str, List[str]]:
+    def _mapping_getter() -> Mapping[str, list[str]]:
         if os.path.exists(all_properties_path):
             logger.info("[%s] loading pre-cached properties", prefix)
             df = pd.read_csv(all_properties_path, sep="\t")
@@ -144,7 +143,7 @@ def get_property(prefix: str, identifier: str, prop: str, **kwargs) -> Optional[
     :returns: The single value for the property. If multiple are expected, use :func:`get_properties`
 
     >>> import pyobo
-    >>> pyobo.get_property('chebi', '132964', 'http://purl.obolibrary.org/obo/chebi/smiles')
+    >>> pyobo.get_property("chebi", "132964", "http://purl.obolibrary.org/obo/chebi/smiles")
     "C1(=CC=C(N=C1)OC2=CC=C(C=C2)O[C@@H](C(OCCCC)=O)C)C(F)(F)F"
     """
     filtered_properties_mapping = get_filtered_properties_mapping(
@@ -153,7 +152,7 @@ def get_property(prefix: str, identifier: str, prop: str, **kwargs) -> Optional[
     return filtered_properties_mapping.get(identifier)
 
 
-def get_properties(prefix: str, identifier: str, prop: str, **kwargs) -> Optional[List[str]]:
+def get_properties(prefix: str, identifier: str, prop: str, **kwargs) -> Optional[list[str]]:
     """Extract a set of properties for the given entity.
 
     :param prefix: the resource to load

pyobo/api/relations.py

@@ -1,11 +1,10 @@
-# -*- coding: utf-8 -*-
-
 """High-level API for relations."""
 
 import logging
 import os
+from collections.abc import Mapping
 from functools import lru_cache
-from typing import List, Mapping, Optional
+from typing import Optional
 
 import networkx as nx
 import pandas as pd
@@ -121,7 +120,7 @@ def get_id_multirelations_mapping(
     use_tqdm: bool = False,
     force: bool = False,
     version: Optional[str] = None,
-) -> Mapping[str, List[Reference]]:
+) -> Mapping[str, list[Reference]]:
     """Get the OBO file and output a synonym dictionary."""
     if version is None:
         version = get_version(prefix)
@@ -129,7 +128,7 @@ def get_id_multirelations_mapping(
     return ontology.get_id_multirelations_mapping(typedef=typedef, use_tqdm=use_tqdm)
 
 
-@lru_cache()
+@lru_cache
 @wrap_norm_prefix
 def get_relation_mapping(
     prefix: str,
@@ -147,9 +146,9 @@ def get_relation_mapping(
      Example usage: get homology between HGNC and MGI:
 
     >>> import pyobo
-    >>> human_mapt_hgnc_id = '6893'
-    >>> mouse_mapt_mgi_id = '97180'
-    >>> hgnc_mgi_orthology_mapping = pyobo.get_relation_mapping('hgnc', 'ro:HOM0000017', 'mgi')
+    >>> human_mapt_hgnc_id = "6893"
+    >>> mouse_mapt_mgi_id = "97180"
+    >>> hgnc_mgi_orthology_mapping = pyobo.get_relation_mapping("hgnc", "ro:HOM0000017", "mgi")
     >>> assert mouse_mapt_mgi_id == hgnc_mgi_orthology_mapping[human_mapt_hgnc_id]
     """
     if version is None:
@@ -178,9 +177,11 @@ def get_relation(
      Example usage: get homology between MAPT in HGNC and MGI:
 
     >>> import pyobo
-    >>> human_mapt_hgnc_id = '6893'
-    >>> mouse_mapt_mgi_id = '97180'
-    >>> assert mouse_mapt_mgi_id == pyobo.get_relation('hgnc', human_mapt_hgnc_id, 'ro:HOM0000017', 'mgi')
+    >>> human_mapt_hgnc_id = "6893"
+    >>> mouse_mapt_mgi_id = "97180"
+    >>> assert mouse_mapt_mgi_id == pyobo.get_relation(
+    ...     "hgnc", human_mapt_hgnc_id, "ro:HOM0000017", "mgi"
+    ... )
     """
     relation_mapping = get_relation_mapping(
         prefix=prefix,

pyobo/api/species.py

@@ -1,14 +1,13 @@
-# -*- coding: utf-8 -*-
-
 """High-level API for species."""
 
 import logging
+from collections.abc import Mapping
 from functools import lru_cache
-from typing import Mapping, Optional
+from typing import Optional
 
 from .alts import get_primary_identifier
 from .utils import get_version
-from ..getters import NoBuild, get_ontology
+from ..getters import NoBuildError, get_ontology
 from ..identifier_utils import wrap_norm_prefix
 from ..utils.cache import cached_mapping
 from ..utils.path import prefix_cache_join
@@ -29,7 +28,7 @@ def get_species(prefix: str, identifier: str, *, version: Optional[str] = None)
 
     try:
         id_species = get_id_species_mapping(prefix, version=version)
-    except NoBuild:
+    except NoBuildError:
         logger.warning("unable to look up species for prefix %s", prefix)
         return None
 
@@ -41,7 +40,7 @@ def get_species(prefix: str, identifier: str, *, version: Optional[str] = None)
     return id_species.get(primary_id)
 
 
-@lru_cache()
+@lru_cache
 @wrap_norm_prefix
 def get_id_species_mapping(
     prefix: str,

pyobo/api/typedefs.py

@@ -1,5 +1,3 @@
-# -*- coding: utf-8 -*-
-
 """High-level API for typedefs."""
 
 import logging
@@ -21,7 +19,7 @@ __all__ = [
 logger = logging.getLogger(__name__)
 
 
-@lru_cache()
+@lru_cache
 @wrap_norm_prefix
 def get_typedef_df(
     prefix: str, *, force: bool = False, version: Optional[str] = None

pyobo/api/utils.py

@@ -1,8 +1,9 @@
-# -*- coding: utf-8 -*-
-
 """Utilities for high-level API."""
 
 import json
+import logging
+import os
+from functools import lru_cache
 from typing import Optional
 
 import bioversions
@@ -10,10 +11,14 @@ import bioversions
 from ..utils.path import prefix_directory_join
 
 __all__ = [
+    "safe_get_version",
     "get_version",
+    "get_version_pins",
     "VersionError",
 ]
 
+logger = logging.getLogger(__name__)
+
 
 class VersionError(ValueError):
     """A catch-all for version getting failure."""
@@ -25,6 +30,10 @@ def get_version(prefix: str) -> Optional[str]:
     :param prefix: the resource name
     :return: The version if available else None
     """
+    # Prioritize loaded environment variable PYOBO_VERSION_PINS dictionary
+    version = get_version_pins().get(prefix)
+    if version:
+        return version
     try:
         version = bioversions.get_version(prefix)
     except KeyError:
@@ -41,3 +50,55 @@ def get_version(prefix: str) -> Optional[str]:
         return data["version"]
 
     return None
+
+
+def safe_get_version(prefix: str) -> str:
+    """Get the version."""
+    v = get_version(prefix)
+    if v is None:
+        raise ValueError
+    return v
+
+
+@lru_cache(1)
+def get_version_pins() -> dict[str, str]:
+    """Retrieve user-defined resource version pins.
+
+    To set your own resource pins, set your machine's environmental variable
+    "PYOBO_VERSION_PINS" to a JSON string containing string resource prefixes
+    as keys and string versions of their respective resource as values.
+    Constraining version pins will make PyOBO rely on cached versions of a resource.
+    A user might want to pin resource versions that are used by PyOBO due to
+    the fact that PyOBO will download the latest version of a resource if it is
+    not pinned. This downloading process can lead to a slow-down in downstream
+    applications that rely on PyOBO.
+    """
+    version_pins_str = os.getenv("PYOBO_VERSION_PINS")
+    if not version_pins_str:
+        return {}
+
+    try:
+        version_pins = json.loads(version_pins_str)
+    except ValueError as e:
+        logger.error(
+            "The value for the environment variable PYOBO_VERSION_PINS "
+            "must be a valid JSON string: %s",
+            e,
+        )
+        return {}
+
+    for prefix, version in list(version_pins.items()):
+        if not isinstance(prefix, str) or not isinstance(version, str):
+            logger.error(f"The prefix:{prefix} and version:{version} name must both be strings")
+            del version_pins[prefix]
+
+    logger.debug(
+        f"These are the resource versions that are pinned.\n"
+        f"{version_pins}. "
+        f"\nPyobo will download the latest version of a resource if it's "
+        f"not pinned.\nIf you want to use a specific version of a "
+        f"resource, edit your PYOBO_VERSION_PINS environmental "
+        f"variable which is a JSON string to include a prefix and version "
+        f"name."
+    )
+    return version_pins