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

pyobo/cli/lookup.py

@@ -2,17 +2,20 @@
 
 import json
 import sys
-from typing import Optional
+from collections.abc import Mapping
 
 import bioregistry
 import click
 from more_click import verbose_option
+from typing_extensions import Unpack
 
 from .utils import (
+    Clickable,
     echo_df,
     force_option,
-    no_strict_option,
+    force_process_option,
     prefix_argument,
+    strict_option,
     version_option,
 )
 from ..api import (
@@ -28,15 +31,17 @@ from ..api import (
     get_id_synonyms_mapping,
     get_id_to_alts,
     get_ids,
+    get_mappings_df,
     get_metadata,
     get_name,
-    get_name_by_curie,
     get_properties_df,
     get_relations_df,
     get_typedef_df,
     get_xrefs_df,
 )
-from ..identifier_utils import normalize_curie
+from ..constants import LookupKwargs
+from ..getters import get_ontology
+from ..struct.reference import _parse_str_or_curie_or_uri
 
 __all__ = [
     "lookup",
@@ -48,150 +53,123 @@ def lookup():
     """Lookup resources."""
 
 
-@lookup.command()
-@prefix_argument
+def lookup_annotate(f: Clickable) -> Clickable:
+    """Add appropriate decorators to lookup CLI functions."""
+    for decorator in [
+        lookup.command(),
+        prefix_argument,
+        verbose_option,
+        force_option,
+        force_process_option,
+        strict_option,
+        version_option,
+    ]:
+        f = decorator(f)
+    return f
+
+
+identifier_option = click.option("-i", "--identifier")
+
+
+@lookup_annotate
 @click.option("-t", "--target")
-@verbose_option
-@force_option
-@no_strict_option
-@version_option
-def xrefs(prefix: str, target: str, force: bool, no_strict: bool, version: Optional[str]):
+def xrefs(target: str, **kwargs: Unpack[LookupKwargs]) -> None:
     """Page through xrefs for the given namespace to the second given namespace."""
     if target:
-        target = bioregistry.normalize_prefix(target)
-        filtered_xrefs = get_filtered_xrefs(
-            prefix, target, force=force, strict=not no_strict, version=version
-        )
+        target_norm = bioregistry.normalize_prefix(target)
+        filtered_xrefs = get_filtered_xrefs(xref_prefix=target_norm, **kwargs)
         click.echo_via_pager(
             "\n".join(f"{identifier}\t{_xref}" for identifier, _xref in filtered_xrefs.items())
         )
     else:
-        all_xrefs_df = get_xrefs_df(prefix, force=force, strict=not no_strict, version=version)
+        all_xrefs_df = get_xrefs_df(**kwargs)
         echo_df(all_xrefs_df)
 
 
-@lookup.command()
-@prefix_argument
-@verbose_option
-@force_option
-@version_option
-def metadata(prefix: str, force: bool, version: Optional[str]):
+@lookup_annotate
+@click.option("--include-names", is_flag=True)
+@click.option("-t", "--target")
+def mappings(include_names: bool, target: str | None, **kwargs: Unpack[LookupKwargs]) -> None:
+    """Page through mappings for the given namespace."""
+    mappings_df = get_mappings_df(names=include_names, **kwargs)
+    if target:
+        target_norm = bioregistry.normalize_prefix(target)
+        if target_norm is None:
+            raise ValueError
+        idx = mappings_df["object_id"].map(
+            lambda x: bioregistry.normalize_prefix(x.split(":")[0]) == target_norm
+        )
+        mappings_df = mappings_df[idx]
+    echo_df(mappings_df)
+
+
+@lookup_annotate
+def metadata(**kwargs: Unpack[LookupKwargs]) -> None:
     """Print the metadata for the given namespace."""
-    metadata = get_metadata(prefix, force=force, version=version)
+    metadata = get_metadata(**kwargs)
     click.echo(json.dumps(metadata, indent=2))
 
 
-@lookup.command()
-@prefix_argument
-@verbose_option
-@force_option
-@no_strict_option
-@version_option
-def ids(prefix: str, force: bool, no_strict: bool, version: Optional[str]):
+@lookup_annotate
+def ids(**kwargs: Unpack[LookupKwargs]) -> None:
     """Page through the identifiers of entities in the given namespace."""
-    id_list = get_ids(prefix, force=force, strict=not no_strict, version=version)
-    click.echo_via_pager("\n".join(id_list))
-
-
-@lookup.command()
-@prefix_argument
-@verbose_option
-@force_option
-@no_strict_option
-@click.option("-i", "--identifier")
-@version_option
-def names(
-    prefix: str, identifier: Optional[str], force: bool, no_strict: bool, version: Optional[str]
-):
-    """Page through the identifiers and names of entities in the given namespace."""
-    id_to_name = get_id_name_mapping(prefix, force=force, strict=not no_strict, version=version)
-    if identifier is None:
-        _help_page_mapping(id_to_name)
+    id_list = get_ids(**kwargs)
+    if not id_list:
+        click.secho("no data", fg="red")
     else:
-        name = id_to_name.get(identifier)
-        if name is None:
-            click.secho(f"No name available for {identifier}", fg="red")
-        else:
-            click.echo(name)
-
-
-@lookup.command()
-@prefix_argument
-@verbose_option
-@force_option
-@no_strict_option
-@click.option("-i", "--identifier")
-@version_option
-def species(
-    prefix: str, identifier: Optional[str], force: bool, no_strict: bool, version: Optional[str]
-):
+        click.echo_via_pager("\n".join(id_list))
+
+
+@lookup_annotate
+@identifier_option
+def names(identifier: str | None, **kwargs: Unpack[LookupKwargs]) -> None:
+    """Page through the identifiers and names of entities in the given namespace."""
+    id_to_name = get_id_name_mapping(**kwargs)
+    _help_page_mapping(id_to_name, identifier=identifier)
+
+
+@lookup_annotate
+@identifier_option
+def species(identifier: str | None, **kwargs: Unpack[LookupKwargs]) -> None:
     """Page through the identifiers and species of entities in the given namespace."""
-    id_to_species = get_id_species_mapping(
-        prefix, force=force, strict=not no_strict, version=version
-    )
-    if identifier is None:
-        _help_page_mapping(id_to_species)
-    else:
-        species = id_to_species.get(identifier)
-        if species is None:
-            click.secho(f"No species available for {identifier}", fg="red")
-        else:
-            click.echo(species)
+    id_to_species = get_id_species_mapping(**kwargs)
+    _help_page_mapping(id_to_species, identifier=identifier)
 
 
-@lookup.command()
-@prefix_argument
-@verbose_option
-@force_option
-@click.option("-i", "--identifier")
-@version_option
-def definitions(prefix: str, identifier: Optional[str], force: bool, version: Optional[str]):
+@lookup_annotate
+@identifier_option
+def definitions(identifier: str | None, **kwargs: Unpack[LookupKwargs]) -> None:
     """Page through the identifiers and definitions of entities in the given namespace."""
-    id_to_definition = get_id_definition_mapping(prefix, force=force, version=version)
-    if identifier is None:
-        _help_page_mapping(id_to_definition)
-    else:
-        definition = id_to_definition.get(identifier)
-        if definition is None:
-            click.secho(f"No definition available for {identifier}", fg="red")
-        else:
-            click.echo(definition)
+    id_to_definition = get_id_definition_mapping(**kwargs)
+    _help_page_mapping(id_to_definition, identifier=identifier)
 
 
-@lookup.command()
-@prefix_argument
-@verbose_option
-@force_option
-@version_option
-def typedefs(prefix: str, force: bool, version: Optional[str]):
+@lookup_annotate
+def typedefs(**kwargs: Unpack[LookupKwargs]) -> None:
     """Page through the identifiers and names of typedefs in the given namespace."""
-    df = get_typedef_df(prefix, force=force, version=version)
+    df = get_typedef_df(**kwargs)
     echo_df(df)
 
 
-def _help_page_mapping(id_to_name):
-    click.echo_via_pager("\n".join("\t".join(item) for item in id_to_name.items()))
+def _help_page_mapping(id_to_name: Mapping[str, str], *, identifier: str | None = None) -> None:
+    if not id_to_name:
+        click.secho("no data", fg="red")
+    elif identifier:
+        value = id_to_name.get(identifier)
+        if value:
+            click.echo(value)
+        else:
+            click.secho(f"no data for {identifier}", fg="red")
+    else:
+        click.echo_via_pager("\n".join("\t".join(item) for item in id_to_name.items()))
 
 
-@lookup.command()
-@prefix_argument
-@verbose_option
-@force_option
-@version_option
-def synonyms(prefix: str, force: bool, version: Optional[str]):
+@lookup_annotate
+@identifier_option
+def synonyms(identifier: str | None, **kwargs: Unpack[LookupKwargs]) -> None:
     """Page through the synonyms for entities in the given namespace."""
-    if ":" in prefix:
-        _prefix, identifier = normalize_curie(prefix)
-        if _prefix is None or identifier is None:
-            click.secho(f"could not normalize {prefix}")
-            return sys.exit(1)
-        name = get_name(_prefix, identifier)
-        id_to_synonyms = get_id_synonyms_mapping(_prefix, force=force)
-        click.echo(f"Synonyms for {_prefix}:{identifier} ! {name}")
-        for synonym in id_to_synonyms.get(identifier, []):
-            click.echo(synonym)
-    else:  # it's a prefix
-        id_to_synonyms = get_id_synonyms_mapping(prefix, force=force, version=version)
+    id_to_synonyms = get_id_synonyms_mapping(**kwargs)
+    if identifier is None:
         click.echo_via_pager(
             "\n".join(
                 f"{identifier}\t{_synonym}"
@@ -199,136 +177,126 @@ def synonyms(prefix: str, force: bool, version: Optional[str]):
                 for _synonym in _synonyms
             )
         )
+    else:
+        synonyms = id_to_synonyms.get(identifier, [])
+        if not synonyms:
+            click.secho(f"No synonyms available for {identifier}", fg="red")
+        else:
+            click.echo_via_pager("\n".join(synonyms))
 
 
-@lookup.command()
-@prefix_argument
+@lookup_annotate
 @click.option(
     "--relation", help="CURIE for the relationship or just the ID if local to the ontology"
 )
 @click.option("--target", help="Prefix for the target")
-@verbose_option
-@no_strict_option
-@force_option
 @click.option("--summarize", is_flag=True)
-@version_option
 def relations(
-    prefix: str,
     relation: str,
     target: str,
-    force: bool,
-    no_strict: bool,
     summarize: bool,
-    version: Optional[str],
-):
+    **kwargs: Unpack[LookupKwargs],
+) -> None:
     """Page through the relations for entities in the given namespace."""
     if relation is None:
-        relations_df = get_relations_df(prefix, force=force, strict=not no_strict, version=version)
+        relations_df = get_relations_df(**kwargs)
         if summarize:
             click.echo(relations_df[relations_df.columns[2]].value_counts())
         else:
             echo_df(relations_df)
     else:
-        curie = normalize_curie(relation)
-        if curie[1] is None:  # that's the identifier
-            click.secho(f"not valid curie, assuming local to {prefix}", fg="yellow")
-            curie = prefix, relation
+        relation_reference = _parse_str_or_curie_or_uri(relation, strict=False)
+        if relation_reference is None:
+            click.secho(f"not a valid curie: {relation}", fg="red")
+            raise sys.exit(1)
 
         if target is not None:
             norm_target = bioregistry.normalize_prefix(target)
             if norm_target is None:
                 raise ValueError
             relations_df = get_filtered_relations_df(
-                prefix, relation=curie, force=force, strict=not no_strict, target=norm_target
+                relation=relation_reference,
+                target=norm_target,
+                **kwargs,
             )
         else:
             raise NotImplementedError(f"can not filter by target prefix {target}")
 
 
-@lookup.command()
-@prefix_argument
+@lookup_annotate
 @click.option("--include-part-of", is_flag=True)
 @click.option("--include-has-member", is_flag=True)
-@verbose_option
-@force_option
-@version_option
 def hierarchy(
-    prefix: str,
     include_part_of: bool,
     include_has_member: bool,
-    force: bool,
-    version: Optional[str],
-):
+    **kwargs: Unpack[LookupKwargs],
+) -> None:
     """Page through the hierarchy for entities in the namespace."""
     h = get_hierarchy(
-        prefix,
         include_part_of=include_part_of,
         include_has_member=include_has_member,
-        force=force,
-        version=version,
+        **kwargs,
     )
