Skip to content

ontocast.onto.prefixes

One prefix per namespace: the rule every prompt, parse and export follows.

A namespace is shown under exactly one prefix, chosen by the first rule that applies and leaves the prefix free:

  1. a well-known namespace keeps its standard prefix (unit:, sosa:);
  2. a catalog ontology's own namespace takes its author's declared prefix, when that prefix is valid -- not a standard prefix of another namespace, not a library id;
  3. else the ontology's id;
  4. a namespace no catalog ontology owns takes the prefix its users bind most;
  5. else a slug of the namespace.

Every other prefix seen bound to a namespace is an alias: accepted when the model writes it and rewritten where authored prose uses it, never shown. Ids may repeat across ontologies; shown prefixes never do, so a shown prefix is the one short handle that names a single ontology.

Attributes

CURIE_IN_TEXT = re.compile('(?<![\\w:/#<.-])([A-Za-z][\\w.-]*):([A-Za-z_](?:[\\w.-]*[\\w-])?)') module-attribute

NOTE_PREDICATES = (SKOS.scopeNote, SKOS.definition, RDFS.comment) module-attribute

__all__ = ['PrefixTable', 'bind_own_namespace', 'build_prefix_table', 'standard_namespace_prefixes', 'standard_prefix_for', 'valid_shown_prefix'] module-attribute

Classes

PrefixTable

The shown prefix of each namespace, and the aliases accepted for it.

Build it with :func:build_prefix_table. Standard namespaces need no entry: :meth:prefix_for falls back to their standard prefix.

