pyobo 0.11.2__py3-none-any.whl → 0.12.0__py3-none-any.whl

pyobo/api/typedefs.py

@@ -2,15 +2,16 @@
 
 import logging
 from functools import lru_cache
-from typing import Optional
 
 import pandas as pd
+from typing_extensions import Unpack
 
-from .utils import get_version
+from .utils import get_version_from_kwargs
+from ..constants import GetOntologyKwargs, check_should_cache, check_should_force
 from ..getters import get_ontology
 from ..identifier_utils import wrap_norm_prefix
 from ..utils.cache import cached_df
-from ..utils.path import prefix_cache_join
+from ..utils.path import CacheArtifact, get_cache_path
 
 __all__ = [
     "get_typedef_df",
@@ -21,18 +22,17 @@ logger = logging.getLogger(__name__)
 
 @lru_cache
 @wrap_norm_prefix
-def get_typedef_df(
-    prefix: str, *, force: bool = False, version: Optional[str] = None
-) -> pd.DataFrame:
+def get_typedef_df(prefix: str, **kwargs: Unpack[GetOntologyKwargs]) -> pd.DataFrame:
     """Get an identifier to name mapping for the typedefs in an OBO file."""
-    if version is None:
-        version = get_version(prefix)
-    path = prefix_cache_join(prefix, name="typedefs.tsv", version=version)
+    version = get_version_from_kwargs(prefix, kwargs)
+    path = get_cache_path(prefix, CacheArtifact.typedefs, version=version)
 
-    @cached_df(path=path, dtype=str, force=force)
+    @cached_df(
+        path=path, dtype=str, force=check_should_force(kwargs), cache=check_should_cache(kwargs)
+    )
     def _df_getter() -> pd.DataFrame:
         logger.debug("[%s] no cached typedefs found. getting from OBO loader", prefix)
-        ontology = get_ontology(prefix, force=force, version=version)
+        ontology = get_ontology(prefix, **kwargs)
         logger.debug("[%s] loading typedef mappings", prefix)
         return ontology.get_typedef_df()
 

pyobo/api/utils.py

@@ -3,18 +3,23 @@
 import json
 import logging
 import os
+import warnings
 from functools import lru_cache
-from typing import Optional
+from typing import Literal, overload
 
 import bioversions
+import curies
+from bioregistry import NormalizedNamableReference as Reference
+from curies import ReferenceTuple
 
+from ..constants import GetOntologyKwargs
 from ..utils.path import prefix_directory_join
 
 __all__ = [
-    "safe_get_version",
+    "VersionError",
     "get_version",
     "get_version_pins",
-    "VersionError",
+    "safe_get_version",
 ]
 
 logger = logging.getLogger(__name__)
@@ -24,11 +29,25 @@ class VersionError(ValueError):
     """A catch-all for version getting failure."""
 
 
-def get_version(prefix: str) -> Optional[str]:
+# docstr-coverage:excused `overload`
+@overload
+def get_version(prefix: str, *, strict: Literal[True] = True) -> str: ...
+
+
+# docstr-coverage:excused `overload`
+@overload
+def get_version(prefix: str, *, strict: Literal[False] = False) -> str | None: ...
+
+
+def get_version(prefix: str, *, strict: bool = False) -> str | None:
     """Get the version for the resource, if available.
 
     :param prefix: the resource name
-    :return: The version if available else None
+    :param strict: Should an error be raised if no version is available?
+
+    :returns: The version if available else None
+
+    :raises VersionError: if the version is not available and strict mode is enabled
     """
     # Prioritize loaded environment variable PYOBO_VERSION_PINS dictionary
     version = get_version_pins().get(prefix)
@@ -47,13 +66,27 @@ def get_version(prefix: str) -> Optional[str]:
     metadata_json_path = prefix_directory_join(prefix, name="metadata.json", ensure_exists=False)
     if metadata_json_path.exists():
         data = json.loads(metadata_json_path.read_text())
-        return data["version"]
+        version = data["version"]
+        if version:
+            return version
+
+    if strict:
+        raise ValueError
 
     return None
 
 
+def get_version_from_kwargs(prefix: str, kwargs: GetOntologyKwargs) -> str | None:
+    """Get the version for the resource based on generic keyword arguments."""
+    if version := kwargs.get("version"):
+        return version
+    # it's okay if none gets returned after getting this far, we at least tried
+    return get_version(prefix, strict=False)
+
+
 def safe_get_version(prefix: str) -> str:
     """Get the version."""
+    # FIXME replace with get_version(prefix, strict=True)
     v = get_version(prefix)
     if v is None:
         raise ValueError
@@ -65,13 +98,12 @@ 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.
+    "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:
@@ -102,3 +134,24 @@ def get_version_pins() -> dict[str, str]:
         f"name."
     )
     return version_pins