-    click.echo_via_pager("\n".join("\t".join(row) for row in h.edges()))
+    if h.number_of_edges() == 0:
+        click.secho("no data", fg="red")
+    else:
+        click.echo_via_pager("\n".join(f"{u.curie}\t{v.curie}" for u, v in h.edges()))
 
 
-@lookup.command()
-@prefix_argument
+@lookup_annotate
 @click.argument("identifier")
-@verbose_option
-@force_option
-@version_option
-def ancestors(prefix: str, identifier: str, force: bool, version: Optional[str]):
+def ancestors(
+    identifier: str,
+    **kwargs: Unpack[LookupKwargs],
+) -> None:
     """Look up ancestors."""
-    curies = get_ancestors(prefix=prefix, identifier=identifier, force=force, version=version)
-    for curie in sorted(curies or []):
-        click.echo(f"{curie}\t{get_name_by_curie(curie, version=version)}")
+    # note, prefix is passed via kwargs
+    ancestors = get_ancestors(identifier=identifier, **kwargs)
+    for ancestor in sorted(ancestors or []):
+        click.echo(f"{ancestor.curie}\t{get_name(ancestor, version=kwargs['version'])}")
 
 
-@lookup.command()
-@prefix_argument
+@lookup_annotate
 @click.argument("identifier")