Source code in ontocast/onto/prefixes.py
class PrefixTable:
    """The shown prefix of each namespace, and the aliases accepted for it.

    Build it with :func:`build_prefix_table`. Standard namespaces need no
    entry: :meth:`prefix_for` falls back to their standard prefix.
    """

    def __init__(self, shown: Mapping[str, str], aliases: Mapping[str, str]) -> None:
        self.shown: dict[str, str] = dict(shown)
        self.aliases: dict[str, str] = dict(aliases)
        known = {**standard_namespace_prefixes(), **self.shown}
        # Longest namespace first, so a namespace nested in another wins.
        self._by_length = sorted(known.items(), key=lambda item: -len(item[0]))

    def prefix_for(self, namespace: str) -> str | None:
        """The prefix shown for ``namespace``, if it has one."""
        namespace = str(namespace)
        return self.shown.get(namespace) or standard_prefix_for(namespace)

    def namespace_for(self, prefix: str) -> str | None:
        """The namespace a shown prefix or an alias stands for."""
        return self.parse_map().get(prefix)

    def qname(self, iri: str) -> str:
        """``iri`` as ``prefix:local`` under the shown prefixes, else as is."""
        text = str(iri)
        for namespace, prefix in self._by_length:
            if text.startswith(namespace):
                local = text[len(namespace) :]
                if local and re.fullmatch(r"[A-Za-z0-9_][\w.-]*", local):
                    return f"{prefix}:{local}"
        return text

    def prefix_or_claim(self, namespace: str, candidate: str) -> str:
        """The shown prefix of ``namespace``, else ``candidate`` as the table
        would claim it: numbered when another namespace holds it.

        For an ontology the catalog does not hold yet, such as a home being
        minted.
        """
        shown = self.prefix_for(namespace)
        if shown is not None:
            return shown
        taken = set(self.parse_map()) | set(STANDARD_PREFIX_NAMESPACES)
        taken |= LIBRARY_ONTOLOGY_IDS
        if candidate not in taken:
            return candidate
        number = 2
        while f"{candidate}{number}" in taken:
            number += 1
        return f"{candidate}{number}"

    def parse_map(self) -> dict[str, str]:
        """Prefix -> namespace for every shown prefix and every alias."""
        result = {prefix: namespace for namespace, prefix in self._by_length if prefix}
        for prefix, namespace in self.aliases.items():
            result.setdefault(prefix, namespace)
        return result

    def _namespace_of(self, iri: str, cache: dict[str, str | None]) -> str | None:
        cut = max(iri.rfind("#"), iri.rfind("/")) + 1
        stem = iri[:cut]
        if stem not in cache:
            cache[stem] = next(
                (ns for ns, _ in self._by_length if stem.startswith(ns)), None
            )
        return cache[stem]

    def bind(self, graph: Graph) -> None:
        """Bind the shown prefix of every namespace ``graph`` binds or uses."""
        namespaces = {str(bound) for prefix, bound in graph.namespaces() if prefix}
        cache: dict[str, str | None] = {}
        for triple in graph:
            for term in triple:
                if isinstance(term, URIRef):
                    namespace = self._namespace_of(str(term), cache)
                    if namespace is not None:
                        namespaces.add(namespace)
        for namespace in sorted(namespaces):
            prefix = self.prefix_for(namespace)
            if prefix is not None and _bound_prefix(graph, namespace) != prefix:
                _bind(graph, prefix, namespace)

    def rewrite_curies(
        self, text: str, source_bindings: Mapping[str, str] | None = None
    ) -> str:
        """Show every CURIE in ``text`` under its namespace's shown prefix.

        A token ``prefix:Local`` is rewritten only when ``source_bindings``
        (the bindings of the graph the text comes from) or an unambiguous
        alias maps its prefix to a namespace shown under another prefix. Any
        other text, unknown prefixes included, is left as it is.
        """
        lookup = {**self.aliases, **(source_bindings or {})}

        def replace(match: re.Match[str]) -> str:
            prefix, local = match.group(1), match.group(2)
            namespace = lookup.get(prefix)
            shown = self.prefix_for(namespace) if namespace is not None else None
            if shown is None or shown == prefix:
                return match.group(0)
            return f"{shown}:{local}"

        return CURIE_IN_TEXT.sub(replace, text)

    def normalize(self, graph: Graph) -> None:
        """Make ``graph`` read under this table, in place.

        Binds the shown prefixes and rewrites the CURIEs in its note text, so
        a prompt rendered from it shows one prefix per namespace. Use it on a
        prompt's copy of a context graph, never on a stored ontology.
        """
        source = {
            prefix: str(namespace) for prefix, namespace in graph.namespaces() if prefix
        }
        self.bind(graph)
        for predicate in _PROSE_PREDICATES:
            for subject, obj in list(graph.subject_objects(predicate)):
                if not isinstance(obj, Literal):
                    continue
                rewritten = self.rewrite_curies(str(obj), source)
                if rewritten != str(obj):
                    graph.remove((subject, predicate, obj))
                    graph.add(
                        (
                            subject,
                            predicate,
                            Literal(
                                rewritten, lang=obj.language, datatype=obj.datatype
                            ),
                        )
                    )

Attributes

aliases = dict(aliases) instance-attribute
shown = dict(shown) instance-attribute

Methods:

__init__(shown, aliases)
Source code in ontocast/onto/prefixes.py
def __init__(self, shown: Mapping[str, str], aliases: Mapping[str, str]) -> None:
    self.shown: dict[str, str] = dict(shown)
    self.aliases: dict[str, str] = dict(aliases)
    known = {**standard_namespace_prefixes(), **self.shown}
    # Longest namespace first, so a namespace nested in another wins.
    self._by_length = sorted(known.items(), key=lambda item: -len(item[0]))
bind(graph)

Bind the shown prefix of every namespace graph binds or uses.

Source code in ontocast/onto/prefixes.py
def bind(self, graph: Graph) -> None:
    """Bind the shown prefix of every namespace ``graph`` binds or uses."""
    namespaces = {str(bound) for prefix, bound in graph.namespaces() if prefix}
    cache: dict[str, str | None] = {}
    for triple in graph:
        for term in triple:
            if isinstance(term, URIRef):
                namespace = self._namespace_of(str(term), cache)
                if namespace is not None:
                    namespaces.add(namespace)
    for namespace in sorted(namespaces):
        prefix = self.prefix_for(namespace)
        if prefix is not None and _bound_prefix(graph, namespace) != prefix:
            _bind(graph, prefix, namespace)
