Skip to content

ontocast.onto.iri_policy

Attributes

PN_PREFIX = '[A-Za-z](?:[\\w.-]*[\\w-])?' module-attribute

URIContext = Literal['ontology', 'facts', 'auto'] module-attribute

Functions:

as_sparql_iriref(value)

Render an IRI for a SPARQL IRIREF slot, or None if it cannot be one.

Callers should log-and-skip on None rather than raising: a single malformed IRI must not fail a whole query.

Parameters:

Name Type Description Default
value str

IRI text, optionally wrapped in Turtle-style angle brackets.

required

Returns:

Type Description
str | None

str | None: <iri> ready for interpolation, or None when value

str | None

is empty or contains a codepoint IRIREF forbids.

Source code in ontocast/onto/iri_policy.py
def as_sparql_iriref(value: str) -> str | None:
    """Render an IRI for a SPARQL ``IRIREF`` slot, or ``None`` if it cannot be one.

    Callers should log-and-skip on ``None`` rather than raising: a single
    malformed IRI must not fail a whole query.

    Args:
        value: IRI text, optionally wrapped in Turtle-style angle brackets.

    Returns:
        str | None: ``<iri>`` ready for interpolation, or ``None`` when ``value``
        is empty or contains a codepoint ``IRIREF`` forbids.
    """
    text = strip_iri_brackets(value).strip()
    return f"<{text}>" if is_iriref_text(text) else None

canonicalize_namespace_iri(namespace)

Map a delimiter-normalized namespace IRI to its canonical alias.

Source code in ontocast/onto/iri_policy.py
def canonicalize_namespace_iri(namespace: str) -> str:
    """Map a delimiter-normalized namespace IRI to its canonical alias."""
    return _NAMESPACE_ALIASES.get(namespace, namespace)

is_in_namespace(uri, namespace, *, context='auto')

Source code in ontocast/onto/iri_policy.py
def is_in_namespace(uri: str, namespace: str, *, context: URIContext = "auto") -> bool:
    normalized_namespace = normalize_namespace_iri(namespace, context=context)
    return uri.startswith(normalized_namespace)

is_iriref_text(text)

Whether text, exactly as given, can sit inside a SPARQL <...>.

Source code in ontocast/onto/iri_policy.py
def is_iriref_text(text: str) -> bool:
    """Whether ``text``, exactly as given, can sit inside a SPARQL ``<...>``."""
    return bool(text) and not any(
        char in _IRIREF_FORBIDDEN or ord(char) <= 0x20 for char in text
    )

is_opaque_local_name(local)

Return True when a local IRI name carries no human-readable semantics.

Heuristic: opaque if the local name is a Q/P-number (Wikidata style), a pure numeric string, or a hex/hash string of length >= 8.

Source code in ontocast/onto/iri_policy.py
def is_opaque_local_name(local: str) -> bool:
    """Return True when a local IRI name carries no human-readable semantics.

    Heuristic: opaque if the local name is a Q/P-number (Wikidata style),
    a pure numeric string, or a hex/hash string of length >= 8.
    """
    if not local:
        return False
    if local[0] in ("Q", "P") and local[1:].isdigit():
        return True
    if local.isdigit():
        return True
    hex_chars = set("0123456789abcdefABCDEF")
    if len(local) >= 8 and all(c in hex_chars for c in local):
        return True
    return False

join_namespace_local(namespace, local, *, context='auto')

Source code in ontocast/onto/iri_policy.py
def join_namespace_local(
    namespace: str,
    local: str,
    *,
    context: URIContext = "auto",
) -> str:
    return f"{normalize_namespace_iri(namespace, context=context)}{local}"

normalize_namespace_iri(namespace, *, context='auto')

Return a namespace IRI with a deterministic terminal delimiter.

Existing trailing # or / are preserved. When absent, we append # for ontology contexts and / for facts/default contexts. Known namespace aliases (e.g. http://schema.org/) are mapped to their canonical form.

Source code in ontocast/onto/iri_policy.py
def normalize_namespace_iri(namespace: str, *, context: URIContext = "auto") -> str:
    """Return a namespace IRI with a deterministic terminal delimiter.

    Existing trailing ``#`` or ``/`` are preserved. When absent, we append ``#``
    for ontology contexts and ``/`` for facts/default contexts. Known namespace
    aliases (e.g. ``http://schema.org/``) are mapped to their canonical form.
    """
    text = strip_iri_brackets(namespace)
    if text.endswith("#") or text.endswith("/"):
        return canonicalize_namespace_iri(text)
    resolved_context = _resolve_context(text, context)
    suffix = "#" if resolved_context == "ontology" else "/"
    return canonicalize_namespace_iri(f"{text}{suffix}")

sanitize_prefix_map(prefix_map, *, context='auto')

Source code in ontocast/onto/iri_policy.py
def sanitize_prefix_map(
    prefix_map: dict[str, str],
    *,
    context: URIContext = "auto",
) -> dict[str, str]:
    return {
        prefix: normalize_namespace_iri(namespace, context=context)
        for prefix, namespace in prefix_map.items()
    }

split_namespace_local(value)

Source code in ontocast/onto/iri_policy.py
def split_namespace_local(value: str) -> tuple[str | None, str]:
    text = value.strip()
    if not text:
        return None, ""
    if "#" in text:
        namespace, local = text.rsplit("#", 1)
        return f"{namespace}#", local
    trimmed = text.rstrip("/")
    if "/" in trimmed:
        namespace, local = trimmed.rsplit("/", 1)
        return f"{namespace}/", local
    return None, text

strip_iri_brackets(value)

Strip optional Turtle-style <...> wrappers from an IRI string.

Source code in ontocast/onto/iri_policy.py
def strip_iri_brackets(value: str) -> str:
    """Strip optional Turtle-style ``<...>`` wrappers from an IRI string."""
    text = value.strip()
    if text.startswith("<") and text.endswith(">") and len(text) > 2:
        return text[1:-1].strip()
    return text