-@verbose_option
-@force_option
-@version_option
-def descendants(prefix: str, identifier: str, force: bool, version: Optional[str]):
+def descendants(
+    identifier: str,
+    **kwargs: Unpack[LookupKwargs],
+) -> None:
     """Look up descendants."""
-    curies = get_descendants(prefix=prefix, identifier=identifier, force=force, version=version)
-    for curie in sorted(curies or []):
-        click.echo(f"{curie}\t{get_name_by_curie(curie, version=version)}")
+    # note, prefix is passed via kwargs
+    descendants = get_descendants(identifier=identifier, **kwargs)
+    for descendant in sorted(descendants or []):
+        click.echo(f"{descendant.curie}\t{get_name(descendant, version=kwargs['version'])}")
 
 
-@lookup.command()
-@prefix_argument
+@lookup_annotate
 @click.option("-k", "--key")
-@verbose_option
-@force_option
-@version_option
-def properties(prefix: str, key: Optional[str], force: bool, version: Optional[str]):
+def properties(
+    key: str | None,
+    **kwargs: Unpack[LookupKwargs],
+) -> None:
     """Page through the properties for entities in the given namespace."""
     if key is None:
-        properties_df = get_properties_df(prefix, force=force, version=version)
+        properties_df = get_properties_df(**kwargs)
     else:
-        properties_df = get_filtered_properties_df(prefix, prop=key, force=force)
+        properties_df = get_filtered_properties_df(prop=key, **kwargs)
     echo_df(properties_df)
 
 
-@lookup.command()
-@prefix_argument
-@verbose_option
-@force_option
-@click.option("-i", "--identifier")
-@version_option
-def alts(prefix: str, identifier: Optional[str], force: bool, version: Optional[str]):
+@lookup_annotate
+@identifier_option
+def alts(
+    identifier: str | None,
+    **kwargs: Unpack[LookupKwargs],
+) -> None:
     """Page through alt ids in a namespace."""
-    id_to_alts = get_id_to_alts(prefix, force=force, version=version)
-    if identifier is None:
-        click.echo_via_pager(
-            "\n".join(
-                f"{identifier}\t{alt}" for identifier, alts in id_to_alts.items() for alt in alts
-            )
-        )
-    else:
-        _alts = id_to_alts.get(identifier)
-        if _alts is None:
-            click.secho(f"No alternate identifiers for {identifier}", fg="red")
-        else:
-            click.echo("\n".join(_alts))
+    id_to_alts = get_id_to_alts(**kwargs)
+    _help_page_mapping(id_to_alts, identifier=identifier)
+
+
+@lookup_annotate
+def prefixes(**kwargs: Unpack[LookupKwargs]) -> None:
+    """Page through prefixes appearing in an ontology."""
+    ontology = get_ontology(**kwargs)
+    for prefix in sorted(ontology._get_prefixes(), key=str.casefold):
+        click.echo(prefix)