namespace_for(prefix)

The namespace a shown prefix or an alias stands for.

Source code in ontocast/onto/prefixes.py
def namespace_for(self, prefix: str) -> str | None:
    """The namespace a shown prefix or an alias stands for."""
    return self.parse_map().get(prefix)
normalize(graph)

Make graph read under this table, in place.

Binds the shown prefixes and rewrites the CURIEs in its note text, so a prompt rendered from it shows one prefix per namespace. Use it on a prompt's copy of a context graph, never on a stored ontology.

Source code in ontocast/onto/prefixes.py
def normalize(self, graph: Graph) -> None:
    """Make ``graph`` read under this table, in place.

    Binds the shown prefixes and rewrites the CURIEs in its note text, so
    a prompt rendered from it shows one prefix per namespace. Use it on a
    prompt's copy of a context graph, never on a stored ontology.
    """
    source = {
        prefix: str(namespace) for prefix, namespace in graph.namespaces() if prefix
    }
    self.bind(graph)
    for predicate in _PROSE_PREDICATES:
        for subject, obj in list(graph.subject_objects(predicate)):
            if not isinstance(obj, Literal):
                continue
            rewritten = self.rewrite_curies(str(obj), source)
            if rewritten != str(obj):
                graph.remove((subject, predicate, obj))
                graph.add(
                    (
                        subject,
                        predicate,
                        Literal(
                            rewritten, lang=obj.language, datatype=obj.datatype
                        ),
                    )
                )
parse_map()

Prefix -> namespace for every shown prefix and every alias.

Source code in ontocast/onto/prefixes.py
def parse_map(self) -> dict[str, str]:
    """Prefix -> namespace for every shown prefix and every alias."""
    result = {prefix: namespace for namespace, prefix in self._by_length if prefix}
    for prefix, namespace in self.aliases.items():
        result.setdefault(prefix, namespace)
    return result
prefix_for(namespace)

The prefix shown for namespace, if it has one.

Source code in ontocast/onto/prefixes.py
def prefix_for(self, namespace: str) -> str | None:
    """The prefix shown for ``namespace``, if it has one."""
    namespace = str(namespace)
    return self.shown.get(namespace) or standard_prefix_for(namespace)
prefix_or_claim(namespace, candidate)

The shown prefix of namespace, else candidate as the table would claim it: numbered when another namespace holds it.

For an ontology the catalog does not hold yet, such as a home being minted.

Source code in ontocast/onto/prefixes.py
def prefix_or_claim(self, namespace: str, candidate: str) -> str:
    """The shown prefix of ``namespace``, else ``candidate`` as the table
    would claim it: numbered when another namespace holds it.

    For an ontology the catalog does not hold yet, such as a home being
    minted.
    """
    shown = self.prefix_for(namespace)
    if shown is not None:
        return shown
    taken = set(self.parse_map()) | set(STANDARD_PREFIX_NAMESPACES)
    taken |= LIBRARY_ONTOLOGY_IDS
    if candidate not in taken:
        return candidate
    number = 2
    while f"{candidate}{number}" in taken:
        number += 1
    return f"{candidate}{number}"
qname(iri)

iri as prefix:local under the shown prefixes, else as is.

Source code in ontocast/onto/prefixes.py
def qname(self, iri: str) -> str:
    """``iri`` as ``prefix:local`` under the shown prefixes, else as is."""
    text = str(iri)
    for namespace, prefix in self._by_length:
        if text.startswith(namespace):
            local = text[len(namespace) :]
            if local and re.fullmatch(r"[A-Za-z0-9_][\w.-]*", local):
                return f"{prefix}:{local}"
    return text
rewrite_curies(text, source_bindings=None)

Show every CURIE in text under its namespace's shown prefix.

A token prefix:Local is rewritten only when source_bindings (the bindings of the graph the text comes from) or an unambiguous alias maps its prefix to a namespace shown under another prefix. Any other text, unknown prefixes included, is left as it is.

