pyobo 0.10.12__py3-none-any.whl → 0.11.1__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,19 +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
@@ -34,7 +33,7 @@ __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])
@@ -46,8 +45,8 @@ def get_name_by_curie(curie: str, *, version: Optional[str] = None) -> Optional[
 
 X = TypeVar("X")
 
-NO_BUILD_PREFIXES: Set[str] = set()
-NO_BUILD_LOGGED: Set = set()
+NO_BUILD_PREFIXES: set[str] = set()
+NO_BUILD_LOGGED: set = set()
 
 
 def _help_get(
@@ -56,12 +55,12 @@ 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)
@@ -85,22 +84,22 @@ def _help_get(
 @wrap_norm_prefix
 def get_name(
     prefix: str | Reference | ReferenceTuple,
-    identifier: Optional[str] = None,
+    identifier: str | None = None,
     /,
     *,
-    version: Optional[str] = None,
-) -> Optional[str]:
+    version: str | None = None,
+) -> str | None:
     """Get the name for an entity."""
     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
@@ -115,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:
@@ -128,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":
@@ -157,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:
@@ -165,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)
@@ -177,8 +176,8 @@ def get_name_id_mapping(
 
 @wrap_norm_prefix
 def get_definition(
-    prefix: str, identifier: str | None = None, *, version: Optional[str] = None
-) -> Optional[str]:
+    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(":")
@@ -190,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:
@@ -213,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()
 
@@ -229,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)
 
@@ -240,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,20 +1,24 @@
-# -*- 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
 
-from ..constants import VERSION_PINS
 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."""
@@ -26,8 +30,8 @@ def get_version(prefix: str) -> Optional[str]:
     :param prefix: the resource name
     :return: The version if available else None
     """
-    # Prioritize loaded environmental variable VERSION_PINS dictionary
-    version = VERSION_PINS.get(prefix)
+    # Prioritize loaded environment variable PYOBO_VERSION_PINS dictionary
+    version = get_version_pins().get(prefix)
     if version:
         return version
     try:
@@ -46,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

pyobo/api/xrefs.py

@@ -1,10 +1,9 @@
-# -*- coding: utf-8 -*-
-
 """High-level API for synonyms."""
 
 import logging
+from collections.abc import Mapping
 from functools import lru_cache
-from typing import List, Mapping, Optional, Tuple, Union
+from typing import Optional, Union
 
 import pandas as pd
 from tqdm.auto import tqdm
@@ -43,7 +42,7 @@ def get_xref(
     return filtered_xrefs.get(identifier)
 
 
-@lru_cache()
+@lru_cache
 @wrap_norm_prefix
 def get_filtered_xrefs(
     prefix: str,
@@ -147,7 +146,7 @@ def get_sssom_df(
         prefix = prefix.ontology
     else:
         df = get_xrefs_df(prefix=prefix, **kwargs)
-    rows: List[Tuple[str, ...]] = []
+    rows: list[tuple[str, ...]] = []
     with logging_redirect_tqdm():
         for source_id, target_prefix, target_id in tqdm(
             df.values, unit="mapping", unit_scale=True, desc=f"[{prefix}] SSSOM"