pyobo/cli/utils.py

@@ -2,6 +2,8 @@
 
 import datetime
 import pathlib
+from collections.abc import Callable
+from typing import TypeVar
 
 import click
 import pandas as pd
@@ -9,12 +11,14 @@ import pandas as pd
 from ..constants import DATABASE_DIRECTORY
 
 __all__ = [
-    "echo_df",
+    "Clickable",
     "directory_option",
-    "zenodo_option",
+    "echo_df",
     "force_option",
+    "force_process_option",
     "prefix_argument",
-    "no_strict_option",
+    "strict_option",
+    "zenodo_option",
 ]
 
 
@@ -37,12 +41,21 @@ directory_option = click.option(
     help=f"Build location. Defaults to {DATABASE_DIRECTORY}/<today>",
 )
 zenodo_option = click.option("--zenodo", is_flag=True, help="Automatically upload to zenodo")
-no_strict_option = click.option(
-    "-x", "--no-strict", is_flag=True, help="Turn off failure on bad CURIEs"
+strict_option = click.option(
+    "--strict/--no-strict",
+    default=False,
+    show_default=True,
+    help="Turn on or off failure on unparsable CURIEs",
 )
 prefix_argument = click.argument("prefix")
-force_option = click.option("-f", "--force", is_flag=True)
+force_option = click.option(
+    "-f", "--force", is_flag=True, help="Force re-downloading and re-processing"
+)
 version_option = click.option(
     "--version",
     help="Explicit version of the data. If not given, the most recent will be looked up.",
 )
+force_process_option = click.option(
+    "--force-process", is_flag=True, help="Force re-processing, but not necessarily re-downloading"
+)
+Clickable = TypeVar("Clickable", bound=Callable)

pyobo/constants.py

@@ -1,13 +1,16 @@
 """Constants for PyOBO."""
 
+from __future__ import annotations
+
 import logging
 import re
 
 import pystow
+from typing_extensions import NotRequired, TypedDict
 
 __all__ = [
-    "RAW_DIRECTORY",
     "DATABASE_DIRECTORY",
+    "RAW_DIRECTORY",
     "SPECIES_REMAPPING",
 ]
 
@@ -19,6 +22,15 @@ RAW_DIRECTORY = RAW_MODULE.base
 DATABASE_MODULE = PYOBO_MODULE.module("database")
 DATABASE_DIRECTORY = DATABASE_MODULE.base
 
+#: The directory inside an ontology cache where
+#: large artifacts like OBO, OWL, JSON, etc. go
+BUILD_SUBDIRECTORY_NAME = "build"
+#: The directory inside an ontology cache where
+#: small caches for alts, xrefs, names, etc. go
+CACHE_SUBDIRECTORY_NAME = "cache"
+#: the directory for caching relations
+RELATION_SUBDIRECTORY_NAME = "relations"
+
 SPECIES_REMAPPING = {
     "Canis familiaris": "Canis lupus familiaris",
 }
@@ -29,7 +41,6 @@ GLOBAL_SKIP = {
     "resid",  # deprecated
     "adw",  # deprecated
 }
-GLOBAL_CHECK_IDS = False
 
 #: Default prefix
 DEFAULT_PREFIX = "debio"
@@ -79,7 +90,7 @@ TYPEDEFS_FILE = "typedefs.tsv.gz"
 SPECIES_RECORD = "5334738"
 SPECIES_FILE = "species.tsv.gz"
 
-NCBITAXON_PREFIX = "NCBITaxon"
+NCBITAXON_PREFIX = "ncbitaxon"
 DATE_FORMAT = "%d:%m:%Y %H:%M"
 PROVENANCE_PREFIXES = {
     "pubmed",
@@ -97,3 +108,91 @@ PROVENANCE_PREFIXES = {
     "isbn",
     "issn",
 }
+
+
+class DatabaseKwargs(TypedDict):
+    """Keyword arguments for database CLI functions."""
+
+    strict: bool
+    force: bool
+    force_process: bool
+    skip_pyobo: bool
+    skip_below: str | None
+    skip_set: set[str] | None
+    use_tqdm: bool
+
+
+class SlimGetOntologyKwargs(TypedDict):
+    """Keyword arguments for database CLI functions.
+
+    These arguments are global during iteration over _all_ ontologies, whereas the
+    additional ``version`` is added in the subclass below for specific instances when
+    only a single ontology is requested.
+    """
+
+    strict: NotRequired[bool]
+    force: NotRequired[bool]
+    force_process: NotRequired[bool]
+
+
+class GetOntologyKwargs(SlimGetOntologyKwargs):
+    """Represents the optional keyword arguments passed to :func:`pyobo.get_ontology`.
+
+    This dictionary doesn't contain ``prefix`` since this is always explicitly handled.
+    """
+
+    version: NotRequired[str | None]
+    cache: NotRequired[bool]
+    use_tqdm: NotRequired[bool]
+
+
+def check_should_force(data: GetOntologyKwargs) -> bool:
+    """Determine whether caching should be forced based on generic keyword arguments."""
+    # note that this could be applied to the superclass of GetOntologyKwargs
+    # but this function should only be used in the scope where GetOntologyKwargs
+    # is appropriate.
+    return data.get("force", False) or data.get("force_process", False)
+
+
+def check_should_cache(data: GetOntologyKwargs) -> bool:
+    """Determine whether caching should be done based on generic keyword arguments."""
+    return data.get("cache", True)
+
+
+def check_should_use_tqdm(data: GetOntologyKwargs) -> bool:
+    """Determine whether caching should be done based on generic keyword arguments."""
+    return data.get("use_tqdm", True)
+
+
+class LookupKwargs(GetOntologyKwargs):
+    """Represents all arguments passed to :func:`pyobo.get_ontology`.
+
+    This dictionary does contain the ``prefix`` since it's used in the scope of CLI
+    functions.
+    """
+
+    prefix: str
+
+
+class IterHelperHelperDict(SlimGetOntologyKwargs):
+    """Represents arguments needed when iterating over all ontologies.
+
+    The explicitly defind arguments in this typed dict are used for the loop function
+    :func:`iter_helper_helper` and the rest that are inherited get passed to
+    :func:`pyobo.get_ontology` in each iteration.
+    """
+
+    use_tqdm: bool
+    skip_below: str | None
+    skip_pyobo: bool
+    skip_set: set[str] | None
+
+
+#: from table 2 of the Functional OWL syntax definition
+#: at https://www.w3.org/TR/owl2-syntax/#IRIs
+DEFAULT_PREFIX_MAP = {
+    "rdfs": "http://www.w3.org/2000/01/rdf-schema#",
+    "rdf": "http://www.w3.org/1999/02/22-rdf-syntax-ns#",
+    "xsd": "http://www.w3.org/2001/XMLSchema#",
+    "owl": "http://www.w3.org/2002/07/owl#",
+}