kapps_triplestore_interface.utils.utils

kapps_triplestore_interface.utils.utils.sanitize_triple(triple: Tuple[str | IRI | BNode, str | IRI, str | IRI | BNode | Any | Literal] | Tuple[str | IRI | BNode | None, str | IRI | None, str | IRI | BNode | Any | Literal | None], allow_partial: bool | None = False) → Tuple[IRI | BNode, IRI, IRI | BNode | Literal] | Tuple[IRI | BNode | None, IRI | None, IRI | BNode | Literal | None]

Validates and converts the components of a triple to their appropriate types.

• A valid triple must have three entries (subject, predicate, object) defined.

• If allow_partial is false, no entry may be None. Otherweise, at least one entry must be not None.

• Subject and predicate must be valid IRIs.

• The object can be either an IRI or a Literal

  • If the object is of type IRI, URIRef, or str, it will be converted to IRI.

  • If an object of type str should be treated as a Literal, it must be explicitly converted to Literal before passing.

  • If the object is of any other type, it will be converted to a Literal.

Parameters:

• triple (Union[TripleLike, PartialTripleLike]) – The triple to validate and convert.

• allow_partial (Optional[bool]) – Whether to allow partial triples. Defaults to False.

Returns:

The validated and converted triple.

Return type:

Union[Triple, PartialTriple]

Raises:

• InvalidInputError – If the triple does not have three or too many None entries.

• TypeError – If subject or predicate are not of type str, URIRef, or IRI.

• InvalidIRIError – If object is of type str or URIRef (except Literal) and not in a valid IRI format.

kapps_triplestore_interface.utils.utils.triple_to_string(triple: Tuple[str | IRI | BNode, str | IRI, str | IRI | BNode | Any | Literal], line_end: str | None = None) → str

Convert a triple to its string representation suitable for SPARQL queries.

Parameters:

triple (TripleLike) – The triple to convert.

Returns:

The string representation of the triple.

Return type:

str

kapps_triplestore_interface.utils.utils.validate_query(query: str)

Validate a SPARQL SELECT/ASK query string by parsing it.

Parameters:

query (str) – The SPARQL query to validate.

Returns:

True if parsing succeeds.

Return type:

bool

Raises:

InvalidQueryError – If parsing fails.

kapps_triplestore_interface.utils.utils.validate_update_query(query: str)

Validate a SPARQL UPDATE string by applying it to a temporary dataset.

Parameters:

query (str) – The SPARQL UPDATE string to validate.

Returns:

True if validation succeeds.

Return type:

bool

Raises:

InvalidQueryError – If validation fails.

kapps_triplestore_interface.utils.utils.to_literal(value: Any, datatype: str | None = None, as_string: bool | None = False) → Literal | str

Convert a Python value to an XSD literal.

Parameters:

• value (Any) – The Python value to convert.

• datatype – (Optional[str]) Optional XSD datatype to use; inferred as XSD.string for strings.

• as_string (Optional[bool]) – If True, return the N3 string form of the literal. Defaults to False.

Returns:

The rdflib.Literal or its N3 string form when as_string=True.

Return type:

Union[Literal, str]

kapps_triplestore_interface.utils.utils.from_xsd_literal(value: str, datatype: str)

Convert an XSD-typed string value to a Python value.

Parameters:

• value (str) – The lexical form of the literal.

• datatype (str) – The XSD datatype IRI.

Returns:

The converted Python value.

Return type:

Any

kapps_triplestore_interface.utils.utils.convert_multi_bindings_to_python_type(bindings: list[dict]) → list[dict]

Convert SPARQL query result bindings to their corresponding Python types.

Parameters:

bindings (list[dict]) – List of SPARQL query result bindings.

Returns:

List of converted Python values.

Return type:

list[Any]

Notes

Bindings are expected in the format:

[
    { # binding 1
        'var1': { 'type': _, 'value': _, 'datatype': _ },
        'var2': { 'type': _, 'value': _, 'datatype': _ },
    },
    { # binding 2
        'var1': { 'type': _, 'value': _, 'datatype': _ },
        'var2': { 'type': _, 'value': _, 'datatype': _ },
    }
]

and returned in the format:

[
    { # binding 1
        'var1': _,
        'var2': _,
    },
    { # binding 2
        'var1': _,
        'var2': _,
    }
]

kapps_triplestore_interface.utils.utils.convert_binding_to_python_type(result_binding: dict) → Any

Convert a SPARQL binding entry to a Python value.

Parameters:

result_binding (dict) – A single binding dict (e.g., { ‘type’: ‘literal’, … }).

Returns:

A Python value converted from the binding, or the raw string when not typed.

Return type:

Any

kapps_triplestore_interface.utils.utils.get_local_name(iri: str) → str

Extract the local name from an IRI.

Prefers the fragment after # when present; otherwise returns the last path segment after /.

Parameters:

iri (str) – The input IRI (full or shorthand acceptable).

Returns:

The local name component.

Return type:

str

kapps_triplestore_interface.utils.utils.encapsulate_named_graph(named_graph: IRI, content: str) → str

Encapsulates the given content within a named graph block if a named graph is provided.

Parameters:

• named_graph (IRI) – The IRI of the named graph. If None, the content is returned as is.

• content (str) – The SPARQL content to encapsulate.

Returns:

The encapsulated content or the original content if no named graph is provided.

Return type:

str

kapps_triplestore_interface.utils.utils.group_triples_by_bnode(triples: List[Tuple[IRI | BNode, IRI, IRI | BNode | Literal]]) → List[List[Tuple[IRI | BNode, IRI, IRI | BNode | Literal]]]

Groups triples sharing blank nodes into connected components to ensure blank node semantics are preserved within query scope.

Parameters:

triples (List[Triple]) – Triples to check.

Returns:

A list of lists of related triples

Return type:

List[List[Triple]]

Example

ASK {
    { <a> <p> <b> . }      # Independent triple
    UNION
    { <x> <q> _:b1 .
      _:b1 <r> <y> . }     # Connected via blank node
    UNION
    { <m> <n> <o> . }      # Another independent triple
}