+
+
+def _get_pi(
+    prefix: str | curies.Reference | ReferenceTuple, identifier: str | None = None, /
+) -> Reference:
+    if isinstance(prefix, ReferenceTuple | curies.Reference):
+        if identifier is not None:
+            raise ValueError("unexpected non-none value passed as second positional argument")
+        return Reference(prefix=prefix.prefix, identifier=prefix.identifier)
+    if isinstance(prefix, str) and identifier is None:
+        return Reference.from_curie(prefix)
+    if identifier is None:
+        raise ValueError(
+            "prefix was given as a string, so an identifier was expected to be passed as a string as well"
+        )
+    warnings.warn(
+        "Passing a prefix and identifier as seperate arguments is deprecated. Please pass a curies.Reference or curies.ReferenceTuple in the first positional-only argument instead.",
+        DeprecationWarning,
+        stacklevel=4,  # this is 4 since this is (always?) called from inside a decorator
+    )
+    return Reference(prefix=prefix, identifier=identifier)

pyobo/api/xrefs.py

@@ -1,28 +1,36 @@
 """High-level API for synonyms."""
 
 import logging
+import warnings
 from collections.abc import Mapping
 from functools import lru_cache
-from typing import Optional, Union
 
 import pandas as pd
-from tqdm.auto import tqdm
-from tqdm.contrib.logging import logging_redirect_tqdm
-
-from .utils import get_version
-from ..constants import TARGET_ID, TARGET_PREFIX
+from curies import ReferenceTuple
+from typing_extensions import Unpack
+
+from .utils import get_version_from_kwargs
+from ..constants import (
+    TARGET_ID,
+    TARGET_PREFIX,
+    GetOntologyKwargs,
+    check_should_cache,
+    check_should_force,
+    check_should_use_tqdm,
+)
 from ..getters import get_ontology
 from ..identifier_utils import wrap_norm_prefix
-from ..struct import Obo, Reference
-from ..utils.cache import cached_df, cached_mapping
-from ..utils.path import prefix_cache_join
+from ..struct import Obo
+from ..utils.cache import cached_df
+from ..utils.path import CacheArtifact, get_cache_path
 
 __all__ = [
-    "get_xrefs_df",
     "get_filtered_xrefs",
+    "get_mappings_df",
+    "get_sssom_df",
     "get_xref",
     "get_xrefs",
-    "get_sssom_df",
+    "get_xrefs_df",
 ]
 
 logger = logging.getLogger(__name__)
@@ -35,10 +43,10 @@ def get_xref(
     new_prefix: str,
     *,
     flip: bool = False,
-    version: Optional[str] = None,
-) -> Optional[str]:
+    **kwargs: Unpack[GetOntologyKwargs],
+) -> str | None:
     """Get the xref with the new prefix if a direct path exists."""
-    filtered_xrefs = get_filtered_xrefs(prefix, new_prefix, flip=flip, version=version)
+    filtered_xrefs = get_filtered_xrefs(prefix, new_prefix, flip=flip, **kwargs)
     return filtered_xrefs.get(identifier)
 
 
@@ -49,32 +57,18 @@ def get_filtered_xrefs(
     xref_prefix: str,
     *,
     flip: bool = False,
-    use_tqdm: bool = False,
-    force: bool = False,
-    strict: bool = False,
-    version: Optional[str] = None,
+    **kwargs: Unpack[GetOntologyKwargs],
 ) -> Mapping[str, str]:
     """Get xrefs to a given target."""
