tripper 0.3.3__tar.gz → 0.3.4__tar.gz

{tripper-0.3.3 → tripper-0.3.4}/.github/workflows/ci_tests.yml

@@ -36,12 +36,14 @@ jobs:
       #  https://pyup.io/vulnerabilities/CVE-2021-34141/44717/
       # 70612: Jinja2 vulnerability. Only used as subdependency for mkdocs++ in tripper.
       #  https://data.safetycli.com/v/70612/97c/
+      #  https://data.safetycli.com/v/72715/97c/   # update to mkdocs>=9.5.32
       safety_options: |
         --ignore=48547
         --ignore=44715
         --ignore=44716
         --ignore=44717
         --ignore=70612
+        --ignore=72715
 
       ## Build package
       run_build_package: true

{tripper-0.3.3 → tripper-0.3.4}/.pre-commit-config.yaml

@@ -19,7 +19,7 @@ ci:
 # hooks
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.6.0
+    rev: v5.0.0
     hooks:
     - id: end-of-file-fixer
       exclude: ^.*\.(svg)$
@@ -41,20 +41,20 @@ repos:
       - --skip-gitignore
 
   - repo: https://github.com/psf/black
-    rev: 24.8.0
+    rev: 24.10.0
     hooks:
     - id: black
       args: [--line-length=79]
 
   - repo: https://github.com/PyCQA/bandit
-    rev: 1.7.9
+    rev: 1.7.10
     hooks:
     - id: bandit
       args: ["-r"]
       files: ^tripper/.*$
 
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.11.1
+    rev: v1.11.2
     hooks:
     - id: mypy
       exclude: ^tests/.*$

{tripper-0.3.3 → tripper-0.3.4}/CHANGELOG.md

@@ -1,23 +1,33 @@
 # Changelog
 
-## [Unreleased](https://github.com/EMMC-ASBL/tripper/tree/HEAD)
+## [v0.3.4](https://github.com/EMMC-ASBL/tripper/tree/v0.3.4) (2024-10-15)
 