Source code in ontocast/onto/prefixes.py
def rewrite_curies(
    self, text: str, source_bindings: Mapping[str, str] | None = None
) -> str:
    """Show every CURIE in ``text`` under its namespace's shown prefix.

    A token ``prefix:Local`` is rewritten only when ``source_bindings``
    (the bindings of the graph the text comes from) or an unambiguous
    alias maps its prefix to a namespace shown under another prefix. Any
    other text, unknown prefixes included, is left as it is.
    """
    lookup = {**self.aliases, **(source_bindings or {})}

    def replace(match: re.Match[str]) -> str:
        prefix, local = match.group(1), match.group(2)
        namespace = lookup.get(prefix)
        shown = self.prefix_for(namespace) if namespace is not None else None
        if shown is None or shown == prefix:
            return match.group(0)
        return f"{shown}:{local}"

    return CURIE_IN_TEXT.sub(replace, text)

Functions:

author_prefix_id(graph, namespace)

The prefix graph binds to namespace, when it is a valid ontology id.

Source code in ontocast/onto/prefixes.py
def author_prefix_id(graph: Graph, namespace: str) -> str | None:
    """The prefix ``graph`` binds to ``namespace``, when it is a valid ontology id."""
    prefix = _bound_prefix(graph, str(namespace)) if namespace else None
    if prefix is None or not valid_shown_prefix(prefix, namespace):
        return None
    try:
        return validate_ontology_id(prefix)
    except ValueError:
        return None

bind_own_namespace(graph, namespace, ontology_id)

Bind the shown prefix of an ontology's own namespace on its graph.