-    if version is None:
-        version = get_version(prefix)
-    path = prefix_cache_join(prefix, "xrefs", name=f"{xref_prefix}.tsv", version=version)
-    all_xrefs_path = prefix_cache_join(prefix, name="xrefs.tsv", version=version)
-    header = [f"{prefix}_id", f"{xref_prefix}_id"]
-
-    @cached_mapping(path=path, header=header, use_tqdm=use_tqdm, force=force)
-    def _get_mapping() -> Mapping[str, str]:
-        if all_xrefs_path.is_file():
-            logger.info("[%s] loading pre-cached xrefs", prefix)
-            df = pd.read_csv(all_xrefs_path, sep="\t", dtype=str)
-            logger.info("[%s] filtering pre-cached xrefs", prefix)
-            df = df.loc[df[TARGET_PREFIX] == xref_prefix, [f"{prefix}_id", TARGET_ID]]
-            return dict(df.values)
-
-        logger.info("[%s] no cached xrefs found. getting from OBO loader", prefix)
-        ontology = get_ontology(prefix, force=force, strict=strict, version=version)
-        return ontology.get_filtered_xrefs_mapping(xref_prefix, use_tqdm=use_tqdm)
-
-    rv = _get_mapping()
+    mappings_df = get_mappings_df(prefix, **kwargs)
+
+    rv = {}
+    for subject_curie, object_curie in mappings_df[["subject_id", "object_id"]].values:
+        subject_pair = ReferenceTuple.from_curie(subject_curie)
+        object_pair = ReferenceTuple.from_curie(object_curie)
+        if object_pair.prefix == xref_prefix:
+            rv[subject_pair.identifier] = object_pair.identifier
+
     if flip:
         return {v: k for k, v in rv.items()}
     return rv
@@ -84,104 +78,104 @@ get_xrefs = get_filtered_xrefs
 
 
 @wrap_norm_prefix
-def get_xrefs_df(
-    prefix: str,
-    *,
-    use_tqdm: bool = False,
-    force: bool = False,
-    strict: bool = False,
-    version: Optional[str] = None,
-) -> pd.DataFrame:
+def get_xrefs_df(prefix: str, **kwargs: Unpack[GetOntologyKwargs]) -> pd.DataFrame:
     """Get all xrefs."""
-    if version is None:
-        version = get_version(prefix)
-    path = prefix_cache_join(prefix, name="xrefs.tsv", version=version)
+    warnings.warn(
+        f"use pyobo.get_mappings_df instead of pyobo.get_xrefs_df."
+        f"Not using cache artifact path to {CacheArtifact.xrefs}",
+        DeprecationWarning,
+        stacklevel=2,
+    )
 
-    @cached_df(path=path, dtype=str, force=force)
-    def _df_getter() -> pd.DataFrame:
-        logger.info("[%s] no cached xrefs found. getting from OBO loader", prefix)
-        ontology = get_ontology(prefix, force=force, strict=strict, version=version)
-        return ontology.get_xrefs_df(use_tqdm=use_tqdm)
+    mappings_df = get_mappings_df(prefix, **kwargs)
 
-    return _df_getter()
+    rows = []
+    for subject_curie, object_curie in mappings_df[["subject_id", "object_id"]].values:
+        subject_pair = ReferenceTuple.from_curie(subject_curie)
+        object_pair = ReferenceTuple.from_curie(object_curie)
+        rows.append((subject_pair.identifier, object_pair.prefix, object_pair.identifier))
+
+    df = pd.DataFrame(rows, columns=[f"{prefix}_id", TARGET_PREFIX, TARGET_ID])
+    df = df.drop_duplicates()
+    return df
 
 
 def get_sssom_df(
-    prefix: Union[str, Obo],
+    prefix: str | Obo, *, names: bool = True, **kwargs: Unpack[GetOntologyKwargs]
+) -> pd.DataFrame:
+    """Get an SSSOM dataframe, replaced by :func:`get_mappings_df`."""
+    warnings.warn("get_sssom_df was renamed to get_mappings_df", DeprecationWarning, stacklevel=2)
+    return get_mappings_df(prefix=prefix, names=names, **kwargs)
+
+
+def get_mappings_df(
+    prefix: str | Obo,
     *,
-    predicate_id: str = "oboinowl:hasDbXref",
-    justification: str = "sempav:UnspecifiedMatching",
     names: bool = True,
-    **kwargs,
+    include_mapping_source_column: bool = False,
+    **kwargs: Unpack[GetOntologyKwargs],
 ) -> pd.DataFrame:
-    r"""Get xrefs from a source as an SSSOM dataframe.
+    r"""Get semantic mappings from a source as an SSSOM dataframe.
 
     :param prefix: The ontology to look in for xrefs