-[Full Changelog](https://github.com/EMMC-ASBL/tripper/compare/v0.3.3...HEAD)
+[Full Changelog](https://github.com/EMMC-ASBL/tripper/compare/v0.3.3...v0.3.4)
 
-**Implemented enhancements:**
-
-- Use Trusted Publishers for PyPI [\#242](https://github.com/EMMC-ASBL/tripper/issues/242)
-
-**Closed issues:**
+**Merged pull requests:**
 
-- Add instructions of how to release a new version [\#47](https://github.com/EMMC-ASBL/tripper/issues/47)
+- Allowing backends to indicate whether they prefer the sparql interface [\#255](https://github.com/EMMC-ASBL/tripper/pull/255) ([jesper-friis](https://github.com/jesper-friis))
+- \[pre-commit.ci\] pre-commit autoupdate [\#254](https://github.com/EMMC-ASBL/tripper/pull/254) ([pre-commit-ci[bot]](https://github.com/apps/pre-commit-ci))
+- Update n3 format for string with quotes. [\#253](https://github.com/EMMC-ASBL/tripper/pull/253) ([pintr](https://github.com/pintr))
+- Added option to Triplestore.value\(\) to return a generator over all matching values [\#252](https://github.com/EMMC-ASBL/tripper/pull/252) ([jesper-friis](https://github.com/jesper-friis))
+- Ignore safety vulnerabeility 72715 [\#251](https://github.com/EMMC-ASBL/tripper/pull/251) ([jesper-friis](https://github.com/jesper-friis))
+- Fix empty prefix [\#250](https://github.com/EMMC-ASBL/tripper/pull/250) ([jesper-friis](https://github.com/jesper-friis))
+- \[pre-commit.ci\] pre-commit autoupdate [\#249](https://github.com/EMMC-ASBL/tripper/pull/249) ([pre-commit-ci[bot]](https://github.com/apps/pre-commit-ci))
+- Backend info to triplestore instance [\#248](https://github.com/EMMC-ASBL/tripper/pull/248) ([jesper-friis](https://github.com/jesper-friis))
+- Added argument `ignore_unrecognised` to tripper.convert\(\) [\#247](https://github.com/EMMC-ASBL/tripper/pull/247) ([jesper-friis](https://github.com/jesper-friis))
+- \[pre-commit.ci\] pre-commit autoupdate [\#244](https://github.com/EMMC-ASBL/tripper/pull/244) ([pre-commit-ci[bot]](https://github.com/apps/pre-commit-ci))
 
 ## [v0.3.3](https://github.com/EMMC-ASBL/tripper/tree/v0.3.3) (2024-08-26)
 
 [Full Changelog](https://github.com/EMMC-ASBL/tripper/compare/v0.3.2...v0.3.3)
 
+**Implemented enhancements:**
+
+- Use Trusted Publishers for PyPI [\#242](https://github.com/EMMC-ASBL/tripper/issues/242)
+
 **Closed issues:**
 
+- Add instructions of how to release a new version [\#47](https://github.com/EMMC-ASBL/tripper/issues/47)
 - Update Python API references in README [\#22](https://github.com/EMMC-ASBL/tripper/issues/22)
 
 **Merged pull requests:**

{tripper-0.3.3 → tripper-0.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: tripper
-Version: 0.3.3
+Version: 0.3.4
 Summary: A triplestore wrapper for Python.
 Keywords: triplestore,ontology,RDF
 Author-email: SINTEF <TEAM4.0@sintef.no>
@@ -47,7 +47,7 @@ Requires-Dist: mkdocs-awesome-pages-plugin==2.9.2 ; extra == "docs"
 Requires-Dist: mkdocs-material==9.5.17 ; extra == "docs"
 Requires-Dist: mkdocstrings==0.22.0 ; extra == "docs"
 Requires-Dist: mkdocstrings-python-legacy==0.2.3 ; extra == "docs"
-Requires-Dist: pre-commit==2.21.0 ; extra == "pre-commit"
+Requires-Dist: pre-commit==4.0.1 ; extra == "pre-commit"
 Requires-Dist: pylint==2.15.5 ; extra == "pre-commit"
 Requires-Dist: pint>=0.16.1,<0.24 ; extra == "testing"
 Requires-Dist: pytest==7.4.4 ; extra == "testing"

{tripper-0.3.3 → tripper-0.3.4}/docs/developers.md

@@ -1,6 +1,12 @@
 # For developers
 
-## New release
+## Adding new backends
+
+See [interface.py], which defines the interface of a backend and may serve as a template for creating new backends.
+
+
+
+## Creating new release
 
 To create a new release, it is good to have a release summary.
 
@@ -15,3 +21,8 @@ Then, go to [create a new GitHub releases](https://github.com/EMMC-ASBL/tripper/
 Add again the tag as the release title (optionally write something else that defines this release as a title).
 
 Finally, press the "Publish release" button and ensure the release workflow succeeds (check [the release workflow](https://github.com/EMMC-ASBL/tripper/actions/workflows/cd_release.yml)).
+
+
+
+
+[interface.py]: https://github.com/EMMC-ASBL/tripper/blob/master/tripper/interface.py

{tripper-0.3.3 → tripper-0.3.4}/pyproject.toml

@@ -35,7 +35,7 @@ dependencies = [
 
 [project.optional-dependencies]
 pre-commit = [
-    "pre-commit==2.21.0",
+    "pre-commit==4.0.1",
     "pylint==2.15.5",
 ]
 testing-core = [
@@ -139,4 +139,5 @@ minversion = "7.0"
 addopts = "-rs --cov=tripper --cov-report=term --doctest-modules"
 filterwarnings = [
     "ignore:.*imp module.*:DeprecationWarning",
+    "ignore:::tripper.literal:243",  # Ignore warning in doctest
 ]

{tripper-0.3.3 → tripper-0.3.4}/tests/backends/test_collection.py

@@ -51,3 +51,5 @@ def test_collection():
     label = ts3.value(STRUCTURE.name, DM.hasLabel)
     assert isinstance(label, Literal)
     assert label == Literal("Strontium titanate", lang="en")
+
+    assert ts.prefer_sparql is False

{tripper-0.3.3 → tripper-0.3.4}/tests/backends/test_rdflib.py

@@ -36,3 +36,5 @@ def test_rdflib_backend():
     # Test for bnode
     ts.add_triples([("_:bn1", RDFS.subClassOf, EX.s)])
     assert ts.value(predicate=RDFS.subClassOf, object=EX.s) == "_:bn1"
+
+    assert ts.prefer_sparql is False

{tripper-0.3.3 → tripper-0.3.4}/tests/test_literals.py

@@ -7,6 +7,7 @@ def test_untyped() -> None:
     """Test creating a untyped literal."""
     import pytest
 
+    from tripper.errors import UnknownDatatypeWarning
     from tripper.literal import XSD, Literal
 
     literal = Literal("Hello world!")
@@ -23,7 +24,7 @@ def test_untyped() -> None:
     # Check two things here:
     #   1) that a plain literal compares false to a non-string literal
     #   2) that we get a warning about unknown XSD.ENTITY datatype
-    with pytest.warns(UserWarning, match="^unknown datatype"):
+    with pytest.warns(UnknownDatatypeWarning, match="^unknown datatype"):
         assert literal != Literal("Hello world!", datatype=XSD.ENTITY)
 
 
@@ -184,6 +185,28 @@ def test_repr() -> None:
     )
 
 
+def test_n3() -> None:
+    """Test n3()."""
+    from tripper import RDF, Literal
+
+    s = Literal(42, datatype=float).n3()
+    assert s == '"42"^^<http://www.w3.org/2001/XMLSchema#double>'
+    s = Literal("a string").n3()
+    assert s == '"a string"'
+    s = Literal('a string with "embedded" quotes').n3()
+    assert s == r'"a string with \"embedded\" quotes"'
+    s = Literal(r"a string with \"escaped\" quotes").n3()
+    assert s == r'"a string with \\\"escaped\\\" quotes"'
+    s = Literal('"json string"', datatype=RDF.JSON).n3()
+    assert s == (
+        r'"\"json string\""^^<http://www.w3.org/1999/02/22-rdf-syntax-ns#JSON>'
+    )
+    s = Literal('{"a": 1}', datatype=RDF.JSON).n3()
+    assert (
+        s == r'"{\"a\": 1}"^^<http://www.w3.org/1999/02/22-rdf-syntax-ns#JSON>'
+    )
+
+
 def test_split_iri() -> None:
     """Test parse n3-encoded literal value."""
     from tripper import DCTERMS, RDFS
@@ -205,6 +228,7 @@ def test_parse_literal() -> None:
     import pytest
 
     from tripper import RDF, XSD, Literal
+    from tripper.errors import UnknownDatatypeWarning
     from tripper.utils import parse_literal
 
     literal = parse_literal(Literal("abc").n3())
@@ -293,7 +317,7 @@ def test_parse_literal() -> None:
     assert literal.lang is None
     assert literal.datatype == RDF.JSON
 
-    with pytest.warns(UserWarning, match="unknown datatype"):
+    with pytest.warns(UnknownDatatypeWarning, match="unknown datatype"):
         literal = parse_literal('"value"^^http://example.com/vocab#mytype')
     assert literal.value == "value"
     assert literal.lang is None

{tripper-0.3.3 → tripper-0.3.4}/tests/test_triplestore.py

@@ -35,14 +35,30 @@ def test_triplestore(  # pylint: disable=too-many-locals
     pytest.importorskip("rdflib")
     pytest.importorskip("dlite")
     pytest.importorskip("SPARQLWrapper")
+    from tripper.errors import NamespaceError
     from tripper.triplestore import DCTERMS, OWL, RDF, RDFS, XSD, Triplestore
 
     ts = Triplestore(backend)
     assert ts.expand_iri("xsd:integer") == XSD.integer
     assert ts.prefix_iri(RDF.type) == "rdf:type"
+
+    with pytest.raises(NamespaceError):
+        ts.expand_iri(":MyConcept")
+
+    assert ts.prefix_iri("http://example.com#MyConcept") == (
+        "http://example.com#MyConcept"
+    )
+    with pytest.raises(NamespaceError):
+        ts.prefix_iri("http://example.com#MyConcept", require_prefixed=True)
+
     EX = ts.bind(
         "ex", "http://example.com/onto#"
     )  # pylint: disable=invalid-name
+    BASE = ts.bind("", "http://example.com#")  # pylint: disable=invalid-name
+
+    assert ts.expand_iri(":MyConcept") == BASE.MyConcept
+    assert ts.prefix_iri(BASE.MyConcept) == ":MyConcept"
+
     assert str(EX) == "http://example.com/onto#"
     ts.add_mapsTo(
         EX.MyConcept, "http://onto-ns.com/meta/0.1/MyEntity", "myprop"
@@ -93,6 +109,15 @@ def test_triplestore(  # pylint: disable=too-many-locals
     # ) == example_function.__doc__
     assert ts.value(func_iri, DCTERMS.description, lang="de") is None
 
+    # Test the `prefer_sparql` property
+    facit = {
+        "collection": False,
+        "ontopy": False,
+        "rdflib": False,
+        "sparqlwrapper": True,
+    }
+    assert ts.prefer_sparql == facit[backend]
+
 
 # if True:
 def test_restriction() -> None:  # pylint: disable=too-many-statements
@@ -392,6 +417,7 @@ def test_backend_ontopy(get_ontology_path: "Callable[[str], Path]") -> None:
 def test_backend_sparqlwrapper() -> None:
     """Specifically test the SPARQLWrapper backend Triplestore."""
     from tripper import SKOS, Triplestore
+    from tripper.errors import UnknownDatatypeWarning
 
     pytest.importorskip("SPARQLWrapper")
     ts = Triplestore(
@@ -400,7 +426,7 @@ def test_backend_sparqlwrapper() -> None:
         "csiro_international-chronostratigraphic-chart_geologic-"
         "time-scale-2020",
     )
-    with pytest.warns(UserWarning, match="unknown datatype"):
+    with pytest.warns(UnknownDatatypeWarning, match="unknown datatype"):
         for s, p, o in ts.triples(predicate=SKOS.notation):
             assert s
             assert p
@@ -496,3 +522,69 @@ def test_bind_errors():
         ts2.bind("ex")
     with pytest.raises(TypeError):
         ts2.bind("ex", Ellipsis)
+
+
+def test_value():
+    """Test Triplestore.value()."""
+    pytest.importorskip("rdflib")
+
+    from tripper import DCTERMS, RDF, RDFS, Literal, Triplestore
+    from tripper.errors import UniquenessError
+
+    ts = Triplestore(backend="rdflib")
+    EX = ts.bind("ex", "http://example.com#")
+    l1 = Literal("First comment...")
+    l2en = Literal("Second comment...", lang="en")
+    l2da = Literal("Anden kommentar...", lang="da")
+    l3en = Literal("Third comment...", lang="en")
+    ts.add_triples(
+        [
+            (EX.mydata, RDF.type, EX.Dataset),
+            (EX.mydata, DCTERMS.title, Literal("My little data")),
+            (EX.mydata, RDFS.comment, l1),
+            (EX.mydata, RDFS.comment, l2en),
+            (EX.mydata, RDFS.comment, l2da),
+            (EX.mydata, RDFS.comment, l3en),
+        ]
+    )
+
+    assert ts.value(subject=EX.mydata, predicate=RDF.type) == EX.Dataset
+    assert ts.value(predicate=RDF.type, object=EX.Dataset) == EX.mydata
+    assert ts.value(subject=EX.mydata, predicate=DCTERMS.title) == Literal(
+        "My little data"
+    )
+
+    with pytest.raises(UniquenessError):
+        ts.value(subject=EX.mydata, predicate=RDFS.comment, lang="en")
+
+    assert (
+        ts.value(subject=EX.mydata, predicate=RDFS.comment, lang="da") == l2da
+    )
+
+    assert ts.value(
+        subject=EX.mydata,
+        predicate=RDFS.comment,
+        lang="en",
+        any=True,
+    ) in (l2en, l3en)
+
+    assert set(
+        ts.value(
+            subject=EX.mydata,
+            predicate=RDFS.comment,
+            lang="en",
+            any=None,
+        )
+    ) == {l2en, l3en}
+
+    assert (
+        ts.value(subject=EX.mydata, predicate=RDFS.comment, lang="no") is None
+    )
+
+    t = ts.value(
+        subject=EX.mydata,
+        predicate=RDFS.comment,
+        lang="no",
+        default="a",
+    )
+    assert t == "a"

{tripper-0.3.3 → tripper-0.3.4}/tripper/__init__.py

@@ -27,7 +27,7 @@ from .namespace import (
 from .triplestore import Triplestore, backend_packages
 from .tripper import Tripper
 
-__version__ = "0.3.3"
+__version__ = "0.3.4"
 
 __all__ = (
     "Literal",

{tripper-0.3.3 → tripper-0.3.4}/tripper/backends/collection.py

@@ -33,6 +33,8 @@ class CollectionStrategy:
             triplestore from.
     """
 
+    prefer_sparql = False
+
     def __init__(
         self,
         base_iri: "Optional[str]" = None,

{tripper-0.3.3 → tripper-0.3.4}/tripper/backends/ontopy.py

@@ -43,6 +43,8 @@ class OntopyStrategy:
     Either the `base_iri` or `onto` argument must be provided.
     """
 
+    prefer_sparql = False
+
     def __init__(
         self,
         base_iri: "Optional[str]" = None,

{tripper-0.3.3 → tripper-0.3.4}/tripper/backends/rdflib.py

@@ -69,6 +69,8 @@ class RdflibStrategy:
             creating a new empty Graph object.
     """
 
+    prefer_sparql = False
+
     def __init__(
         self,
         base_iri: "Optional[str]" = None,  # pylint: disable=unused-argument

{tripper-0.3.3 → tripper-0.3.4}/tripper/backends/sparqlwrapper.py

@@ -31,6 +31,8 @@ class SparqlwrapperStrategy:
 
     """
 
+    prefer_sparql = True
+
     def __init__(self, base_iri: str, **kwargs) -> None:
         kwargs.pop(
             "database", None

{tripper-0.3.3 → tripper-0.3.4}/tripper/convert/convert.py

@@ -1,4 +1,28 @@
-"""Tripper module for converting between RDF and other repetations."""
+# pylint: disable=line-too-long
+"""Tripper module for converting between RDF and other repetations.
+
+Example use:
+
+>>> from tripper import DCTERMS, Literal, Triplestore
+>>> from tripper.convert import load_container, save_container
+
+>>> ts = Triplestore("rdflib")
+>>> dataset = {"a": 1, "b": 2}
+>>> save_container(ts, dataset, ":data_indv")
+>>> load_container(ts, ":data_indv")
+{'a': 1, 'b': 2}
+
+# Add additional context to our data individual
+>>> ts.add((":data_indv", DCTERMS.title, Literal("My wonderful data")))
+
+>>> load_container(ts, ":data_indv")  # doctest: +IGNORE_EXCEPTION_DETAIL
+Traceback (most recent call last):
+ValueError: Unrecognised predicate 'http://purl.org/dc/terms/title' in dict: :data_indv
+
+>>> load_container(ts, ":data_indv", ignore_unrecognised=True)
+{'a': 1, 'b': 2}
+
+"""
 
 # pylint: disable=invalid-name,redefined-builtin
 import warnings
@@ -88,11 +112,11 @@ def from_container(
         if isinstance(obj, Mapping):
             if not obj:
                 return OTEIO.Dictionary
-            obj_iri = f"_:{dict}_{uuid}"
+            obj_iri = f"_:dict_{uuid}"
         elif isinstance(obj, Sequence) and not isinstance(obj, str):
             if not obj:
                 return RDF.List
-            obj_iri = f"_:{list}_{uuid}"
+            obj_iri = f"_:list_{uuid}"
         elif obj is None:
             return OWL.Nothing
         else:
@@ -208,6 +232,7 @@ def load_container(
     ts: "Triplestore",
     iri: str,
     recognised_keys: "Optional[Union[Dict, str]]" = None,
+    ignore_unrecognised: bool = False,
 ) -> "Union[dict, list]":
     """Deserialise a Python container object from a triplestore.
 
@@ -218,6 +243,9 @@ def load_container(
             correspond to IRIs of recognised RDF properties.
             If set to the special string "basic", the
             `BASIC_RECOGNISED_KEYS` module will be used.
+        ignore_unrecognised: Ignore relations that has `iri` as subject and
+            a predicate that is not among the values of `recognised_keys`
+            or `rdf:type`.  The default is to raise an exception.
 
     Returns:
         A Python container object corresponding to `iri`.
@@ -258,7 +286,10 @@ def load_container(
                 container[str(key)] = get_obj(value)
             elif pred in recognised_iris:
                 container[recognised_iris[pred]] = get_obj(obj)
-            elif pred not in (RDF.type,):
+            elif not ignore_unrecognised and pred not in (
+                RDF.type,
+                RDFS.subClassOf,
+            ):
                 raise ValueError(
                     f"Unrecognised predicate '{pred}' in dict: {iri}"
                 )

tripper-0.3.4/tripper/errors.py

@@ -0,0 +1,43 @@
+"""Exceptions and warnings for the triplestore package."""
+
+
+# === Exceptions ===
+class TripperError(Exception):
+    """Base exception for tripper errors."""
+
+
+class UniquenessError(TripperError):
+    """More than one matching triple."""
+
+
+class NamespaceError(TripperError):
+    """Namespace error."""
+
+
+class NoSuchIRIError(NamespaceError):
+    """Namespace has no such IRI."""
+
+
+class CannotGetFunctionError(TripperError):
+    """Not able to get function documented in the triplestore."""
+
+
+class ArgumentTypeError(TripperError, TypeError):
+    """Invalid argument type."""
+
+
+class ArgumentValueError(TripperError, ValueError):
+    """Invalid argument value (of correct type)."""
+
+
+# === Warnings ===
+class TripperWarning(Warning):
+    """Base class for tripper warnings."""
+
+
+class UnusedArgumentWarning(TripperWarning):
+    """Argument is unused."""
+
+
+class UnknownDatatypeWarning(TripperWarning):
+    """Unknown datatype."""

{tripper-0.3.3 → tripper-0.3.4}/tripper/interface.py

@@ -24,6 +24,10 @@ class ITriplestore(Protocol):
 
     ```python
 
+    # Whether the backend perfers SPQRQL queries instead of using the
+    # triples() method.
+    prefer_sparql = True
+
     def parse(
             self,
             source: Union[str, Path, IO] = None,

{tripper-0.3.3 → tripper-0.3.4}/tripper/literal.py

@@ -12,6 +12,7 @@ import warnings
 from datetime import datetime
 from typing import TYPE_CHECKING
 
+from tripper.errors import UnknownDatatypeWarning
 from tripper.namespace import RDF, RDFS, XSD
 
 if TYPE_CHECKING:  # pragma: no cover
@@ -240,7 +241,8 @@ class Literal(str):
             string.datatype in types for types in cls.datatypes.values()
         ):
             warnings.warn(
-                f"unknown datatype: {string.datatype} - assuming xsd:string"
+                f"unknown datatype: {string.datatype} - assuming xsd:string",
+                category=UnknownDatatypeWarning,
             )
 
         return string
@@ -305,8 +307,11 @@ class Literal(str):
 
     def n3(self) -> str:  # pylint: disable=invalid-name
         """Returns a representation in n3 format."""
+
+        form = self.replace("\\", r"\\").replace('"', r"\"")
+
         if self.lang:
-            return f'"{self}"@{self.lang}'
+            return f'"{form}"@{self.lang}'
         if self.datatype:
-            return f'"{self}"^^<{self.datatype}>'
-        return f'"{self}"'
+            return f'"{form}"^^<{self.datatype}>'
+        return f'"{form}"'

{tripper-0.3.3 → tripper-0.3.4}/tripper/triplestore.py

@@ -29,7 +29,7 @@ from tripper.errors import (
     ArgumentValueError,
     CannotGetFunctionError,
     NamespaceError,
-    TriplestoreError,
+    TripperError,
     UniquenessError,
 )
 from tripper.literal import Literal
@@ -99,12 +99,14 @@ hasCost = DM.hasCost
 
 
 # Regular expression matching a prefixed IRI
-_MATCH_PREFIXED_IRI = re.compile(r"^([a-z][a-z0-9]*):([^/]{1}.*)$")
+_MATCH_PREFIXED_IRI = re.compile(r"^([a-z][a-z0-9]*)?:([^/]{1}.*)$")
 
 
 class Triplestore:
     """Provides a common frontend to a range of triplestore backends."""
 
+    # pylint: disable=too-many-instance-attributes
+
     default_namespaces = {
         "xml": XML,
         "rdf": RDF,
@@ -165,6 +167,9 @@ class Triplestore:
         self.namespaces: "Dict[str, Namespace]" = {}
         self.closed = False
         self.backend_name = backend_name
+        self.database = database
+        self.package = package
+        self.kwargs = kwargs.copy()
         self.backend = cls(base_iri=base_iri, database=database, **kwargs)
 
         # Cache functions in the triplestore for fast access
@@ -534,6 +539,23 @@ class Triplestore:
     # interfaces to the triples(), add_triples() and remove() methods
     # implemented by all backends.
 
+    prefer_sparql = property(
+        fget=lambda self: getattr(self.backend, "prefer_sparql", None),
+        doc=(
+            "Whether the backend prefer SPARQL over the triples() interface. "
+            "Is None if not specified by the backend."
+            "\n\n"
+            "Even though Tripper requires that the Triplestore.triples() is "
+            "implemented, Triplestore.query() must be used for some "
+            "backends in specific cases (like fuseki when working on RDF "
+            "lists) because of how blank nodes are treated. "
+            "\n\n"
+            "The purpose of this property is to let tripper "
+            "automatically select the most appropriate interface depending "
+            "on the current backend settings."
+        ),
+    )
+
     @classmethod
     def _get_backend(cls, backend: str, package: "Optional[str]" = None):
         """Returns the class implementing the given backend."""
@@ -580,8 +602,11 @@ class Triplestore:
             predicate: Possible criteria to match.
             object: Possible criteria to match.
             default: Value to return if no matches are found.
-            any: If true, return any matching value, otherwise raise
-                UniquenessError.
+            any: Used to define how many values to return. Can be set to:
+                `False` (default): return the value or raise UniquenessError
+                if there is more than one matching value.
+                `True`: return any matching value if there is more than one.
+                `None`: return a generator over all matching values.
             lang: If provided, require that the value must be a localised
                 literal with the given language code.
 
@@ -600,33 +625,30 @@ class Triplestore:
         (idx,) = [i for i, v in enumerate(spo) if v is None]
 
         triples = self.triples(subject, predicate, object)
+
         if lang:
-            first = None
-            if idx != 2:
-                raise ValueError("`object` must be None if `lang` is given")
-            for triple in triples:
-                value = triple[idx]
-                if isinstance(value, Literal) and value.lang == lang:
-                    if any:
-                        return value
-                    if first:
-                        raise UniquenessError("More than one match")
-                    first = value
-            if first is None:
-                return default
-        else:
-            try:
-                triple = next(triples)
-            except StopIteration:
-                return default
+            triples = (
+                t
+                for t in triples
+                if isinstance(t[idx], Literal)
+                and t[idx].lang == lang  # type: ignore
+            )
+
+        if any is None:
+            return (t[idx] for t in triples)  # type: ignore
+
+        try:
+            value = next(triples)[idx]
+        except StopIteration:
+            return default
 
         try:
             next(triples)
         except StopIteration:
-            return triple[idx]
+            return value
 
-        if any:
-            return triple[idx]
+        if any is True:
+            return value
         raise UniquenessError("More than one match")
 
     def subjects(
@@ -696,22 +718,63 @@ class Triplestore:
     # ------------------------------------------
     def expand_iri(self, iri: str):
         """Return the full IRI if `iri` is prefixed.  Otherwise `iri` is
-        returned."""
+        returned.
+
+        Examples:
+        >>> from tripper import Triplestore
+        >>> ts = Triplestore(backend="rdflib")
+
+        # Unknown prefix raises an exception
+        >>> ts.expand_iri("ex:Concept")  # doctest: +ELLIPSIS
+        Traceback (most recent call last):
+        ...
+        tripper.errors.NamespaceError: unknown namespace: 'ex'
+
+        >>> EX = ts.bind("ex", "http://example.com#")
+        >>> ts.expand_iri("ex:Concept")
+        'http://example.com#Concept'
+
+        # Returns `iri` if it has no prefix
+        >>> ts.expand_iri("http://example.com#Concept")
+        'http://example.com#Concept'
+
+        """
         match = re.match(_MATCH_PREFIXED_IRI, iri)
         if match:
             prefix, name = match.groups()
+            if prefix is None:
+                prefix = ""
             if prefix not in self.namespaces:
-                raise NamespaceError(f"unknown namespace: {prefix}")
+                raise NamespaceError(f"unknown namespace: '{prefix}'")
             return f"{self.namespaces[prefix]}{name}"
         return iri
 
     def prefix_iri(self, iri: str, require_prefixed: bool = False):
+        # pylint: disable=line-too-long
         """Return prefixed IRI.
 
         This is the reverse of expand_iri().
 
         If `require_prefixed` is true, a NamespaceError exception is raised
         if no prefix can be found.
+
+        Examples:
+        >>> from tripper import Triplestore
+        >>> ts = Triplestore(backend="rdflib")
+        >>> ts.prefix_iri("http://example.com#Concept")
+        'http://example.com#Concept'
+
+        >>> ts.prefix_iri(
+        ...     "http://example.com#Concept", require_prefixed=True
+        ... )  # doctest: +ELLIPSIS
+        Traceback (most recent call last):
+        ...
+        tripper.errors.NamespaceError: No prefix defined for IRI: http://example.com#Concept
+
+        >>> EX = ts.bind("ex", "http://example.com#")
+        >>> ts.prefix_iri("http://example.com#Concept")
+        'ex:Concept'
+
         """
         if not re.match(_MATCH_PREFIXED_IRI, iri):
             for prefix, namespace in self.namespaces.items():
@@ -967,7 +1030,7 @@ class Triplestore:
         self.bind("map", MAP)
 
         if not property_name and not isinstance(source, str):
-            raise TriplestoreError(
+            raise TripperError(
                 "`property_name` is required when `target` is not a string."
             )
 

{tripper-0.3.3 → tripper-0.3.4}/tripper/tripper.py

@@ -7,7 +7,7 @@ from __future__ import annotations  # Support Python 3.7 (PEP 585)
 import uuid
 from typing import TYPE_CHECKING
 
-from tripper.errors import TriplestoreError
+from tripper.errors import TripperError
 from tripper.literal import Literal
 from tripper.namespace import MAP, RDF
 from tripper.triplestore import (
@@ -186,7 +186,7 @@ class Tripper(Triplestore):
                     )
                 return retval
 
-            raise TriplestoreError(
+            raise TripperError(
                 f"data source {iri} has neither a 'hasDataValue' or a "
                 f"'hasAccessFunction' property"
             )

tripper-0.3.3/tripper/errors.py

@@ -1,35 +0,0 @@
-"""Exceptions and warnings for the triplestore package."""
-
-
-# === Exceptions ===
-class TriplestoreError(Exception):
-    """Base exception for triplestore errors."""
-
-
-class UniquenessError(TriplestoreError):
-    """More than one matching triple."""
-
-
-class NamespaceError(TriplestoreError):
-    """Namespace error."""
-
-
-class NoSuchIRIError(NamespaceError):
-    """Namespace has no such IRI."""
-
-
-class CannotGetFunctionError(TriplestoreError):
-    """Not able to get function documented in the triplestore."""
-
-
-class ArgumentTypeError(TriplestoreError, TypeError):
-    """Invalid argument type."""
-
-
-class ArgumentValueError(TriplestoreError, ValueError):
-    """Invalid argument value (of correct type)."""
-
-
-# === Warnings ===
-class UnusedArgumentWarning(Warning):
-    """Argument is unused."""