A standard namespace takes its standard prefix; else a valid prefix the graph already binds to it (the author's) is kept; else the id is bound.

Returns:

Type Description
str

The prefix now bound to namespace.

Source code in ontocast/onto/prefixes.py
def bind_own_namespace(graph: Graph, namespace: str, ontology_id: str) -> str:
    """Bind the shown prefix of an ontology's own namespace on its graph.

    A standard namespace takes its standard prefix; else a valid prefix the
    graph already binds to it (the author's) is kept; else the id is bound.

    Returns:
        The prefix now bound to ``namespace``.
    """
    namespace = str(namespace)
    standard = standard_prefix_for(namespace)
    if standard is not None:
        _bind(graph, standard, namespace)
        return standard
    existing = _bound_prefix(graph, namespace)
    if existing is not None and valid_shown_prefix(existing, namespace):
        return existing
    graph.namespace_manager.bind(ontology_id, Namespace(namespace), override=True)
    return _bound_prefix(graph, namespace) or ontology_id

build_prefix_table(ontologies, others=())

The prefix table of a catalog.

Parameters:

Name Type Description Default
ontologies Iterable[Ontology]

The catalog's head ontologies.

required
others Iterable[Graph]

Further graphs whose bindings name namespaces (the shapes).

()

Returns:

Type Description
PrefixTable

The table: rules 2-5 of the module docstring, in that order; rule 1

PrefixTable

holds through :meth:PrefixTable.prefix_for.

Source code in ontocast/onto/prefixes.py
def build_prefix_table(
    ontologies: Iterable[Ontology], others: Iterable[Graph] = ()
) -> PrefixTable:
    """The prefix table of a catalog.

    Args:
        ontologies: The catalog's head ontologies.
        others: Further graphs whose bindings name namespaces (the shapes).

    Returns:
        The table: rules 2-5 of the module docstring, in that order; rule 1
        holds through :meth:`PrefixTable.prefix_for`.
    """
    heads = sorted(
        (o for o in ontologies if not o.is_null() and o.namespace),
        key=lambda o: o.iri,
    )
    graphs: list[Graph] = [o.graph for o in heads] + list(others)
    seen: dict[str, Counter[str]] = {}
    for graph in graphs:
        for prefix, namespace in graph.namespaces():
            if prefix and not _GENERATED_PREFIX.match(prefix):
                seen.setdefault(str(namespace), Counter())[prefix] += 1

    standard = standard_namespace_prefixes()
    taken: set[str] = set(STANDARD_PREFIX_NAMESPACES) | set(standard.values())
    taken |= LIBRARY_ONTOLOGY_IDS
    shown: dict[str, str] = {}

    def claim(namespace: str, *candidates: str | None) -> None:
        for candidate in candidates:
            if (
                candidate
                and candidate not in taken
                and valid_shown_prefix(candidate, namespace)
            ):
                shown[namespace] = candidate
                taken.add(candidate)
                return
        base = next((c for c in candidates if c), None) or _slug(namespace)
        number = 2
        while f"{base}{number}" in taken:
            number += 1
        shown[namespace] = f"{base}{number}"
        taken.add(shown[namespace])

    owners: dict[str, Ontology] = {}
    for head in heads:
        owners.setdefault(str(head.namespace), head)
    for namespace, head in sorted(owners.items()):
        if namespace in standard:
            continue
        claim(namespace, head.prefix, head.ontology_id)
    for namespace in sorted(seen):
        if namespace in standard or namespace in shown:
            continue
        ranked = sorted(seen[namespace].items(), key=lambda item: (-item[1], item[0]))
        claim(namespace, *(prefix for prefix, _ in ranked), _slug(namespace))

    claims: dict[str, set[str]] = {}
    for namespace, counter in seen.items():
        for prefix in counter:
            claims.setdefault(prefix, set()).add(namespace)
    for namespace, head in owners.items():
        if head.ontology_id:
            claims.setdefault(head.ontology_id, set()).add(namespace)
    shown_prefixes = set(shown.values()) | set(standard.values())
    aliases = {
        prefix: next(iter(namespaces))
        for prefix, namespaces in claims.items()
        if len(namespaces) == 1 and prefix not in shown_prefixes
    }
    return PrefixTable(shown, aliases)

standard_namespace_prefixes() cached

Namespace IRI -> its standard prefix.

The well-known vocabularies first, then the library's prefix tables, then the remaining standard prefixes, the lexically first where a namespace has several.

Source code in ontocast/onto/prefixes.py
@cache
def standard_namespace_prefixes() -> dict[str, str]:
    """Namespace IRI -> its standard prefix.

    The well-known vocabularies first, then the library's prefix tables, then
    the remaining standard prefixes, the lexically first where a namespace has
    several.
    """
    found: dict[str, str] = {}
    for vocabulary in WELL_KNOWN_VOCABULARIES:
        for namespace in vocabulary.namespaces:
            found.setdefault(namespace, vocabulary.prefix)
    for prefix, namespace in prefix_lookup_for_ingest().items():
        found.setdefault(namespace, prefix)
    for prefix in sorted(STANDARD_PREFIX_NAMESPACES):
        for namespace in sorted(STANDARD_PREFIX_NAMESPACES[prefix]):
            found.setdefault(namespace, prefix)
    return found

standard_prefix_for(namespace)

The standard prefix of namespace, if it is a standard namespace.

Source code in ontocast/onto/prefixes.py
def standard_prefix_for(namespace: str) -> str | None:
    """The standard prefix of ``namespace``, if it is a standard namespace."""
    return standard_namespace_prefixes().get(str(namespace))

valid_shown_prefix(prefix, namespace)

Whether prefix may be shown for namespace.

It must be a prefix name, not one rdflib generated, not a library namespace's, and not the standard prefix of another namespace.

Source code in ontocast/onto/prefixes.py
def valid_shown_prefix(prefix: str, namespace: str) -> bool:
    """Whether ``prefix`` may be shown for ``namespace``.

    It must be a prefix name, not one rdflib generated, not a library
    namespace's, and not the standard prefix of another namespace.
    """
    if not prefix or not _PREFIX_NAME.match(prefix):
        return False
    if _GENERATED_PREFIX.match(prefix) or prefix in LIBRARY_ONTOLOGY_IDS:
        return False
    stem = prefix.rstrip("0123456789")
    if stem != prefix and stem in STANDARD_PREFIX_NAMESPACES:
        # rdflib's rename of a clashing standard prefix (``time1``).
        return False
    standard = STANDARD_PREFIX_NAMESPACES.get(prefix)
    return standard is None or str(namespace) in standard