-    :param predicate_id: The predicate used in the SSSOM document. By default, ontologies
-        don't typically ascribe semantics to xrefs so ``oboinowl:hasDbXref`` is used
-    :param justification: The justification for the mapping. By default, ontologies
-        don't typically ascribe semantics, so this is left with `sempav:UnspecifiedMatching`
     :param names: Add name columns (``subject_label`` and ``object_label``)
+
     :returns: A SSSOM-compliant dataframe of xrefs
 
     For example, if you want to get UMLS as an SSSOM dataframe, you can do
 
-    >>> import pyobo
-    >>> df = pyobo.get_sssom_df("umls")
-    >>> df.to_csv("umls.sssom.tsv", sep="\t", index=False)
+    .. code-block:: python
 
-    If you don't want to get all of the many resources required to add
-    names, you can pass ``names=False``
+        import pyobo
 
-    >>> import pyobo
-    >>> df = pyobo.get_sssom_df("umls", names=False)
-    >>> df.to_csv("umls.sssom.tsv", sep="\t", index=False)
+        df = pyobo.get_mappings_df("umls")
+        df.to_csv("umls.sssom.tsv", sep="\t", index=False)
 
-    .. note:: This assumes the Bioregistry as the prefix map
-    """
-    from .names import get_name
+    If you don't want to get all of the many resources required to add names, you can
+    pass ``names=False``
+
+    .. code-block:: python
+
+        import pyobo
+
+        df = pyobo.get_mappings_df("umls", names=False)
+        df.to_csv("umls.sssom.tsv", sep="\t", index=False)
 
+    .. note::
+
+        This assumes the Bioregistry as the prefix map
+    """
     if isinstance(prefix, Obo):
-        df = prefix.get_xrefs_df()
+        df = prefix.get_mappings_df(
+            include_subject_labels=names,
+            include_mapping_source_column=include_mapping_source_column,
+            use_tqdm=check_should_use_tqdm(kwargs),
+        )
         prefix = prefix.ontology
+
     else:
-        df = get_xrefs_df(prefix=prefix, **kwargs)
-    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"
-        ):
-            source = Reference(prefix=prefix, identifier=source_id)
-            target = Reference(prefix=target_prefix, identifier=target_id)
-
-            if names:
-                rows.append(
-                    (
-                        source.curie,
-                        get_name(prefix, source_id) or "",
-                        target.curie,
-                        get_name(target_prefix, target_id),
-                        predicate_id,
-                        justification,
-                    )
-                )
-            else:
-                rows.append((source.curie, target.curie, predicate_id, justification))
+        version = get_version_from_kwargs(prefix, kwargs)
+        path = get_cache_path(prefix, CacheArtifact.mappings, version=version)
+
+        @cached_df(
+            path=path, dtype=str, force=check_should_force(kwargs), cache=check_should_cache(kwargs)
+        )
+        def _df_getter() -> pd.DataFrame:
+            logger.info("[%s] rebuilding SSSOM", prefix)
+            ontology = get_ontology(prefix, **kwargs)
+            return ontology.get_mappings_df(
+                use_tqdm=check_should_use_tqdm(kwargs),
+                include_subject_labels=True,
+                include_mapping_source_column=include_mapping_source_column,
+            )
+
+        df = _df_getter()
 
     if names:
-        columns = [
-            "subject_id",
-            "subject_label",
-            "object_id",
-            "object_label",
-            "predicate_id",
-            "mapping_justification",
-        ]
-    else:
-        columns = [
-            "subject_id",
-            "object_id",
-            "predicate_id",
-            "mapping_justification",
-        ]
-    return pd.DataFrame(rows, columns=columns)
+        from .names import get_name_by_curie
+
+        df["object_label"] = df["object_id"].map(get_name_by_curie)
+    elif "subject_label" in df.columns:
+        del df["subject_label"]
+
+    return df

pyobo/cli/cli.py

@@ -2,23 +2,19 @@
 
 import logging
 import os
-import sys
+from collections.abc import Iterable
+from functools import lru_cache
 from operator import itemgetter
 
+import bioregistry
 import click
 import humanize
-from more_click import verbose_option
 from tabulate import tabulate
 
-from .aws import main as aws_main
 from .database import main as database_main
 from .lookup import lookup
