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

pyobo/struct/functional/utils.py

@@ -0,0 +1,112 @@
+"""Utilities for functional OWL."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Iterable
+
+import curies
+import rdflib
+from curies import Converter, Reference
+from rdflib import OWL, RDF, Graph, term
+
+from pyobo.constants import DEFAULT_PREFIX_MAP
+
+__all__ = [
+    "EXAMPLE_PREFIX_MAP",
+    "FunctionalOWLSerializable",
+    "RDFNodeSerializable",
+    "get_rdf_graph",
+]
+
+
+EXAMPLE_PREFIX_MAP = {
+    **DEFAULT_PREFIX_MAP,
+    "oboInOwl": "http://www.geneontology.org/formats/oboInOwl#",
+    "dcterms": "http://purl.org/dc/terms/",
+    "obo": "http://purl.obolibrary.org/obo/",
+    "OMO": "http://purl.obolibrary.org/obo/OMO_",
+    "sssom": "https://w3id.org/sssom/",
+    "semapv": "https://w3id.org/semapv/vocab/",
+    "skos": "http://www.w3.org/2004/02/skos/core#",
+    #
+    "a": "https://example.org/a:",
+    "orcid": "https://orcid.org",
+    "ZFA": "http://purl.obolibrary.org/obo/ZFA_",
+    "CL": "http://purl.obolibrary.org/obo/CL_",
+    "BFO": "http://purl.obolibrary.org/obo/BFO_",
+    "NCBITaxon": "http://purl.obolibrary.org/obo/NCBITaxon_",
+}
+
+
+class FunctionalOWLSerializable(ABC):
+    """An object that can be serialized to functional OWL."""
+
+    def to_funowl(self) -> str:
+        """Make functional OWL."""
+        tag = self.__class__.__name__
+        return f"{tag}({self.to_funowl_args()})"
+
+    @abstractmethod
+    def to_funowl_args(self) -> str:
+        """Make a string representing the positional arguments inside a box."""
+
+
+class RDFNodeSerializable(ABC):
+    """An object that can be serialized to RDF as a node."""
+
+    @abstractmethod
+    def to_rdflib_node(self, graph: Graph, converter: Converter):
+        """Make RDF."""
+
+    def to_ttl(self, prefix_map: dict[str, str], *, output_prefixes: bool = False) -> str:
+        """Output terse Turtle statements."""
+        return serialize_turtle([self], output_prefixes=output_prefixes, prefix_map=prefix_map)
+
+
+EXAMPLE_ONTOLOGY_IRI = "https://example.org/example.ofn"
+
+
+def get_rdf_graph(
+    axioms: Iterable[RDFNodeSerializable], prefix_map: dict[str, str]
+) -> rdflib.Graph:
+    """Serialize axioms as an RDF graph."""
+    graph = Graph()
+    graph.add((term.URIRef(EXAMPLE_ONTOLOGY_IRI), RDF.type, OWL.Ontology))
+    # chain these together so you don't have to worry about
+    # default namespaces like owl
+    converter = curies.chain(
+        [
+            Converter.from_rdflib(graph),
+            Converter.from_prefix_map(prefix_map),
+        ]
+    )
+    for prefix, uri_prefix in converter.bimap.items():
+        graph.namespace_manager.bind(prefix, uri_prefix)
+    for axiom in axioms:
+        axiom.to_rdflib_node(graph, converter)
+    return graph
+
+
+def serialize_turtle(
+    axioms: Iterable[RDFNodeSerializable],
+    *,
+    output_prefixes: bool = False,
+    prefix_map: dict[str, str],
+) -> str:
+    """Serialize axioms as turtle."""
+    graph = get_rdf_graph(axioms, prefix_map=prefix_map)
+    rv = graph.serialize()
+    if output_prefixes:
+        return rv.strip()
+    return "\n".join(line for line in rv.splitlines() if not line.startswith("@prefix")).strip()
+
+
+def list_to_funowl(
+    elements: Iterable[FunctionalOWLSerializable | Reference], *, sep: str = " "
+) -> str:
+    """Serialize a list of objects as functional OWL, separated by space or other givne separator."""
+    return sep.join(
+        element.to_funowl() if isinstance(element, FunctionalOWLSerializable) else element.curie
+        for element in elements
+    )

pyobo/struct/reference.py

@@ -1,140 +1,76 @@
 """Data structures for OBO."""
 
-from typing import Optional
+from __future__ import annotations
+
+import datetime
+import logging
+from collections import Counter
+from collections.abc import Iterable, Sequence
+from typing import Any, NamedTuple
 
 import bioregistry
 import curies
-from curies.api import ExpansionError
-from pydantic import Field, field_validator, model_validator
-
-from .utils import obo_escape
-from ..constants import GLOBAL_CHECK_IDS
-from ..identifier_utils import normalize_curie
+import dateutil.parser
+import pytz
+from bioregistry import NormalizedNamableReference as Reference
+from curies import ReferenceTuple
+from curies.preprocessing import BlocklistError
+
+from ..identifier_utils import (
+    NotCURIEError,
+    ParseError,
+    UnparsableIRIError,
+    _is_valid_identifier,
+    _parse_str_or_curie_or_uri_helper,
+)
 
 __all__ = [
-    "Reference",
     "Referenced",
+    "default_reference",
+    "get_preferred_curie",
+    "multi_reference_escape",
+    "reference_escape",
+    "unspecified_matching",
 ]
 
-
-class Reference(curies.Reference):
-    """A namespace, identifier, and label."""
-
-    name: Optional[str] = Field(default=None, description="the name of the reference")
-
-    @field_validator("prefix")
-    def validate_prefix(cls, v):  # noqa
-        """Validate the prefix for this reference."""
-        norm_prefix = bioregistry.normalize_prefix(v)
-        if norm_prefix is None:
-            raise ExpansionError(f"Unknown prefix: {v}")
-        return norm_prefix
-
-    @property
-    def preferred_prefix(self) -> str:
-        """Get the preferred curie for this reference."""
-        return bioregistry.get_preferred_prefix(self.prefix) or self.prefix
-
-    @property
-    def preferred_curie(self) -> str:
-        """Get the preferred curie for this reference."""
-        return f"{self.preferred_prefix}:{self.identifier}"
-
-    @model_validator(mode="before")
-    def validate_identifier(cls, values):  # noqa
-        """Validate the identifier."""
-        prefix, identifier = values.get("prefix"), values.get("identifier")
-        if not prefix or not identifier:
-            return values
-        resource = bioregistry.get_resource(prefix)
-        if resource is None:
-            raise ExpansionError(f"Unknown prefix: {prefix}")
-        values["prefix"] = resource.prefix
-        values["identifier"] = resource.standardize_identifier(identifier)
-        if GLOBAL_CHECK_IDS and not resource.is_valid_identifier(values["identifier"]):
-            raise ValueError(f"non-standard identifier: {resource.prefix}:{values['identifier']}")
-        return values
-
-    @classmethod
-    def auto(cls, prefix: str, identifier: str) -> "Reference":
-        """Create a reference and autopopulate its name."""
-        from ..api import get_name
-
-        name = get_name(prefix, identifier)
-        return cls.model_validate({"prefix": prefix, "identifier": identifier, "name": name})
-
-    @property
-    def bioregistry_link(self) -> str:
-        """Get the bioregistry link."""
-        return f"https://bioregistry.io/{self.curie}"
-
-    @classmethod
-    def from_curie(
-        cls,
-        curie: str,
-        name: Optional[str] = None,
-        *,
-        strict: bool = True,
-        auto: bool = False,
-    ) -> Optional["Reference"]:
-        """Get a reference from a CURIE.
-
-        :param curie: The compact URI (CURIE) to parse in the form of `<prefix>:<identifier>`
-        :param name: The name associated with the CURIE
-        :param strict: If true, raises an error if the CURIE can not be parsed.
-        :param auto: Automatically look up name
-        """
-        prefix, identifier = normalize_curie(curie, strict=strict)
-        return cls._materialize(prefix=prefix, identifier=identifier, name=name, auto=auto)
-
-    @classmethod
-    def from_iri(
-        cls,
-        iri: str,
-        name: Optional[str] = None,
-        *,
-        auto: bool = False,
-    ) -> Optional["Reference"]:
-        """Get a reference from an IRI using the Bioregistry.
-
-        :param iri: The IRI to parse
-        :param name: The name associated with the CURIE
-        :param auto: Automatically look up name
-        """
-        prefix, identifier = bioregistry.parse_iri(iri)
-        return cls._materialize(prefix=prefix, identifier=identifier, name=name, auto=auto)
-
-    @classmethod
-    def _materialize(
-        cls,
-        prefix: Optional[str],
-        identifier: Optional[str],
-        name: Optional[str] = None,
-        *,
-        auto: bool = False,
-    ) -> Optional["Reference"]:
-        if prefix is None or identifier is None:
+logger = logging.getLogger(__name__)
+
+
+def _parse_str_or_curie_or_uri(
+    str_curie_or_uri: str,
+    name: str | None = None,
+    *,
+    strict: bool = False,
+    ontology_prefix: str | None = None,
+    node: Reference | None = None,
+    predicate: Reference | None = None,
+    line: str | None = None,
+    context: str | None = None,
+    upgrade: bool = False,
+) -> Reference | None:
+    reference = _parse_str_or_curie_or_uri_helper(
+        str_curie_or_uri,
+        ontology_prefix=ontology_prefix,
+        name=name,
+        node=node,
+        predicate=predicate,
+        line=line,
+        context=context,
+        upgrade=upgrade,
+    )
+
+    match reference:
+        case Reference():
+            return reference
+        case BlocklistError():
             return None
-        if name is None and auto:
-            return cls.auto(prefix=prefix, identifier=identifier)
-        return cls.model_validate({"prefix": prefix, "identifier": identifier, "name": name})
-
-    @property
-    def _escaped_identifier(self):
-        return obo_escape(self.identifier)
-
-    def __str__(self):
-        identifier_lower = self.identifier.lower()
-        if identifier_lower.startswith(f"{self.prefix.lower()}:"):
-            rv = identifier_lower
-        else:
-            rv = f"{self.preferred_prefix}:{self._escaped_identifier}"
-        if self.name:
-            rv = f"{rv} ! {self.name}"
-        return rv
-
-    def __hash__(self):
-        return hash((self.__class__, self.prefix, self.identifier))
+        case ParseError():
+            if strict:
+                raise reference
+            else:
+                return None
+        case _:
+            raise TypeError(f"Got invalid: ({type(reference)}) {reference}")
 
 
 class Referenced:
@@ -142,6 +78,19 @@ class Referenced:
 
     reference: Reference
 
+    def __hash__(self) -> int:
+        return self.reference.__hash__()
+
+    def __eq__(self, other: Any) -> bool:
+        if isinstance(other, curies.Reference | Referenced):
+            return self.prefix == other.prefix and self.identifier == other.identifier
+        raise TypeError
+
+    def __lt__(self, other: Referenced) -> bool:
+        if not isinstance(other, curies.Reference | Referenced):
+            raise TypeError
+        return self.reference < other.reference
+
     @property
     def prefix(self):
         """The prefix of the typedef."""
@@ -163,16 +112,262 @@ class Referenced:
         return self.reference.curie
 
     @property
-    def preferred_curie(self) -> str:
-        """The preferred CURIE for this typedef."""
-        return self.reference.preferred_curie
-
-    @property
-    def pair(self) -> tuple[str, str]:
+    def pair(self) -> ReferenceTuple:
         """The pair of namespace/identifier."""
         return self.reference.pair
 
-    @property
-    def bioregistry_link(self) -> str:
-        """Get the bioregistry link."""
-        return self.reference.bioregistry_link
+
+def get_preferred_prefix(
+    ref: curies.Reference | Reference | Referenced,
+) -> str:
+    """Get the preferred prefix from a variety of types."""
+    match ref:
+        case Referenced() | Reference():
+            return bioregistry.get_preferred_prefix(ref.prefix) or ref.prefix
+        case curies.Reference():
+            return ref.prefix
+
+
+def get_preferred_curie(
+    ref: curies.Reference | Reference | Referenced,
+) -> str:
+    """Get the preferred CURIE from a variety of types."""
+    match ref:
+        case Referenced() | Reference():
+            return f"{get_preferred_prefix(ref)}:{ref.identifier}"
+        case curies.Reference():
+            return ref.curie
+
+
+def default_reference(prefix: str, identifier: str, name: str | None = None) -> Reference:
+    """Create a CURIE for an "unqualified" reference.
+
+    :param prefix: The prefix of the ontology in which the "unqualified" reference is made
+    :param identifier: The "unqualified" reference. For example, if you just write
+        "located_in" somewhere there is supposed to be a CURIE
+    :returns: A CURIE for the "unqualified" reference based on the OBO semantic space
+
+    >>> default_reference("chebi", "conjugate_base_of")
+    Reference(prefix="obo", identifier="chebi#conjugate_base_of", name=None)
+    """
+    if not identifier.strip():
+        raise ValueError("default identifier is empty")
+    return Reference(prefix="obo", identifier=f"{prefix}#{identifier}", name=name)
+
+
+def _get_ref_name(reference: curies.Reference | Referenced) -> str | None:
+    if isinstance(reference, curies.NamableReference | Referenced):
+        return reference.name
+    return None
+
+
+def reference_escape(
+    reference: curies.Reference | Referenced,
+    *,
+    ontology_prefix: str,
+    add_name_comment: bool = False,
+) -> str:
+    """Write a reference with default namespace removed."""
+    if reference.prefix == "obo" and reference.identifier.startswith(f"{ontology_prefix}#"):
+        return reference.identifier.removeprefix(f"{ontology_prefix}#")
+    rv = get_preferred_curie(reference)
+    if add_name_comment and (name := _get_ref_name(reference)):
+        rv += f" ! {name}"
+    return rv
+
+
+def multi_reference_escape(
+    references: Sequence[Reference | Referenced],
+    *,
+    ontology_prefix: str,
+    add_name_comment: bool = False,
+) -> str:
+    """Write multiple references with default namespace normalized."""
+    rv = " ".join(
+        reference_escape(r, ontology_prefix=ontology_prefix, add_name_comment=False)
+        for r in references
+    )
+    names = [r.name or "" for r in references]
+    if add_name_comment and all(names):
+        rv += " ! " + " ".join(names)
+    return rv
+
+
+def comma_separate_references(elements: Iterable[Reference | OBOLiteral]) -> str:
+    """Map a list to strings and make comma separated."""
+    return ", ".join(reference_or_literal_to_str(element) for element in elements)
+
+
+def _obo_parse_identifier(
+    str_or_curie_or_uri: str,
+    *,
+    ontology_prefix: str,
+    strict: bool = False,
+    node: Reference | None = None,
+    predicate: Reference | None = None,
+    line: str | None = None,
+    context: str | None = None,
+    name: str | None = None,
+    upgrade: bool = True,
+    counter: Counter[tuple[str, str]] | None = None,
+) -> Reference | None:
+    """Parse from a CURIE, URI, or default string in the ontology prefix's IDspace using OBO semantics."""
+    match _parse_str_or_curie_or_uri_helper(
+        str_or_curie_or_uri,
+        ontology_prefix=ontology_prefix,
+        node=node,
+        predicate=predicate,
+        line=line,
+        context=context,
+        name=name,
+        upgrade=upgrade,
+    ):
+        case Reference() as reference:
+            return reference
+        case BlocklistError():
+            return None
+        case NotCURIEError() as exc:
+            # this means there's no colon `:`
+            if _is_valid_identifier(str_or_curie_or_uri):
+                return default_reference(prefix=ontology_prefix, identifier=str_or_curie_or_uri)
+            elif strict:
+                raise exc
+            else:
+                return None
+        case ParseError() as exc:
+            if strict:
+                raise exc
+            if counter is None:
+                logger.warning(str(exc))
+            else:
+                if not counter[ontology_prefix, str_or_curie_or_uri]:
+                    logger.warning(str(exc))
+                counter[ontology_prefix, str_or_curie_or_uri] += 1
+            return None
+
+
+def _parse_reference_or_uri_literal(
+    str_or_curie_or_uri: str,
+    *,
+    ontology_prefix: str,
+    strict: bool = False,
+    node: Reference,
+    predicate: Reference | None = None,
+    line: str,
+    context: str,
+    name: str | None = None,
+    upgrade: bool = True,
+    #
+    counter: Counter[tuple[str, str]] | None = None,
+) -> None | Reference | OBOLiteral:
+    match _parse_str_or_curie_or_uri_helper(
+        str_or_curie_or_uri,
+        node=node,
+        predicate=predicate,
+        ontology_prefix=ontology_prefix,
+        line=line,
+        context=context,
+        name=name,
+        upgrade=upgrade,
+    ):
+        case Reference() as reference:
+            return reference
+        case BlocklistError():
+            return None
+        case UnparsableIRIError():
+            # this means that it's defininitely a URI,
+            # but it couldn't be parsed with Bioregistry
+            return OBOLiteral.uri(str_or_curie_or_uri)
+        case NotCURIEError() as exc:
+            # this means there's no colon `:`
+            if _is_valid_identifier(str_or_curie_or_uri):
+                return default_reference(prefix=ontology_prefix, identifier=str_or_curie_or_uri)
+            elif strict:
+                raise exc
+            else:
+                return None
+        case ParseError() as exc:
+            if strict:
+                raise exc
+            if counter is None:
+                logger.warning(str(exc))
+            else:
+                if not counter[ontology_prefix, str_or_curie_or_uri]:
+                    logger.warning(str(exc))
+                counter[ontology_prefix, str_or_curie_or_uri] += 1
+            return None
+
+
+unspecified_matching = Reference(
+    prefix="semapv", identifier="UnspecifiedMatching", name="unspecified matching process"
+)
+
+
+class OBOLiteral(NamedTuple):
+    """A tuple representing a property with a literal value."""
+
+    value: str
+    datatype: curies.Reference
+    language: str | None
+
+    @classmethod
+    def string(cls, value: str, *, language: str | None = None) -> OBOLiteral:
+        """Get a string literal."""
+        return cls(value, curies.Reference(prefix="xsd", identifier="string"), language)
+
+    @classmethod
+    def boolean(cls, value: bool) -> OBOLiteral:
+        """Get a boolean literal."""
+        return cls(str(value).lower(), curies.Reference(prefix="xsd", identifier="boolean"), None)
+
+    @classmethod
+    def decimal(cls, value) -> OBOLiteral:
+        """Get a decimal literal."""
+        return cls(str(value), curies.Reference(prefix="xsd", identifier="decimal"), None)
+
+    @classmethod
+    def float(cls, value) -> OBOLiteral:
+        """Get a float literal."""
+        return cls(str(value), curies.Reference(prefix="xsd", identifier="float"), None)
+
+    @classmethod
+    def integer(cls, value: int | str) -> OBOLiteral:
+        """Get a integer literal."""
+        return cls(str(int(value)), curies.Reference(prefix="xsd", identifier="integer"), None)
+
+    @classmethod
+    def year(cls, value: int | str) -> OBOLiteral:
+        """Get a year (gYear) literal."""
+        return cls(str(int(value)), curies.Reference(prefix="xsd", identifier="gYear"), None)
+
+    @classmethod
+    def uri(cls, uri: str) -> OBOLiteral:
+        """Get a string literal for a URI."""
+        return cls(uri, curies.Reference(prefix="xsd", identifier="anyURI"), None)
+
+    @classmethod
+    def datetime(cls, dt: datetime.datetime | str) -> OBOLiteral:
+        """Get a datetime literal."""
+        if isinstance(dt, str):
+            dt = _parse_datetime(dt)
+        return cls(dt.isoformat(), curies.Reference(prefix="xsd", identifier="dateTime"), None)
+
+
+def _parse_datetime(dd: str) -> datetime.datetime:
+    xx = dateutil.parser.parse(dd)
+    xx = xx.astimezone(pytz.UTC)
+    return xx
+
+
+def _reference_list_tag(
+    tag: str, references: Iterable[Reference], ontology_prefix: str
+) -> Iterable[str]:
+    for reference in references:
+        yield f"{tag}: {reference_escape(reference, ontology_prefix=ontology_prefix, add_name_comment=True)}"
+
+
+def reference_or_literal_to_str(x: OBOLiteral | curies.Reference | Reference | Referenced) -> str:
+    """Get a string from a reference or literal."""
+    if isinstance(x, OBOLiteral):
+        return x.value
+    return get_preferred_curie(x)