-from ..constants import RAW_DIRECTORY
-from ..plugins import has_nomenclature_plugin, iter_nomenclature_plugins
-from ..registries import iter_cached_obo
-from ..utils.io import get_writer
-from ..xrefdb.canonicalizer import Canonicalizer, get_priority_curie, remap_file_stream
-from ..xrefdb.priority import DEFAULT_PRIORITY_LIST
+from ..constants import GLOBAL_SKIP, RAW_DIRECTORY
+from ..plugins import has_nomenclature_plugin
 
 __all__ = ["main"]
 
@@ -31,36 +27,6 @@ def main():
     """CLI for PyOBO."""
 
 
-_ORDERING_TEXT = ", ".join(f"{i}) {x}" for i, x in enumerate(DEFAULT_PRIORITY_LIST, start=1))
-
-
-@main.command(help=f"Prioritize a CURIE from ordering: {_ORDERING_TEXT}")
-@click.argument("curie")
-def prioritize(curie: str):
-    """Prioritize a CURIE."""
-    priority_curie = get_priority_curie(curie)
-    click.secho(priority_curie)
-
-
-@main.command()
-@click.option("-i", "--file-in", type=click.File("r"), default=sys.stdin)
-@click.option("-o", "--file-out", type=click.File("w"), default=sys.stdout)
-@click.option("--column", type=int, default=0, show_default=True)
-@click.option("--sep", default="\t", show_default=True)
-def recurify(file_in, file_out, column: int, sep: str):
-    """Remap a column in a given file stream."""
-    remap_file_stream(file_in=file_in, file_out=file_out, column=column, sep=sep)
-
-
-@main.command()
-@verbose_option
-def cache():
-    """Cache all resources."""
-    for obo in iter_nomenclature_plugins():
-        click.secho(f"Caching {obo.ontology}", bold=True, fg="green")
-        obo.write_default()
-
-
 @main.command()
 @click.option("--remove-obo", is_flag=True)
 def clean(remove_obo: bool):
@@ -93,7 +59,7 @@ def clean(remove_obo: bool):
 @main.command()
 def ls():
     """List how big all of the OBO files are."""
-    entries = [(prefix, os.path.getsize(path)) for prefix, path in iter_cached_obo()]
+    entries = [(prefix, os.path.getsize(path)) for prefix, path in _iter_cached_obo()]
     entries = [
         (prefix, humanize.naturalsize(size), "✅" if not has_nomenclature_plugin(prefix) else "❌")
         for prefix, size in sorted(entries, key=itemgetter(1), reverse=True)
@@ -101,19 +67,38 @@ def ls():
     click.echo(tabulate(entries, headers=["Source", "Size", "OBO"]))
 
 
-@main.command()
-@verbose_option
-@click.option("-f", "--file", type=click.File("w"))
-def remapping(file):
-    """Make a canonical remapping."""
-    canonicalizer = Canonicalizer.get_default()
-    writer = get_writer(file)
-    writer.writerow(["input", "canonical"])
-    writer.writerows(canonicalizer.iterate_flat_mapping())
+def _iter_cached_obo() -> Iterable[tuple[str, str]]:
+    """Iterate over cached OBO paths."""
+    for prefix in os.listdir(RAW_DIRECTORY):
+        if prefix in GLOBAL_SKIP or _has_no_download(prefix) or bioregistry.is_deprecated(prefix):
+            continue
+        d = RAW_DIRECTORY.joinpath(prefix)
+        if not os.path.isdir(d):
+            continue
+        for x in os.listdir(d):
+            if x.endswith(".obo"):
+                p = os.path.join(d, x)
+                yield prefix, p
+
+
+def _has_no_download(prefix: str) -> bool:
+    """Return if the prefix is not available."""
+    prefix_norm = bioregistry.normalize_prefix(prefix)
+    return prefix_norm is not None and prefix_norm in _no_download()
+
+
+@lru_cache(maxsize=1)
+def _no_download() -> set[str]:
+    """Get the list of prefixes not available as OBO."""
+    return {
+        prefix
+        for prefix in bioregistry.read_registry()
+        if bioregistry.get_obo_download(prefix) is None
+        and bioregistry.get_owl_download(prefix) is None
+    }
 
 
 main.add_command(lookup)
-main.add_command(aws_main)
 main.add_command(database_main)
 
 if __name__ == "__main__":